Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
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 → DONE
**Lean mode active.** Simplified workflow: Plan (optional for SMALL) -> Build -> Verify.
**Strict mode active.** Maximum rigor for all story sizes.
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.
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]."
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?"
**Red flag:** If editing multiple files or changing observable behavior, STOP and reclassify as STANDARD. Fast-track is for genuinely trivial changes only.
**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.
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.
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`).
Present questions to user. Integrate answers into the plan. Remove resolved `[NEEDS CLARIFICATION]` markers.
**POST-PLAN-MODE EXECUTION — THIS IS NOT OPTIONAL**
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.
Do NOT skip the readiness gate for ANY story size except TRIVIAL. Output the 5-check results before proceeding to Phase 3.
Analyze the approved plan for parallel execution opportunities. Read `references/parallel-streams.md` for the full protocol.
Skip — proceed directly to Phase 3.
**TDD Ordering Enforcement (Feature, Bug Fix, Refactoring stories):**
Do NOT skip self-review for ANY story size. If any checklist item fails, go back to Phase 3 and fix before continuing.
**Strict override:** Dispatch `/quality-check --all` for ALL stories regardless of risk level. Integration-tester is mandatory for all stories.
**Lean override:** Skip quality agent dispatch. Phase 4b quality-gate-sequence (lint + test) is sufficient.
Execute the configured quality commands. Verify all pass with zero failures.
Run any configured commands (lint, typecheck). No test command configured — skip test verification, note in completion report.
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.
If any criterion lacks evidence: identify the gap, loop back to Phase 3 for that specific item, re-verify.
Report what IS complete with evidence, list remaining gaps.
Do NOT print the completion report until every acceptance criterion has been verified with evidence. Show test output or code references — not assertions.
Profile-Adaptive Behavior
Read the **Profile:** line from CLAUDE.md to determine the active project profile.
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-check with 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.
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 --all for 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:
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_steps list — 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: Title with inline metadata
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 /ideate to 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:
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 /handoff at 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
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)
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
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 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:
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.md exists 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.md files in the target directory and parent directories — these contain module-specific patterns and conventions that supplement global CLAUDE.md
1c.5. Online Verification
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, WebSearch for: "<library> <pinned-version> deprecation OR breaking change OR CVE" (batch into 1-2 searches)
If a result looks relevant, WebFetch the 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:
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.
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).
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.
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:
Execute the remaining_steps from 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.
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_exploration reasoning tool and elicitation techniques from references/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.
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., ## Python or ## TypeScript), plus the ## Universal Conventions and ## AI-Specific Anti-Patterns sections. Skip other language sections.
docs/reference/TESTING_STRATEGY.md — load ONLY the ## Test Infrastructure section (project-specific commands) and the section matching the story type (e.g., ## Feature Story or ## 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
Phase 3a: Parallel Stream Analysis (Optional)
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
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)" HEAD
Record 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 up
Intermediate 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.
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.
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).
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.
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)
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.
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), or tests/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 as UAT-### (zero-padded to 3 digits).
Generate test case matching the template format in UAT_COVERAGE.md:
**Claude Sense Check** and **Human UAT Check** checkbox sections
#### Results append-only table with initial ⬜ Untested row
Write the test case:
Single file (docs/testing/UAT_COVERAGE.md): Append before the ## Reference section
Directory (docs/testing/uat/ or tests/uat/): Create a new file following existing naming convention
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
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.
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 documented
If [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.
4e. Docs + Commit
Capture story outcome: Run the capture-outcome micro-component from .claude/prompts/capture-outcome.md to record measurable deltas (lines added/removed, test count, coverage, new deps) to docs/sessions/.story-outcomes.tsv. Skip for Spike/Research and Documentation stories.
Update docs/reference/BACKLOG_INDEX.md: Update story counts per priority group in the status table.
Update docs/progress.md with 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 set Last Verified date 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-learnings micro-component from .claude/prompts/capture-learnings.md to save to docs/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 /commit skill. Do NOT merge or create PR — that's /sprint-end's job.
### 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 session
Recovery
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.md if 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)
