gsd-opencode 1.3.33 → 1.4.2

package/get-shit-done/references/scope-estimation.md

@@ -78,15 +78,78 @@ See `~/.config/opencode/get-shit-done/references/tdd.md` for TDD plan structure.
 </split_signals>
 
 <splitting_strategies>
-**By subsystem:** Auth → 01: DB models, 02: API routes, 03: Protected routes, 04: UI components
+**Vertical slices (default):** Group by feature, not by layer.
 
-**By dependency:** Payments → 01: Stripe setup, 02: Subscription logic, 03: Frontend integration
+```
+PREFER: Plan 01 = User (model + API + UI)
+        Plan 02 = Product (model + API + UI)
+        Plan 03 = Order (model + API + UI)
+
+AVOID:  Plan 01 = All models
+        Plan 02 = All APIs (depends on 01)
+        Plan 03 = All UIs (depends on 02)
+```
 
-**By complexity:** Dashboard → 01: Layout shell, 02: Data fetching, 03: Visualization
+Vertical slices maximize parallelism: [01, 02, 03] run simultaneously.
+Horizontal layers force sequential execution: 01 → 02 → 03.
 
-**By verification:** Deploy → 01: Vercel setup (checkpoint), 02: Env config (auto), 03: CI/CD (checkpoint)
+**By dependency:** Only when genuine dependencies exist.
+```
+Plan 01: Auth foundation (middleware, JWT utils)
+Plan 02: Protected features (uses auth from 01)
+```
+
+**By complexity:** When one slice is much heavier.
+```
+Plan 01: Dashboard layout shell
+Plan 02: Data fetching and state
+Plan 03: Visualization components
+```
 </splitting_strategies>
 
+<dependency_awareness>
+**Plans declare dependencies explicitly via frontmatter.**
+
+```yaml
+# Independent plan (Wave 1 candidate)
+depends_on: []
+files_modified: [src/features/user/model.ts, src/features/user/api.ts]
+autonomous: true
+
+# Dependent plan (later wave)
+depends_on: ["03-01"]
+files_modified: [src/integration/stripe.ts]
+autonomous: true
+```
+
+**Wave assignment rules:**
+- `depends_on: []` + no file conflicts → Wave 1 (parallel)
+- `depends_on: ["XX"]` → runs after plan XX completes
+- Shared `files_modified` with sibling → sequential (by plan number)
+
+**SUMMARY references:**
+- Only reference prior SUMMARY if genuinely needed (imported types, decisions affecting this plan)
+- Independent plans need NO prior SUMMARY references
+- Reflexive chaining (02 refs 01, 03 refs 02) is an anti-pattern
+</dependency_awareness>
+
+<file_ownership>
+**Exclusive file ownership prevents conflicts:**
+
+```yaml
+# Plan 01 frontmatter
+files_modified: [src/models/user.ts, src/api/users.ts, src/components/UserList.tsx]
+
+# Plan 02 frontmatter
+files_modified: [src/models/product.ts, src/api/products.ts, src/components/ProductList.tsx]
+```
+
+No overlap → can run parallel.
+
+**If file appears in multiple plans:** Later plan depends on earlier (by plan number).
+**If file cannot be split:** Plans must be sequential for that file.
+</file_ownership>
+
 <anti_patterns>
 **Bad - Comprehensive plan:**
 ```
@@ -101,8 +164,26 @@ Plan 1: "Auth Database Models" (2 tasks)
 Plan 2: "Auth API Core" (3 tasks)
 Plan 3: "Auth API Protection" (2 tasks)
 Plan 4: "Auth UI Components" (2 tasks)
-Each: 30-40% context, peak quality, atomic commits (2-3 task commits + 1 metadata commit)
+Each: 30-40% context, peak quality, atomic commits
 ```
+
+**Bad - Horizontal layers (sequential):**
+```
+Plan 01: Create User model, Product model, Order model
+Plan 02: Create /api/users, /api/products, /api/orders
+Plan 03: Create UserList UI, ProductList UI, OrderList UI
+```
+Result: 02 depends on 01, 03 depends on 02
+Waves: [01] → [02] → [03] (fully sequential)
+
+**Good - Vertical slices (parallel):**
+```
+Plan 01: User feature (model + API + UI)
+Plan 02: Product feature (model + API + UI)
+Plan 03: Order feature (model + API + UI)
+```
+Result: Each plan self-contained, no file overlap
+Waves: [01, 02, 03] (all parallel)
 </anti_patterns>
 
 <estimating_context>
@@ -158,15 +239,18 @@ Each plan: fresh context, peak quality. More plans = more thoroughness, same qua
 <summary>
 **2-3 tasks, 50% context target:**
 - All tasks: Peak quality
-- Git: Atomic per-task commits (each task = 1 commit, plan = 1 metadata commit)
-- Autonomous plans: Subagent execution (fresh context)
+- Git: Atomic per-task commits
+- Parallel by default: Fresh context per subagent
 
 **The principle:** Aggressive atomicity. More plans, smaller scope, consistent quality.
 
-**The rule:** If in doubt, split. Quality over consolidation. Always.
-
-**Depth rule:** Depth increases plan COUNT, never plan SIZE.
+**The rules:**
+- If in doubt, split. Quality over consolidation.
+- Depth increases plan COUNT, never plan SIZE.
+- Vertical slices over horizontal layers.
+- Explicit dependencies via `depends_on` frontmatter.
+- Autonomous plans get parallel execution.
 
-**Commit rule:** Each plan produces 3-4 commits total (2-3 task commits + 1 docs commit). More granular history = better observability for Claude.
+**Commit rule:** Each plan produces 3-4 commits total (2-3 task commits + 1 docs commit).
 </summary>
 </scope_estimation>

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

@@ -0,0 +1,159 @@
+# Debug Template
+
+Template for `.planning/debug/[slug].md` — active debug session tracking.
+
+---
+
+## File Template
+
+```markdown
+---
+status: gathering | investigating | fixing | verifying | resolved
+trigger: "[verbatim user input]"
+created: [ISO timestamp]
+updated: [ISO timestamp]
+---
+
+## Current Focus
+<!-- OVERWRITE on each update - always reflects NOW -->
+
+hypothesis: [current theory being tested]
+test: [how testing it]
+expecting: [what result means if true/false]
+next_action: [immediate next step]
+
+## Symptoms
+<!-- Written during gathering, then immutable -->
+
+expected: [what should happen]
+actual: [what actually happens]
+errors: [error messages if any]
+reproduction: [how to trigger]
+started: [when it broke / always broken]
+
+## Eliminated
+<!-- APPEND only - prevents re-investigating after /clear -->
+
+- hypothesis: [theory that was wrong]
+  evidence: [what disproved it]
+  timestamp: [when eliminated]
+
+## Evidence
+<!-- APPEND only - facts discovered during investigation -->
+
+- timestamp: [when found]
+  checked: [what was examined]
+  found: [what was observed]
+  implication: [what this means]
+
+## Resolution
+<!-- OVERWRITE as understanding evolves -->
+
+root_cause: [empty until found]
+fix: [empty until applied]
+verification: [empty until verified]
+files_changed: []
+```
+
+---
+
+<section_rules>
+
+**Frontmatter (status, trigger, timestamps):**
+- `status`: OVERWRITE - reflects current phase
+- `trigger`: IMMUTABLE - verbatim user input, never changes
+- `created`: IMMUTABLE - set once
+- `updated`: OVERWRITE - update on every change
+
+**Current Focus:**
+- OVERWRITE entirely on each update
+- Always reflects what Claude is doing RIGHT NOW
+- If Claude reads this after /clear, it knows exactly where to resume
+- Fields: hypothesis, test, expecting, next_action
+
+**Symptoms:**
+- Written during initial gathering phase
+- IMMUTABLE after gathering complete
+- Reference point for what we're trying to fix
+- Fields: expected, actual, errors, reproduction, started
+
+**Eliminated:**
+- APPEND only - never remove entries
+- Prevents re-investigating dead ends after context reset
+- Each entry: hypothesis, evidence that disproved it, timestamp
+- Critical for efficiency across /clear boundaries
+
+**Evidence:**
+- APPEND only - never remove entries
+- Facts discovered during investigation
+- Each entry: timestamp, what checked, what found, implication
+- Builds the case for root cause
+
+**Resolution:**
+- OVERWRITE as understanding evolves
+- May update multiple times as fixes are tried
+- Final state shows confirmed root cause and verified fix
+- Fields: root_cause, fix, verification, files_changed
+
+</section_rules>
+
+<lifecycle>
+
+**Creation:** Immediately when /gsd:debug is called
+- Create file with trigger from user input
+- Set status to "gathering"
+- Current Focus: next_action = "gather symptoms"
+- Symptoms: empty, to be filled
+
+**During symptom gathering:**
+- Update Symptoms section as user answers questions
+- Update Current Focus with each question
+- When complete: status → "investigating"
+
+**During investigation:**
+- OVERWRITE Current Focus with each hypothesis
+- APPEND to Evidence with each finding
+- APPEND to Eliminated when hypothesis disproved
+- Update timestamp in frontmatter
+
+**During fixing:**
+- status → "fixing"
+- Update Resolution.root_cause when confirmed
+- Update Resolution.fix when applied
+- Update Resolution.files_changed
+
+**During verification:**
+- status → "verifying"
+- Update Resolution.verification with results
+- If verification fails: status → "investigating", try again
+
+**On resolution:**
+- status → "resolved"
+- Move file to .planning/debug/resolved/
+
+</lifecycle>
+
+<resume_behavior>
+
+When Claude reads this file after /clear:
+
+1. Parse frontmatter → know status
+2. Read Current Focus → know exactly what was happening
+3. Read Eliminated → know what NOT to retry
+4. Read Evidence → know what's been learned
+5. Continue from next_action
+
+The file IS the debugging brain. Claude should be able to resume perfectly from any interruption point.
+
+</resume_behavior>
+
+<size_constraint>
+
+Keep debug files focused:
+- Evidence entries: 1-2 lines each, just the facts
+- Eliminated: brief - hypothesis + why it failed
+- No narrative prose - structured data only
+
+If evidence grows very large (10+ entries), consider whether you're going in circles. Check Eliminated to ensure you're not re-treading.
+
+</size_constraint>

package/get-shit-done/templates/agent-history.md

@@ -0,0 +1,263 @@
+# Agent History Template
+
+Template for `.planning/agent-history.json` - tracks subagent spawns during plan execution for resume capability.
+
+---
+
+## File Template
+
+```json
+{
+  "version": "1.2",
+  "max_entries": 50,
+  "entries": []
+}
+```
+
+## Entry Schema
+
+Each entry tracks a subagent spawn or status change:
+
+```json
+{
+  "agent_id": "agent_01HXXXX...",
+  "task_description": "Execute tasks 1-3 from plan 02-01",
+  "phase": "02",
+  "plan": "01",
+  "segment": 1,
+  "timestamp": "2026-01-15T14:22:10Z",
+  "status": "spawned",
+  "completion_timestamp": null,
+  "execution_mode": "sequential",
+  "parallel_group": null,
+  "granularity": "plan",
+  "depends_on": null,
+  "files_modified": null,
+  "checkpoints_skipped": null,
+  "task_results": null
+}
+```
+
+### Field Definitions
+
+| Field | Type | Description |
+|-------|------|-------------|
+| agent_id | string | Unique ID returned by Task tool |
+| task_description | string | Brief description of what agent is executing |
+| phase | string | Phase number (e.g., "02", "02.1") |
+| plan | string | Plan number within phase |
+| segment | number/null | Segment number for segmented plans, null for full plan |
+| timestamp | string | ISO 8601 timestamp when agent was spawned |
+| status | string | spawned, completed, interrupted, resumed, queued, failed |
+| completion_timestamp | string/null | ISO timestamp when completed |
+| execution_mode | string | "sequential" or "parallel" |
+| parallel_group | string/null | Batch ID linking agents in same parallel execution |
+| granularity | string | "plan" or "task_group" |
+| depends_on | array/null | Agent IDs or plan refs this depends on |
+| files_modified | array/null | Files this agent created/modified |
+| checkpoints_skipped | number/null | Count of checkpoints skipped in background |
+| task_results | object/null | Per-task outcomes for task-level parallelization |
+
+### Status Lifecycle
+
+```
+queued ──> spawned ──────────────────> completed
+               │                           ^
+               │                           │
+               ├──> interrupted ──> resumed┘
+               │
+               └──> failed
+```
+
+- **queued**: Waiting for dependency (parallel execution only)
+- **spawned**: Agent created via Task tool, execution in progress
+- **completed**: Agent finished successfully, results received
+- **interrupted**: Session ended before agent completed (detected on resume)
+- **resumed**: Previously interrupted agent resumed via resume parameter
+- **failed**: Agent execution failed (error during execution)
+
+## Usage
+
+### When to Create File
+
+Create `.planning/agent-history.json` from this template when:
+- First subagent spawn in execute-plan workflow
+- File doesn't exist yet
+
+### When to Add Entry
+
+Add new entry immediately after Task tool returns with agent_id:
+
+```
+1. Task tool spawns subagent
+2. Response includes agent_id
+3. Write agent_id to .planning/current-agent-id.txt
+4. Append entry to agent-history.json with status "spawned"
+```
+
+### When to Update Entry
+
+Update existing entry when:
+
+**On successful completion:**
+```json
+{
+  "status": "completed",
+  "completion_timestamp": "2026-01-15T14:45:33Z"
+}
+```
+
+**On resume detection (interrupted agent found):**
+```json
+{
+  "status": "interrupted"
+}
+```
+
+Then add new entry with resumed status:
+```json
+{
+  "agent_id": "agent_01HXXXX...",
+  "status": "resumed",
+  "timestamp": "2026-01-15T15:00:00Z"
+}
+```
+
+### Entry Retention
+
+- Keep maximum 50 entries (configurable via max_entries)
+- On exceeding limit, remove oldest completed entries first
+- Never remove entries with status "spawned" (may need resume)
+- Prune during init_agent_tracking step
+
+## Example Entries
+
+### Sequential Execution (Default)
+
+```json
+{
+  "agent_id": "agent_01HXY123ABC",
+  "task_description": "Execute full plan 02-01 (autonomous)",
+  "phase": "02",
+  "plan": "01",
+  "segment": null,
+  "timestamp": "2026-01-15T14:22:10Z",
+  "status": "completed",
+  "completion_timestamp": "2026-01-15T14:45:33Z",
+  "execution_mode": "sequential",
+  "parallel_group": null,
+  "granularity": "plan",
+  "depends_on": null,
+  "files_modified": ["src/api/auth.ts", "src/types/user.ts"],
+  "checkpoints_skipped": null,
+  "task_results": null
+}
+```
+
+### Parallel Execution (Plan-Level)
+
+Independent plans in a phase running in parallel:
+
+```json
+{
+  "agent_id": "agent_01HXYZ123",
+  "task_description": "Execute plan 05-01 (parallel)",
+  "phase": "05",
+  "plan": "01",
+  "segment": null,
+  "timestamp": "2026-01-12T10:00:00Z",
+  "status": "completed",
+  "completion_timestamp": "2026-01-12T10:15:00Z",
+  "execution_mode": "parallel",
+  "parallel_group": "phase-05-batch-1736676000",
+  "granularity": "plan",
+  "depends_on": null,
+  "files_modified": ["src/auth/login.ts", "src/auth/types.ts"],
+  "checkpoints_skipped": 1,
+  "task_results": null
+}
+```
+
+### Queued with Dependency
+
+Agent waiting for another to complete:
+
+```json
+{
+  "agent_id": "agent_01HXYZ456",
+  "task_description": "Execute plan 05-03 (depends on 05-01)",
+  "phase": "05",
+  "plan": "03",
+  "segment": null,
+  "timestamp": "2026-01-12T10:15:00Z",
+  "status": "spawned",
+  "completion_timestamp": null,
+  "execution_mode": "parallel",
+  "parallel_group": "phase-05-batch-1736676000",
+  "granularity": "plan",
+  "depends_on": ["agent_01HXYZ123"],
+  "files_modified": null,
+  "checkpoints_skipped": null,
+  "task_results": null
+}
+```
+
+### Parallel Group Format
+
+- **Plan-level parallel:** `phase-{phase}-batch-{timestamp}`
+- **Task-level parallel:** `plan-{phase}-{plan}-tasks-batch-{timestamp}`
+
+Example: `phase-05-batch-1736676000` groups all agents executing Phase 5 plans in parallel.
+
+## Parallel Execution Resume
+
+When a session is interrupted during parallel execution:
+
+### Detection
+
+Check for entries with `status: "spawned"` and `parallel_group` set. These are agents that were running when session ended.
+
+```bash
+# Find interrupted parallel agents
+jq '.entries[] | select(.status == "spawned" and .parallel_group != null)' .planning/agent-history.json
+```
+
+### Resume Options
+
+1. **Resume batch:** Resume all interrupted agents in the parallel group
+2. **Resume single:** Resume a specific agent by ID
+3. **Start fresh:** Abandon interrupted batch, start new execution
+
+### Resume Command
+
+`/gsd:resume-task` accepts:
+- No argument: Resume most recent interrupted agent
+- Agent ID: Resume specific agent
+- `--batch`: Resume entire parallel group
+
+### Conflict Detection
+
+Before resuming, check for file modifications since spawn:
+
+```bash
+git diff --name-only ${SPAWN_COMMIT}..HEAD
+```
+
+If files modified by another agent conflict with files this agent modifies, warn user before proceeding. This prevents overwriting work done by other parallel agents that completed after the interruption.
+
+## Related Files
+
+- `.planning/current-agent-id.txt`: Single line with currently active agent ID (for quick resume lookup)
+- `.planning/STATE.md`: Project state including session continuity info
+
+---
+
+## Template Notes
+
+**When to create:** First subagent spawn during execute-plan workflow.
+
+**Location:** `.planning/agent-history.json`
+
+**Companion file:** `.planning/current-agent-id.txt` (single agent ID, overwritten on each spawn)
+
+**Purpose:** Enable resume capability for interrupted subagent executions via Task tool's resume parameter.