get-shit-done-cc 1.3.8 → 1.3.10

package/commands/gsd/new-project.md

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

package/commands/gsd/progress.md

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

package/get-shit-done/templates/project.md

@@ -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]
-
-Common types: Tech stack, Timeline, Resources, Dependencies, Compatibility, Performance, Security
+- **[Type]**: [What] — [Why]
+- **[Type]**: [What] — [Why]
 
-## Decisions Made
+Common types: Tech stack, Timeline, Budget, Dependencies, Compatibility, Performance, Security
 
-Key decisions from project exploration:
+## Key Decisions
 
-| Decision | Choice | Rationale |
-|----------|--------|-----------|
-| [Area/Topic] | [What we decided] | [Why this choice] |
-| [Area/Topic] | [What we decided] | [Why this choice] |
+<!-- Decisions that constrain future work. Add throughout project lifecycle. -->
 
-## 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]
+</template>
 
-**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]
+<guidelines>
 
-## Open Questions
+**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
+
+**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
+
+**Requirements — Validated:**
+- Requirements that shipped and proved valuable
+- Format: `- ✓ [Requirement] — [version/phase]`
+- These are locked — changing them requires explicit discussion
+
+**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
 
-- [ ] [Question for this version]
-- [ ] [Question for this version]
+**Constraints:**
+- Hard limits on implementation choices
+- Tech stack, timeline, budget, compatibility, dependencies
+- Include the "why" — constraints without rationale get questioned
+
+**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>
 
-<details>
-<summary>Original Vision (v1.0 - Archived)</summary>
+<evolution>
 
-## Vision
+PROJECT.md evolves throughout the project lifecycle.
 
-[Original vision content]
+**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
 
-## Problem
+**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)
 
-[Original problem statement]
+</evolution>
 
-## Success Criteria
+<brownfield>
 
-- [x] [Outcome 1] - Achieved
-- [x] [Outcome 2] - Achieved
-- [x] [Outcome 3] - Achieved
+For existing codebases:
 
-## Scope
+1. **Map codebase first** via `/gsd:map-codebase`
 
-### Built
-- [What was built]
+2. **Infer Validated requirements** from existing code:
+   - What does the codebase actually do?
+   - What patterns are established?
+   - What's clearly working and relied upon?
 
-### Not Built
-- [What was excluded]
+3. **Gather Active requirements** from user:
+   - Present inferred current state
+   - Ask what they want to build next
 
-## Context
+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
 
-[Original context]
+</brownfield>
 
-## Constraints
+<state_reference>
 
-[Original constraints]
+STATE.md references PROJECT.md:
 
-## Decisions Made
+```markdown
+## Project Reference
 
-[Original decisions table]
+See: .planning/PROJECT.md (updated [date])
 
-</details>
+**Core value:** [One-liner from Core Value section]
+**Current focus:** [Current phase name]
 ```
 
-<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>
-
-<state_summary>
-When creating STATE.md, extract a summary from PROJECT.md:
-
-**Building:** [One-liner from Vision]
-
-**Core requirements:**
-- [Top 3 from Success Criteria]
-
-**Constraints:**
-- [Key constraints]
+This ensures Claude reads current PROJECT.md context.
 
-This goes in STATE.md's immutable "Project Summary" section.
-</state_summary>
+</state_reference>