Open Manifold

Multi-agent development system for opencode with persistent knowledge.

A Lead Dev agent walks through a task plan, a deterministic plugin state machine orchestrates a Senior/Junior/Debug loop, and all decisions are logged to a persistent Manifold/ folder that compounds knowledge across the project.

Core principle: Deterministic orchestration + scoped LLM execution + persistent knowledge = agents that learn and don't repeat mistakes.

v2 Update: The orchestration state machine now lives in plugin TypeScript code, not agent prompts. Agents are pure workers — the plugin decides when to call whom. This eliminates the "agent ignores protocol" problem and makes the system reliable.

Requirements

Open Manifold requires:

1. opencode-codebase-index plugin — Provides semantic code search for the Clerk's research phase. The Clerk uses it to find relevant code patterns and build focused prompts for worker agents.

2. Obsidian (optional but recommended) — The Manifold/ folder is structured as an Obsidian vault for browsing logs, tasks, and knowledge graph.

Installation:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    "opencode-codebase-index",
    "opencode-manifold"
  ]
}

Two Ways to Install

Option A — npm package (Recommended)

1. Add "opencode-manifold" to your opencode.json plugins array:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["opencode-manifold"]
}

2. Run opencode. The plugin auto-installs and generates the global template source.
3. Run /manifold-init in the TUI to set up the project.

Option B — Local plugin files

1. Clone this repository
2. Copy src/ into your project's .opencode/plugins/ directory:

   cp -r src ~/.config/opencode/plugins/opencode-manifold/
   # OR copy into your project:
   mkdir -p .opencode/plugins
   cp -r src .opencode/plugins/opencode-manifold

3. Add to your opencode.json:

   {
     "plugin": ["/path/to/.opencode/plugins/opencode-manifold"]
   }

4. Run opencode. The plugin generates the global template source.
5. Run /manifold-init in the TUI to set up the project.

Quick Start

1. Install using one of the methods above
2. Run /manifold-init in the opencode TUI to set up agents, skills, and the Manifold directory
3. Create a plan — any format (markdown, TODO list, email, meeting notes)
4. Run /manifold-plan <path> — the Planner agent interviews you to clarify the plan
5. Answer the questions and run /manifold-plan-answers
6. Run /manifold-decompose <plan> — Todo agent breaks it into tasks
7. Run /manifold-execute <tasks> — the plugin orchestrates Clerk → Senior → Junior loop
8. Run /manifold-continue for each subsequent task

The plugin code (not agents) handles all orchestration:

• Clerk researches, returns findings
• Senior Dev implements
• Junior Dev reviews (strict COMPLETE/QUESTIONS)
• Loop repeats up to 3×, then Debug intervenes
• All decisions logged to Manifold/

Architecture: Plugin-Driven Orchestration

In Manifold v2, the plugin TypeScript code is the conductor. Agents are pure musicians who play what they're told. This eliminates prompt-drift and protocol-ignoring.

| Component | Role | |-----------|------| | Plugin Code | Orchestrator — decides when to call whom, manages state, enforces loops | | Planner | Interview agent — asks clarifying questions, refines plan | | Todo | Decomposer — breaks refined plan into tasks | | Clerk | Researcher — searches codebase, returns structured findings | | Senior Dev | Implementer — receives scoped prompt, produces code | | Junior Dev | Reviewer — strict COMPLETE/QUESTIONS parsing | | Debug | Strategist — fresh perspective after 3 failed loops | | Manifold/ | Persistent knowledge — task logs, index, graph |

Architecture

Planning Phase (Plugin-Orchestrated)

User → /manifold-plan <plan-file>
  │
  ▼ Plugin creates session, invokes Planner
Planner → analyzes plan → returns JSON questions
  │
  ▼ Plugin presents questions in chat
User → answers (numbered list)
  │
  ▼ Plugin invokes Planner with Q&A
Planner → returns refined plan markdown
  │
  ▼ Plugin saves to Manifold/plans/<slug>-plan.md
User → /manifold-decompose <plan>
  │
  ▼ Plugin invokes Todo agent
Todo → decomposes into task list
  │
  ▼ Plugin saves to Manifold/plans/<slug>-tasks.md
User reviews → approves → /manifold-execute

Implementation Phase (Plugin State Machine)

Plugin Code (TypeScript, deterministic)
  │
  ├── For each task:
  │     ├── Create session → invoke Clerk
  │     │     └── Clerk researches → returns findings
  │     │
  │     ├── Extract scoped prompt from Clerk output
  │     │
  │     ├── Dev Loop (up to 3 iterations):
  │     │     ├── Create session → invoke Senior Dev with scoped prompt
  ���     │     ├── Create session → invoke Junior Dev with implementation
  │     │     ├── Parse response: COMPLETE → done, QUESTIONS → loop
  │     │     └── Feed Junior feedback to Senior on next iteration
  │     │
  │     ├── If loops exhausted:
  │     │     ├── Create session → invoke Debug for fresh perspective
  │     │     ├── One final Senior attempt with Debug suggestion
  │     │     └── Final Junior review → if still fails, escalate
  │     │
  │     ├── Log result to Manifold/tasks/<id>.md
  │     ├── Update index.md, log.md, graph/
  │     └── Save orchestrator state
  │
  └── User runs /manifold-continue for next task

Agents

| Agent | Model | Role | Called By | |-------|-------|------|-----------| | planner | planning | Interview Agent — asks clarifying questions, refines plans | Plugin (interview phase) | | todo | planning | Process Engineer — decomposes refined plans into tasks | Plugin (decomposition phase) | | clerk | conceptualizing + large context | Researcher — searches codebase, returns structured findings | Plugin (per task) | | senior-dev | coding | Implementation specialist | Plugin (per loop) | | junior-dev | cheap/small coding | Review agent — strict COMPLETE/QUESTIONS | Plugin (per loop) | | debug | coding + troubleshooting | Fresh perspective after 3 failed loops | Plugin (escalation) | | manifold | good tool calling + planning | User-facing guide — explains system, presents results | User |

Agent Specialization

Planning Phase (Plugin-orchestrated):

• Planner analyzes plan, generates questions, produces refined document
• Todo decomposes with full architectural awareness from Clerk research
• Plugin presents questions to user and manages the flow

Implementation Phase (Plugin-orchestrated):

• Clerk researches codebase, returns structured findings (no orchestration)
• Senior Dev implements scoped prompt (no self-managed loops)
• Junior Dev reviews — strict first-word parsing by plugin code
• Debug provides fresh perspective when loop is stuck

The sr/jr/debug loop enables cost-efficient workflows: a strong sr-dev paired with a cheaper junior for review, and a different model for debug (fresh perspective). The key is diversity between sr and debug, not raw power. Junior's role as reviewer means a smaller/cheaper model works well — the sr/jr loop catches most issues, and debug's different reasoning approach breaks deadlocks.

Customizing Agents

Agents are markdown files with opencode frontmatter for configuration (description, mode, permissions, model) and a body that becomes the agent's system prompt.

Manifold uses a three-tier template system:

Bundled (inside npm package)
  └── Never edit directly — overwritten on updates
        │
        ▼  Plugin load (one-time, only copies missing files)
~/.config/opencode/manifold/  ← Global templates
  ├── agents/   (clerk.md, senior-dev.md, ...)
  ├── skills/   (manifold-workflow/, clerk-orchestration/, ...)
  ├── manifold/ (settings.json, schema.md, ...)
  └── config/   (opencode.json)
        │
        ▼  /manifold-init (only copies missing files)
Project root
  ├── .opencode/agents/   ← Per-project (editable)
  ├── .opencode/skills/
  ├── Manifold/
  └── opencode.json

Per-project customization

Edit files directly in .opencode/agents/ or .opencode/skills/. These are never overwritten by /manifold-init — only files that don't exist yet are copied.

Global customization

Edit files in ~/.config/opencode/manifold/. All new projects initialized with /manifold-init will inherit your customized versions.

Resetting

To reset a specific agent to its default, delete just that file and run /manifold-init again:

rm .opencode/agents/senior-dev.md
# Then run /manifold-init

To reset all Manifold files, delete the directories and re-run:

rm -rf .opencode/agents/ .opencode/skills/ Manifold/
# Then run /manifold-init

Assigning models to agents

Using the get-model-path tool: Say "call the get-model-path tool" to get the current model path (e.g., google/gemini-3-flash). Then manually edit the agent's frontmatter:

---
description: Implementation specialist
model: google/gemini-3-flash
---

Manual: Add a model field to the agent's frontmatter or your opencode.json:

{
  "agent": {
    "senior-dev": {
      "model": "anthropic/claude-sonnet-4-20250514"
    },
    "junior-dev": {
      "model": "anthropic/claude-haiku-4-20250514"
    }
  }
}

See the Example Configurations section for model pairing suggestions.

Example Configurations

| Budget | Senior Dev | Junior Dev | Debug | |--------|-----------|-----------|-------| | Self Host | Qwen3.5 27B | Gemma 4 31B | GLM 4.7 Flash | | Cost-effective | Qwen3.5 397B A17B | MiniMax-2.7 | GLM 5.1 | | Premium | Claude Opus | GPT 5.4 | Gemini 3.1 pro |

Models change frequently. These examples prioritize sr/debug diversity and cost gradient.

Manifold Folder Structure

Manifold/
├── .obsidian/          # Makes it an Obsidian vault
├── index.md            # Catalog of all tasks
├── log.md              # Chronological append-only log
├── plans.json          # Plan registry
├── schema.md           # Wiki conventions
├── settings.json       # User-tunable parameters
├── state.json          # State machine persistence
├── tasks/              # Individual task logs
│   ├── share-cart-001.md
│   └── ...
└── graph/              # Document graph
    ├── src_middleware_auth_ts.md
    └── ...

Settings

Located at Manifold/settings.json:

| Setting | Default | Description | |---------|---------|-------------| | maxLoops | 3 | Senior↔Junior loops before Debug escalation | | maxRetries | 1 | Retry attempts per agent call | | maxResults | 10 | Codebase-index search results | | recentTaskCount | 3 | Recent task logs to read for context | | clerkRetryEnabled | true | Clerk gets second pass after Debug fails | | timeout | 300 | Max seconds per agent call | | testCommand | null | Default test command | | updateCachePaths | [] | Legacy setting, no longer used |

Session Resumption

If a session crashes mid-loop:

• The Lead Dev reads the plan file
• Completed tasks are marked in index.md
• Lead Dev picks up from the first unmarked task
• The existing task log (created in Phase 1) shows partial work

No mid-loop state recovery needed — restart the task, the Clerk's research phase accounts for what was already done.

FAQ

Q: Do I need to configure agents? A: No. Run /manifold-init once per project and it sets up agent definitions, skills, and configuration from templates.

Q: Can I customize agents and skills? A: Yes. See the Customizing Agents section for the full three-tier template system.

Q: What is the Clerk's role? A: The Clerk has full project sight. It researches context (codebase-index, wiki, graph), composes scoped prompts for workers, and maintains the wiki.

Q: What happens if Debug also fails? A: The Clerk gets one retry with full failure context. If that also fails, the task escalates to you.

Q: Can I define tests for tasks? A: Yes. Add test: <command> in the task description or set testCommand in settings.json.

Q: What plugins does Open Manifold require? A: The opencode-codebase-index plugin is required for semantic code search. Install it alongside opencode-manifold.

Q: Is Obsidian required? A: No, but recommended. The Manifold/ folder is an Obsidian vault for browsing logs, tasks, and the knowledge graph. You can use any markdown viewer.

Q: Can I use Open Manifold without semantic search? A: The system is designed around the Clerk's ability to research context via semantic search. Modifying it would require significant changes to the Clerk's orchestration skill.

Plugin Updates

Opencode caches plugins to improve startup performance. When a new version of opencode-manifold is published, clear the cache to receive the update.

macOS/Linux

rm -rf ~/.cache/opencode/packages/opencode-manifold@latest
# If installed via npm globally:
rm -rf ~/node_modules/opencode-manifold

Windows

rmdir /s "%LOCALAPPDATA%\opencode\packages\opencode-manifold@latest"

Then restart opencode to pull the fresh version.

Uninstall

To remove Open Manifold from a project:

rm -rf .opencode/agents/ .opencode/skills/ Manifold/

Then remove "opencode-manifold" from the plugin array in your opencode.json.

Clear Plugin Cache (Optional)

If you want to fully remove cached plugin files:

macOS/Linux:

rm -rf ~/.cache/opencode/packages/opencode-manifold@latest

Windows:

rmdir /s "%LOCALAPPDATA%\opencode\packages\opencode-manifold@latest"

Remove Global Templates

rm -rf ~/.config/opencode/manifold/

Attributions

• Caveman — Julius Brussee — Ultra-compressed communication skill used by all Manifold agents to reduce token usage while maintaining technical accuracy.

License

GPL 3+. See LICENSE file.