@nklisch/pi-agile-workflow 0.15.3

package/skills/epicize/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: epicize
+description: >
+  Decompose foundation docs into multiple epics seeded in .work/active/epics/ with declared
+  dependencies. Reads VISION.md, SPEC.md, ARCHITECTURE.md, identifies capability arcs, proposes an
+  epic decomposition with depends_on chains, and writes the epic files at stage:drafting after user
+  confirmation. Use after /agile-workflow:convert on a greenfield project, or any time foundation docs
+  need epic decomposition. User-invocable only — interactive workshop.
+---
+
+# Epicize
+
+You read the project's foundation docs and produce **multiple epics** at
+`.work/active/epics/`, each at `stage: drafting`, with declared `depends_on` chains
+where one epic's output feeds another.
+
+Epics are containment shapes — multi-feature architectural arcs. Each epic eventually
+gets designed (via the design family on its child features) and implemented. Epicize
+just establishes the top-level decomposition.
+
+## Prerequisites
+
+- Substrate bootstrapped (`.work/CONVENTIONS.md` exists). If not, halt and tell the
+  user to run `/agile-workflow:convert` first.
+- Foundation docs exist in `docs/`. At minimum `docs/VISION.md` AND
+  `docs/ARCHITECTURE.md` (or equivalents). If missing, halt and tell the user to run
+  `/agile-workflow:ideate` first.
+
+## Think like an agent
+
+Before decomposing anything, think about what an agent (in autopilot or manual
+mode) would need to execute each epic:
+
+- **What can be built in one design + implement cycle?** A child feature under
+  the epic should fit comfortably in one `/agile-workflow:feature-design` →
+  `/agile-workflow:implement` pass — 5-15 implementation units. If a single
+  child feature would need more, the epic is too coarse; split.
+- **What can be parallelized?** If two children of an epic don't share types or
+  files, declare them with no `depends_on` between them. The autopilot fans
+  them out as parallel agents.
+- **What's needed before starting?** Dependencies aren't just code — research
+  needs (unfamiliar libraries, APIs you don't know cold), seed data,
+  configuration. If an epic uses a library no one has touched yet, plan for a
+  research pass on the first child.
+- **How do you know an epic is done?** Not "it looks right" — every child
+  feature reaches `stage: done`. Stage transitions are the agent-readable
+  completion signal.
+- **What design artifact feeds implementation?** Each child feature's body
+  accumulates the design when `/agile-workflow:feature-design` (or
+  refactor-design / perf-design) runs on it. The epic's body is a brief, not a
+  design — `/agile-workflow:epic-design` later writes the realized
+  decomposition into it.
+
+## Anti-patterns
+
+- **Don't produce a phase plan.** Epics are containment shapes, not temporal
+  slots. No "Phase 1: Auth, Phase 2: Profiles, Phase 3: Admin." Use the
+  dependency graph; let the autopilot pick what's ready.
+- **Don't split by layer.** Epic-DB / Epic-API / Epic-UI is anti-pattern unless
+  the layers are genuinely independent products. Split by capability instead:
+  "core search works" / "results link to the right app" / "users can see it in
+  a browser."
+- **Don't pad with refactor or test epics.** Refactoring happens incrementally
+  via `/agile-workflow:refactor-design` on tagged features. Testing happens
+  through gate-tests at release time and per-feature acceptance criteria. Don't
+  manufacture epics for either.
+- **Don't estimate.** No "this epic is bigger than that one" sizing labels. The
+  agent doesn't benefit from difficulty ratings; the work either fits in 5-15
+  child-feature units or it should be split further.
+- **Don't pre-bind to releases.** Epics get `release_binding: null`. Binding
+  happens only when `/agile-workflow:release-deploy` runs.
+- **Don't include deployment as an epic** unless deployment infrastructure is
+  the core value of the project.
+
+## Workflow
+
+### Phase 1: Read foundation
+
+Read every foundation doc the project has:
+- `docs/VISION.md`
+- `docs/SPEC.md`
+- `docs/ARCHITECTURE.md`
+- `docs/PRINCIPLES.md` (if exists)
+- Domain-specific docs (UX, CONTRACT, GAMEPLAY, DATA-SPEC, etc.)
+
+Build a mental model of the system as foundation describes it.
+
+### Phase 2: Identify capability arcs
+
+Look for natural decomposition seams. Signals:
+- ARCHITECTURE.md describes distinct components or boundaries — each is a candidate
+  epic
+- VISION.md identifies multiple capability areas — each is a candidate epic
+- SPEC.md groups requirements by domain — each group is a candidate epic
+- Sequencing implied by the docs (foundation systems before consumers, contracts
+  before clients, etc.) — these become `depends_on` chains
+
+Aim for 3-8 epics for a typical project. Fewer than 3 means you should consider whether
+this project even needs epic-level decomposition (maybe just go straight to features).
+More than 8 means you're slicing too thin — collapse some.
+
+### Phase 3: Propose dependencies
+
+For each epic candidate, identify what must be done first:
+- "Auth epic must be at done before User-Profile epic can start" → User-Profile
+  `depends_on: [epic-auth]`
+- Independent epics (no shared types, no cross-cutting concerns) have no dependencies
+  and can be worked in parallel
+
+### Phase 4: Confirm with user
+
+Present the proposed decomposition via structured question tool or conversational summary:
+
+```
+Proposed epic decomposition (4 epics):
+
+1. epic-substrate-foundation
+   depends_on: []
+   covers: foundation work that everything else builds on
+
+2. epic-auth
+   depends_on: [epic-substrate-foundation]
+   covers: authentication and session management
+
+3. epic-user-profile
+   depends_on: [epic-auth]
+   covers: profile CRUD, avatar handling, settings
+
+4. epic-admin-dashboard
+   depends_on: [epic-auth]
+   covers: admin-only views, user management
+```
+
+Iterate with the user — they may collapse, split, rename, or reorder epics. Confirm
+each rename and dependency edge before writing.
+
+### Phase 5: Write epic files
+
+For each confirmed epic, write `.work/active/epics/<id>.md`:
+
+```yaml
+---
+id: epic-<slug>
+kind: epic
+stage: drafting
+tags: [<tag>, ...]   # if a clear category from foundation docs
+parent: null
+depends_on: [<epic-id>, ...]
+release_binding: null
+gate_origin: null
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# <Epic Name>
+
+## Brief
+<two to four paragraphs: what this epic delivers, what capability area it covers,
+why it exists, what it does NOT cover>
+
+## Foundation references
+- `docs/VISION.md` — relevant section(s)
+- `docs/ARCHITECTURE.md` — relevant component(s)
+- (other foundation docs as relevant)
+
+## Anticipated child features
+<NOT a commitment — a sketch of where features will likely live under this epic.
+The actual feature decomposition happens at design time, not now. Keep this short
+and provisional.>
+
+<!-- The design pass on each child feature will fill in real specifics. -->
+```
+
+### Phase 6: Cycle check
+
+Run `.work/bin/work-view --blocking <id> --paths` for each epic against its
+`depends_on`. If any cycle exists, surface it and ask the user to break it before
+committing.
+
+### Phase 7: Commit
+
+```bash
+git add .work/active/epics/
+git commit -m "epicize: <N> epics seeded from foundation docs"
+```
+
+## Output
+
+In conversation:
+- **Seeded**: list of `<id>` per epic with `depends_on` per epic
+- **Suggested next step**: pick one epic to start with —
+  start an autopilot goal for `<epic-id>` for autonomous execution, or scope a
+  feature under one of the epics manually for guided exploration
+
+## Guardrails
+
+- Epics produced here are at `stage: drafting`. Their bodies are briefs and
+  references — NOT designs. Design happens at the feature level under each epic, not
+  at the epic level.
+- Anticipated child features are provisional, not commitments. Don't pre-create child
+  feature files at epicize time — that's `/agile-workflow:scope` (manual) or
+  `/agile-workflow:epic-design` (often autopilot-driven) when the epic is ready to be
+  decomposed into real feature files.
+- Don't pre-bind epics to releases. `release_binding` stays `null` until
+  `/agile-workflow:release-deploy` runs.
+- Don't infer `depends_on` purely from docs without confirming with the user.
+  Doc ordering doesn't always mean execution dependency.
+- If the foundation docs don't have enough content to identify capability arcs,
+  halt and tell the user to run `/agile-workflow:ideate` to flesh out
+  ARCHITECTURE.md before epicizing.

package/skills/epicize/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Epicize"
+  short_description: "Use Epicize for repo workflows"
+  default_prompt: "Use $epicize for this repository."
+policy:
+  allow_implicit_invocation: false

package/skills/feature-design/SKILL.md

@@ -0,0 +1,472 @@
+---
+name: feature-design
+description: >
+  ALWAYS invoke when the user asks to design or flesh out a feature at stage:drafting; do not write
+  design prose inline. Designs the feature inside its agile-workflow item body, grounded in foundation
+  docs and code, then spawns child stories with depends_on chains and advances drafting to
+  implementing. Use for greenfield features without [refactor], [perf], [prose], or [research] tags;
+  route [refactor] to refactor-design, [perf] to perf-design, [prose] to prose-author, [research] to
+  the agentic-research research-orchestrator, and epic decomposition to epic-design. UI/UX mockups are
+  fallback here, inherited from the parent epic when available.
+---
+
+# Feature-Design
+
+You design a feature in the agile-workflow substrate. The design lives in the
+feature item's body — there is no separate `docs/designs/<name>.md`. As the design
+takes shape, child stories are spawned with declared `depends_on` chains. When the
+design is done, you advance the feature's stage `drafting → implementing`.
+
+This skill is the feature-level entry point in the design family. The family
+routes by item kind and tags:
+- `epic-design` — `kind: epic` at `stage: drafting` (decomposes into features; an epic
+  carrying `[research]` is a research-program epic — routes here as normal decomposition,
+  whose children are `[research]` features each with their own `research_dials:` registration;
+  the tag at epic level signals program decomposition, never an epic-level registration)
+- `feature-design` (this skill) — `kind: feature`, no specialized tag
+- `refactor-design` — `kind: feature` with `tags: [refactor]`
+- `perf-design` — `kind: feature` with `tags: [perf]`
+- `prose-author` — `kind: feature` with `tags: [prose]` (no-code-surface work —
+  the authoring lane, not a design step: brief-as-design, no Explore / pre-mortem / question gate)
+- `agentic-research:research-orchestrator` (**cross-plugin**) — `kind: feature` with
+  `tags: [research]`. A grounded research engagement is an *input* that grounds other work,
+  not a code design: the orchestrator reads the item's `research_dials:` block (the
+  commissioning subset of the registration) and runs the ARD walk; gates run inline; it
+  never binds to a release. Requires the
+  `agentic-research` plugin (without it, `[research]` is an inert project tag — fall through
+  to `feature-design`).
+
+The cross-plugin target `agentic-research:research-orchestrator` is a fixed pairing contract;
+a deployment substituting a different research entry skill edits these routing rows.
+
+If the feature you're looking at has `[refactor]`, `[perf]`, `[prose]`, or `[research]`
+in `tags`, you were misrouted. Don't try to design it — log a one-line note to the item
+body ("Misrouted to feature-design; should have gone to refactor-design / perf-design /
+prose-author / the agentic-research research-orchestrator based on tags") and return without advancing the
+stage. The caller (autopilot or human) will route correctly on the next pass.
+
+## Trigger
+
+Auto-triggers when the agent identifies a feature at `stage: drafting` ready for
+design, with no specialized tag. Common phrases:
+- "design feature X"
+- "let's design this feature"
+- "this feature is ready to design"
+
+## Invocation modes
+
+The skill accepts an optional `--only-questions` flag and an optional target.
+
+| Invocation | Behavior |
+|---|---|
+| `<feature-id>` (default) | Full design pass on one feature — workflow Phases 1-9. |
+| `<feature-id> --only-questions` | Question-only pass on one feature — runs the read/ground phases, surfaces ambiguities, asks the user, captures answers in the body, does NOT design or advance stage. |
+| `--only-questions <id1> <id2> ...` | Question-only pass over each listed feature, in order. |
+| `--only-questions --all` | Question-only pass over every `kind: feature` at `stage: drafting` in `.work/active/features/` whose `tags` does not contain `refactor`, `perf`, `prose`, or `research`. Iterate in dependency order (features with fewer unresolved upstream deps first). |
+
+`--only-questions` mode exists so a user can align with the agent on
+high-level direction across many drafting features in one session, then
+hand off to an autopilot goal for the full design + implement pass. Autopilot
+inherits the captured answers from each feature body and no longer has to use
+judgment on those points.
+
+`--only-questions` requires interactive mode — if an active autopilot run or
+harness goal is driving this session, refuse to run and report that the flag is
+for interactive alignment only.
+Do not run cross-model advisory review in `--only-questions` mode — the user is
+the alignment signal.
+
+## Workflow — `--only-questions` mode
+
+Use this path when invoked with `--only-questions`. Iterate over the
+target set (one feature, an explicit list, or every drafting feature
+under `--all` per the table above).
+
+For each feature in the target set:
+
+1. **Read the feature item** at `.work/active/features/<id>.md`.
+   - Skip if `kind` is not `feature`, if `stage` is not `drafting`, or if
+     `tags` contains `refactor`, `perf`, `prose`, or `research`. Log the skip and move on.
+2. **Ground yourself** — read the parent epic body if `parent` is set, plus
+   the foundation docs (`docs/VISION.md`, `docs/SPEC.md`,
+   `docs/ARCHITECTURE.md`) and `AGENTS.md` / `CLAUDE.md`. Treat AGENTS as
+   canonical when both exist. Be efficient: skim, don't exhaustively re-read
+   across iterations within one session.
+3. **Map the codebase lightly** — start with direct Read/Glob/Grep over the
+   obvious area. Use one exploratory sub-agent only if local reading
+   leaves a real unknown; skip the full three-agent parallel sweep used in
+   the default mode because you're not designing units.
+4. **Run Phase 4.6 (UI surface fallback)** when `ux-ui-design` is installed
+   — same rules as default mode (inheritance check, mock only when
+   upstream coverage is missing). Most ask-questions runs find the parent
+   epic already mocked and skip here.
+5. **Surface ambiguities** — run Phase 4.5 as written above, but always in
+   the interactive branch (use `structured question tool`). Do not resolve with
+   judgment — the whole point of this mode is to capture user answers.
+6. **Capture answers** — append (or merge into existing) `## Design
+   decisions` in the feature body:
+   ```markdown
+   ## Design decisions
+   - **<question>**: <choice> — <one-line rationale>
+   ```
+   If the section already exists, merge — don't duplicate previously
+   answered questions, and don't overwrite prior answers without flagging
+   the conflict to the user.
+7. **Do NOT** spawn child stories, write the design body, or advance the
+   stage. The feature stays at `stage: drafting` so the design family can
+   pick it up later.
+8. **Commit per feature**:
+   ```bash
+   git add .work/active/features/<id>.md
+   git commit -m "feature-design --only-questions: <id>"
+   ```
+
+### Output (`--only-questions` mode)
+
+In conversation, after the run:
+- **Aligned**: list of feature ids and the count of design decisions
+  captured per feature
+- **Skipped**: list of feature ids and reason (wrong stage, wrong tag, no
+  ambiguities found)
+- **Next**: features stay at `stage: drafting` — start an autopilot goal for
+  `<epic-id>` or `--all`, or use direct `/agile-workflow:autopilot <scope>`.
+  The design pass on each feature will inherit the captured answers.
+
+## Workflow
+
+### Phase 1: Read the feature item
+
+Read the feature file at `.work/active/features/<id>.md`. Confirm:
+- `kind: feature`
+- `stage: drafting`
+- `tags` does NOT include `refactor`, `perf`, `prose`, or `research` (otherwise log a
+  misroute note and return without advancing — see the description block above)
+
+The body should already have a brief from `scope`. Use it as the seed for design.
+
+### Phase 2: Ground yourself
+
+The principles skill auto-loads — both code-design (Ports & Adapters, SSOT,
+Generated Contracts, Fail Fast) and substrate-execution (Item-IS-the-Work,
+Rolling-Foundation, Late-Binding) are active.
+
+Read:
+1. `docs/VISION.md`, `docs/SPEC.md`, `docs/ARCHITECTURE.md` (foundation docs that
+   constrain this feature)
+2. `AGENTS.md` / `CLAUDE.md` (project conventions; AGENTS is canonical)
+2a. `.agents/rules/*.md` (if present) — the project's force-loaded agent rules
+   (tag semantics, test integrity, review policy)
+3. The parent epic if `parent` is set — read `.work/active/epics/<parent>.md`
+4. Existing source code in the area the feature touches
+5. Research docs in `docs/research/` if the feature uses libraries you haven't
+   verified
+
+### Phase 3: Map the codebase
+
+Run a read-first scope-size probe before spawning exploratory sub-agents:
+
+1. Use Glob/`rg --files` to identify likely directories, entry points, and
+   existing tests.
+2. Use Grep/`rg` for feature terms, route names, exported types, and nearby
+   helpers.
+3. Read 2-5 representative source/test files yourself.
+
+Then choose the dispatch size:
+
+- **Small/bounded feature** — known module or a few obvious files: skip exploratory fanout
+  and use direct reading.
+- **Medium/unclear feature** — one area but uncertain patterns: spawn one
+  read-only exploratory sub-agent with a combined brief.
+- **Broad/cross-cutting feature** — distinct structure, interface, and test
+  questions across separate areas: spawn parallel read-only exploratory sub-agents.
+
+For exploratory fanout:
+- Use the host's generic/general-purpose subagent prompted with the explorer capsule from `../principles/references/subagents.md`, at medium reasoning by default.
+- Use high or strongest reviewer reasoning for large or complex codebases.
+- If no generic subagent adapter is available, keep the bounded mapping in the host session.
+
+Possible prompts:
+1. **Codebase Structure** — directory layout, modules, entry points, exports
+2. **Interface & Type Inventory** — exported interfaces, types, signatures with file paths
+3. **Test Structure** — test patterns, helpers, fixtures, organization
+
+After direct reading or Explore results, **read 2-3 key source files yourself**
+to verify findings.
+
+### Phase 4: Re-align to project standards
+
+Re-read `AGENTS.md` and `CLAUDE.md` if present at root, `.agents/`, or
+`.claude/`, plus `.agents/rules/*.md` (if present) — the project's force-loaded
+agent rules (tag semantics, test integrity, review policy). Treat AGENTS as
+canonical if they disagree. Recency improves adherence. Confirm your approach
+aligns with project conventions.
+
+### Phase 4.5: Surface ambiguities
+
+Read the feature brief and the design space you've started to map, and
+derive specific, concrete design questions about *this* feature's actual
+work — requirements gaps, architecture trade-offs, scope boundaries,
+integration assumptions, UX decisions. The questions must come from the
+feature in front of you; examples of the *shape* only:
+
+- "Should the cache invalidate on write or rely on TTL only?"
+- "Does the upload accept multipart, or a presigned URL flow?"
+- "When the parser hits a malformed row, do we skip and continue or fail
+  the whole batch?"
+- "Is paging cursor-based or offset-based?"
+
+Skip anything the brief, parent epic body, foundation docs, or codebase
+already pin. Skip anything that's safely an implementation-time call.
+
+Aim for the smallest set of questions that meaningfully resolve direction
+— typically 2-5. Zero is fine if everything's already pinned.
+
+**Cross-model advisory review under autopilot.** If this skill is running as a
+delegation from active autopilot, the feature has large/risky architectural
+decisions, and the body does not already contain useful `## Design decisions`
+from a prior `--only-questions` pass, apply the cross-model advisory review
+policy from `principles/SKILL.md` before resolving the questions yourself.
+
+Use one focused `peer` pass only when a different model class is available.
+Ask for missing questions, risks, ambiguous constraints, and alternatives for
+this feature's design — not for a final verdict. Do not run the multi-pass
+`peer-review` loop during routine autopilot design. If peeragent is
+unavailable, the peer would use the same model class, or the invocation fails,
+continue with host judgment and note that the advisory pass was skipped.
+If the peeragent target is Claude Opus, allow 10 to 30 minutes for a large
+review; no return after a few minutes is not evidence that it has hung.
+
+Summarize the useful output under `## Other agent review` in the feature body
+and fold accepted questions/risks into the decisions you log. Do not paste the
+peer transcript into the item.
+
+If this skill is running **as a delegation from an active autopilot run or
+harness goal**, resolve each question with judgment (prioritize: consistent
+with foundation docs > simpler option > defers irreversible decisions) and log
+under `## Design decisions` in the body:
+
+```markdown
+## Design decisions
+- **<question>**: <choice> — <one-line rationale>
+```
+
+If the body already contains a `## Design decisions` section (from a prior
+`--only-questions` pass or from `epic-design` Phase 4.7), treat those
+locked-in answers as inputs — do NOT re-ask them.
+
+In every other invocation — including direct user invocation under harness
+auto mode (`permissions.defaultMode: "auto"`) — ask the user via
+`structured question tool` before locking in. Harness-level "work without pausing"
+reminders do **not** suppress these checkpoints. See `principles/SKILL.md`
+Part III for the full caller-awareness rule.
+
+The exception under autopilot: a 50/50 between two large irreversible choices
+(e.g., SQL vs document store). Append a `## Blocker` section and return
+without advancing — autopilot will skip and surface the blocker.
+
+### Phase 4.6: UI surface fallback (runs when ux-ui-design is installed)
+
+This is the **fallback** mockup tier per `ux-ui-principles`. Epic-design
+Phase 4.6 is primary; this phase exists to catch surfaces it didn't cover.
+
+**Inheritance check first.** Read the parent epic body for a `## Mockups`
+section and check `.mockups/screens/<this-feature-id>/` and
+`.mockups/flows/` for existing mocks. If coverage exists, copy those paths
+into this feature's `## Mockups` section and **skip the rest of this
+phase**. Do not re-mock.
+
+**Fallback only when upstream coverage is missing** — i.e. there's no
+parent epic, the epic body shows a `## UI alignment deferred` note, OR a
+genuinely-new surface emerged after epic-design ran. Then:
+
+- **Net-new screen** → `/ux-ui-design:screens <feature-id>`.
+- **Multi-screen flow tighter than the feature** → `/ux-ui-design:flows
+  <flow-name>` (rare).
+- **Minor composition reusing existing patterns** → skip; note the
+  feature inherits from `<epic-id>`'s mocks.
+- **No UI surface** → skip.
+
+If prominent UI surface is missing both coverage AND a deferred note, the
+epic-design tier should have caught it. Proceed with the fallback mock
+and flag the discrepancy in the run output.
+
+Skip this phase entirely if `ux-ui-design` is not installed.
+
+### Phase 5: Design the units
+
+The substantive phase. Don't rush.
+
+#### 5a. Architectural options
+
+Name 2-3 plausible high-level approaches:
+- One-paragraph description each
+- Key tradeoff (what it optimizes for, what it sacrifices)
+- Why it might or might not fit this project
+
+Choose one explicitly. State why over the others.
+
+#### 5b. Trickiest unit first
+
+Among the units you'll design, name the one with highest unknowns or most novel
+logic. Design it first and most carefully — the rest hangs on whether this is feasible.
+
+#### 5c. Design each unit
+
+For each unit, specify:
+- **Exact file path** (e.g., `src/domain/user.ts`, not "the user file")
+- **Code showing interfaces, types, and function signatures** in the project's language
+- **Implementation notes** for non-obvious logic
+- **Acceptance criteria** as testable assertions
+
+Make strong decisions about abstractions, naming, and module boundaries.
+
+### Phase 5.5: Pre-mortem
+
+Before finalizing, attack the design:
+- What's the riskiest assumption?
+- What would have to be true for this to fail in production?
+- What's the fallback if the riskiest unit doesn't work?
+- Where am I least sure?
+
+If a serious risk surfaces, revise the design or add a spike unit that validates the
+risky assumption first. Document discovered risks in a `## Risks` section in the
+feature body.
+
+### Phase 6: Test approach
+
+For each unit, design:
+- **Unit tests** — behaviors to verify, edge cases, error paths
+- **Integration points** — where does this unit meet other units; what tests prove the seams
+- **Test data** — fixtures, factories, seed data needed
+
+If a unit is hard to test, the design is probably wrong. Note it and revise.
+
+### Phase 7: Order and child stories
+
+Specify implementation order — what must exist before what. Decide whether to
+spawn child stories or treat the feature itself as the single implementation
+unit.
+
+#### When to spawn stories
+
+Stories pay for themselves when **at least one** of these is true:
+
+- **Parallelizable.** Three or more chunks can be implemented by independent
+  agents simultaneously — `/agile-workflow:implement-orchestrator` wants
+  stories so it has fan-out targets.
+- **Non-trivial dependencies.** Story A blocks B blocks C; declaring
+  `depends_on:` at the story level makes the chain visible without reading
+  the full design body.
+- **Multi-session work.** A feature that won't fit in one stride needs
+  resume points. A story file gives a fresh agent a smaller surface to
+  absorb than the entire feature design.
+- **Heterogeneous acceptance.** Different chunks have different test
+  surfaces (UI works / IPC errors / DB schema). Gates score per-story
+  rather than per-feature, which is cleaner when the surfaces are genuinely
+  different.
+
+#### When stories are pure overhead
+
+Skip stories when **all** of these hold:
+
+- Retroactive capture of already-done work (stories are forward-looking
+  containers; if the work is already done, just land it under the feature)
+- Single-stride implementation (one session can finish the whole feature)
+- Tight cohesion (every test exercises every code path; the chunks aren't
+  meaningfully independent)
+- The natural decomposition is just "frontend / backend" — that's the
+  package boundary, not stories
+
+#### Spawning a story
+
+For each child story to spawn:
+- Create `.work/active/stories/<feature-id>-<story-slug>.md`
+- Frontmatter: `kind: story`, `stage: implementing`, `parent: <feature-id>`,
+  `depends_on: [...]` (declare which sibling stories must finish first)
+- Body: scope of this story, the unit(s) it implements, acceptance criteria
+
+Cycle check: run `.work/bin/work-view --blocking <story-id>` before adding any
+`depends_on` entry.
+
+### Phase 8: Write design INTO the feature body
+
+Update the feature file. Append (after the existing brief) sections like:
+
+```markdown
+## Architectural choice
+<chosen approach + rationale>
+
+## Implementation Units
+
+### Unit N: <name>
+**File**: `src/path/to/file.ext`
+**Story**: `<story-id>` (if spawned as a separate story)
+
+\`\`\`<lang>
+// Exact interfaces, types, signatures
+\`\`\`
+
+**Implementation Notes**:
+- <key detail>
+
+**Acceptance Criteria**:
+- [ ] <testable assertion>
+
+---
+
+## Implementation Order
+1. <unit / story>
+2. <unit / story>
+
+## Testing
+### Unit Tests: `tests/path/<name>.test.ext`
+<test approach for each unit>
+
+## Risks
+<from pre-mortem, if any>
+```
+
+### Phase 9: Advance stage and commit
+
+1. Edit the feature file's frontmatter: `stage: drafting → implementing`. The
+   PostToolUse hook auto-bumps `updated:`.
+2. Commit:
+   ```bash
+   git add .work/active/features/<id>.md .work/active/stories/<feature-id>-*.md
+   git commit -m "feature-design: <feature-id> (<N> child stories)"
+   ```
+
+## Output (default mode)
+
+(For `--only-questions` mode output, see the section above.)
+
+In conversation:
+- **Designed**: `<feature-id>` advanced to `stage: implementing`
+- **Child stories**: list with `depends_on` chains
+- **Implementation order**: 1, 2, 3, ...
+- **Risks flagged**: list (or "none")
+- **Next**: `/agile-workflow:implement <story-id>` for sequential, or
+  `/agile-workflow:implement-orchestrator <feature-id>` for parallel agents over
+  the dependency graph
+
+## Guardrails
+
+- The design lives in the feature's body. NEVER create `docs/designs/<name>.md` —
+  that's a workflow-plugin pattern; agile-workflow uses item-IS-the-work.
+- **UI/UX mockups are FALLBACK here.** Check the parent epic body for
+  `## Mockups` first; reference and skip. Only mock at this tier for
+  genuinely-new surfaces the parent epic didn't cover, and flag the
+  upstream gap rather than silently back-filling.
+- Specify types and signatures EXACTLY. Vague descriptions become guesses during
+  implementation, and guesses become bugs.
+- Design error handling explicitly. Undesigned error paths are the #1 source of
+  production surprises.
+- Build on existing patterns in the codebase — consistency reduces cognitive load.
+- Cycle prevention is mandatory for `depends_on`. Use `work-view --blocking`.
+- Don't pre-populate stage on child stories beyond `implementing`. Stage advances
+  through actual work, not at design time.
+- `--only-questions` mode never advances stage, never spawns stories, and never
+  writes design content beyond the `## Design decisions` section. If you find
+  yourself doing any of those, you're in the wrong mode.
+- `--only-questions` is interactive-only — refuse to run when an active
+  autopilot run or harness goal is driving the session.