Why a Ledger File Is Essential in the Subagent-Driven Development Workflow

A ledger file provides durable state across sessions, prevents redundant task execution through idempotency checks, and maintains an immutable audit trail of architectural decisions in the subagent-driven development workflow.

The subagent-driven development workflow in the openai/plugins repository orchestrates multiple AI subagents to execute complex, multi-step plans. Because LLM conversation memory does not survive context compaction or session restarts, the workflow relies on a ledger file to persist progress, rulings, and recovery metadata between runs.

The Problem with Volatile Conversation Memory

LLM conversation state is ephemeral. According to the workflow specification in SKILL.md, conversation memory does not survive compaction, which makes it impossible to track long-running tasks solely through in-context todo lists or chat history lines 31-35. When the controller’s context window is compressed or a session terminates unexpectedly, any task status stored only in conversation is lost. The ledger file solves this by acting as a recovery map that survives controller restarts and provides a ground-truth record of what has been accomplished.

Core Functions of the Ledger File

Persistent State and Workspace Isolation

Each plan receives an isolated workspace under .superpowers/sdd/<plan-basename>/, where the ledger resides alongside briefs, reports, and review packages lines 36-40. This isolation prevents cross-contamination between parallel plans while ensuring the ledger persists locally on the filesystem. The ledger also functions as a recovery map by recording the specific Git commits that generated each artifact. If the workspace directory is lost, these commit references allow complete reconstruction of the work history from Git lines 48-52.

Idempotent Task Execution

Before dispatching a subagent, the controller checks the ledger to determine if a task is already marked complete. By verifying the first line of the ledger file, the system prevents expensive re-dispatching of finished tasks and ensures that interruptions—whether from context limits or manual stops—do not cause duplicate work lines 41-44. This idempotency guarantee is critical for long-running plans that may span multiple controller sessions.

Decision Audit Trail

Every architectural ruling, conflict resolution, and "parked" finding is appended to the ledger. Unlike volatile conversation logs, these entries survive compaction and provide human reviewers with a chronological record of why specific technical decisions were made lines 22-25. This audit trail transforms the ledger from a simple progress tracker into a durable log of the plan's intellectual history.

Implementation and File Structure

The ledger is implemented as a plain-text file named progress.md within the plan's isolated directory. The helper script scripts/sdd-workspace automates the creation of this file when initializing a new plan workspace, ensuring the ledger is initialized with the correct header format referencing the source plan file. The ledger lives at .superpowers/sdd/<plan-basename>/progress.md, co-located with other plan artifacts to maintain a single source of truth for each initiative.

Practical Usage Examples

Initialize a new workspace and ledger for a feature plan:

plugins/superpowers/skills/subagent-driven-development/scripts/sdd-workspace docs/feature-plan.md

# Creates: .superpowers/sdd/feature-plan/progress.md

# With header: # SDD ledger — plan: docs/feature-plan.md

Check ledger status before dispatching a subagent to avoid duplicate work:

head -n 1 .superpowers/sdd/feature-plan/progress.md

# Verify the plan identifier matches before resuming

Mark a task complete with specific Git commit references for recovery:

echo "Task 3: complete (commits a1b2c3..d4e5f6, review clean)" >> \
    .superpowers/sdd/feature-plan/progress.md

Record an architectural ruling for audit purposes:

echo "Ruling: use async API — cheaper, latency < 100ms (cost if wrong: wasted compute)" >> \
    .superpowers/sdd/feature-plan/progress.md

Summary

• The ledger file provides durable state that outlives volatile conversation memory and context compaction.
• It enables idempotent execution by tracking completed tasks and preventing redundant subagent dispatches.
• It serves as a recovery map by recording Git commits, allowing workspace reconstruction from history if directories are lost.
• It maintains an audit trail of architectural rulings and decisions for human review and compliance.
• The scripts/sdd-workspace utility automates ledger creation in isolated .superpowers/sdd/ directories to enforce workspace hygiene.

Frequently Asked Questions

What happens if the ledger file is deleted?

If the ledger is removed, the controller loses its memory of completed tasks and rulings. While the Git history retains code changes (assuming commits were made), the workflow will re-dispatch subagents for tasks it can no longer verify as complete, potentially causing duplicate work until the ledger is reconstructed or the plan is restarted.

How does the ledger differ from a todo list?

While todo lists track intended work, the ledger records actual execution state—specifically which tasks are complete, the exact Git commits produced, and formal rulings. According to the source documentation, progress must be tracked in the ledger "not only in todos" because todos lack the durability and commit references required for recovery across sessions.

Can multiple subagents write to the same ledger simultaneously?

The workflow design implies sequential writes to the ledger file within a single plan's workspace. While the file itself is plain text, concurrent modifications without coordination could corrupt the state tracking. The architecture isolates each plan in its own .superpowers/sdd/ directory to minimize collision risks and ensure atomicity of updates.

Where is the ledger file physically located?

The ledger is stored at .superpowers/sdd/<plan-basename>/progress.md relative to the repository root. The sdd-workspace script creates this path automatically when initializing a plan, ensuring the ledger is co-located with the plan's briefs, reports, and review packages for easy discovery and backup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}