| name | phase |
| version | 2.0 |
| category | utilities |
| execution_speed | medium |
| token_efficiency | medium |
| triggers | ["what phase are we in?","phase status","phase transition","ADR impact analysis","project lifecycle"] |
| cache_key | phase-2.0 |
| dependencies | [] |
| disable-model-invocation | true |
| description | Track project phase lifecycle: status snapshots, transitions, and ADR impact analysis. Trigger on: "what phase are we in?", "is phase X unblocked?", "did ADR-### move any phase?", "give me a status snapshot", "what's next?", "what's blocked?", "phase status", creating or editing phase documents, or comparing phase state across plan revisions. Project-agnostic -- binds to any project with a Phase Registry. Backed by Karpathy principles: surface state truthfully, no silent assumptions.
|
Phase -- Project Phase Lifecycle Tracking
Project-agnostic phase lifecycle governance.
Enforces a canonical status lexicon and single-FOCUS invariant.
Binds to the active project at invocation time.
Resilience (checkpoint + resume)
Follow the global Long-Workflow Resilience rule (CLAUDE.md): for a long phase sweep or multi-phase transition, after each phase write progress to .claude/state/phase-progress.md, and on an API error (500, 529 overload, usage limit) stop cleanly and name the phase to resume from instead of restarting. A single /phase snapshot is short -- graceful stop is enough.
Initiation
Commands
| Command | What It Does |
|---|
/phase | Current phase snapshot (short form, ≤12 lines) |
/phase status | Same as above |
/phase transition [##] | Record and validate a phase status change |
/phase impact [adr-###] | Show which phases an ADR touches |
/phase audit | Check Phase Registry for invariant violations (run .claude/skills/phase/check-focus-invariant.sh first) |
/phase long | Full report -- all phases, all criteria, all notes |
Project Binding
Resolves the Phase Registry in this order:
- User names the project or path explicitly
CLAUDE.md or AGENTS.md declares a phase-status: pointer (e.g., phase-status: docs/phase-status/INDEX.md)- Search working directory for
docs/phase-status/INDEX.md
- Default assumption:
docs/phase-status/
- If none found: halt and ask before answering any status question
Once bound, this project's registry is authoritative for the session.
Switching projects mid-session requires an explicit re-bind.
Status Lexicon
Six legal values. No synonyms. No abbreviations.
Forbidden: IN_PROGRESS, DONE, WIP, TODO, STUCK, SOMEWHAT_DONE.
Map any of these to the lexicon below or reject them.
| Status | Meaning |
|---|
| DORMANT | Phase exists but is not yet runnable. Dependencies unresolved. |
| UNBLOCKED | All gating ADRs ratified. Engineering may start. No active work yet. |
| ACTIVE | Under construction. Code in flight. Acceptance criteria open. |
| FOCUS | Current control point. The output the rest of the project depends on right now. At most one phase may hold FOCUS at any time. |
| COMPLETE | Exit criteria met. Locked against regression. Outputs treated as truth. |
| SUPERSEDED | Replaced or removed. Preserved for history only. Never re-entered. |
Transition Rules
Phases move forward only. SUPERSEDED is terminal.
DORMANT ──► UNBLOCKED ──► ACTIVE ──► FOCUS ──► COMPLETE
│ │ │ │ │
└──────────────┴────────────┴──────────┴──────► SUPERSEDED
| Transition | Required Evidence |
|---|
| DORMANT → UNBLOCKED | All gating ADRs in ACCEPTED status |
| UNBLOCKED → ACTIVE | First commit referencing phase ID, or scoped sprint kickoff |
| ACTIVE → FOCUS | At most one FOCUS at a time; promoting a new FOCUS forces the prior FOCUS to attempt COMPLETE |
| FOCUS → COMPLETE | All P0 acceptance criteria pass; results recorded |
| any → SUPERSEDED | Explicit ADR or Plan revision that supersedes the phase |
Hard rule: If two phases claim FOCUS, halt and force disambiguation before answering any further status questions.
Phase Registry Format
Maintained at docs/phase-status/INDEX.md. Single source of truth.
All other documents defer to it on conflict.
# Phase Registry
| Phase | Title | Status | Gating ADRs | Source |
|-------|-------|--------|-------------|--------|
| 01 | [Phase title] | COMPLETE | -- | Plan v1.0 |
| 02 | [Phase title] | FOCUS | ADR-001, ADR-002 | Plan v1.1 |
| 03 | [Phase title] | UNBLOCKED | ADR-003 | Plan v1.1 |
| 04 | [Phase title] | DORMANT | ADR-004 (pending) | -- |
Update this table first. Prose updates follow. Never the reverse.
ADR → Phase Impact Matrix
Maintained at docs/phase-status/IMPACT-MATRIX.md.
# ADR → Phase Impact Matrix
| ADR | Title | Phases Touched | Effect |
|-----|-------|----------------|--------|
| ADR-001 | [Title] | 02 | DORMANT → UNBLOCKED |
| ADR-002 | [Title] | 02, 03 | 03 created (DORMANT) |
| ADR-003 | [Title] | 03 | UNBLOCKED gate met |
Rule: An ADR ratification is incomplete until this matrix is updated.
/phase Snapshot Format
FOCUS: Phase 03 -- [title]. [One-line state description.]
ACTIVE: Phase 04, Phase 05.
UNBLOCKED: Phase 06 -- ADR-007 cleared last week.
DORMANT: Phase 07 (waiting: ADR-009), Phase 08 (waiting: ADR-010, ADR-011).
COMPLETE: Phases 01-02 locked.
Keep snapshots under 12 lines. Long form only on /phase long.
/phase transition [##] Record
# Phase ## -- [Title]
**Previous Status:** [DORMANT|UNBLOCKED|ACTIVE|FOCUS|COMPLETE]
**Current Status:** [UNBLOCKED|ACTIVE|FOCUS|COMPLETE|SUPERSEDED]
**Transition Date:** YYYY-MM-DD
**Triggering ADR(s):** ADR-###
## Why This Transition
[One paragraph. Cite the gate satisfied. No marketing language.]
## Exit Criteria (FOCUS → COMPLETE only)
| Criterion | Description | Pass / Open |
|-----------|-------------|-------------|
| C##-01 | … | ✅ / ⏳ |
## Downstream Effects
- Phase ## moves [DORMANT → UNBLOCKED] because [reason].
## Checklist
- [ ] Phase Registry table updated
- [ ] Only one phase holds FOCUS
- [ ] Status value is from the legal lexicon
- [ ] Triggering ADR is ACCEPTED (not PROPOSED)
- [ ] All P0 criteria recorded (for FOCUS → COMPLETE)
- [ ] Impact Matrix updated
- [ ] Downstream phases re-evaluated in the same change
Conflict Resolution
When Plan, Requirements, and ADRs disagree on a phase's status:
- Most recently
ACCEPTED ADR
- Most recent Requirements version
- Project Plan
- Memory or inferred state -- never used as primary evidence
If precedence cannot resolve: halt and ask rather than guess.
Karpathy Principles Applied
See /karpathy for guidelines. Applied here:
- G1: Read the registry before answering phase questions. No inferring from conversation history.
- G2: Default to snapshot. Long form only on explicit request. One transition per record.
- G3: Touch only the phases involved. Don't rewrite unrelated rows.
- G4 Done: Registry updated ✅ · Impact Matrix updated ✅ · One-FOCUS invariant holds ✅
