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
2025-12-27 10:03:29 -06:00
parent 8ebae044fc
commit 31597a9481
9 changed files with 787 additions and 502 deletions

View File

@@ -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>
```

View File

@@ -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">