msd-core/get-shit-done/templates/agent-history.md

Agent History Template

Template for .planning/agent-history.json - tracks subagent spawns during plan execution for resume capability.

---

File Template

{
  "version": "1.2",
  "max_entries": 50,
  "entries": []
}

Entry Schema

Each entry tracks a subagent spawn or status change:

{
  "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:

{
  "status": "completed",
  "completion_timestamp": "2026-01-15T14:45:33Z"
}

On resume detection (interrupted agent found):

{
  "status": "interrupted"
}

Then add new entry with resumed status:

{
  "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)

{
  "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:

{
  "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:

{
  "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.

# 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:

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.