opencode-goopspec 0.1.0

package/references/dispatch-patterns.md

@@ -0,0 +1,176 @@
+# Agent Dispatch Patterns
+
+GoopSpec supports multiple patterns for spawning and coordinating specialized agents. Choose the right pattern based on task characteristics.
+
+## Dispatch Modes
+
+### Sequential Dispatch
+
+**When:** Tasks have strict dependencies, order matters.
+
+**Pattern:**
+```
+Task A → Complete → Task B → Complete → Task C
+```
+
+**Use for:**
+- Database migrations before schema-dependent code
+- Build before deploy
+- Test before commit
+- Setup before configuration
+
+**Example:**
+```json
+{
+  "mode": "sequential",
+  "agents": [
+    { "agent": "planner", "task": "Create migration plan" },
+    { "agent": "executor", "task": "Run migrations" },
+    { "agent": "verifier", "task": "Verify schema" }
+  ]
+}
+```
+
+### Parallel Dispatch
+
+**When:** Tasks are independent, can run concurrently.
+
+**Pattern:**
+```
+       ┌─ Task A ─┐
+Start ─┼─ Task B ─┼─ Merge
+       └─ Task C ─┘
+```
+
+**Use for:**
+- Independent feature implementations
+- Multiple test suites
+- Documentation + implementation
+- Research across different domains
+
+**Example:**
+```json
+{
+  "mode": "parallel",
+  "max_concurrent": 3,
+  "agents": [
+    { "agent": "executor", "task": "Implement auth module" },
+    { "agent": "executor", "task": "Implement user module" },
+    { "agent": "tester", "task": "Write integration tests" }
+  ]
+}
+```
+
+### Background Dispatch
+
+**When:** Long-running tasks that shouldn't block main flow.
+
+**Pattern:**
+```
+Main Flow ───────────────────────────────►
+              ↓
+         Background Task ──────► Notify on complete
+```
+
+**Use for:**
+- Research tasks
+- Large test suites
+- Documentation generation
+- Code analysis
+
+**Example:**
+```json
+{
+  "mode": "background",
+  "agent": "researcher",
+  "task": "Research authentication best practices",
+  "notify_on_complete": true
+}
+```
+
+## Agent Selection
+
+### By Task Type
+
+| Task Type | Primary Agent | Fallback |
+|-----------|--------------|----------|
+| Planning | goop-planner | goop-orchestrator |
+| Implementation | goop-executor | goop-orchestrator |
+| Verification | goop-verifier | goop-tester |
+| Research | goop-researcher | goop-explorer |
+| Documentation | goop-writer | goop-orchestrator |
+| Debugging | goop-debugger | goop-executor |
+| UI/UX | goop-designer | goop-executor |
+| Testing | goop-tester | goop-verifier |
+
+### By Complexity
+
+| Complexity | Model Profile | Context Budget |
+|------------|--------------|----------------|
+| Simple | budget | 40% |
+| Standard | balanced | 60% |
+| Complex | quality | 80% |
+| Critical | quality + thinking | 90% |
+
+## Wave Execution
+
+Plans are grouped into waves for efficient parallel execution:
+
+```
+Wave 1: Foundation (sequential dependencies)
+  ├─ Plan A (infrastructure)
+  └─ Plan B (database setup)
+
+Wave 2: Features (parallel, depends on Wave 1)
+  ├─ Plan C (auth feature)
+  ├─ Plan D (user feature)
+  └─ Plan E (API feature)
+
+Wave 3: Integration (depends on Wave 2)
+  └─ Plan F (integration tests)
+```
+
+### Wave Metadata
+
+Each plan specifies its wave in frontmatter:
+```yaml
+---
+wave: 2
+depends_on: [plan-a, plan-b]
+autonomous: true
+---
+```
+
+## Fresh Context Strategy
+
+**When to spawn fresh agents:**
+1. Context usage exceeds 70%
+2. Switching to different task domain
+3. Starting a new phase
+4. After checkpoint restoration
+
+**Context handoff:**
+- Pass essential state (phase, spec, todos)
+- Include recent ADL decisions
+- Summarize previous progress
+- Exclude verbose logs
+
+## Error Handling
+
+### On Agent Failure
+
+1. Log failure to state
+2. Save checkpoint
+3. Attempt recovery:
+   - Retry with fresh context
+   - Fallback to different agent
+   - Escalate to user
+
+### On Timeout
+
+1. Check for partial progress
+2. Save checkpoint with partial state
+3. Notify user with options:
+   - Resume from checkpoint
+   - Retry task
+   - Skip and continue

package/references/model-profiles.md

@@ -0,0 +1,109 @@
+# Model Profiles
+
+Model profiles control which model each GoopSpec agent uses. This enables optimal performance by matching cognitive tasks to the best-suited models.
+
+## Default Model Assignments
+
+| Agent | Model | Rationale |
+|-------|-------|-----------|
+| goop-debugger | openai/gpt-5.2-codex | Best for code-heavy debugging, hypothesis testing, evidence-based analysis |
+| goop-designer | anthropic/claude-opus-4-5 | Best for visual design, UI/UX reasoning, component architecture decisions |
+| goop-executor | openai/gpt-5.2-codex | Best for code implementation, atomic commits, clean patterns |
+| goop-explorer | google/antigravity-gemini-3-flash | Fast codebase mapping, pattern detection, lightweight exploration |
+| goop-librarian | openai/gpt-5.2 | Best for information retrieval, documentation search, code search |
+| goop-orchestrator | anthropic/claude-opus-4-5 | Complex orchestration, task delegation, context management |
+| goop-planner | anthropic/claude-opus-4-5 | Best for complex architecture decisions, goal decomposition, reasoning-heavy planning |
+| goop-researcher | openai/gpt-5.2 | Best for research, technology evaluation, knowledge synthesis |
+| goop-tester | opencode/kimi-k2.5-free | Cost-effective for test writing, quality assurance, coverage thinking |
+| goop-verifier | openai/gpt-5.2-codex | Best for code verification, security analysis, catching subtle bugs |
+| goop-writer | google/antigravity-gemini-3-pro-high | Documentation, structured writing, comprehensive coverage |
+| memory-distiller | anthropic/claude-haiku-3-5 | Fast, lightweight distillation of events into structured memories |
+
+## Model Selection Philosophy
+
+### Why GPT-5.2-Codex for Code Tasks?
+Code-heavy tasks (debugging, execution, verification) benefit from Codex's specialized training. GPT-5.2-Codex excels at:
+- Deep code understanding and generation
+- Bug detection and hypothesis testing
+- Security vulnerability analysis
+- Clean, production-quality implementation
+- Following coding patterns and conventions
+
+### Why Claude Opus 4.5 for Planning & Orchestration?
+Planning and orchestration require complex reasoning and decision-making. Opus 4.5 excels at:
+- Complex reasoning about system design
+- Identifying genuine dependencies vs false ones
+- Creating comprehensive, executable plans
+- Goal-backward verification derivation
+- Task delegation and context management
+- Visual/UI reasoning and component architecture
+
+### Why GPT-5.2 for Research & Information Retrieval?
+Research and information tasks benefit from GPT-5.2's broad knowledge and retrieval capabilities:
+- Deep domain research and synthesis
+- Technology evaluation and comparison
+- Documentation and code search
+- Information extraction and organization
+- Knowledge synthesis across sources
+
+### Why Gemini 3 Flash for Lightweight Tasks?
+Fast, lightweight tasks benefit from Gemini 3 Flash's speed and efficiency:
+- Fast codebase scanning and mapping
+- Quick pattern extraction
+- Status checks and session management
+- Low cost for frequent operations
+- Excellent speed-to-quality ratio
+
+### Why Gemini 3 Pro High for Writing?
+Documentation and writing tasks benefit from Gemini 3 Pro High's comprehensive coverage:
+- Structured documentation generation
+- Technical writing with clarity
+- Comprehensive coverage of topics
+- Memory persistence and note-taking
+- Milestone completion summaries
+
+### Why Kimi K2.5 Free for Testing?
+Testing tasks can use cost-effective models while maintaining quality:
+- Test writing and quality assurance
+- Coverage thinking and edge cases
+- Cost-effective for frequent test generation
+- Good enough quality for test scenarios
+
+## Override Configuration
+
+Users can override models for specific scenarios in goopspec.json:
+
+```json
+{
+  "models": {
+    "planner": "anthropic/claude-opus-4-5",
+    "executor": "openai/gpt-5.2-codex",
+    "overrides": {
+      "security_review": "openai/gpt-5.2-codex",
+      "performance_audit": "openai/gpt-5.2-codex",
+      "refactor": "openai/gpt-5.2-codex",
+      "quick_fix": "openai/gpt-5.2-codex",
+      "research": "openai/gpt-5.2",
+      "documentation": "google/antigravity-gemini-3-pro-high"
+    }
+  }
+}
+```
+
+## Resolution Logic
+
+1. Check for scenario override (security_review, quick_fix, etc.)
+2. If override exists, use that model
+3. Otherwise, use default agent model
+4. Pass model parameter to Task tool when spawning
+
+## Cost vs Quality Trade-offs
+
+| Scenario | Recommended Model | Reason |
+|----------|-------------------|--------|
+| Budget constrained | Use Gemini 3 Flash for exploration, Kimi K2.5 Free for testing | Lowest cost while maintaining quality |
+| Maximum quality | Use GPT-5.2-Codex for code, Opus 4.5 for planning | Best performance per task type |
+| Balanced (default) | As per default assignments | Smart allocation per task type |
+| Security critical | Use GPT-5.2-Codex for verification | Strong security analysis capabilities |
+| Research intensive | Use GPT-5.2 for research and information retrieval | Best for knowledge synthesis |
+| Documentation heavy | Use Gemini 3 Pro High for writing | Comprehensive coverage and clarity |

package/references/orchestrator-philosophy.md

@@ -0,0 +1,280 @@
+# The Orchestrator Philosophy
+
+The orchestrator is a **CONDUCTOR** - it coordinates the orchestra but never plays an instrument.
+
+## Core Principle
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║  THE ORCHESTRATOR NEVER WRITES CODE.                           ║
+║  It coordinates, delegates, tracks, and decides.               ║
+║  All implementation happens in subagent contexts.              ║
+╚════════════════════════════════════════════════════════════════╝
+```
+
+## Why This Matters
+
+### The Context Problem
+
+The orchestrator's context window is PRECIOUS:
+- ~200k tokens total
+- Every line of code consumes context
+- Code details cause "context rot"
+- Orchestration quality degrades as context fills
+
+### The Solution: Subagent Contexts
+
+Each delegated task runs in a FRESH context:
+- Subagents get full 200k for their task
+- Implementation details stay contained
+- Orchestrator context stays clean
+- Consistent coordination quality throughout
+
+### The Orchestra Metaphor
+
+A conductor:
+- Reads the score (specification)
+- Directs each section (delegates to agents)
+- Listens for harmony (verifies outcomes)
+- Adjusts tempo (manages flow)
+- NEVER picks up a violin
+
+## Hard Rules
+
+### NEVER Do
+
+| Action | Why |
+|--------|-----|
+| Use Edit tool on code files | That's executor's job |
+| Use Write tool for implementation | Delegate instead |
+| "Quickly fix" something | Creates context debt |
+| Write code in responses | Use delegation |
+| Say "let me just..." and implement | Always delegate |
+| Inline "small" changes | No change is small enough |
+
+### ALWAYS Do
+
+| Action | Why |
+|--------|-----|
+| Delegate ALL code work | Keeps context clean |
+| Track in CHRONICLE.md | Maintains state |
+| Use memory tools | Persists decisions |
+| Spawn fresh agents | Fresh context per task |
+| Coordinate through files | Async communication |
+| Verify outcomes, not process | Trust but verify |
+
+## Permitted Actions
+
+The orchestrator CAN directly:
+
+### Read Operations
+- Read SPEC.md, BLUEPRINT.md, CHRONICLE.md
+- Search codebase (exploration)
+- Check file existence
+- Read configuration
+- Search memory
+
+### Coordination Operations
+- Create/update SPEC.md
+- Create/update BLUEPRINT.md
+- Update CHRONICLE.md status
+- Write to memory
+- Delegate to agents
+- Track todos
+
+### Decision Operations
+- Apply deviation rules
+- Route tasks to agents
+- Determine phase transitions
+- Present gates to user
+
+## Delegation Protocol
+
+### When to Delegate
+
+```
+IF task involves writing/modifying code
+   → DELEGATE to appropriate agent
+
+IF task involves implementation decisions
+   → DELEGATE to planner or researcher
+
+IF task is purely coordination/tracking
+   → HANDLE directly
+```
+
+### How to Delegate
+
+```
+task({
+  subagent_type: "general",
+  description: "Execute task",
+  prompt: `
+    ## TASK
+    [Clear, single task]
+    
+    ## CONTEXT
+    - SPEC: .goopspec/SPEC.md
+    - Task: Wave 2, Task 3
+    
+    ## FILES
+    - src/auth/login.ts (modify)
+    - src/auth/session.ts (create)
+    
+    ## REQUIREMENTS
+    [Explicit requirements from spec]
+    
+    ## CONSTRAINTS
+    [Technical constraints]
+    
+    ## ACCEPTANCE
+    [How to verify completion]
+  `
+})
+```
+
+### Delegation Categories
+
+| Category | Agent | Use When |
+|----------|-------|----------|
+| `code` | goop-executor | Implementation tasks |
+| `plan` | goop-planner | Architecture, wave design |
+| `research` | goop-researcher | Deep domain exploration |
+| `explore` | goop-explorer | Codebase mapping |
+| `search` | goop-librarian | Documentation lookup |
+| `verify` | goop-verifier | Spec compliance checking |
+| `debug` | goop-debugger | Bug investigation |
+| `visual` | goop-designer | UI/UX work |
+| `test` | goop-tester | Test writing |
+| `docs` | goop-writer | Documentation |
+
+## Context Management
+
+### Signs of Context Rot
+
+- Orchestrator starts "helping" with code
+- Responses include implementation details
+- Coordination quality decreasing
+- Forgetting earlier decisions
+- Contradicting previous statements
+
+### Prevention
+
+1. **Strict delegation** - Never write code
+2. **Minimal responses** - Coordination only
+3. **File-based state** - CHRONICLE.md for tracking
+4. **Memory usage** - Persist decisions, don't repeat
+5. **Fresh agents** - New context for new tasks
+
+### Recovery
+
+If context becomes polluted:
+1. Save state to CHRONICLE.md
+2. Save key decisions to memory
+3. Start fresh orchestrator session
+4. Load state from files + memory
+
+## Orchestrator Mental Model
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   ORCHESTRATOR                       │
+│                                                     │
+│  ┌─────────┐  ┌─────────┐  ┌─────────┐            │
+│  │ SPEC.md │  │BLUEPRINT│  │CHRONICLE│            │
+│  │ (What)  │  │ (How)   │  │ (State) │            │
+│  └────┬────┘  └────┬────┘  └────┬────┘            │
+│       │            │            │                  │
+│       └────────────┼────────────┘                  │
+│                    │                               │
+│              ┌─────▼─────┐                         │
+│              │ DECISIONS │                         │
+│              └─────┬─────┘                         │
+│                    │                               │
+│    ┌───────────────┼───────────────┐              │
+│    ▼               ▼               ▼              │
+│ delegate()    delegate()      delegate()          │
+│    │               │               │              │
+└────┼───────────────┼───────────────┼──────────────┘
+     ▼               ▼               ▼
+┌─────────┐    ┌─────────┐    ┌─────────┐
+│Executor │    │Researcher│    │Verifier │
+│ (Code)  │    │ (Learn)  │    │ (Check) │
+└─────────┘    └─────────┘    └─────────┘
+```
+
+## Common Mistakes
+
+### Mistake 1: "Quick Fix"
+
+```
+❌ WRONG:
+"Let me just fix that typo in the config..."
+[Uses Edit tool]
+
+✓ RIGHT:
+"I'll delegate this fix to the executor."
+[Uses delegate()]
+```
+
+### Mistake 2: "Showing Code"
+
+```
+❌ WRONG:
+"Here's how the auth should look:
+```typescript
+export async function login() { ... }
+```"
+
+✓ RIGHT:
+"The executor will implement login following the spec.
+See SPEC.md for requirements."
+```
+
+### Mistake 3: "Helping Implementation"
+
+```
+❌ WRONG:
+"The executor returned the code. Let me review and adjust..."
+[Makes inline edits]
+
+✓ RIGHT:
+"Executor completed the task. Running verification.
+If issues: delegate fixes back to executor."
+```
+
+## Trust the Orchestra
+
+The orchestrator's power comes from:
+- Clear specifications (the score)
+- Quality delegation (clear instructions)
+- Proper verification (listening to the result)
+- Memory persistence (institutional knowledge)
+
+NOT from:
+- Doing the work itself
+- Micromanaging implementation
+- Having "all the context"
+- Being "helpful" with code
+
+## Summary
+
+```
+ORCHESTRATOR = CONDUCTOR
+
+Does:
+- Coordinate
+- Delegate  
+- Track
+- Decide
+
+Does NOT:
+- Code
+- Implement
+- "Help"
+- "Fix"
+
+Context is precious.
+Keep it clean.
+Trust your agents.
+```