Project State and The .swarm Directory
Relevant source files
The following files were used as context for generating this wiki page:
The .swarm directory serves as the centralized repository for all runtime project state within the opencode-swarm environment. It is the authoritative source for the project plan, agent activities, and accumulated knowledge. This directory ensures that state is persistent across different sessions and portable between different execution environments, such as local development or CI pipelines. Sources: AGENTS.md:79-81, src/agents/architect.ts:168-171
The system follows a strict "containment" principle where all runtime state must live exclusively within the project root's .swarm/ directory. This structure prevents Git pollution and ensures that tools have a consistent path for reading and writing critical project data. Sources: AGENTS.md:79-81, src/agents/architect.ts:251-255
Primary State Artifacts
The project state is represented by several key files within the .swarm directory. These files govern the lifecycle of a task from planning to implementation and verification.
Plan and Ledger
The project uses a ledger-based system for plan durability. The plan-ledger.jsonl is the authoritative source of truth for the project plan's history and state changes. Other files like plan.json and plan.md are derived projections of this ledger. Sources: AGENTS.md:104-106, src/agents/architect.ts:168-171
- .swarm/plan.md: A human-readable Markdown representation of the current project phases and tasks. Sources: src/agents/architect.ts:503-514
- .swarm/plan.json: A machine-readable JSON structure containing phase and task metadata. Sources: src/agents/architect.ts:256-261
- .swarm/plan-ledger.jsonl: The append-only log of all plan mutations. Sources: AGENTS.md:104-105
Context and Knowledge
The system maintains a running context of technical decisions, domain guidance, and discovered patterns to assist agents in subsequent tasks.
- .swarm/context.md: Stores high-level project metadata, technical decisions, and SME (Subject Matter Expert) cache entries. Sources: src/agents/architect.ts:516-532
- .swarm/doc-manifest.json: An index of project documentation generated by the Explorer agent. Sources: src/agents/explorer.ts:143-150
- .swarm/knowledge/: A directory containing structured knowledge entries, such as documentation constraints. Sources: src/agents/explorer.ts:162-164
This diagram illustrates the hierarchical organization of state artifacts within the .swarm directory. Sources: AGENTS.md:79-113, src/agents/architect.ts:503-532
State Management and Lifecycle
State management is strictly controlled through specific tool invocations rather than direct file edits. The Architect agent orchestrates these changes to ensure consistency. Sources: src/agents/architect.ts:251-266
Update Protocols
- save_plan: Used to create or restructure the plan. It updates
plan.json, which triggers an auto-regeneration ofplan.md. Sources: src/agents/architect.ts:256-258 - update_task_status: Specifically used for marking individual tasks as "in_progress" or "completed". Sources: src/agents/architect.ts:259-260
- phase_complete: Handles the transition between project phases and requires retrospective evidence. Sources: src/agents/architect.ts:260-261
Directory Containment Rules
The system enforces strict containment rules to maintain project integrity:
- Root Only: The
.swarmdirectory must be at the project root. Creating it in subdirectories is prohibited. Sources: AGENTS.md:85-87 - Tool Injection: Tools receive the project directory via injection (
ctx.directory) to ensure they write to the correct.swarmpath. Sources: AGENTS.md:79-81 - Git Hygiene: The directory is excluded from Git via
.git/info/excludeto prevent state from polluting the main repository history. Sources: AGENTS.md:88-89
The Research Cache and SME State
The system caches Subject Matter Expert (SME) findings in .swarm/context.md under the ## Research Sources section. This prevents redundant network calls and expensive LLM lookups for previously resolved technical questions. Sources: src/agents/sme.ts:153-155
Research Caching Workflow
- Lookup: Before starting fresh research, the SME agent checks
context.mdfor the topic. Sources: src/agents/sme.ts:157-160 - Hit: If the topic exists, the cached summary is reused. Sources: src/agents/sme.ts:161-161
- Miss: If not found, the SME performs research and appends a
CACHE-UPDATEline to its response. Sources: src/agents/sme.ts:162-164 - Persistence: The Architect agent is responsible for saving these updates to the
.swarm/context.mdfile. Sources: src/agents/sme.ts:168-168
| Component | Responsibility | Source File |
|---|---|---|
| Architect | Persists cache updates to context.md | src/agents/sme.ts |
| SME | Performs lookup and identifies updates | src/agents/sme.ts |
| .swarm/context.md | Acts as the durable storage for research | src/agents/sme.ts |
Sources: src/agents/sme.ts:153-170
Task Scoping and Write Authority
Before an agent can modify files, the Architect must define a specific "scope" for that task. This state is persisted in .swarm/scopes/. Sources: src/tools/declare-scope.ts:211-215
Scope Declaration Workflow
The declare_scope tool sets the boundary for what the Coder agent is permitted to modify. This is a critical security and integrity feature. Sources: src/tools/declare-scope.ts:10-14
This sequence shows how task-level write authority is persisted to the .swarm directory and consumed during execution. Sources: src/tools/declare-scope.ts:211-215, src/agents/architect.ts:102-111
Conclusion
The .swarm directory is the foundational state management system for the opencode-swarm project. By centralizing the plan ledger, research cache, and task scopes, it enables a coordinated multi-agent workflow that is robust, persistent, and portable. Adherence to directory containment and the authoritative ledger ensures project integrity across complex engineering phases. Sources: AGENTS.md:79-113, src/agents/architect.ts:251-270