feat: evolutionary PROJECT.md system
PROJECT.md evolves throughout project lifecycle: - Requirements have states: Validated, Active, Out of Scope - Decisions track outcomes: Good, Revisit, Pending - Phase transitions update requirements and log decisions - Milestone completions trigger full PROJECT.md review STATE.md now references PROJECT.md (not a copy): - Claude reads PROJECT.md directly for full context - Smaller STATE.md footprint (~100 lines) - Project Reference section with core value and focus Brownfield projects infer Validated requirements from existing code. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
@@ -8,24 +8,28 @@ allowed-tools:
|
||||
---
|
||||
|
||||
<objective>
|
||||
|
||||
Initialize a new project through comprehensive context gathering.
|
||||
|
||||
This is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes.
|
||||
|
||||
Creates `.planning/` with PROJECT.md and config.json.
|
||||
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
|
||||
@~/.claude/get-shit-done/references/principles.md
|
||||
@~/.claude/get-shit-done/references/questioning.md
|
||||
@~/.claude/get-shit-done/templates/project.md
|
||||
@~/.claude/get-shit-done/templates/config.json
|
||||
</execution_context>
|
||||
|
||||
</execution_context>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="setup">
|
||||
|
||||
**MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
|
||||
|
||||
1. **Abort if project exists:**
|
||||
@@ -53,9 +57,11 @@ Creates `.planning/` with PROJECT.md and config.json.
|
||||
```
|
||||
|
||||
**You MUST run all bash commands above using the Bash tool before proceeding.**
|
||||
|
||||
</step>
|
||||
|
||||
<step name="brownfield_offer">
|
||||
|
||||
**If existing code detected and .planning/codebase/ doesn't exist:**
|
||||
|
||||
Check the results from setup step:
|
||||
@@ -66,8 +72,8 @@ Use AskUserQuestion:
|
||||
- header: "Existing Code"
|
||||
- question: "I detected existing code in this directory. Would you like to map the codebase first?"
|
||||
- options:
|
||||
- "Map codebase first" - Run /gsd:map-codebase to understand existing architecture (Recommended)
|
||||
- "Skip mapping" - Proceed with project initialization
|
||||
- "Map codebase first" — Run /gsd:map-codebase to understand existing architecture (Recommended)
|
||||
- "Skip mapping" — Proceed with project initialization
|
||||
|
||||
**If "Map codebase first":**
|
||||
```
|
||||
@@ -78,10 +84,12 @@ Exit command.
|
||||
**If "Skip mapping":** Continue to question step.
|
||||
|
||||
**If no existing code detected OR codebase already mapped:** Continue to question step.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="question">
|
||||
**1. Open (FREEFORM - do NOT use AskUserQuestion):**
|
||||
|
||||
**1. Open (FREEFORM — do NOT use AskUserQuestion):**
|
||||
|
||||
Ask inline: "What do you want to build?"
|
||||
|
||||
@@ -121,22 +129,97 @@ Use AskUserQuestion:
|
||||
- header: "Ready?"
|
||||
- question: "Ready to create PROJECT.md, or explore more?"
|
||||
- options (ALL THREE REQUIRED):
|
||||
- "Create PROJECT.md" - Finalize and continue
|
||||
- "Ask more questions" - I'll dig deeper
|
||||
- "Let me add context" - You have more to share
|
||||
- "Create PROJECT.md" — Finalize and continue
|
||||
- "Ask more questions" — I'll dig deeper
|
||||
- "Let me add context" — You have more to share
|
||||
|
||||
If "Ask more questions" → check coverage gaps from `questioning.md` → return to step 2.
|
||||
If "Let me add context" → receive input via their response → return to step 2.
|
||||
Loop until "Create PROJECT.md" selected.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="project">
|
||||
|
||||
Synthesize all context into `.planning/PROJECT.md` using the template from `templates/project.md`.
|
||||
|
||||
**For greenfield projects:**
|
||||
|
||||
Initialize requirements as hypotheses:
|
||||
|
||||
```markdown
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
(None yet — ship to validate)
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] [Requirement 1]
|
||||
- [ ] [Requirement 2]
|
||||
- [ ] [Requirement 3]
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- [Exclusion 1] — [why]
|
||||
- [Exclusion 2] — [why]
|
||||
```
|
||||
|
||||
All Active requirements are hypotheses until shipped and validated.
|
||||
|
||||
**For brownfield projects (codebase map exists):**
|
||||
|
||||
Infer Validated requirements from existing code:
|
||||
|
||||
1. Read `.planning/codebase/ARCHITECTURE.md` and `STACK.md`
|
||||
2. Identify what the codebase already does
|
||||
3. These become the initial Validated set
|
||||
|
||||
```markdown
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
- ✓ [Existing capability 1] — existing
|
||||
- ✓ [Existing capability 2] — existing
|
||||
- ✓ [Existing capability 3] — existing
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] [New requirement 1]
|
||||
- [ ] [New requirement 2]
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- [Exclusion 1] — [why]
|
||||
```
|
||||
|
||||
**Key Decisions:**
|
||||
|
||||
Initialize with any decisions made during questioning:
|
||||
|
||||
```markdown
|
||||
## Key Decisions
|
||||
|
||||
| Decision | Rationale | Outcome |
|
||||
|----------|-----------|---------|
|
||||
| [Choice from questioning] | [Why] | — Pending |
|
||||
```
|
||||
|
||||
**Last updated footer:**
|
||||
|
||||
```markdown
|
||||
---
|
||||
*Last updated: [date] after initialization*
|
||||
```
|
||||
|
||||
Do not compress. Capture everything gathered.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="mode">
|
||||
|
||||
Ask workflow mode preference:
|
||||
|
||||
Use AskUserQuestion:
|
||||
@@ -144,13 +227,15 @@ Use AskUserQuestion:
|
||||
- header: "Mode"
|
||||
- question: "How do you want to work?"
|
||||
- options:
|
||||
- "Interactive" - Confirm at each step
|
||||
- "YOLO" - Auto-approve, just execute
|
||||
- "Interactive" — Confirm at each step
|
||||
- "YOLO" — Auto-approve, just execute
|
||||
|
||||
Create `.planning/config.json` with chosen mode using `templates/config.json` structure.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="commit">
|
||||
|
||||
```bash
|
||||
git add .planning/PROJECT.md .planning/config.json
|
||||
git commit -m "$(cat <<'EOF'
|
||||
@@ -158,14 +243,15 @@ docs: initialize [project-name]
|
||||
|
||||
[One-liner from PROJECT.md]
|
||||
|
||||
Creates PROJECT.md with vision and requirements.
|
||||
Creates PROJECT.md with requirements and constraints.
|
||||
EOF
|
||||
)"
|
||||
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
<step name="done">
|
||||
|
||||
Present completion with next steps (see ~/.claude/get-shit-done/references/continuation-format.md):
|
||||
|
||||
```
|
||||
@@ -187,19 +273,25 @@ Project initialized:
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<output>
|
||||
|
||||
- `.planning/PROJECT.md`
|
||||
- `.planning/config.json`
|
||||
|
||||
</output>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
- [ ] Deep questioning completed (not rushed)
|
||||
- [ ] PROJECT.md captures full context
|
||||
- [ ] PROJECT.md captures full context with evolutionary structure
|
||||
- [ ] Requirements initialized as hypotheses (greenfield) or with inferred Validated (brownfield)
|
||||
- [ ] Key Decisions table initialized
|
||||
- [ ] config.json has workflow mode
|
||||
- [ ] All committed to git
|
||||
|
||||
</success_criteria>
|
||||
```
|
||||
|
||||
@@ -38,7 +38,7 @@ If missing STATE.md or ROADMAP.md: inform what's missing, suggest running `/gsd:
|
||||
|
||||
- Read `.planning/STATE.md` for living memory (position, decisions, issues)
|
||||
- Read `.planning/ROADMAP.md` for phase structure and objectives
|
||||
- Read `.planning/PROJECT.md` for project vision (brief summary only)
|
||||
- Read `.planning/PROJECT.md` for current state (What This Is, Core Value, Requirements)
|
||||
</step>
|
||||
|
||||
<step name="recent">
|
||||
|
||||
@@ -1,207 +1,184 @@
|
||||
# PROJECT.md Template
|
||||
|
||||
Template for `.planning/PROJECT.md` - the full project context captured during initialization.
|
||||
Template for `.planning/PROJECT.md` — the living project context document.
|
||||
|
||||
## Greenfield Project (v1.0)
|
||||
<template>
|
||||
|
||||
```markdown
|
||||
# [Project Name]
|
||||
|
||||
## Vision
|
||||
## What This Is
|
||||
|
||||
[What this is and why it matters. 2-4 paragraphs capturing the full picture.
|
||||
Use the user's language and framing. Include motivation, not just description.
|
||||
This should feel like the user explaining their project to a smart collaborator.]
|
||||
[Current accurate description — 2-3 sentences. What does this product do and who is it for?
|
||||
Use the user's language and framing. Update whenever reality drifts from this description.]
|
||||
|
||||
## Problem
|
||||
## Core Value
|
||||
|
||||
[What problem exists, who has it, why it matters, what the current state is.
|
||||
Be specific - vague problems lead to vague solutions.
|
||||
Include the pain, the gap, or the opportunity that makes this worth building.]
|
||||
[The ONE thing that matters most. If everything else fails, this must work.
|
||||
One sentence that drives prioritization when tradeoffs arise.]
|
||||
|
||||
## Success Criteria
|
||||
## Requirements
|
||||
|
||||
How we know this worked:
|
||||
### Validated
|
||||
|
||||
- [ ] [Measurable outcome 1 - specific, verifiable]
|
||||
- [ ] [Measurable outcome 2 - specific, verifiable]
|
||||
- [ ] [Measurable outcome 3 - specific, verifiable]
|
||||
- [ ] [Add as many as genuinely needed]
|
||||
<!-- Shipped and confirmed valuable. -->
|
||||
|
||||
## Scope
|
||||
(None yet — ship to validate)
|
||||
|
||||
### Building
|
||||
- [Feature/capability 1]
|
||||
- [Feature/capability 2]
|
||||
- [Feature/capability 3]
|
||||
### Active
|
||||
|
||||
### Not Building
|
||||
- [Explicit exclusion 1 - prevents scope creep]
|
||||
- [Explicit exclusion 2 - clarifies boundaries]
|
||||
- [Explicit exclusion 3 - manages expectations]
|
||||
<!-- Current scope. Building toward these. -->
|
||||
|
||||
- [ ] [Requirement 1]
|
||||
- [ ] [Requirement 2]
|
||||
- [ ] [Requirement 3]
|
||||
|
||||
### Out of Scope
|
||||
|
||||
<!-- Explicit boundaries. Includes reasoning to prevent re-adding. -->
|
||||
|
||||
- [Exclusion 1] — [why]
|
||||
- [Exclusion 2] — [why]
|
||||
|
||||
## Context
|
||||
|
||||
[Background information that informs implementation:
|
||||
- Current state (greenfield)
|
||||
- Technical environment or ecosystem
|
||||
- Relevant prior work or experience
|
||||
- Technical environment or ecosystem context
|
||||
- Explored alternatives and why they were rejected]
|
||||
- User research or feedback themes
|
||||
- Known issues to address]
|
||||
|
||||
## Constraints
|
||||
|
||||
- **[Constraint type]**: [What] - [Why]
|
||||
- **[Constraint type]**: [What] - [Why]
|
||||
- **[Constraint type]**: [What] - [Why]
|
||||
- **[Type]**: [What] — [Why]
|
||||
- **[Type]**: [What] — [Why]
|
||||
|
||||
Common types: Tech stack, Timeline, Resources, Dependencies, Compatibility, Performance, Security
|
||||
Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security
|
||||
|
||||
## Decisions Made
|
||||
## Key Decisions
|
||||
|
||||
Key decisions from project exploration:
|
||||
<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
|
||||
|
||||
| Decision | Choice | Rationale |
|
||||
|----------|--------|-----------|
|
||||
| [Area/Topic] | [What we decided] | [Why this choice] |
|
||||
| [Area/Topic] | [What we decided] | [Why this choice] |
|
||||
|
||||
## Open Questions
|
||||
|
||||
Things to figure out during execution:
|
||||
|
||||
- [ ] [Question 1 - known unknown to resolve]
|
||||
- [ ] [Question 2 - decision to make later]
|
||||
- [ ] [Question 3 - area needing research]
|
||||
| Decision | Rationale | Outcome |
|
||||
|----------|-----------|---------|
|
||||
| [Choice] | [Why] | [✓ Good / ⚠️ Revisit / — Pending] |
|
||||
|
||||
---
|
||||
*Initialized: [date]*
|
||||
*Last updated: [date] after [trigger]*
|
||||
```
|
||||
|
||||
## Brownfield Project (v1.1+)
|
||||
|
||||
After shipping v1.0, update PROJECT.md to include current state:
|
||||
|
||||
```markdown
|
||||
# [Project Name]
|
||||
|
||||
## Current State (Updated: YYYY-MM-DD)
|
||||
|
||||
**Shipped:** v[X.Y] [Name] (YYYY-MM-DD)
|
||||
**Status:** [Production / Beta / Internal / Live with users]
|
||||
**Users:** [If known: "~500 downloads, 50 DAU" or "Internal use only" or "N/A"]
|
||||
**Feedback:** [Key themes from user feedback, or "Initial release, gathering feedback"]
|
||||
|
||||
**Codebase:**
|
||||
- [X,XXX] lines of [primary language]
|
||||
- [Key tech stack: framework, platform, deployment target]
|
||||
- [Notable dependencies or architecture]
|
||||
|
||||
**Known Issues:**
|
||||
- [Issue 1 from v1.x that needs addressing]
|
||||
- [Issue 2]
|
||||
- [Or "None" if clean slate]
|
||||
|
||||
## v[Next] Goals
|
||||
|
||||
**Vision:** [What's the goal for this next iteration?]
|
||||
|
||||
**Motivation:**
|
||||
- [Why this work matters now]
|
||||
- [User feedback driving it]
|
||||
- [Technical debt or improvements needed]
|
||||
|
||||
**Scope (v[X.Y]):**
|
||||
- [Feature/improvement 1]
|
||||
- [Feature/improvement 2]
|
||||
- [Feature/improvement 3]
|
||||
|
||||
**Success Criteria:**
|
||||
- [ ] [Measurable outcome 1]
|
||||
- [ ] [Measurable outcome 2]
|
||||
- [ ] [Measurable outcome 3]
|
||||
|
||||
**Not Building (this version):**
|
||||
- [Not doing X in this version]
|
||||
- [Not doing Y in this version]
|
||||
|
||||
## Constraints
|
||||
|
||||
- **[Constraint type]**: [What] - [Why]
|
||||
- **[Constraint type]**: [What] - [Why]
|
||||
|
||||
## Open Questions
|
||||
|
||||
- [ ] [Question for this version]
|
||||
- [ ] [Question for this version]
|
||||
|
||||
---
|
||||
|
||||
<details>
|
||||
<summary>Original Vision (v1.0 - Archived)</summary>
|
||||
|
||||
## Vision
|
||||
|
||||
[Original vision content]
|
||||
|
||||
## Problem
|
||||
|
||||
[Original problem statement]
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [x] [Outcome 1] - Achieved
|
||||
- [x] [Outcome 2] - Achieved
|
||||
- [x] [Outcome 3] - Achieved
|
||||
|
||||
## Scope
|
||||
|
||||
### Built
|
||||
- [What was built]
|
||||
|
||||
### Not Built
|
||||
- [What was excluded]
|
||||
|
||||
## Context
|
||||
|
||||
[Original context]
|
||||
|
||||
## Constraints
|
||||
|
||||
[Original constraints]
|
||||
|
||||
## Decisions Made
|
||||
|
||||
[Original decisions table]
|
||||
|
||||
</details>
|
||||
```
|
||||
</template>
|
||||
|
||||
<guidelines>
|
||||
**Greenfield:**
|
||||
- Don't compress - capture everything from questioning
|
||||
- Use user's words - preserve their language and framing
|
||||
- Be specific - vague inputs create vague outputs
|
||||
- Include rationale - "what" without "why" loses context
|
||||
- Mark unknowns - open questions are valuable, not failures
|
||||
|
||||
**Brownfield:**
|
||||
- Current State shows real-world context (shipped, users, feedback)
|
||||
- v[Next] Goals focuses on the upcoming work
|
||||
- Original Vision collapsed in `<details>` for reference
|
||||
- Checkboxes marked [x] for achieved goals
|
||||
- This makes all plans brownfield-aware automatically
|
||||
</guidelines>
|
||||
**What This Is:**
|
||||
- Current accurate description of the product
|
||||
- 2-3 sentences capturing what it does and who it's for
|
||||
- Use the user's words and framing
|
||||
- Update when the product evolves beyond this description
|
||||
|
||||
<state_summary>
|
||||
When creating STATE.md, extract a summary from PROJECT.md:
|
||||
**Core Value:**
|
||||
- The single most important thing
|
||||
- Everything else can fail; this cannot
|
||||
- Drives prioritization when tradeoffs arise
|
||||
- Rarely changes; if it does, it's a significant pivot
|
||||
|
||||
**Building:** [One-liner from Vision]
|
||||
**Requirements — Validated:**
|
||||
- Requirements that shipped and proved valuable
|
||||
- Format: `- ✓ [Requirement] — [version/phase]`
|
||||
- These are locked — changing them requires explicit discussion
|
||||
|
||||
**Core requirements:**
|
||||
- [Top 3 from Success Criteria]
|
||||
**Requirements — Active:**
|
||||
- Current scope being built toward
|
||||
- These are hypotheses until shipped and validated
|
||||
- Move to Validated when shipped, Out of Scope if invalidated
|
||||
|
||||
**Requirements — Out of Scope:**
|
||||
- Explicit boundaries on what we're not building
|
||||
- Always include reasoning (prevents re-adding later)
|
||||
- Includes: considered and rejected, deferred to future, explicitly excluded
|
||||
|
||||
**Context:**
|
||||
- Background that informs implementation decisions
|
||||
- Technical environment, prior work, user feedback
|
||||
- Known issues or technical debt to address
|
||||
- Update as new context emerges
|
||||
|
||||
**Constraints:**
|
||||
- [Key constraints]
|
||||
- Hard limits on implementation choices
|
||||
- Tech stack, timeline, budget, compatibility, dependencies
|
||||
- Include the "why" — constraints without rationale get questioned
|
||||
|
||||
This goes in STATE.md's immutable "Project Summary" section.
|
||||
</state_summary>
|
||||
**Key Decisions:**
|
||||
- Significant choices that affect future work
|
||||
- Add decisions as they're made throughout the project
|
||||
- Track outcome when known:
|
||||
- ✓ Good — decision proved correct
|
||||
- ⚠️ Revisit — decision may need reconsideration
|
||||
- — Pending — too early to evaluate
|
||||
|
||||
**Last Updated:**
|
||||
- Always note when and why the document was updated
|
||||
- Format: `after Phase 2` or `after v1.0 milestone`
|
||||
- Triggers review of whether content is still accurate
|
||||
|
||||
</guidelines>
|
||||
|
||||
<evolution>
|
||||
|
||||
PROJECT.md evolves throughout the project lifecycle.
|
||||
|
||||
**After each phase transition:**
|
||||
1. Requirements invalidated? → Move to Out of Scope with reason
|
||||
2. Requirements validated? → Move to Validated with phase reference
|
||||
3. New requirements emerged? → Add to Active
|
||||
4. Decisions to log? → Add to Key Decisions
|
||||
5. "What This Is" still accurate? → Update if drifted
|
||||
|
||||
**After each milestone:**
|
||||
1. Full review of all sections
|
||||
2. Core Value check — still the right priority?
|
||||
3. Audit Out of Scope — reasons still valid?
|
||||
4. Update Context with current state (users, feedback, metrics)
|
||||
|
||||
</evolution>
|
||||
|
||||
<brownfield>
|
||||
|
||||
For existing codebases:
|
||||
|
||||
1. **Map codebase first** via `/gsd:map-codebase`
|
||||
|
||||
2. **Infer Validated requirements** from existing code:
|
||||
- What does the codebase actually do?
|
||||
- What patterns are established?
|
||||
- What's clearly working and relied upon?
|
||||
|
||||
3. **Gather Active requirements** from user:
|
||||
- Present inferred current state
|
||||
- Ask what they want to build next
|
||||
|
||||
4. **Initialize:**
|
||||
- Validated = inferred from existing code
|
||||
- Active = user's goals for this work
|
||||
- Out of Scope = boundaries user specifies
|
||||
- Context = includes current codebase state
|
||||
|
||||
</brownfield>
|
||||
|
||||
<state_reference>
|
||||
|
||||
STATE.md references PROJECT.md:
|
||||
|
||||
```markdown
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated [date])
|
||||
|
||||
**Core value:** [One-liner from Core Value section]
|
||||
**Current focus:** [Current phase name]
|
||||
```
|
||||
|
||||
This ensures Claude reads current PROJECT.md context.
|
||||
|
||||
</state_reference>
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# State Template
|
||||
|
||||
Template for `.planning/STATE.md` - the project's living memory.
|
||||
Template for `.planning/STATE.md` — the project's living memory.
|
||||
|
||||
---
|
||||
|
||||
@@ -9,26 +9,19 @@ Template for `.planning/STATE.md` - the project's living memory.
|
||||
```markdown
|
||||
# Project State
|
||||
|
||||
## Project Summary
|
||||
[IMMUTABLE - Copy verbatim from PROJECT.md on creation. Never edit this section.]
|
||||
## Project Reference
|
||||
|
||||
**Building:** [One-liner from project vision]
|
||||
See: .planning/PROJECT.md (updated [date])
|
||||
|
||||
**Core requirements:**
|
||||
- [Requirement 1]
|
||||
- [Requirement 2]
|
||||
- [Requirement 3]
|
||||
|
||||
**Constraints:**
|
||||
- [Key constraint 1]
|
||||
- [Key constraint 2]
|
||||
**Core value:** [One-liner from PROJECT.md Core Value section]
|
||||
**Current focus:** [Current phase name]
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: [X] of [Y] ([Phase name])
|
||||
Plan: [A] of [B] in current phase
|
||||
Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
|
||||
Last activity: [YYYY-MM-DD] - [What happened]
|
||||
Last activity: [YYYY-MM-DD] — [What happened]
|
||||
|
||||
Progress: [░░░░░░░░░░] 0%
|
||||
|
||||
@@ -53,31 +46,26 @@ Progress: [░░░░░░░░░░] 0%
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
### Decisions Made
|
||||
### Decisions
|
||||
|
||||
| Phase | Decision | Rationale |
|
||||
|-------|----------|-----------|
|
||||
| - | - | - |
|
||||
Decisions are logged in PROJECT.md Key Decisions table.
|
||||
Recent decisions affecting current work:
|
||||
|
||||
- [Phase X]: [Decision summary]
|
||||
- [Phase Y]: [Decision summary]
|
||||
|
||||
### Deferred Issues
|
||||
|
||||
[From ISSUES.md - list open items with phase of origin]
|
||||
[From ISSUES.md — list open items with phase of origin]
|
||||
|
||||
None yet.
|
||||
|
||||
### Blockers/Concerns Carried Forward
|
||||
### Blockers/Concerns
|
||||
|
||||
[From prior "Next Phase Readiness" sections - issues that affect future work]
|
||||
[Issues that affect future work]
|
||||
|
||||
None yet.
|
||||
|
||||
## Project Alignment
|
||||
|
||||
Last checked: [Date or "Project start"]
|
||||
Status: [✓ Aligned / ⚠️ Drift detected / ✗ Misaligned]
|
||||
Assessment: [One line summary]
|
||||
Drift notes: [Details if drift detected, otherwise "None"]
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: [YYYY-MM-DD HH:MM]
|
||||
@@ -86,25 +74,27 @@ Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
|
||||
```
|
||||
|
||||
<purpose>
|
||||
STATE.md is the project's "short-term memory" that spans all phases and sessions.
|
||||
|
||||
**Problem it solves:** Information is captured in summaries, issues, and decisions - but not systematically consumed. Each phase plans in isolation. Sessions start without knowing accumulated context.
|
||||
STATE.md is the project's short-term memory spanning all phases and sessions.
|
||||
|
||||
**Problem it solves:** Information is captured in summaries, issues, and decisions but not systematically consumed. Sessions start without context.
|
||||
|
||||
**Solution:** A single, small file that's:
|
||||
- Always read first (every workflow)
|
||||
- Always updated after work (every execution)
|
||||
- Contains digest of all accumulated wisdom
|
||||
- Enables instant context restoration
|
||||
- Read first in every workflow
|
||||
- Updated after every significant action
|
||||
- Contains digest of accumulated context
|
||||
- Enables instant session restoration
|
||||
|
||||
</purpose>
|
||||
|
||||
<lifecycle>
|
||||
|
||||
**Creation:** After ROADMAP.md is created (during init)
|
||||
- Copy Project Summary from PROJECT.md (immutable after this)
|
||||
- Reference PROJECT.md (read it for current context)
|
||||
- Initialize empty accumulated context sections
|
||||
- Set position to "Phase 1 ready to plan"
|
||||
|
||||
**Reading:** First step of EVERY workflow
|
||||
**Reading:** First step of every workflow
|
||||
- progress: Present status to user
|
||||
- plan: Inform planning decisions
|
||||
- execute: Know current position
|
||||
@@ -113,30 +103,33 @@ STATE.md is the project's "short-term memory" that spans all phases and sessions
|
||||
**Writing:** After every significant action
|
||||
- execute: After SUMMARY.md created
|
||||
- Update position (phase, plan, status)
|
||||
- Extract decisions → add to table
|
||||
- Extract new issues → update deferred list
|
||||
- Extract concerns → add to blockers
|
||||
- Note new decisions (detail in PROJECT.md)
|
||||
- Update deferred issues list
|
||||
- Add blockers/concerns
|
||||
- transition: After phase marked complete
|
||||
- Update progress bar
|
||||
- Clear resolved blockers
|
||||
- alignment-check: After verification
|
||||
- Update alignment status
|
||||
- Refresh Project Reference date
|
||||
|
||||
</lifecycle>
|
||||
|
||||
<sections>
|
||||
|
||||
### Project Summary (Immutable)
|
||||
Copied from PROJECT.md on project initialization. Never edited afterward.
|
||||
Provides constant reference to "what are we building" without re-reading full project doc.
|
||||
### Project Reference
|
||||
Points to PROJECT.md for full context. Includes:
|
||||
- Core value (the ONE thing that matters)
|
||||
- Current focus (which phase)
|
||||
- Last update date (triggers re-read if stale)
|
||||
|
||||
Claude reads PROJECT.md directly for requirements, constraints, and decisions.
|
||||
|
||||
### Current Position
|
||||
Where we are right now:
|
||||
- Phase X of Y - which phase
|
||||
- Plan A of B - which plan within phase
|
||||
- Status - current state
|
||||
- Last activity - what happened most recently
|
||||
- Progress bar - visual indicator of overall completion
|
||||
- Phase X of Y — which phase
|
||||
- Plan A of B — which plan within phase
|
||||
- Status — current state
|
||||
- Last activity — what happened most recently
|
||||
- Progress bar — visual indicator of overall completion
|
||||
|
||||
Progress calculation: (completed plans) / (total plans across all phases) × 100%
|
||||
|
||||
@@ -151,10 +144,7 @@ Updated after each plan completion.
|
||||
|
||||
### Accumulated Context
|
||||
|
||||
**Decisions Made:** Table of significant decisions with rationale.
|
||||
- Extracted from SUMMARY.md "Decisions Made" sections
|
||||
- Include phase number for traceability
|
||||
- These constrain future phases (e.g., "use jose not jsonwebtoken")
|
||||
**Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md.
|
||||
|
||||
**Deferred Issues:** Open items from ISSUES.md
|
||||
- Brief description with ISS-XXX number
|
||||
@@ -167,14 +157,6 @@ Updated after each plan completion.
|
||||
- Prefix with originating phase
|
||||
- Cleared when addressed
|
||||
|
||||
### Project Alignment
|
||||
Tracks whether work matches original requirements:
|
||||
- ✓ Aligned: On track
|
||||
- ⚠️ Drift: Scope creeping or diverging
|
||||
- ✗ Misaligned: Work doesn't serve project goals
|
||||
|
||||
Updated after each phase completion.
|
||||
|
||||
### Session Continuity
|
||||
Enables instant resumption:
|
||||
- When was last session
|
||||
@@ -184,43 +166,45 @@ Enables instant resumption:
|
||||
</sections>
|
||||
|
||||
<size_constraint>
|
||||
Keep STATE.md under 150 lines.
|
||||
|
||||
Keep STATE.md under 100 lines.
|
||||
|
||||
It's a DIGEST, not an archive. If accumulated context grows too large:
|
||||
- Summarize older phase decisions: "Phases 1-2: [key decisions]"
|
||||
- Reference ISSUES.md instead of listing all: "12 open issues - see ISSUES.md"
|
||||
- Keep only active blockers, archive resolved ones
|
||||
- Keep only 3-5 recent decisions in summary (full log in PROJECT.md)
|
||||
- Reference ISSUES.md instead of listing all: "12 open issues — see ISSUES.md"
|
||||
- Keep only active blockers, remove resolved ones
|
||||
|
||||
The goal is "read once, know where we are" — if it's too long, that fails.
|
||||
|
||||
The goal is "read once, know everything" - if it's too long, that fails.
|
||||
</size_constraint>
|
||||
|
||||
<guidelines>
|
||||
|
||||
**When created:**
|
||||
- During project initialization (after ROADMAP.md)
|
||||
- Copy Project Summary from PROJECT.md (never edit this section after creation)
|
||||
- Reference PROJECT.md (extract core value and current focus)
|
||||
- Initialize empty sections
|
||||
|
||||
**When read:**
|
||||
- EVERY workflow starts by reading STATE.md
|
||||
- Every workflow starts by reading STATE.md
|
||||
- Then read PROJECT.md for full context
|
||||
- Provides instant context restoration
|
||||
- Shows current position and accumulated wisdom
|
||||
|
||||
**When updated:**
|
||||
- After each plan execution (update position, extract decisions/issues/blockers)
|
||||
- After phase transitions (update progress bar, clear resolved blockers)
|
||||
- After alignment checks (update alignment status)
|
||||
- After each plan execution (update position, note decisions, update issues/blockers)
|
||||
- After phase transitions (update progress bar, clear resolved blockers, refresh project reference)
|
||||
|
||||
**Size management:**
|
||||
- Keep under 150 lines total
|
||||
- Summarize older decisions if table grows large
|
||||
- Keep under 100 lines total
|
||||
- Recent decisions only in STATE.md (full log in PROJECT.md)
|
||||
- Reference ISSUES.md instead of listing all issues
|
||||
- Keep only active blockers, archive resolved ones
|
||||
- Keep only active blockers
|
||||
|
||||
**Sections:**
|
||||
- Project Summary: Immutable project overview
|
||||
- Project Reference: Pointer to PROJECT.md with core value
|
||||
- Current Position: Where we are now (phase, plan, status)
|
||||
- Performance Metrics: Velocity tracking
|
||||
- Accumulated Context: Decisions, deferred issues, blockers
|
||||
- Project Alignment: Are we on track with original vision?
|
||||
- Accumulated Context: Recent decisions, deferred issues, blockers
|
||||
- Session Continuity: Resume information
|
||||
|
||||
</guidelines>
|
||||
|
||||
@@ -1,25 +1,31 @@
|
||||
<purpose>
|
||||
Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, updates PROJECT.md with current state, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
|
||||
|
||||
Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
|
||||
|
||||
This is the ritual that separates "development" from "shipped."
|
||||
|
||||
</purpose>
|
||||
|
||||
<required_reading>
|
||||
|
||||
**Read these files NOW:**
|
||||
|
||||
1. templates/milestone.md
|
||||
2. templates/milestone-archive.md
|
||||
3. `.planning/ROADMAP.md`
|
||||
4. `.planning/PROJECT.md`
|
||||
</required_reading>
|
||||
|
||||
</required_reading>
|
||||
|
||||
<archival_behavior>
|
||||
|
||||
When a milestone completes, this workflow:
|
||||
|
||||
1. Extracts full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
|
||||
2. Updates ROADMAP.md to replace milestone details with one-line summary
|
||||
3. Links to archive file for historical reference
|
||||
4. Offers to create next milestone inline
|
||||
4. Performs full PROJECT.md evolution review
|
||||
5. Offers to create next milestone inline
|
||||
|
||||
**Context Efficiency:**
|
||||
|
||||
@@ -33,11 +39,13 @@ Uses `templates/milestone-archive.md` template with:
|
||||
- Milestone header (status, phases, date)
|
||||
- Full phase details from roadmap
|
||||
- Milestone summary (decisions, issues, technical debt)
|
||||
</archival_behavior>
|
||||
|
||||
</archival_behavior>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="verify_readiness">
|
||||
|
||||
Check if milestone is truly complete:
|
||||
|
||||
```bash
|
||||
@@ -67,12 +75,15 @@ Total: 4 phases, 8 plans, all complete
|
||||
```
|
||||
|
||||
<config-check>
|
||||
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null
|
||||
```
|
||||
|
||||
</config-check>
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
```
|
||||
⚡ Auto-approved: Milestone scope verification
|
||||
|
||||
@@ -82,9 +93,11 @@ Proceeding to stats gathering...
|
||||
```
|
||||
|
||||
Proceed directly to gather_stats step.
|
||||
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_milestone_scope true">
|
||||
|
||||
```
|
||||
Ready to mark this milestone as shipped?
|
||||
(yes / wait / adjust scope)
|
||||
@@ -94,10 +107,13 @@ Wait for confirmation.
|
||||
|
||||
If "adjust scope": Ask which phases should be included.
|
||||
If "wait": Stop, user will return when ready.
|
||||
|
||||
</if>
|
||||
|
||||
</step>
|
||||
|
||||
<step name="gather_stats">
|
||||
|
||||
Calculate milestone statistics:
|
||||
|
||||
```bash
|
||||
@@ -134,6 +150,7 @@ Milestone Stats:
|
||||
</step>
|
||||
|
||||
<step name="extract_accomplishments">
|
||||
|
||||
Read all phase SUMMARY.md files in milestone range:
|
||||
|
||||
```bash
|
||||
@@ -158,6 +175,7 @@ Key accomplishments for this milestone:
|
||||
</step>
|
||||
|
||||
<step name="create_milestone_entry">
|
||||
|
||||
Create or update `.planning/MILESTONES.md`.
|
||||
|
||||
If file doesn't exist:
|
||||
@@ -199,58 +217,152 @@ Use template from `templates/milestone.md`:
|
||||
|
||||
</step>
|
||||
|
||||
<step name="update_project">
|
||||
Update `.planning/PROJECT.md` to reflect current state.
|
||||
<step name="evolve_project_full_review">
|
||||
|
||||
Add/update "Current State" section at top (after YAML if present):
|
||||
Perform full PROJECT.md evolution review at milestone completion.
|
||||
|
||||
```markdown
|
||||
# Project: [Name]
|
||||
**Read all phase summaries in this milestone:**
|
||||
|
||||
## Current State (Updated: YYYY-MM-DD)
|
||||
|
||||
**Shipped:** v[X.Y] [Name] (YYYY-MM-DD)
|
||||
**Status:** [Production / Beta / Internal]
|
||||
**Users:** [If known, e.g., "~500 downloads, 50 DAU" or "Internal use only"]
|
||||
**Feedback:** [Key themes from users, or "Initial release, gathering feedback"]
|
||||
**Codebase:** [LOC] [language], [key tech stack], [platform/deployment target]
|
||||
|
||||
## [Next Milestone] Goals
|
||||
|
||||
**Vision:** [What's the goal for next version?]
|
||||
|
||||
**Motivation:**
|
||||
|
||||
- [Why this next work matters]
|
||||
- [User feedback driving it]
|
||||
- [Technical debt or improvements needed]
|
||||
|
||||
**Scope (v[X.Y]):**
|
||||
|
||||
- [Feature/improvement 1]
|
||||
- [Feature/improvement 2]
|
||||
- [Feature/improvement 3]
|
||||
|
||||
---
|
||||
|
||||
<details>
|
||||
<summary>Original Vision (v1.0 - Archived for reference)</summary>
|
||||
|
||||
[Move original project content here]
|
||||
|
||||
</details>
|
||||
```bash
|
||||
cat .planning/phases/*-*/*-SUMMARY.md
|
||||
```
|
||||
|
||||
**If this is v1.0 (first milestone):**
|
||||
Just add "Current State" section, no need to archive original vision yet.
|
||||
**Full review checklist:**
|
||||
|
||||
**If this is v1.1+:**
|
||||
Collapse previous version's content into `<details>` section.
|
||||
1. **"What This Is" accuracy:**
|
||||
- Read current description
|
||||
- Compare to what was actually built
|
||||
- Update if the product has meaningfully changed
|
||||
|
||||
2. **Core Value check:**
|
||||
- Is the stated core value still the right priority?
|
||||
- Did shipping reveal a different core value?
|
||||
- Update if the ONE thing has shifted
|
||||
|
||||
3. **Requirements audit:**
|
||||
|
||||
**Validated section:**
|
||||
- All Active requirements shipped in this milestone → Move to Validated
|
||||
- Format: `- ✓ [Requirement] — v[X.Y]`
|
||||
|
||||
**Active section:**
|
||||
- Remove requirements that moved to Validated
|
||||
- Add any new requirements for next milestone
|
||||
- Keep requirements that weren't addressed yet
|
||||
|
||||
**Out of Scope audit:**
|
||||
- Review each item — is the reasoning still valid?
|
||||
- Remove items that are no longer relevant
|
||||
- Add any requirements invalidated during this milestone
|
||||
|
||||
4. **Context update:**
|
||||
- Current codebase state (LOC, tech stack)
|
||||
- User feedback themes (if any)
|
||||
- Known issues or technical debt to address
|
||||
|
||||
5. **Key Decisions audit:**
|
||||
- Extract all decisions from milestone phase summaries
|
||||
- Add to Key Decisions table with outcomes where known
|
||||
- Mark ✓ Good, ⚠️ Revisit, or — Pending for each
|
||||
|
||||
6. **Constraints check:**
|
||||
- Any constraints that changed during development?
|
||||
- Update as needed
|
||||
|
||||
**Update PROJECT.md:**
|
||||
|
||||
Make all edits inline. Update "Last updated" footer:
|
||||
|
||||
```markdown
|
||||
---
|
||||
*Last updated: [date] after v[X.Y] milestone*
|
||||
```
|
||||
|
||||
**Example full evolution (v1.0 → v1.1 prep):**
|
||||
|
||||
Before:
|
||||
|
||||
```markdown
|
||||
## What This Is
|
||||
|
||||
A real-time collaborative whiteboard for remote teams.
|
||||
|
||||
## Core Value
|
||||
|
||||
Real-time sync that feels instant.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
(None yet — ship to validate)
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] Canvas drawing tools
|
||||
- [ ] Real-time sync < 500ms
|
||||
- [ ] User authentication
|
||||
- [ ] Export to PNG
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- Mobile app — web-first approach
|
||||
- Video chat — use external tools
|
||||
```
|
||||
|
||||
After v1.0:
|
||||
|
||||
```markdown
|
||||
## What This Is
|
||||
|
||||
A real-time collaborative whiteboard for remote teams with instant sync and drawing tools.
|
||||
|
||||
## Core Value
|
||||
|
||||
Real-time sync that feels instant.
|
||||
|
||||
## Requirements
|
||||
|
||||
### Validated
|
||||
|
||||
- ✓ Canvas drawing tools — v1.0
|
||||
- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
|
||||
- ✓ User authentication — v1.0
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] Export to PNG
|
||||
- [ ] Undo/redo history
|
||||
- [ ] Shape tools (rectangles, circles)
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- Mobile app — web-first approach, PWA works well
|
||||
- Video chat — use external tools
|
||||
- Offline mode — real-time is core value
|
||||
|
||||
## Context
|
||||
|
||||
Shipped v1.0 with 2,400 LOC TypeScript.
|
||||
Tech stack: Next.js, Supabase, Canvas API.
|
||||
Initial user testing showed demand for shape tools.
|
||||
```
|
||||
|
||||
**Step complete when:**
|
||||
|
||||
- [ ] "What This Is" reviewed and updated if needed
|
||||
- [ ] Core Value verified as still correct
|
||||
- [ ] All shipped requirements moved to Validated
|
||||
- [ ] New requirements added to Active for next milestone
|
||||
- [ ] Out of Scope reasoning audited
|
||||
- [ ] Context updated with current state
|
||||
- [ ] All milestone decisions added to Key Decisions
|
||||
- [ ] "Last updated" footer reflects milestone completion
|
||||
|
||||
Show diff of changes:
|
||||
</step>
|
||||
|
||||
<step name="reorganize_roadmap">
|
||||
|
||||
Update `.planning/ROADMAP.md` to group completed milestone phases.
|
||||
|
||||
Add milestone headers and collapse completed work:
|
||||
@@ -260,19 +372,19 @@ Add milestone headers and collapse completed work:
|
||||
|
||||
## Milestones
|
||||
|
||||
- ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD)
|
||||
- 🚧 **v1.1 Security** - Phases 5-6 (in progress)
|
||||
- 📋 **v2.0 Redesign** - Phases 7-10 (planned)
|
||||
- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
|
||||
- 🚧 **v1.1 Security** — Phases 5-6 (in progress)
|
||||
- 📋 **v2.0 Redesign** — Phases 7-10 (planned)
|
||||
|
||||
## Phases
|
||||
|
||||
<details>
|
||||
<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>
|
||||
<summary>✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD</summary>
|
||||
|
||||
- [x] Phase 1: Foundation (2/2 plans) - completed YYYY-MM-DD
|
||||
- [x] Phase 2: Authentication (2/2 plans) - completed YYYY-MM-DD
|
||||
- [x] Phase 3: Core Features (3/3 plans) - completed YYYY-MM-DD
|
||||
- [x] Phase 4: Polish (1/1 plan) - completed YYYY-MM-DD
|
||||
- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD
|
||||
- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD
|
||||
- [x] Phase 3: Core Features (3/3 plans) — completed YYYY-MM-DD
|
||||
- [x] Phase 4: Polish (1/1 plan) — completed YYYY-MM-DD
|
||||
|
||||
</details>
|
||||
|
||||
@@ -296,6 +408,7 @@ Add milestone headers and collapse completed work:
|
||||
</step>
|
||||
|
||||
<step name="archive_milestone">
|
||||
|
||||
Extract completed milestone details and create archive file.
|
||||
|
||||
**Process:**
|
||||
@@ -305,42 +418,36 @@ Extract completed milestone details and create archive file.
|
||||
2. Read `~/.claude/get-shit-done/templates/milestone-archive.md` template
|
||||
|
||||
3. Extract data from current ROADMAP.md:
|
||||
|
||||
- All phases belonging to this milestone (by phase number range)
|
||||
- Full phase details (goals, plans, dependencies, status)
|
||||
- Phase plan lists with completion checkmarks
|
||||
|
||||
4. Extract data from STATE.md:
|
||||
|
||||
- All decisions made during this milestone (filter by Phase column)
|
||||
- Issues that were resolved
|
||||
- Issues that were deferred
|
||||
4. Extract data from PROJECT.md:
|
||||
- Key decisions made during this milestone
|
||||
- Requirements that were validated
|
||||
|
||||
5. Fill template {{PLACEHOLDERS}}:
|
||||
|
||||
- {{VERSION}} - Milestone version (e.g., "1.0")
|
||||
- {{MILESTONE_NAME}} - From ROADMAP.md milestone header
|
||||
- {{DATE}} - Today's date
|
||||
- {{PHASE_START}} - First phase number in milestone
|
||||
- {{PHASE_END}} - Last phase number in milestone
|
||||
- {{TOTAL_PLANS}} - Count of all plans in milestone
|
||||
- {{MILESTONE_DESCRIPTION}} - From ROADMAP.md overview
|
||||
- {{PHASES_SECTION}} - Full phase details extracted
|
||||
- {{DECISIONS_FROM_PROJECT_STATE}} - Filtered decisions
|
||||
- {{ISSUES_RESOLVED_DURING_MILESTONE}} - From summaries
|
||||
- {{ISSUES_DEFERRED_TO_LATER}} - From ISSUES.md
|
||||
- {{VERSION}} — Milestone version (e.g., "1.0")
|
||||
- {{MILESTONE_NAME}} — From ROADMAP.md milestone header
|
||||
- {{DATE}} — Today's date
|
||||
- {{PHASE_START}} — First phase number in milestone
|
||||
- {{PHASE_END}} — Last phase number in milestone
|
||||
- {{TOTAL_PLANS}} — Count of all plans in milestone
|
||||
- {{MILESTONE_DESCRIPTION}} — From ROADMAP.md overview
|
||||
- {{PHASES_SECTION}} — Full phase details extracted
|
||||
- {{DECISIONS_FROM_PROJECT}} — Key decisions from PROJECT.md
|
||||
- {{ISSUES_RESOLVED_DURING_MILESTONE}} — From summaries
|
||||
- {{ISSUES_DEFERRED_TO_LATER}} — From ISSUES.md
|
||||
|
||||
6. Write filled template to `.planning/milestones/v[X.Y]-ROADMAP.md`
|
||||
|
||||
7. Update ROADMAP.md:
|
||||
|
||||
- Create/update "## Completed Milestones" section if not exists
|
||||
- Add one-line entry: `- ✅ [v[X.Y] [Name]](milestones/v[X.Y]-ROADMAP.md) (Phases [N]-[M]) - SHIPPED [DATE]`
|
||||
- Add one-line entry: `- ✅ [v[X.Y] [Name]](milestones/v[X.Y]-ROADMAP.md) (Phases [N]-[M]) — SHIPPED [DATE]`
|
||||
- Remove full milestone details from "Current Milestone" section
|
||||
- Move next planned milestone to "Current Milestone" position
|
||||
|
||||
8. Verify files:
|
||||
|
||||
- Check archive file exists: `ls .planning/milestones/v[X.Y]-ROADMAP.md`
|
||||
- Validate ROADMAP.md still parseable
|
||||
|
||||
@@ -350,10 +457,44 @@ Extract completed milestone details and create archive file.
|
||||
✅ v[X.Y] archived to milestones/v[X.Y]-ROADMAP.md
|
||||
```
|
||||
|
||||
Continue to git_tag step. Milestone creation happens in offer_next step.
|
||||
</step>
|
||||
</step>
|
||||
|
||||
<step name="update_state">
|
||||
|
||||
Update STATE.md to reflect milestone completion.
|
||||
|
||||
**Project Reference:**
|
||||
|
||||
```markdown
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated [today])
|
||||
|
||||
**Core value:** [Current core value from PROJECT.md]
|
||||
**Current focus:** [Next milestone or "Planning next milestone"]
|
||||
```
|
||||
|
||||
**Current Position:**
|
||||
|
||||
```markdown
|
||||
Phase: [Next phase] of [Total] ([Phase name])
|
||||
Plan: Not started
|
||||
Status: Ready to plan
|
||||
Last activity: [today] — v[X.Y] milestone complete
|
||||
|
||||
Progress: [updated progress bar]
|
||||
```
|
||||
|
||||
**Accumulated Context:**
|
||||
|
||||
- Clear decisions summary (full log in PROJECT.md)
|
||||
- Clear resolved blockers
|
||||
- Keep open blockers for next milestone
|
||||
|
||||
</step>
|
||||
|
||||
<step name="git_tag">
|
||||
|
||||
Create git tag for milestone:
|
||||
|
||||
```bash
|
||||
@@ -385,6 +526,7 @@ git push origin v[X.Y]
|
||||
</step>
|
||||
|
||||
<step name="git_commit_milestone">
|
||||
|
||||
Commit milestone completion including archive file.
|
||||
|
||||
```bash
|
||||
@@ -392,32 +534,33 @@ Commit milestone completion including archive file.
|
||||
git add .planning/MILESTONES.md
|
||||
git add .planning/PROJECT.md
|
||||
git add .planning/ROADMAP.md
|
||||
git add .planning/STATE.md
|
||||
git add .planning/milestones/v[X.Y]-ROADMAP.md
|
||||
|
||||
# Commit with descriptive message
|
||||
git commit -m "$(cat <<'EOF'
|
||||
chore: archive v[X.Y] milestone
|
||||
chore: complete v[X.Y] milestone
|
||||
|
||||
- Added MILESTONES.md entry
|
||||
- Updated PROJECT.md current state
|
||||
- Evolved PROJECT.md with validated requirements
|
||||
- Reorganized ROADMAP.md with milestone grouping
|
||||
- Created milestone archive: milestones/v[X.Y]-ROADMAP.md
|
||||
- Updated STATE.md
|
||||
- Tagged v[X.Y]
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
Confirm: "Committed: chore: archive v[X.Y] milestone"
|
||||
Confirm: "Committed: chore: complete v[X.Y] milestone"
|
||||
|
||||
Then proceed to git tag step.
|
||||
</step>
|
||||
|
||||
<step name="offer_next">
|
||||
|
||||
```
|
||||
✅ Milestone v[X.Y] [Name] complete
|
||||
|
||||
Shipped:
|
||||
|
||||
- [N] phases ([M] plans, [P] tasks)
|
||||
- [One sentence of what shipped]
|
||||
|
||||
@@ -441,15 +584,17 @@ Tag: v[X.Y]
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</step>
|
||||
|
||||
</process>
|
||||
|
||||
<milestone_naming>
|
||||
|
||||
**Version conventions:**
|
||||
- **v1.0** - Initial MVP
|
||||
- **v1.1, v1.2, v1.3** - Minor updates, new features, fixes
|
||||
- **v2.0, v3.0** - Major rewrites, breaking changes, significant new direction
|
||||
- **v1.0** — Initial MVP
|
||||
- **v1.1, v1.2, v1.3** — Minor updates, new features, fixes
|
||||
- **v2.0, v3.0** — Major rewrites, breaking changes, significant new direction
|
||||
|
||||
**Name conventions:**
|
||||
- v1.0 MVP
|
||||
@@ -459,9 +604,11 @@ Tag: v[X.Y]
|
||||
- v2.0 iOS Launch
|
||||
|
||||
Keep names short (1-2 words describing the focus).
|
||||
|
||||
</milestone_naming>
|
||||
|
||||
<what_qualifies>
|
||||
|
||||
**Create milestones for:**
|
||||
- Initial release (v1.0)
|
||||
- Public releases
|
||||
@@ -475,15 +622,22 @@ Keep names short (1-2 words describing the focus).
|
||||
|
||||
If uncertain, ask: "Is this deployed/usable/shipped in some form?"
|
||||
If yes → milestone. If no → keep working.
|
||||
|
||||
</what_qualifies>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
Milestone completion is successful when:
|
||||
|
||||
- [ ] MILESTONES.md entry created with stats and accomplishments
|
||||
- [ ] PROJECT.md updated with current state
|
||||
- [ ] PROJECT.md full evolution review completed
|
||||
- [ ] All shipped requirements moved to Validated
|
||||
- [ ] Key Decisions updated with outcomes
|
||||
- [ ] ROADMAP.md reorganized with milestone grouping
|
||||
- [ ] Milestone archive created
|
||||
- [ ] STATE.md updated with fresh project reference
|
||||
- [ ] Git tag created (v[X.Y])
|
||||
- [ ] Milestone commit made
|
||||
- [ ] User knows next steps
|
||||
|
||||
</success_criteria>
|
||||
```
|
||||
|
||||
@@ -29,7 +29,7 @@ Extract:
|
||||
- Previous milestone version (e.g., v1.0)
|
||||
- Last phase number used
|
||||
- Deferred issues from STATE.md
|
||||
- Project brief summary from STATE.md
|
||||
- Project context from PROJECT.md (What This Is, Core Value)
|
||||
|
||||
**Calculate next milestone version:**
|
||||
|
||||
|
||||
@@ -285,7 +285,8 @@ mkdir -p .planning/phases/02-{phase-name}
|
||||
</step>
|
||||
|
||||
<step name="initialize_project_state">
|
||||
Create STATE.md - the project's living memory.
|
||||
|
||||
Create STATE.md — the project's living memory.
|
||||
|
||||
Use template from `~/.claude/get-shit-done/templates/state.md`.
|
||||
|
||||
@@ -294,47 +295,56 @@ Write to `.planning/STATE.md`:
|
||||
```markdown
|
||||
# Project State
|
||||
|
||||
## Brief Summary
|
||||
## Project Reference
|
||||
|
||||
**Building:** [Copy one-liner from PROJECT.md]
|
||||
See: .planning/PROJECT.md (updated [today's date])
|
||||
|
||||
**Core requirements:**
|
||||
[Copy 3-5 key requirements from PROJECT.md]
|
||||
|
||||
**Constraints:**
|
||||
[Copy key constraints from PROJECT.md]
|
||||
**Core value:** [Copy Core Value from PROJECT.md]
|
||||
**Current focus:** Phase 1 — [First phase name]
|
||||
|
||||
## Current Position
|
||||
|
||||
Phase: 1 of [N] ([First phase name])
|
||||
Plan: Not started
|
||||
Status: Ready to plan
|
||||
Last activity: [today's date] - Project initialized
|
||||
Last activity: [today's date] — Project initialized
|
||||
|
||||
Progress: ░░░░░░░░░░ 0%
|
||||
|
||||
## Performance Metrics
|
||||
|
||||
**Velocity:**
|
||||
- Total plans completed: 0
|
||||
- Average duration: —
|
||||
- Total execution time: 0 hours
|
||||
|
||||
**By Phase:**
|
||||
|
||||
| Phase | Plans | Total | Avg/Plan |
|
||||
|-------|-------|-------|----------|
|
||||
| — | — | — | — |
|
||||
|
||||
**Recent Trend:**
|
||||
- Last 5 plans: —
|
||||
- Trend: —
|
||||
|
||||
## Accumulated Context
|
||||
|
||||
### Decisions Made
|
||||
### Decisions
|
||||
|
||||
| Phase | Decision | Rationale |
|
||||
| ----- | -------- | --------- |
|
||||
Decisions are logged in PROJECT.md Key Decisions table.
|
||||
Recent decisions affecting current work:
|
||||
|
||||
(None yet)
|
||||
|
||||
### Deferred Issues
|
||||
|
||||
None yet.
|
||||
|
||||
### Blockers/Concerns Carried Forward
|
||||
### Blockers/Concerns
|
||||
|
||||
None yet.
|
||||
|
||||
## Brief Alignment
|
||||
|
||||
Last checked: Project start
|
||||
Status: ✓ Aligned
|
||||
Assessment: No work done yet - baseline alignment.
|
||||
Drift notes: None
|
||||
|
||||
## Session Continuity
|
||||
|
||||
Last session: [today's date and time]
|
||||
@@ -344,11 +354,12 @@ Resume file: None
|
||||
|
||||
**Key points:**
|
||||
|
||||
- Brief Summary section is IMMUTABLE after creation - never edit it
|
||||
- Copy verbatim from PROJECT.md to ensure fidelity
|
||||
- Project Reference points to PROJECT.md for full context
|
||||
- Claude reads PROJECT.md directly for requirements, constraints, decisions
|
||||
- This file will be read first in every future operation
|
||||
- This file will be updated after every execution
|
||||
</step>
|
||||
|
||||
</step>
|
||||
|
||||
<step name="git_commit_initialization">
|
||||
Commit project initialization (brief + roadmap + state together):
|
||||
|
||||
@@ -30,23 +30,32 @@ ls .planning/PROJECT.md 2>/dev/null && echo "Project file exists"
|
||||
</step>
|
||||
|
||||
<step name="load_state">
|
||||
Read and parse STATE.md:
|
||||
|
||||
Read and parse STATE.md, then PROJECT.md:
|
||||
|
||||
```bash
|
||||
cat .planning/STATE.md
|
||||
cat .planning/PROJECT.md
|
||||
```
|
||||
|
||||
Extract:
|
||||
**From STATE.md extract:**
|
||||
|
||||
- **Brief Summary**: What we're building (immutable reminder)
|
||||
- **Project Reference**: Core value and current focus
|
||||
- **Current Position**: Phase X of Y, Plan A of B, Status
|
||||
- **Progress**: Visual progress bar
|
||||
- **Decisions Made**: Key decisions that constrain future work
|
||||
- **Recent Decisions**: Key decisions affecting current work
|
||||
- **Deferred Issues**: Open items awaiting attention
|
||||
- **Blockers/Concerns**: Issues carried forward
|
||||
- **Brief Alignment**: Are we on track?
|
||||
- **Session Continuity**: Where we left off, any resume files
|
||||
</step>
|
||||
|
||||
**From PROJECT.md extract:**
|
||||
|
||||
- **What This Is**: Current accurate description
|
||||
- **Requirements**: Validated, Active, Out of Scope
|
||||
- **Key Decisions**: Full decision log with outcomes
|
||||
- **Constraints**: Hard limits on implementation
|
||||
|
||||
</step>
|
||||
|
||||
<step name="check_incomplete_work">
|
||||
Look for incomplete work that needs attention:
|
||||
@@ -81,7 +90,7 @@ Present complete project status to user:
|
||||
╔══════════════════════════════════════════════════════════════╗
|
||||
║ PROJECT STATUS ║
|
||||
╠══════════════════════════════════════════════════════════════╣
|
||||
║ Building: [one-liner from Brief Summary] ║
|
||||
║ Building: [one-liner from PROJECT.md "What This Is"] ║
|
||||
║ ║
|
||||
║ Phase: [X] of [Y] - [Phase name] ║
|
||||
║ Plan: [A] of [B] - [Status] ║
|
||||
@@ -237,7 +246,7 @@ If STATE.md is missing but other artifacts exist:
|
||||
|
||||
"STATE.md missing. Reconstructing from artifacts..."
|
||||
|
||||
1. Read PROJECT.md → Extract Brief Summary
|
||||
1. Read PROJECT.md → Extract "What This Is" and Core Value
|
||||
2. Read ROADMAP.md → Determine phases, find current position
|
||||
3. Scan \*-SUMMARY.md files → Extract decisions, issues, concerns
|
||||
4. Read ISSUES.md → Count deferred issues
|
||||
|
||||
@@ -1,33 +1,41 @@
|
||||
<required_reading>
|
||||
|
||||
**Read these files NOW:**
|
||||
|
||||
1. `.planning/STATE.md`
|
||||
2. `.planning/ROADMAP.md`
|
||||
3. Current phase's plan files (`*-PLAN.md`)
|
||||
4. Current phase's summary files (`*-SUMMARY.md`)
|
||||
</required_reading>
|
||||
2. `.planning/PROJECT.md`
|
||||
3. `.planning/ROADMAP.md`
|
||||
4. Current phase's plan files (`*-PLAN.md`)
|
||||
5. Current phase's summary files (`*-SUMMARY.md`)
|
||||
|
||||
</required_reading>
|
||||
|
||||
<purpose>
|
||||
Mark current phase complete and advance to next. This is the natural point
|
||||
where progress tracking happens - implicit via forward motion.
|
||||
|
||||
Mark current phase complete and advance to next. This is the natural point where progress tracking and PROJECT.md evolution happen.
|
||||
|
||||
"Planning next phase" = "current phase is done"
|
||||
|
||||
</purpose>
|
||||
|
||||
<process>
|
||||
|
||||
<step name="load_project_state" priority="first">
|
||||
|
||||
Before transition, read project state:
|
||||
|
||||
```bash
|
||||
cat .planning/STATE.md 2>/dev/null
|
||||
cat .planning/PROJECT.md 2>/dev/null
|
||||
```
|
||||
|
||||
Parse current position to verify we're transitioning the right phase.
|
||||
Note accumulated context that may need updating after transition.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="verify_completion">
|
||||
|
||||
Check current phase has all plan summaries:
|
||||
|
||||
```bash
|
||||
@@ -43,34 +51,40 @@ ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort
|
||||
- If counts don't match: incomplete
|
||||
|
||||
<config-check>
|
||||
|
||||
```bash
|
||||
cat .planning/config.json 2>/dev/null
|
||||
```
|
||||
|
||||
</config-check>
|
||||
|
||||
**If all plans complete:**
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
```
|
||||
⚡ Auto-approved: Transition Phase [X] → Phase [X+1]
|
||||
Phase [X] complete - all [Y] plans finished.
|
||||
Phase [X] complete — all [Y] plans finished.
|
||||
|
||||
Proceeding to mark done and advance...
|
||||
```
|
||||
|
||||
Proceed directly to cleanup_handoff step.
|
||||
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_transition true">
|
||||
Ask: "Phase [X] complete - all [Y] plans finished. Ready to mark done and move to Phase [X+1]?"
|
||||
|
||||
Ask: "Phase [X] complete — all [Y] plans finished. Ready to mark done and move to Phase [X+1]?"
|
||||
|
||||
Wait for confirmation before proceeding.
|
||||
|
||||
</if>
|
||||
|
||||
**If plans incomplete:**
|
||||
|
||||
**SAFETY RAIL: always_confirm_destructive applies here.**
|
||||
Skipping incomplete plans is destructive - ALWAYS prompt regardless of mode.
|
||||
Skipping incomplete plans is destructive — ALWAYS prompt regardless of mode.
|
||||
|
||||
Present:
|
||||
|
||||
@@ -89,19 +103,23 @@ Options:
|
||||
```
|
||||
|
||||
Wait for user decision.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="cleanup_handoff">
|
||||
|
||||
Check for lingering handoffs:
|
||||
|
||||
```bash
|
||||
ls .planning/phases/XX-current/.continue-here*.md 2>/dev/null
|
||||
```
|
||||
|
||||
If found, delete them - phase is complete, handoffs are stale.
|
||||
</step>
|
||||
If found, delete them — phase is complete, handoffs are stale.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="update_roadmap">
|
||||
|
||||
Update the roadmap file:
|
||||
|
||||
```bash
|
||||
@@ -137,11 +155,101 @@ Update the file:
|
||||
</step>
|
||||
|
||||
<step name="archive_prompts">
|
||||
|
||||
If prompts were generated for the phase, they stay in place.
|
||||
The `completed/` subfolder pattern from create-meta-prompts handles archival.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="evolve_project">
|
||||
|
||||
Evolve PROJECT.md to reflect learnings from completed phase.
|
||||
|
||||
**Read phase summaries:**
|
||||
|
||||
```bash
|
||||
cat .planning/phases/XX-current/*-SUMMARY.md
|
||||
```
|
||||
|
||||
**Assess requirement changes:**
|
||||
|
||||
1. **Requirements validated?**
|
||||
- Any Active requirements shipped in this phase?
|
||||
- Move to Validated with phase reference: `- ✓ [Requirement] — Phase X`
|
||||
|
||||
2. **Requirements invalidated?**
|
||||
- Any Active requirements discovered to be unnecessary or wrong?
|
||||
- Move to Out of Scope with reason: `- [Requirement] — [why invalidated]`
|
||||
|
||||
3. **Requirements emerged?**
|
||||
- Any new requirements discovered during building?
|
||||
- Add to Active: `- [ ] [New requirement]`
|
||||
|
||||
4. **Decisions to log?**
|
||||
- Extract decisions from SUMMARY.md files
|
||||
- Add to Key Decisions table with outcome if known
|
||||
|
||||
5. **"What This Is" still accurate?**
|
||||
- If the product has meaningfully changed, update the description
|
||||
- Keep it current and accurate
|
||||
|
||||
**Update PROJECT.md:**
|
||||
|
||||
Make the edits inline. Update "Last updated" footer:
|
||||
|
||||
```markdown
|
||||
---
|
||||
*Last updated: [date] after Phase [X]*
|
||||
```
|
||||
|
||||
**Example evolution:**
|
||||
|
||||
Before:
|
||||
|
||||
```markdown
|
||||
### Active
|
||||
|
||||
- [ ] JWT authentication
|
||||
- [ ] Real-time sync < 500ms
|
||||
- [ ] Offline mode
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- OAuth2 — complexity not needed for v1
|
||||
```
|
||||
|
||||
After (Phase 2 shipped JWT auth, discovered rate limiting needed):
|
||||
|
||||
```markdown
|
||||
### Validated
|
||||
|
||||
- ✓ JWT authentication — Phase 2
|
||||
|
||||
### Active
|
||||
|
||||
- [ ] Real-time sync < 500ms
|
||||
- [ ] Offline mode
|
||||
- [ ] Rate limiting on sync endpoint
|
||||
|
||||
### Out of Scope
|
||||
|
||||
- OAuth2 — complexity not needed for v1
|
||||
```
|
||||
|
||||
**Step complete when:**
|
||||
|
||||
- [ ] Phase summaries reviewed for learnings
|
||||
- [ ] Validated requirements moved from Active
|
||||
- [ ] Invalidated requirements moved to Out of Scope with reason
|
||||
- [ ] Emerged requirements added to Active
|
||||
- [ ] New decisions logged with rationale
|
||||
- [ ] "What This Is" updated if product changed
|
||||
- [ ] "Last updated" footer reflects this transition
|
||||
|
||||
</step>
|
||||
|
||||
<step name="update_current_position_after_transition">
|
||||
|
||||
Update Current Position section in STATE.md to reflect phase completion and transition.
|
||||
|
||||
**Format:**
|
||||
@@ -150,7 +258,7 @@ Update Current Position section in STATE.md to reflect phase completion and tran
|
||||
Phase: [next] of [total] ([Next phase name])
|
||||
Plan: Not started
|
||||
Status: Ready to plan
|
||||
Last activity: [today] - Phase [X] complete, transitioned to Phase [X+1]
|
||||
Last activity: [today] — Phase [X] complete, transitioned to Phase [X+1]
|
||||
|
||||
Progress: [updated progress bar]
|
||||
```
|
||||
@@ -163,7 +271,7 @@ Progress: [updated progress bar]
|
||||
- Update last activity to describe transition
|
||||
- Recalculate progress bar based on completed plans
|
||||
|
||||
**Example - transitioning from Phase 2 to Phase 3:**
|
||||
**Example — transitioning from Phase 2 to Phase 3:**
|
||||
|
||||
Before:
|
||||
|
||||
@@ -173,7 +281,7 @@ Before:
|
||||
Phase: 2 of 4 (Authentication)
|
||||
Plan: 2 of 2 in current phase
|
||||
Status: Phase complete
|
||||
Last activity: 2025-01-20 - Completed 02-02-PLAN.md
|
||||
Last activity: 2025-01-20 — Completed 02-02-PLAN.md
|
||||
|
||||
Progress: ███████░░░ 60%
|
||||
```
|
||||
@@ -186,7 +294,7 @@ After:
|
||||
Phase: 3 of 4 (Core Features)
|
||||
Plan: Not started
|
||||
Status: Ready to plan
|
||||
Last activity: 2025-01-20 - Phase 2 complete, transitioned to Phase 3
|
||||
Last activity: 2025-01-20 — Phase 2 complete, transitioned to Phase 3
|
||||
|
||||
Progress: ███████░░░ 60%
|
||||
```
|
||||
@@ -197,23 +305,47 @@ Progress: ███████░░░ 60%
|
||||
- [ ] Plan status reset to "Not started"
|
||||
- [ ] Status shows "Ready to plan"
|
||||
- [ ] Last activity describes the transition
|
||||
- [ ] Progress bar still reflects total completed plans
|
||||
</step>
|
||||
- [ ] Progress bar reflects total completed plans
|
||||
|
||||
</step>
|
||||
|
||||
<step name="update_project_reference">
|
||||
|
||||
Update Project Reference section in STATE.md.
|
||||
|
||||
```markdown
|
||||
## Project Reference
|
||||
|
||||
See: .planning/PROJECT.md (updated [today])
|
||||
|
||||
**Core value:** [Current core value from PROJECT.md]
|
||||
**Current focus:** [Next phase name]
|
||||
```
|
||||
|
||||
Update the date and current focus to reflect the transition.
|
||||
|
||||
</step>
|
||||
|
||||
<step name="review_accumulated_context">
|
||||
|
||||
Review and update Accumulated Context section in STATE.md.
|
||||
|
||||
**Decisions:**
|
||||
|
||||
- Note recent decisions from this phase (3-5 max)
|
||||
- Full log lives in PROJECT.md Key Decisions table
|
||||
|
||||
**Blockers/Concerns:**
|
||||
|
||||
- Review blockers from completed phase
|
||||
- If addressed in this phase: Remove from list
|
||||
- If still relevant for future: Keep with note "Carried from Phase X"
|
||||
- If still relevant for future: Keep with "Phase X" prefix
|
||||
- Add any new concerns from completed phase's summaries
|
||||
|
||||
**Deferred Issues:**
|
||||
|
||||
- Count open issues in ISSUES.md
|
||||
- Update count: "[N] open issues - see ISSUES.md"
|
||||
- Update count: "[N] open issues — see ISSUES.md"
|
||||
- If many accumulated, note: "Consider addressing ISS-XXX, ISS-YYY in next phase"
|
||||
|
||||
**Example:**
|
||||
@@ -221,109 +353,41 @@ Review and update Accumulated Context section in STATE.md.
|
||||
Before:
|
||||
|
||||
```markdown
|
||||
### Blockers/Concerns Carried Forward
|
||||
### Blockers/Concerns
|
||||
|
||||
- ⚠️ [Phase 1] Database schema not indexed for common queries
|
||||
- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
|
||||
|
||||
### Deferred Issues
|
||||
|
||||
- ISS-001: Rate limiting on sync endpoint (Phase 2) - Medium
|
||||
- ISS-001: Rate limiting on sync endpoint (Phase 2) — Medium
|
||||
```
|
||||
|
||||
After (if database indexing was addressed in Phase 2):
|
||||
|
||||
```markdown
|
||||
### Blockers/Concerns Carried Forward
|
||||
### Blockers/Concerns
|
||||
|
||||
- ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown
|
||||
|
||||
### Deferred Issues
|
||||
|
||||
- ISS-001: Rate limiting on sync endpoint (Phase 2) - Medium
|
||||
- ISS-002: Better sync error messages (Phase 2) - Quick
|
||||
- ISS-001: Rate limiting on sync endpoint (Phase 2) — Medium
|
||||
- ISS-002: Better sync error messages (Phase 2) — Quick
|
||||
```
|
||||
|
||||
**Step complete when:**
|
||||
|
||||
- [ ] Recent decisions noted (full log in PROJECT.md)
|
||||
- [ ] Resolved blockers removed from list
|
||||
- [ ] Unresolved blockers kept with phase prefix
|
||||
- [ ] New concerns from completed phase added
|
||||
- [ ] Deferred issues count updated
|
||||
</step>
|
||||
|
||||
<step name="update_brief_alignment">
|
||||
Perform brief alignment check after phase completion to verify work matches original vision.
|
||||
|
||||
**Instructions:**
|
||||
|
||||
1. Re-read PROJECT.md core requirements
|
||||
2. Assess what was built in completed phase
|
||||
3. Compare against project's problem statement and success criteria
|
||||
4. Determine alignment status:
|
||||
- ✓ Aligned: Work delivers on project goals, no scope drift
|
||||
- ⚠️ Drift detected: Some divergence from original vision
|
||||
- ✗ Misaligned: Work doesn't serve the project
|
||||
|
||||
**Format:**
|
||||
|
||||
```markdown
|
||||
## Brief Alignment
|
||||
|
||||
Last checked: [today] (Phase [X] completion)
|
||||
Status: [✓ Aligned / ⚠️ Drift detected / ✗ Misaligned]
|
||||
Assessment: [One sentence describing alignment state]
|
||||
Drift notes: [Details if drift detected, otherwise "None"]
|
||||
```
|
||||
|
||||
**Example - transitioning after Phase 2 completion:**
|
||||
|
||||
Before:
|
||||
|
||||
```markdown
|
||||
## Brief Alignment
|
||||
|
||||
Last checked: Project start
|
||||
Status: ✓ Aligned
|
||||
Assessment: No work done yet - baseline alignment.
|
||||
Drift notes: None
|
||||
```
|
||||
|
||||
After:
|
||||
|
||||
```markdown
|
||||
## Brief Alignment
|
||||
|
||||
Last checked: 2025-01-20 (Phase 2 completion)
|
||||
Status: ✓ Aligned
|
||||
Assessment: Auth phase delivered JWT-based authentication as specified. Sync phase next aligns with project's real-time requirements.
|
||||
Drift notes: None
|
||||
```
|
||||
|
||||
**Alternative example - drift detected:**
|
||||
|
||||
After (with drift):
|
||||
|
||||
```markdown
|
||||
## Brief Alignment
|
||||
|
||||
Last checked: 2025-01-20 (Phase 2 completion)
|
||||
Status: ⚠️ Drift detected
|
||||
Assessment: Auth phase added OAuth2 support beyond project's JWT requirement.
|
||||
Drift notes: OAuth2 adds complexity not in original scope. Consider if this serves user needs or gold-plating.
|
||||
```
|
||||
|
||||
**Step complete when:**
|
||||
|
||||
- [ ] PROJECT.md core requirements reviewed
|
||||
- [ ] Completed phase work assessed against project goals
|
||||
- [ ] Last checked updated to current date with phase reference
|
||||
- [ ] Status reflects actual alignment (Aligned/Drift/Misaligned)
|
||||
- [ ] Assessment explains the alignment state in one sentence
|
||||
- [ ] Drift notes document any divergence from project goals
|
||||
</step>
|
||||
</step>
|
||||
|
||||
<step name="update_session_continuity_after_transition">
|
||||
|
||||
Update Session Continuity section in STATE.md to reflect transition completion.
|
||||
|
||||
**Format:**
|
||||
@@ -334,36 +398,16 @@ Stopped at: Phase [X] complete, ready to plan Phase [X+1]
|
||||
Resume file: None
|
||||
```
|
||||
|
||||
**Example - after completing Phase 2 transition:**
|
||||
|
||||
Before:
|
||||
|
||||
```markdown
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2025-01-20
|
||||
Stopped at: Completed 02-02-PLAN.md
|
||||
Resume file: None
|
||||
```
|
||||
|
||||
After:
|
||||
|
||||
```markdown
|
||||
## Session Continuity
|
||||
|
||||
Last session: 2025-01-20 16:45
|
||||
Stopped at: Phase 2 complete, ready to plan Phase 3
|
||||
Resume file: None
|
||||
```
|
||||
|
||||
**Step complete when:**
|
||||
|
||||
- [ ] Last session timestamp updated to current date and time
|
||||
- [ ] Stopped at describes phase completion and next phase
|
||||
- [ ] Resume file confirmed as None (transitions don't use resume files)
|
||||
</step>
|
||||
|
||||
</step>
|
||||
|
||||
<step name="offer_next_phase">
|
||||
|
||||
**Check if there's a next phase in the current milestone:**
|
||||
|
||||
Re-read the ROADMAP file:
|
||||
@@ -376,18 +420,21 @@ Re-read the ROADMAP file:
|
||||
**If next phase exists:**
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
```
|
||||
Phase [X] marked complete.
|
||||
|
||||
Next: Phase [X+1] - [Name]
|
||||
Next: Phase [X+1] — [Name]
|
||||
|
||||
⚡ Auto-continuing: Plan Phase [X+1] in detail
|
||||
```
|
||||
|
||||
Exit skill and invoke SlashCommand("/gsd:plan-phase [X+1]")
|
||||
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_transition true">
|
||||
|
||||
```
|
||||
## ✓ Phase [X] Complete
|
||||
|
||||
@@ -410,27 +457,31 @@ Exit skill and invoke SlashCommand("/gsd:plan-phase [X+1]")
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</if>
|
||||
|
||||
**If no next phase (milestone 100% complete):**
|
||||
|
||||
<if mode="yolo">
|
||||
|
||||
```
|
||||
Phase [X] marked complete.
|
||||
|
||||
🎉 Milestone [version] is 100% complete - all phases finished!
|
||||
🎉 Milestone [version] is 100% complete — all phases finished!
|
||||
|
||||
⚡ Auto-continuing: Complete milestone and archive
|
||||
```
|
||||
|
||||
Exit skill and invoke SlashCommand("/gsd:complete-milestone [version]")
|
||||
|
||||
</if>
|
||||
|
||||
<if mode="interactive" OR="custom with gates.confirm_transition true">
|
||||
|
||||
```
|
||||
## ✓ Phase [X] Complete
|
||||
|
||||
🎉 Milestone [version] is 100% complete - all phases finished!
|
||||
🎉 Milestone [version] is 100% complete — all phases finished!
|
||||
|
||||
---
|
||||
|
||||
@@ -449,6 +500,7 @@ Exit skill and invoke SlashCommand("/gsd:complete-milestone [version]")
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
</if>
|
||||
|
||||
</step>
|
||||
@@ -456,6 +508,7 @@ Exit skill and invoke SlashCommand("/gsd:complete-milestone [version]")
|
||||
</process>
|
||||
|
||||
<implicit_tracking>
|
||||
|
||||
Progress tracking is IMPLICIT:
|
||||
|
||||
- "Plan phase 2" → Phase 1 must be done (or ask)
|
||||
@@ -463,9 +516,11 @@ Progress tracking is IMPLICIT:
|
||||
- Transition workflow makes it explicit in ROADMAP.md
|
||||
|
||||
No separate "update progress" step. Forward motion IS progress.
|
||||
|
||||
</implicit_tracking>
|
||||
|
||||
<partial_completion>
|
||||
|
||||
If user wants to move on but phase isn't fully complete:
|
||||
|
||||
```
|
||||
@@ -479,22 +534,25 @@ Options:
|
||||
3. Stay and finish current phase
|
||||
```
|
||||
|
||||
Respect user judgment - they know if work matters.
|
||||
Respect user judgment — they know if work matters.
|
||||
|
||||
**If marking complete with incomplete plans:**
|
||||
|
||||
- Update ROADMAP: "2/3 plans complete" (not "3/3")
|
||||
- Note in transition message which plans were skipped
|
||||
</partial_completion>
|
||||
|
||||
</partial_completion>
|
||||
|
||||
<success_criteria>
|
||||
|
||||
Transition is complete when:
|
||||
|
||||
- [ ] Current phase plan summaries verified (all exist or user chose to skip)
|
||||
- [ ] Any stale handoffs deleted
|
||||
- [ ] ROADMAP.md updated with completion status and plan count
|
||||
- [ ] STATE.md updated (position, blockers, alignment, session)
|
||||
- [ ] Brief alignment check performed
|
||||
- [ ] PROJECT.md evolved (requirements, decisions, description if needed)
|
||||
- [ ] STATE.md updated (position, project reference, context, session)
|
||||
- [ ] Progress table updated
|
||||
- [ ] User knows next steps
|
||||
</success_criteria>
|
||||
|
||||
</success_criteria>
|
||||
|
||||
Reference in New Issue
Block a user