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.

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. Point the Lead Dev agent at your plan file and tell it to execute

The Lead Dev will:

• Extract tasks from your plan
• Dispatch each to the multi-agent system
• Log all decisions to Manifold/

Architecture: The Circuit Board Model

Think of a plan as a circuit board design:

| Agent | Role | Question | |-------|------|----------| | Manifold | Board Designer | "What is this board's intended function?" | | Clerk | Systems Integrator | "How does this board interface with existing system?" | | Todo | Process Engineer | "What's the assembly sequence?" |

This ensures every plan is:

• Clearly understood (Manifold clarifies)
• Architecturally sound (Clerk validates fitment)
• Actionably decomposed (Todo sequences)
• Double-checked (Manifold + Clerk review)

Architecture

Planning Phase (Pre-Dispatch)

User → points to plan file (any format)
  │
Manifold (Phase 0: Ingest Clarity)
  │ Validates requirements are clear
  │ Assesses if input is granular
  ↓
Clerk (Phase 1: Research) — ALWAYS runs first
  │ Searches codebase, wiki, graph
  │ Answers: "How does this fit?"
  ↓
Todo (Phase 2: Decomposition) — Only if not granular
  │ Creates task list with context awareness
  │ Applies purity tags
  ↓
Manifold (Phase 3: Design Review)
  │ Validates task list satisfies plan intent
  │ Kickback to Todo if needed
  ↓
Clerk (Phase 4: Interface Validation)
  │ Validates fitment against codebase
  │ Kickback to Todo if needed
  ↓
User Approval
  ↓

Implementation Phase

Plugin State Machine (TypeScript, zero LLM cost)
  │
  ├── Phase 1: Clerk research (per task)
  │     ├── codebase-index search + wiki lookback + graph entries
  │     ├── Composes scoped prompt
  │     └── Creates task log file
  │
  ├── Phase 2: Senior/Junior/Debug loop
  │     ├── Spawn Senior Dev → implementation
  │     ├── Spawn Junior Dev → review (first word: COMPLETE or QUESTIONS)
  │     ├── Loop up to 3×, then escalate to Debug
  │     └── Debug → one loop with Senior+Debug, then escalate to Clerk retry
  │
  ├── Phase 3: Clerk logging
  │     ├── Appends design decisions to task log
  │     ├── Updates index.md, appends log.md, updates graph entries
  │     └── Returns to Manifold
  │
  └── Phase 4: Test (optional)
        ├── If test defined → run, check output
        └── If no test → complete

Agents

| Agent | Model | Role | |-------|-------|------| | manifold | good tool calling + planning | Board Designer — orchestrates planning and dispatch | | clerk | conceptualizing + large context | Systems Integrator — researches codebase, validates integration | | todo | planning | Process Engineer — decomposes plans into task lists | | senior-dev | coding | Implementation specialist | | junior-dev | cheap/small coding | Review agent | | debug | coding + troubleshooting | Fresh perspective after 3 failed loops |

Agent Specialization

Planning Phase:

• Manifold handles clarity assessment, design review, and final validation
• Clerk researches codebase integration (always runs first, even for granular inputs)
• Todo decomposes with full architectural awareness

Implementation Phase:

• Clerk composes scoped prompts and maintains wiki
• Senior Dev implements
• Junior Dev reviews
• Debug breaks deadlocks after 3 failed loops

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.