story-cycle
Skill9 starsChanged 3 months agoMITView on GitHub
Use when the user wants to implement a single story or deliver a backlog item.
In this repository56 other files it gives its agents.
- .claude/agents/CLAUDE.mdCLAUDE.md
- .claude/hooks/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- .claude/prompts/CLAUDE.mdCLAUDE.md
- .claude/rules/CLAUDE.mdCLAUDE.md
- .claude/skills/CLAUDE.mdCLAUDE.md
- docs/CLAUDE.mdCLAUDE.md
- vision/CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- scaffold/llms.txtllms.txt
- architecture-checkSkill
- backlog-reviewSkill
- bootstrapSkill
- brainstormSkill
- buildSkill
- claude-sense-checkSkill
- code-qualitySkill
- commitSkill
- continueSkill
- custom-hooksSkill
- dashboardSkill
- debug-sessionSkill
- deploySkill
- discoverSkill
- doctorSkill
- fix-issueSkill
- framework-upgradeSkill
- handoffSkill
- help-meSkill
- ideateSkill
- lanesSkill
- manual-testSkill
- merge-downSkill
- merge-upSkill
- optimizeSkill
- parallel-workSkill
- performance-checkSkill
- phase-reviewSkill
- pr-statusSkill
- quality-checkSkill
- quickstartSkill
- refine-loopSkill
- researchSkill
- retrospectiveSkill
- security-auditSkill
- skill-createSkill
- skill-evalSkill
- sprint-endSkill
- sprint-startSkill
- testing-cycleSkill
- test-validatorSkill
- UAT-cycleSkill
- undo-workSkill
- uninstallSkill
- weekly-maintenanceSkill
- wrap-upSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
124 rules. About 0 are common, 79 are distinctive, and 45 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈79
Distinctive · estimate
This author's own choices. Worth a look.
45
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 76
Read the Profile: line from CLAUDE.md to determine the active project profile.
- Distinctive: line 105
All 8 phases are mandatory for ALL stories including TRIVIAL — no fast-tracking, no Phase 3-lite
- Very specific: line 125
Read the plan file's remaining_steps list — it is your execution checklist
- Very specific: line 131
Run the context-prime micro-component from .claude/prompts/context-prime.md to load project context (intent-aware ordering based on the …
- Very specific: line 135
If $ARGUMENTS matches a story ID pattern (e.g., PROJ-001, S01, E01-S03), search docs/reference/backlog/E*.md for the story:
- Very specific: line 140
Use extracted type/size/priority as starting classification (validated in the Size & Risk Classification step)
- Very specific: line 142
Definition of Ready check: If the story has status: draft or is missing verification commands, affected files, or out-of-scope section, …
- Very specific: line 145
Dependency check: If the story has dependencies listed, verify each dependency story has status done in its epic file.
- Very specific: line 155
If on a sprint branch (branch name matches sprint-*), load the sprint spec for decision context:
- Distinctive: line 166
Capacity check: If remaining stories (🔲 + 🔄) require more sessions than remain in sprint capacity:
- Distinctive: line 169
M/L story session guidance: If this story is sized M or L, suggest the three-session pattern:
- Distinctive: line 184
Do NOT re-decide settled questions.
- Distinctive: line 189
If implementation reveals an assumption is wrong, update the register: set status → INVALIDATED, add evidence in the Evidence column.
- Very specific: line 200
Before any exploration, decompose the user's request.
- Distinctive: line 205
If the request contains multiple independent stories, suggest splitting and confirm scope
- Distinctive: line 212
After Phase 0 decomposition, classify by size then risk:
- Distinctive: line 225
Do not reclassify a LARGE or XL story downward, or split it, merely because it touches many files.
- Very specific: line 228
Adaptive calibration: If docs/sessions/.activity-log.jsonl contains 10+ skill execution records, check historical data for this story …
- Distinctive: line 229
If stories matching this type consistently required full workflow despite SMALL classification → escalate to STANDARD
- Distinctive: line 230
If STANDARD stories in this area consistently completed without issues → note as candidate for lightweight treatment
- Distinctive: line 251
Red flag: If editing multiple files or changing observable behavior, STOP and reclassify as STANDARD.
- Distinctive: line 257
All other phases are REQUIRED — do NOT skip them because the story feels simple:
- Distinctive: line 270
Run tests (if test command configured)
- Distinctive: line 272
Commit with conventional format
- Very specific: line 279
Pre-flight: Run the discover-commands micro-component from .claude/prompts/discover-commands.md to extract configured commands (test, lint, …
- Very specific: line 299
If the story type is ambiguous after checking indicators, ask the user using AskUserQuestion with description fields explaining workflow …
- Very specific: line 314
Use the grep-first-explore micro-component from .claude/prompts/grep-first-explore.md to efficiently identify relevant files before reading …
- Distinctive: line 325
Run parallel Grep calls: imports/usage, definitions, and test references
- Distinctive: line 327
If fewer than 3 files match (greenfield or entirely new feature): fall back to codebase-explorer agents
- Very specific: line 329
If sub-agents are available (STANDARD stories): Use the wave-execution micro-component from .claude/prompts/wave-execution.md to dispatch …
- Very specific: line 333
Prior learnings check: Search docs/solutions/ for prior learnings on affected modules.
- Distinctive: line 337
If sub-agents are NOT available: Use grep-first only — it's efficient enough for most stories without agent support.
- Very specific: line 339
Architecture rules check: If docs/architecture/ARCHITECTURE.md exists and is non-template, read ONLY the Module Map (Dependency Rules …
- Very specific: line 341
Debt register cross-reference (skip for TRIVIAL stories): If docs/technical-debt.md has active items, grep its Location fields for files …
- Very specific: line 349
If docs/context/system-patterns.md exists and is populated (not template-only), check it against the files being touched:
- Distinctive: line 356
Check for CLAUDE.md files in the target directory and parent directories — these contain module-specific patterns and conventions that …
- Distinctive: line 381
Decision: If ANY signal points to "research needed" → proceed.
- Distinctive: line 420
If official docs reveal a deprecation or API change: note it in the plan as a "Doc Finding" and update relevant reference docs after …
- Distinctive: line 421
If a better approach is found: incorporate it into the plan
- Distinctive: line 422
If everything checks out: note "Online verification: APIs confirmed current" and move on
- Very specific: line 432
If a result looks relevant, WebFetch the specific page to confirm
- Distinctive: line 455
Intent-based security activation: If the story touches user input, API endpoints, database queries, file uploads, sessions, or network …
- Distinctive: line 459
Before writing the plan, check: do you have enough information to write a plan without assumptions?
- Distinctive: line 461
If YES: proceed to 1d.7
- Distinctive: line 462
If NO: present the 3 most critical unknowns to the user as focused questions with 2-4 answer options each.
- Distinctive: line 464
Red flag: If you're about to write "Assuming X..." in the plan, STOP — ask the user about X instead.
- Very specific: line 480
Keep the plan concise — under 50 lines.
- Very specific: line 482
Follow the plan template structure in references/plan-template.md.
- Very specific: line 496
Check the plan against docs/reference/GROUND_RULES.md.
- Distinctive: line 510
All deliverables from Phase 0 have implementation steps
- Distinctive: line 511
All acceptance criteria have verification approaches
- Distinctive: line 520
Use this exact format at the TOP of the plan:
- Distinctive: line 558
When context compacts, MERGE new file paths into these lists — never discard previous entries.
- Distinctive: line 563
When you exit Plan Mode (ExitPlanMode) during a story-cycle, you are NOT done.
- Very specific: line 566
Read .claude/skills/story-cycle/SKILL.md starting from ## Phase 2: Context Transition + Confidence Gate
- Distinctive: line 568
Do NOT report completion until Phase 4d passes with evidence for every acceptance criterion
- Distinctive: line 578
Before presenting for approval, offer the user a depth option if the plan contains areas with complexity ≥4 or unresolved uncertainties:
- Distinctive: line 583
If [D]: apply the most relevant elicitation technique, integrate findings into the plan, then present for approval.
- Distinctive: line 584
If [C] or no uncertainties exist: proceed directly to approval.
- Distinctive: line 589
Do NOT write any implementation code, edit source files, or take any implementation action until the plan has been presented and the user …
- Distinctive: line 594
After plan approval, prune context and score confidence in a single pass.
- Very specific: line 610
Run the confidence-gate micro-component from .claude/prompts/confidence-gate.md.
- Distinctive: line 619
Do NOT skip the readiness gate for ANY story size except TRIVIAL.
- Distinctive: line 628
Check for file overlaps — if ANY file appears in multiple streams, merge those streams
- Distinctive: line 629
If ≥2 non-overlapping streams exist, present the stream analysis to the user
- Distinctive: line 630
If user approves: create worktrees per stream, dispatch agents, coordinate merges
- Distinctive: line 631
If user declines or streams overlap: proceed to serial Phase 3 </IF> <ELSE> Skip — proceed directly to Phase 3.
- Distinctive: line 645
Before writing any implementation code, create a checkpoint so the entire implementation can be cleanly rolled back if verification fails:
- Distinctive: line 660
After each completed TDD cycle (test written → implementation passes → tests green), create an intermediate commit:
- Distinctive: line 668
Prevent data loss: if the session crashes mid-implementation
- Distinctive: line 671
Should each leave the codebase in a working state (tests pass)
- Very specific: line 677
Before writing the first test, apply the test_strategy_selection reasoning tool from references/reasoning-tools.md.
- Distinctive: line 685
Write a failing test for the first behavior (RED) — run it, show the failure output
- Distinctive: line 686
Only THEN write the minimum implementation to make it pass (GREEN)
- Distinctive: line 691
Write a reproduction test that captures the bug (must FAIL) — run it, show the failure output
- Distinctive: line 692
Only THEN implement the fix
- Distinctive: line 693
Verify the reproduction test now passes
- Distinctive: line 696
Write characterization tests that capture current behavior (must PASS) — run them, show the output
- Distinctive: line 697
Only THEN perform the refactoring
- Distinctive: line 698
Verify characterization tests still pass after each step
- Very specific: line 705
When errors occur during execution, consult references/error-recovery.md — search for ## Phase 3 for the recovery table.
- Distinctive: line 709
When a build error, test failure, or runtime exception involves an external library (not internal logic), use the research engine before …
- Very specific: line 731
Read references/self-review.md and complete the checklist (completeness, quality, testing, discipline).
- Distinctive: line 735
Security web verification (security-scoped stories only): If the story was tagged with intent-based security activation (Phase 1d) or is a …
- Distinctive: line 738
Do NOT skip self-review for ANY story size.
- Very specific: line 741
Ground rules re-check: If docs/reference/GROUND_RULES.md exists, re-read it and verify the IMPLEMENTATION (not just the plan) complies.
- Distinctive: line 746
Check user-facing text: Do error messages, labels, or instructions use jargon that conflicts with the persona's CONTEXT (tech proficiency)?
- Distinctive: line 747
Check interaction patterns: Does the UI/UX match the persona's BEHAVIORS (e.g., keyboard navigation for accessibility, mobile-first for …
- Distinctive: line 748
Check the persona's FAILURE LOOKS LIKE scenarios: Is any of them possible in this implementation?
- Very specific: line 776
Error learning: If self-review caught a wrong approach requiring significant rework, invoke the record-failure micro-component from …
- Very specific: line 780
Run the quality-gate-sequence micro-component from .claude/prompts/quality-gate-sequence.md: execute the project's quality commands (from …
- Distinctive: line 786
Run any configured commands (lint, typecheck).
- Distinctive: line 790
Do NOT proceed to Phase 4c/4d until ALL configured quality gates pass with zero failures.
- Very specific: line 798
Find UAT location: Check for docs/testing/UAT_COVERAGE.md (single-file), docs/testing/uat/ (directory), or tests/uat/scenarios/.
- Very specific: line 799
Find next UAT ID: Search for ### UAT- headings in existing files, increment the highest number, format as UAT-### (zero-padded to 3 digits).
- Distinctive: line 817
Skip when: No UAT case was generated.
- Very specific: line 833
Check the box: - [x] Logic verified from code perspective
- Distinctive: line 841
If any criterion lacks evidence: identify the gap, loop back to Phase 3 for that specific item, re-verify.
- Distinctive: line 847
Checkpoint Rollback Option: If verification has failed after 2 loop passes and the implementation appears fundamentally flawed (not just …
- Very specific: line 856
If [R]: git stash push --include-untracked -m "story-cycle: checkpoint rollback" && git reset --soft <checkpoint-tag> && git restore .
- Very specific: line 857
If [C]: Save state to .failure-state.md for /continue pickup.
- Distinctive: line 858
If [F]: Document gaps in completion report, proceed to Phase 4e.
- Distinctive: line 862
Do NOT print the completion report until every acceptance criterion has been verified with evidence.
- Very specific: line 867
Capture story outcome: Run the capture-outcome micro-component from .claude/prompts/capture-outcome.md to record measurable deltas (lines …
- Very specific: line 872
Check all acceptance criteria boxes in the detail section (- [ ] → - [x])
- Very specific: line 877
Update
docs/reference/BACKLOG_INDEX.md: Update story counts per priority group in the status table. - Distinctive: line 880
Update documentation: only if the story's AC requires it
- Very specific: line 881
Architecture documentation check: Read the Update Triggers section of docs/architecture/ARCHITECTURE.md.
- Distinctive: line 882
If a non-obvious gotcha was discovered during implementation → add to Known Landmines
- Distinctive: line 883
If a significant architectural choice was made → add to Key Decisions with trade-off
- Distinctive: line 884
If no Update Trigger matches, skip
- Very specific: line 886
Clean up checkpoint: Delete the git checkpoint tag from Phase 3.pre: git tag -l 'story-checkpoint-*' | xargs -r git tag -d
- Distinctive: line 919
Test failure (new code): Read the error, fix the implementation, re-run.
- Very specific: line 923
Skill not found: If a required skill (e.g., /code-quality) is not available, skip it and note in the completion report.
- Distinctive: line 924
Implementation fundamentally wrong: If Phase 4 reveals the approach is flawed, use the checkpoint rollback option (Phase 4d) to cleanly …
- Distinctive: line 928
NEVER skip the plan phase — always enter plan mode first
- Distinctive: line 929
NEVER carry exploration context into execution — clear and reload
- Distinctive: line 930
NEVER merge to main or create a PR — that's sprint-end
- Distinctive: line 931
NEVER add features not in the acceptance criteria
- Distinctive: line 932
NEVER weaken or delete existing tests
- Very specific: line 933
Follow coding standards in docs/reference/CODING_STANDARDS.md
- Very specific: line 934
Follow testing strategy in docs/reference/TESTING_STRATEGY.md
- Very specific: line 935
Follow architecture constraints in docs/architecture/ARCHITECTURE.md
- Very specific: line 936
Follow project ground rules in docs/reference/GROUND_RULES.md (if exists)
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
story-cycle
Delivering story: $ARGUMENTS
Skill metrics: Emit a start event to the activity log:
echo "{\"type\":\"skill\",\"event\":\"start\",\"skill\":\"story-cycle\",\"story\":\"$ARGUMENTS\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" >> docs/sessions/.activity-log.jsonlProgress tracking: At the start, create a task list for phase tracking:
- "Phase 0+1: Decompose intent, research, plan" — activeForm: "Planning..."
- "Phase 2: Context transition + readiness gate" — activeForm: "Preparing..." — blockedBy: [1]
- "Phase 3: Implement by story type" — activeForm: "Implementing..." — blockedBy: [2]
- "Phase 4: Verify, quality gates, commit" — activeForm: "Verifying..." — blockedBy: [3]
At each phase boundary, mark the current task completed and the next task in_progress.
Process Flow (authoritative — prose below is supporting detail)
START → Phase 0: Intent Decomposition (identify ALL deliverables, mark uncertainties)
→ Size Classification:
→ [TRIVIAL: single-file, <10 lines, no behavioral change]
→ Phase 3-lite: Make change → Run tests → Abbreviated self-review → Commit → DONE
→ [SMALL: single-file, <50 lines, clear AC]
→ Lightweight Phase 1 (skip 1f-1g) → Phase 2 → Phase 3 → Phase 4 → DONE
→ [STANDARD: everything else]
→ Phase 1: Plan Mode (research, identify type, write plan with WHAT/HOW separation)
→ Phase 1c.5: Online Verification → `*** HARD GATE: must print Research Decision block ***`
→ 1c.5+: Dependency Freshness Check (always, if story touches external deps)
→ Phase 1d.7: Story Refinement & Forward Context (gap analysis, cross-story notes)
→ Phase 1f: Clarification Check (ambiguity_scan across 7 categories)
→ Phase 1g: Plan Completeness (verify spec/implementation sections)
→ [User approved?] → NO: Revise → YES: Continue
→ Phase 2: Context Transition + Confidence Gate
→ (prune context, score 5 dimensions, ≥85 proceed, 70-84 clarify, <70 return to Phase 1)
→ Phase 3: Execute by Story Type
→ `*** HARD GATE: TDD ordering — tests BEFORE implementation (Feature/Bug Fix/Refactoring) ***`
→ Web-Assisted Error Recovery (on build/test failure involving external libraries)
→ Bug Fix Web Research (always for bug fix stories — search error patterns first)
→ Phase 4: Verify + Wrap Up
→ Self-review + disaster prevention + ground rules re-check
→ Quality agents dispatched per risk level
→ Security web verification (security-scoped stories — CWE + CVE check)
→ Quality gates `*** HARD GATE: all configured gates must pass ***`
→ UAT generation + sense check (optional — Feature/Bug Fix only)
→ Completion verification (evidence for every AC)
→ Docs + commit
→ [All criteria met?] → NO: Fix + re-verify (max 2 passes) → YES: Report → DONEProfile-Adaptive Behavior
Read the **Profile:** line from CLAUDE.md to determine the active project profile.
<IF condition="Profile is lean">
**Lean mode active.** Simplified workflow: Plan (optional for SMALL) -> Build -> Verify.Skip these phases/steps entirely:
- Phase 0a.5 (sprint context loading)
- Phase 1f (clarification check) and Phase 1g (plan completeness check)
- Phase 2 confidence gate scoring — only run objective pre-checks: are planned files read? do existing tests pass?
- Phase 4a quality agent dispatch — use
/quality-checkwith no flags (lean defaults = code only) - Phase 4c (UAT generation)
- Phase 4e capture-outcome and capture-learnings micro-components
Keep these (non-negotiable):
- Phase 0 (intent decomposition and size classification)
- Phase 1 core (1a-1e for STANDARD stories; skip Phase 1 entirely for SMALL — go directly to Build)
- Phase 3 (implementation with TDD for Feature/Bug Fix/Refactoring story types)
- Phase 4b quality-gate-sequence (lint + test from CLAUDE.md Commands)
- Phase 4d (completion verification — all AC met with evidence)
- Phase 4e commit and completion report
Plan is optional for SMALL stories — if the task is clear, go directly to Phase 3 (Build).
Safety is unchanged in Lean mode: TDD enforcement, test-before-ship, all hooks active. Lean is less ceremony, not less safe.
</IF>
<IF condition="Profile is strict">
**Strict mode active.** Maximum rigor for all story sizes.Additions beyond standard behavior:
- All 8 phases are mandatory for ALL stories including TRIVIAL — no fast-tracking, no Phase 3-lite
- Phase 4a: dispatch
/quality-check --allfor EVERY story regardless of risk level (all 5 agents + integration-tester) - Coverage delta must be >= 0 (test coverage cannot decrease). Compare before/after in Phase 4b.
- Security audit runs full CWE checklist (all 15 entries) for ALL stories, not just security-scoped ones
- On story completion (Phase 4e), write structured audit entry to
docs/sessions/.audit-log.jsonl:{"type":"audit","story":"<id>","story_type":"<type>","profile":"strict","files_changed":["<paths>"],"agents_run":["<names>"],"gates_passed":true,"coverage_delta":"+N%","ts":"<ISO-8601>"}
</IF>Plan Mode for Phases 0-2 (Optional)
For STANDARD stories, consider entering Plan Mode at the start of Phase 0 and remaining in it through Phase 2 (Context Transition). This prevents accidental implementation during the planning phases and provides a natural approval checkpoint.
When to use: Complex stories, high-risk changes, or when the user requests careful planning.
How: Enter Plan Mode before Phase 0. The existing Phase 1 already operates in Plan Mode. Exit Plan Mode after plan approval — just before Phase 2 (Context Transition + Confidence Gate) and Phase 3 (Execution).
CRITICAL — After ExitPlanMode: Plan Mode exit wipes the story-cycle skill from context. After ExitPlanMode, you MUST immediately:
- Read the plan file's
remaining_stepslist — it is your execution checklist - The first step (BOOTSTRAP) tells you to re-read this skill file from Phase 2 onwards
- Continue executing all remaining phases (2 → 3 → 4) — do NOT stop
Phase 0: Intent Decomposition
Run the context-prime micro-component from .claude/prompts/context-prime.md to load project context (intent-aware ordering based on the story description).
0a. Backlog Story Lookup
If $ARGUMENTS matches a story ID pattern (e.g., PROJ-001, S01, E01-S03), search docs/reference/backlog/E*.md for the story:
- Find the story in the epic checklist:
- [ ] ID — Title (Priority, Status) - Find the detailed story section:
### ID: Titlewith inline metadata - Extract metadata: Type, Size, Priority, Status, Dependencies, Affected files, Acceptance criteria, Verification commands
- Use extracted type/size/priority as starting classification (validated in the Size & Risk Classification step)
Definition of Ready check: If the story has status: draft or is missing verification commands, affected files, or out-of-scope section, warn the user:
"This story doesn't meet the Definition of Ready. Missing: [list]. Consider running
/ideateto refine it, or proceed with caution."
Dependency check: If the story has dependencies listed, verify each dependency story has status done in its epic file. If any dependency is not done, warn:
"Dependency [ID] is not complete (status: [status]). This story may be blocked."
Status update: Set the story's status to in-progress in the epic file (both checklist and detail section). Emit a story lifecycle event:
echo "{\"type\":\"story\",\"event\":\"status-change\",\"id\":\"<story-id>\",\"from\":\"<previous>\",\"to\":\"in-progress\",\"story_type\":\"<type>\",\"size\":\"<size>\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" >> docs/sessions/.activity-log.jsonl0a.5. Sprint Context Load
If on a sprint branch (branch name matches sprint-*), load the sprint spec for decision context:
- Find
docs/sprints/sprint-<number>.md(derive number from branch name) - Extract and hold in context:
- Sprint goal — the primary decision-making context for this story. When implementation choices are ambiguous, the sprint goal breaks the tie.
- Boundaries — out-of-scope items. If this story drifts toward an out-of-scope area, flag it.
- Remaining capacity — count stories by status and size (S=1, M=2, L=4 sessions). Compare against total available sessions to determine sprint health.
- Decisions log — prior decisions in this sprint that may constrain this story's approach.
Sprint-aware risk modifier: If the sprint goal explicitly relates to this story's domain (e.g., sprint goal is "auth integration" and story is about auth), note "sprint-aligned" — this story is goal-critical and deserves full depth. If the story is peripheral to the sprint goal (e.g., sprint goal is "auth integration" but story is "update error messages"), note "sprint-peripheral" — keep scope minimal.
Capacity check: If remaining stories (🔲 + 🔄) require more sessions than remain in sprint capacity:
"⚠️ Sprint capacity at risk — [N] stories remaining ([M] sessions needed), [K] sessions available. Consider carrying over the lowest-priority ⏭️ story."
M/L story session guidance: If this story is sized M or L, suggest the three-session pattern:
"This is a [M/L] story (~[2-3/3-5] sessions). Consider: Session 1 = Phase 0-1 (plan + approve), Session 2 = Phase 3 (implement), Session 3 = Phase 4 (verify + commit). Use
/handoffat natural break points to preserve context."
This is guidance, not enforcement — the developer may complete it in fewer sessions.
0b. PRD Scope Guard
If docs/reference/PRD_SUMMARY.md exists, load Section 7 (scope boundaries) and Section 3 (success criteria). Use scope boundaries as guard rails throughout implementation — if the story drifts toward a stated non-goal or violates an implementation boundary, flag it. Use success criteria to verify the story contributes to measurable product outcomes.
0b.5. Discovery Context Loading
<IF condition="docs/reference/DECISION_LOG.md exists">
Load decisions relevant to this story (grep for keywords from story description and affected files).
During implementation: if a decision point arises that's already in the log, USE the logged decision. State:
> "Using decision D007 (logged during discovery): [decision]"
Do NOT re-decide settled questions. If a decision needs revisiting, document why and update the log.
</IF><IF condition="docs/reference/ASSUMPTION_REGISTER.md exists">
Load assumptions relevant to this story (grep for keywords from story description).
If implementation reveals an assumption is wrong, update the register: set status → INVALIDATED, add evidence in the Evidence column. Flag to the user:
> "Assumption A003 has been invalidated: [assumption]. Evidence: [what we found]. This may affect [related decisions]."
</IF><IF condition="Story has a 'No-Gos' section OR vision/project-pitch.md contains NO-GOS">
Load No-Gos into context. If scope creep toward a No-Go is detected during implementation, STOP:
> "This is heading toward a documented No-Go: [no-go]. Should we continue or respect the boundary?"
</IF>0c. Scope Analysis
Before any exploration, decompose the user's request. Apply the scope_analysis reasoning tool from references/reasoning-tools.md:
- List ALL distinct outcomes the user expects (implementation, tests, docs, PR, etc.)
- For each: identify type, files likely affected, complexity (1-5), and dependencies
- Flag any deliverable rated complexity ≥4 as candidate for splitting
- If the request contains multiple independent stories, suggest splitting and confirm scope
- Confirm the full scope with the user before proceeding to planning
This prevents missing later parts of compound requests (e.g., "refactor auth AND add rate limiting AND create a PR").
Size & Risk Classification (Fast-Track Gate)
After Phase 0 decomposition, classify by size then risk:
Size classification — use the story's frontmatter size field as starting point (if the story came from the backlog via /ideate). Validate against actual scope after decomposition — reclassify if the scope doesn't match:
| Size | Criteria | Default Workflow |
| TRIVIAL | Single file, <10 lines changed, no behavioral change (typo, config, comment) | Phase 3-lite (below) |
| SMALL | One clear change following an existing pattern | Lightweight Phase 1 (skip 1f, 1g) → Phase 2 → Phase 3 → Phase 4 |
| STANDARD | One coherent feature, requires a plan | Full workflow (unchanged) |
| LARGE | One coherent mechanism whose parts interlock and cannot be meaningfully tested in isolation | Full workflow + integration test pass before Phase 4 |
| XL | A complete subsystem with a single conceptual center | Full workflow, staged implementation — build and verify one part of the mechanism at a time, then a full-suite pass before Phase 4 |
Sizing is by conceptual cohesion, not file count — see ../ideate/references/story-template.md.
Do not reclassify a LARGE or XL story downward, or split it, merely because it touches many files.
Split only when it spans genuinely unrelated topics.
Adaptive calibration: If docs/sessions/.activity-log.jsonl contains 10+ skill execution records, check historical data for this story type/scope:
- If stories matching this type consistently required full workflow despite SMALL classification → escalate to STANDARD
- If STANDARD stories in this area consistently completed without issues → note as candidate for lightweight treatment
- Log calibration adjustment in plan for transparency:
Depth calibration: [escalated/standard/downgraded] based on [N] prior executions
Sprint context modifier (from Phase 0a.5): If sprint context was loaded, apply:
- Sprint-aligned stories: maintain or escalate depth — these are goal-critical, quality matters most
- Sprint-peripheral stories: consider downgrading depth if sprint capacity is tight — keep scope minimal, defer stretch goals to next sprint
- Log:
Sprint alignment: [aligned/peripheral] — sprint goal: "[goal]"
Risk classification (apply risk_classification reasoning tool from references/reasoning-tools.md):
Score domain risk, integration surface, and reversibility (1-3 each). Sum determines risk level:
| Low risk (3-4) | Medium risk (5-6) | High risk (7-9) | |
| TRIVIAL | Phase 3-lite | Phase 3-lite + full test suite | Reclassify as SMALL |
| SMALL | Lightweight Phase 1 | Standard workflow | Standard + mandatory security-audit |
| STANDARD | Standard workflow | Standard + all quality agents | Standard + all agents + architecture-check |
| LARGE | Standard + integration tests | Standard + all quality agents + integration tests | Standard + all agents + architecture-check + security-audit |
| XL | Staged build + all quality agents | Staged build + all agents + architecture-check | Staged build + all agents + architecture-check + security-audit + integration-tester |
<HARD-GATE>
**Red flag:** If editing multiple files or changing observable behavior, STOP and reclassify as STANDARD. Fast-track is for genuinely trivial changes only.
</HARD-GATE>SMALL Story Checklist
SMALL stories skip Phase 1f (clarification check) and 1g (plan completeness) only. All other phases are REQUIRED — do NOT skip them because the story feels simple:
- Phase 0: Intent decomposition
- Phase 1: Lightweight analysis + plan (includes 1c.5 Research Decision — MANDATORY output) →
*** HARD GATE: user approval *** - Phase 2: Context transition + readiness gate (5 objective checks) →
*** HARD GATE *** - Phase 3: Implementation (TDD by story type)
- Phase 4: Self-review + quality gates + completion verification with evidence →
*** HARD GATE ***
Why this matters: Testing proved that SMALL stories get their quality gates skipped when the agent optimizes for speed. The code may be fine, but the process guarantees are missing. Every gate exists for a reason.
Phase 3-lite (TRIVIAL only)
- Make the change
- Run tests (if test command configured)
- Abbreviated self-review: Does the diff match intent? Any unintended side effects?
- Commit with conventional format
- Print completion report
Phase 1: Story Analysis (Plan Mode)
Enter plan mode to research and design the approach.
Pre-flight: Run the discover-commands micro-component from .claude/prompts/discover-commands.md to extract configured commands (test, lint, format, build, typecheck) from CLAUDE.md. Run the verify-clean-git-state micro-component from .claude/prompts/verify-clean-git-state.md to confirm no uncommitted changes and correct branch.
1a. Identify Story Type
Determine the story type from the description, backlog entry, or user input:
| Type | Indicators | Approach |
| Feature | New user-facing capability, "As a user..." | TDD: RED-GREEN-REFACTOR |
| Bug Fix | Defect, "fix", error report, reproduction steps | Reproduce → Test → Fix → Verify |
| Refactoring | "Refactor", "restructure", no behavior change | Characterization tests → Refactor → Verify |
| Spike/Research | "Investigate", "evaluate", "prototype", time-boxed | Explore → Document → Decide |
| Infrastructure | CI/CD, tooling, build, config, environment | Plan → Implement → Smoke Test |
| Testing | "Add tests", "coverage", "E2E tests" | Design strategy → Generate → Validate |
| Documentation | "Document", "write docs", "update README" | Gather → Generate → Review |
| Security | "Harden", "audit", "vulnerability", "encrypt" | Threat model → Implement → Audit |
| Performance | "Optimize", "benchmark", "speed up", "latency" | Baseline → Optimize → Benchmark |
| Skill/Tooling | "Create skill", "add tool", "developer experience" | Design → Build → Document |
| Review | Phase transition, walkthrough, assumption validation, direction decision | Interactive walkthrough → Document findings → Decide direction |
If the story type is ambiguous after checking indicators, ask the user using AskUserQuestion with description fields explaining workflow implications:
- Feature — description: "Full TDD (RED-GREEN-REFACTOR). AC in Given/When/Then. Heaviest testing."
- Bug Fix — description: "Reproduce first, then fix. Creates regression test. Lighter planning."
- Refactoring — description: "No behavior change. Characterization tests first, then restructure."
- Spike/Research — description: "Time-boxed exploration. Output is a decision doc, not code. No TDD."
- Infrastructure — description: "CI/CD, tooling, config. Smoke test verification. Lighter AC."
- Testing — description: "Pure test code. Design strategy, generate tests, validate coverage."
- Documentation — description: "Non-code deliverable. Gather, generate, review cycle."
- Security — description: "Threat model first. Mandatory security-audit agent. CWE checklist."
- Performance — description: "Baseline measurement required. Optimize, then benchmark."
- Skill/Tooling — description: "Developer experience. Design, build, document pattern."
1b. Codebase Exploration (Grep-First)
Use the grep-first-explore micro-component from .claude/prompts/grep-first-explore.md to efficiently identify relevant files before reading them. The number of exploration streams scales with story size:
| Size | Exploration Strategy |
| TRIVIAL | Skip Phase 1b entirely (already fast-tracked) |
| SMALL | Single grep-first pass: extract terms from the story, run parallel Grep calls, read top 5-7 files |
| STANDARD | Grep-first pass + 1-2 codebase-explorer agents for broader context (architecture focus, test focus) |
| STANDARD + High-risk | Grep-first pass + 2 agents + security-focused grep (search for auth patterns, input validation, trust boundaries in affected modules) |
Grep-first process:
- Extract key terms from the story description (function names, module names, API endpoints, error messages)
- Run parallel Grep calls: imports/usage, definitions, and test references
- Rank files by match density, select top 5-10
- If fewer than 3 files match (greenfield or entirely new feature): fall back to codebase-explorer agents
If sub-agents are available (STANDARD stories): Use the wave-execution micro-component from .claude/prompts/wave-execution.md to dispatch codebase-explorer agents in parallel with focused prompts:
- Implementation focus: "Find source files that implement or relate to: [story description]."
- Test focus: "Find test files, test utilities, and fixtures related to: [story description]."
Prior learnings check: Search docs/solutions/ for prior learnings on affected modules. Grep frontmatter fields (tags, module, component) for terms from the story. Read matching solution documents to avoid rediscovering known patterns or gotchas.
Collect all results. Deduplicate and synthesize into a focused file list (10-15 files max). Read ONLY the files identified. If during implementation you need additional files, read them then — don't front-load.
If sub-agents are NOT available: Use grep-first only — it's efficient enough for most stories without agent support.
Architecture rules check: If docs/architecture/ARCHITECTURE.md exists and is non-template, read ONLY the Module Map (Dependency Rules subsection) and Known Landmines sections. For each module this story touches, note any applicable rules or landmines in the exploration summary. This avoids wrong-direction implementations and repeat mistakes.
Debt register cross-reference (skip for TRIVIAL stories): If docs/technical-debt.md has active items, grep its Location fields for files identified in exploration. If any explored files appear in active debt items:
- Low severity + Hours effort in files being modified → suggest addressing as a "boy scout" improvement alongside the story (leave code better than you found it). Note: do not expand story scope — only fix if genuinely trivial.
- Higher severity or effort → note in exploration summary for awareness ("TD-NNN affects this file"), but do not expand scope. The debt register tracks these for future sprints.
1c. Research Codebase
- Deep-read the files identified in step 1b
- Understand patterns, conventions, and existing tests in the area
- If
docs/context/system-patterns.mdexists and is populated (not template-only), check it against the files being touched:- Which implementation patterns apply to this story's scope? (Note reference files to follow.)
- Does the area's error handling match the documented strategy? (Flag divergence.)
- What testing conventions apply? (Test naming, fixture approach, mock strategy.)
- Is there an implementation recipe for the type of entity this story adds? (Follow it.) Note applicable patterns in the plan's "patterns to follow" section. If the story will introduce a NEW pattern not yet documented, note that for post-implementation update.
- Identify files to modify and files to create
- Check for
CLAUDE.mdfiles in the target directory and parent directories — these contain module-specific patterns and conventions that supplement global CLAUDE.md
1c.5. Online Verification
<HARD-GATE>
**This phase produces MANDATORY output.** You MUST print a `## Research Decision` block (format below) before proceeding to Phase 1d. The plan CANNOT be written without this block. Skipping this phase silently is a workflow violation.
</HARD-GATE>Step 1 — Classify research requirement:
| Story type | Research requirement | Depth |
| Spike/Research | MANDATORY | DEEP |
| Security | MANDATORY | STANDARD |
| Bug Fix | MANDATORY (error pattern search) | QUICK |
| All other types | Conditional (evaluate 3 signals below) | Auto-select |
Step 2 — For conditional stories, evaluate these three signals:
| Signal | Research needed | Skip research |
| Risk level | High-risk topics: security, payments, auth, external APIs, new dependencies | Low-risk internal changes |
| Local context strength | Weak: unfamiliar library, no existing patterns, no prior solutions in docs/solutions/ | Strong: established patterns, existing tests, prior solution docs cover this area |
| Uncertainty level | Approach is unclear, multiple valid strategies exist | Approach is obvious from codebase conventions |
Decision: If ANY signal points to "research needed" → proceed. Otherwise → skip with justification.
Step 3 — Execute research (when proceeding):
Compose the deep-research methodology (.claude/prompts/deep-research.md) at the depth from Step 1:
| Story context | Research depth |
| Spike/Research | DEEP |
| Security, new external dependencies | STANDARD |
| Bug fix, standard story with research signals | QUICK |
The research engine handles: query decomposition, parallel subagent dispatch, source evaluation, reflection-based compression. See .claude/prompts/deep-research.md.
For Spike/Research stories specifically: Generate sub-questions from the spike's questions. Research current state of reference technologies, recent publications, competitor approaches, and relevant patterns. All claims MUST cite sources with URLs. Training data alone is NEVER sufficient for spikes.
Step 4 — Print the Research Decision block (MANDATORY):
## Research Decision
**Story type:** [type from 1a]
**Research requirement:** [MANDATORY / Conditional]
**Decision:** [PERFORMED at [depth] / SKIPPED]
**Justification:** [why — for skips: which signals were evaluated and why all pointed to skip]
### Findings (if research was performed)
- [Key finding 1 with source URL]
- [Key finding 2 with source URL]
- [Finding N...]
**Research confidence:** [high/medium/low]
**Impact on plan:** [how findings affect the approach — or "No findings that change approach"]This block is included in the plan and feeds into Phase 2b readiness checks.
Record findings:
- If official docs reveal a deprecation or API change: note it in the plan as a "Doc Finding" and update relevant reference docs after implementation
- If a better approach is found: incorporate it into the plan
- If everything checks out: note "Online verification: APIs confirmed current" and move on
1c.5+. Dependency Freshness Check (Always-On for External Deps)
Trigger: The story creates, modifies, or directly calls any external dependency (not internal modules). This runs even when the main 1c.5 research gate was skipped.
Quick check (~30 seconds):
- Identify the external libraries the story will use (from plan or codebase grep)
- For each,
WebSearchfor:"<library> <pinned-version> deprecation OR breaking change OR CVE"(batch into 1-2 searches) - If a result looks relevant,
WebFetchthe specific page to confirm
Outcomes:
| Finding | Action |
| No issues | Note "Dep freshness: all clear" in plan, move on |
| Deprecation notice | Note in plan, use recommended replacement API |
| Known CVE | Flag to user immediately — may change story scope |
| Breaking change in newer version | Note in plan for awareness; no action if pinned version is stable |
Skip when: Story only touches internal code with no external library calls.
1d. Define Required Skills
Determine which skills benefit this story. If the story metadata already defines skills, use those. Otherwise select from:
| Skill | Load When |
/code-quality | Feature, refactoring, infrastructure stories |
/test-validator | Feature, bug fix, refactoring, testing stories |
/security-audit | Security stories, code touching auth/credentials/data |
Intent-based security activation: If the story touches user input, API endpoints, database queries, file uploads, sessions, or network calls, treat the security rule as active for ALL files in this story — not just files matching security path patterns. Note this in the plan: Security scope: story-wide (intent-based).
1d.5. Discovery Gate (Facilitator Check)
Before writing the plan, check: do you have enough information to write a plan without assumptions?
- If YES: proceed to 1d.7
- If NO: present the 3 most critical unknowns to the user as focused questions with 2-4 answer options each. Integrate answers, then proceed to 1d.7.
Red flag: If you're about to write "Assuming X..." in the plan, STOP — ask the user about X instead. Facilitate discovery; don't generate assumptions.
1d.7. Story Refinement & Forward Context
With codebase understanding from 1b-1c, pressure-test the story before planning:
- Map to application: For each acceptance criterion, identify the concrete components, endpoints, services, and modules involved. If a criterion is vague, make it specific to the project's architecture.
- Gap analysis: What's needed for this to work that the story doesn't mention? Check if gaps are covered by other TODO stories in the epic.
- Small uncovered gap → propose expanding this story's AC (confirm with user)
- Large uncovered gap → flag it, don't silently absorb scope
- Forward context: Check TODO stories in the same epic that depend on or relate to this one. If research clarifies anything for them (API shape they'll consume, patterns to follow, components to reuse), add a brief
> Context from [this story]: ...note to those stories in the epic file.
Summarize: what was refined, what gaps were found, what forward context was added.
1e. Write the Plan
Keep the plan concise — under 50 lines. Save complex plans to docs/plans/ for persistence across compaction. Reference files by path rather than inlining content.
Follow the plan template structure in references/plan-template.md. The plan MUST have two distinct sections:
- Specification (WHAT/WHY) — User-visible behavior changes, acceptance criteria in Given/When/Then format. NO file paths, NO function names, NO framework references.
- Implementation Approach (HOW) — Files to modify/create, patterns to follow, technical strategy with rationale.
For any requirement where the user's intent is ambiguous or multiple valid interpretations exist, insert [NEEDS CLARIFICATION: specific question] in the plan. Maximum 3 markers before triggering a hard gate for user input.
Apply the test_strategy_selection reasoning tool for the testing section.
<IF condition="docs/adr/ contains ADR files">
Scan ADR YAML frontmatter for `status: accepted` records with tags relevant to this story's domain. Check that no proposed approach matches a `rejected-options` value in any accepted ADR. If a match is found, note the ADR reference and use the chosen alternative instead. Check `Reconsider when` conditions only if circumstances have materially changed.
</IF><IF condition="docs/reference/GROUND_RULES.md exists">
Check the plan against `docs/reference/GROUND_RULES.md`. Any MUST violation → HALT. Any SHOULD violation → document justification in an Architectural Violations table (see `references/plan-template.md`).
</IF>1f. Clarification Check
Apply the ambiguity_scan reasoning tool from references/reasoning-tools.md. Scan the plan for assumptions across 7 categories (scope, data model, UX, non-functional, integration, edge cases, constraints).
<IF condition="ambiguity_scan produces questions OR plan contains [NEEDS CLARIFICATION] markers">
Present questions to user. Integrate answers into the plan. Remove resolved `[NEEDS CLARIFICATION]` markers.
</IF>1g. Plan Completeness
Apply the plan_completeness reasoning tool from references/reasoning-tools.md to verify:
- All deliverables from Phase 0 have implementation steps
- All acceptance criteria have verification approaches
- Specification section contains zero implementation details
- Implementation section traces to every acceptance criterion
- Research Decision block is present (from Phase 1c.5) — if missing, HALT and go back to 1c.5
CRITICAL — Story-Cycle Context Preservation:
After plan approval, context resets and only the plan survives. The plan MUST start with a "Story-Cycle Context" section so Claude Code knows what workflow it's in and what steps remain. Update the phase and stepsCompleted fields at each phase transition — this enables true mid-workflow resume if the session is interrupted or context compacts.
Use this exact format at the TOP of the plan:
## Story-Cycle Context
workflow: story-cycle
storyType: "[from Phase 1a]"
sprint_number: [N]
sprint_goal: "[from Phase 0a.5 — one sentence]"
sprint_alignment: "[aligned/peripheral — from Size & Risk Classification]"
phase: "plan-approved — proceed to Phase 2 Context Transition + Confidence Gate"
stepsCompleted: [0-intent, 0a5-sprint-context, 1a-type, 1b-discovery, 1c-research, 1c5-online-verify, 1d-skills, 1d5-discovery-gate, 1d7-refinement, 1e-plan, 1f-clarification, 1g-completeness, 1h-depth-check]
remaining_steps:
- "BOOTSTRAP (do this FIRST): Read .claude/skills/story-cycle/SKILL.md starting from '## Phase 2: Context Transition + Confidence Gate' to reload the full story-cycle workflow. You are mid-workflow — planning is done, implementation phases remain. Do NOT stop after reading the plan."
- "Phase 2 — CONTEXT + READINESS GATE (HARD-GATE): Prune context (keep plan + paths + gotchas, discard bulk). Read .claude/prompts/confidence-gate.md. Verify 5 objective checks (files read, tests baseline, pattern match, scope bounded, no conflicts). All pass → proceed. Any fail → address gap. Output the check results."
- "Phase 3 — IMPLEMENT (TDD HARD-GATE for Feature/Bug Fix/Refactoring): Read .claude/skills/story-cycle/references/story-types.md for [storyType] execution steps. Load relevant sections of docs/reference/CODING_STANDARDS.md and docs/reference/TESTING_STRATEGY.md. Re-read all target files from plan before editing. CRITICAL: For Feature/Bug Fix/Refactoring stories, write and run a failing test BEFORE writing implementation code. Show test failure output. Only then write implementation. Follow story-type methodology (TDD: RED → GREEN → REFACTOR)."
- "Phase 4a — SELF-REVIEW (HARD-GATE): Read .claude/skills/story-cycle/references/self-review.md — complete ALL checklist items including ground rules re-check. Read .claude/skills/story-cycle/references/disaster-prevention.md — check for wheel reinvention, spec drift, integration wiring, file structure, regression surface, architecture doc staleness. Dispatch quality skills per risk level (Low: code-quality+test-validator+security-audit-lightweight, Medium: +security-audit-full, High: +architecture-check). At Medium+ risk, also dispatch integration-tester native agent (.claude/agents/integration-tester.md) with test commands + acceptance criteria for independent dynamic verification. If ANY item fails → fix in Phase 3 before proceeding."
- "Phase 4b — QUALITY GATES (HARD-GATE): Run the project's quality command (from CLAUDE.md Commands section: lint → typecheck → test). Stop on first failure, fix, re-run. Show passing output in the current turn — do NOT claim tests pass without evidence. Do NOT proceed until all gates pass."
- "Phase 4b.5 — LAUNCH & VERIFY (optional, Feature/Bug Fix only): Check CLAUDE.md Commands for a dev command. If one exists AND the story type is Feature or Bug Fix: offer to run it so the user can visually verify. Run in background, show whatever output it produces (URLs, status, CLI output — do NOT assume localhost). Ask: 'Want to verify it visually?' If user declines or no dev command exists, skip. Also skip for Spike, Infrastructure, Documentation, Testing, Refactoring, Performance, Skill/Tooling, Review stories."
- "Phase 4c — UAT (optional, Feature/Bug Fix only): If project has UAT directory, generate UAT test case + sense check per Phase 4c/4c.1 in SKILL.md. Skip for Spike/Research, Infrastructure, Documentation, Testing, Refactoring, Performance, Skill/Tooling stories. Also skip if no UAT directory exists."
- "Phase 4d — COMPLETION VERIFICATION (HARD-GATE): Re-read original AC from plan. For EACH criterion, provide concrete evidence (test output, file:line, command output). Max 2 extra loop passes if gaps found. Do NOT print completion report until every AC has evidence."
- "Phase 4e — DOCS + COMMIT: (1) Update epic file (mark story DONE in heading, check all AC boxes). (2) Update BACKLOG_INDEX.md (increment Done, decrement TODO for epic row, update Total row). (3) Update docs/progress.md (story status ✅). (4) Update sprint spec (docs/sprints/sprint-N.md): set story Status to ✅, Session column to today's date. (5) Update CLAUDE.md if it contains backlog counts or epic progress that changed. (6) Emit skill metrics event to docs/sessions/.activity-log.jsonl. (7) Invoke /commit skill. Do NOT merge or create PR — that is sprint-end."
- "COMPLETION REPORT: Print story, type, approach, files modified, test counts, commit hash, verification evidence. Include Next Steps section with concrete commands. Determine the next story from the sprint spec (docs/sprints/sprint-N.md) or epic file — find the first story with status TODO/ready. Format: '**Next steps:**\n1. Clear your context window: `/clear`\n2. Start the next story: `/story-cycle [next-story-id]`' — always use the actual story ID. If no stories remain, suggest `/sprint-end` instead."
error_recovery: ".claude/skills/story-cycle/references/error-recovery.md"
skill_file: ".claude/skills/story-cycle/SKILL.md"File Context (accumulates across compactions)
<files-read>
[List all files read during planning — one path per line]
</files-read>
<files-modified>
[Update as files are modified during execution — one path per line]
</files-modified>When context compacts, MERGE new file paths into these lists — never discard previous entries.
<HARD-GATE>
**POST-PLAN-MODE EXECUTION — THIS IS NOT OPTIONAL**When you exit Plan Mode (ExitPlanMode) during a story-cycle, you are NOT done. Planning is only Phase 1 of 4. After Plan Mode exits, you MUST:
- Read
.claude/skills/story-cycle/SKILL.mdstarting from## Phase 2: Context Transition + Confidence Gate - Execute the
remaining_stepsfrom the plan's Story-Cycle Context block IN ORDER - Do NOT report completion until Phase 4d passes with evidence for every acceptance criterion
The plan approval is a checkpoint, not the finish line. If you stop after Plan Mode,
the story is incomplete — no code was written, no tests were run, nothing was committed.
</HARD-GATE>
For complex stories, use ultrathink to reason through architectural decisions before writing the plan.
1h. Depth Check (Optional)
Before presenting for approval, offer the user a depth option if the plan contains areas with complexity ≥4 or unresolved uncertainties:
- [D] Deep dive — Explore design alternatives for uncertain areas using the
depth_explorationreasoning tool and elicitation techniques fromreferences/elicitation-techniques.md - [C] Continue — Plan is ready for approval as-is
If [D]: apply the most relevant elicitation technique, integrate findings into the plan, then present for approval. If [C] or no uncertainties exist: proceed directly to approval.
Present the plan for user approval.
<HARD-GATE>
Do NOT write any implementation code, edit source files, or take any implementation action until the plan has been presented and the user has explicitly approved it. "I already know what to do" is NOT approval. Wait for the user.
</HARD-GATE>Phase 2: Context Transition + Confidence Gate
After plan approval, prune context and score confidence in a single pass.
2a. Context Pruning
KEEP: The approved plan (with Story-Cycle Context header), file paths from research, edge cases/gotchas, pattern snippets. DISCARD: Full file contents from exploration, dead-end investigations, irrelevant search results. RELOAD for Phase 3 (section-specific to save context):
docs/reference/CODING_STANDARDS.md— load ONLY the section for the story's language/stack (e.g.,## Pythonor## TypeScript), plus the## Universal Conventionsand## AI-Specific Anti-Patternssections. Skip other language sections.docs/reference/TESTING_STRATEGY.md— load ONLY the## Test Infrastructuresection (project-specific commands) and the section matching the story type (e.g.,## Feature Storyor## Bug Fix). Skip unrelated story-type sections.- Target source/test files from the plan.
SKIP until Phase 4:
docs/progress.md,docs/architecture/ARCHITECTURE.md, backlog files,docs/reference/GROUND_RULES.md(already checked in Phase 1e).
Re-read target files before editing — context may have changed since Phase 1.
2b. Readiness Gate
Run the confidence-gate micro-component from .claude/prompts/confidence-gate.md. Verify 5 objective pre-conditions (files read, tests baseline, pattern match, scope bounded, no conflicts) as PASS or FAIL.
| Result | Action |
| All 5 pass | Proceed to Phase 3 |
| Any fail | Address the specific gap (re-read missing files, run tests, check rules) |
| User override | Proceed with acknowledgment of overridden checks |
<HARD-GATE>
Do NOT skip the readiness gate for ANY story size except TRIVIAL. Output the 5-check results before proceeding to Phase 3.
</HARD-GATE>Phase 3a: Parallel Stream Analysis (Optional)
<IF condition="story is STANDARD size AND risk is Low or Medium (3-6) AND plan identifies ≥2 independent work units">
Analyze the approved plan for parallel execution opportunities. Read `references/parallel-streams.md` for the full protocol.- Map each work unit to its file scope (which files it creates/modifies)
- Check for file overlaps — if ANY file appears in multiple streams, merge those streams
- If ≥2 non-overlapping streams exist, present the stream analysis to the user
- If user approves: create worktrees per stream, dispatch agents, coordinate merges
- If user declines or streams overlap: proceed to serial Phase 3
</IF>
<ELSE>
Skip — proceed directly to Phase 3.
</ELSE>Session Recovery
The Stop hook auto-saves git state to docs/sessions/.auto-save.md (branch, recent commits, uncommitted files). The /continue skill uses this plus git state to resume interrupted workflows. No manual state file management needed.
Phase 3: Execute by Story Type
3.pre. Git Checkpoint
Before writing any implementation code, create a checkpoint so the entire implementation can be cleanly rolled back if verification fails:
git tag "story-checkpoint-$(date +%s)" HEADRecord the tag name in .failure-state.md under a checkpoint_tag field. This tag is used by Phase 4 if verification fails — see "Checkpoint Rollback" in Phase 4d.
On successful story completion (Phase 4e commit), delete the checkpoint tag:
git tag -d "story-checkpoint-*" # Clean upIntermediate Commits During Implementation
After each completed TDD cycle (test written → implementation passes → tests green), create an intermediate commit:
git add <changed-files>
git commit -m "<type>(<scope>): <description of this unit>"These intermediate commits:
- Prevent data loss if the session crashes mid-implementation
- Provide natural rollback points within a story
- Are squashed at sprint-end anyway — commit freely during development
- Should each leave the codebase in a working state (tests pass)
For TRIVIAL and SMALL stories, a single commit at Phase 4e is sufficient.
In references/story-types.md, search for the ## [Your Story Type] heading matching Phase 1 — load only that section, not the entire file.
Before writing the first test, apply the test_strategy_selection reasoning tool from references/reasoning-tools.md.
<HARD-GATE>
**TDD Ordering Enforcement (Feature, Bug Fix, Refactoring stories):**For story types that require tests (Feature, Bug Fix, Refactoring), you MUST write and run test code BEFORE writing implementation code. This is not optional — it is the framework's #1 principle.
Feature stories (RED-GREEN-REFACTOR):
- Write a failing test for the first behavior (RED) — run it, show the failure output
- Only THEN write the minimum implementation to make it pass (GREEN)
- Refactor while keeping tests green
- Repeat for each behavior in the acceptance criteria
Bug Fix stories:
- Write a reproduction test that captures the bug (must FAIL) — run it, show the failure output
- Only THEN implement the fix
- Verify the reproduction test now passes
Refactoring stories:
- Write characterization tests that capture current behavior (must PASS) — run them, show the output
- Only THEN perform the refactoring
- Verify characterization tests still pass after each step
What "before" means concretely: The first Edit or Write call to a source file (non-test) MUST be preceded by at least one Edit or Write call to a test file, AND a Bash call that ran the test and showed output. If you find yourself about to edit a source file without having written and run a test first, STOP and write the test.
Exceptions: Spike/Research, Infrastructure, Documentation, Testing, Performance, Security, Skill/Tooling stories follow their own methodology from references/story-types.md and are not subject to this gate.
</HARD-GATE>
When errors occur during execution, consult references/error-recovery.md — search for ## Phase 3 for the recovery table.
Web-Assisted Error Recovery (Phase 3)
When a build error, test failure, or runtime exception involves an external library (not internal logic), use the research engine before guessing:
Trigger: Error message contains a library name, unfamiliar API, or stack trace pointing outside the project's source tree. Does NOT trigger for purely internal logic errors (wrong variable, missing import of own module, etc.).
Protocol: Compose the deep-research methodology (.claude/prompts/deep-research.md) at QUICK depth:
- Sub-questions (1-2, generated from the error):
- "What does [error message snippet] mean in [library/framework] [version]?"
- "How to fix [error pattern] in [library] [version]?"
- Output format:
evidence-check(fix or workaround with source citation) - Apply the fix if found. If no results: fall back to normal error recovery (re-read code, check types, etc.)
Time budget: Max 60 seconds of web research per error. If nothing useful surfaces, move on — don't spiral.
Bug fix stories — proactive search: For bug fix story types, search the error pattern at the START of Phase 3 (before attempting a fix), not just after failure. The error message is the most valuable search query you have — use it early. See references/story-types.md for the updated Bug Fix workflow.
Phase 4: Verify + Wrap Up
This phase combines self-review, quality gates, UAT, and completion verification into a single pass. All checks are mandatory — none are skipped because the story feels simple.
4a. Self-Review + Disaster Prevention
Read references/self-review.md and complete the checklist (completeness, quality, testing, discipline).
Then read references/disaster-prevention.md — check for: wheel reinvention, spec drift, integration wiring, file structure, regression surface.
Security web verification (security-scoped stories only): If the story was tagged with intent-based security activation (Phase 1d) or is a Security story type, perform a targeted web check before quality gates. See references/self-review.md → "Security Web Verification" section for the protocol.
<HARD-GATE>
Do NOT skip self-review for ANY story size. If any checklist item fails, go back to Phase 3 and fix before continuing.
</HARD-GATE>Ground rules re-check: If docs/reference/GROUND_RULES.md exists, re-read it and verify the IMPLEMENTATION (not just the plan) complies. Plans can comply while implementation drifts. Check git diff --name-only against ground rules — any MUST violation requires fixing before proceeding.
Persona cross-check (medium+ risk, user-facing stories only): If docs/context/personas.md exists AND the story has a Personas: field (not "internal"), scan the implementation for persona-mismatch issues that functional AC wouldn't catch:
- Load the persona(s) referenced in the story's
Personas:field - Check user-facing text: Do error messages, labels, or instructions use jargon that conflicts with the persona's CONTEXT (tech proficiency)?
- Check interaction patterns: Does the UI/UX match the persona's BEHAVIORS (e.g., keyboard navigation for accessibility, mobile-first for mobile personas)?
- Check the persona's FAILURE LOOKS LIKE scenarios: Is any of them possible in this implementation?
Focus on surface-level mismatches between implementation and persona constraints — not whether the feature conceptually serves the persona (the AC already covers that).
Skip when: Story is TRIVIAL or low risk (3-4), story has Personas: internal, or personas.md doesn't exist.
If sub-agents are available: Dispatch quality gates via /quality-check based on the risk matrix from Size & Risk Classification:
| Risk Level | /quality-check Invocation | Notes |
| Low (3-4) | /quality-check (profile defaults) | Standard: code+tests+security. Lean: code only. |
| Medium (5-6) | /quality-check --code --tests --security | Plus integration-tester at standard+ profiles |
| High (7-9) | /quality-check --all | All 5 agents + integration-tester (mandatory) |
<IF condition="Profile is strict">
**Strict override:** Dispatch `/quality-check --all` for ALL stories regardless of risk level. Integration-tester is mandatory for all stories.
</IF><IF condition="Profile is lean">
**Lean override:** Skip quality agent dispatch. Phase 4b quality-gate-sequence (lint + test) is sufficient.
</IF>Why security at ALL risk levels: AI-generated code contains vulnerabilities 40-45% of the time regardless of story type. /quality-check handles lightweight vs full security pass based on flags.
Why integration-tester at Medium+ risk: The implementing LLM verifies its own work in Phase 4b (self-assessment). The integration-tester agent independently re-runs the test suite and verifies acceptance criteria — breaking the self-verification cycle. At low risk, Phase 4b's quality-gate-sequence is sufficient.
If sub-agents are NOT available: Complete self-review checklist manually. Do NOT skip quality checks.
Error learning: If self-review caught a wrong approach requiring significant rework, invoke the record-failure micro-component from .claude/prompts/record-failure.md.
4b. Quality Gates
Run the quality-gate-sequence micro-component from .claude/prompts/quality-gate-sequence.md: execute the project's quality commands (from CLAUDE.md Commands section) in order: lint → typecheck → test. Stop on first failure, fix, and re-run.
<IF condition="test command exists in CLAUDE.md Commands">
Execute the configured quality commands. Verify all pass with zero failures.
</IF>
<ELSE>
Run any configured commands (lint, typecheck). No test command configured — skip test verification, note in completion report.
</ELSE><HARD-GATE>
Do NOT proceed to Phase 4c/4d until ALL configured quality gates pass with zero failures. Show the passing output in the current turn. "It passed earlier" is not evidence — re-run if any code changed since the last run.
</HARD-GATE>4c. Generate UAT Test Case (Optional)
Applies to: Feature and Bug Fix stories that affect user-visible behavior, AND the project has UAT tracking (docs/testing/UAT_COVERAGE.md, docs/testing/uat/, or tests/uat/).
Skip for: Spike/Research, Infrastructure, Documentation, Testing, Refactoring, Performance, Skill/Tooling stories. Also skip if no UAT file or directory exists in the project.
- Find UAT location: Check for
docs/testing/UAT_COVERAGE.md(single-file),docs/testing/uat/(directory), ortests/uat/scenarios/. If none exists, skip this phase entirely. - Find next UAT ID: Search for
### UAT-headings in existing files, increment the highest number, format asUAT-###(zero-padded to 3 digits). - Generate test case matching the template format in UAT_COVERAGE.md:
### UAT-NNN: [Title derived from story]**Priority:** [risk-based] | **Type:** [positive|negative|boundary] | **Covers:** [Story IDs] | **Tags:** [relevant tags]**Setup:**— preconditions from story context**Given**/**When**/**Then**/**And**— one per acceptance criterion; create multiple test cases if an AC needs multiple scenarios**Test Data:**table if applicable**Status:** ⬜ Untested/**Tested On:** —/**Findings:** —**Claude Sense Check**and**Human UAT Check**checkbox sections#### Resultsappend-only table with initial⬜ Untestedrow
- Write the test case:
- Single file (
docs/testing/UAT_COVERAGE.md): Append before the## Referencesection - Directory (
docs/testing/uat/ortests/uat/): Create a new file following existing naming convention
- Single file (
- Update Dashboard: Increment "Total Test Cases" and "⬜ Untested" counts in the Dashboard table
4c.1. Sense Check UAT Case (Optional)
Applies when: A UAT test case was generated in Phase 4c. Skip when: No UAT case was generated.
Since the implementation code is fresh in context, immediately verify the UAT case logic:
- Trace each UAT step through the code just written:
- Does the action map to a real UI element / API endpoint / code path?
- Is the assertion verifiable from the implementation?
- Are there any steps that reference behavior not actually implemented?
- Verify acceptance criteria coverage:
- Each UAT acceptance criterion should correspond to tested, reachable code
- Flag any criterion that assumes functionality beyond what was built
- Assign verdict:
- Pass — all steps and criteria trace to working code
- Warning — potential gap found; note the issue in the UAT file and fix if trivial
- Fail — step references non-existent behavior; fix the UAT case (not the code — the code was already tested)
- Update the UAT file:
- Check the box:
- [x] Logic verified from code perspective - Fill in Notes with verdict and what was checked
- Check the box:
4d. Completion Verification
Re-read the original acceptance criteria from the plan. For each criterion, provide concrete evidence: test output, code reference (file:line), or command output.
<LOOP max="2" until="all acceptance criteria have evidence">
If any criterion lacks evidence: identify the gap, loop back to Phase 3 for that specific item, re-verify.
</LOOP><HALT reason="max verification loops exhausted">
Report what IS complete with evidence, list remaining gaps.Checkpoint Rollback Option: If verification has failed after 2 loop passes and the implementation appears fundamentally flawed (not just minor gaps), offer the user a rollback:
Verification failed after 2 passes. Options:
[R] Rollback — restore to pre-implementation checkpoint (git tag from Phase 3.pre) and re-plan
[C] Continue — keep current code and address remaining gaps in next session
[F] Force complete — mark as done with known gaps documentedIf [R]: git stash push --include-untracked -m "story-cycle: checkpoint rollback" && git reset --soft <checkpoint-tag> && git restore . && git tag -d <checkpoint-tag>. Clear .failure-state.md. Suggest re-entering Phase 1 with lessons learned.
If [C]: Save state to .failure-state.md for /continue pickup.
If [F]: Document gaps in completion report, proceed to Phase 4e.
</HALT>
<HARD-GATE>
Do NOT print the completion report until every acceptance criterion has been verified with evidence. Show test output or code references — not assertions.
</HARD-GATE>4e. Docs + Commit
- Capture story outcome: Run the
capture-outcomemicro-component from.claude/prompts/capture-outcome.mdto record measurable deltas (lines added/removed, test count, coverage, new deps) todocs/sessions/.story-outcomes.tsv. Skip for Spike/Research and Documentation stories. - Update epic file (
docs/reference/backlog/E##-*.md):- In story checklist: change
- [ ] ID — Title (P#, in-progress)→- [ ] ID — Title (P#, review) - In story detail section: update
**Status:** review - Legacy format: mark as
[DONE]if epic uses old markers - Check all acceptance criteria boxes in the detail section (
- [ ]→- [x]) - Emit story lifecycle event:
echo "{\"type\":\"story\",\"event\":\"status-change\",\"id\":\"<id>\",\"from\":\"in-progress\",\"to\":\"review\",\"story_type\":\"<type>\",\"size\":\"<size>\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" >> docs/sessions/.activity-log.jsonl
- In story checklist: change
- Update
docs/reference/BACKLOG_INDEX.md: Update story counts per priority group in the status table. - Update
docs/progress.mdwith story status (✅) 4.5. Update sprint spec (docs/sprints/sprint-<N>.md): set this story's Status to ✅ and Session column to today's date (YYYY-MM-DD). This creates the session-to-sprint mapping needed for cycle time calculation and retrospective analysis. - Update documentation only if the story's AC requires it
- Architecture documentation check: Read the Update Triggers section of
docs/architecture/ARCHITECTURE.md. If ANY trigger matches changes in this story (git diff --name-only), update the relevant sections and setLast Verifieddate to today. Also:- If a non-obvious gotcha was discovered during implementation → add to Known Landmines
- If a significant architectural choice was made → add to Key Decisions with trade-off
- If no Update Trigger matches, skip
- Capture learnings (optional): If non-obvious patterns discovered, run the
capture-learningsmicro-component from.claude/prompts/capture-learnings.mdto save todocs/solutions/<topic-slug>.md - Clean up checkpoint: Delete the git checkpoint tag from Phase 3.pre:
git tag -l 'story-checkpoint-*' | xargs -r git tag -d - Commit: Invoke the
/commitskill. Do NOT merge or create PR — that's/sprint-end's job.
Skill metrics: Emit a completion event:
echo "{\"type\":\"skill\",\"event\":\"end\",\"skill\":\"story-cycle\",\"outcome\":\"success\",\"story\":\"$ARGUMENTS\",\"ts\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"}" >> docs/sessions/.activity-log.jsonlCompletion Report
### Story Complete
**Story:** [description]
**Type:** [story type]
**Approach:** [methodology used]
**Files modified:** [list]
**Tests:** [count] passing, [new tests added]
**Commit:** [hash and message]
**Verification:** [All N acceptance criteria verified — see evidence above]
**Next Steps:**
→ `/story-cycle "[next story from backlog]"` — deliver the next story
→ `/sprint-end` — if this was the last story in the sprint
→ `/handoff` — if ending the sessionRecovery
For phase-specific error recovery, consult references/error-recovery.md — search for the relevant ## Phase N section.
General recovery:
- Test failure (new code): Read the error, fix the implementation, re-run. Do not weaken the test.
- Test failure (pre-existing): Inform user. Do not mask it. Log to
docs/technical-debt.mdif out of scope. - Context exhaustion: Save current progress to
docs/plans/, commit work-in-progress, inform user to start a new session with/continue. - Git conflict: Show conflict to user. Do NOT auto-resolve without approval.
- Skill not found: If a required skill (e.g.,
/code-quality) is not available, skip it and note in the completion report. - Implementation fundamentally wrong: If Phase 4 reveals the approach is flawed, use the checkpoint rollback option (Phase 4d) to cleanly revert to pre-implementation state.
Rules
- NEVER skip the plan phase — always enter plan mode first
- NEVER carry exploration context into execution — clear and reload
- NEVER merge to main or create a PR — that's sprint-end
- NEVER add features not in the acceptance criteria
- NEVER weaken or delete existing tests
- Follow coding standards in
docs/reference/CODING_STANDARDS.md - Follow testing strategy in
docs/reference/TESTING_STRATEGY.md - Follow architecture constraints in
docs/architecture/ARCHITECTURE.md - Follow project ground rules in
docs/reference/GROUND_RULES.md(if exists)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

