Skip to content
/

GoopSpec

goopspec · hffmnnj/opencode-goopspec · ★ 29 · last commit 2026-04-15

Enforces spec-driven development in OpenCode via a 5-phase workflow with two mandatory human contract gates, a 16-agent multi-model orchestration system, and a memory pipeline that learns from every completed milestone.

Best whenThe AI cannot declare itself done — two explicit human confirmations ('confirm' to lock spec, 'accept' to approve work) are architecturally required before a…
Skip ifConductor writing code directly (blocked by hook), Agents reading/editing state.json directly (must use goop_state tool)
vs seeds
openspecseed (Archetype 4: markdown scaffold), it adds 16 agents, 22 MCP tools, 7 hooks, a CLI binary, wave execution, git workt…
Primitive shape 97 total
Commands 19 Skills 33 Subagents 16 Hooks 7 MCP tools 22
00

Summary

goopspec — Summary

GoopSpec is a spec-driven development platform delivered as an OpenCode plugin that enforces a 5-phase workflow (Discuss → Plan → Execute → Audit → Confirm) with two mandatory human confirmation gates that prevent the AI from declaring itself done. Unlike the base openspec seed (which targets Claude Code/Cursor), GoopSpec is purpose-built for OpenCode and extends the SDD pattern with a 16-agent multi-model orchestration system routing tasks to different LLMs by complexity tier (low/medium/high/frontend). The orchestrator agent (The Conductor, claude-opus-4-6) never writes code — it delegates to 15 specialist agents each with a designated default model. GoopSpec introduces git worktree isolation, wave-based implementation, a semantic memory system with local embeddings (all-MiniLM-L6-v2 via SQLite), an Automated Decision Log (ADL), and a 4-rule deviation system that auto-handles bugs/missing error handling but stops and asks before architectural changes. With 29 stars, 1,660 passing tests, and a Bun monorepo with 4 packages (core, daemon, opencode-plugin, web), it is the most execution-complete framework in this batch — a self-contained development OS around spec-driven workflow.

differs_from_seeds

Compared to the openspec seed (Archetype 4), GoopSpec adds an entirely new dimension: multi-model routing, a dedicated CLI binary, wave-based execution, git worktree isolation, semantic memory, and human-gated contracts. Compared to ralphy-openspec (SQLite state + Ralph Loop in this batch), GoopSpec uses a Conductor+Specialists orchestration model where each specialist has a distinct LLM rather than a single-agent continuous loop. Compared to goose (open-source general agent), GoopSpec is spec-first and workflow-locked — it forces discovery interviews before planning. The two CONTRACT GATE checkpoints are the defining differentiator: the AI cannot self-complete without explicit human "confirm" and "accept" inputs at spec-lock and post-execution respectively.

01

Overview

goopspec — Overview

Origin

GoopSpec (v0.2.9) is an OpenCode plugin authored by hffmnnj, released under MIT license, with last commit 2026-04-15. The repository is a TypeScript/Bun monorepo with 29 stars and 1,660 passing tests. It targets OpenCode as the sole primary IDE and cannot run under Claude Code or Cursor without adaptation.

Philosophy

From the README:

Stop the AI chaos. Ship what you actually want.

You've been there. You ask an AI to build a feature. It starts coding immediately, misses half your requirements, forgets context mid-conversation, and delivers something that... works? But isn't what you wanted.

GoopSpec fixes this.

It's a spec-driven workflow for OpenCode that forces clarity before code. You describe what you want, GoopSpec interviews you to uncover the edge cases, locks a specification you both agree on, then executes against that contract.

No more "that's not what I meant." No more scope creep. No more AI amnesia.

Core beliefs:

  • Ask, Don't Assume — Interview first, code second
  • Spec as Contract — Lock requirements before execution
  • Memory-First — Learn from every project
  • Scale to the Task — Quick fixes skip gates, big features get the full workflow

Verbatim from orchestrator agent

From packages/opencode-plugin/agents/goop-orchestrator.md:

You are the Conductor of the GoopSpec orchestra. You coordinate. You delegate. You track. You enforce gates. You NEVER play the instruments yourself.

Verbatim from goop-plan command

From packages/opencode-plugin/commands/goop-plan.md:

Gate: interviewComplete: true required. Check via goop_state({ action: "get" }).

IF interviewComplete is not true: return BLOCKED immediately with: "Cannot plan. Run /goop-discuss first." Do not process further instructions.

Verbatim from deviation rules (README)

Rule 4: Ask About Architectural Changes

STOP and ask before:

  • Database schema changes
  • Framework/library switches
  • Breaking API changes
  • New infrastructure

All deviations are logged to the Automated Decision Log (ADL).

02

Architecture

goopspec — Architecture

Distribution Type

OpenCode plugin (npm package @goopspec/opencode-plugin v0.2.9) + standalone CLI binary goopspec.

Install Methods

  1. Plugin (primary) — Add "goopspec" to plugins array in opencode.json, then run goopspec init
  2. CLI onlynpx goopspec init or bunx goopspec init
  3. Build from sourcegit clone ... && bun install && bun run build

Monorepo Package Structure

opencode-goopspec/
├── packages/
│   ├── core/                    # @goopspec/core v0.1.0 — shared types, utilities
│   ├── daemon/                  # Background state sync process
│   ├── opencode-plugin/         # @goopspec/opencode-plugin v0.2.9 (primary)
│   │   ├── agents/              # 16 agent YAML+Markdown definitions
│   │   ├── commands/            # 19 slash command Markdown files
│   │   ├── skills/              # 33+ skill directories (goop-core, task-delegation, etc.)
│   │   ├── references/          # Reference docs loaded by agents at runtime
│   │   ├── templates/           # Markdown templates for SPEC.md, BLUEPRINT.md, etc.
│   │   ├── src/
│   │   │   ├── hooks/           # 7 hook files (compaction, enforcement, auto-progression, etc.)
│   │   │   ├── tools/           # 22 MCP tool directories
│   │   │   ├── agents/          # Agent runtime code
│   │   │   ├── features/        # Feature modules
│   │   │   └── plugin-handlers/ # OpenCode plugin integration
│   │   └── package.json
│   └── web/                     # Web UI (optional dashboard)
├── goopspec.example.json        # Full config example with all options
└── bun.lock

Project State Directory (.goopspec/)

.goopspec/
├── SPEC.md              # Locked specification (current)
├── BLUEPRINT.md         # Execution plan (current)
├── CHRONICLE.md         # Journey log
├── RESEARCH.md          # Research findings
├── config.json          # Project configuration
├── quick/               # Quick task history
│   └── 001-fix-typo/
│       └── SUMMARY.md
├── milestones/          # Active milestones
│   └── v1.0-auth/
└── archive/             # Completed milestones
    └── v0.9-setup/
        ├── RETROSPECTIVE.md
        └── LEARNINGS.md

Configuration (goopspec.example.json / .goopspec/config.json)

Key configurable sections:

  • projectName — project identifier
  • enforcementassist | warn | strict
  • agents — per-agent model + temperature overrides (12 agents configurable)
  • mcp — enable/disable context7, exa, playwright, memory, github, sqlite
  • orchestrator — model, thinkingBudget, phaseGates, waveExecution
  • memory — enabled flag, workerPort, capture settings, injection settings, privacy patterns

Required Runtime

  • Bun 1.0+
  • OpenCode (primary target IDE)
  • Node.js/npm (for npx install alternative)
  • Optional: MCP servers (context7, exa, playwright, memory, github, sqlite)

Target Tools

  • Primary: OpenCode
  • Secondary: any OpenCode-compatible environment
03

Components

goopspec — Components

CLI Binary: goopspec

Subcommand Purpose
goopspec init Interactive setup wizard — configure project name, agent models, MCP servers, memory, enforcement level
goopspec models Configure agent models — assign specific LLMs to each specialist agent
goopspec memory Configure the memory system — provider selection, vector search, dependency installation
goopspec status Show current configuration — project info, memory, MCP servers, agent models
goopspec verify Run health checks — validate config files, MCP servers, memory system, dependencies
goopspec reset Reset configuration — remove global, project, or both config scopes with confirmation

Slash Commands (19 total)

Workflow Commands

Command Purpose
/goop-discuss Start discovery interview to gather requirements before planning
/goop-plan Create SPEC.md and BLUEPRINT.md from completed interview
/goop-execute Begin wave-based implementation against the locked spec
/goop-accept Verify and accept work at the ACCEPTANCE GATE

Task Mode Commands

Command Purpose
/goop-quick [task] Fast-track a small task (skip gates)
/goop-milestone [name] Start a versioned milestone with full tracking

Research & Debug

Command Purpose
/goop-research Deep domain research on unknowns or risks
/goop-debug Scientific debugging workflow
/goop-map-codebase Analyze existing codebase structure
/goop-pr-review Review a GitHub pull request with intelligent fixes and safe merge

Memory Commands

Command Purpose
/goop-recall [query] Search past work and memory using semantic search
/goop-remember [note] Save important context to persistent memory
/goop-memory View memory system status

Utility Commands

Command Purpose
/goop-status Show current workflow state
/goop-setup First-time setup wizard
/goop-amend [change] Propose spec changes after lock
/goop-pause Save checkpoint and pause work
/goop-resume [id] Resume from a saved checkpoint
/goop-help Show help and available commands

Agents (16 total)

Orchestrator

Agent Alias Default Model Purpose
goop-orchestrator The Conductor anthropic/claude-opus-4-6 Coordinates all work; NEVER writes code; enforces gates

Executor Tier System

Agent Alias Default Model Purpose
goop-executor-low The Builder (Low) anthropic/claude-sonnet-4-6 Config, simple edits, boilerplate
goop-executor-medium The Builder (Medium) kimi-for-coding/k2p5 Business logic, middleware, tests
goop-executor-high The Builder (High) openai/gpt-5.3-codex Architecture, complex algorithms, security
goop-executor-frontend The Builder (Frontend) anthropic/claude-opus-4-6 UI, styling, responsiveness, accessibility

Specialists

Agent Alias Default Model Purpose
goop-planner The Architect openai/gpt-5.3-codex Creates SPEC.md and BLUEPRINT.md
goop-researcher The Scholar openai/gpt-5.2 Deep domain research
goop-explorer The Scout google/gemini-3-flash Fast codebase mapping
goop-verifier The Auditor openai/gpt-5.3-codex Verifies implementation against spec
goop-debugger The Detective openai/gpt-5.3-codex Scientific debugging
goop-creative The Visionary anthropic/claude-opus-4-6 Creative ideation and architecture brainstorming
goop-designer The Artisan anthropic/claude-opus-4-6 UI/UX design
goop-tester The Guardian kimi-for-coding/k2p5 Test writing
goop-writer The Scribe google/gemini-3-pro-high Documentation
goop-librarian The Archivist openai/gpt-5.2 Code and doc search
memory-distiller The Curator zai-coding-plan/glm-4.7 Extracts learnings to persistent memory

MCP Tools (22 tools)

Tool Purpose
goop-adl Automated Decision Log — record deviations and architectural decisions
goop-checkpoint Save/restore workflow checkpoints
goop-spec Validate and manage SPEC.md (lock/unlock spec)
goop-state Get/set workflow state machine (never edit state.json directly)
goop-status Full workflow status with phase and gate info
goop-reference Load named reference documents into agent context
goop-skill Load named skill documents into agent context
memory-save Persist a memory with metadata
memory-search Semantic search over past memories
memory-note Save a quick note to memory
memory-decision Save a decision with reasoning to memory
memory-forget Remove a memory entry
worktree-create Create a git worktree for isolated work
worktree-delete Remove a git worktree
session-search Search past sessions
slashcommand Invoke another slash command programmatically (enables chaining)
goop-pr-review GitHub PR analysis and merge tooling
goop-setup Runtime setup configuration
goop-daemon-items Daemon background task item management
goop-daemon-projects Daemon project tracking
goop-daemon-status Daemon health status
goop-daemon-workflow Daemon workflow event streaming

Hooks (7 files)

Hook Purpose
compaction-hook.ts Handles context compaction — triggers memory distillation before window overflow
orchestrator-enforcement.ts Prevents orchestrator from writing code directly (enforces Conductor role)
auto-progression.ts Autopilot mode — automatically advances phases when gates are met
event-handler.ts Routes OpenCode plugin events to handlers
system-transform.ts Transforms system prompts to inject phase context
tool-lifecycle.ts Intercepts tool calls for ADL logging and enforcement
chat-message.ts Monitors chat messages for command triggers and gate signals

Skills (33 named skill directories)

Examples: goop-core, task-delegation, progress-tracking, deviation-handling, memory-usage, accessibility-testing, architecture-design, atomic-commits, debugging, documentation, scientific-method, security-audit, task-decomposition, testing, verification, visual-regression, and 17 more.

Planning Files (state artifacts)

File Purpose
SPEC.md Locked specification with must-haves and out-of-scope
BLUEPRINT.md Execution plan with ordered waves and tasks
CHRONICLE.md Journey log tracking progress across sessions
RESEARCH.md Research findings from exploration phase
RETROSPECTIVE.md Post-completion analysis
LEARNINGS.md Extracted patterns and insights for memory pipeline
05

Prompts

goopspec — Prompts

Verbatim: goop-orchestrator agent (mandatory first steps)

From packages/opencode-plugin/agents/goop-orchestrator.md:

## ⚠️ MANDATORY FIRST STEP

**DO NOT proceed past this section until all steps are complete.**

**Step 1: Load Full Project State**

goop_status() # Full workflow status goop_state({ action: "get" }) # ALWAYS use goop_state, NEVER read state directly Read(".goopspec//SPEC.md") # Requirements (if exists) Read(".goopspec//BLUEPRINT.md") # Execution plan (if exists) Read(".goopspec//CHRONICLE.md") # Progress log (if exists) Read(".goopspec/PROJECT_KNOWLEDGE_BASE.md") # Project context (global, if exists)


**CRITICAL: Never read or edit state directly via files. Always use `goop_state` tool for all state operations.**

**Step 2: Search Memory for Context**

memory_search({ query: "[current task or user request]", limit: 5 })


**Step 5: Acknowledge State**
Before orchestrating, state:
- Current phase: [from goop_state output]
- Interview complete: [yes/no from goop_state]
- Spec locked: [yes/no from goop_state]
- Active wave: [if executing]
- User request: [from prompt]

**ONLY THEN proceed to orchestration.**

Verbatim: goop-discuss command (the six questions)

From packages/opencode-plugin/commands/goop-discuss.md:

### The Six Questions

Use the `question` tool with category-specific options for each discovery question. 
Always include a "Type your own answer" option. Adapt labels to the user's project context.

1. **Vision** — What are you building? What problem? Who for?
   - Options: "New feature for an existing app (Recommended)", "Bug fix or improvement", 
     "New standalone project", "Refactor or migration", custom

2. **Must-Haves** — Non-negotiable requirements and acceptance criteria
   - Options: "Add a new must-have requirement (Recommended)", "Review what we have so far", 
     "That covers the must-haves", custom
   - Loop until the user selects "That covers the must-haves"

3. **Constraints** — Stack, frameworks, performance, timeline
   - Options: "Stack or framework requirements (Recommended)", "Performance or scalability 
     targets", "Timeline or resource limits", "Must integrate with existing code", 
     "No specific constraints", custom

4. **Out of Scope** — What we're NOT building
   [...]

Verbatim: goop-execute command (autopilot hard rule)

From packages/opencode-plugin/commands/goop-execute.md:

### Autopilot

**If `workflow.autopilot` is `true`**: skip the wave-completion continuation `question` 
calls between waves and auto-proceed through all waves without stopping. Do not ask 
"How would you like to continue?" or any equivalent inter-phase confirmation.

When all waves are complete, immediately call:

mcp_slashcommand({ command: "/goop-accept" })


**Hard rule:** Do NOT display "Start a new session, then run `/goop-accept`" and stop. 
Announcing intent in text without calling the tool is a **hard failure** — `/goop-accept` 
never runs. The transition only happens when `mcp_slashcommand` is actually executed.

Verbatim: goop-plan command (gate check)

From packages/opencode-plugin/commands/goop-plan.md:

### STOP-AND-RETURN

**Execute this tool call NOW before reading anything else:**

goop_state({ action: "get" })


**IF `interviewComplete` is not `true`:** return **BLOCKED** immediately with: 
"Cannot plan. Run /goop-discuss first." Do not process further instructions.

### Autopilot

**If `workflow.autopilot` is `true`**: skip the Contract Gate confirmation `question`, 
call `goop_state({ action: "lock-spec" })` immediately after planning completes, 
then immediately execute:

mcp_slashcommand({ command: "/goop-execute" })


**Hard rule:** Do NOT write "Autopilot enabled — proceeding to /goop-execute" and then stop. 
Announcing intent in text without calling the tool is a **hard failure** — `/goop-execute` 
never runs. Do not ask "Ready to proceed?" or any equivalent confirmation.

Verbatim: orchestrator Conductor role description

From packages/opencode-plugin/agents/goop-orchestrator.md:

You are the **Conductor** of the GoopSpec orchestra. You coordinate. You delegate. 
You track. You enforce gates. You **NEVER** play the instruments yourself.
| Tool | When to Use |
|------|-------------|
| `goop_status` | Start of every session - understand current state |
| `goop_state` | **ALL state operations** - transition phases, lock spec, complete interview. 
  NEVER edit state directly via files |
| `goop_checkpoint` | Before risky operations, at wave boundaries |
| `slashcommand` | Execute user-requested workflow commands |
| `task` | **Delegation + Execution** - directly dispatches subagents with complete context-rich prompts |
| `goop_adl` | Log decisions, deviations, observations |
| `memory_search` | Find prior context before delegating |
| `memory_decision` | Record architectural choices |
09

Uniqueness

goopspec — Uniqueness and Positioning

differs_from_seeds

Compared to the openspec seed (Archetype 4: markdown scaffold), GoopSpec adds an entirely separate execution layer: a 16-agent multi-model system, 22 MCP tools, 7 hooks, a CLI binary, wave-based execution, git worktree isolation, semantic memory with local embeddings, and an ADL. This is not a spec-storage overlay — it is a spec-first development OS built on top of OpenCode. Compared to ralphy-openspec (this batch), both use persistent state and a CLI binary, but GoopSpec uses Conductor+Specialists orchestration with distinct LLMs per role vs. ralphy's single-agent SQLite+Ralph Loop. Compared to taskmaster-ai (MCP toolserver seed), GoopSpec includes an equivalent MCP toolset but pairs it with structured agent roles and a mandatory discovery interview. Compared to BMAD (hierarchical multi-agent), GoopSpec is equally role-rich but spec-first — the discovery interview and CONTRACT GATE are non-optional entry points, not optional add-ons. The two mandatory human confirmation gates (CONTRACT GATE at spec-lock and ACCEPTANCE GATE after execution) are the defining differentiator in the entire corpus: GoopSpec is the only framework where the AI is architecturally prevented from declaring itself done without explicit typed human confirmation.

Positioning

  • Niche: "Full-stack spec-driven development OS for OpenCode with mandatory human contract gates"
  • Primary differentiator: Two-gate contract system (confirm before code, accept after code) — the AI cannot self-complete
  • Secondary differentiator: Executor tier routing — 4 executor agents (low/medium/high/frontend) each with a different default LLM, routing tasks by complexity
  • Memory-first: Local embedding-based semantic memory (all-MiniLM-L6-v2) with archive-to-memory pipeline across milestones
  • OpenCode-exclusive: Tightly coupled to OpenCode plugin API; not portable to Claude Code, Cursor, or Copilot without rewrite
  • Test coverage: 1,660 passing tests — the highest demonstrated test investment in this batch

Observable Failure Modes

  1. OpenCode lock-in: GoopSpec cannot run outside OpenCode without significant porting effort. Teams using Claude Code, Cursor, or VS Code Copilot cannot adopt it without a parallel implementation.
  2. Memory system disabled by default: The semantic memory (the "Memory-First" pillar) is explicitly noted as disabled by default due to worker architecture issues. This means the key differentiating memory feature requires additional setup and may not work reliably.
  3. No parallel wave execution (v0.2 planned): The README explicitly states that parallel research and wave execution are "planned for v0.2; current implementation does not spawn agents yet." Sequential waves reduce execution speed for large features.
  4. Model cost surface: Default model list includes claude-opus-4-6 (orchestrator, frontend), gpt-5.3-codex (high executor, planner, verifier, debugger), and gpt-5.2 (researcher, librarian). Running a single mid-sized feature through all phases could touch 6+ different paid API endpoints.
  5. Autopilot bypasses the core value prop: The autopilot mode (bypass both gates) defeats GoopSpec's primary claim — that the AI cannot declare itself done. Teams that enable autopilot lose the CONTRACT GATE and ACCEPTANCE GATE that make the system distinctive.
  6. 29 stars, 1 contributor: Low external validation despite sophisticated implementation. No evidence of production use outside the author.

Explicit Anti-Patterns

From the goop-orchestrator agent definition:

  • Conductor writing code directly (blocked by orchestrator-enforcement.ts hook)
  • Reading/editing state.json directly (all agents must use goop_state tool)
  • Announcing intent without calling the tool ("Autopilot enabled — proceeding" then stopping = hard failure)
  • Asking "Ready to proceed?" or equivalent confirmation in autopilot mode

From the deviation rules:

  • Making architectural changes (DB schema, framework switch, breaking API) without stopping and asking
04

Workflow

goopspec — Workflow

Five-Phase Workflow

  DISCUSS        PLAN         EXECUTE        AUDIT        CONFIRM
 ┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐    ┌────────┐
 │  What  │    │  How   │    │ Build  │    │ Verify │    │ Accept │
 │   do   │ ─> │  will  │ ─> │   it   │ ─> │   it   │ ─> │   it   │
 │  you   │    │   we   │    │        │    │        │    │        │
 │ want?  │    │ do it? │    │        │    │        │    │        │
 └────────┘    └────────┘    └────────┘    └────────┘    └────────┘
      |              |             |             |             |
   Interview     Create       Waves of      Check vs.    You sign
   to uncover    locked       atomic        the spec     off on it
   requirements  spec         commits
                   |                                          |
                   └──────── CONTRACT GATE ───────────────────┘

Phases and Artifacts

Phase Command Artifact(s) Description
Discuss /goop-discuss (interview only) 6-question discovery interview; uncovers requirements, constraints, risks, out-of-scope
Plan /goop-plan SPEC.md, BLUEPRINT.md Creates locked specification and wave-based execution plan
CONTRACT GATE user types "confirm" Human confirms spec before execution begins; blocks /goop-execute
Execute /goop-execute source code, atomic commits Wave-based implementation; Conductor delegates to executor tier agents
Audit (automatic during Execute) CHRONICLE.md Verifier agent checks each wave against SPEC.md; ADL logs deviations
Confirm /goop-accept RETROSPECTIVE.md Human reviews verification results; types "accept" to sign off
ACCEPTANCE GATE user types "accept" Human explicitly accepts the work; AI cannot self-complete

Approval Gates (2 mandatory)

Gate 1: Contract Gate (end of Plan, before Execute)

  • Presented as a formatted table of MUST-HAVES and OUT-OF-SCOPE items
  • User must type "confirm" to lock the spec
  • After lock, changes require /goop-amend (triggers re-review)
  • Format shown to user:
    +-------------------------------------------------------+
    |  CONTRACT GATE                                        |
    +-------------------------------------------------------+
    |  MUST-HAVES:           | OUT OF SCOPE:                |
    |  • Login with email    | • OAuth (future)             |
    |  • Session persistence | • Password reset             |
    |  • Error messages      |                              |
    +-------------------------------------------------------+
    |  Type "confirm" to lock. Changes require /goop-amend. |
    +-------------------------------------------------------+
    

Gate 2: Acceptance Gate (after Audit, completing Confirm)

  • Presented with verification results from goop-verifier (each requirement + test reference)
  • User must type "accept" to mark work complete
  • Format shown to user:
    +-------------------------------------------------------+
    |  ACCEPTANCE GATE                                      |
    +-------------------------------------------------------+
    |  VERIFIED:                                            |
    |  ✓ Login with email       (test: auth.test.ts:15)    |
    |  ✓ Session persistence    (test: session.test.ts:42) |
    |  ✓ Error messages         (manual check)             |
    |                                                       |
    |  Tests: 24/24 | Build: OK                             |
    +-------------------------------------------------------+
    |  Type "accept" to confirm completion.                 |
    +-------------------------------------------------------+
    

Wave-Based Execution

The Conductor (goop-orchestrator) assigns tasks to executor tiers per wave:

  1. Tasks classified into Low / Medium / High / Frontend tier
  2. Tasks within a wave run sequentially (parallel planned for v0.2, not yet implemented)
  3. Each task produces atomic commits
  4. Deviations logged to ADL immediately; Rule 4 (architectural changes) stops and asks user

Deviation System (4 Rules)

Rule Trigger Action
Rule 1 Type errors, logic bugs, security vulns, memory leaks Auto-fix immediately; log to ADL
Rule 2 Missing error handling, input validation, auth checks Auto-add immediately; log to ADL
Rule 3 Missing dependencies, broken imports, config errors Auto-fix immediately; log to ADL
Rule 4 DB schema changes, framework switches, breaking API changes, new infra STOP, ask user; blocked until answered

Quick Mode (bypass gates)

/goop-quick [task] — skips both CONTRACT and ACCEPTANCE gates for small single-file tasks. Produces a SUMMARY.md in .goopspec/quick/.

Milestone Mode

/goop-milestone [name] — wraps a full workflow cycle into a versioned milestone. Archives to .goopspec/archive/ with RETROSPECTIVE.md and LEARNINGS.md on completion.

Autopilot Mode

When workflow.autopilot: true in state, /goop-plan skips the Contract Gate confirmation and immediately chains to /goop-execute via mcp_slashcommand. Per the command definition: "Announcing intent in text without calling the tool is a hard failure."

06

Memory Context

goopspec — Memory and Context

State Storage

Two layers of state:

1. File-Based Planning Documents (.goopspec/)

File Scope Purpose
SPEC.md Per workflow Locked specification with must-haves and out-of-scope
BLUEPRINT.md Per workflow Wave-based execution plan
CHRONICLE.md Per workflow Journey log — updated every wave
RESEARCH.md Per workflow Research findings from goop-researcher
PROJECT_KNOWLEDGE_BASE.md Global Persistent project context across workflows
config.json Global Agent model assignments, enforcement level, MCP config
quick/*/SUMMARY.md Per quick task Quick task history
milestones/*/ Per milestone Active milestone tracking
archive/*/RETROSPECTIVE.md Per archived milestone Post-completion analysis
archive/*/LEARNINGS.md Per archived milestone Extracted patterns for memory pipeline

2. Machine State (goop_state tool, backed by state.json)

The goop_state tool is the only sanctioned way to read or write workflow state. Agents are explicitly prohibited from reading/editing state.json directly. State fields include:

  • interviewComplete — gates /goop-plan
  • specLocked — gates /goop-execute
  • workflowId — current workflow identifier
  • workflow.autopilot — whether gates are automatically bypassed

Memory System (Optional, disabled by default)

GoopSpec includes an optional semantic memory system using local embeddings:

  • Embedding model: all-MiniLM-L6-v2 (local, runs via worker)
  • Storage: SQLite database via dedicated worker process
  • Worker port: 37777 (configurable)
  • Status: Disabled by default due to worker architecture issues in bundled plugins (stated known limitation)

Memory Capture (when enabled)

Automatically captures from:

  • Architectural decisions (via memory_decision tool)
  • Observations and notes (via memory_note, memory_save tools)
  • Phase changes and tool use (configurable; captureToolUse, captureMessages, capturePhaseChanges flags)
  • Minimum importance threshold: 0.4 (configurable)
  • Privacy stripping: strips API keys, tokens, secrets matching regex patterns

Memory Injection (when enabled)

  • Budget: 1,400 tokens per session
  • Format: structured
  • Priority types: decision, observation, note
  • Injected into orchestrator context at session start via memory_search

Archive-to-Memory Pipeline

When milestones complete:

  1. Generate RETROSPECTIVE.md
  2. Extract LEARNINGS.md (patterns, decisions, gotchas)
  3. Persist learnings to memory with semantic concepts via memory-distiller agent (glm-4.7)
  4. Future projects benefit from past learnings via /goop-recall

Automated Decision Log (ADL)

All deviations and architectural decisions are logged to the ADL via the goop-adl MCP tool. This creates a structured audit trail of every auto-fix, auto-add, and explicitly asked deviation during execution.

Cross-Session Handoff

Yes — GoopSpec is explicitly designed for cross-session work:

  • CHRONICLE.md logs progress across sessions
  • goop_checkpoint tool saves checkpoints at wave boundaries
  • /goop-pause and /goop-resume [id] enable explicit pause/resume
  • At each wave boundary, HANDOFF.md is generated for the next session
  • The orchestrator's mandatory first step includes loading all prior state files

Context Compaction Handling

The compaction-hook.ts hook handles context window overflow:

  • Triggers memory distillation before the window fills
  • Routes important content through the memory-distiller agent for extraction before compaction
07

Orchestration

goopspec — Orchestration

Multi-Agent

Yes. 16 agents with explicit role separation: 1 Conductor + 15 specialists.

Orchestration Pattern

Conductor + Specialists (hub-and-spoke). The goop-orchestrator (The Conductor) is the sole entry point for all workflow commands. It:

  • Reads all state before any action
  • Delegates implementation tasks to executor tier agents
  • Delegates research to goop-researcher, goop-explorer, goop-librarian
  • Delegates verification to goop-verifier
  • Delegates planning to goop-planner
  • NEVER writes code itself

Multi-Model Routing

Yes — explicit per-agent model assignments with a tiered executor system:

Role Agent Default Model
Orchestrator goop-orchestrator anthropic/claude-opus-4-6
Low executor goop-executor-low anthropic/claude-sonnet-4-6
Medium executor goop-executor-medium kimi-for-coding/k2p5
High executor goop-executor-high openai/gpt-5.3-codex
Frontend executor goop-executor-frontend anthropic/claude-opus-4-6
Planner goop-planner openai/gpt-5.3-codex
Researcher goop-researcher openai/gpt-5.2
Explorer goop-explorer google/gemini-3-flash
Verifier goop-verifier openai/gpt-5.3-codex
Debugger goop-debugger openai/gpt-5.3-codex
Creative goop-creative anthropic/claude-opus-4-6
Designer goop-designer anthropic/claude-opus-4-6
Tester goop-tester kimi-for-coding/k2p5
Writer goop-writer google/gemini-3-pro-high
Librarian goop-librarian openai/gpt-5.2
Memory distiller memory-distiller zai-coding-plan/glm-4.7

All models are configurable via /goop-setup or goopspec models.

Delegation Mechanism

The Conductor uses the native OpenCode task tool to dispatch agents. Each delegation includes a complete context-rich prompt with current SPEC.md, BLUEPRINT.md, CHRONICLE.md, and relevant reference documents.

Isolation Mechanism

Git worktrees — worktree-create and worktree-delete MCP tools enable isolated branches per task or wave. Not mandatory but available.

Parallel Execution

Documented as a known limitation: parallel research and wave execution are planned for v0.2. Current implementation runs waves sequentially.

Execution Mode

Interactive-loop with optional autopilot. Standard mode: the Conductor pauses at each wave boundary and at both contract gates for human confirmation. Autopilot mode: gates and wave pauses are bypassed; mcp_slashcommand is used to chain phases automatically.

Consensus Mechanism

None. The Conductor is authoritative; specialists report back results. Human provides confirmation at gates.

Crash Recovery / Checkpoint

Yes — goop_checkpoint tool saves state at wave boundaries. /goop-pause saves an explicit checkpoint. /goop-resume [id] restores from checkpoint. HANDOFF.md generated at each wave boundary for cross-session continuity.

Hooks in the Orchestration Loop

7 hooks intercept the OpenCode plugin event stream:

  • orchestrator-enforcement.ts — blocks Conductor from writing code directly
  • auto-progression.ts — drives autopilot mode phase chaining
  • tool-lifecycle.ts — intercepts tool calls for ADL logging
  • compaction-hook.ts — triggers memory distillation before context overflow
  • system-transform.ts — injects phase/state context into system prompts
  • event-handler.ts — routes plugin events to handlers
  • chat-message.ts — monitors messages for command triggers and gate signals
08

Ui Cli Surface

goopspec — UI, CLI, and Observability

Dedicated CLI Binary

Yesgoopspec binary (shipped as @goopspec/opencode-plugin package).

Available via npx goopspec, bunx goopspec, or global install.

Subcommand Description
goopspec init Interactive setup wizard — project name, agent models, MCP servers, memory, enforcement level
goopspec models Configure per-agent model assignments
goopspec memory Configure memory system — provider, vector search, dependency installation
goopspec status Show current configuration — project info, memory, MCP servers, agent models
goopspec verify Run health checks — validate config files, MCP servers, memory system, dependencies
goopspec reset Reset global, project, or both config scopes with confirmation

The CLI handles setup and configuration outside of OpenCode. It is a thin configuration/setup wrapper — it does not execute the workflow itself.

Local Web Dashboard

Yespackages/web in the monorepo. Details about the web UI's feature set are limited in public documentation, but the package exists as a web visualization layer. Not described as a required component; appears to be an optional companion.

IDE Integration

OpenCode (primary) — GoopSpec is an OpenCode plugin. The plugin integrates via:

  • opencode.json plugins array
  • 19 slash commands available in OpenCode chat
  • 16 agent definitions loaded by OpenCode's agent runtime
  • 22 MCP tools registered with the OpenCode plugin system
  • 7 hooks intercepting the OpenCode event stream

Other IDEs: Not supported. GoopSpec's plugin architecture, hook system, and agent definitions are tightly coupled to OpenCode's plugin API.

Observability

Multiple layers:

Layer Mechanism
ADL (Automated Decision Log) goop-adl MCP tool logs every deviation and architectural decision
CHRONICLE.md Journey log updated every wave with progress, decisions, and state
goop_checkpoint Wave-boundary state snapshots with timestamps
goopspec status CLI Current config snapshot (models, memory, MCP)
goopspec verify CLI Health check output for all system components
/goop-status command Runtime workflow state from within OpenCode
RETROSPECTIVE.md Post-milestone analysis with what worked and what didn't
LEARNINGS.md Extracted patterns for future project memory injection

The ADL + CHRONICLE.md combination provides a complete audit trail of all execution decisions, enabling post-hoc review of what the AI did and why, even across multiple sessions.

Related frameworks

same archetype · same primary tool · same memory type

Claude-Flow / Ruflo ★ 55k

Eliminates single-agent context limits and sequential bottlenecks by orchestrating fault-tolerant swarms of specialized AI agents…

Hermes Agent (NousResearch) ★ 168k

Self-improving personal AI agent with closed learning loop, 7 terminal backends, and messaging gateway — not tied to any AI…

OpenCode ★ 165k

Terminal-first AI coding agent with multi-model routing, native desktop app, and a typed .opencode/ configuration system for…

OpenHands ★ 75k

Open-source AI software development platform (open-source Devin alternative) with Docker sandbox isolation, 77.6% SWE-bench…

DeerFlow ★ 70k

Long-horizon superagent that researches, codes, and creates by orchestrating parallel sub-agents with isolated contexts in Docker…

oh-my-openagent (omo) ★ 60k

Multi-provider AI agent orchestration for OpenCode: escape vendor lock-in by routing Sisyphus (Claude/Kimi/GLM) and Hephaestus…