get-shit-done-cc 1.8.0 → 1.9.0

package/get-shit-done/references/model-profiles.md

@@ -0,0 +1,73 @@
+# Model Profiles
+
+Model profiles control which Claude model each GSD agent uses. This allows balancing quality vs token spend.
+
+## Profile Definitions
+
+| Agent | `quality` | `balanced` | `budget` |
+|-------|-----------|------------|----------|
+| gsd-planner | opus | opus | sonnet |
+| gsd-roadmapper | opus | sonnet | sonnet |
+| gsd-executor | opus | sonnet | sonnet |
+| gsd-phase-researcher | opus | sonnet | haiku |
+| gsd-project-researcher | opus | sonnet | haiku |
+| gsd-research-synthesizer | sonnet | sonnet | haiku |
+| gsd-debugger | opus | sonnet | sonnet |
+| gsd-codebase-mapper | sonnet | haiku | haiku |
+| gsd-verifier | sonnet | sonnet | haiku |
+| gsd-plan-checker | sonnet | sonnet | haiku |
+| gsd-integration-checker | sonnet | sonnet | haiku |
+
+## Profile Philosophy
+
+**quality** - Maximum reasoning power
+- Opus for all decision-making agents
+- Sonnet for read-only verification
+- Use when: quota available, critical architecture work
+
+**balanced** (default) - Smart allocation
+- Opus only for planning (where architecture decisions happen)
+- Sonnet for execution and research (follows explicit instructions)
+- Sonnet for verification (needs reasoning, not just pattern matching)
+- Use when: normal development, good balance of quality and cost
+
+**budget** - Minimal Opus usage
+- Sonnet for anything that writes code
+- Haiku for research and verification
+- Use when: conserving quota, high-volume work, less critical phases
+
+## Resolution Logic
+
+Orchestrators resolve model before spawning:
+
+```
+1. Read .planning/config.json
+2. Get model_profile (default: "balanced")
+3. Look up agent in table above
+4. Pass model parameter to Task call
+```
+
+## Switching Profiles
+
+Runtime: `/gsd:set-profile <profile>`
+
+Per-project default: Set in `.planning/config.json`:
+```json
+{
+  "model_profile": "balanced"
+}
+```
+
+## Design Rationale
+
+**Why Opus for gsd-planner?**
+Planning involves architecture decisions, goal decomposition, and task design. This is where model quality has the highest impact.
+
+**Why Sonnet for gsd-executor?**
+Executors follow explicit PLAN.md instructions. The plan already contains the reasoning; execution is implementation.
+
+**Why Sonnet (not Haiku) for verifiers in balanced?**
+Verification requires goal-backward reasoning - checking if code *delivers* what the phase promised, not just pattern matching. Sonnet handles this well; Haiku may miss subtle gaps.
+
+**Why Haiku for gsd-codebase-mapper?**
+Read-only exploration and pattern extraction. No reasoning required, just structured output from file contents.

package/get-shit-done/templates/config.json

@@ -1,6 +1,11 @@
 {
   "mode": "interactive",
   "depth": "standard",
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true
+  },
   "planning": {
     "commit_docs": true,
     "search_gitignored": false

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

@@ -0,0 +1,173 @@
+# Entity Template
+
+Template for `.planning/codebase/{entity-slug}.md` - file-level intelligence documentation.
+
+---
+
+## File Template
+
+```markdown
+---
+path: {path}
+type: {type}
+updated: {updated}
+status: {status}
+---
+
+# {filename}
+
+## Purpose
+
+{purpose}
+
+## Exports
+
+{exports}
+
+## Dependencies
+
+{dependencies}
+
+## Used By
+
+{used_by}
+
+## Notes
+
+{notes}
+```
+
+---
+
+## Field Reference
+
+### Frontmatter
+
+| Field | Values | Description |
+|-------|--------|-------------|
+| `path` | Absolute path | Full path to the file |
+| `type` | module, component, util, config, test, api, hook | Primary classification |
+| `updated` | YYYY-MM-DD | Last time this entity was updated |
+| `status` | active, deprecated, stub | Current state |
+
+### Sections
+
+**Purpose** (required)
+1-3 sentences covering:
+- What this file does
+- Why it exists
+- Who/what uses it (high-level)
+
+**Exports** (required for modules with exports)
+List each export with signature and description:
+```markdown
+- `functionName(arg: Type): ReturnType` - What it does
+- `ClassName` - What it represents
+- `CONSTANT_NAME` - What value it holds
+```
+
+For files without exports (config, tests), write "None" or describe what the file defines.
+
+**Dependencies** (required)
+Internal dependencies use wiki-links (slugified paths):
+```markdown
+- [[src-lib-db]] - Database client
+- [[src-types-user]] - User type definitions
+```
+
+External dependencies use plain text:
+```markdown
+- react - Component framework
+- jose - JWT handling
+```
+
+**Used By** (grows over time)
+Files that import this one, using wiki-links:
+```markdown
+- [[src-app-api-auth-route]]
+- [[src-components-dashboard]]
+```
+
+Initially may be empty or incomplete. Updated as Claude encounters imports.
+
+**Notes** (optional)
+Patterns, gotchas, or context:
+```markdown
+- Uses singleton pattern for connection pooling
+- WARNING: Must call `init()` before any other method
+- Related: See [[src-lib-cache]] for caching layer
+```
+
+---
+
+## Slug Convention
+
+Entity slugs are derived from file paths:
+- `src/lib/db.ts` becomes `src-lib-db`
+- `src/app/api/auth/route.ts` becomes `src-app-api-auth-route`
+
+Rule: Replace `/` and `.` with `-`, drop file extension.
+
+---
+
+## Example
+
+```markdown
+---
+path: /project/src/lib/auth.ts
+type: util
+updated: 2025-01-15
+status: active
+---
+
+# auth.ts
+
+## Purpose
+
+JWT token management using jose library. Handles token creation, verification, and refresh rotation. Used by all protected API routes via middleware.
+
+## Exports
+
+- `createAccessToken(userId: string): Promise<string>` - Creates 15-min access token
+- `createRefreshToken(userId: string): Promise<string>` - Creates 7-day refresh token
+- `verifyToken(token: string): Promise<TokenPayload>` - Validates and decodes token
+- `rotateRefresh(oldToken: string): Promise<TokenPair>` - Issues new token pair
+
+## Dependencies
+
+- [[src-lib-db]] - Stores refresh tokens for revocation
+- [[src-types-auth]] - TokenPayload, TokenPair types
+- jose - JWT signing and verification
+- bcrypt - Password hashing
+
+## Used By
+
+- [[src-middleware]]
+- [[src-app-api-auth-login-route]]
+- [[src-app-api-auth-logout-route]]
+- [[src-app-api-auth-refresh-route]]
+
+## Notes
+
+- Access tokens are stateless; refresh tokens stored in DB for revocation
+- Uses RS256 algorithm with keys from environment
+- WARNING: Never log token values, even in debug mode
+```
+
+---
+
+## Guidelines
+
+**When to create/update:**
+- After modifying a file during plan execution
+- When encountering a file that lacks documentation
+- When relationships change (new imports, exports)
+
+**Minimal viable entity:**
+At minimum, an entity needs frontmatter + Purpose. Other sections can be "TBD" if unknown.
+
+**Accuracy over completeness:**
+Better to have partial accurate info than complete guesses. Mark unknowns explicitly.
+
+**Link discovery:**
+The hook that processes entities extracts all `[[wiki-links]]` to build the relationship graph. Ensure links use correct slug format.

package/get-shit-done/workflows/execute-phase.md

@@ -13,7 +13,27 @@ Read config.json for planning behavior settings.
 
 <process>
 
-<step name="load_project_state" priority="first">
+<step name="resolve_model_profile" priority="first">
+Read model profile for agent spawning:
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| gsd-executor | opus | sonnet | sonnet |
+| gsd-verifier | sonnet | sonnet | haiku |
+| general-purpose | — | — | — |
+
+Store resolved models for use in Task calls below.
+</step>
+
+<step name="load_project_state">
 Before any operation, read project state:
 
 ```bash
@@ -170,9 +190,18 @@ Execute each wave in sequence. Autonomous plans within a wave run in parallel.
    - Bad: "Executing terrain generation plan"
    - Good: "Procedural terrain generator using Perlin noise — creates height maps, biome zones, and collision meshes. Required before vehicle physics can interact with ground."
 
-2. **Spawn all autonomous agents in wave simultaneously:**
+2. **Read files and spawn all autonomous agents in wave simultaneously:**
 
-   Use Task tool with multiple parallel calls. Each agent gets prompt from subagent-task-prompt template:
+   Before spawning, read file contents. The `@` syntax does not work across Task() boundaries - content must be inlined.
+
+   ```bash
+   # Read each plan in the wave
+   PLAN_CONTENT=$(cat "{plan_path}")
+   STATE_CONTENT=$(cat .planning/STATE.md)
+   CONFIG_CONTENT=$(cat .planning/config.json 2>/dev/null)
+   ```
+
+   Use Task tool with multiple parallel calls. Each agent gets prompt with inlined content:
 
    ```
    <objective>
@@ -189,9 +218,14 @@ Execute each wave in sequence. Autonomous plans within a wave run in parallel.
    </execution_context>
 
    <context>
-   Plan: @{plan_path}
-   Project state: @.planning/STATE.md
-   Config: @.planning/config.json (if exists)
+   Plan:
+   {plan_content}
+
+   Project state:
+   {state_content}
+
+   Config (if exists):
+   {config_content}
    </context>
 
    <success_criteria>
@@ -260,7 +294,7 @@ Plans with `autonomous: false` require user interaction.
 
 1. **Spawn agent for checkpoint plan:**
    ```
-   Task(prompt="{subagent-task-prompt}", subagent_type="general-purpose")
+   Task(prompt="{subagent-task-prompt}", subagent_type="gsd-executor", model="{executor_model}")
    ```
 
 2. **Agent runs until checkpoint:**
@@ -299,7 +333,8 @@ Plans with `autonomous: false` require user interaction.
    ```
    Task(
      prompt=filled_continuation_template,
-     subagent_type="general-purpose"
+     subagent_type="gsd-executor",
+     model="{executor_model}"
    )
    ```
 
@@ -375,7 +410,8 @@ Phase goal: {goal from ROADMAP.md}
 
 Check must_haves against actual codebase. Create VERIFICATION.md.
 Verify what actually exists in the code.",
-  subagent_type="gsd-verifier"
+  subagent_type="gsd-verifier",
+  model="{verifier_model}"
 )
 ```
 

package/get-shit-done/workflows/execute-plan.md

@@ -11,7 +11,25 @@ Read config.json for planning behavior settings.
 
 <process>
 
-<step name="load_project_state" priority="first">
+<step name="resolve_model_profile" priority="first">
+Read model profile for agent spawning:
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| gsd-executor | opus | sonnet | sonnet |
+
+Store resolved model for use in Task calls below.
+</step>
+
+<step name="load_project_state">
 Before any operation, read project state:
 
 ```bash
@@ -219,7 +237,7 @@ No segmentation benefit - execute entirely in main
 ```
 1. Run init_agent_tracking step first (see step below)
 
-2. Use Task tool with subagent_type="gsd-executor":
+2. Use Task tool with subagent_type="gsd-executor" and model="{executor_model}":
 
    Prompt: "Execute plan at .planning/phases/{phase}-{plan}-PLAN.md
 
@@ -371,7 +389,7 @@ For Pattern A (fully autonomous) and Pattern C (decision-dependent), skip this s
 
    B. If routing = Subagent:
       ```
-      Spawn Task tool with subagent_type="gsd-executor":
+      Spawn Task tool with subagent_type="gsd-executor" and model="{executor_model}":
 
       Prompt: "Execute tasks [task numbers/names] from plan at [plan path].
 
@@ -580,7 +598,8 @@ Execute each task in the prompt. **Deviations are normal** - handle them automat
    - Continue implementing, applying rules as needed
    - Run the verification
    - Confirm done criteria met
-   - **Commit the task** (see `<task_commit>` below)
+   - **Update intel entities** for modified files (see `<update_intel_entity>` below)
+   - **Commit the task** (see `<task_commit>` below) - includes entity files in commit
    - Track task completion and commit hash for Summary documentation
    - Continue to next task
 
@@ -909,6 +928,148 @@ None - plan executed exactly as written.
 
 </deviation_documentation>
 
+<update_intel_entity>
+
+## Update Codebase Intelligence Entity
+
+**Trigger:** After each task's `<done>` criteria met, BEFORE committing.
+
+This step documents your understanding of modified files. The knowledge base self-evolves as you work.
+
+**1. Get files from the just-completed task:**
+
+Check the task's `<files>` list. If no `<files>` attribute, use `git status --short` to identify modified files.
+
+**2. For each file, determine if significant:**
+
+**Skip these patterns (not worth indexing):**
+```bash
+# Build/generated
+node_modules/*, .next/*, dist/*, build/*, .git/*
+
+# Tests (their targets are more valuable)
+*.test.*, *.spec.*, __tests__/*, __mocks__/*
+
+# Config files (change rarely, low context value)
+package.json, package-lock.json, tsconfig.json, *.config.*, *.config.js, *.config.ts
+
+# Environment and locks
+.env*, *.lock, *.log, yarn.lock, pnpm-lock.yaml
+```
+
+If file matches skip pattern: continue to next file.
+
+**3. Derive entity path:**
+
+```bash
+# Convert file path to entity filename
+# src/lib/auth.ts → src-lib-auth.md
+# app/api/users/route.ts → app-api-users-route.md
+
+FILE_PATH="$1"
+ENTITY_NAME=$(echo "$FILE_PATH" | sed 's|^[./]*||' | tr '/' '-' | sed 's/\.[^.]*$//')
+ENTITY_PATH=".planning/intel/entities/${ENTITY_NAME}.md"
+```
+
+**4. Create intel directory if needed:**
+
+```bash
+mkdir -p .planning/intel/entities
+```
+
+**5. Check if entity exists:**
+
+```bash
+if [ -f "$ENTITY_PATH" ]; then
+  ACTION="update"
+else
+  ACTION="create"
+fi
+```
+
+**6. Create or update entity:**
+
+Use template from `~/.claude/get-shit-done/templates/entity.md`.
+
+Fill fields based on what you just built:
+
+| Field | Source |
+|-------|--------|
+| `path` | Absolute path to file |
+| `type` | Infer: module, component, util, config, api, hook |
+| `updated` | Today's date (YYYY-MM-DD) |
+| `status` | active (unless you're deprecating) |
+| **Purpose** | What you understand this file does |
+| **Exports** | Extract from the code you just wrote |
+| **Dependencies** | `[[slugified-path]]` for internal, plain for external |
+| **Used By** | Add callers if you know them from this session |
+| **Notes** | Gotchas, patterns, warnings discovered |
+
+**If updating existing entity:**
+- Read current content first
+- Preserve Used By entries you didn't touch
+- Update sections that changed
+- Don't remove information unless it's wrong
+
+**7. Write entity file:**
+
+```bash
+# Write the entity content
+cat > "$ENTITY_PATH" << 'EOF'
+---
+path: {path}
+type: {type}
+updated: {today}
+status: active
+---
+
+# {filename}
+
+## Purpose
+
+{purpose}
+
+## Exports
+
+{exports}
+
+## Dependencies
+
+{dependencies}
+
+## Used By
+
+{used_by}
+
+## Notes
+
+{notes}
+EOF
+```
+
+**8. Verify entity was created/updated:**
+
+```bash
+head -10 "$ENTITY_PATH"
+```
+
+**9. Stage entity file:**
+
+Entity files are staged along with task code files in the task commit.
+
+```bash
+git add "$ENTITY_PATH"
+```
+
+**Error handling:**
+- If entity creation fails: Log warning, continue to task_commit
+- Entity update is NOT blocking - a failed entity shouldn't stop code from being committed
+- Log: `"Warning: Could not update entity for {file}: {reason}"`
+
+**Target size:** Keep entities concise (30-50 lines). Purpose and Exports are most valuable.
+
+</update_intel_entity>
+
 <tdd_plan_execution>
 ## TDD Plan Execution
 

package/get-shit-done/workflows/map-codebase.md

@@ -22,7 +22,25 @@ Documents are reference material for Claude when planning/executing. Always incl
 
 <process>
 
-<step name="check_existing" priority="first">
+<step name="resolve_model_profile" priority="first">
+Read model profile for agent spawning:
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| gsd-codebase-mapper | sonnet | haiku | haiku |
+
+Store resolved model for use in Task calls below.
+</step>
+
+<step name="check_existing">
 Check if .planning/codebase/ already exists:
 
 ```bash
@@ -73,7 +91,7 @@ Continue to spawn_agents.
 <step name="spawn_agents">
 Spawn 4 parallel gsd-codebase-mapper agents.
 
-Use Task tool with `subagent_type="gsd-codebase-mapper"` and `run_in_background=true` for parallel execution.
+Use Task tool with `subagent_type="gsd-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
 
 **CRITICAL:** Use the dedicated `gsd-codebase-mapper` agent, NOT `Explore`. The mapper agent writes documents directly.
 
@@ -82,6 +100,7 @@ Use Task tool with `subagent_type="gsd-codebase-mapper"` and `run_in_background=
 Task tool parameters:
 ```
 subagent_type: "gsd-codebase-mapper"
+model: "{mapper_model}"
 run_in_background: true
 description: "Map codebase tech stack"
 ```
@@ -104,6 +123,7 @@ Explore thoroughly. Write documents directly using templates. Return confirmatio
 Task tool parameters:
 ```
 subagent_type: "gsd-codebase-mapper"
+model: "{mapper_model}"
 run_in_background: true
 description: "Map codebase architecture"
 ```
@@ -126,6 +146,7 @@ Explore thoroughly. Write documents directly using templates. Return confirmatio
 Task tool parameters:
 ```
 subagent_type: "gsd-codebase-mapper"
+model: "{mapper_model}"
 run_in_background: true
 description: "Map codebase conventions"
 ```
@@ -148,6 +169,7 @@ Explore thoroughly. Write documents directly using templates. Return confirmatio
 Task tool parameters:
 ```
 subagent_type: "gsd-codebase-mapper"
+model: "{mapper_model}"
 run_in_background: true
 description: "Map codebase concerns"
 ```

package/get-shit-done/workflows/verify-work.md

@@ -20,6 +20,25 @@ No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. D
 
 <process>
 
+<step name="resolve_model_profile" priority="first">
+Read model profile for agent spawning:
+
+```bash
+MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| gsd-planner | opus | opus | sonnet |
+| gsd-plan-checker | sonnet | sonnet | haiku |
+
+Store resolved models for use in Task calls below.
+</step>
+
 <step name="check_active_session">
 **First: Check for active UAT sessions**
 
@@ -389,6 +408,7 @@ Plans must be executable prompts.
 </downstream_consumer>
 """,
   subagent_type="gsd-planner",
+  model="{planner_model}",
   description="Plan gap fixes for Phase {phase}"
 )
 ```
@@ -434,6 +454,7 @@ Return one of:
 </expected_output>
 """,
   subagent_type="gsd-plan-checker",
+  model="{checker_model}",
   description="Verify Phase {phase} fix plans"
 )
 ```
@@ -474,6 +495,7 @@ Do NOT replan from scratch unless issues are fundamental.
 </instructions>
 """,
   subagent_type="gsd-planner",
+  model="{planner_model}",
   description="Revise Phase {phase} plans"
 )
 ```