Build Feature

Build Feature

Run the full feature path. This skill is the driver. It loads other pack skills. It does not invent a third planning method.

Leaves stay callable alone. This is the only pack skill that names them for a pipeline, besides fix-bug offering prove-it.

When To Use

Load when the user runs /build-feature, or asks to implement / build a feature (including a refactor that is not a failure).

Skip if a failure is already in play. That job is fix-bug. Skip typos, comments, format, docs-only. Skip if they only asked for one leaf (/touch-map, /lego-plan, and similar).

Hard Gates

1. No production code until plan 2 is approved. Spec and DAG first.
2. Two blocks. Plan 1 (design spec) must be approved. Plan 2 (implementation plan + DAG) must be approved. Silence is not approval. approved, go, yes, or looks good counts.
3. grill-me is the only interview. Do not run Superpowers brainstorming questions.
4. Do not commit the spec file or the plan file.
5. Same-layer nodes run in parallel. Do not use Superpowers subagent-driven-development as the dispatcher (that loop is one task, then review, then the next).
6. Every implementer subagent must be told to load typescript-standards, test-hygiene, reuse-first, and docs. Pass the confirmed reader list and tone. Workers do not re-ask persona or tone. Workers do not get grill-me, touch-map, lego-plan, writing-plans, or prove-it.
7. Do not load prove-it until the end ask. Default skip. A green DAG is not proof.
8. The driver paints. Subagents never paint. After every live-board status change, the next user-visible message MUST contain a full Mermaid of the board. done nodes are green (:::done). A JSON write, a prose recap, a todo list, or waiting until the layer (or the whole run) ends does not count. If several subagents return in one wake, paint once with every new status. Do not skip the fence because more than one finished.

Flow

grill-me (or skip if design is already settled)
  → docs Phase 1 + persona gate (stop)
  → write spec, open, wait for approved          [block 1]
  → touch-map
  → reuse-first (once, on files-to-touch)
  → lego-plan
  → writing-plans file from the DAG, open, wait  [block 2]
  → one tone gate if any node writes docs pages
  → implement layers in parallel; driver paints DAG after each return
  → optional prove-it

Load each named skill and follow it. Overrides in this file win where they conflict (writing-plans grain, no sequential dispatcher, do not commit those two files, driver paints the live DAG). lego-plan forbids classDef on the plan emit. This driver paint is the exception.

Paint the live DAG

The user-facing product during implement is the colored Mermaid, not the JSON.

The driver (this conversation, the main agent) paints. A worker subagent must not emit the live DAG. Ignore a worker mermaid if one appears.

Paint after:

1. Setting a ready layer to in-progress, before spawn.
2. Each subagent return (this conversation wakes). First actions: update JSON from done when, then paint in the user-visible reply, then continue.
3. Marking a node red.

The paint is a fenced mermaid block in chat. Tool logs and subagent transcripts are not the paint.

Form (ids match the live board; apply :::pending / :::inprogress / :::done / :::failed from JSON status):

flowchart TD
  classDef pending fill:#e5e7eb,stroke:#9ca3af,color:#111
  classDef inprogress fill:#fde68a,stroke:#d97706,color:#111
  classDef done fill:#86efac,stroke:#16a34a,color:#111
  classDef failed fill:#fca5a5,stroke:#dc2626,color:#111
  fetch-order[fetch-order]:::done
  order-card[order-card]:::inprogress
  wire-loader[wire-loader]:::pending
  fetch-order --> wire-loader
  order-card --> wire-loader

Keep every node and the same edges. Do not drop finished nodes. :::done is green so the user can see what landed.

Procedures

Procedure 1: Route

1. If a test is red, CI is red, or the user says it is broken / fix this: stop. Tell them to use fix-bug. Do not start this flow.
2. Else Procedure 2.

Procedure 2: Grill or skip

1. If this conversation already has a settled design (grill already done, or they pasted a spec): do not run grill-me. Write or copy it to the plan-1 path if that file is missing. Then Procedure 3.
2. Else load grill-me and follow it until the design is shared. Then Procedure 3.
3. If the spec file already exists and they already approved it in this conversation and readers are already confirmed: Procedure 5.

Procedure 3: Docs readers (persona gate)

1. Load docs. Run Phase 1 only: who reads this, and which pages are new or changed.
2. Show the persona list in chat. Stop. That message is the turn.
3. After they confirm, drop, or add readers: Procedure 4.
4. If readers were already confirmed in this conversation: skip the wait. Procedure 4.

Procedure 4: Write spec (plan 1) and block

1. Path: docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md (today’s date, kebab topic). New file. Create parent dirs if needed.
2. Write a short design spec: what we build, choices from the grill, confirmed readers, doc-impact pages. Not a task list. Not full source.
3. Open the file. Do not git add it. Do not commit it.
4. Wait until they approve. If they want changes: edit, open, wait again.
5. Procedure 5.

Procedure 5: Map, reuse, lego

1. Load touch-map and follow it (six-section map, then it stops).
2. Load reuse-first once on the files-to-touch list. Record the reuse: line. The DAG must not invent a helper that this pass found.
3. Load lego-plan and follow it (chat DAG + .agent/scratch/lego-plan.json).
4. Procedure 6.

Procedure 6: Implementation plan (plan 2) and block

1. Announce that writing-plans is in use, with node grain (not 2-minute steps).
2. Load Superpowers writing-plans for header and file path only.
3. Path: docs/superpowers/plans/YYYY-MM-DD-<topic>.md. New file.
4. Tasks are the lego nodes. Each task has id, name, depends, files, parts, done-when. Embed the Mermaid DAG (same ids). Point at .agent/scratch/lego-plan.json. No full production source. Do not ask which execution mode. This skill is the driver.
5. Open the file. Do not commit it.
6. Wait until they approve. If they want changes: edit the plan and the live board together (keep ids stable). Open. Wait again.
7. Procedure 7.

Procedure 7: Tone, then implement

1. If any node files include docs pages, and tone is not already chosen in this conversation: one tone gate from docs. Stop. Then continue.
2. If no docs pages: skip tone.
3. Ready layer = every pending node whose depends are all done (empty depends = ready).
4. Set those nodes to in-progress in .agent/scratch/lego-plan.json. Paint the live DAG (see above). Then spawn.
5. Spawn one subagent per in-progress node, in parallel. Each prompt must include:
   • node id, name, files, ordered parts, done-when
   • the spec path and the relevant spec facts
   • confirmed readers and tone (if that node writes docs)
   • Load these skills and follow them: typescript-standards, test-hygiene, reuse-first, docs
   • do not edit paths outside files
   • do not re-plan, do not grill, do not re-ask persona or tone
   • do not paint the live DAG (the driver paints)
6. When a subagent returns, the main agent does this before any other user-facing text: run that node’s done when; set done or red; update the JSON; Paint the live DAG. Then spawn the next layer only if this layer is all done. Do not hold the paint until the layer or the run ends.
7. If done when is red or the subagent errors: keep other in-progress nodes running. Paint with :::failed on that node. Load fix-bug for that node (driver or a subagent with the same file list). Do not start the next layer until every node in this layer is done, or the user stops the run.
8. Repeat from step 3 until every node is done.
9. Procedure 8.

Procedure 8: Optional prove-it

1. Ask once: load prove-it, or skip. Default skip.
2. Wait.
3. If skip: say the feature is not proved as a user path. Procedure 9.
4. If they pick it, or already asked to prove in this conversation: load prove-it and follow it. Then Procedure 9.

Procedure 9: Stop

Stop. Do not start unrelated work.

Decision Tree

• Failure already in play → Procedure 1 (stop, fix-bug).
• /build-feature or implement a feature → Procedure 2 → … → 9.
• Design already settled → skip grill-me (Procedure 2 step 1).
• Readers already confirmed → skip persona wait.
• Spec already approved in this conversation → skip plan-1 wait.
• No docs pages in the DAG → skip tone.
• Layer has 2+ ready nodes → parallel (Hard gate 5).
• Subagent returned → Procedure 7 step 6 (paint first).
• Node red → fix-bug; rest of layer continues. Paint :::failed.
• All nodes done → Procedure 8.

Red Flags

Error Handling

• grill-me missing: interview in the same shape (one question at a time, recommended option first). Say the skill file was not found.
• writing-plans missing: still write plan 2 at the Superpowers plan path with the node contract. Say the skill file was not found.
• docs missing: stop. Do not skip docs. Tell the user.
• Cannot spawn parallel subagents: run the ready layer one node at a time. Say that in chat. Keep the same prompts and skills.
• User rejects spec or plan: edit, open, wait. Do not start the next procedure.
• User stops the run mid-layer: stop dispatch. Leave the live board as it is. Do not mark skipped nodes done.
• prove-it missing: say so. Offer skip. Do not invent a second prove procedure.
• They pick prove-it, then skip inside it: not proved. Procedure 9.
• Paint omitted from a completion message: emit the painted DAG immediately. Do not start the next layer until that fence is in chat.
• Harness wakes once for several finished workers: update every returned node, then paint once. Do not skip because the wake was a batch.