Feature

Implement the feature described in $ARGUMENTS.

Parse arguments

• /feature → resolve to docs/specs/NNN_.md (or docs/specs/NNN_/ for a sliced spec) by matching the suffix after the prefix. Specs carry a roadmap-phase-aligned NNN prefix — see /spec for the numbering rules. If multiple specs match, ask which.
• /feature .md → use explicit path
• /feature # → fetch the GitHub issue # via gh issue view (or the GitHub MCP), extract the title and body, then resolve the spec by scanning docs/specs/ for a file whose Issue: # field matches. If found, proceed with that spec. If not found, treat the issue title/body as the feature description and ask (via AskUserQuestion) whether to create a spec first or build inline.
• --commit — after the feature is complete and verified, auto-commit without presenting a plan for approval. Apply the same grouping logic from /commit but skip step 5 (plan presentation). Output only the git log --oneline - lines for the new commits. No other output.
• --pr — implies --commit: auto-commit (as above), then immediately open a PR without presenting a draft for approval. Apply the same PR logic from /pr but skip step 7 (draft presentation). Output only the git log --oneline - lines and the PR URL. No other output.

If the spec doesn't exist, use AskUserQuestion to ask whether to create one via /spec first or build without a spec (they describe the feature inline). For bugfixes, use /fix instead.

Asking the user questions. Whenever this skill needs a decision from the user mid-flight (missing spec, slice-size override, split shape, ambiguous metadata, etc.), use the AskUserQuestion tool — never plain free-text prompts. Phrase the question clearly, lead with your recommendation as the first option labelled "(Recommended)", and keep options mutually exclusive. Free-text follow-up is always available to the user via the auto-injected "Other" choice, so don't pad with a custom-input option.

If the spec lives under docs/specs/NNN_/ (sliced spec, per /spec's trunk-based slicing), /feature implements one slice at a time. The argument must point to a specific slice file (docs/specs/NNN_/MMM_.md), never the index README.md.

Branch

Before writing code, ensure you are on a short-lived branch named for this slice, always cut from main (never from another feature branch — trunk forbids stacking).

Branch-name resolution order:

1. If the spec's ## Trunk Metadata (or its row in the Slices table) has a filled Issue: # field, use /- — e.g., feat/42-jira-sync. This is the canonical form after /issues has run.
2. If no issue is filed yet, fall back to / — e.g., feat/jira-sync. When the issue later gets filed, do NOT rename the branch mid-flight; keep the name and put Closes # in the PR body.
3. ` comes from the spec's Type field (feat/fix/refactor/chore/test/docs/perf/security`).

If the spec is missing Type or Issue, warn the user and pick the most conservative default (feat/). Don't silently guess.

See the global Trunk-Based Workflow in root CLAUDE.md for worktree conventions.

Workflow

1. Read the spec. Note the Verification Criteria — your tests must cover each one.

1. Pick a test strategy. Read docs/TECHNICAL_DESIGN_DOCUMENT.md if it exists; otherwise infer from the project (test dirs, package.json / pyproject.toml / Makefile, 1–2 existing test files). Unit tests always; integration tests when the feature crosses boundaries (API, DB, filesystem, subprocess); e2e only for critical user flows. If no tests exist yet, set up the minimum infrastructure and tell the user.

Test placement is a contract, not an implementation detail. If the spec or existing project structure distinguishes tests/unit/ from tests/integration/ (or equivalent layout), mirror that distinction in directory placement based on what the test covers, not how you wrote it. A test that exercises a module across a real boundary (Qdrant container, respx-stubbed HTTP, tmp_path filesystem) belongs in tests/integration/ even if it runs fast and mocks a few leaves. A test of pure logic belongs in tests/unit/ even if the function happens to be in a service-layer file. Getting this wrong scatters integration coverage into the unit suite, where it drifts out of the slow-path CI filter and stops catching the boundary regressions it exists to catch.

1. Plan if non-trivial. Touches 3+ files or has non-obvious design decisions? Use Plan Mode to align before writing code.

For larger scopes (6+ files or multi-phase work), before writing any code produce a file placement table derived from the spec — one row per module, with columns: (source file, test file, test type, depends on). This forces you to resolve test-type ambiguity up front against the spec's language, catches underspecified corners, and gives the user a checkpoint before the implementation commits to a structure. If the project already has a tasks.md or equivalent task breakdown (e.g., from /speckit-tasks), treat it as the source of truth for file paths and test placement and skip generating a duplicate table.

1. Implement with tests, layer by layer. Unit → integration → e2e. Run each layer and fix failures before moving on. Tests must cover every Verification Criterion.

Parallel implementation (safe-by-default). When step 3 produced a file placement table, use the depends on column to partition rows into waves: Wave 0 = rows with no deps; Wave N = rows depending only on Waves 0..N-1. Within a wave, a set of rows is parallel-safe only if all of these hold:

• 2+ rows in the wave.
• Source files are fully disjoint across rows (no two rows edit the same file).
• Test files are fully disjoint (no shared test module being mutated).
• No shared test fixtures/factories/mocks are being modified (read-only shared fixtures are fine).
• No row touches a shared config, schema, migration, or generated file (package.json, pyproject.toml, go.mod, schema.sql, OpenAPI, codegen outputs) — serialize those.
• Test infrastructure (runners, CI config, conftest) is already in place — if step 2 is setting it up, do that inline first, then parallelize.

If any check fails, implement that wave sequentially. When in doubt, serialize — a single retry costs less than a tangled merge. For each parallel-safe row in a wave, spawn an implementer subagent with Agent(subagent_type: "general-purpose", model: "sonnet", ...). The prompt must be self-contained: spec path + relevant excerpt, the exact files to create/edit (and "do not touch any other file"), test placement rules from step 2, verification commands, and coding conventions from CLAUDE.md. Use isolation: "worktree" when a wave has 3+ agents to prevent working-tree contention; for 2 agents on disjoint files, same-tree is fine. After each wave: run the project's test suite, fix failures inline (do not respawn), then dispatch the next wave. Never pipeline waves — always barrier between them. If no placement table was produced (scope /MMM_*.md`"). Recommend the option that best matches the diff shape — recommend "ship as-is" only when the bulk is mechanical (formatter reflow, generated lockfile, mass rename) and the substantive review surface is small.

• If the spec is already one slice of a sliced feature: include "ship as-is", "defer hunks X/Y to a follow-up slice", and any other relevant choice for the user.

Never silently leave a >200-line slice in the working tree. The gate can be overridden by the user ("ship as-is"), but never by the skill.

Feature flag wiring. If the spec's ## Feature Flag section names a flag, verify the new behavior is gated by it. If the flag doesn't exist yet in the project, create it (default off) as part of this slice.

1. External review (fresh-context subagent, bounded fix loop). You are the writer. You do not review your own work — that violates the writer/reviewer rule in CLAUDE.md and produces lower-quality reviews because your context is biased toward the choices you just made. Instead, spawn a single reviewer subagent with cold context.

Do NOT use the code-review skill in this session — skills run in your context, which defeats the purpose. Always use the Agent tool to spawn an external reviewer.

Reviewer dispatch:

`` Agent( subagent_type: "general-purpose", model: "sonnet", run_in_background: false, description: "Review feature implementation", prompt: ) ``

Reviewer prompt (token-disciplined — do not let it explore the whole codebase):

``` You are a code reviewer with fresh context. You DO NOT write code.

## Project context (5 lines)

## Your inputs (read ONLY these)

1. The diff: git diff ...HEAD (or git diff if not yet committed)
2. The spec:
3. Selective reads: only files the diff makes you doubt (e.g., a caller of a changed function). Cap: 3 files.

If you want to read more than 3 extra files, STOP and emit a LOW finding "review-coverage-limited". Do not actually read them.

## Checklist (focused, not exhaustive)

• Spec compliance: does the diff implement what the spec says, no more, no less?
• Verification criteria: are all spec verification criteria covered by tests?
• Security: input validation at boundaries, authz, secrets, injection (where applicable)
• Correctness: obvious bugs, error handling at boundaries, race conditions
• Test quality: tests actually exercise the change (not tautological)
• Convention drift: respects nearby existing patterns

Out of scope: lint-style nits, unrelated refactors, hypothetical futures.

## Output — exact format, nothing else

VERDICT: PASS | FIX_REQUIRED FINDINGS:

• [HIGH]
• [MED]
• [LOW]

(PASS with only LOW findings is allowed — they become user-facing nits, not fix-loop triggers.) (No findings → "FINDINGS: none" and VERDICT: PASS.)

SUMMARY: ```

Process the verdict:

• PASS with no findings → record Review: PASS. Continue to step 7.
• PASS with LOW findings only → record Review: PASS_WITH_NITS and surface the LOW list to the user verbatim in step 7. Continue.
• FIX_REQUIRED (HIGH/MED present) → fix exactly the listed action items in your current context (you're warm — you have the spec and files loaded; respawning a fresh fixer would be pure waste). After fixing, re-run the quality gate from step 5, then re-dispatch the reviewer with one extra line in its prompt: "This is review cycle 2. Your previous findings were: . Verify they are resolved. Find any new issues introduced by the fix."

Bounded loop: max 2 fix cycles. If cycle 2 still returns FIX_REQUIRED:

• Record Review: NEEDS_HUMAN — HIGH/MED unresolved after 2 cycles.
• If the SAME finding category surfaced in both cycles, also record Spec ambiguity suspected at — this usually means the spec, not the code, is the problem.
• Surface both to the user in step 7. Do NOT loop further.

Token shape: reviewer is small (diff + spec + ≤3 files), runs at most twice. Worst-case overhead vs. no-review is roughly +25–40% of writer cost; common case (PASS first try) is +10–15%.

1. Report and stop.

If --pr or --commit was passed, skip the summary below and go directly to the auto-commit/PR path described here:

• Auto-commit (--commit or --pr): Apply /commit's grouping and message logic (steps 1–4 of that skill) but skip plan presentation. Stage and commit each group sequentially without asking. On pre-commit hook failure, stop and surface the error — never bypass with --no-verify. After all commits land, output only git log --oneline - (where N = number of new commits). Nothing else.

• Auto-PR (only when --pr): After auto-commit, apply /pr's push and body-drafting logic (steps 1–6 of that skill) but skip draft presentation. Push the branch and create the PR immediately. Output only the PR URL. Nothing else.

• Combined output for --pr: one git log --oneline - block followed by one PR URL line. No headers, no summaries, no reminders.

Otherwise (no flag), summarize for the user:

• Files changed — git diff --stat output, or a short list.
• Verification — lint / typecheck / test commands run and their tail output.
• Review verdict — from step 6: PASS / PASS_WITH_NITS (list the LOW nits) / NEEDS_HUMAN (list the unresolved HIGH/MED, plus any "Spec ambiguity suspected" note).
• Slice metadata — for the eventual PR body the user will write: spec link, Closes # line from the spec's Issue: field (or Closes: (none — ran before /issues)), feature-flag state from ## Feature Flag, and a one-paragraph test plan (which layers were touched, how to re-run them).

Then stop. The user reviews the working tree and decides next steps (typically /commit then /pr).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: 0xrafasec
• Source: 0xrafasec/ai-workflow
• License: MIT

Install and usage instructions live in the source repository linked above.