get-shit-done-cc 1.3.31 → 1.3.32

package/README.md

@@ -1,10 +1,26 @@
-# Get Shit Done
+<div align="center">
+
+# GET SHIT DONE
+
+**A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.**
 
-**A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.**
+[![npm version](https://img.shields.io/npm/v/get-shit-done-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-done-cc)
+[![npm downloads](https://img.shields.io/npm/dm/get-shit-done-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-done-cc)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/glittercowboy/get-shit-done?style=for-the-badge&logo=github&color=181717)](https://github.com/glittercowboy/get-shit-done)
+
+<br>
+
+```bash
+npx get-shit-done-cc
+```
+
+**Works on Mac, Windows, and Linux.**
+
+<br>
 
 ![GSD Install](assets/terminal.svg)
 
-<div align="center">
 <br>
 
 *"If you know clearly what you want, this WILL build it for you. No bs."*
@@ -17,67 +33,50 @@
 
 **Trusted by engineers at Amazon, Google, Shopify, and Webflow.**
 
-</div>
-
----
+[Why I Built This](#why-i-built-this) · [How It Works](#how-it-works) · [Commands](#commands) · [Why It Works](#why-it-works)
 
-Vibecoding has a bad reputation. You describe what you want, AI generates code, and you get inconsistent garbage that falls apart at scale.
-
-GSD fixes that. It's the context engineering layer that makes Claude Code reliable. Describe your idea, let the system extract everything it needs to know, and let Claude Code get to work.
+</div>
 
 ---
 
-## Who This Is For
-
-People who want to describe what they want and have it built correctly — without pretending they're running a 50-person engineering org.
-
-### Marketplace Installation
+## Why I Built This
 
-Install from the Claude Code marketplace:
+I'm a solo developer. I don't write code — Claude Code does.
 
-```bash
-/plugin marketplace add glittercowboy/get-shit-done
-/plugin install get-shit-done@get-shit-done
-```
+Other spec-driven development tools exist; BMAD, Speckit... But they all seem to make things way more complicated than they need to be (sprint ceremonies, story points, stakeholder syncs, retrospectives, Jira workflows) or lack real big picture understanding of what you're building. I'm not a 50-person software company. I don't want to play enterprise theater. I'm just a creative person trying to build great things that work.
 
-### Manual Installation
+So I built GSD. The complexity is in the system, not in your workflow. Behind the scenes: context engineering, XML prompt formatting, subagent orchestration, state management. What you see: a few commands that just work.
 
-Clone the repository and tell Claude Code where to find it:
+The system gives Claude everything it needs to do the work *and* verify it. I trust the workflow. It just does a good job.
 
-```bash
-git clone https://github.com/glittercowboy/get-shit-done.git
-claude --plugin-dir ./get-shit-done
-```
+That's what this is. No enterprise roleplay bullshit. Just an incredibly effective system for building cool stuff consistently using Claude Code.
 
-Useful for development or testing modifications.
+— **TÂCHES**
 
 ---
 
-## Why I Built This
-
-I'm a solo developer. I don't write code — Claude Code does.
-
-Other spec-driven development tools exist; BMAD, Speckit... But they all seem to make things way more complicated than they need to be (sprint ceremonies, story points, stakeholder syncs, retrospectives, Jira workflows) or lack real big picture understanding of what you're building. I'm not a 50-person software company. I don't want to play enterprise theater. I'm just a creative person trying to build great things that work.
+Vibecoding has a bad reputation. You describe what you want, AI generates code, and you get inconsistent garbage that falls apart at scale.
 
-So I built GSD. The complexity is in the system, not in your workflow. Behind the scenes: context engineering, XML prompt formatting, subagent orchestration, state management. What you see: a few commands that just work.
+GSD fixes that. It's the context engineering layer that makes Claude Code reliable. Describe your idea, let the system extract everything it needs to know, and let Claude Code get to work.
 
-The system gives Claude everything it needs to do the work _and_ verify it. I trust the workflow. It just does a good job.
+---
 
-That's what this is. No enterprise roleplay bullshit. Just an incredibly effective system for building cool stuff consistently using Claude Code.
+## Who This Is For
 
-— TÂCHES
+People who want to describe what they want and have it built correctly — without pretending they're running a 50-person engineering org.
 
 ---
 
-## Installation
+## Getting Started
 
 ```bash
 npx get-shit-done-cc
 ```
 
-That's it. Works on Mac, Windows, and Linux.
+That's it. Verify with `/gsd:help`.
 
-### Non-interactive Install (Docker, CI, Scripts)
+<details>
+<summary><strong>Non-interactive Install (Docker, CI, Scripts)</strong></summary>
 
 ```bash
 npx get-shit-done-cc --global   # Install to ~/.claude/
@@ -86,7 +85,22 @@ npx get-shit-done-cc --local    # Install to ./.claude/
 
 Use `--global` (`-g`) or `--local` (`-l`) to skip the interactive prompt.
 
-Verify: `/gsd:help`
+</details>
+
+<details>
+<summary><strong>Development Installation</strong></summary>
+
+Clone the repository and run the installer locally:
+
+```bash
+git clone https://github.com/glittercowboy/get-shit-done.git
+cd get-shit-done
+node bin/install.js --local
+```
+
+Installs to `./.claude/` for testing modifications before contributing.
+
+</details>
 
 ### Recommended: Skip Permissions Mode
 
@@ -96,12 +110,13 @@ GSD is designed for frictionless automation. Run Claude Code with:
 claude --dangerously-skip-permissions
 ```
 
-This is how GSD is intended to be used — stopping to approve `date` and `git commit` 50 times defeats the purpose.
-
-If you prefer not to use that flag, add this to your project's `.claude/settings.json` to auto-approve GSD's commands:
+> [!TIP]
+> This is how GSD is intended to be used — stopping to approve `date` and `git commit` 50 times defeats the purpose.
 
 <details>
-<summary>Show settings.json permissions</summary>
+<summary><strong>Alternative: Granular Permissions</strong></summary>
+
+If you prefer not to use that flag, add this to your project's `.claude/settings.json`:
 
 ```json
 {
@@ -146,13 +161,12 @@ The system asks questions. Keeps asking until it has everything — your goals,
 ### 2. Create roadmap
 
 ```
-/gsd:create-roadmap     # Create phases and state tracking
+/gsd:create-roadmap
 ```
 
-Roadmap creation produces:
-
-- **ROADMAP.md** - Phases from start to finish
-- **STATE.md** - Living memory that persists across sessions
+Produces:
+- **ROADMAP.md** — Phases from start to finish
+- **STATE.md** — Living memory that persists across sessions
 
 ### 3. Plan and execute phases
 
@@ -187,13 +201,15 @@ Already have code? Start here instead.
 
 Spawns parallel agents to analyze your code. Creates `.planning/codebase/` with 7 documents:
 
-- **STACK.md** — Languages, frameworks, dependencies
-- **ARCHITECTURE.md** — Patterns, layers, data flow
-- **STRUCTURE.md** — Directory layout, where things live
-- **CONVENTIONS.md** — Code style, naming patterns
-- **TESTING.md** — Test framework, patterns
-- **INTEGRATIONS.md** — External services, APIs
-- **CONCERNS.md** — Tech debt, known issues, fragile areas
+| Document | Purpose |
+|----------|---------|
+| `STACK.md` | Languages, frameworks, dependencies |
+| `ARCHITECTURE.md` | Patterns, layers, data flow |
+| `STRUCTURE.md` | Directory layout, where things live |
+| `CONVENTIONS.md` | Code style, naming patterns |
+| `TESTING.md` | Test framework, patterns |
+| `INTEGRATIONS.md` | External services, APIs |
+| `CONCERNS.md` | Tech debt, known issues, fragile areas |
 
 ### 2. Initialize project
 
@@ -215,18 +231,18 @@ The codebase docs load automatically during planning. Claude knows your patterns
 
 ### Context Engineering
 
-Claude Code is incredibly powerful _if_ you give it the context it needs. Most people don't.
+Claude Code is incredibly powerful *if* you give it the context it needs. Most people don't.
 
 GSD handles it for you:
 
-| File         | What it does                                           |
-| ------------ | ------------------------------------------------------ |
-| `PROJECT.md` | Project vision, always loaded                          |
-| `ROADMAP.md` | Where you're going, what's done                        |
-| `STATE.md`   | Decisions, blockers, position — memory across sessions |
-| `PLAN.md`    | Atomic task with XML structure, verification steps     |
-| `SUMMARY.md` | What happened, what changed, committed to history      |
-| `ISSUES.md`  | Deferred enhancements tracked across sessions          |
+| File | What it does |
+|------|--------------|
+| `PROJECT.md` | Project vision, always loaded |
+| `ROADMAP.md` | Where you're going, what's done |
+| `STATE.md` | Decisions, blockers, position — memory across sessions |
+| `PLAN.md` | Atomic task with XML structure, verification steps |
+| `SUMMARY.md` | What happened, what changed, committed to history |
+| `ISSUES.md` | Deferred enhancements tracked across sessions |
 
 Size limits based on where Claude's quality degrades. Stay under, get consistent excellence.
 
@@ -252,19 +268,21 @@ Precise instructions. No guessing. Verification built in.
 
 ### Subagent Execution
 
-As Claude fills its context window, quality degrades. You've seen it: "Due to context limits, I'll be more concise now." That "concision" is code for cutting corners.
+As Claude fills its context window, quality degrades. You've seen it: *"Due to context limits, I'll be more concise now."* That "concision" is code for cutting corners.
 
 GSD prevents this. Each plan is maximum 3 tasks. Each plan runs in a fresh subagent — 200k tokens purely for implementation, zero accumulated garbage.
 
-- Task 1: fresh context, full quality
-- Task 2: fresh context, full quality
-- Task 3: fresh context, full quality
+| Task | Context | Quality |
+|------|---------|---------|
+| Task 1 | Fresh | ✅ Full |
+| Task 2 | Fresh | ✅ Full |
+| Task 3 | Fresh | ✅ Full |
 
 No degradation. Walk away, come back to completed work.
 
 ### Atomic Git Commits
 
-Each task gets its own commit immediately after completion. Plans produce 2-4 commits total:
+Each task gets its own commit immediately after completion:
 
 ```bash
 abc123f docs(08-02): complete user registration plan
@@ -273,11 +291,8 @@ hij789k feat(08-02): implement password hashing
 lmn012o feat(08-02): create registration endpoint
 ```
 
-**Benefits:**
-- Git bisect finds exact failing task
-- Each task independently revertable
-- Clear history for Claude in future sessions
-- Better observability in AI-automated workflow
+> [!NOTE]
+> **Benefits:** Git bisect finds exact failing task. Each task independently revertable. Clear history for Claude in future sessions. Better observability in AI-automated workflow.
 
 Every commit is surgical, traceable, and meaningful.
 
@@ -294,31 +309,31 @@ You're never locked in. The system adapts.
 
 ## Commands
 
-| Command                           | What it does                                                  |
-| --------------------------------- | ------------------------------------------------------------- |
-| `/gsd:new-project`                | Extract your idea through questions, create PROJECT.md        |
-| `/gsd:create-roadmap`             | Create roadmap and state tracking                             |
-| `/gsd:map-codebase`               | Map existing codebase for brownfield projects                 |
-| `/gsd:plan-phase [N]`             | Generate task plans for phase                                 |
-| `/gsd:execute-plan`               | Run plan via subagent                                         |
-| `/gsd:progress`                   | Where am I? What's next?                                      |
-| `/gsd:verify-work [N]`*           | User acceptance test of phase or plan                         |
-| `/gsd:plan-fix [plan]`            | Plan fixes for UAT issues from verify-work                    |
-| `/gsd:complete-milestone`         | Ship it, prep next version                                    |
-| `/gsd:discuss-milestone`          | Gather context for next milestone                             |
-| `/gsd:new-milestone [name]`       | Create new milestone with phases                              |
-| `/gsd:add-phase`                  | Append phase to roadmap                                       |
-| `/gsd:insert-phase [N]`           | Insert urgent work                                            |
-| `/gsd:remove-phase [N]`           | Remove future phase, renumber subsequent                      |
-| `/gsd:discuss-phase [N]`          | Gather context before planning                                |
-| `/gsd:research-phase [N]`         | Deep ecosystem research for niche domains                     |
-| `/gsd:list-phase-assumptions [N]` | See what Claude thinks before you correct it                  |
-| `/gsd:pause-work`                 | Create handoff file when stopping mid-phase                   |
-| `/gsd:resume-work`                | Restore from last session                                     |
-| `/gsd:consider-issues`            | Review deferred issues, close resolved, identify urgent       |
-| `/gsd:help`                       | Show all commands and usage guide                             |
-
-*Contributed by reddit user OracleGreyBeard
+| Command | What it does |
+|---------|--------------|
+| `/gsd:new-project` | Extract your idea through questions, create PROJECT.md |
+| `/gsd:create-roadmap` | Create roadmap and state tracking |
+| `/gsd:map-codebase` | Map existing codebase for brownfield projects |
+| `/gsd:plan-phase [N]` | Generate task plans for phase |
+| `/gsd:execute-plan` | Run plan via subagent |
+| `/gsd:progress` | Where am I? What's next? |
+| `/gsd:verify-work [N]` | User acceptance test of phase or plan ¹ |
+| `/gsd:plan-fix [plan]` | Plan fixes for UAT issues from verify-work |
+| `/gsd:complete-milestone` | Ship it, prep next version |
+| `/gsd:discuss-milestone` | Gather context for next milestone |
+| `/gsd:new-milestone [name]` | Create new milestone with phases |
+| `/gsd:add-phase` | Append phase to roadmap |
+| `/gsd:insert-phase [N]` | Insert urgent work |
+| `/gsd:remove-phase [N]` | Remove future phase, renumber subsequent |
+| `/gsd:discuss-phase [N]` | Gather context before planning |
+| `/gsd:research-phase [N]` | Deep ecosystem research for niche domains |
+| `/gsd:list-phase-assumptions [N]` | See what Claude thinks before you correct it |
+| `/gsd:pause-work` | Create handoff file when stopping mid-phase |
+| `/gsd:resume-work` | Restore from last session |
+| `/gsd:consider-issues` | Review deferred issues, close resolved, identify urgent |
+| `/gsd:help` | Show all commands and usage guide |
+
+<sup>¹ Contributed by reddit user OracleGreyBeard</sup>
 
 ---
 
@@ -341,7 +356,13 @@ npx get-shit-done-cc@latest
 
 ## Star History
 
-[![Star History Chart](https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=date&legend=top-left)](https://www.star-history.com/#glittercowboy/get-shit-done&type=date&legend=top-left)
+<a href="https://star-history.com/#glittercowboy/get-shit-done&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=Date" />
+ </picture>
+</a>
 
 ---
 
@@ -351,4 +372,8 @@ MIT License. See [LICENSE](LICENSE) for details.
 
 ---
 
+<div align="center">
+
 **Claude Code is powerful. GSD makes it reliable.**
+
+</div>

package/commands/gsd/resume-task.md

@@ -0,0 +1,87 @@
+---
+name: gsd:resume-task
+description: Resume an interrupted subagent execution
+argument-hint: "[agent-id]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Resume an interrupted subagent execution using the Task tool's resume parameter.
+
+When a session ends mid-execution, subagents may be left in an incomplete state. This command allows users to continue that work without starting over.
+
+Uses the agent ID tracking infrastructure from execute-phase to identify and resume agents.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/resume-task.md
+</execution_context>
+
+<context>
+Agent ID: $ARGUMENTS (optional - defaults to most recent)
+
+**Load project state:**
+@.planning/STATE.md
+
+**Load agent tracking:**
+@.planning/current-agent-id.txt
+@.planning/agent-history.json
+</context>
+
+<process>
+1. Check .planning/ directory exists (error if not)
+2. Parse agent ID from arguments or current-agent-id.txt
+3. Validate agent exists in history and is resumable
+4. Check for file conflicts since spawn
+5. Follow resume-task.md workflow:
+   - Update agent status to "interrupted"
+   - Resume via Task tool resume parameter
+   - Update history on completion
+   - Clear current-agent-id.txt
+</process>
+
+<usage>
+**Resume most recent interrupted agent:**
+```
+/gsd:resume-task
+```
+
+**Resume specific agent by ID:**
+```
+/gsd:resume-task agent_01HXYZ123
+```
+
+**Find available agents to resume:**
+Check `.planning/agent-history.json` for entries with status "spawned" or "interrupted".
+</usage>
+
+<error_handling>
+**No agent to resume:**
+- current-agent-id.txt empty or missing
+- Solution: Run /gsd:progress to check project status
+
+**Agent already completed:**
+- Agent finished successfully, nothing to resume
+- Solution: Continue with next plan
+
+**Agent not found:**
+- Provided ID not in history
+- Solution: Check agent-history.json for valid IDs
+
+**Resume failed:**
+- Agent context expired or invalidated
+- Solution: Start fresh with /gsd:execute-plan
+</error_handling>
+
+<success_criteria>
+- [ ] Agent resumed via Task tool resume parameter
+- [ ] Agent-history.json updated with completion
+- [ ] current-agent-id.txt cleared
+- [ ] User informed of result
+</success_criteria>

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

@@ -0,0 +1,161 @@
+# Agent History Template
+
+Template for `.planning/agent-history.json` - tracks subagent spawns during plan execution for resume capability.
+
+---
+
+## File Template
+
+```json
+{
+  "version": "1.0",
+  "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
+}
+```
+
+### 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 | Segment number (1-based) for segmented plans, null for Pattern A |
+| timestamp | string | ISO 8601 timestamp when agent was spawned |
+| status | string | Current status: spawned, completed, interrupted, resumed |
+| completion_timestamp | string/null | ISO 8601 timestamp when completed, null if pending |
+
+### Status Lifecycle
+
+```
+spawned ──────────────────────────> completed
+    │                                   ^
+    │                                   │
+    └──> interrupted ──> resumed ───────┘
+```
+
+- **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
+
+## Usage
+
+### When to Create File
+
+Create `.planning/agent-history.json` from this template when:
+- First subagent spawn in execute-phase 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 File
+
+```json
+{
+  "version": "1.0",
+  "max_entries": 50,
+  "entries": [
+    {
+      "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"
+    },
+    {
+      "agent_id": "agent_01HXY456DEF",
+      "task_description": "Execute tasks 1-3 from plan 02-02",
+      "phase": "02",
+      "plan": "02",
+      "segment": 1,
+      "timestamp": "2026-01-15T15:00:00Z",
+      "status": "spawned",
+      "completion_timestamp": null
+    }
+  ]
+}
+```
+
+## 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-phase 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.

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

@@ -204,15 +204,48 @@ No segmentation benefit - execute entirely in main
 **For fully autonomous plans:**
 
 ```
-Use Task tool with subagent_type="general-purpose":
+1. Run init_agent_tracking step first (see step below)
 
-Prompt: "Execute plan at .planning/phases/{phase}-{plan}-PLAN.md
+2. Use Task tool with subagent_type="general-purpose":
 
-This is an autonomous plan (no checkpoints). Execute all tasks, create SUMMARY.md in phase directory, commit with message following plan's commit guidance.
+   Prompt: "Execute plan at .planning/phases/{phase}-{plan}-PLAN.md
 
-Follow all deviation rules and authentication gate protocols from the plan.
+   This is an autonomous plan (no checkpoints). Execute all tasks, create SUMMARY.md in phase directory, commit with message following plan's commit guidance.
 
-When complete, report: plan name, tasks completed, SUMMARY path, commit hash."
+   Follow all deviation rules and authentication gate protocols from the plan.
+
+   When complete, report: plan name, tasks completed, SUMMARY path, commit hash."
+
+3. After Task tool returns with agent_id:
+
+   a. Write agent_id to current-agent-id.txt:
+      echo "[agent_id]" > .planning/current-agent-id.txt
+
+   b. Append spawn entry to agent-history.json:
+      {
+        "agent_id": "[agent_id from Task response]",
+        "task_description": "Execute full plan {phase}-{plan} (autonomous)",
+        "phase": "{phase}",
+        "plan": "{plan}",
+        "segment": null,
+        "timestamp": "[ISO timestamp]",
+        "status": "spawned",
+        "completion_timestamp": null
+      }
+
+4. Wait for subagent to complete
+
+5. After subagent completes successfully:
+
+   a. Update agent-history.json entry:
+      - Find entry with matching agent_id
+      - Set status: "completed"
+      - Set completion_timestamp: "[ISO timestamp]"
+
+   b. Clear current-agent-id.txt:
+      rm .planning/current-agent-id.txt
+
+6. Report completion to user
 ```
 
 **For segmented plans (has verify-only checkpoints):**
@@ -247,6 +280,54 @@ Quality maintained through small scope (2-3 tasks per plan)
 See step name="segment_execution" for detailed segment execution loop.
 </step>
 
+<step name="init_agent_tracking">
+**Initialize agent tracking for subagent resume capability.**
+
+Before spawning any subagents, set up tracking infrastructure:
+
+**1. Create/verify tracking files:**
+
+```bash
+# Create agent history file if doesn't exist
+if [ ! -f .planning/agent-history.json ]; then
+  echo '{"version":"1.0","max_entries":50,"entries":[]}' > .planning/agent-history.json
+fi
+
+# Clear any stale current-agent-id (from interrupted sessions)
+# Will be populated when subagent spawns
+rm -f .planning/current-agent-id.txt
+```
+
+**2. Check for interrupted agents (resume detection):**
+
+```bash
+# Check if current-agent-id.txt exists from previous interrupted session
+if [ -f .planning/current-agent-id.txt ]; then
+  INTERRUPTED_ID=$(cat .planning/current-agent-id.txt)
+  echo "Found interrupted agent: $INTERRUPTED_ID"
+fi
+```
+
+**If interrupted agent found:**
+- The agent ID file exists from a previous session that didn't complete
+- This agent can potentially be resumed using Task tool's `resume` parameter
+- Present to user: "Previous session was interrupted. Resume agent [ID] or start fresh?"
+- If resume: Use Task tool with `resume` parameter set to the interrupted ID
+- If fresh: Clear the file and proceed normally
+
+**3. Prune old entries (housekeeping):**
+
+If agent-history.json has more than `max_entries`:
+- Remove oldest entries with status "completed"
+- Never remove entries with status "spawned" (may need resume)
+- Keep file under size limit for fast reads
+
+**When to run this step:**
+- Pattern A (fully autonomous): Before spawning the single subagent
+- Pattern B (segmented): Before the segment execution loop
+- Pattern C (main context): Skip - no subagents spawned
+</step>
+
 <step name="segment_execution">
 **Detailed segment execution loop for segmented plans.**
 
@@ -299,8 +380,36 @@ For Pattern A (fully autonomous) and Pattern C (decision-dependent), skip this s
       - Deviations encountered
       - Any issues or blockers"
 
+      **After Task tool returns with agent_id:**
+
+      1. Write agent_id to current-agent-id.txt:
+         echo "[agent_id]" > .planning/current-agent-id.txt
+
+      2. Append spawn entry to agent-history.json:
+         {
+           "agent_id": "[agent_id from Task response]",
+           "task_description": "Execute tasks [X-Y] from plan {phase}-{plan}",
+           "phase": "{phase}",
+           "plan": "{plan}",
+           "segment": [segment_number],
+           "timestamp": "[ISO timestamp]",
+           "status": "spawned",
+           "completion_timestamp": null
+         }
+
       Wait for subagent to complete
       Capture results (files changed, deviations, etc.)
+
+      **After subagent completes successfully:**
+
+      1. Update agent-history.json entry:
+         - Find entry with matching agent_id
+         - Set status: "completed"
+         - Set completion_timestamp: "[ISO timestamp]"
+
+      2. Clear current-agent-id.txt:
+         rm .planning/current-agent-id.txt
+
       ```
 
    C. If routing = Main context:

package/get-shit-done/workflows/resume-project.md

@@ -69,6 +69,12 @@ for plan in .planning/phases/*/*-PLAN.md; do
   summary="${plan/PLAN/SUMMARY}"
   [ ! -f "$summary" ] && echo "Incomplete: $plan"
 done 2>/dev/null
+
+# Check for interrupted agents
+if [ -f .planning/current-agent-id.txt ] && [ -s .planning/current-agent-id.txt ]; then
+  AGENT_ID=$(cat .planning/current-agent-id.txt | tr -d '\n')
+  echo "Interrupted agent: $AGENT_ID"
+fi
 ```
 
 **If .continue-here file exists:**
@@ -81,6 +87,12 @@ done 2>/dev/null
 
 - Execution was started but not completed
 - Flag: "Found incomplete plan execution"
+
+**If interrupted agent found:**
+
+- Subagent was spawned but session ended before completion
+- Read agent-history.json for task details
+- Flag: "Found interrupted agent"
   </step>
 
 <step name="present_status">
@@ -103,6 +115,14 @@ Present complete project status to user:
 ⚠️  Incomplete work detected:
     - [.continue-here file or incomplete plan]
 
+[If interrupted agent found:]
+⚠️  Interrupted agent detected:
+    Agent ID: [id]
+    Task: [task description from agent-history.json]
+    Interrupted: [timestamp]
+
+    Resume with: /gsd:resume-task
+
 [If deferred issues exist:]
 📋 [N] deferred issues awaiting attention
 
@@ -120,6 +140,10 @@ Present complete project status to user:
 <step name="determine_next_action">
 Based on project state, determine the most logical next action:
 
+**If interrupted agent exists:**
+→ Primary: Resume interrupted agent (/gsd:resume-task)
+→ Option: Start fresh (abandon agent work)
+
 **If .continue-here file exists:**
 → Primary: Resume from checkpoint
 → Option: Start fresh on current plan
@@ -154,6 +178,8 @@ Present contextual options based on project state:
 What would you like to do?
 
 [Primary action based on state - e.g.:]
+1. Resume interrupted agent (/gsd:resume-task) [if interrupted agent found]
+   OR
 1. Resume from checkpoint (/gsd:execute-plan .planning/phases/XX-name/.continue-here-02-01.md)
    OR
 1. Execute next plan (/gsd:execute-plan .planning/phases/XX-name/02-02-PLAN.md)

package/get-shit-done/workflows/resume-task.md

@@ -0,0 +1,259 @@
+<trigger>
+Use this workflow when:
+- User runs /gsd:resume-task
+- Need to continue interrupted subagent execution
+- Resuming work after session ended mid-plan
+</trigger>
+
+<purpose>
+Resume an interrupted subagent execution using the Task tool's resume parameter.
+
+Enables seamless continuation of autonomous work that was interrupted by session timeout, user exit, or crash.
+</purpose>
+
+<process>
+
+<step name="parse_arguments">
+Parse the optional agent_id argument:
+
+```bash
+# Check if argument provided
+if [ -n "$ARGUMENTS" ]; then
+  AGENT_ID="$ARGUMENTS"
+  echo "Using provided agent ID: $AGENT_ID"
+else
+  # Read from current-agent-id.txt
+  if [ -f .planning/current-agent-id.txt ] && [ -s .planning/current-agent-id.txt ]; then
+    AGENT_ID=$(cat .planning/current-agent-id.txt | tr -d '\n')
+    echo "Using current agent ID: $AGENT_ID"
+  else
+    echo "ERROR: No agent to resume"
+    exit 1
+  fi
+fi
+```
+
+**If no agent ID found:**
+Present error:
+```
+No active agent to resume.
+
+There's no interrupted agent recorded. This could mean:
+- No subagent was spawned in the current plan
+- The last agent completed successfully
+- .planning/current-agent-id.txt was cleared
+
+Use /gsd:progress to check project status.
+```
+
+**If agent ID found:** Continue to validate_agent step.
+</step>
+
+<step name="validate_agent">
+Validate the agent exists and is resumable:
+
+```bash
+# Check if agent-history.json exists
+if [ ! -f .planning/agent-history.json ]; then
+  echo "ERROR: No agent history found"
+  exit 1
+fi
+
+# Read history and find the agent
+cat .planning/agent-history.json
+```
+
+**Parse agent-history.json and find entry matching AGENT_ID:**
+
+Check the entry status:
+- **If status = "completed":** Error - agent already completed
+- **If status = "spawned" or "interrupted":** Valid for resume
+- **If not found:** Error - agent ID not in history
+
+**If agent already completed:**
+```
+Agent already completed.
+
+Agent ID: [id]
+Completed: [completion_timestamp]
+Task: [task_description]
+
+This agent finished successfully. No resume needed.
+```
+
+**If agent not found:**
+```
+Agent ID not found in history.
+
+ID: [provided_id]
+
+Available agents:
+- [list most recent 5 agents with status]
+
+Did you mean one of these?
+```
+
+**If valid for resume:** Continue to check_conflicts step.
+</step>
+
+<step name="check_conflicts">
+Check for file modifications since the agent was spawned.
+
+**Read the agent entry to get context:**
+- phase, plan, segment information
+- timestamp of spawn
+
+**Check for git changes since spawn:**
+
+```bash
+# Get files modified since agent spawn
+# Note: This is a best-effort check - relies on git status
+git status --short
+```
+
+**If modifications detected:**
+
+Use AskUserQuestion to warn user:
+
+```
+Files modified since agent was interrupted:
+- [list files]
+
+These changes may conflict with the agent's work.
+
+Options:
+1. Continue anyway - Agent will resume with current files
+2. Abort - Review changes first
+
+Select option:
+```
+
+Wait for user response.
+
+**If user selects "Abort":**
+```
+Resume aborted. Review your changes and run /gsd:resume-task when ready.
+```
+End workflow.
+
+**If user selects "Continue anyway" or no conflicts found:**
+Continue to update_status step.
+</step>
+
+<step name="update_status">
+Update the agent status to "interrupted" if it was "spawned" (marking the interruption point):
+
+```bash
+# Read current history
+HISTORY=$(cat .planning/agent-history.json)
+```
+
+Update the entry in agent-history.json:
+- If status was "spawned", change to "interrupted"
+- Add note about resume attempt
+
+This provides audit trail of the interruption before resume.
+</step>
+
+<step name="resume_agent">
+Resume the agent using Task tool's resume parameter:
+
+```
+Resuming agent: [agent_id]
+Task: [task_description from history]
+Phase: [phase]-[plan]
+
+The agent will continue from where it left off...
+```
+
+**Use Task tool with resume parameter:**
+
+```
+Task(
+  description: "Resume interrupted agent",
+  prompt: "Continue your previous work. You were executing [task_description].",
+  subagent_type: "general-purpose",
+  resume: "[AGENT_ID]"
+)
+```
+
+Wait for agent completion.
+
+**On agent completion:**
+- Capture any results returned
+- Continue to completion_update step
+</step>
+
+<step name="completion_update">
+Update tracking files on successful completion:
+
+**1. Update agent-history.json:**
+
+Add new entry marking the resume completion:
+```json
+{
+  "agent_id": "[AGENT_ID]",
+  "task_description": "[original task] (resumed)",
+  "phase": "[phase]",
+  "plan": "[plan]",
+  "segment": [segment or null],
+  "timestamp": "[now]",
+  "status": "completed",
+  "completion_timestamp": "[now]"
+}
+```
+
+**2. Clear current-agent-id.txt:**
+
+```bash
+# Clear the current agent file
+> .planning/current-agent-id.txt
+```
+
+**3. Present completion message:**
+
+```
+Agent resumed and completed successfully.
+
+Agent ID: [id]
+Task: [task_description]
+Original spawn: [original_timestamp]
+Completed: [now]
+
+The agent's work has been incorporated. Check git status for changes.
+```
+</step>
+
+<step name="handle_errors">
+Error handling for resume failures:
+
+**If Task tool returns error on resume:**
+```
+Failed to resume agent.
+
+Agent ID: [id]
+Error: [error message]
+
+Possible causes:
+- Agent context may have expired
+- Agent may have been invalidated
+
+Options:
+1. Start fresh - Execute plan from beginning
+2. Check status - Review what was completed
+
+Run /gsd:execute-plan to start fresh if needed.
+```
+
+Do NOT clear current-agent-id.txt on error - allow retry.
+</step>
+
+</process>
+
+<success_criteria>
+Resume is complete when:
+- [ ] Agent resumed successfully via Task tool resume parameter
+- [ ] Agent-history.json updated with completion status
+- [ ] Current-agent-id.txt cleared
+- [ ] User informed of completion
+</success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-done-cc",
-  "version": "1.3.31",
+  "version": "1.3.32",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "get-shit-done-cc": "bin/install.js"