opencode-goopspec 0.1.2 → 0.1.3

package/commands/goop-debug.md

@@ -1,318 +1,40 @@
 ---
 name: goop-debug
-description: Systematic debugging using scientific method - investigate bugs with hypothesis testing
-tools:
-  read: true
-  write: true
-  edit: true
-  bash: true
-  grep: true
-  glob: true
+description: Debug with a systematic workflow
 ---
 
-<objective>
-Systematic debugging using the scientific method.
+# /goop-debug
 
-Investigates bugs through hypothesis testing, manages persistent debug sessions, and handles checkpoints when user input is needed.
+**Systematic debugging.** Solve hard bugs using the scientific method.
 
-**Key principles:**
-- User = Reporter (knows symptoms), Claude = Investigator (finds cause)
-- Hypothesis testing with falsifiable predictions
-- Change one variable at a time
-- Document everything in DEBUG.md
-
-**Creates:**
-- `.goopspec/debug/DEBUG-{id}.md` - Debug session record
-</objective>
-
-<execution_context>
-<!-- Debug template is embedded in the process section above -->
-</execution_context>
-
-<context>
-@.goopspec/PROJECT.md
-@.goopspec/STATE.md
-</context>
-
-<process>
-## Phase 1: Gather Evidence
-
-**Opening questions:**
-
-"Tell me about the bug. What did you expect to happen, and what actually happened?"
-
-Listen for:
-- Expected behavior
-- Actual behavior
-- Error messages
-- When it started
-- Reproduction steps
-- Environment details
-
-**Do NOT ask:**
-- "What's causing it?" (User doesn't know)
-- "Which file has the bug?" (That's your job)
-- "How should we fix it?" (Investigate first)
-
-**DO ask about:**
-- "What were you doing when it happened?"
-- "Does it happen every time?"
-- "When did you first notice it?"
-- "What error messages did you see?"
-
-## Phase 2: Initialize Debug Session
-
-Create debug session file:
+## Usage
 
 ```bash
-DEBUG_ID=$(date +%Y%m%d-%H%M%S)
-mkdir -p .goopspec/debug
+/goop-debug [symptom description]
 ```
 
-Create `.goopspec/debug/DEBUG-$DEBUG_ID.md`:
-
-```markdown
-# Debug Session: $DEBUG_ID
-
-**Started:** [Timestamp]
-**Status:** In Progress
-**Severity:** [Critical/Major/Minor]
-
-## Problem Statement
-
-**Expected:** [What should happen]
-**Actual:** [What actually happens]
-**Impact:** [Who/what is affected]
-
-## Evidence Gathered
-
-### Error Messages
-```
-[Paste error messages]
-```
-
-### Reproduction Steps
-1. [Step 1]
-2. [Step 2]
-3. [Step 3]
-
-### Environment
-- [OS/Version]
-- [Runtime version]
-- [Relevant env vars]
-
-## Investigation Log
-
-### Hypothesis 1: [Brief description]
-**Prediction:** If true, [observable outcome]
-**Test:** [What to do]
-**Result:** [Pending/Confirmed/Refuted]
-**Conclusion:** [What we learned]
-
----
-
-## Current Status
-
-**Active Hypothesis:** [Which one we're testing]
-**Next Step:** [What to do next]
-
-## Resolution
-
-**Root Cause:** [What was actually wrong]
-**Fix Applied:** [What was changed]
-**Verification:** [How we confirmed it's fixed]
-**Committed:** [Commit hash]
-
----
-*Debug session following scientific method*
-```
-
-## Phase 3: Form Hypotheses
-
-Based on evidence, generate 3+ independent hypotheses:
-
-**Good hypotheses (falsifiable):**
-- "User state resets because component remounts on route change"
-- "API returns 404 because URL construction is wrong"
-- "Race condition between async operations"
-
-**Bad hypotheses (unfalsifiable):**
-- "Something is wrong with the state"
-- "The timing is off"
-- "There's a bug somewhere"
-
-For each hypothesis, design an experiment:
-
-```markdown
-### Hypothesis N: [Description]
-**Prediction:** If this hypothesis is true, I will observe [specific outcome]
-**Test:** [Exact steps to test]
-**Measurement:** [What to measure]
-**Success criteria:** [What confirms/refutes]
-```
-
-## Phase 4: Test Hypotheses
-
-**Rule: Change ONE variable at a time**
-
-For each hypothesis:
-1. Run the test
-2. Record the exact outcome
-3. Compare to prediction
-4. Document in DEBUG.md
-
-**If hypothesis confirmed:**
-- Move to Phase 5 (Action)
-- Update DEBUG.md with conclusion
-
-**If hypothesis refuted:**
-- Document what we learned (rules something out)
-- Form new hypothesis based on new information
-- Continue testing
-
-## Phase 5: Take Action
-
-**Only act when ALL are true:**
-1. Understand the mechanism (not just "what fails" but "why")
-2. Can reproduce reliably
-3. Have evidence, not just theory
-4. Ruled out alternatives
-
-**Action types:**
-
-### Fix the bug
-- Make minimal, targeted change
-- Update tests to prevent regression
-- Verify fix works
-- Document in DEBUG.md
-
-### Checkpoint (if blocked)
-If you need user input:
-```
-<task type="checkpoint:decision" gate="blocking">
-  <decision>[What needs deciding]</decision>
-  <context>[Why this matters]</context>
-  <options>[Available options]</options>
-</task>
-```
-
-## Phase 6: Document Resolution
-
-Update DEBUG.md:
-
-```markdown
-## Resolution
-
-**Root Cause:** [Clear explanation]
-**Fix Applied:** [What was changed]
-```diff
-- [Old code]
-+ [New code]
-```
-
-**Verification:** [How confirmed]
-- [ ] Test passes
-- [ ] Manual verification
-- [ ] No regressions
-
-**Committed:** [Hash]
-**Duration:** [How long it took]
-**Status:** RESOLVED
-```
-
-## Phase 7: Offer Next Steps
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-  GOOPSPEC > DEBUG COMPLETE
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-**Bug Resolved**
-
-Root Cause: [Brief description]
-Fix: [What was changed]
-Commit: [Hash]
-
-Debug record: .goopspec/debug/DEBUG-{id}.md
-
-───────────────────────────────────────────────────────────────
-
-## Lessons Learned
-
-[Key insight from this debug session]
-
-───────────────────────────────────────────────────────────────
-
-**Next steps:**
-- Continue with current work
-- /goop-status - Check overall progress
-- /goop-pause - Save checkpoint
-
-───────────────────────────────────────────────────────────────
-```
-</process>
-
-<methodology>
-**Scientific Method Steps:**
-
-1. **Observe precisely**
-   - Not "it's broken" but "counter shows 3 when clicking once, should show 1"
-
-2. **Form falsifiable hypotheses**
-   - Must be provable wrong
-   - Make specific, testable claims
-
-3. **Design experiments**
-   - One variable at a time
-   - Clear prediction
-   - Unambiguous outcome
-
-4. **Run experiments**
-   - Document exact results
-   - No interpretation yet
-
-5. **Conclude based on evidence**
-   - Update mental model
-   - Form new hypotheses if needed
-
-**Cognitive Biases to Avoid:**
-
-| Bias | Trap | Antidote |
-|------|------|----------|
-| Confirmation | Only look for supporting evidence | Actively seek disproof |
-| Anchoring | First explanation becomes anchor | Generate 3+ hypotheses |
-| Availability | Recent bugs -> similar cause | Treat each bug as novel |
-| Sunk Cost | Keep going despite evidence | "If I started fresh...?" |
-
-**When to Restart:**
-- 2+ hours with no progress
-- 3+ "fixes" that didn't work
-- Can't explain current behavior
-- Debugging the debugger
+## How It Works
 
-**Restart protocol:**
-1. Close all files
-2. Write what you know for certain
-3. Write what you've ruled out
-4. List new hypotheses
-5. Begin again
-</methodology>
+Enters a specialized debugging mode that enforces scientific rigor to prevent "flailing."
 
-<checkpoint_types>
-**When to use checkpoints in debugging:**
+### The Protocol
+1. **Observation:** "What exactly is happening?" (Gather evidence).
+2. **Hypothesis:** "Why might this be happening?" (List possible causes).
+3. **Experiment:** "How can we test that?" (Design falsifiable tests).
+4. **Deduction:** "What does the result tell us?" (Eliminate possibilities).
 
-**checkpoint:human-verify**
-- After implementing fix, need user to test
-- Can't reproduce in your environment
-- Needs specific hardware/data
+### Features
+- **Debug Session Log:** Creates `.goopspec/debug/SESSION-<id>.md`.
+- **Constraint:** Forces changing *one variable at a time*.
+- **Memory:** searches for similar past bugs.
 
-**checkpoint:decision**
-- Multiple possible fixes, user must choose
-- Fix has tradeoffs (performance vs simplicity)
-- Requires architectural change
+### Output
+- A resolution report with Root Cause and Fix.
+- Updates persistent memory with the solution to prevent recurrence.
 
-**checkpoint:human-action**
-- Needs user to provide data/credentials
-- Requires access to external system
-- Needs deployment to test environment
-</checkpoint_types>
+## Example
+> **User:** `/goop-debug Login fails with 500 error only on production`
+> **Agent:** "Starting debug session.
+> Hypothesis 1: Env vars missing.
+> Hypothesis 2: Database connection timeout.
+> Let's test Hypothesis 1 first..."

package/commands/goop-discuss.md

@@ -1,138 +1,22 @@
 ---
 name: goop-discuss
-description: Capture user vision before planning - the discovery conversation
+description: Capture user vision before planning
 ---
 
-# GoopSpec Discuss
+# /goop-discuss
 
-Capture user vision and gather requirements through structured conversation before formal planning.
+**Deprecated.** Use `/goop-plan`.
 
 ## Usage
 
+```bash
+/goop-discuss [topic]
 ```
-/goop-discuss [brief description]
-```
-
-## Workflow Position
-
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│   DISCUSS   │ ──▶ │    PLAN     │ ──▶ │  RESEARCH   │
-│  (Vision)   │     │  (Intent)   │     │  (Explore)  │
-└─────────────┘     └─────────────┘     └─────────────┘
-      ↑
-(You are here)
-```
-
-The Discuss phase answers: **What does the user really want?**
-
-## What Happens
-
-1. **Vision Capture** - Understand the high-level goal
-2. **Requirements Gathering** - Ask clarifying questions to understand:
-   - Functional requirements (what it should do)
-   - Non-functional requirements (performance, security, accessibility)
-   - Constraints (time, technology, compatibility)
-   - Success criteria (how to know it's done)
-3. **Scope Definition** - Identify boundaries
-4. **Priority Clarification** - Understand what matters most
-5. **Memory Search** - Check for relevant past context
-
-## Discussion Techniques
-
-**Ask Open-Ended Questions:**
-```
-"Can you walk me through how a user would interact with this?"
-"What happens if [edge case]?"
-"Are there any existing patterns in the codebase we should follow?"
-```
-
-**Validate Understanding:**
-```
-"Let me make sure I understand correctly:
-- The feature should [summary]
-- It needs to handle [edge cases]
-- Success looks like [acceptance criteria]
-
-Is that accurate?"
-```
-
-**Challenge Assumptions:**
-```
-"I notice you mentioned X. Have you considered Y as an alternative? 
-It might be simpler because [reason]."
-```
-
-## What to Gather
 
-### Functional Requirements
-- What should the feature DO?
-- What are the inputs and outputs?
-- What are the edge cases?
-- What happens on errors?
+## Description
 
-### Non-Functional Requirements
-- Performance expectations?
-- Security considerations?
-- Accessibility needs?
-- Compatibility requirements?
+This command is an alias for `/goop-plan`. 
 
-### Context & Constraints
-- Why is this needed? What problem does it solve?
-- What existing code/patterns should be followed?
-- Any technical constraints or limitations?
-- Timeline or priority considerations?
-
-### Acceptance Criteria
-- How will we know it's "done"?
-- What tests should pass?
-- What should the user experience be?
-
-## Artifacts Created
-
-- Understanding of requirements (informal)
-- Identified edge cases
-- Agreement on acceptance criteria
-- Technical research notes (if needed)
-
-## Example
-
-```
-/goop-discuss Add user authentication
-```
-
-Agent asks:
-- "What authentication methods? Email/password? OAuth?"
-- "Should sessions persist across browser closes?"
-- "Any specific security requirements?"
-- "How should errors be displayed?"
-
-After discussion, agent summarizes understanding and asks for confirmation.
-
-## Transition to Plan
-
-When requirements are clear:
-```
-"I have a clear picture of what we need:
-[Summary of requirements]
-
-Ready to move to planning? I'll capture the formal intent 
-and requirements in the Plan phase."
-```
-
-## Next Steps
-
-After discussion:
-- `/goop-plan [description]` - Capture formal intent and requirements
-
-## Tips
-
-- Don't rush to planning - thorough discussion prevents rework
-- Ask about edge cases early
-- Validate understanding frequently
-- Challenge assumptions respectfully
-- Search memory for relevant past context
-
----
+In GoopSpec Wave 3, the "discussion" or "interview" phase is an integral part of **Planning**. When you run `/goop-plan`, the agent automatically engages in a discovery conversation to clarify requirements before generating artifacts.
 
-**GoopSpec**: Understand deeply, build correctly.
+See [/goop-plan](./goop-plan.md) for details.

package/commands/goop-execute.md

@@ -1,137 +1,71 @@
 ---
 name: goop-execute
-description: Start the Execute phase - wave-based implementation
+description: Begin wave-based execution
+agent: goop-executor
+spawn: true
+phase: execute
+next-step: "When all waves are complete, verify the work and request acceptance"
+next-command: /goop-accept
+alternatives:
+  - command: /goop-status
+    when: "To check current progress and wave status"
+  - command: /goop-pause
+    when: "To save a checkpoint and continue later"
 ---
 
-# GoopSpec Execute
+# /goop-execute
 
-Implement the specification through wave-based task execution with orchestrated subagents.
+**Start the Execution Phase.** Implement the blueprint using wave-based orchestration.
 
 ## Usage
 
-```
+```bash
 /goop-execute
 ```
 
-## Workflow Position
-
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│    PLAN     │ ──▶ │  RESEARCH   │ ──▶ │   SPECIFY   │
-│  (Intent)   │     │  (Explore)  │     │ (Contract)  │
-└─────────────┘     └─────────────┘     └─────────────┘
-                                              │
-       ┌──────────────────────────────────────┘
-       ▼
-┌─────────────┐     ┌─────────────┐
-│   EXECUTE   │ ──▶ │   ACCEPT    │
-│   (Build)   │     │  (Verify)   │
-└─────────────┘     └─────────────┘
-       ↑
- (You are here)
-```
-
-The Execute phase answers: **Build exactly what the spec says.**
-
-## What Happens
+## How It Works
 
-1. **Wave-Based Execution** - Tasks grouped into sequential waves:
-   - **Wave 1: Foundation** - Setup, configuration, base structures
-   - **Wave 2: Core** - Main feature, business logic, data handling
-   - **Wave 3: Integration** - Connect components, wire to existing system
-   - **Wave 4: Polish** - Error handling, edge cases, documentation
+The **Orchestrator** takes control and manages the implementation process. It does not write code directly but delegates to the **Executor** agent.
 
-2. **Orchestrator Coordination** - Orchestrator acts as CONDUCTOR:
-   - Delegates tasks to specialized subagents
-   - Tracks progress in CHRONICLE.md
-   - Applies deviation rules automatically
-   - Handles blockers and checkpoints
-   - **NEVER writes code itself**
+### 1. Wave-Based Execution
+Tasks are executed in sequential waves (vertical slices):
+- **Wave 1:** Foundation (Core structure)
+- **Wave 2:** Implementation (Main logic)
+- **Wave 3:** Integration (Wiring it up)
+- **Wave 4:** Polish (Refinement & fixes)
 
-3. **Task Execution** - For each task:
-   - Read from BLUEPRINT.md
-   - Check deviation rules
-   - Delegate to goop-executor agent
-   - Agent implements with memory protocol
-   - Atomic commit per task
-   - Update CHRONICLE.md
-   - Verify tests pass
+### 2. Orchestration Loop
+For each task in `BLUEPRINT.md`:
+1. **Delegate:** Send task to `goop-executor`.
+2. **Monitor:** Watch for completion or blocks.
+3. **Verify:** Run tests/checks.
+4. **Update:** Mark task complete in `CHRONICLE.md`.
 
-4. **Deviation Handling** - Auto-fix without asking:
-   - **Rule 1:** Bugs (type errors, logic errors, crashes)
-   - **Rule 2:** Missing critical functionality (validation, error handling)
-   - **Rule 3:** Blocking issues (missing deps, broken imports)
-   - **Rule 4:** STOP for architectural decisions (new tables, framework changes)
+### 3. Deviation Handling
+The Orchestrator applies rules for issues:
+- **Rule 1-3 (Auto-fix):** Minor bugs, missing imports (fix and continue).
+- **Rule 4 (Architectural):** Major blockers (PAUSE and ask user).
 
-5. **Checkpoint Handling** - Pause for user input when needed:
-   - `checkpoint:verify` - User verifies functionality
-   - `checkpoint:decision` - User makes decision
-   - `checkpoint:action` - User performs action
+### 4. Checkpoints
+If user input is needed, the system pauses and creates a checkpoint.
+- **Decision:** User must choose between options (e.g., architecture trade-off).
+- **Verification:** User must verify something (e.g., UI visual check).
+- **Action:** User must perform an action (e.g., add API key).
 
-## Wave Principles
+## Output
 
-1. **Sequential waves** - Wave N completes before Wave N+1 starts
-2. **Vertical slices** - Each wave delivers working functionality
-3. **Atomic commits** - Each task = one commit
-4. **Verification gates** - Tests must pass between waves
-
-## Artifacts Created/Updated
-
-- `CHRONICLE.md` - Real-time progress tracking:
-  - Current wave and task
-  - Completed tasks with commit hashes
-  - Deviations logged
-  - Blockers noted
-
-- Git commits - One per task:
-  ```
-  feat(wave-task): description
-  
-  - Change 1
-  - Change 2
-  ```
+- **Code:** Modified source files.
+- **Commits:** Atomic commits per task.
+- **Chronicle:** Updated `.goopspec/CHRONICLE.md`.
 
 ## Example
 
-After spec locked for authentication:
-
-```
-/goop-execute
-```
-
-Orchestrator executes:
-- Wave 1: Setup auth directory, install jose library
-- Wave 2: Implement login function, session management
-- Wave 3: Wire to API routes, connect to user model
-- Wave 4: Add error handling, write tests
-
-Each task delegated to goop-executor, committed atomically.
-
-## Continuation Enforcement
-
-The agent **CANNOT stop** with incomplete tasks:
-- Incomplete todos = forced continuation
-- Only checkpoints allow pause
-- User must explicitly confirm completion
-- Max continuation prompts before escalation
-
-## Next Steps
-
-After execution:
-- `/goop-accept` - Verify and accept completion (ACCEPTANCE GATE)
-
-During execution:
-- `/goop-status` - Check progress
-- `/goop-pause` - Save checkpoint manually
-
-## Quick Mode Execution
-
-For Quick tasks:
-- Abbreviated waves (often just 1-2)
-- Faster delegation
-- Less formal tracking
-- Direct to Accept phase
-
----
+> **User:** `/goop-execute`
+> **Agent:** "Starting Wave 1...
+> [Task 1.1] Setup Auth Context... Done (commit: a1b2c3)
+> [Task 1.2] Create Login Component... Done (commit: d4e5f6)
+> Wave 1 Complete. Verification passed. Starting Wave 2..."
 
-**GoopSpec**: Execute with precision, deliver with confidence.
+## Interactive Control
+- Use `/goop-status` to check progress.
+- Use `/goop-pause` to stop safely.