Feature

/feature — AI-Assisted Development Lifecycle

Activate this skill for non-trivial features or changes to run the full structured development workflow: plan → critique → implement → test → code-review → QA → PR.

Workflow

Step 1 — Draft, critique, and approve the plan

Preconditions — check the branch first. The workflow assumes the human started this session on a fresh feature branch: the code review (Step 4) diffs against the default branch (named in AGENTS.md → Commands) and Step 9 opens a PR targeting it, neither of which works from the default branch itself. If the session is on the default branch, STOP and ask the user to create a feature branch — you may not create or switch branches yourself (Rule 3 in AGENTS.md).

Enter plan mode now, before drafting. Plan mode is a structural commitment: while in plan mode the harness blocks edit tools, so the workflow cannot skip the approval gate even if the agent is tempted to inline the plan and proceed. Stay in plan mode through steps 1a, 1b, and 1c. Exit plan mode only in step 1c, after the user approves.

Step 1a — Draft the plan

Invoke the planner sub-agent to draft an implementation plan. Pass the user's prompt verbatim — including any reference to docs or links. The planner will fetch all external specs with its own tools (it has WebFetch for URLs) and return the plan as markdown text.

Do not use tools directly — always delegate to the planner sub-agent, regardless of which platform you are running on.

Step 1b — Critique the plan

Invoke the plan-critic sub-agent with the draft plan as input. The critic will apply pre-mortem, inversion, load-bearing assumption analysis, and consistency checks against ADRs and product docs, and return the critique as markdown text.

Skip this step ONLY if the change qualifies as trivial under ALL of:

• diff is plausibly under ~50 lines of non-test code,
• touches none of the project's sensitive areas (the Sensitive Areas section in AGENTS.md is the canonical list),
• introduces no new public endpoints, no new persisted fields, no new external dependencies,
• AND the user explicitly said "skip the critic" (or equivalent) in this session.

If any condition fails, run the critic. When in doubt, run it. Do not infer "trivial" from your own read of the plan — the user has to ask.

Step 1c — Present plan and critique for approval

Present BOTH the plan and the critique to the user for approval, using whatever mechanism the harness provides for exiting plan mode.

Lead with the approval screen: the plan's Approval Summary first, immediately followed by the critique's Confidence verdict and its top findings (any suggested amendments the user is likely to want). This is what the user reads on a phone. The full plan and the full critique follow below, clearly separated — make clear which sections are the plan and which are the critique; do not interleave them. The user reads the approval screen (and drills into the detail only where needed) and decides whether to approve as-is, amend the plan based on critique findings, or request a re-plan.

Do not proceed until the plan is approved. On a substantive change (new scope, a different approach, or reworked requirements), re-enter plan mode and re-invoke the planner sub-agent to revise the plan — do not re-plan yourself — then re-run the plan-critic and re-present for approval. When re-presenting a revised plan, lead with a short delta section — what changed relative to the previously presented version — so the user re-reads only the changes, not the whole plan again.

If the user approves the plan conditional on adopting specific critique amendments ("approved, but also address point 2"), you may fold those specific amendments into the plan text yourself before implementing — that is transcribing an accepted decision, not fresh planning, so it does not need another planner round. The code-critic and adversarial-qa sub-agents receive only the plan text — an amendment that lives only in the conversation is invisible to them.

After approval, retain the plan text — you will pass it to the code-critic and adversarial-qa sub-agents later.

Step 2 — Implement

Acceptance tests first. Before implementing, write the end-to-end tests from the plan's Test Strategy — at minimum the [AC-<slug>-n]-tagged ones. They encode the approved contract, so drift from the plan surfaces as a failing test during implementation instead of a surprise at review. Tests derived from the plan may not be weakened, loosened, or rewritten to make them pass — if one turns out to be wrong, treat it as a plan deviation (below): flag it, don't silently adjust it.

Then implement the approved plan in small logical steps until the suite is green. Run the test suite once a coherent unit of work is complete (e.g., after finishing a module or a meaningful set of related changes) — not after every individual step.

Look up current library/API docs instead of relying on training-time memory for version-sensitive details. Before writing code against an external library or framework — especially anything that could have changed since training (recent APIs, config shape, breaking changes) — use the bundled context7 MCP server — resolve the library ID, then query its docs — to pull current docs rather than guessing. Skip it for stdlib/language-core usage you're already confident about. This is a quality aid, not a gate like the canonical commands in Rule 1 — if the lookup errors or the library isn't found, note it in your summary and proceed on your best existing knowledge rather than stopping the implementation step over it.

If you discover something during implementation that changes what needs to be built, stop and assess the impact:

• Minor (an implied edge case, a small clarification): note the deviation and inform the user with a brief note before continuing.
• Material (scope change, different approach, new requirements): stop, re-enter plan mode, update the plan, and present it for re-approval before continuing.

Step 3 — Run all tests

All tests must pass before proceeding. Run the project's run-all-tests command (AGENTS.md → Commands).

Step 4 — Code review

Commit your work first — the review must cover the committed state, because scripts/review-ok.sh (Step 6) records the reviewed commit SHA and the pre-push hook compares against it.

Invoke the code-critic sub-agent to review all changes against project standards. Pass the approved plan text, and include the summary output of the most recent full test-suite run (Step 3). The reviewer is not allowed to run the test suite itself — it verifies coverage statically and needs a record that the committed tests ran and passed on the reviewed state. That summary comes from you, the implementer, so it is a record, not independent proof (see Deterministic enforcement in the AI Workflow plugin's own documentation) — this workflow's job ends at a well-vetted PR; whether your project's own CI provides independent evidence on top of that is outside this workflow's scope.

Escalate the model on the security surface. The code-critic runs on Sonnet by default (see its wrapper). If the diff touches the security surface — the Sensitive Areas section in AGENTS.md is the canonical list — invoke the code-critic with its model overridden to opus for that review: Opus is the stronger bug-finder, and this surface is where a missed finding is most expensive. Sonnet stays the default everywhere else. (This is the model-tier counterpart to the second-reviewer-pass recommendation in Step 9.)

Step 5 — Relay NEEDS_DECISION items

If the reviewer flags any NEEDS_DECISION items, stop and present ALL of them to the user. Wait for answers before proceeding.

Step 6 — Fix FAIL items

If the reviewer found critical issues (FAIL), fix them and re-invoke the code-critic. Repeat until no critical issues remain.

Do not push or open a PR until the code-critic has passed with no FAIL items (see Rules — non-negotiable in AGENTS.md). Re-run the reviewer after any later change, including fixes prompted by Step 8 QA findings.

Record the pass. After a pass with no FAIL items on the committed state (see Step 4 — the review always covers a commit), run scripts/review-ok.sh — it records the reviewed HEAD, and the pre-push hook (githooks/pre-push) blocks pushing any other commit. Any commit made after the review makes the marker stale by design: re-run the reviewer, then scripts/review-ok.sh again on the new HEAD. Never run it without a passing review of the current HEAD.

Step 7 — Exploratory QA

Run this step only when the change has a UI and/or API surface: the diff touches templates/views, static assets, a controller path that renders a view, fragment, or client-driven (e.g. HTMX/AJAX) response, or exposes/changes a REST (or other network-callable) endpoint. For changes with neither surface (pure internal service/repository logic, migrations, build/config work), skip this step and state in your summary that QA was skipped and why. When in doubt, run it.

Invoke the adversarial-qa sub-agent for an adversarial probe of the feature through whichever surface(s) it exposes. Its role is to catch things the plan and the committed tests did not anticipate — NOT to re-verify the plan's Requirements (those are locked down by the committed end-to-end tests written during implementation). Pass the approved plan text so the agent understands the feature, not as a checklist.

Step 8 — Relay QA findings

If the QA agent surfaces any findings, present them to the user before opening a PR and wait for direction on each (fix now, defer, or ignore).

For each finding the user chooses to defer, file a GitHub issue labeled known-issue (gh issue create --label known-issue …) describing the behaviour, where it lives, the QA pass that found it, and sign it with model attribution. QA evidence under .qa-evidence/ is session-local (gitignored), so the issue body must stand alone: include reproduction steps and describe in words what the evidence showed. The QA skill checks that label on every pass, so deferred findings are reported as known instead of being re-triaged each time. Do not file issues for findings the user chooses to ignore outright.

Step 9 — Open PR

Only open a PR after the code review has passed and every QA finding has been dispositioned (fixed / deferred / ignored) — or QA was skipped because there is no UI or API surface.

The PR body is where the human review starts — it must carry the pipeline's conclusions so the reviewer does not have to reconstruct them from the diff or a session transcript:

• Plan summary — the requirements and approach in a few sentences, plus a link to the source spec if there was one.
• Acceptance criteria → test table — one row per AC-<slug>-n from the plan's Approval Summary: the criterion, and the committed test(s) tagged [AC-<slug>-n] that prove it. This is the reviewer's traceability skim — a criterion without a test row must not reach the PR (the code-critic enforces this earlier).
• Review outcome — the final code-review verdict, every NEEDS_DECISION that was raised, and the decision the user made on each.
• QA outcome — findings with their dispositions (fixed / deferred with issue number / ignored), or "skipped: no UI or API surface". Describe each finding in words — .qa-evidence/ is gitignored and session-local, so its paths are dead links to anyone reading the PR; the durable record for a deferred finding is its known-issue issue.
• Test evidence — one line: the test count and result from the final full test-suite run.

If the branch touches the security surface (the Sensitive Areas list in AGENTS.md), say so explicitly in the PR body, and give that surface a second, independent look before merging by re-running the code-critic sub-agent in a fresh context. A single reviewer pass is the last line of defense there; the project's own review is the no-cost way to get a second.

Important Rules

• NEVER skip the planner step for new features. Implementation without an approved plan leads to rework.
• NEVER skip the plan-critic step unless the trivial-change criteria in Step 1b are ALL met AND the user explicitly opted out. The default is always to run the critic.
• NEVER fetch external links or docs directly — always delegate to the planner sub-agent, regardless of platform.
• NEVER enter plan mode from within a sub-agent — only the main agent presents plans for review.
• NEVER present work to the user before the code-critic sub-agent has reviewed it.
• If a sub-agent flags NEEDS_DECISION, you MUST relay ALL flagged items to the user and wait. Do not make these decisions yourself.
• Sub-agents are read-only for review purposes — only the main agent implements changes.