opencode-goopspec 0.1.2 → 0.1.4

package/commands/goop-execute.md

@@ -1,137 +1,420 @@
 ---
 name: goop-execute
-description: Start the Execute phase - wave-based implementation
+description: Begin wave-based execution
+phase: execute
+requires: spec_locked
+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
-
-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
-
-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**
-
-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
-
-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)
-
-5. **Checkpoint Handling** - Pause for user input when needed:
-   - `checkpoint:verify` - User verifies functionality
-   - `checkpoint:decision` - User makes decision
-   - `checkpoint:action` - User performs action
-
-## Wave Principles
-
-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
+## Gate Requirement
+
+```
++================================================================+
+|  EXECUTION GATE: Specification must be locked before executing. |
+|  This ensures we build what was agreed upon.                    |
++================================================================+
+```
+
+**Required before this command:**
+- `specLocked: true` (check via `goop_state({ action: "get" })`)
+- `.goopspec/BLUEPRINT.md` exists with wave structure
+
+**If not satisfied:** Refuse and redirect to `/goop-specify`
+
+**CRITICAL: Never read or edit .goopspec/state.json directly. Always use `goop_state` tool.**
+
+## Tools Used
+
+| Tool | Purpose in This Command |
+|------|------------------------|
+| `goop_status` | Check spec lock status and wave progress |
+| `goop_state` | **ALL state operations** - check spec lock, update wave progress. NEVER edit state.json directly |
+| `goop_spec` | Load blueprint for execution |
+| `goop_checkpoint` | Save state at wave boundaries |
+| `goop_delegate` | Spawn executor agents for implementation |
+| `goop_adl` | Log deviations during execution |
+| `memory_search` | Find relevant patterns and conventions |
+
+**Hook Support:** `tool.execute.after` auto-progresses to accept phase when all waves complete.
+
+---
+
+## Process
+
+### Phase 1: Gate Check
+
+**Execute BEFORE anything else:**
+
+```
+goop_status()
+goop_state({ action: "get" })        # NEVER read state.json directly
+Read(".goopspec/BLUEPRINT.md")
+```
+
+**1.1 Check specLocked:**
+
+```
+IF state.specLocked != true:
+  REFUSE with:
+  
+  ## 🔮 GoopSpec · Gate Blocked
+  
+  ✗ Specification must be locked before execution.
+  
+  → Run: `/goop-specify`
   
-  - Change 1
-  - Change 2
-  ```
+  ---
+```
+
+**1.2 Gate passed:**
+
+```
+## 🔮 GoopSpec · Execution
 
-## Example
+✓ Spec gate passed
 
-After spec locked for authentication:
+⚡ Starting wave-based execution...
 
+---
 ```
-/goop-execute
+
+### Phase 2: Load Context
+
+```
+Read(".goopspec/SPEC.md")           # Must-haves
+Read(".goopspec/BLUEPRINT.md")      # Waves and tasks
+Read(".goopspec/CHRONICLE.md")      # Progress (if resuming)
+Read(".goopspec/PROJECT_KNOWLEDGE_BASE.md")  # Conventions
+
+memory_search({ query: "[feature] implementation patterns" })
+```
+
+Identify:
+- Current wave (from CHRONICLE or start at 1)
+- Tasks to execute
+- Dependencies between tasks
+
+### Phase 3: Wave Execution Loop
+
+**Display wave start:**
+
+```
+## 🔮 GoopSpec · Wave [N] of [M]: [Wave Name]
+
+**Tasks:** [X] | **Execution:** [Parallel/Sequential]
+
+---
+```
+
+**For each task in wave:**
+
+1. **Delegate to executor:**
+```
+task({
+  subagent_type: "goop-executor",
+  description: "Execute Task [N.M]",
+  prompt: `
+## TASK
+Wave [N], Task [M]: [Task Name]
+
+## PROJECT CONTEXT
+[From PROJECT_KNOWLEDGE_BASE.md]
+
+## SPEC REQUIREMENTS
+[Relevant must-have from SPEC.md]
+
+## TASK DETAILS
+[From BLUEPRINT.md]
+
+Intent: [intent]
+Deliverables: [list]
+Files: [paths]
+Verification: [command]
+Acceptance: [criteria]
+
+## INSTRUCTIONS
+1. Implement following existing patterns
+2. Commit atomically
+3. Return XML response envelope
+4. Include spec coverage in response
+  `
+})
+```
+
+2. **Parse XML response:**
+   - Extract status (COMPLETE/PARTIAL/BLOCKED)
+   - Extract artifacts (files, commits)
+   - Extract handoff instructions
+
+3. **Update CHRONICLE.md:**
+```markdown
+### Task [N.M]: [Name]
+- Status: [Complete/Partial/Blocked]
+- Commit: [sha]
+- Files: [list]
+- Time: [timestamp]
+```
+
+4. **Handle status:**
+
+| Status | Action |
+|--------|--------|
+| COMPLETE | Continue to next task |
+| PARTIAL | Resume with partial context |
+| BLOCKED | Check deviation rules |
+
+### Phase 4: Deviation Handling
+
+**Apply deviation rules:**
+
+| Rule | Trigger | Action |
+|------|---------|--------|
+| Rule 1 | Bug found | Auto-fix, document |
+| Rule 2 | Missing critical | Auto-add, document |
+| Rule 3 | Blocking issue | Auto-fix, document |
+| Rule 4 | Architectural | **STOP**, ask user |
+
+**On Rule 4:**
+```
+## 🔮 GoopSpec · Decision Required
+
+⚠️ **Type:** Architectural Decision
+
+**Context:** [From executor response]
+
+**Options:**
+- **A)** [option] — [impact]
+- **B)** [option] — [impact]
+
+**Recommendation:** [If any]
+
+Which option? (A/B/other)
+
+---
+```
+
+Use `question` tool, then resume with decision.
+
+### Phase 5: Wave Completion
+
+**At end of each wave:**
+
+1. **Run wave verification:**
+```
+Spawn goop-verifier for wave-level checks
+```
+
+2. **Update CHRONICLE.md:**
+```markdown
+## Wave [N]: COMPLETE
+- Tasks: [X/X]
+- Commits: [list]
+- Verification: PASSED
+- Time: [timestamp]
+```
+
+3. **Save checkpoint:**
+```
+goop_checkpoint({ 
+  action: "save",
+  context: { wave: N, phase: "execute" }
+})
+```
+
+4. **Generate HANDOFF.md:**
+```markdown
+# Session Handoff
+
+**Phase:** execute
+**Wave:** [N] of [M] complete
+
+## Accomplished
+- [x] Task N.1: [description]
+- [x] Task N.2: [description]
+
+## Next Session
+Run: /goop-execute
+
+## Context
+Wave [N] complete. Starting Wave [N+1] next.
+```
+
+5. **Suggest new session:**
+```
+## 🔮 GoopSpec · Wave [N] Complete
+
+✨ Wave finished successfully
+
+| Metric | Status |
+|--------|--------|
+| Tasks | ✓ [X/X] complete |
+| Commits | [Y] |
+| Verification | ✓ PASSED |
+
+### Next
+
+**Option A:** Continue to Wave [N+1] (current session)
+**Option B:** Start new session for fresh context (Recommended)
+
+For Option B:
+1. Start a new session
+2. Run: `/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
+### Phase 6: Execution Complete
 
-Each task delegated to goop-executor, committed atomically.
+**When all waves done:**
 
-## Continuation Enforcement
+```
+## 🔮 GoopSpec · Execution Complete
+
+✨ All waves finished successfully
 
-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
+| Metric | Status |
+|--------|--------|
+| Waves | ✓ [M/M] complete |
+| Tasks | ✓ [P/P] complete |
+| Commits | [Q] |
 
-## Next Steps
+All must-haves implemented and verified.
 
-After execution:
-- `/goop-accept` - Verify and accept completion (ACCEPTANCE GATE)
+### Next Step
 
-During execution:
-- `/goop-status` - Check progress
-- `/goop-pause` - Save checkpoint manually
+**Verify and accept** — Final verification against spec
 
-## Quick Mode Execution
+→ `/goop-accept`
+
+---
+
+Start a new session for fresh context.
+```
+
+Update state using goop_state:
+```
+goop_state({ action: "transition", phase: "accept" })
+```
+
+This atomically updates the workflow state. **NEVER edit state.json directly.**
+
+## Output
+
+| File | Purpose |
+|------|---------|
+| Source files | Implementation |
+| Commits | Atomic changes |
+| `.goopspec/CHRONICLE.md` | Progress log |
+| `.goopspec/HANDOFF.md` | Session handoff |
+
+## Transitions
+
+| Outcome | Next Step |
+|---------|-----------|
+| All waves complete | `/goop-accept` for verification |
+| Checkpoint reached | `/goop-pause` to save, resume later |
+| Wave complete | Continue or new session |
+| Gate blocked | `/goop-specify` to lock spec |
+
+## Examples
+
+**Starting Execution:**
+```
+User: /goop-execute
+
+Orchestrator:
++--------------------------------------------------------+
+|  GOOPSPEC > EXECUTION                                   |
++--------------------------------------------------------+
+|  Spec gate: PASSED                                       |
+|  Starting wave-based execution...                        |
++--------------------------------------------------------+
+
++--------------------------------------------------------+
+|  GOOPSPEC > WAVE 1 of 3: Foundation                     |
++--------------------------------------------------------+
+
+[Delegating Task 1.1...]
+
+goop-executor: Task 1.1 COMPLETE (commit: abc123)
+
+[Delegating Task 1.2...]
+
+goop-executor: Task 1.2 COMPLETE (commit: def456)
+
++--------------------------------------------------------+
+|  GOOPSPEC > WAVE 1 COMPLETE                             |
++--------------------------------------------------------+
+
+**Recommend:** Start new session for Wave 2
+```
+
+**Checkpoint Reached:**
+```
+goop-executor: BLOCKED - Rule 4 deviation
+
++--------------------------------------------------------+
+|  GOOPSPEC > CHECKPOINT: Decision Required               |
++--------------------------------------------------------+
+
+**Context:** Database schema change needed
+
+**Options:**
+| A | Add index | Better performance |
+| B | Skip index | Faster deployment |
+
+Which option?
+
+User: A
+
+Orchestrator: Resuming with Option A...
+```
 
-For Quick tasks:
-- Abbreviated waves (often just 1-2)
-- Faster delegation
-- Less formal tracking
-- Direct to Accept phase
+## Success Criteria
+
+- [ ] Gate check performed (spec_locked)
+- [ ] Project context loaded (KNOWLEDGE_BASE, memory)
+- [ ] Each task delegated with full context
+- [ ] XML responses parsed correctly
+- [ ] CHRONICLE.md updated after each task
+- [ ] Deviation rules applied (auto-fix or checkpoint)
+- [ ] Checkpoints saved at wave boundaries
+- [ ] HANDOFF.md generated at natural pauses
+- [ ] User informed of progress throughout
+
+## Anti-Patterns
+
+**DON'T:**
+- Skip the spec_locked gate
+- Delegate without full context
+- Ignore XML response status
+- Skip wave-boundary checkpoints
+- Continue indefinitely without handoffs
+
+**DO:**
+- Enforce the gate strictly
+- Include PROJECT_KNOWLEDGE_BASE in delegations
+- Parse and act on XML responses
+- Save checkpoints at wave boundaries
+- Suggest new sessions for fresh context
 
 ---
 
-**GoopSpec**: Execute with precision, deliver with confidence.
+*Execution Protocol v0.1.4*
+*"Execute in waves. Checkpoint often. Handoff clean."*

package/commands/goop-help.md

@@ -13,6 +13,17 @@ Display help information and available commands.
 /goop-help
 ```
 
+## Tools Used
+
+| Tool | Purpose in This Command |
+|------|------------------------|
+| `goop_reference` | Load reference documentation |
+| `goop_skill` | List available skills |
+
+**Hook Support:** None specific - informational command.
+
+---
+
 ## Available Commands
 
 **Project Management:**

package/commands/goop-map-codebase.md

@@ -15,7 +15,7 @@ Map an existing codebase for brownfield projects.
 
 Analyzes codebase with parallel Explore agents. Creates `.goopspec/codebase/` with 7 focused documents covering stack, architecture, structure, conventions, testing, integrations, and concerns.
 
-Use before `/goop-new` on existing codebases. Provides the context needed to extend rather than replace.
+Use before `/goop-setup` on existing codebases. Provides the context needed to extend rather than replace.
 
 **Creates:**
 - `.goopspec/codebase/STACK.md` - Technology stack
@@ -33,6 +33,19 @@ Use before `/goop-new` on existing codebases. Provides the context needed to ext
 @/home/james/Documents/opencode-goopspec/templates/codebase/conventions.md
 </execution_context>
 
+<tools_used>
+## Tools Used
+
+| Tool | Purpose in This Command |
+|------|------------------------|
+| `goop_status` | Check if mapping already exists |
+| `memory_search` | Find prior codebase insights |
+| `memory_save` | Persist discovered patterns |
+| `memory_note` | Quick capture during exploration |
+
+**Hook Support:** `system.transform` injects patterns for future sessions.
+</tools_used>
+
 <process>
 ## Phase 1: Setup
 
@@ -429,7 +442,7 @@ OPTIONAL_VAR=[description]
 
 ## Phase 5: Update State
 
-Update STATE.md:
+Update `.goopspec/state.json`:
 - Mark codebase as mapped
 - Add timestamp
 - Link to codebase docs
@@ -467,7 +480,7 @@ Created in .goopspec/codebase/:
 
 **Initialize GoopSpec project** with brownfield context
 
-/goop-new [project-name]
+/goop-setup
 
 <sub>Will use codebase map to understand existing code</sub>
 

package/commands/goop-memory.md

@@ -11,6 +11,17 @@ View the status and statistics of the persistent memory system.
 `/goop-memory stats` - Show detailed statistics
 `/goop-memory clean` - Clean up old/low-importance memories
 
+## Tools Used
+
+| Tool | Purpose in This Command |
+|------|------------------------|
+| `goop_status` | Check memory worker status |
+| `memory_search` | Query memory statistics |
+
+**Hook Support:** None specific - status command.
+
+---
+
 ## Instructions
 
 When this command is invoked: