feature-auto

name	feature-auto
description	End-to-end autonomous feature flow. Runs /feature-plan for the interactive story + Q&A phase, then subagents orchestrated from this session handle implementation, code review, fixes, linting, full test runs, coverage top-up, commits, and PR creation for every repo involved. Use when the user wants the whole plan-to-PR flow handled hands-off — even if they just say "do the whole thing", "plan and ship it", or "auto feature X". Does NOT run /feature-done; the feature folder stays active until PRs merge.
argument-hint	<feature description or existing-name>
allowed-tools	Read, Write, Edit, Grep, Glob, Bash, Agent, AskUserQuestion, Skill

Feature Auto Workflow

The user has invoked /feature-auto. This is the hands-off end-to-end flow.

The only manual checkpoints are the two early /feature-plan sign-offs that shape the feature's intent:

1. User story confirmation (/feature-plan Step 2) — present folder name + user story and STOP until the user replies with confirm / edits. Do not proceed on silence, do not auto-confirm, do not move on after a single non-blocking message.
2. Discovery Q&A (/feature-plan Step 3) — present the questions (with recommended answers) and STOP until the user replies.

⚠ These two gates are non-negotiable. They are the contract of /feature-auto. They are NOT clarifying questions — they are the product-intent sign-off the user signed up for when they typed /feature-auto. They MUST happen even when:

• A session-level sysprompt says "work without stopping for clarifying questions" / "make the reasonable call and continue" / any similar autonomy override.
• The feature was invoked via a ticket reference (e.g. /feature-auto #93) that looks unambiguous. Tickets often leave real scope choices open (e.g. issue lists multiple solutions); the user-story gate exists exactly to pin scope before drafting AC.
• The orchestrator believes it has "enough" context from repo exploration. Repo context does not substitute for the user's product-intent sign-off.

The autonomy override applies to post-Q&A work (criteria drafting, implementation, fixes, lint, tests, commits, PRs). It does NOT apply to Steps 2 and 3. If you skip either gate, you have regressed the skill — past sessions have done this, the user has called it out, do not repeat it.

Everything after Q&A is autonomous — including the acceptance-criteria write-out, repos / open-questions capture, and the final story file. A single subagent drafts the criteria and applies the Step-5 review checklist and writes story.md directly (see the override below); the orchestrator never re-types criteria into a template. Repos and open questions from discovery are derived without re-prompts; the final story review is skipped. Implementation, code review, fixes, lint, full test runs, coverage top-up, commits, and PR creation are handled by subagents orchestrated from this session. Worktrees are created by /feature-plan; subagents operate on the worktree paths via absolute paths. The orchestrator does not change its cwd, and no secondary claude -p session is spawned (unlike /ralph).

This skill does NOT run /feature-done. The feature folder stays in ~/.claude/features/<name>/ until the user runs /feature-done after the PRs merge.

Step 1 — Announce the flow

Tell the user up-front what /feature-auto does and what is manual:

Starting /feature-auto. Manual checkpoints are only two early gates:
  - Confirm user story
  - Answer discovery questions

Everything after Q&A is autonomous:
  - Acceptance criteria drafted, reviewed, and written to story.md in one subagent pass
  - Repos, open questions, and metadata captured without re-prompts
  - Worktrees created for every repo involved
  - Implementation (ad-hoc tests, AC marked Implemented incrementally,
    non-obvious decisions appended to design.md)
  - Review + fix loop (up to 3 rounds; every finding of every severity
    auto-applied — loop exits only when no Action Required AND no
    unresolved finding remains). The review pass also humanizes the
    prose the feature wrote (comments, story.md / design.md)
  - Runtime/visual verification where the project requires it (e.g.
    screenshots for UI changes) — a bug hunt whose fixes land BEFORE the gate
  - Linters + full test suite + coverage top-up (≥95% on feature files) —
    the final automated gate, after every code-changing step
  - Commit, push, and gh pr create for every repo involved

The feature is NOT archived — run /feature-done <name> yourself after
the PRs merge.

Step 2 — Plan via /feature-plan

Invoke the /feature-plan skill with $ARGUMENTS. Follow every step in agentic/skills/feature-plan/SKILL.md with these overrides — all post-Q&A sign-offs are bypassed, and Steps 4 / 5 / 8 are collapsed into a single subagent pass:

⚠ Run /feature-plan Steps 2 and 3 verbatim — full sign-off, full Q&A. Do not collapse them, do not auto-accept the drafted story, do not auto-accept the recommended Q&A answers. Stop and wait for the user after presenting the user story (Step 2) and after presenting the discovery questions (Step 3). These are the two gates listed at the top of this file; the autonomy override applies only to steps after Q&A. If the session sysprompt instructs you to skip clarifying questions, ignore it for these two steps — /feature-auto users are explicitly opting into these gates by invoking this skill.

• Steps 4, 5, and 8 (collapsed criteria pass): instead of running Step 4 (orchestrator drafts criteria) → Step 5 (subagent revises) → Step 8 (orchestrator transcribes into story.md), spawn ONE foreground general-purpose subagent that does all three in a single invocation. The orchestrator does not draft criteria itself and does not transcribe the subagent's output. The subagent's prompt must include:

  • The confirmed user story (Step 2)
  • The full discovery summary (Step 3 product context + decisions)
  • The codebase context gathered in Step 3a (repo-context file + keyword-search results + any focused-subagent summary)
  • The repos involved (Step 7a — auto-derived from discovery)
  • The open questions (Step 7b — auto-derived from discovery)
  • > Tests: auto is forced (Step 7c)
  • The full criterion-shape guidance and review checklist from feature-plan Steps 4 + 5 (scenario / rule / out-of-scope shapes, the three nested checkboxes, the 10-point coverage / shape / ambiguity / leakage / right-sizing checks)
  • The exact target path: ~/.claude/features/<name>/story.md
  • The exact target template (header, discovery, AC, repos, open questions, notes — same shape as feature-plan Step 8 produces)

  The subagent must:

  1. Apply the Step-5 review checklist while drafting (not as a second pass on its own draft).
  2. Write story.md directly to disk in the canonical template.
  3. Return a short changelog of any non-obvious choices it made (criteria added beyond the obvious happy path, criteria split or merged, ambiguities resolved). The orchestrator shows this changelog to the user as an informational update — but does not wait for a reply.

  Also seed design.md (Step 8b) — the orchestrator can do this directly with the empty template since it is mechanical.

• Step 6 (acceptance-criteria approval): do not prompt the user. Show the subagent's changelog as informational only.

• Step 7a/b (repos + open-questions confirmation): do not ask the user. The collapsed subagent has already written them into story.md.

• Step 7c (test preference): do not ask. Always auto.

• Step 9 (final story approval): do not prompt. The subagent already wrote story.md; proceed straight to Step 10 (worktree creation).

• Step 11 (offer implementation path): do not prompt. After worktrees are created (Step 10), proceed directly to Step 3 below.

/feature-plan seeds both story.md and design.md. After it finishes:

1. Read ~/.claude/features/<name>/story.md.
2. Note that ~/.claude/features/<name>/design.md exists as an empty living log — every subagent you spawn must read it before working and append any non-obvious decisions it makes.
3. Extract the primary worktree path from > Working directory:.
4. If a ## Worktrees table is present, collect every (repo, worktree path, source, branch) row. Otherwise the primary worktree covers the only repo.
5. Store this set — every downstream subagent needs the absolute worktree paths.

If > Worktree: true is not present in story.md (user declined worktrees in the initial prompt to /feature-plan), use the repo directories listed under Repos Involved as the working paths. The rest of the flow is unchanged.

Step 3 — Implement via subagent

Spawn one general-purpose subagent to carry out the implementation. Wait for it to complete.

The subagent prompt must include:

• Full contents of story.md and design.md
• Feature folder path (~/.claude/features/<name>/)
• Every worktree path (absolute) with its repo name
• Instruction to follow agentic/skills/feature-implement/SKILL.md Steps 3b through 6, with these constraints:
  • Operate via absolute paths and git -C "<worktree>". Do not assume a particular cwd; the orchestrator keeps its own.
  • Skip branch creation — worktrees already have feature/<name> checked out.
  • Write tests ad-hoc alongside implementation, targeting near-100% line/branch coverage for the code it introduces.
  • Mark each acceptance criterion - [x] Implemented in story.md incrementally as it satisfies them. Do not touch Reviewed or Action Required — those are owned by the review/fix flows.
  • Append non-obvious implementation decisions to design.md using the entry format at the bottom of that file, tagging the entry's Source as feature-implement.
  • Run only the test files it wrote/touched at the end (Step 6 auto mode). The full lint + test + coverage sweep runs later in Step 5.

When the subagent returns, re-read story.md. If any acceptance criterion still shows - [ ] Implemented, spawn a follow-up subagent with the remaining gaps and wait for it. Cap the follow-up at two attempts — if criteria still aren't implemented after two retries, surface the gap to the user.

Step 4 — Review / fix loop

Iterate review + fix until both are true — no criterion has - [x] Action Required and review-fixes.md has no unresolved actionable finding of any severity — with a hard cap of 3 rounds.

Action Required is a per-criterion gate (it only fires for findings that map to a criterion with PARTIAL/MISSING coverage or HIGH/CRITICAL drift). It is not the list of things worth fixing. Many real improvements land as LOW findings that don't flip any criterion's Action Required — a plural-rule typo, a one-frame flash, a missing nil-guard. The fix step (4c) auto-applies every finding regardless of severity, so the loop must keep going while any actionable finding remains, not just while Action Required is set. Gating the loop on Action Required alone would let a round that produced only LOW findings exit before any fix subagent ran — silently dropping every one of them. Don't do that.

4a — Review

Spawn a general-purpose subagent to execute the full workflow in agentic/skills/feature-code-review/SKILL.md for <name>. Include the worktree paths, feature folder path, and design.md path in the prompt. The subagent writes ~/.claude/features/<name>/review-fixes.md and — via /review-code's Behavior Verification agent — checks - [x] Reviewed on every criterion it covers, and checks - [x] Action Required on every criterion that has findings requiring a code change. The subagent also runs /feature-code-review's /code-commenter pass on the changed files (Step 5 of that skill) before writing review-fixes.md.

After the /code-commenter pass, the same subagent runs /humanizer over the prose the feature introduced or changed — code comments in the changed files plus any story.md / design.md text this session wrote — to strip AI writing tics before the fixes and the PR description are generated. /humanizer only rewrites style; it must preserve meaning exactly. Its edits ride along in the review round like any other change.

4b — Triage

Read story.md and review-fixes.md.

• If review-fixes.md has no unresolved actionable finding (every finding is marked Fixed or Won't-fix-with-reason) and no criterion has - [x] Action Required checked: exit the loop and proceed to Step 5.
• Otherwise (any criterion has Action Required, or review-fixes.md still lists any unresolved finding of any severity — LOW included): proceed to 4c.

A round that surfaced only LOW findings and zero Action Required still goes to 4c — those LOWs are real improvements and must be applied (or explicitly won't-fixed with a reason), never skipped because no criterion gate fired.

4c — Fix (auto-accept all findings)

Spawn a general-purpose subagent to execute agentic/skills/feature-code-fix/SKILL.md Step 4 (the execution subagent) directly. /feature-auto pre-authorises full auto-apply, so skip the Step 3 interactive triage — every finding in review-fixes.md, of every severity (LOW included), is treated as accepted. The fix subagent will:

• Apply every accepted finding that improves the code or app — regardless of severity or whether it mapped to an Action Required criterion.
• For any finding it does not apply, mark it Won't-fix in review-fixes.md with a one-line reason. A finding may only be won't-fixed when it is genuinely not an improvement — a false positive, a story-sanctioned choice, an intentional behavior, or a deliberately-rejected minimization. "Too small / out of scope" is not a valid reason to drop a real improvement: if a real improvement is being deferred rather than applied, file it as a tracked GitHub issue (tier label matching its size, plus the feature name) and record the issue link as the finding's status, so it is never silently lost.
• Append non-obvious decisions to design.md with Source feature-code-fix F<id>.
• Uncheck Action Required for every criterion whose findings were all resolved.
• Update review-fixes.md with per-finding status (Fixed / Won't-fix-reason / tracked-as-#NN).

Return to 4a for the next round.

Loop exit

If round 3 still has criteria with - [x] Action Required (or unresolved non-won't-fixed findings), stop the loop and surface the outstanding criteria

• findings to the user — this signals a reviewer/fixer disagreement that needs human judgment. Do not proceed to Step 5 until the user decides.

After the loop exits cleanly, confirm that every criterion with - [x] Implemented also has - [x] Reviewed and that no criterion has - [x] Action Required. Any deviation means a subagent missed an update — fix it before moving on.

Step 4.5 — Runtime / visual verification (when the project requires it)

If the project mandates a runtime or visual verification for the kind of change this feature makes — e.g. screenshots for any user-visible UI change, or a manual smoke-run — do it here, after the review/fix loop and before the Step 5 gate. This is a bug hunt that produces code fixes, not a photo op: it routinely surfaces truncation, contrast/theme slips, missing accessibility, broken empty/error states, wrong navigation, and decode mismatches that build-green and unit tests cannot catch. Fix every defect it finds in the worktree, append the decision to design.md, and re-verify — exactly like a fix round.

The accessibility tree and screenshots catch different bug classes, so when a project supports both, use both. The AX tree verifies behavioral state — values, labels, navigation, and whether an element resolves at all; screenshots verify rendering — layout, spacing, color, typography, truncation. A green AX assertion doesn't prove the pixels are right, and a clean screenshot doesn't prove the control is reachable. Prefer the AX tree first (it's text — cheap and precise), and reach for a screenshot when layout, color, or typography is what's actually in question.

Order matters: this step must run before Step 5, never after. Step 5 (lint

• full tests + coverage) is the final automated gate — it only certifies the tree green if every code-changing step has already happened. Running screenshots/manual QA after Step 5 (or after Step 6's PR) means any fix they produce bypasses the gate: it ships un-lint-checked, un-tested, and outside the coverage top-up, validated only by CI after the fact. If a project has no runtime/visual mandate for this change (e.g. a backend-only or refactor-only feature), skip this step.

Step 5 — Lint, full tests, coverage

This is the final automated gate before commit. By the time it runs, every step that can change code — implementation, the review/fix loop, and Step 4.5's runtime/visual fixes — must already be done, so the sweep certifies the complete tree. If a later step changes code, re-run this gate.

Spawn one general-purpose subagent per repo (parallel when repos are independent). Each subagent receives:

• The worktree path (absolute)
• Repo name and ~/.claude/repo-context/<repo>.md path (if it exists)
• Paths to story.md and design.md (for feature context)
• The list of files the feature touched (derive with git -C <worktree> diff --name-only origin/<base-branch>)

Each subagent's job:

1. Detect tools. From the repo's config files — package.json, pyproject.toml, Cargo.toml, go.mod, build.gradle, Package.swift, .swiftformat, .swiftlint.yml, Makefile, CI workflow files — identify the linter, formatter, test runner, and coverage tool. Fall back to repo-context if present.
2. Run linters + formatters. Fix every failure. Do not suppress or silence — fix the root cause.
3. Run the full test suite. All tests must pass.
4. Measure coverage on files touched by the feature. Use the repo's coverage tool when available.
5. Top up coverage. Target ≥95% line/branch coverage on feature files. For every uncovered line or branch, add a test that exercises it. Skip only genuinely unreachable code, with a one-line justification in the subagent report.
6. Re-run lint + tests to confirm green state after additions.
7. Log test-strategy decisions. If the subagent makes a non-obvious testing choice (e.g. stubbing a boundary, choosing contract vs unit scope for a piece of logic), append to design.md with Source feature-auto Step 5.

Swift / Xcode repos: run xcodebuild piped through xcbeautify with set -o pipefail (xcodebuild … 2>&1 | tee build.log | xcbeautify) so the gate reads a few file:line:col anchors instead of thousands of compiler lines — the mirrored build.log is the fallback when an anchor isn't enough. xcbeautify collapses each @Test(arguments:) suite to one pass/fail line, so on a parameterized failure, read build.log for the failing argument row before concluding which case broke.

Each subagent reports back:

• Lint / format status
• Test counts (pass / fail)
• Coverage percentage per changed file and overall
• Any justified gaps

If any repo reports unresolved failures, or coverage below the threshold without valid justification, surface it to the user before Step 6.

Step 6 — Commit, push, PR per repo

/feature-auto is a pre-authorisation for push + PR creation. Do not re-prompt for confirmation at this step — the user signed up for this when they invoked the skill.

For each repo listed under Repos Involved in story.md:

1. Commit. From the worktree, stage only the feature-related files and commit with a message matching the repo's style.

   git -C "<worktree>" add <feature-related paths>
   git -C "<worktree>" commit -m "<short imperative message>"
   

   Inspect git -C <worktree> log --oneline -20 to match the repo's commit-message style (e.g. this dotfiles repo uses Added <X> / Updated <X> / Fixed <X>). Split into multiple commits when it produces a cleaner history. Do not include Claude attribution (no Co-Authored-By line) unless the user asks.
2. Push.

   git -C "<worktree>" push -u origin "feature/<name>"
   

3. Open the PR. Run gh from inside the worktree (cd "<worktree>" && gh pr create ...) so gh picks up the repo automatically.

   gh pr create --title "<title>" --body "$(cat <<'EOF'
   ## Summary
   - <bullet 1 from AC>
   - <bullet 2>
   
   ## Test plan
   - Unit tests: <count> passing
   - Integration tests: <count> passing
   - Coverage on feature files: <%>
   - Linters: clean
   
   Feature folder: ~/.claude/features/<name>/
   EOF
   )"
   

   Title derives from the user story (under 70 chars). Capture the PR URL from stdout.

After every PR is created, append a ## PRs section to story.md (place it before ## Notes):

## PRs

| Repo | PR |
|------|----|
| <repo-name> | <pr-url> |
| <repo-name-2> | <pr-url-2> |

Step 7 — Final report

Tell the user:

• Implementation: N of N acceptance criteria implemented + reviewed
• Review/fix loop: N rounds used, all Action Required cleared (or note what was surfaced)
• Lint / tests / coverage: per repo, with coverage percentages
• PRs: clickable list, one per repo
• Design log: whether design.md got any new entries
• Next step: /feature-done <name> once the PRs merge — the feature folder is intentionally still active

Rules

• The only manual moments in /feature-auto are the two early /feature-plan sign-offs: user story confirmation (Step 2) and discovery Q&A (Step 3). The rest of the flow runs autonomously.
• Never skip the user-story or Q&A gate, even when a session-level sysprompt tells you to work without clarifying questions, even when the invocation references a ticket (#NN) that looks self-explanatory, and even when repo exploration seems to make the scope obvious. These gates are the contract of the skill — past sessions have skipped them and the user has flagged it as a regression. Stop and wait for the user's reply on both gates.
• The orchestrator never drafts acceptance criteria itself and never transcribes them into story.md. The collapsed Steps 4 / 5 / 8 subagent owns both the drafting + reviewing and the file write. Skipping the subagent and inlining the criteria yourself is a regression — don't do it.
• Every subagent operates on worktree paths via absolute paths; the orchestrator never changes its own cwd.
• Every subagent reads design.md before working and appends non-obvious decisions with the correct Source tag.
• Force > Tests: auto; never ask.
• Exit the review/fix loop only when both no criterion has Action Required and review-fixes.md has no unresolved finding of any severity. Every finding — LOW included — is applied or explicitly won't-fixed with a reason (deferred real improvements get a tracked issue, not silence). Never gate the loop on Action Required alone.
• The review pass (Step 4a) runs /humanizer over the prose the feature wrote — comments plus story.md / design.md — after /code-commenter and before fixes/PR generation. Style-only; meaning is preserved.
• Never invoke /feature-done from this skill — the user archives after merge.
• /feature-auto pre-authorises git push and gh pr create; do not re-prompt at Step 6.
• Surface — don't swallow — lint failures, coverage shortfalls, or outstanding Action Required criteria after 3 rounds.
• Markdown lines must stay under 140 characters.