add-feature — feature lifecycle for azure-functions-agents-runtime

This skill operationalizes the lifecycle in AGENTS.md §1 for medium+ features. Run the phases in order; each has an exit gate — do not advance until it is met. Record consequential feature-behavior choices in the FRD Decisions log, not delivery or PR-management decisions.

When to use

Use for medium+ features: new public surface (frontmatter keys, config, endpoints), cross-module changes, or new discovery/registration/authoring behavior. Skip (use the lightweight lane) for nits, typos, and self-contained one-module bug fixes.

Prerequisites

• Read AGENTS.md (process) and docs/architecture.md §2–§3 (design + module map).
• Know the canonical gate commands (AGENTS.md §3).

Phase 0 — Triage + worktree (gate: scope + lane agreed)

1. Confirm the change is genuinely medium+. If not, drop to the lightweight lane.
2. Agree a short slug and create a worktree off main:

   git worktree add \
     ../copilot-worktrees/azure-functions-agents-runtime/<user>-<slug> \
     -b <user>/<slug> main

Phase 1 — FRD (gate: FRD drafted)

1. Determine the next FRD number: highest docs/frds/NNNN-*.md + 1, zero-padded.
2. Copy docs/frds/_template.md → docs/frds/<NNNN>-<slug>.md.
3. Fill every section. Map the Proposed design onto the pipeline stages (discover → translate → register → execute) and describe the intended behavior, compatibility boundaries, and acceptance criteria. Do not describe the PR sequence, slice scope, ownership, schedule, or rollout plan in the FRD.
4. Seed the Decisions log with feature-contract choices and who made them (Human vs Agent). Do not record implementation or delivery planning there.
5. If the implementation is too large or risky for one reviewable PR, read references/split-rules.md. Discuss the PR sequence and dependencies in PR descriptions or a separate delivery plan, never in the FRD.
6. Keep the FRD focused on intended behavior, contracts, and durable decisions. Do not encode delivery mechanics such as PR numbers, commit SHAs, temporary slice/phasing labels, or package versions already owned by pyproject.toml.
7. Write in crisp, plain English. Use short sentences, define terms on first use, assume little background context, and state conclusions as facts. Do not narrate investigation history in the FRD; put evidence in PR descriptions.
8. Never cite Decisions-log numbers in FRD prose or cross-references; describe the decision instead, because numbers shift on merges/renumbering.

Phase 2 — Architecture review (planning mode) (gate: human sign-off → status: Finalized)

1. Run a dedicated review pass — prefer a review sub-agent (e.g. rubber-duck) so the author's context does not bias it. Ask it to judge the FRD for:
   • completeness (all sections answered, edge cases, compatibility);
   • alignment with the docs/architecture.md module map and pipeline boundaries (discovery read-only; registration is the only Azure-aware stage; lazy runner);
   • whether the public surface stays consistent with docs/front-matter-spec.md.
2. Iterate on the FRD until findings are resolved. Append decisions to the log.
3. Get explicit human sign-off, record it in §8, and set status: Finalized. Do not implement before the FRD is Finalized.

Phase 3 — Implementation (gate: ruff + mypy clean)

For multi-PR delivery, repeat phases 3–5 for every approved slice. Give each slice its own branch and worktree as described in AGENTS.md.

1. Implement product changes only, per the finalized FRD. Keep diffs surgical; no unrelated refactors.
2. For multi-PR delivery, implement only the agreed delivery slice and keep its dependency and review scope explicit in the PR, not the FRD.
3. Follow AGENTS.md §5 conventions (PEP 695 type aliases, strict typing, Pydantic v2 base-class fields, MAF default with only AGENTS.md's bounded app-level Copilot preview exception, shared _logger).
4. Run and pass:

   python -m ruff check src tests
   python -m mypy src

Phase 4 — Testing (gate: full gate green)

1. Design coverage for the current slice's behavior — prefer a separate testing review pass (sub-agent or fresh checklist) so gaps are caught independently.
2. Add tests under tests/, mirroring source modules. For config/authoring changes, add a scenario folder under tests/fixtures/config_scenarios/.
3. For bug-adjacent work, add a failing regression test first.
4. Run the full CI-equivalent gate:

   python -m pytest --cache-clear --cov=./src/azure_functions_agents --cov-report=xml --cov-branch tests

Phase 5 — Docs (gate: DoD met)

1. Update documentation made inaccurate by the current slice. docs/architecture.md (module map / pipeline) is the design source of truth and must stay accurate.
2. If schema.py changed:
   • Run python eng/scripts/generate_config_reference.py to regenerate the reference
   • Use the update-schema-docs skill to add examples to docs/front-matter-spec.md and review docs/architecture.md for consistency
   • Review the skill's PR checklist and address architectural concerns
3. Update relevant docs under docs/ (commonly front-matter-spec.md, triggers.md, or other files as needed) if the authoring surface changed (for non-schema changes, or to refine schema-generated examples).
4. Update README.md if user-facing behavior changed.
5. Update the FRD index in docs/frds/README.md.
6. Verify the AGENTS.md §8 Definition of Done, then open the PR.
7. After each PR merges, remove its worktree (git worktree remove <path>). Set the FRD status: Implemented only after the final planned PR merges.

Guardrails

• Never skip a gate. If a gate fails, fix before advancing.
• Keep the Decisions log focused on the feature contract; it is not a delivery diary.
• Never cite Decisions-log numbers in FRD prose or cross-references; describe the decision instead, because numbers shift on merges/renumbering.
• Keep implementation diffs surgical and scoped to the FRD.
• This skill is repo dev-tooling under .github/skills/; it is unrelated to the runtime's user-authored agent skills discovered from an app's skills/ folder.