@nklisch/pi-agile-workflow 0.15.3

package/skills/e2e-test-design/references/test-taxonomy.md

@@ -0,0 +1,211 @@
+# Test Taxonomy
+
+The four test styles `e2e-test-design` covers, with when-to-apply rules,
+structural patterns, examples, and anti-patterns. Reference from SKILL.md
+Phase 5b.
+
+## 1. Golden-path tests
+
+**What:** Realistic, successful user journeys exercised end-to-end against
+the containerized product.
+
+**When to apply:** Always. Every project has golden paths. If you can't name
+3-5 critical journeys, the project's purpose is unclear and that's a prior
+problem.
+
+**Structural pattern:**
+
+```
+Test: <user-intent name>
+Setup: docker-compose stack up; seed data via fixtures
+Journey: step-by-step what the user does (real CLI commands, HTTP requests,
+         UI actions)
+Invariant: <one-line user-visible outcome that must hold>
+Assertions: outputs, files created, DB rows, side effects — all user-visible
+Teardown: stack down; volumes wiped
+```
+
+**Example (HTTP API):**
+
+```
+Test: User registers, logs in, creates a project, sees it in their dashboard
+Invariant: After registration → login → POST /projects → GET /dashboard,
+           the new project ID appears in the dashboard response
+Setup: stack up (postgres + redis + smtp4dev); seed empty
+Steps: POST /register → POST /login → POST /projects → GET /dashboard
+Assertions: 201 from register, 200 from login (cookie set), 201 from projects
+           with new id, 200 from dashboard listing the new id
+```
+
+**Categories to cover:**
+- First-use / happy path (install/start → first successful operation)
+- Core workflows (the 3-5 things users do most)
+- Configuration variations (different valid configs)
+- Multi-step workflows (operations that build on each other)
+
+**Anti-patterns:**
+- Asserting on internal state instead of user-visible output
+- Skipping the docker-compose stack and using in-memory substitutes
+- Testing one endpoint at a time rather than a journey
+
+## 2. Failure-mode tests
+
+**What:** Verify the product fails gracefully under predictable wrong
+conditions — invalid input, missing config, unavailable deps, boundary
+values, permission errors, interrupted operations.
+
+**When to apply:** Always. Failure handling is where most production bugs
+hide. Skipping failure-mode tests means shipping a product that's fragile in
+exactly the way users will hit first.
+
+**Structural pattern:**
+
+```
+Test: <what goes wrong>
+Setup: stack up; configure the failure condition (e.g., invalid input,
+       killed dep)
+Action: user-equivalent operation
+Invariant: <one-line: how the product should respond>
+Assertions: error message format, exit code, HTTP status, NO corrupted state
+Teardown: stack down; verify cleanup happened
+```
+
+**Categories to cover:**
+
+User mistakes:
+- Invalid input (wrong types, out-of-range, malformed)
+- Missing required args/config
+- Wrong order of operations (e.g., login before register)
+- Permission issues
+- Conflicting flags
+
+Bad environment:
+- Missing dependencies (kill a container before the test)
+- Network failures (via Toxiproxy)
+- Disk full (mount a tiny tmpfs)
+- Missing/corrupted config files
+
+Boundary:
+- Empty input
+- Extremely large input
+- Special characters
+- Interrupted operations (SIGINT mid-operation)
+
+**Example (DB unavailable):**
+
+```
+Test: API returns 503 with retry hint when DB is unreachable
+Setup: stack up; then `docker compose stop postgres`
+Action: POST /projects
+Invariant: User sees 503 with a Retry-After header; no half-written rows
+Assertions: status==503, Retry-After present, no orphan rows after Postgres
+            comes back
+```
+
+**Anti-patterns:**
+- Asserting *that* an error occurred without asserting *what* the error said
+- Mocking the dep instead of actually stopping it
+- Skipping the state-corruption check (real value of these tests)
+
+## 3. Chaos tests
+
+**What:** Verify graceful degradation, retry behavior, and recovery under
+random failures injected into the running stack.
+
+**When to apply:** When the system has retry / fallback / graceful-degrade /
+circuit-breaker / failover behaviors. **If the system has none of those,
+chaos tests have nothing to verify.** Don't add chaos tests just to have
+them — fix the missing resilience features first, or skip this layer.
+
+**Common injection patterns:**
+
+| Failure | Tool |
+|---|---|
+| Network latency | Toxiproxy (`latency` toxic) |
+| Connection drop | Toxiproxy (`down` toxic), `docker compose pause` |
+| Packet loss | Toxiproxy (`limit_data`, `bandwidth` toxics) |
+| Container kill | Pumba (`pumba kill`) |
+| Container pause | Pumba (`pumba pause`) |
+| Clock skew | libfaketime (`LD_PRELOAD`) |
+| Disk full | small tmpfs mount |
+| CPU starvation | `docker update --cpus 0.1` |
+
+**Structural pattern:**
+
+```
+Test: <golden-path journey> survives <injected failure>
+Setup: stack up; start the journey; inject failure mid-journey
+Action: continue the journey
+Invariant: <one-line: what graceful behavior must hold — retry succeeds,
+           degraded mode kicks in, error is clean, no data loss>
+Assertions: final outcome matches invariant; no corrupted state
+```
+
+**Example (retry on latency):**
+
+```
+Test: Checkout completes despite 500ms upstream latency
+Setup: stack up; Toxiproxy adds 500ms latency to the payment-gateway mock
+Action: full checkout journey
+Invariant: Checkout succeeds within the configured retry budget (3 attempts);
+           order row created; no duplicate charges
+Assertions: order exists, exactly one charge row, response time < 5s
+```
+
+**Anti-patterns:**
+- Injecting a failure with no defined behavior to verify (the test passes if
+  *anything* happens — useless)
+- Injecting at points the system was never designed to handle (testing wishes,
+  not contracts)
+- Making chaos tests non-deterministic without seeding the chaos (then
+  failures aren't reproducible)
+
+## 4. Fuzzing tests
+
+**What:** Generate inputs from a strategy and verify properties hold for all
+generated inputs. Catches edge cases human-written tests miss.
+
+**When to apply:** When the system has clear input boundaries — parsers,
+serializers, validators, query builders, codec/encoding layers,
+state-machine transition functions. Don't apply to systems whose only
+"input" is high-level user intent (no parseable contract).
+
+**Three flavors:**
+
+| Flavor | Tooling | Use when |
+|---|---|---|
+| Property-based | Hypothesis (Python), fast-check (JS/TS), proptest (Rust), QuickCheck (Haskell/Erlang) | Inputs have a generative shape; you can state a property that must hold for all inputs |
+| Mutation | AFL++, libFuzzer, Jazzer (Java) | Inputs are binary or close to it; you have a corpus of valid seeds; you want crash discovery |
+| Grammar-based | Atheris with grammar, custom generators on Hypothesis | Inputs follow a formal grammar (SQL, JSON, protocol messages) |
+
+**Structural pattern (property-based):**
+
+```
+Test: parse(serialize(x)) == x for all x of shape T
+Strategy: generate x from the shape (Hypothesis @given, fc.assert)
+Invariant: round-trip preserves identity
+Assertions: the property; shrinking reproduces minimal failing case
+```
+
+**Properties worth fuzzing:**
+- Round-trip: `decode(encode(x)) == x`
+- Idempotence: `f(f(x)) == f(x)`
+- Commutativity: `merge(a, b) == merge(b, a)`
+- Invariants: result.size >= input.size, sum(parts) == whole
+- Negative space: malformed input never produces a panic / exception leak
+
+**Example (HTTP parser round-trip):**
+
+```
+Test: parse_request(format_request(req)) == req for arbitrary valid requests
+Strategy: Hypothesis generates valid request structs (method, headers, body)
+Invariant: round-trip preserves the request semantically
+Assertions: structural equality after the round-trip
+```
+
+**Anti-patterns:**
+- Fuzzing without a property to assert (just running random inputs through
+  a function and noting it didn't crash — that's coverage theater)
+- Fuzzing with too-strict generators (every generated input is trivially
+  valid; the bugs hide in the inputs you excluded)
+- Not seeding the random source (failures aren't reproducible)

package/skills/epic-design/SKILL.md

@@ -0,0 +1,476 @@
+---
+name: epic-design
+description: >
+  ALWAYS invoke this skill when the user asks to design, decompose, or pick up an epic at
+  stage:drafting. Reads the epic, foundation docs, and codebase; identifies child feature arcs; writes
+  feature files with parent and depends_on metadata; updates the epic body with the realized
+  decomposition; and advances drafting to implementing. When ux-ui-design is installed, includes
+  mockup planning for net-new screens and journeys.
+---
+
+# Epic-Design
+
+You design an epic in the agile-workflow substrate. The decomposition lives in
+the epic item's body (replacing the provisional "Anticipated child features"
+sketch with the realized list), and child feature files are spawned at
+`.work/active/features/` with declared `depends_on` chains. When the
+decomposition is done, you advance the epic's stage `drafting → implementing`.
+
+This skill is the design-family entry point for `kind: epic`. The downstream
+feature-design family (`design`, `refactor-design`, `perf-design`) then runs
+on each child feature individually.
+
+## Trigger
+
+Auto-triggers when the agent identifies an epic at `stage: drafting` ready for
+decomposition — often inside an active autopilot goal.
+Common phrases:
+- "design epic X"
+- "decompose this epic"
+- "this epic is ready to break down"
+
+User-invocable too when the user wants to break down a specific epic without
+running full autopilot.
+
+## Invocation modes
+
+| Invocation | Behavior |
+|---|---|
+| `epic-design <id>` (default) | Full design pass on one epic — workflow Phases 1-7. |
+| `epic-design --only-questions <id>` | Question-only pass on one epic — runs read/ground phases, surfaces strategic ambiguities (Phase 4.7), captures answers under `## Design decisions`, does NOT decompose or advance stage. |
+| `epic-design --only-questions <id1> <id2> ...` | Question-only pass over each listed epic, in order. |
+| `epic-design --only-questions --all` | Question-only pass over every epic at `stage: drafting` in `.work/active/epics/`. Iterate in dependency order. |
+
+`--only-questions` mode requires interactive mode — refuse to run when an
+active autopilot run or harness goal is driving the session (matches
+feature-design's rule). When the design family runs later, captured answers are
+inherited from each epic body, so autopilot no longer has to use judgment on
+those points.
+
+## Anti-patterns
+
+These mirror `epicize`'s anti-patterns at the next level down:
+
+- **Don't produce a phase plan.** Features are containment shapes, not temporal
+  slots. Use the dependency graph; let the autopilot pick what's ready.
+- **Don't split by layer.** Feature-DB / Feature-API / Feature-UI under one
+  epic is an anti-pattern unless the layers are genuinely independent
+  deliverables. Split by capability.
+- **Don't pad with refactor or test features.** Refactoring happens incrementally
+  via `/agile-workflow:refactor-design` on tagged features when actual smells
+  surface. Don't manufacture features for either.
+- **Don't design the features.** That's the per-feature design pass. Here you
+  write a brief and declare dependencies — the feature body fills in interfaces,
+  signatures, and test approach when its own design pass runs.
+- **Don't pre-bind to releases.** Child features get `release_binding: null`.
+- **Don't pre-populate child feature stages beyond `drafting`.** Stage advances
+  through actual work.
+
+## Workflow — `--only-questions` mode
+
+Use this path when invoked with `--only-questions`. Iterate over the target set
+(one epic, an explicit list, or every drafting epic under `--all`):
+
+For each epic:
+1. Read the epic file; skip if `kind` is not `epic` or `stage` is not `drafting`
+2. Ground yourself (Phase 2 below — foundation docs + AGENTS.md / CLAUDE.md + parent if any; AGENTS is canonical)
+3. Map the codebase lightly — direct Read/Glob/Grep first; use one Task
+   Explore over the epic's area only when local reading leaves a real unknown
+4. **Run Phase 4.6 (UI surface alignment)** — `--only-questions` is the
+   visual alignment gate, not just the textual one. When `ux-ui-design` is
+   installed, run the full Phase 4.6 pass; reference resulting paths in
+   the epic body's `## Mockups` section.
+5. Run Phase 4.7 (Surface high-level design ambiguities) in the interactive
+   branch, always using `structured question tool`
+6. Capture answers under `## Design decisions` in the epic body (merge with
+   existing entries; don't overwrite without flagging)
+7. Do NOT decompose into child features or advance stage
+8. Commit per epic: `epic-design --only-questions: <id>`
+
+Requires interactive mode; refuse to run under an active autopilot run or goal.
+Do not run cross-model advisory review in this mode — the user is the alignment
+signal.
+
+## Workflow
+
+### Phase 1: Read the epic
+
+Read `.work/active/epics/<id>.md`. Confirm:
+- `kind: epic`
+- `stage: drafting`
+- No direct children yet (see Phase 1.5)
+
+Note the epic's `tags` — if `[refactor]` or `[perf]`, propagate the tag to
+child features so the right design-family skill picks them up.
+
+### Phase 1.5: Children-already-exist short-circuit
+
+Run:
+
+```bash
+.work/bin/work-view --parent <epic-id> --paths
+```
+
+If direct children already exist, the decomposition was done previously (manually
+via `scope`, or by an upstream skill like `bold-refactor`). Don't re-decompose.
+Instead:
+
+1. Verify the children form a coherent decomposition (every child has a
+   sensible `parent: <epic-id>`, no obvious capability gaps relative to the
+   brief).
+2. Append a short note to the epic body: "Decomposition pre-existed — N child
+   features, listed below."
+3. Advance epic stage `drafting → implementing` and commit.
+4. Skip Phases 2-7. Go to Output.
+
+### 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 that
+   constrains this epic
+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. `docs/PRINCIPLES.md` if it exists
+4. The epic's parent if `parent` is set (rare — epics usually top-level)
+5. Sibling epics in `.work/active/epics/` — to see what they cover and avoid
+   straddling boundaries
+6. Research docs in `docs/research/` for any libraries the epic mentions
+   that 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, active
+   sibling work, and tests.
+2. Use Grep/`rg` for epic terms, capability names, exported types, route names,
+   and shared integration points.
+3. Read 2-5 representative source, test, and sibling item files yourself.
+
+Then choose the dispatch size:
+
+- **Small/bounded epic** — one known subsystem with obvious seams: skip exploratory fanout
+  and map it directly.
+- **Medium/unclear epic** — one area but missing ownership or dependency
+  clarity: spawn one read-only exploratory sub-agent.
+- **Broad/cross-cutting epic** — several independent surfaces or sibling-work
+  interactions: 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 direct host-local mapping.
+
+Possible prompts:
+1. **Existing surface in this epic's area** — what modules, components, or
+   integration points already exist that this epic will extend or touch?
+   Report file paths and brief responsibility per finding.
+2. **Cross-cutting touchpoints** — what areas does this epic interact with
+   (auth, persistence, transport, UI shell, etc.)? Each touchpoint is a
+   candidate for a dedicated feature OR a constraint on existing features.
+3. **Already-scoped sibling work** — features and stories under sibling epics
+   in `.work/active/`. Report any overlap or shared types that imply a
+   dependency edge from this epic's children to a sibling epic.
+
+After direct reading or Explore results, **read 2-3 key source files yourself**
+to verify findings.
+
+### Phase 4: Identify feature arcs
+
+Look for natural decomposition seams within the epic:
+
+- The epic body's "Anticipated child features" sketch (if any) is your seed —
+  it's provisional, but the user wrote it for a reason. Honor the spirit, refine
+  the shape.
+- Foundation-doc sections within the epic's scope often map to features.
+- Capability arcs from the brief — "users can do X" usually maps to one feature;
+  "system supports Y constraint" might be its own feature or fold into an
+  existing one.
+- Sequencing implied by the brief or the architecture (foundation systems
+  before consumers, contracts before clients) — these become `depends_on`
+  edges.
+
+**Sizing rule (from epicize, mirrored down a level):** each child feature
+should fit comfortably in one `/agile-workflow:feature-design` →
+`/agile-workflow:implement` pass — 5-15 implementation units. If a single
+candidate feature would need more, split it. If candidates feel tiny (1-2
+units each), collapse them into one feature.
+
+Aim for 2-6 child features per epic. Fewer than 2 means the epic was probably
+sized as a feature; flag the user. More than 6 means you're slicing too thin;
+collapse.
+
+### Phase 4.5: Identify cross-feature dependencies
+
+For each candidate feature, ask:
+- What must be done first before this can be designed and implemented?
+- Does this feature share types or contracts with another candidate? If yes,
+  the producer of the type is a `depends_on`.
+- Independent features (no shared types, no cross-cutting concerns) have no
+  dependencies and can be parallelized by autopilot.
+
+Cycle check: for every candidate `depends_on` edge, verify no cycle. Once the
+child files exist (Phase 6) you'll re-check via `work-view --blocking`. For
+now, sanity-check by hand.
+
+### Phase 4.6: UI surface alignment (PRIMARY mockup tier — runs when ux-ui-design is installed)
+
+This is the primary mockup tier per `ux-ui-principles`. Run the full UI
+alignment pass against the candidate arcs from Phase 4. Err on mocking —
+`feature-design` Phase 4.6 is the fallback, not a planned second pass.
+
+1. **Palette** — if `.mockups/design-system/tokens.css` doesn't exist,
+   invoke `/ux-ui-design:palette` first so subsequent mocks inherit tokens.
+2. **Screens** — for every candidate feature with a net-new screen, page,
+   modal, or major component, invoke `/ux-ui-design:screens <feature-id>`
+   using the future child feature id (e.g. `epic-auth-login`).
+3. **Flows** — for every multi-screen journey within the epic, invoke
+   `/ux-ui-design:flows <flow-name>`.
+4. **Existing-surface composition / no UI** — skip.
+
+The `screens`/`flows` skills write a `## Mockups` section into each item
+body automatically; reference those paths from the child feature briefs in
+Phase 6 so `feature-design` inherits direction by reference.
+
+**Caller awareness.** Under autopilot delegation, the mockup skills cannot
+run (they need interactive input). Append a `## UI alignment deferred`
+note to the epic body listing the surfaces, recommend the user run
+`/agile-workflow:epic-design --only-questions <epic-id>`, and continue
+decomposition. Child briefs note "mockups pending — see parent epic" so
+`feature-design` knows to fall back. Every other invocation runs in full.
+
+Skip this phase entirely if `ux-ui-design` is not installed.
+
+### Phase 4.7: Surface high-level design ambiguities
+
+Read the epic and the candidate decomposition you've sketched, and derive
+specific, concrete high-level design questions about *this* epic's actual
+work. These are the directional choices that, if locked in now, will keep
+every child feature's later design pass aligned. Examples of the *shape* of
+question to surface (the actual content must come from the epic):
+
+- "For this epic's auth surface, do we use OAuth via the existing provider,
+  or roll a local session model?"
+- "Should the new sync engine push from server to client, pull from client
+  on-demand, or both?"
+- "Are we committing to multi-tenant data isolation in this epic, or is
+  single-tenant acceptable for v1?"
+- "Does the import pipeline need to handle CSV and Parquet, or just CSV?"
+
+These are product/architecture/scope questions specific to the epic in
+front of you — not generic prompts about boundaries, naming, or sizing.
+Skip anything you can answer from the epic body, foundation docs, or
+codebase. Skip anything that's safely a downstream feature-design call
+(function signatures, exact file paths, per-unit test approach).
+
+Aim for the smallest set of questions that meaningfully resolve direction
+— typically 2-5. Zero is fine if the epic body and foundation docs already
+pin every directional choice.
+
+**Cross-model advisory review under autopilot.** If this skill is running as a
+delegation from active autopilot, the epic 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 epic's decomposition — 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 epic 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 epic body:
+
+```markdown
+## Design decisions
+- **<question>**: <choice> — <one-line rationale>
+```
+
+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, then write the answers under `## Design
+decisions` in the epic body. Harness-level "work without pausing" reminders
+do **not** suppress these checkpoints. See `principles/SKILL.md` Part III
+for the full caller-awareness rule.
+
+The child feature briefs you write in Phase 6 should reference the relevant
+design decisions so each feature's later design pass inherits the locked-in
+direction.
+
+The exception under autopilot: a 50/50 between two large irreversible
+choices (e.g., SQL vs document store for this epic's persistence layer).
+Append a `## Blocker` section and return without advancing — autopilot will
+skip and surface the blocker.
+
+### Phase 5: Pre-mortem
+
+Before writing files, attack the decomposition:
+- What's the riskiest feature? Is it sized correctly?
+- What capability is least clearly assigned to a feature? Is there a gap?
+- Are any features so tightly coupled they should be one feature?
+- Does the dependency chain create a critical path that defeats the parallelism
+  intent?
+
+Revise the decomposition if anything surfaces. Document discovered risks in a
+`## Decomposition risks` section in the epic body.
+
+### Phase 6: Write child feature files
+
+For each child feature, create `.work/active/features/<feature-id>.md`:
+
+```yaml
+---
+id: <epic-slug>-<feature-slug>
+kind: feature
+stage: drafting
+tags: [<inherited from epic if [refactor] or [perf]>, ...]
+parent: <epic-id>
+depends_on: [<feature-id>, ...]
+release_binding: null
+gate_origin: null
+created: YYYY-MM-DD
+updated: YYYY-MM-DD
+---
+
+# <Feature Name>
+
+## Brief
+<two to three paragraphs: what this feature delivers within the epic, what
+capability it covers, why it exists in this epic, what it does NOT cover>
+
+## Epic context
+- Parent epic: `<epic-id>`
+- Position in epic: <e.g., "foundation feature — others depend on its types"
+  / "consumer of feature-X" / "independent capability">
+
+## Foundation references
+- `docs/VISION.md` — relevant section(s) (only if directly relevant)
+- `docs/ARCHITECTURE.md` — relevant component(s)
+- (other foundation docs as relevant)
+
+## Mockups
+<!-- Only present when Phase 4.6 produced or inherited mocks covering this
+feature. Reference the parent epic's chosen options by path; do NOT re-mock
+at the feature tier. -->
+- Inherits design system: `.mockups/design-system/tokens.css`
+- Screens: `.mockups/screens/<feature-id>/index.html` — selected option-N
+- Flow (if applicable): `.mockups/flows/<flow-name>/index.html`
+
+<!-- The design pass on this feature (`/agile-workflow:feature-design`,
+refactor-design, or perf-design) will fill in interfaces, signatures, and
+implementation units. -->
+```
+
+Naming convention: `<epic-slug>-<feature-slug>` — e.g., epic `epic-auth`
+spawns features `epic-auth-login`, `epic-auth-session`, `epic-auth-recovery`.
+This makes parent-child relationships obvious from filenames at a glance.
+
+### Phase 6.5: Cycle check
+
+For every child feature with non-empty `depends_on`, run:
+
+```bash
+.work/bin/work-view --blocking <feature-id> --paths
+```
+
+If any candidate dependency appears in that output, the edge would create a
+cycle. Drop or reroute the edge before continuing.
+
+### Phase 7: Write decomposition INTO epic body
+
+Update the epic file. Replace the provisional "Anticipated child features"
+section (if present) with a `## Decomposition` section listing the realized
+features:
+
+```markdown
+## Decomposition
+
+<one-paragraph summary of the chosen decomposition and why this shape over
+alternatives — e.g., "Split by capability: login flow, session handling, and
+recovery are independent enough to parallelize after the shared session-type
+feature lands.">
+
+### Child features
+
+- `<feature-id-1>` — <one-line description> — depends on: `[]`
+- `<feature-id-2>` — <one-line description> — depends on: `[<feature-id-1>]`
+- `<feature-id-3>` — <one-line description> — depends on: `[<feature-id-1>]`
+
+### Decomposition risks
+
+<from pre-mortem, if any. Otherwise omit the section.>
+```
+
+Do NOT write design content (interfaces, signatures, test plans) into the epic
+body. That's feature-level work.
+
+### Phase 8: Advance epic stage and commit
+
+1. Edit the epic file's frontmatter: `stage: drafting → implementing`. The
+   PostToolUse hook auto-bumps `updated:`.
+2. Commit:
+
+```bash
+git add .work/active/epics/<epic-id>.md .work/active/features/<epic-id>-*.md
+git commit -m "epic-design: <epic-id> (<N> child features)"
+```
+
+## Output
+
+In conversation:
+- **Decomposed**: `<epic-id>` advanced to `stage: implementing`
+- **Child features**: list with `depends_on` chains, e.g.:
+  - `epic-auth-session` — depends on: `[]`
+  - `epic-auth-login` — depends on: `[epic-auth-session]`
+  - `epic-auth-recovery` — depends on: `[epic-auth-session]`
+- **Tags propagated**: list (or "none — greenfield")
+- **Decomposition risks flagged**: list (or "none")
+- **Next**: each child feature is at `stage: drafting` ready for the
+  feature-design family (`/agile-workflow:feature-design`,
+  `/agile-workflow:refactor-design`, or `/agile-workflow:perf-design` based on
+  tags). Autopilot will pick them up automatically.
+
+## Guardrails
+
+- The decomposition lives in the epic's body. NEVER create
+  `docs/designs/epic-<name>.md` — that's a workflow-plugin pattern;
+  agile-workflow uses item-IS-the-work.
+- **Phase 4.6 is the primary UI/UX mockup tier.** Don't defer net-new
+  surfaces to `feature-design` — its mockup phase is a fallback only.
+- **`--only-questions` always runs the mockup pass** — that mode IS the
+  visual alignment gate.
+- Child features are at `stage: drafting` — they get DESIGNED next, not
+  implemented next. Don't pre-populate them at `implementing`.
+- Don't write feature-level design content (interfaces, signatures, tests)
+  into the epic body or the child feature briefs. That belongs in each
+  feature's own design pass.
+- Propagate `[refactor]` or `[perf]` tags from the epic to child features so
+  the right design-family skill picks them up. Greenfield epics produce
+  greenfield features.
+- Aim for 2-6 child features per epic. Outside that range, ask whether the
+  epic is sized correctly.
+- Cycle prevention is mandatory for `depends_on`. Use `work-view --blocking`.
+- If the epic already has direct children (Phase 1.5), short-circuit — advance
+  the stage and stop. Don't re-decompose work the user or another skill
+  already did.
+- Don't pre-bind child features to releases. `release_binding` stays `null`
+  until `/agile-workflow:release-deploy` runs.
+- Don't manufacture refactor/test/deployment features just to have them.
+  Those surface organically from gates and refactor-tagged work.