--- name: feature description: "Add a feature to an existing codebase. Lightweight by default: production-build + tests + review + PR. Concept slides / wireframe / prototype / codify are opt-in for work where risk, ambiguity, or new user-visible behavior justifies them." argument-hint: "[feature-name] [--size trivial|standard|major]" --- # /feature — Feature Workflow (Lightweight by Default) You are orchestrating a feature implementation. **The default flow is lightweight** — jump to production-build → tests → review → PR (Steps 7 onward). Concept, wireframe, prototype, and codify phases are **opt-in**, enabled at preflight only when the user confirms the work needs them. Why this default: most `/feature` invocations are bounded changes to existing code (new endpoint, new screen wired into existing patterns, adjustment to existing behavior) and run cleanly through TDD + review without needing the prototype-driven pipeline. The pipeline phases exist for work that genuinely needs them — multi-screen new flows, UX iteration, interactive exploration of an unsettled design, or architecture changes — and stay one user-confirmation away. ## Execution Protocol **REQUIRED SUB-SKILL**: load and follow the skill — do not substitute judgment. Step summaries describe outcomes; the loaded skill defines the process. ## Input Ask the user for: 1. **Feature name** (slug format, e.g. `add-payments`, `user-auth`) 2. **Feature description** (what should it do?) 3. **Existing requirements** (docs, tickets, screenshots, meeting notes) 4. **Complexity** (optional): `trivial` / `standard` / `major`. If not provided, the preflight phase planner suggests one. ## Step 0: Repo-State Detection & Routing Redirect Before any other check, detect whether this repo is in **prototype mode** or **production mode** per `rules/common/skill-selection.md` Step 1. 1. **Local context wins** (the mixed-mode override). Check work-item-local signals first; these override the project-level declared mode: - Working directory or work path is under `pocs/`, or its name ends in `-prototype` - Existing manifest under `.forge/work/feature/` has `phase_plan.prototype: active` and `phase_plan.codify: skipped` If either local signal fires, treat as prototype and proceed to the redirect offer below, regardless of `project.mode:` in CLAUDE.md. 2. **Otherwise, read `.claude/CLAUDE.md`'s `project.mode:`** (set by `/setup` Step 2.5): - `prototype` or `greenfield` → offer the redirect below. - `production` → skip the redirect and proceed straight to Step 0a. - Absent (e.g. pre-Step-2.5 install, or `/setup` not yet run) → ask the user once and persist the answer per `rules/common/skill-selection.md` Step 1. Note: an "empty `aiwiki/architecture/`" check is intentionally NOT a signal — every fresh forge install starts with empty `aiwiki/architecture/`, so using it would misclassify existing codebases as prototypes. See `rules/common/skill-selection.md` Step 1. **If prototype mode is detected**, stop and offer the redirect: ``` This looks like prototype iteration on an existing prototype (signals: ). /feature would spin up a 7-phase production workflow (concept → wireframe → prototype → iterate → codify → production-build → deliver). Most phases would end up explicitly skipped, which trains the manifest to lie about gate state. The right route here is iterate-prototype — lightweight in-place tweaks, no harden/codify ceremony, capture gotchas as feedback items. Redirect to iterate-prototype? [Y]es / [n]o continue with /feature anyway / [a]bort ``` User responses: - **Y / yes**: invoke `iterate-prototype` skill with the feature description as input. Skip the rest of /feature's steps. - **n / no**: proceed to Step 0a below. User must explicitly accept that most phases will be marked `skipped` in the manifest. - **a / abort**: stop without action. If production mode is detected (or the user chose "no continue"), proceed to Step 0a. ## Step 0a: Preflight Checks 1. Git is clean — no uncommitted changes 2. Tools installed (build tools, test runner, package manager) 3. Tests pass on current branch — if failing, STOP ## Step 0b: Trivial-Pattern Fast Path (deepest shortcut) Before any other preflight question, detect whether the work is single-pattern trivial. If so, jump to a one-confirmation flow that skips even the lightweight-vs-extended question below. **Detection signals (any one is sufficient):** - `--size trivial` flag passed - Description matches obvious single-pattern phrases: "fix typo", "change copy", "tweak ", "rename X to Y", "bump version", "update dep", "add log line" - User has explicitly scoped to a single file path in the description **If a trivial signal fires, offer:** ``` This looks like single-pattern trivial work (signal: ). Fast path: skip Steps 0c, 1–6 entirely (no preflight question, no phase planning, no discover / concept / wireframe / design-system / prototype / codify) and jump to: Step 7 Worktree Step 8 Production-build (build-tdd with --size trivial → focused regression test) Step 9 Test plan + execution (trivial: unit tests for changed code, no E2E/load) Step 10 Final code review Step 11 Create PR Step 13 (gotcha capture) is also skipped on this path — trivial work doesn't merit aiwiki state, and bootstrap was skipped at Step 0d. Manifest will be created with phase_plan: concept, wireframe, plan-design-system, prototype, iterate, codify, discover-codebase, uiux-review, onboarding, gotchas: skipped production-build, test-plan, code-review-final, deliver: active Confirm fast path? [Y]es / [n]o use standard preflight / [a]bort ``` User responses: - **Y / yes**: skip Step 0d (wiki bootstrap is unnecessary), create the manifest with the trivial `phase_plan` above, then jump directly to Step 7. - **n / no**: proceed to Step 0c. User wants to consider whether extended phases apply. - **a / abort**: stop without action. If no trivial signal fires, proceed to Step 0c. ## Step 0c: Lightweight-vs-Extended Preflight (the default question) **The default is lightweight.** Most `/feature` work runs as: production-build (with TDD) → tests → review → PR. Extended phases (concept slides, wireframe, prototype, codify) are opt-in — they exist for work that genuinely needs them, not as the default ceremony. Ask the user **one** question before doing anything else: ``` Default flow: lightweight — production-build (TDD per slice) → tests → review → PR. Extended phases are opt-in. Does this feature need any of: [c] concept slides — multi-screen new flow, design conversation needed [w] wireframe — UX iteration, layout / interaction decisions to lock [p] prototype — interactive exploration of an unsettled design [k] codify — architecture changes, ADRs, slice graph needed Pick any combination (e.g. `wp` = wireframe + prototype), or: [Enter] / [n]o — proceed with lightweight default (no extended phases) [a]bort — stop without creating a manifest ``` **Phase enablement rules:** - Enabling `prototype` (`p`) automatically enables `iterate` (the prototype polish loop) and `codify` (`k`) — you cannot lock a prototype without codifying it before production-build. - Enabling `wireframe` (`w`) automatically enables `concept` (`c`) when a multi-screen flow is implied. (A single-screen wireframe-only change is allowed; ask the user if it's a multi-screen flow.) - Enabling `concept` (`c`) on its own (no wireframe, no prototype) is rare but allowed — produces a 1-3 slide micro-deck for design conversation, then proceeds to lightweight build. - Enabling `codify` (`k`) on its own is NOT allowed: harden derives architecture FROM a locked prototype (per `skills/harden/SKILL.md` Inputs table). Picking `k` without `p` auto-cascades to `pk` — if the user wants architecture decisions on existing code without building a prototype, route them to `/refactor` (which uses `plan-*` skills) instead. - Enabling `codify` (`k`) is implicitly forced off when `project.aiwiki_enabled: false` — there's no `aiwiki/architecture/` or `aiwiki/oracles/` for harden to write to. If the user picks `k` or `pk` with aiwiki disabled, prompt: enable aiwiki via `/setup` or drop `k` and let Phase 6 operate without oracle lookups. **Manifest construction:** - Lightweight default (no flags): `phase_plan` marks concept / wireframe / prototype / iterate / codify / plan-design-system / discover-codebase / uiux-review as `skipped`. Active: `production-build`, `test-plan`, `code-review-final`, `deliver`, plus `gotchas` (kept active so genuine surprises during build can still capture). - Extended (any flag set): the chosen phases become `active` plus their implicit cascades. The rest stay `skipped`. Cascade rules: - `p` → also enables `iterate` and `codify` (per the phase-enablement rules above). - `w` or `p` → also enables `plan-design-system` (Step 4.5 — both phases reference the project's `DESIGN.md`). - any extended pick → also enables `discover-codebase` (Step 1.5 — codebase analysis helps the picked phases avoid skinning conflicts). - UI work + `w`/`p` → also enables `uiux-review` (Step 11 — a/11y review on UI surfaces). - The work flows through Steps 1–6 only for the `active` phases (including the cascades); skipped phases are no-ops with their gates auto-passing per `references/common/quality-gates.md`. **Default-mode validations:** - If the user picks `n`/Enter but later the build reveals genuinely new user-visible behavior, multi-screen flows, or unsettled UX, surface the gap at Step 8 and offer to re-open the relevant phases (changing `phase_plan.{phase}` from `skipped` to `active`). The lightweight default is the assumption, not a one-way door. - If the user picks `c`/`w`/`p`/`k` but during phase execution discovers the phase was unnecessary, mark it `complete-inline` with a reason instead of leaving it half-done. ## Step 0d: Wiki Bootstrap **Skip if** Step 0b's trivial fast path was taken (already past wiki bootstrap by jumping to Step 7). **Otherwise:** REQUIRED SUB-SKILL: Use **support-wiki-bootstrap** to ensure aiwiki/ exists. Both lightweight and extended flows write to `aiwiki/` (gotchas captured during production-build land there even on the lightweight path). ## Step 1: Manifest Creation **Skip if Step 0b's fast path was taken** — the manifest was already created with the trivial phase_plan and the flow has jumped to Step 7. Check if `.forge/work/feature/{name}/manifest.yaml` exists. **If it exists**: Resume from the last incomplete phase. Skip phases marked `locked` or `skipped`. If `status: escalated` or `status: completed`, do NOT resume — surface `successor_path` and ask the user. **If it does not exist**: Create the manifest from `.claude/templates/manifests/feature.yaml` using the `phase_plan` decided at Step 0c. The Step 0c choice (lightweight vs extended + which extended phases) determines which phases are `active` vs `skipped` — no second round of planning here. If escalated from `/bugfix` or `/hotfix`, set `escalated_from: work/{type}/{predecessor-name}`. **Stack selection (only if `prototype` was enabled at Step 0c):** propose `artifacts.prototype.stack:` per `skills/build-prototype/SKILL.md` "Stack variants" — default from `project.stack:` in `.claude/CLAUDE.md` (e.g. `vite-react` for React projects, `nextjs` for existing Next.js apps, `python-fastapi` for Python backends, `go-service` for Go services, `cli` for CLI tools, `existing-repo` for non-Next.js existing apps, `none` to skip the phase). User confirms or overrides. **If `prototype` was NOT enabled at Step 0c, skip the stack question entirely — the lightweight path doesn't produce a prototype artifact.** **Reference table — when extended phases are typically warranted:** | Feature shape | Typical Step 0c picks | |---|---| | Trivial UI tweak (color, spacing, copy) | `n` (lightweight) — the description IS the spec, existing UI is the wireframe | | Single-component change, well-known pattern | `n` (lightweight) — TDD + review + PR is enough | | New screen, single user role, fits existing patterns | `n` (lightweight) — or `w` if layout is unclear | | Multi-screen new flow | `cwp` — concept + wireframe + prototype to nail the UX before coding | | New feature touching auth/payments/PII | `cwpk` — full pipeline + adversarial review on every ADR + security audit escalation | | Backend-only API endpoint with established contract | `n` (lightweight) — or `k` if it introduces a new architectural pattern | | Backend feature needing playground UI for verification | `wp` — admin/playground wireframe + interactive prototype | | Architecture change without UI change | `k` — codify-only path: ADRs + architecture-delta + slice graph, then build | | Refactor disguised as feature | escalate to `/refactor` | This table guides the user's Step 0c answer; it is not a re-litigation of that choice. Whatever Step 0c chose stands unless the user explicitly asks to re-open the question. ## Step 2: Discover — Codebase Analysis — if active **Skip if** `phase_plan.discover-codebase: skipped`. The lightweight default skips this — codebase analysis is overhead for bounded changes the user already has located. It is enabled implicitly when extended phases are picked at Step 0c (concept / wireframe / prototype / codify benefit from knowing where the prototype skins into the existing app), or when the user explicitly enables it. **Otherwise:** REQUIRED SUB-SKILL: Use **discover-codebase-analysis**. For extended-flow features on existing codebases, this is non-optional — production code grows from the prototype, and the prototype skins into the existing app. Without codebase analysis, the prototype-builder will reinvent patterns that already exist. ### GATE: Codebase Analysis Approved User reviews. Update manifest: `discover.codebase-analysis.{status: complete, gate-passed: true}`. ## Step 3: Concept (Phase 1) — if active REQUIRED SUB-SKILL: Use **concept-slides**. For features, often a 1-3 slide mini-deck — what the feature is, where it sits in the existing app, the visual sketch. ### GATE: Concept Locked Update manifest: `artifacts.concept.{deck_path, locked_at}`. Presence of `locked_at` is the lock signal that downstream phases check. ## Step 4: Wireframe (Phase 2) — if active REQUIRED SUB-SKILL: Use **build-wireframe**. For features on existing apps: - If the existing app has a wireframe at `pocs/wireframe/index.html`, fork it and add the new screens / states - If not, produce a mini-wireframe at `pocs/{name}-wireframe/index.html` covering only the feature's screens ### GATE: Wireframe Locked Update manifest: `artifacts.wireframe.{html_path, locked_at}`. ## Step 4.5: Design System — if active **Skip if** `phase_plan.plan-design-system: skipped`. The lightweight default skips this. Design tokens are auto-enabled when `wireframe` (`w`) or `prototype` (`p`) is picked at Step 0c, since both phases reference the project's `DESIGN.md`. Backend-only extended paths (e.g. `k` alone) keep this skipped. **Otherwise:** REQUIRED SUB-SKILL: Use **plan-design-system** to lock design tokens before architecture. For features that add or change UI surfaces, plan-design-system extends the project's existing `DESIGN.md` (or creates one if the project never had a frontend before). The skill self-skips when `DESIGN.md` already exists and is current for this work item. ### GATE: Design Tokens Approved Update manifest: `artifacts.design-system.{path, approved_at}`. ## Step 5: Prototype + Iterate (Phases 3–4) — if active Phases 3 and 4 are distinct in `references/common/phases.md` (Phase 3 = build-prototype, Phase 4 = iterate-prototype) and have separate entries in `hooks/config/gate-requirements.json` (`prototype` + `iterate`), but they share a single lock signal — `artifacts.prototype.locked_at`. The user's satisfaction emission after iteration is the close for both. REQUIRED SUB-SKILL: Use **build-prototype** for the initial scaffold (Phase 3), then **iterate-prototype** for the polish loop (Phase 4). For features on existing apps: - Scaffold `pocs/{name}-prototype/` as a mini-prototype, OR - Skin the new screens into a prototype branch of the existing app (manifest field `prototype_path` records which approach) Capture gotchas + conventions during iteration to `aiwiki/`. ### GATE: Prototype Locked (closes Phases 3 + 4) User emits "satisfied" or "LOCKED" after click-through verification. Update manifest: `artifacts.prototype.{path, locked_at}`. Both `phase_plan.prototype` and `phase_plan.iterate` reach terminal state on this lock. ## Step 6: Codify (Phase 5) — if active REQUIRED SUB-SKILL: Use **harden**. For features, often produces an architecture-delta (extending existing `aiwiki/architecture/{topic}.md` rather than creating new), 0-3 ADRs, and a focused slice graph (the production tasks specific to this feature). For features touching `--size major` complexity (auth, payments, PII, schema changes): adversarial review is mandatory on every ADR. Surface adversarial objections inline in the ADR `review:` block during harden Step 2 and have the user sign off explicitly before the ADR is marked `accepted`. If Codex is configured (`protocols/codex.md`), the review pass may be dispatched to Codex in verify mode. ### GATE: Codified Plan Approved User reviews architecture-delta + ADRs + slice graph. Approves before Phase 6 starts. Update manifest: `artifacts.codify.locked_at` (no path — the populated slice_graph + the aiwiki/architecture/ files ARE the codify artifacts). ## Step 7: Build — Create Worktree REQUIRED SUB-SKILL: Use **build-pr-workflow** to create a git worktree for the feature branch. Update manifest: `build.worktree-created: true`. ## Step 8: Production Build (Phase 6) **If `codify` ran** (`phase_plan.codify: active` — Step 0c picked `k` directly, or `p` which cascaded to `pk`, or `pk` / `wpk` / `cwpk`): execute the slice graph from Phase 5 in dependency order. Per slice, run the loop below. **If `codify` was skipped** (`phase_plan.codify: skipped` — lightweight default, or `c`/`w`-only with no prototype, or `aiwiki_enabled: false` cascaded the skip per Step 0c's rule): there is no slice graph. Treat the entire feature as a single slice driven by the feature description. The user-confirmation between slices collapses into a single confirmation at the end of the build. Per slice (or per the single lightweight build): 1. REQUIRED SUB-SKILL: Use **build-tdd** — strict RED-GREEN-REFACTOR 2. REQUIRED SUB-SKILL: Use **quality-code-review** 3. Fix any Critical or Important findings 4. Per-slice user-confirm 5. **Per-slice dream (auto-fire on slice close, aiwiki-gated).** After the slice's gates pass (`gate-passed: true` on the slice's `code-review` + `runtime-reach`): - **If `project.aiwiki_enabled: false`** (set at `/setup` Step 4; missing → treat as `true` for back-compat): skip the dream call entirely — there is no `aiwiki/proposed/` target to write to. The slice still gate-passes; nothing else changes. - **Otherwise:** invoke the **support-dream** skill with: - **scope:** `aiwiki/gotchas/`, `aiwiki/conventions/` (any subfolders the slice's builder + reviewer subagents wrote to; check git diff on `aiwiki/` since the slice started for a precise list) - **trigger:** `phase-close` - **trigger_detail:** `"Phase 6 per-slice — {slice_id}"` Dream output goes to `aiwiki/proposed/{dream_id}/`. Surface the id + review path to the user. The next slice can start while the proposal is pending review (per-slice dreams do NOT block forward motion — only phase-close gates do). **Skip when:** the slice's build wrote nothing to `aiwiki/` (pure code change with no new gotcha or convention). No-op dreams add noise. For `--size major` features: also escalate to `quality-security-audit` on slices that touch auth/payments/PII. Optional: `/autopilot production` for Ralph-loop hands-off slice execution *(planned, not yet implemented — see docs/V6-PLAN.md §11; per-slice manual dispatch is the only mode today)*. ### GATE: All Slices Complete All slices `gate-passed: true`. Update manifest: `artifacts.production-build.locked_at` (the slice terminal state + the production code ARE the production-build artifacts). Any pending per-slice dream proposals from Step 8.5 must be reviewed before Phase 7 (deliver) starts — Phase 7's retrospective dream depends on a consolidated wiki state. ## Step 9: Test Plan + Execution REQUIRED SUB-SKILL: Use **quality-test-plan** (per complexity), then **quality-test-execution**. - `trivial`: focused regression plan (unit tests for changed code, no E2E/load) - `standard`: full test plan - `major`: full test plan including load/stress scenarios ### GATE: Test Results ALL tests pass. Coverage meets thresholds. ## Step 9.5: UI/UX Review — if frontend feature If the wireframe phase ran (frontend feature): REQUIRED SUB-SKILL: Use **quality-uiux**. Verifies production matches the locked wireframe + design tokens. ## Step 10: Final Code Review REQUIRED SUB-SKILL: Use **quality-code-review** for a final pass across all changes (full diff from feature branch base to HEAD). Fix any Critical or Important findings before creating PRs. ## Step 11: Deliver — Create PRs REQUIRED SUB-SKILL: Use **build-pr-workflow** to create one PR per logical function/component. Update manifest: `deliver.pr-created: true`. ## Step 12: Deliver — Deploy (optional) Ask the user: "Would you like to deploy now?" If yes: REQUIRED SUB-SKILL: Use **deliver-deploy**. ## Step 12.5: Deliver — Update Onboarding Docs - `trivial`: skip - `standard`: skip if purely internal with no new concepts/setup/env-vars/services - `major`: REQUIRED — significant features always warrant doc updates REQUIRED SUB-SKILL: Use **deliver-onboarding**. ## Step 13: Support — Record Lessons **Skip if** `phase_plan.gotchas: skipped` (Step 0b trivial fast path, where wiki bootstrap was also skipped) OR `project.aiwiki_enabled: false` (the knowledge layer is disabled, so there's no destination for gotcha writes or the retrospective dream). The lightweight default at Step 0c keeps `gotchas` active when aiwiki is enabled — genuine surprises during build still get captured. Otherwise: REQUIRED SUB-SKILL: Use **support-gotcha**. Final dream cycle consolidates all wiki captures from the previous phases — also gated on `aiwiki_enabled: true`. If aiwiki is disabled, `support-gotcha` surfaces an upgrade hint per its own contract and the dream call is skipped. Update manifest: `status: completed`. ## Phase Skip Handling When phase planning marks a phase `skipped`, the downstream phase reads from whatever the skipped phase would have produced — e.g. if wireframe is skipped because the user has Figma mockups, the prototype builder uses the Figma export instead of a wireframe HTML. Record skip reasons in the manifest. Skipped phases do not run gates. If a skipped phase reveals a gap during a later phase, that affected phase opens with `locked-with-deltas` and a delta entry pointing back. The downstream phase's gate verifies the delta is closed. ## Gate Checking Logic Resume rule: skip phases where `artifacts.{phase}.locked_at` is present (already locked) or `phase_plan.{phase}` is `skipped`. **Special case for prototype:** if `artifacts.prototype.scaffold_status: complete` is set but `locked_at` is absent, Phase 3 (build-prototype) is done — resume jumps straight into Phase 4 (iterate-prototype) which is the sole writer of `locked_at`. Halt and fix any phase whose gate hasn't passed before continuing.