opencode-goopspec 0.1.2 → 0.1.3

package/README.md

@@ -1,4 +1,4 @@
-# GoopSpec v0.1.2
+# GoopSpec v0.1.3
 
 <div align="center">
 
@@ -6,7 +6,7 @@
 
 *The Orchestrator that turns vague ideas into shipped software*
 
-[![Version](https://img.shields.io/badge/version-0.1.2-blue.svg)](https://github.com/hffmnnj/opencode-goopspec)
+[![Version](https://img.shields.io/badge/version-0.1.3-blue.svg)](https://github.com/hffmnnj/opencode-goopspec)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
 [![Tests](https://img.shields.io/badge/tests-936%20passing-green.svg)](./TEST-SUMMARY.md)
 [![License](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
@@ -21,73 +21,75 @@ GoopSpec is a plugin for [OpenCode](https://opencode.ai) that transforms how you
 
 **The Problem:** AI assistants are powerful but unpredictable. They start coding before understanding requirements, miss edge cases, forget context, and deliver work that doesn't match what you actually wanted.
 
-**The Solution:** GoopSpec introduces **contracts**, **phases**, and **verification gates** that ensure the AI understands what you want before it writes a single line of code.
+**The Solution:** GoopSpec introduces **interactive questioning**, **contracts**, and **verification gates** that ensure the AI understands what you want before it writes a single line of code.
 
 ```
-Your Idea → Plan → Research → Specify (CONTRACT) → Execute → Accept (VERIFY)
+Your Idea → Interactive Plan → Research (Opt-in) → Specify → Execute → Accept
 ```
 
 ---
 
 ## Core Philosophy
 
+### "Ask, Don't Assume"
+GoopSpec is interactive by default. It interviews you to uncover hidden requirements and ambiguities. If something is unclear, it asks clarifying questions rather than guessing.
+
 ### "Spec as Contract"
 The specification is a binding agreement. Once locked, both you and the AI know exactly what will be delivered. No scope creep. No surprises.
 
-### "Orchestrator as Conductor"
-The GoopSpec Orchestrator never writes code itself. It coordinates specialized sub-agents, maintains clean context, and ensures quality. Like a conductor leading an orchestra - directing, not playing.
-
 ### "Memory-First"
 Every agent searches memory before starting work, saves decisions during work, and persists learnings after. GoopSpec gets smarter with every project you complete.
 
+### "Unified Experience"
+A consistent, rich terminal UI (powered by Clack) keeps you informed with clear status indicators, spinners for long tasks, and human-friendly prompts.
+
 ### "Scale to the Task"
-Quick bug fix? Use Quick Mode. Major feature? Use Standard Mode. Full system overhaul? Use Comprehensive Mode. GoopSpec adapts to your task size.
+Quick bug fix? GoopSpec routes to a lightweight path. Major feature? Full 5-phase workflow. The system detects task complexity and adapts.
 
 ---
 
-## The 5-Phase Workflow
+## The Workflow
 
 ```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│    PLAN     │ ──▶ │  RESEARCH   │ ──▶ │   SPECIFY   │
-│  (Intent)   │     │  (Explore)  │     │ (CONTRACT)  │
-└─────────────┘     └─────────────┘     └─────────────┘
-                                              │
-       ┌──────────────────────────────────────┘
-       ▼
 ┌─────────────┐     ┌─────────────┐
-│   EXECUTE   │ ──▶ │   ACCEPT    │
-│   (Build)   │     │  (VERIFY)   │
+│    PLAN     │ ◀──▶ │  RESEARCH   │
+│ (Interview) │     │  (Opt-in)   │
 └─────────────┘     └─────────────┘
+       │
+       ▼
+┌─────────────┐     ┌─────────────┐
+│   SPECIFY   │ ──▶ │   EXECUTE   │ ──▶ │   ACCEPT    │
+│ (Contract)  │     │   (Build)   │     │  (Verify)   │
+└─────────────┘     └─────────────┘     └─────────────┘
 ```
 
-### Phase 1: Plan
-Capture your intent. What do you want to build and why? GoopSpec asks clarifying questions, identifies requirements, and ensures nothing is ambiguous before moving forward.
+### Phase 1: Plan (Interactive)
+Capture your intent. GoopSpec acts as a product manager, conducting an interview to:
+- Clarify ambiguous requirements
+- Identify edge cases
+- Suggest technical approaches
+- confirm the "Definition of Done"
 
-### Phase 2: Research
-Multiple agents explore in parallel:
-- **Researcher** - Deep domain knowledge, technology options, best practices
-- **Explorer** - Existing codebase patterns, conventions, integration points
-- **Librarian** - Documentation, API references, code examples
+### Phase 2: Research (Opt-in)
+Triggered only when needed or requested. Specialized agents explore:
+- **Researcher** - Deep domain knowledge & options
+- **Explorer** - Existing codebase patterns
+- **Librarian** - Documentation & APIs
 
 ### Phase 3: Specify (CONTRACT GATE)
-Lock the specification. This is the contract between you and the AI:
-- **Must-Haves** - Non-negotiable requirements (guaranteed delivery)
-- **Nice-to-Haves** - Best effort if time permits
-- **Out of Scope** - Explicitly excluded items
-
-**You must confirm before execution begins.**
+Lock the specification. This is the contract:
+- **Must-Haves** - Non-negotiable requirements
+- **Out of Scope** - Explicit exclusions
+- **You must confirm before execution begins.**
 
 ### Phase 4: Execute
 Wave-based implementation with atomic commits:
 - Tasks grouped into sequential waves
-- Each task = one commit
-- Progress tracked in real-time
+- Real-time progress tracking via Unified UI
 - Checkpoints for pausing/resuming
 
 ### Phase 5: Accept (ACCEPTANCE GATE)
 Verify the implementation:
-- All must-haves checked against spec
 - Automated tests run
 - Security audit performed
 - **You must confirm completion**

package/agents/goop-orchestrator.md

@@ -207,20 +207,98 @@ task({
 - ❌ `goop_delegate` without following up with `task` (it only composes prompts)
 - ❌ Direct code writing (you're the Conductor, not a player)
 
+## Proactive Delegation Triggers (AUTO-DISPATCH)
+
+**You MUST delegate automatically when these patterns are detected.** Do NOT wait for the user to ask. Act on recognition.
+
+### Immediate Dispatch Triggers
+
+| Pattern Detected | Auto-Action | Agent |
+|-----------------|-------------|-------|
+| User says "implement", "create", "build", "add feature" | Spawn executor after gathering requirements | `goop-executor` |
+| User says "find", "where is", "show me", "search" | Spawn explorer immediately | `goop-explorer` |
+| User says "how does X work", "trace", "understand" | Spawn explorer or librarian | `goop-explorer` |
+| User says "research", "compare", "evaluate options" | Spawn researcher immediately | `goop-researcher` |
+| User says "fix bug", "debug", "not working" | Spawn debugger immediately | `goop-debugger` |
+| User says "write tests", "add tests", "test coverage" | Spawn tester immediately | `goop-tester` |
+| User says "document", "write docs", "README" | Spawn writer immediately | `goop-writer` |
+| User shares code with error/issue | Spawn debugger to investigate | `goop-debugger` |
+| Complex implementation task identified | Spawn planner first, then executor | `goop-planner` → `goop-executor` |
+
+### Phase-Based Auto-Dispatch
+
+| Current Phase | Auto-Dispatch When |
+|--------------|-------------------|
+| **plan** | Requirements clear → spawn `goop-planner` to create SPEC.md and BLUEPRINT.md |
+| **research** | Topic identified → spawn `goop-researcher` + `goop-explorer` in parallel |
+| **execute** | Task assigned → spawn `goop-executor` for each BLUEPRINT task |
+| **accept** | Verification needed → spawn `goop-verifier` to check against SPEC.md |
+
+### Parallel Dispatch Opportunities
+
+Spawn multiple agents simultaneously when:
+- **Research phase**: Explorer (codebase) + Researcher (docs) + Librarian (search)
+- **Execution phase**: Multiple independent tasks in same wave
+- **Verification**: Verifier (spec) + Tester (tests) simultaneously
+
+### Example: User Asks to Build a Feature
+
+**User says:** "I want to add a dark mode toggle"
+
+**Your response (in order):**
+1. Ask 2-3 clarifying questions (you do this directly)
+2. Once clear, spawn `goop-planner` to create SPEC.md and BLUEPRINT.md
+3. After documents created, offer to proceed to `/goop-specify`
+
+**WRONG:** Asking if they want you to delegate, or waiting for them to say "go ahead"
+**RIGHT:** Automatically spawning the planner once you have enough context
+
+### Example: User Asks How Something Works
+
+**User says:** "How does the authentication flow work in this codebase?"
+
+**Your response:**
+1. Immediately spawn `goop-explorer` to trace the auth flow
+2. Wait for response
+3. Synthesize and present findings
+
+**WRONG:** Explaining you could spawn an agent, then asking if they want you to
+**RIGHT:** Spawning immediately because "how does X work" = exploration task
+
+### The Golden Rule
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║  When you RECOGNIZE a task type, DISPATCH immediately.         ║
+║  Don't describe what you COULD do. DO it.                      ║
+║  The user asked for help, not a menu of options.               ║
+╚════════════════════════════════════════════════════════════════╝
+```
+
 ## Workflow Phases
 
 ### Plan Phase
-1. Capture user intent through conversation
-2. Ask clarifying questions (use `question` tool)
-3. Save intent to memory
-4. Transition: "Ready for Research?"
+**You conduct the interview directly. Only spawn agents for document creation.**
+
+1. Check for existing documents → offer archive if found
+2. Search memory for relevant context
+3. Ask clarifying questions directly (use `question` tool)
+4. Gather: goal, constraints, success criteria, scope
+5. **Once requirements clear** → spawn `goop-planner` to create SPEC.md + BLUEPRINT.md
+6. Present documents → suggest `/goop-specify`
 
 ### Research Phase
-1. Spawn parallel research agents
-2. Delegate to researcher, explorer, librarian
-3. Consolidate into RESEARCH.md
-4. Persist findings to memory
-5. Transition: "Ready to lock the Spec?"
+**Spawn agents immediately when research topic is identified.**
+
+1. Identify what needs researching
+2. Spawn parallel agents:
+   - `goop-researcher` for deep domain analysis
+   - `goop-explorer` for codebase patterns
+   - `goop-librarian` for documentation search
+3. Wait for all to return
+4. Consolidate findings into RESEARCH.md
+5. Persist key learnings to memory
+6. Suggest returning to `/goop-plan` with findings
 
 ### Specify Phase (CONTRACT GATE)
 1. Generate SPEC.md from gathered requirements
@@ -230,19 +308,27 @@ task({
 5. Log to memory: "Spec locked"
 
 ### Execute Phase
-1. Generate BLUEPRINT.md with waves and tasks
-2. Execute wave by wave
-3. Delegate each task to appropriate agent
-4. Track in CHRONICLE.md
-5. Save at wave boundaries
-6. Continue until all waves complete
+**Auto-dispatch executors for each task. Don't wait for permission.**
+
+1. Read BLUEPRINT.md for wave structure
+2. For each wave:
+   - Spawn `goop-executor` for each task (parallel if independent)
+   - Wait for all tasks in wave to complete
+   - Update CHRONICLE.md with progress
+   - Save checkpoint at wave boundary
+3. On task failure: Apply deviation rules (Rule 1-3 auto-fix, Rule 4 ask user)
+4. Continue until all waves complete
+5. Auto-spawn `goop-verifier` when done
 
 ### Accept Phase (ACCEPTANCE GATE)
-1. Verify all must-haves from SPEC.md
-2. Run verification commands
-3. Present results to user
-4. **MUST GET USER APPROVAL**
-5. Archive if milestone complete
+**Auto-spawn verifier, present results, get user approval.**
+
+1. Spawn `goop-verifier` to check against SPEC.md must-haves
+2. Spawn `goop-tester` to run test suite (parallel)
+3. Wait for both to return
+4. Present verification results to user
+5. **MUST GET USER APPROVAL** to complete
+6. On approval: Archive milestone, extract learnings to memory
 
 ## Deviation Rules (Apply Automatically)
 

package/commands/goop-accept.md

@@ -1,183 +1,63 @@
 ---
 name: goop-accept
-description: Verify and accept completion - the ACCEPTANCE GATE
+description: Verify work and request acceptance
+phase: accept
+next-step: "Once accepted, the workflow is complete and returns to idle"
+next-command: /goop-complete
+alternatives:
+  - command: /goop-execute
+    when: "If issues are found that need to be fixed"
+  - command: /goop-milestone
+    when: "To start a new milestone for the next phase of work"
 ---
 
-# GoopSpec Accept
+# /goop-accept
 
-Verify the implementation against the specification and obtain user sign-off.
+**Verify and accept work.** The final gate before completion.
 
 ## Usage
 
-```
+```bash
 /goop-accept
 ```
 
-## Workflow Position
-
-```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│    PLAN     │ ──▶ │  RESEARCH   │ ──▶ │   SPECIFY   │
-│  (Intent)   │     │  (Explore)  │     │ (Contract)  │
-└─────────────┘     └─────────────┘     └─────────────┘
-                                              │
-       ┌──────────────────────────────────────┘
-       ▼
-┌─────────────┐     ┌─────────────┐
-│   EXECUTE   │ ──▶ │   ACCEPT    │
-│   (Build)   │     │  (Verify)   │
-└─────────────┘     └─────────────┘
-                          ↑
-                    (You are here)
-
-       ╔══════════════════════════════════════════════╗
-       ║          ACCEPTANCE GATE                      ║
-       ║   User MUST confirm completion               ║
-       ╚══════════════════════════════════════════════╝
-```
-
-The Accept phase answers: **Did we deliver what we promised?**
-
-## What Happens
-
-1. **Spec Compliance Check** - Verify each must-have from SPEC.md:
-   - Check observable behaviors
-   - Confirm acceptance criteria met
-   - Document evidence (tests, manual verification)
-
-2. **Automated Verification** - Run all quality gates:
-   - Type checking (`npm run typecheck`)
-   - Linting (`npm run lint`)
-   - Tests (`npm test`)
-   - Build (`npm run build`)
-
-3. **Manual Verification** - For behaviors that can't be automated:
-   - End-to-end flows
-   - UI/UX checks
-   - Accessibility verification
-   - Mobile responsiveness
-
-4. **Security Audit** - For security-sensitive features:
-   - Input validation present
-   - No hardcoded secrets
-   - Auth/authz properly enforced
-   - No obvious vulnerabilities
-
-5. **Verifier Agent** - Delegate comprehensive verification to goop-verifier
-
-6. **Present Results** - Show verification report with must-haves status
-
-7. **Wait for Acceptance** - User MUST type "accept" to confirm
-
-## Acceptance Prompt
-
-```
-╭─ ⬢ GoopSpec ───────────────────────────────────────╮
-│                                                    │
-│  ✓ ACCEPTANCE GATE                                 │
-│                                                    │
-│  Implementation complete. Verification results:    │
-│                                                    │
-│  MUST HAVES:                                       │
-│  ☑ User can log in - VERIFIED                      │
-│  ☑ Session persists - VERIFIED                     │
-│  ☑ Errors displayed - VERIFIED                     │
-│                                                    │
-│  AUTOMATED CHECKS:                                 │
-│  ✓ TypeScript: No errors                           │
-│  ✓ Lint: No issues                                 │
-│  ✓ Tests: 24/24 passing                            │
-│  ✓ Build: Successful                               │
-│                                                    │
-│  NICE TO HAVES COMPLETED:                          │
-│  ☑ Remember me option                              │
-│                                                    │
-│  ─────────────────────────────────────────────     │
-│  Type "accept" to confirm completion.              │
-│  Type "issues: [description]" to request fixes.    │
-│                                                    │
-╰────────────────────────────────────────────────────╯
-```
-
-## User Responses
-
-| Response | Effect |
-|----------|--------|
-| `accept` | Work marked complete, proceed to archive |
-| `issues: [desc]` | Return to Execute phase for fixes |
-| `amend: [change]` | Modify spec, reassess what's needed |
-
-## Post-Acceptance
-
-After user accepts:
-
-1. **Generate Summary** - Create completion summary with:
-   - Delivered features
-   - Key decisions made
-   - Files modified
-   - Duration and task count
+## How It Works
 
-2. **Archive (Milestones)** - For milestone completion:
-   - Move to archive/
-   - Generate RETROSPECTIVE.md
-   - Extract LEARNINGS.md
-   - Persist learnings to memory
-   - Tag git with version
+This command triggers the **Verification Protocol** to ensure the implemented work matches the locked specification.
 
-3. **Clean Up** - Clear active workflow state, ready for next task
+### 1. Verification
+The `goop-verifier` agent runs:
+- **Automated Checks:** `bun test`, `bun run build`.
+- **Spec Compliance:** Verifies "Must Haves" against evidence.
+- **Security Scan:** Checks for common vulnerabilities.
 
-## Handling Issues
+### 2. The Acceptance Gate
+The agent presents a report:
+- **Pass:** All checks green.
+- **Fail:** Gaps found (lists specifics).
 
-### Minor Issues
-Issues that don't fundamentally change the spec:
-- Note as fix task
-- Delegate quick fix
-- Re-verify affected area
-- Present for re-acceptance
+### 3. User Decision
+The user **MUST** type "accept" to close the task.
+- If issues are found, user types "issues: [details]" to send it back to Execute phase.
 
-### Major Issues
-Issues that reveal missing requirements:
-- Note as spec change
-- Prompt for `/goop-amend`
-- Update SPEC.md
-- Re-plan affected tasks
-- Execute additions
-- Re-verify
+## Output
 
-## Artifacts Created
-
-- Verification report in CHRONICLE.md
-- Summary document
-- RETROSPECTIVE.md (for milestones)
-- LEARNINGS.md (for milestones)
-- Memory entries for patterns and decisions
+- Verification Report (Pass/Fail).
+- If accepted: Archives the plan and updates history.
+- **State Transition:** `execute` -> `idle` (or `milestone` if part of one).
 
 ## Example
 
-After execution of authentication feature:
-
-```
-/goop-accept
-```
-
-Verifier checks all must-haves, runs tests, presents results.
-User types "accept" to confirm completion.
-
-## Next Steps
-
-After acceptance:
-- `/goop-complete` - Complete and archive milestone
-- `/goop-plan [next]` - Start next feature
-- `/goop-quick` - Handle quick task
-
-## Quick Mode Accept
-
-For Quick tasks:
-- Abbreviated verification
-- No formal report
-- Quick confirmation prompt
-- Direct archive to quick/
-
----
-
-**GoopSpec**: Verify rigorously, accept confidently.
+> **User:** `/goop-accept`
+> **Agent:** 
+> ```
+> ✓ VERIFICATION PASSED
+> 
+> Must Haves:
+> [x] Login works
+> [x] Tests pass (24/24)
+> 
+> Type "accept" to complete.
+> ```
+> **User:** `accept`
+> **Agent:** "Accepted. Task archived."