Plan Generation and Ledger
Relevant source files
The following files were used as context for generating this wiki page:
The Plan Generation and Ledger system serves as the foundational orchestrator for task management within the OpenCode Swarm. It defines how requirements are decomposed into actionable phases and tasks, maintained through a persistent JSON schema, and synchronized with human-readable documentation. The system ensures project continuity by tracking the state of the swarm through a robust ledger and checkpoint mechanism, allowing for reliable recovery and multi-agent coordination.
Sources: src/plan/manager.ts, src/agents/architect.ts:60-75, .claude/skills/plan/SKILL.md
Core Architecture and Components
The planning system is built around three primary artifacts located in the .swarm/ directory: plan.json, plan.md, and plan-ledger.jsonl. The PlanManager is the central service responsible for coordinating these files, ensuring that the machine-readable state (plan.json) and the human-readable view (plan.md) remain in sync through automated workers.
Sources: src/plan/manager.ts, src/agents/architect.ts:740-755
The Plan Management Lifecycle
The following diagram illustrates the flow from initial requirement analysis to persistent state management.
The lifecycle begins with the Clarification Funnel to resolve uncertainties before the Architect invokes save_plan. This triggers a chain reaction where plan.json is updated, and a background worker regenerates the markdown representation.
Sources: src/plan/manager.ts, .claude/skills/plan/SKILL.md
Key Components
| Component | Responsibility | Relevant Files |
|---|---|---|
| PlanManager | High-level API for loading, saving, and updating task statuses. | src/plan/manager.ts |
| PlanSyncWorker | Monitors plan.json for changes and automatically regenerates plan.md. | src/agents/architect.ts:740-745 |
| Ledger | Provides an append-only audit trail of every plan mutation and phase transition. | src/plan/ledger.ts |
| Checkpoint | Creates project-level snapshots to allow for rollback during risky operations. | src/plan/checkpoint.ts |
Sources: src/plan/manager.ts, src/plan/ledger.ts, src/plan/checkpoint.ts
Plan Generation and Specification
Plan generation is governed by the MODE: PLAN protocol. The system enforces strict granularity rules to ensure tasks are atomic and verifiable. The Architect uses the save_plan tool to commit structural changes, which include descriptive titles, swarm identifiers, and a structured array of phases and tasks.
Sources: src/agents/architect.ts:655-680, .claude/skills/plan/SKILL.md
Task Granularity and Traceability
The system implements a traceability check that ensures every functional requirement (FR-###) defined in the specification corresponds to at least one task in the plan. Tasks are categorized by size (SMALL, MEDIUM, LARGE) to assist in context management.
Sources: src/agents/architect.ts:125-135, .claude/skills/plan/SKILL.md
This class diagram represents the structure of the RuntimePlan schema used for persistent storage in plan.json.
Sources: src/plan/manager.ts, tests/unit/plan/manager.test.ts:14-40
The Plan Ledger and State Protection
The Ledger is an append-only jsonl file (.swarm/plan-ledger.jsonl) that records the evolution of the plan. It prevents "silent mutations" where the plan might be altered without proper review.
Sources: src/plan/ledger.ts:1-20
Ledger Security and Verification
The system uses hash-based verification to ensure integrity. The plan.md file contains a hidden PLAN_HASH comment. If the content of plan.json changes, the hash in plan.md will no longer match, triggering a synchronization or an advisory warning.
Sources: src/hooks/system-enhancer.ts:35-60, tests/unit/plan/manager.test.ts:175-200
The sequence above details how the system detects spec-drift and notifies the Architect when the persistent plan deviates from the active specification or approved baseline.
Sources: src/hooks/system-enhancer.ts:38-70, src/plan/manager.ts
Checkpoints and Recovery
The Checkpoint system provides a safety net for multi-file refactors. Before performing operations involving more than three files, the Architect is required to create a snapshot.
Sources: src/agents/architect.ts:173-177, src/plan/checkpoint.ts
- Save Checkpoint: Captured via
checkpoint save. It stores the current state of the workspace and the plan. - Restore Checkpoint: Invoked via
checkpoint restoreon critical failure or implementation loops. - Rollback: A more granular operation that reverts the last completed task or phase transition.
Sources: src/agents/architect.ts:173-177, src/plan/checkpoint.ts
Summary of Plan Ledger Operations
| Function/Tool | Action | Target Artifact |
|---|---|---|
save_plan() | Creates or restructures the entire plan. | plan.json |
update_task_status() | Marks a specific task as completed or in-progress. | plan.json |
phase_complete() | Transitions the system to the next project phase. | plan.json, plan-ledger.jsonl |
loadPlan() | Retrieves the current state and checks for Spec Drift. | In-memory RuntimePlan |
write_retro() | Records phase-end metrics and lessons learned. | context.md, evidence/ |
Sources: src/plan/manager.ts, src/agents/architect.ts:750-765, tests/unit/plan/manager.test.ts:500-520
Conclusion
The Plan Generation and Ledger system ensures that the OpenCode Swarm operates within a controlled, observable, and recoverable framework. By separating machine-readable state from human-readable documentation and enforcing an append-only ledger, the project maintains high integrity across multiple agent delegations. The integration of checkpoints and automated synchronization workers allows the Architect to manage complex codebase transitions without losing track of the project's requirements or current progress.
Sources: src/plan/manager.ts, src/plan/ledger.ts, src/agents/architect.ts