From 194d1d88bbbf14ed08d60c3f6dc9457661182c78 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Wed, 14 Jan 2026 23:48:44 -0600 Subject: [PATCH] refactor: slim principles.md and load in core commands Reduce principles.md from 158 to 73 lines: - Remove duplicates (atomic_commits, tdd, deviation_rules) - Remove version drag from claude_automates - Keep core orientation: solo dev model, plans are prompts, scope control, ship fast, anti-enterprise Add principles.md to 9 core commands so Claude always understands what GSD is. Co-Authored-By: Claude Opus 4.5 --- commands/gsd/create-roadmap.md | 1 + commands/gsd/define-requirements.md | 1 + commands/gsd/discuss-milestone.md | 1 + commands/gsd/discuss-phase.md | 1 + commands/gsd/execute-phase.md | 1 + commands/gsd/execute-plan.md | 1 + commands/gsd/plan-phase.md | 1 + commands/gsd/research-phase.md | 1 + commands/gsd/research-project.md | 1 + get-shit-done/references/principles.md | 90 +------------------------- 10 files changed, 12 insertions(+), 87 deletions(-) diff --git a/commands/gsd/create-roadmap.md b/commands/gsd/create-roadmap.md index a99647cb0..3b9421729 100644 --- a/commands/gsd/create-roadmap.md +++ b/commands/gsd/create-roadmap.md @@ -18,6 +18,7 @@ Run after `/gsd:define-requirements`. +@~/.claude/get-shit-done/references/principles.md @~/.claude/get-shit-done/workflows/create-roadmap.md @~/.claude/get-shit-done/templates/roadmap.md @~/.claude/get-shit-done/templates/state.md diff --git a/commands/gsd/define-requirements.md b/commands/gsd/define-requirements.md index c7b1043d1..4df713f43 100644 --- a/commands/gsd/define-requirements.md +++ b/commands/gsd/define-requirements.md @@ -23,6 +23,7 @@ Output: `.planning/REQUIREMENTS.md` +@~/.claude/get-shit-done/references/principles.md @~/.claude/get-shit-done/workflows/define-requirements.md @~/.claude/get-shit-done/templates/requirements.md diff --git a/commands/gsd/discuss-milestone.md b/commands/gsd/discuss-milestone.md index 221e3d2d3..2295eb73a 100644 --- a/commands/gsd/discuss-milestone.md +++ b/commands/gsd/discuss-milestone.md @@ -11,6 +11,7 @@ Output: Context gathered, then routes to /gsd:new-milestone +@~/.claude/get-shit-done/references/principles.md @~/.claude/get-shit-done/workflows/discuss-milestone.md diff --git a/commands/gsd/discuss-phase.md b/commands/gsd/discuss-phase.md index b9d8d8745..d1a2eb1a8 100644 --- a/commands/gsd/discuss-phase.md +++ b/commands/gsd/discuss-phase.md @@ -13,6 +13,7 @@ Output: {phase}-CONTEXT.md capturing the user's vision for the phase +@~/.claude/get-shit-done/references/principles.md @~/.claude/get-shit-done/workflows/discuss-phase.md @~/.claude/get-shit-done/templates/context.md diff --git a/commands/gsd/execute-phase.md b/commands/gsd/execute-phase.md index a0e057642..21215c5b3 100644 --- a/commands/gsd/execute-phase.md +++ b/commands/gsd/execute-phase.md @@ -23,6 +23,7 @@ Context budget: ~15% orchestrator, 100% fresh per subagent. +@~/.claude/get-shit-done/references/principles.md @~/.claude/get-shit-done/workflows/execute-phase.md @~/.claude/get-shit-done/templates/subagent-task-prompt.md diff --git a/commands/gsd/execute-plan.md b/commands/gsd/execute-plan.md index 5391622cf..01220ddb6 100644 --- a/commands/gsd/execute-plan.md +++ b/commands/gsd/execute-plan.md @@ -21,6 +21,7 @@ Context budget: ~15% orchestrator, 100% fresh for subagent. +@~/.claude/get-shit-done/references/principles.md @~/.claude/get-shit-done/templates/subagent-task-prompt.md diff --git a/commands/gsd/plan-phase.md b/commands/gsd/plan-phase.md index 7477bee10..d9cfe7bac 100644 --- a/commands/gsd/plan-phase.md +++ b/commands/gsd/plan-phase.md @@ -21,6 +21,7 @@ Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-na +@~/.claude/get-shit-done/references/principles.md @~/.claude/get-shit-done/workflows/plan-phase.md @~/.claude/get-shit-done/templates/phase-prompt.md @~/.claude/get-shit-done/references/plan-format.md diff --git a/commands/gsd/research-phase.md b/commands/gsd/research-phase.md index 59d4fdcd7..a22a4b708 100644 --- a/commands/gsd/research-phase.md +++ b/commands/gsd/research-phase.md @@ -27,6 +27,7 @@ Output: RESEARCH.md with ecosystem knowledge that informs quality planning. +@~/.claude/get-shit-done/references/principles.md @~/.claude/get-shit-done/workflows/research-phase.md @~/.claude/get-shit-done/templates/research.md @~/.claude/get-shit-done/references/research-pitfalls.md diff --git a/commands/gsd/research-project.md b/commands/gsd/research-project.md index 6f406fc5a..b2eaba9f2 100644 --- a/commands/gsd/research-project.md +++ b/commands/gsd/research-project.md @@ -28,6 +28,7 @@ Output: `.planning/research/` folder with ecosystem knowledge. +@~/.claude/get-shit-done/references/principles.md @~/.claude/get-shit-done/workflows/research-project.md @~/.claude/get-shit-done/templates/research-project/SUMMARY.md @~/.claude/get-shit-done/templates/research-project/STACK.md diff --git a/get-shit-done/references/principles.md b/get-shit-done/references/principles.md index abc048a9a..52fd4129e 100644 --- a/get-shit-done/references/principles.md +++ b/get-shit-done/references/principles.md @@ -1,5 +1,6 @@ -Core principles for the Gets Shit Done planning system. + +Core principles for the GSD planning system. @@ -22,15 +23,6 @@ PLAN.md IS the prompt. It contains: When planning a phase, you are writing the prompt that will execute it. - - -The most leveraged moment is project initialization. -- Deep questioning here = better everything downstream -- Garbage in = garbage out -- Spend the tokens on context gathering -- Don't rush to "the work" - - Plans must complete within reasonable context usage. @@ -54,62 +46,8 @@ If Claude CAN do it via CLI/API/tool, Claude MUST do it. Checkpoints are for: - **Verification** - Human confirms Claude's work (visual, UX) - **Decision** - Human makes implementation choice - -Not for: -- Deploying (use CLI) -- Creating resources (use CLI/API) -- Running builds/tests (use Bash) -- Writing files (use Write tool) - - -Plans are guides, not straitjackets. During execution: - -1. **Auto-fix bugs** - Fix immediately, document -2. **Auto-add critical** - Security/correctness gaps, add immediately -3. **Auto-fix blockers** - Can't proceed, fix immediately -4. **Ask about architectural** - Major changes, stop and ask -5. **Log enhancements** - Nice-to-haves, log to Issues, continue - - - - -Use TDD when the work WOULD benefit from it. Not dogma—pragmatism. - -**TDD candidates (create dedicated TDD plan):** -- Business logic with defined inputs/outputs -- API endpoints and handlers -- Data transformations and parsing -- Validation rules -- State machines and workflows -- Anything where you can describe expected behavior before implementing - -**Skip TDD (use standard plan):** -- UI layout and styling -- Exploratory prototyping -- One-off scripts and migrations -- Configuration changes -- Glue code with no logic - -**Decision heuristic:** -Can you write `expect(fn(input)).toBe(output)` before writing `fn`? -→ Yes: Create a TDD plan (one feature per plan) -→ No: Standard plan, add tests after if needed - -**Why TDD gets its own plan:** -TDD requires 2-3 execution cycles (RED → GREEN → REFACTOR), each with file reads, test runs, and potential debugging. This consumes 40-50% of context for a single feature. Dedicated TDD plans ensure full quality throughout the cycle. - -**TDD plan structure:** -1. Write failing test (RED) → commit -2. Implement to pass (GREEN) → commit -3. Refactor if needed → commit - -This is about design quality, not test coverage metrics. - -See `~/.claude/get-shit-done/references/tdd.md` for TDD plan structure. - - No enterprise process. No approval gates. @@ -119,29 +57,6 @@ Plan → Execute → Ship → Learn → Repeat Milestones mark shipped versions (v1.0 → v1.1 → v2.0). - - -**Git commits = context engineering for Claude.** - -Each task gets its own commit immediately after completion: -- Format: `{type}({phase}-{plan}): {task-description}` -- Types: feat, fix, test, refactor, perf, chore, docs -- One final metadata commit per plan: `docs({phase}-{plan}): complete [plan-name]` - -**Why per-task commits:** -- Git history becomes primary context source for future Claude sessions -- `git bisect` finds exact failing task, not just failing plan -- Each task independently revertable -- Better failure recovery (task 1 committed ✅, retry task 2) -- Observability optimized for AI workflow, not human browsing - -**Plans produce 3-4 commits total:** -- 2-3 task commits (working code) -- 1 metadata commit (SUMMARY + STATE + ROADMAP) - -See `~/.claude/get-shit-done/references/git-integration.md` for complete strategy. - - NEVER include: @@ -154,4 +69,5 @@ NEVER include: If it sounds like corporate PM theater, delete it. +