opencode-goopspec 0.1.3 → 0.1.4

package/commands/goop-execute.md

@@ -1,9 +1,8 @@
 ---
 name: goop-execute
 description: Begin wave-based execution
-agent: goop-executor
-spawn: true
 phase: execute
+requires: spec_locked
 next-step: "When all waves are complete, verify the work and request acceptance"
 next-command: /goop-accept
 alternatives:
@@ -23,49 +22,399 @@ alternatives:
 /goop-execute
 ```
 
-## How It Works
+## Gate Requirement
 
-The **Orchestrator** takes control and manages the implementation process. It does not write code directly but delegates to the **Executor** agent.
+```
++================================================================+
+|  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`
+  
+  ---
+```
+
+**1.2 Gate passed:**
+
+```
+## 🔮 GoopSpec · Execution
+
+✓ Spec gate passed
+
+⚡ Starting wave-based execution...
+
+---
+```
+
+### 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)
+
+---
+```
 
-### 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)
+Use `question` tool, then resume with decision.
 
-### 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`.
+### Phase 5: Wave Completion
 
-### 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).
+**At end of each wave:**
 
-### 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).
+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`
+
+---
+```
+
+### Phase 6: Execution Complete
+
+**When all waves done:**
+
+```
+## 🔮 GoopSpec · Execution Complete
+
+✨ All waves finished successfully
+
+| Metric | Status |
+|--------|--------|
+| Waves | ✓ [M/M] complete |
+| Tasks | ✓ [P/P] complete |
+| Commits | [Q] |
+
+All must-haves implemented and verified.
+
+### Next Step
+
+**Verify and accept** — Final verification against spec
+
+→ `/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
 
-- **Code:** Modified source files.
-- **Commits:** Atomic commits per task.
-- **Chronicle:** Updated `.goopspec/CHRONICLE.md`.
+| 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)
 
-## Example
++--------------------------------------------------------+
+|  GOOPSPEC > WAVE 1 COMPLETE                             |
++--------------------------------------------------------+
 
-> **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..."
+**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...
+```
+
+## 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
+
+---
 
-## Interactive Control
-- Use `/goop-status` to check progress.
-- Use `/goop-pause` to stop safely.
+*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

@@ -33,6 +33,19 @@ Use before `/goop-setup` on existing codebases. Provides the context needed to e
 @/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
 

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:

package/commands/goop-milestone.md

@@ -13,6 +13,19 @@ description: Start a new milestone
 /goop-milestone [start|status|list] [name]
 ```
 
+## Tools Used
+
+| Tool | Purpose in This Command |
+|------|------------------------|
+| `goop_status` | Check current milestone state |
+| `goop_adl` | Log milestone start/completion |
+| `memory_search` | Find prior milestone context |
+| `goop_checkpoint` | Save milestone boundaries |
+
+**Hook Support:** `tool.execute.after` tracks milestone transitions.
+
+---
+
 ## How It Works
 
 Milestones are containers for multiple features/tasks. They help track progress towards a larger release.

package/commands/goop-pause.md

@@ -13,6 +13,18 @@ description: Save a checkpoint and pause work
 /goop-pause [optional message]
 ```
 
+## Tools Used
+
+| Tool | Purpose in This Command |
+|------|------------------------|
+| `goop_checkpoint` | Save execution state for later resume |
+| `goop_status` | Capture current phase and progress |
+| `memory_save` | Persist session context |
+
+**Hook Support:** `system.transform` includes checkpoint in future sessions.
+
+---
+
 ## How It Works
 
 Safely stops the current workflow and saves a snapshot of the context. This allows you to switch tasks or end your session without losing "brain state."