refactor: consolidate expertise into agents

Commands load agent expertise directly via Task tool spawning.
Thin orchestrator pattern — agents have methodology baked in.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-01-16 16:59:42 -06:00
parent 247e991eaf
commit 6fd95c3ce5
25 changed files with 6 additions and 524 deletions

View File

@@ -18,7 +18,7 @@ Verify milestone achieved its definition of done. Check requirements coverage, c
</objective>
<execution_context>
@~/.claude/get-shit-done/references/principles.md
<!-- Spawns gsd-integration-checker agent which has all audit expertise baked in -->
</execution_context>
<context>

View File

@@ -35,11 +35,9 @@ Roadmaps define what work happens in what order. Phases map to requirements.
</objective>
<execution_context>
@~/.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
@~/.claude/get-shit-done/references/goal-backward.md
</execution_context>
<context>

View File

@@ -36,7 +36,6 @@ Output: `.planning/REQUIREMENTS.md`
</objective>
<execution_context>
@~/.claude/get-shit-done/references/principles.md
@~/.claude/get-shit-done/workflows/define-requirements.md
@~/.claude/get-shit-done/templates/requirements.md
</execution_context>

View File

@@ -11,7 +11,6 @@ Output: Context gathered, then routes to /gsd:new-milestone
</objective>
<execution_context>
@~/.claude/get-shit-done/references/principles.md
@~/.claude/get-shit-done/workflows/discuss-milestone.md
</execution_context>

View File

@@ -18,7 +18,6 @@ Extract implementation decisions that downstream agents need — researcher and
</objective>
<execution_context>
@~/.claude/get-shit-done/references/principles.md
@~/.claude/get-shit-done/workflows/discuss-phase.md
@~/.claude/get-shit-done/templates/context.md
</execution_context>

View File

@@ -23,7 +23,6 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
</objective>
<execution_context>
@~/.claude/get-shit-done/references/principles.md
@~/.claude/get-shit-done/references/ui-brand.md
@~/.claude/get-shit-done/workflows/execute-phase.md
</execution_context>

View File

@@ -25,7 +25,7 @@ Context budget: ~15% orchestrator, 100% fresh for subagent.
</objective>
<execution_context>
@~/.claude/get-shit-done/references/principles.md
<!-- Spawns gsd-executor agent which has all execution expertise baked in -->
</execution_context>
<context>

View File

@@ -19,8 +19,7 @@ One command creates all fix phases — no manual `/gsd:add-phase` per gap.
</objective>
<execution_context>
@~/.claude/get-shit-done/references/principles.md
@~/.claude/get-shit-done/workflows/plan-phase.md
<!-- Spawns gsd-planner agent which has all planning expertise baked in -->
</execution_context>
<context>

View File

@@ -1,11 +0,0 @@
# Debugging Mindset (DEPRECATED)
This reference has been consolidated into the `gsd-debugger` agent.
**Location:** `agents/gsd-debugger.md`
**Section:** `<philosophy>`
**Reason:** Debugging expertise is now baked into the agent. Loading separate reference files into orchestrator context was wasteful (~95% context reduction).
See `agents/gsd-debugger.md` for the consolidated debugging methodology.

View File

@@ -1,11 +0,0 @@
# Hypothesis Testing (DEPRECATED)
This reference has been consolidated into the `gsd-debugger` agent.
**Location:** `agents/gsd-debugger.md`
**Section:** `<hypothesis_testing>`
**Reason:** Debugging expertise is now baked into the agent. Loading separate reference files into orchestrator context was wasteful (~95% context reduction).
See `agents/gsd-debugger.md` for the consolidated debugging methodology.

View File

@@ -1,11 +0,0 @@
# Investigation Techniques (DEPRECATED)
This reference has been consolidated into the `gsd-debugger` agent.
**Location:** `agents/gsd-debugger.md`
**Section:** `<investigation_techniques>`
**Reason:** Debugging expertise is now baked into the agent. Loading separate reference files into orchestrator context was wasteful (~95% context reduction).
See `agents/gsd-debugger.md` for the consolidated debugging methodology.

View File

@@ -1,11 +0,0 @@
# Verification Patterns (DEPRECATED)
This reference has been consolidated into the `gsd-debugger` agent.
**Location:** `agents/gsd-debugger.md`
**Section:** `<verification_patterns>`
**Reason:** Debugging expertise is now baked into the agent. Loading separate reference files into orchestrator context was wasteful (~95% context reduction).
See `agents/gsd-debugger.md` for the consolidated debugging methodology.

View File

@@ -1,11 +0,0 @@
# When to Research (DEPRECATED)
This reference has been consolidated into the `gsd-debugger` agent.
**Location:** `agents/gsd-debugger.md`
**Section:** `<research_vs_reasoning>`
**Reason:** Debugging expertise is now baked into the agent. Loading separate reference files into orchestrator context was wasteful (~95% context reduction).
See `agents/gsd-debugger.md` for the consolidated debugging methodology.

View File

@@ -1,33 +0,0 @@
# DEPRECATED: Goal-Backward Planning Reference
**This reference has been consolidated into the gsd-planner agent.**
## Migration
Planning expertise is now baked into:
- `agents/gsd-planner.md` - Section: `<goal_backward>`
## Why This Changed
The thin orchestrator pattern consolidates all planning methodology into the agent:
- Before: Reference files loaded separately (~287 lines)
- After: Agent has expertise baked in, orchestrator is thin
## Historical Reference
This file previously contained:
- Goal-backward vs forward planning distinction
- Must-haves derivation process (5 steps)
- Observable truths from user perspective
- Required artifacts mapping
- Required wiring analysis
- Key links identification
- must_haves YAML structure for PLAN.md frontmatter
- Examples (e-commerce, settings, notifications)
- Common failures and anti-patterns
All content preserved in `agents/gsd-planner.md`.
---
*Deprecated: 2026-01-16*
*Replaced by: agents/gsd-planner.md*

View File

@@ -1,32 +0,0 @@
# DEPRECATED: Plan Format Reference
**This reference has been consolidated into the gsd-planner agent.**
## Migration
Planning expertise is now baked into:
- `agents/gsd-planner.md` - Section: `<plan_format>`
## Why This Changed
The thin orchestrator pattern consolidates all planning methodology into the agent:
- Before: Reference files loaded separately (~474 lines)
- After: Agent has expertise baked in, orchestrator is thin
## Historical Reference
This file previously contained:
- PLAN.md frontmatter structure
- XML prompt structure
- Task anatomy (files, action, verify, done)
- Task types (auto, checkpoint:*)
- TDD plans guidance
- Context references and anti-patterns
- Specificity levels (too vague vs just right)
- Task sizing guidance
All content preserved in `agents/gsd-planner.md`.
---
*Deprecated: 2026-01-16*
*Replaced by: agents/gsd-planner.md*

View File

@@ -1,29 +0,0 @@
# DEPRECATED: GSD Principles
**This reference has been consolidated into the gsd-planner agent.**
## Migration
Planning expertise is now baked into:
- `agents/gsd-planner.md` - Section: `<philosophy>`
## Why This Changed
The thin orchestrator pattern consolidates all planning methodology into the agent:
- Before: Reference files loaded separately (~74 lines)
- After: Agent has expertise baked in, orchestrator is thin
## Historical Reference
This file previously contained:
- Solo developer + Claude workflow philosophy
- "Plans are prompts" principle
- Scope control and quality degradation curve
- "Claude automates" and "ship fast" principles
- Anti-enterprise patterns
All content preserved in `agents/gsd-planner.md`.
---
*Deprecated: 2026-01-16*
*Replaced by: agents/gsd-planner.md*

View File

@@ -1,233 +0,0 @@
# Research Pitfalls Reference
## DEPRECATED
**This reference has been consolidated into the gsd-researcher agent.**
The verification protocols and pitfall patterns now live in:
- `agents/gsd-researcher.md` (section: `<verification_protocol>`)
The content below is preserved for reference but is no longer the primary source.
---
*Deprecated: 2026-01-15*
*Replaced by: agents/gsd-researcher.md*
---
<research_pitfalls>
<purpose>
This document catalogs research mistakes discovered in production use, providing specific patterns to avoid and verification strategies to prevent recurrence.
</purpose>
<known_pitfalls>
<pitfall_config_scope>
**What**: Assuming global configuration means no project-scoping exists
**Example**: Concluding "MCP servers are configured GLOBALLY only" while missing project-scoped `.mcp.json`
**Why it happens**: Not explicitly checking all known configuration patterns
**Prevention**:
```xml
<verification_checklist>
**CRITICAL**: Verify ALL configuration scopes:
- User/global scope - System-wide configuration
- Project scope - Project-level configuration files
- Local scope - Project-specific user overrides
- Workspace scope - IDE/tool workspace settings
- Environment scope - Environment variables
</verification_checklist>
```
</pitfall_config_scope>
<pitfall_search_vagueness>
**What**: Asking researchers to "search for documentation" without specifying where
**Example**: "Research MCP documentation" -> finds outdated community blog instead of official docs
**Why it happens**: Vague research instructions don't specify exact sources
**Prevention**:
```xml
<sources>
Official sources (use WebFetch):
- https://exact-url-to-official-docs
- https://exact-url-to-api-reference
Search queries (use WebSearch):
- "specific search query {current_year}"
- "another specific query {current_year}"
</sources>
```
</pitfall_search_vagueness>
<pitfall_deprecated_features>
**What**: Finding archived/old documentation and concluding feature doesn't exist
**Example**: Finding 2022 docs saying "feature not supported" when current version added it
**Why it happens**: Not checking multiple sources or recent updates
**Prevention**:
```xml
<verification_checklist>
- Check current official documentation
- Review changelog/release notes for recent updates
- Verify version numbers and publication dates
- Cross-reference multiple authoritative sources
</verification_checklist>
```
</pitfall_deprecated_features>
<pitfall_tool_variations>
**What**: Conflating capabilities across different tools/environments
**Example**: "Claude Desktop supports X" does not mean "Claude Code supports X"
**Why it happens**: Not explicitly checking each environment separately
**Prevention**:
```xml
<verification_checklist>
- Claude Desktop capabilities
- Claude Code capabilities
- VS Code extension capabilities
- API/SDK capabilities
Document which environment supports which features
</verification_checklist>
```
</pitfall_tool_variations>
<pitfall_negative_claims>
**What**: Making definitive "X is not possible" statements without official source verification
**Example**: "Folder-scoped MCP configuration is not supported" (missing `.mcp.json`)
**Why it happens**: Drawing conclusions from absence of evidence rather than evidence of absence
**Prevention**:
```xml
<critical_claims_audit>
For any "X is not possible" or "Y is the only way" statement:
- [ ] Is this verified by official documentation stating it explicitly?
- [ ] Have I checked for recent updates that might change this?
- [ ] Have I verified all possible approaches/mechanisms?
- [ ] Am I confusing "I didn't find it" with "it doesn't exist"?
</critical_claims_audit>
```
</pitfall_negative_claims>
<pitfall_missing_enumeration>
**What**: Investigating open-ended scope without enumerating known possibilities first
**Example**: "Research configuration options" instead of listing specific options to verify
**Why it happens**: Not creating explicit checklist of items to investigate
**Prevention**:
```xml
<verification_checklist>
Enumerate ALL known options FIRST:
- Option 1: [specific item]
- Option 2: [specific item]
- Option 3: [specific item]
- Check for additional unlisted options
For each option above, document:
- Existence (confirmed/not found/unclear)
- Official source URL
- Current status (active/deprecated/beta)
</verification_checklist>
```
</pitfall_missing_enumeration>
<pitfall_single_source>
**What**: Relying on a single source for critical claims
**Example**: Using only Stack Overflow answer from 2021 for current best practices
**Why it happens**: Not cross-referencing multiple authoritative sources
**Prevention**:
```xml
<source_verification>
For critical claims, require multiple sources:
- [ ] Official documentation (primary)
- [ ] Release notes/changelog (for currency)
- [ ] Additional authoritative source (for verification)
- [ ] Contradiction check (ensure sources agree)
</source_verification>
```
</pitfall_single_source>
<pitfall_assumed_completeness>
**What**: Assuming search results are complete and authoritative
**Example**: First Google result is outdated but assumed current
**Why it happens**: Not verifying publication dates and source authority
**Prevention**:
```xml
<source_verification>
For each source consulted:
- [ ] Publication/update date verified (prefer recent/current)
- [ ] Source authority confirmed (official docs, not blogs)
- [ ] Version relevance checked (matches current version)
- [ ] Multiple search queries tried (not just one)
</source_verification>
```
</pitfall_assumed_completeness>
</known_pitfalls>
<red_flags>
<red_flag_zero_not_found>
**Warning**: Every investigation succeeds perfectly
**Problem**: Real research encounters dead ends, ambiguity, and unknowns
**Action**: Expect honest reporting of limitations, contradictions, and gaps
</red_flag_zero_not_found>
<red_flag_no_confidence>
**Warning**: All findings presented as equally certain
**Problem**: Can't distinguish verified facts from educated guesses
**Action**: Require confidence levels (High/Medium/Low) for key findings
</red_flag_no_confidence>
<red_flag_missing_urls>
**Warning**: "According to documentation..." without specific URL
**Problem**: Can't verify claims or check for updates
**Action**: Require actual URLs for all official documentation claims
</red_flag_missing_urls>
<red_flag_no_evidence>
**Warning**: "X cannot do Y" or "Z is the only way" without citation
**Problem**: Strong claims require strong evidence
**Action**: Flag for verification against official sources
</red_flag_no_evidence>
<red_flag_incomplete_enum>
**Warning**: Verification checklist lists 4 items, output covers 2
**Problem**: Systematic gaps in coverage
**Action**: Ensure all enumerated items addressed or marked "not found"
</red_flag_incomplete_enum>
</red_flags>
<continuous_improvement>
When research gaps occur:
1. **Document the gap**
- What was missed or incorrect?
- What was the actual correct information?
- What was the impact?
2. **Root cause analysis**
- Why wasn't it caught?
- Which verification step would have prevented it?
- What pattern does this reveal?
3. **Update this document**
- Add new pitfall entry
- Update relevant checklists
- Share lesson learned
</continuous_improvement>
<quick_reference>
Before submitting research, verify:
- [ ] All enumerated items investigated (not just some)
- [ ] Negative claims verified with official docs
- [ ] Multiple sources cross-referenced for critical claims
- [ ] URLs provided for all official documentation
- [ ] Publication dates checked (prefer recent/current)
- [ ] Tool/environment-specific variations documented
- [ ] Confidence levels assigned honestly
- [ ] Assumptions distinguished from verified facts
- [ ] "What might I have missed?" review completed
**Living Document**: Update after each significant research gap
**Lessons From**: MCP configuration research gap (missed `.mcp.json`)
</quick_reference>
</research_pitfalls>

View File

@@ -1,32 +0,0 @@
# DEPRECATED: Scope Estimation Reference
**This reference has been consolidated into the gsd-planner agent.**
## Migration
Planning expertise is now baked into:
- `agents/gsd-planner.md` - Section: `<scope_estimation>`
## Why This Changed
The thin orchestrator pattern consolidates all planning methodology into the agent:
- Before: Reference files loaded separately (~257 lines)
- After: Agent has expertise baked in, orchestrator is thin
## Historical Reference
This file previously contained:
- Quality degradation curve (0-30%, 30-50%, 50-70%, 70%+)
- Context budget targets (~50%)
- Task-per-plan rules (2-3 tasks)
- Split signals (always split, consider splitting)
- Splitting strategies (vertical slices preferred)
- Dependency awareness and wave assignment
- File ownership for parallel execution
- Depth calibration (quick, standard, comprehensive)
All content preserved in `agents/gsd-planner.md`.
---
*Deprecated: 2026-01-16*
*Replaced by: agents/gsd-planner.md*

View File

@@ -573,5 +573,4 @@ Task completion ≠ Goal achievement. A task "create chat component" can complet
5. Gaps found → fix plans created → execute → re-verify
6. All must_haves pass → phase complete
See `~/.claude/get-shit-done/references/goal-backward.md` for derivation process.
See `~/.claude/get-shit-done/workflows/verify-phase.md` for verification logic.

View File

@@ -1,14 +0,0 @@
# Debug Workflow (DEPRECATED)
This workflow has been consolidated into the `gsd-debugger` agent.
**Location:** `agents/gsd-debugger.md`
**Reason:** The gsd-debugger agent contains all debugging expertise. Loading a separate workflow into orchestrator context was wasteful.
**Migration:**
- `/gsd:debug` now spawns `gsd-debugger` agent directly
- All debugging methodology lives in the agent file
- Templates remain at `get-shit-done/templates/DEBUG.md`
See `agents/gsd-debugger.md` for debugging expertise.

View File

@@ -107,7 +107,7 @@ For: Choosing between options, new external integration.
5. **Cross-verify:** Any WebSearch finding → confirm with Context7/official docs.
6. **Quality check:** Before finalizing findings, consult ~/.claude/get-shit-done/references/research-pitfalls.md to avoid common research gaps.
6. **Quality check:** Before finalizing findings, consult the gsd-researcher agent's verification protocols to avoid common research gaps.
7. **Create DISCOVERY.md** using ~/.claude/get-shit-done/templates/discovery.md structure:
@@ -160,7 +160,7 @@ For: Architectural decisions, novel problems, high-risk choices.
- Mark what's verified vs assumed
- Flag contradictions
6. **Quality check:** Before finalizing findings, consult ~/.claude/get-shit-done/references/research-pitfalls.md to ensure comprehensive coverage and avoid common research gaps.
6. **Quality check:** Before finalizing findings, consult the gsd-researcher agent's verification protocols to ensure comprehensive coverage and avoid common research gaps.
7. **Create comprehensive DISCOVERY.md:**

View File

@@ -1,41 +0,0 @@
# DEPRECATED: Plan-Phase Workflow
**This workflow has been consolidated into the gsd-planner agent.**
## Migration
Planning expertise is now baked into:
- `agents/gsd-planner.md` - Complete planning methodology
The `/gsd:plan-phase` command spawns the gsd-planner agent directly.
## Why This Changed
The thin orchestrator pattern reduces main context usage:
- Before: ~3,580 lines loaded into main context
- After: ~150 lines in orchestrator, expertise in agent
## Historical Reference
This file previously contained:
- Decimal phase numbering rules
- Required reading list (8 reference files)
- Planning principles and philosophy
- Discovery level definitions (Level 0-3)
- Project history assembly via frontmatter dependency graph
- Gap closure mode process
- Task breakdown with TDD detection
- Dependency graph building
- Wave assignment algorithm
- Plan grouping rules
- Scope estimation and depth calibration
- Phase prompt writing (PLAN.md structure)
- User setup frontmatter for external services
- Git commit step
- Success criteria (standard and gap closure modes)
All content preserved in `agents/gsd-planner.md`.
---
*Deprecated: 2026-01-16*
*Replaced by: agents/gsd-planner.md*

View File

@@ -1,17 +0,0 @@
# Research Phase Workflow
## DEPRECATED
**This workflow has been consolidated into the gsd-researcher agent.**
The research methodology, tool strategy, source hierarchy, and verification protocols now live in:
- `agents/gsd-researcher.md`
The `/gsd:research-phase` command spawns the gsd-researcher agent directly.
**Migration:** No action needed - the command handles this automatically.
---
*Deprecated: 2026-01-15*
*Replaced by: agents/gsd-researcher.md*

View File

@@ -1,23 +0,0 @@
# Research Project Workflow
## DEPRECATED
**This workflow has been consolidated into the gsd-researcher agent.**
The research methodology for project research now lives in:
- `agents/gsd-researcher.md`
The `/gsd:research-project` command spawns 4 parallel gsd-researcher agents:
- Stack agent -> .planning/research/STACK.md
- Features agent -> .planning/research/FEATURES.md
- Architecture agent -> .planning/research/ARCHITECTURE.md
- Pitfalls agent -> .planning/research/PITFALLS.md
The orchestrator synthesizes SUMMARY.md after all agents complete.
**Migration:** No action needed - the command handles this automatically.
---
*Deprecated: 2026-01-15*
*Replaced by: agents/gsd-researcher.md*

View File

@@ -19,7 +19,6 @@ Then verify each level against the actual codebase.
<required_reading>
**Load these references:**
- ~/.claude/get-shit-done/references/goal-backward.md (derivation process)
- ~/.claude/get-shit-done/references/verification-patterns.md (detection patterns)
- ~/.claude/get-shit-done/templates/verification-report.md (output format)
</required_reading>
@@ -97,7 +96,7 @@ If no must_haves in frontmatter, derive using goal-backward process:
5. **Document derived must-haves** before proceeding to verification.
See ~/.claude/get-shit-done/references/goal-backward.md for detailed derivation guidance.
<!-- Goal-backward derivation expertise is baked into the gsd-verifier agent -->
</step>
<step name="verify_truths">