opencode-goopspec 0.1.2 → 0.1.3

package/commands/goop-research.md

@@ -1,98 +1,64 @@
 ---
 name: goop-research
-description: Start the Research phase - explore implementation approaches
+description: Launch research for unknowns or risks
+agent: goop-researcher
+spawn: true
+phase: research
+next-step: "Apply research findings to create or refine the plan"
+next-command: /goop-plan
+alternatives:
+  - command: /goop-research
+    when: "For additional research on related topics"
+  - command: /goop-specify
+    when: "If research confirms the plan is ready to lock"
 ---
 
-# GoopSpec Research
+# /goop-research
 
-Gather context and explore implementation approaches before committing to a specification.
+**Start the Research Phase.** Explore unknowns, compare options, and gather technical context.
 
 ## Usage
 
+```bash
+/goop-research [topic or question]
 ```
-/goop-research
-```
-
-## Workflow Position
-
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│    PLAN     │ ──▶ │  RESEARCH   │ ──▶ │   SPECIFY   │
-│  (Intent)   │     │  (Explore)  │     │ (Contract)  │
-└─────────────┘     └─────────────┘     └─────────────┘
-                          ↑
-                    (You are here)
-```
-
-The Research phase answers: **How should we build this?**
-
-## What Happens
-
-1. **Parallel Agent Spawning** - Multiple agents work simultaneously:
-   - **Researcher** - Deep domain research (technologies, patterns, best practices)
-   - **Explorer** - Codebase analysis (existing patterns, conventions, integration points)
-   - **Librarian** - Documentation gathering (API docs, library guides, examples)
-   - **Designer** - (UI tasks only) Visual research (patterns, components, UX)
 
-2. **Research Areas Covered:**
-   - Technology options and trade-offs
-   - Existing codebase patterns
-   - Domain knowledge and edge cases
-   - Security and performance considerations
-   - Industry standards and best practices
+## How It Works
 
-3. **Consolidation** - Findings merged into RESEARCH.md with:
-   - Technology recommendations
-   - Codebase integration points
-   - Key decisions needed
-   - Risk assessment
-   - Estimated complexity
+Research is an **opt-in** phase used when the path forward isn't clear. It prevents "coding in the dark."
 
-4. **Memory Integration** - Past research and patterns retrieved
+### 1. Scope Definition
+The agent confirms what needs to be learned:
+- Technical feasibility
+- Library/Tool selection
+- Architectural patterns
+- Bug root cause analysis
 
-## Artifacts Created
+### 2. Investigation
+The `goop-researcher` subagent performs:
+- **Web Search:** For latest docs and libraries.
+- **Code Search:** For examples and usage patterns.
+- **Memory Search:** For past learnings.
 
-- `RESEARCH.md` - Consolidated research findings
-- Technology comparison table
-- Recommended approach with rationale
-- Risk catalog
-- Integration points identified
+### 3. Synthesis
+Findings are compiled into a structured report with a clear recommendation.
 
-## Example
+## Output
 
-After planning "Add user authentication":
+- `.goopspec/RESEARCH.md`: Detailed findings and trade-offs.
+- **Memory:** Key learnings are persisted for future recall.
 
-```
-/goop-research
-```
-
-Research agents explore:
-- JWT vs session-based auth
-- Existing auth patterns in codebase
-- Security best practices
-- Library options (jose, jsonwebtoken, etc.)
-- Integration with current user model
-
-## Next Steps
+## Transitions
 
-After research:
-- `/goop-specify` - Lock the specification (CONTRACT GATE)
+- **Next Step:** `/goop-plan` to apply findings to a plan.
+- **Loop:** `/goop-research` can be run multiple times for deep dives.
 
-## Quick Mode Shortcut
+## Examples
 
-For Quick tasks, Research phase is **SKIPPED entirely**:
-- Assumes existing patterns are sufficient
-- No parallel agent spawning
-- Jumps directly from Plan to Execute
-
-## Comprehensive Mode
-
-For Comprehensive tasks:
-- Deeper research per agent
-- More alternatives explored
-- Extended timeframe
-- User reviews RESEARCH.md before Specify
-
----
+**Library Selection:**
+> **User:** `/goop-research best react animation library for minimal bundle size`
+> **Agent:** "I'll compare Framer Motion, React Spring, and a CSS-only approach."
 
-**GoopSpec**: Research thoroughly, decide confidently.
+**Technical Feasibility:**
+> **User:** `/goop-research can we use WebSockets on Vercel serverless?`
+> **Agent:** "Investigating Vercel platform limits and workaround options like Pusher."

package/commands/goop-resume.md

@@ -1,57 +1,36 @@
 ---
 name: goop-resume
-description: Resume from a checkpoint
+description: Resume from a saved checkpoint
 ---
 
-# GoopSpec Resume
+# /goop-resume
 
-Resume your work from a saved checkpoint.
+**Resume from a checkpoint.** Restore context and continue work.
 
 ## Usage
 
-```
+```bash
 /goop-resume [checkpoint-id]
 ```
 
-## What Gets Restored
+## How It Works
 
-When resuming:
-- Session context is restored
-- Current phase is set
-- Active spec is loaded
-- Todos are displayed
-- Modified files list is shown
+Loads a saved state, restores the workflow context, and prepares the agent to continue exactly where it left off.
 
-## Without Checkpoint ID
+### Behavior
+- **No ID:** Resumes the most recent checkpoint.
+- **With ID:** Resumes specific checkpoint (e.g., `/goop-resume cp-123`).
 
-If no checkpoint ID is provided, loads the **most recent** checkpoint.
+### What Happens
+1. **Load State:** Reads the checkpoint JSON.
+2. **Restore Context:** Re-initializes the Orchestrator at the correct phase/wave.
+3. **Status Check:** Runs a quick status check to confirm environment matches.
+4. **Prompt:** Reminds user of the next pending task.
 
 ## Example
 
-```
-/goop-resume
-```
-
-Or specify a specific checkpoint:
-```
-/goop-resume checkpoint-abc123
-```
-
-## Workflow
-
-1. **Load checkpoint data**
-2. **Restore session context**
-3. **Display current todos**
-4. **Show relevant files**
-5. **Ready to continue work**
-
-## See Available Checkpoints
-
-To list all checkpoints:
-```
-Use the goop_checkpoint tool with action: "list"
-```
-
----
-
-**GoopSpec**: Pick up exactly where you left off.
+> **User:** `/goop-resume`
+> **Agent:** "Resuming session from 2 hours ago.
+> Phase: Execute (Wave 2).
+> Next Task: [2.2] Implement handler.
+> Ready to continue?"

package/commands/goop-setup.md

@@ -1,208 +1,299 @@
 ---
 name: goop-setup
-description: First-time GoopSpec setup wizard with model picker
+description: GoopSpec setup wizard - first-time init, configuration, and verification
 ---
 
 # GoopSpec Setup Wizard
 
-You are helping the user set up GoopSpec for the first time. This wizard includes an in-depth model picker for configuring each agent.
+You are helping the user set up or modify their GoopSpec configuration. This wizard handles first-time setup, modifications, and verification.
 
-## Step 1: Detect Current Environment
+## Available Actions
 
-First, call the `goop_setup` tool with `action: "detect"` to see what's already configured:
+| Action | Purpose | When to Use |
+|--------|---------|-------------|
+| `init` | Full first-time initialization | New projects, creates all directories and files |
+| `detect` | Show current environment | Understand what's already configured |
+| `plan` | Preview changes | Before applying, see what will change |
+| `apply` | Write configuration | Apply configuration changes |
+| `verify` | Check setup health | Ensure everything is working |
+| `reset` | Reset to defaults | Start over or fix broken config |
+| `models` | Show model suggestions | Help choosing agent models |
+| `status` | Show current config | Quick overview of current state |
+
+## First-Time Setup Flow
+
+For users who haven't set up GoopSpec yet, use the `init` action.
+
+### Step 1: Detect Current State
 
 ```
 goop_setup(action: "detect")
 ```
 
-Review the output and share a brief summary with the user about their current state.
+Review what's already configured. If nothing exists, proceed to full init.
+
+### Step 2: Ask for Project Name
+
+Ask the user: "What's your project name?"
 
-## Step 2: Configuration Scope
+This will be stored in the configuration for context.
+
+### Step 3: Configuration Scope
 
 Ask: "Where should GoopSpec be configured?"
 
-Use the question tool to present these options:
+Use the question tool:
 - **both** (Recommended) - Both global and project-specific settings
-- **global** - Only system-wide settings (~/.config/opencode/goopspec.json)
-- **project** - Only this project (.goopspec/config.json)
+- **global** - Only system-wide settings
+- **project** - Only this project
 
-## Step 3: MCP Preset
+### Step 4: MCP Preset
 
 Ask: "Which MCPs should be installed?"
 
-Use the question tool to present these options:
-- **recommended** - Context7 + Exa + Playwright (full GoopSpec workflow support)
-- **core** - Context7 + Exa only (minimal setup)
+- **recommended** - Context7 + Exa + Playwright (full workflow support)
+- **core** - Context7 + Exa only (minimal)
 - **none** - Skip MCP installation
 
-## Step 4: Default Agent
+### Step 5: Memory System
 
-Ask: "Should GoopSpec be set as your default agent?"
+Ask: "Would you like to enable the memory system?"
 
-Use the question tool:
-- **yes** - GoopSpec orchestrator will be the default for new sessions
-- **no** - Keep current default agent
+The memory system allows GoopSpec to remember decisions, patterns, and context across sessions.
 
-## Step 5: Model Configuration
+If yes, ask about embedding provider:
+- **local** (Recommended) - Uses local embeddings, no API needed
+- **openai** - Uses OpenAI embeddings (requires API key)
+- **ollama** - Uses local Ollama server
 
-This is the key step. Ask: "Would you like to configure models for each agent?"
+### Step 6: Model Configuration
 
-Use the question tool:
-- **Quick setup** - Use recommended defaults for all agents
-- **Custom setup** - Choose models for each agent individually
-
-### If Quick Setup
-Use the defaults from agent files (user can change later):
-- goop-debugger: openai/gpt-5.2-codex
-- goop-designer: anthropic/claude-opus-4-5
-- goop-executor: openai/gpt-5.2-codex
-- goop-explorer: google/antigravity-gemini-3-flash
-- goop-librarian: openai/gpt-5.2
-- goop-orchestrator: anthropic/claude-opus-4-5
-- goop-planner: anthropic/claude-opus-4-5
-- goop-researcher: openai/gpt-5.2
-- goop-tester: opencode/kimi-k2.5-free
-- goop-verifier: openai/gpt-5.2-codex
-- goop-writer: google/antigravity-gemini-3-pro-high
-
-### If Custom Setup
-For EACH agent, present a model picker using the question tool. Include a "Custom model" option that allows free text entry.
-
-#### Agent Model Options
-
-**goop-debugger** (Systematic debugging with hypothesis testing):
+Ask: "Would you like to configure models for each agent?"
+
+- **Quick setup** - Use recommended defaults
+- **Custom setup** - Choose models individually
+
+For custom setup, walk through each agent or accept shortcuts like "use Claude Sonnet for everything".
+
+### Step 7: Apply Init
+
+Execute the initialization:
+
+```
+goop_setup(
+  action: "init",
+  scope: "<scope>",
+  projectName: "<name>",
+  mcpPreset: "<preset>",
+  memoryEnabled: true,
+  memoryProvider: "local",
+  agentModels: { ... }
+)
+```
+
+### Step 8: Verify Setup
+
+After init completes, verify everything is working:
+
+```
+goop_setup(action: "verify")
+```
+
+Report any issues and suggest fixes.
+
+## Modifying Existing Setup
+
+For users who already have GoopSpec configured:
+
+### Check Current Status
+
+```
+goop_setup(action: "status")
+```
+
+Shows what's currently configured.
+
+### Update Configuration
+
+```
+goop_setup(
+  action: "apply",
+  scope: "project",
+  // Only include what you want to change
+  memoryEnabled: true,
+  agentModels: {
+    "goop-executor": "anthropic/claude-sonnet-4-5"
+  }
+)
+```
+
+### Reset Configuration
+
+If something is broken:
+
+```
+goop_setup(
+  action: "reset",
+  scope: "project",
+  preserveData: true,  // Keep memories, history, checkpoints
+  confirmed: true
+)
+```
+
+## Agent Model Options
+
+### goop-debugger
+*Systematic debugging with hypothesis testing*
 1. openai/gpt-5.2-codex
 2. anthropic/claude-opus-4-5
 3. opencode/kimi-k2.5-free
-- Custom model...
 
-**goop-designer** (Visual design planning and UI/UX reasoning):
+### goop-designer
+*Visual design planning and UI/UX reasoning*
 1. anthropic/claude-opus-4-5
 2. opencode/kimi-k2.5-free
 3. google/antigravity-gemini-3-pro-high
-- Custom model...
 
-**goop-executor** (Task execution with checkpoints and verification):
+### goop-executor
+*Task execution with checkpoints and verification*
 1. openai/gpt-5.2-codex
 2. anthropic/claude-opus-4-5
 3. anthropic/claude-sonnet-4-5
 4. opencode/kimi-k2.5-free
 5. google/antigravity-gemini-3-pro-high
 6. opencode/glm-4.7-free
-- Custom model...
 
-**goop-explorer** (Fast codebase exploration and pattern extraction):
+### goop-explorer
+*Fast codebase exploration and pattern extraction*
 1. google/antigravity-gemini-3-flash
 2. anthropic/claude-haiku-4-5
 3. opencode/minimax-m2.1-free
-- Custom model...
 
-**goop-librarian** (Codebase search and documentation retrieval):
+### goop-librarian
+*Codebase search and documentation retrieval*
 1. openai/gpt-5.2
 2. google/antigravity-gemini-3-flash
 3. anthropic/claude-sonnet-4-5
-- Custom model...
 
-**goop-orchestrator** (Primary orchestrator - spec clarity and wave execution):
+### goop-orchestrator
+*Primary orchestrator - spec clarity and wave execution*
 1. anthropic/claude-opus-4-5
 2. openai/gpt-5.2-codex
 3. opencode/kimi-k2.5-free
 4. anthropic/claude-sonnet-4-5
-- Custom model...
 
-**goop-planner** (Detailed execution plans with architectural precision):
+### goop-planner
+*Detailed execution plans with architectural precision*
 1. anthropic/claude-opus-4-5
 2. openai/gpt-5.2-codex
 3. opencode/kimi-k2.5-free
 4. anthropic/claude-sonnet-4-5
-- Custom model...
 
-**goop-researcher** (Comprehensive ecosystem research):
+### goop-researcher
+*Comprehensive ecosystem research*
 1. openai/gpt-5.2
 2. anthropic/claude-sonnet-4-5
 3. opencode/kimi-k2.5-free
 4. opencode/glm-4.7-free
-- Custom model...
 
-**goop-tester** (Web frontend testing with Playwright):
+### goop-tester
+*Web frontend testing with Playwright*
 1. opencode/kimi-k2.5-free
 2. anthropic/claude-sonnet-4-5
 3. google/antigravity-gemini-3-flash
-- Custom model...
 
-**goop-verifier** (Post-execution verification with security focus):
+### goop-verifier
+*Post-execution verification with security focus*
 1. openai/gpt-5.2-codex
 2. anthropic/claude-opus-4-5
-- Custom model...
 
-**goop-writer** (Comprehensive documentation generation):
+### goop-writer
+*Comprehensive documentation generation*
 1. google/antigravity-gemini-3-pro-high
 2. opencode/kimi-k2.5-free
 3. anthropic/claude-sonnet-4-5
-- Custom model...
 
-## Step 6: Preview the Plan
+## Memory System Configuration
 
-After collecting all answers, call `goop_setup` with `action: "plan"` and the user's choices:
+The memory system allows GoopSpec to:
+- Remember decisions and their reasoning
+- Recall patterns from past work
+- Build context across sessions
 
-```
-goop_setup(
-  action: "plan",
-  scope: "<user_choice>",
-  mcpPreset: "<user_choice>",
-  enableOrchestrator: <true/false>,
-  agentModels: {
-    "goop-orchestrator": "<model>",
-    "goop-planner": "<model>",
-    "goop-executor": "<model>",
-    // ... other agents
-  }
-)
-```
+### Configuration Options
 
-Show the user a summary including:
-- Configuration scope
-- MCPs to install
-- Agent model assignments (in a table format)
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `memoryEnabled` | boolean | true | Enable/disable memory |
+| `memoryProvider` | string | "local" | Embedding provider |
+| `memoryWorkerPort` | number | 37777 | Worker process port |
 
-Ask for confirmation before proceeding.
+### Embedding Providers
 
-## Step 7: Apply Configuration
+- **local** - Uses `Xenova/all-MiniLM-L6-v2`, runs locally, free
+- **openai** - Uses OpenAI's embedding API, requires API key
+- **ollama** - Uses local Ollama server
 
-If the user confirms, call `goop_setup` with `action: "apply"` and the same parameters.
+## Troubleshooting
 
-## Step 8: Verify and Complete
+### "Memory worker not responding"
 
-After applying, summarize what was done:
-- List all agents and their assigned models
-- List MCPs installed
-- Show any warnings or notes
+1. Check if port 37777 is in use: `lsof -i :37777`
+2. Try a different port: `memoryWorkerPort: 37778`
+3. Check memory directory exists: `.goopspec/memory/`
 
-Suggest next steps:
-- Run `/goop-status` to verify configuration
-- Start a new conversation to use GoopSpec
-- Try `/goop-discuss` to start your first spec-driven project
+### "Configuration not loading"
 
-## Tips for the Model Picker
+1. Run `goop_setup(action: "verify")` to diagnose
+2. Check for JSON syntax errors in config files
+3. Try `goop_setup(action: "reset", scope: "project", confirmed: true)`
 
-1. **Be conversational** - Don't just list options, explain the trade-offs
-2. **Group similar agents** - You can ask about related agents together (e.g., "orchestrator + planner" or "explorer + librarian")
-3. **Explain costs** - Opus models are more capable but expensive; free models (opencode/*) are great for budget-conscious users
-4. **Allow skipping** - If a user says "use defaults for the rest", accept that
-5. **Support bulk selection** - If a user says "use Claude Sonnet for everything", honor that
+### "MCPs not installing"
 
-## Available Models
+MCPs require OpenCode configuration. Check:
+1. OpenCode is installed and configured
+2. You have write permissions to ~/.config/opencode/
 
-All models listed in the suggestions:
-- openai/gpt-5.2-codex
-- openai/gpt-5.2
-- anthropic/claude-opus-4-5
-- anthropic/claude-sonnet-4-5
-- anthropic/claude-haiku-4-5
-- google/antigravity-gemini-3-pro-high
-- google/antigravity-gemini-3-flash
-- opencode/kimi-k2.5-free
-- opencode/glm-4.7-free
-- opencode/minimax-m2.1-free
+## Tips
 
-Users can also enter any custom model name supported by their OpenCode installation.
+1. **Start with detect** - Always check what's already configured
+2. **Use verify after changes** - Ensures everything works
+3. **Preserve data on reset** - Don't lose memories unless needed
+4. **Quick setup is fine** - Model defaults work well for most users
+5. **Local memory is best** - No API costs, runs offline
+
+## Complete Example
+
+First-time setup:
+
+```
+// 1. Check current state
+goop_setup(action: "detect")
+
+// 2. Initialize everything
+goop_setup(
+  action: "init",
+  scope: "both",
+  projectName: "my-project",
+  mcpPreset: "recommended",
+  memoryEnabled: true,
+  memoryProvider: "local",
+  enableOrchestrator: true
+)
+
+// 3. Verify
+goop_setup(action: "verify")
+```
+
+Modify existing:
+
+```
+// Update just the executor model
+goop_setup(
+  action: "apply",
+  scope: "project",
+  agentModels: {
+    "goop-executor": "anthropic/claude-opus-4-5"
+  }
+)
+```