opencode-manifold 0.5.14 → 0.5.16

package/README.md

@@ -6,6 +6,8 @@ A Lead Dev agent walks through a task plan, a deterministic plugin state machine
 
 **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
@@ -72,115 +74,119 @@ Open Manifold requires:
 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/`
+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: The Circuit Board Model
-
-Think of a plan as a circuit board design:
+## Architecture: Plugin-Driven Orchestration
 
-| 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?" |
+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.
 
-This ensures every plan is:
-- Clearly understood (Manifold clarifies)
-- Architecturally sound (Clerk validates fitment)
-- Actionably decomposed (Todo sequences)
-- Double-checked (Manifold + Clerk review)
+| 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 (Pre-Dispatch)
+### Planning Phase (Plugin-Orchestrated)
 
 ```
-User → points to plan file (any format)
+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)
   │
-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
-  ↓
+  ▼ 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
+### Implementation Phase (Plugin State Machine)
 
 ```
-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
+Plugin Code (TypeScript, deterministic)
   │
-  ├── Phase 3: Clerk logging
-  │     ├── Appends design decisions to task log
-  │     ├── Updates index.md, appends log.md, updates graph entries
-  │     └── Returns to Manifold
+  ├── 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
   │
-  └── Phase 4: Test (optional)
-        ├── If test defined → run, check output
-        └── If no test → complete
+  └── User runs /manifold-continue for next task
 ```
 
 ---
 
 ## 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 | 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:**
-- **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
+**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:**
-- **Clerk** composes scoped prompts and maintains wiki
-- **Senior Dev** implements
-- **Junior Dev** reviews
-- **Debug** breaks deadlocks after 3 failed loops
+**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.