opencode-goopspec 0.1.3 → 0.1.4

package/references/subagent-protocol.md

@@ -2,14 +2,26 @@
 
 All GoopSpec subagents follow a standardized protocol for memory usage, planning file access, and communication with the orchestrator.
 
-## Core Principle
+## Core Principles
 
 ```
-╔════════════════════════════════════════════════════════════════╗
-║  SUBAGENTS ARE MEMORY-FIRST.                                   ║
-║  Search before starting. Save during work. Persist after.      ║
-║  Decisions and learnings flow through memory.                  ║
-╚════════════════════════════════════════════════════════════════╝
++================================================================+
+|  SUBAGENTS ARE MEMORY-FIRST.                                    |
+|  Search before starting. Save during work. Persist after.       |
+|  Decisions and learnings flow through memory.                   |
++================================================================+
+
++================================================================+
+|  SUBAGENTS USE XML RESPONSE ENVELOPES.                          |
+|  Every response ends with a <goop_report> XML block.            |
+|  See references/xml-response-schema.md for full format.         |
++================================================================+
+
++================================================================+
+|  SUBAGENTS LOAD PROJECT CONTEXT.                                |
+|  Read PROJECT_KNOWLEDGE_BASE.md for conventions.                |
+|  Align work with spec must-haves.                               |
++================================================================+
 ```
 
 ## The Memory-First Protocol
@@ -19,20 +31,26 @@ All GoopSpec subagents follow a standardized protocol for memory usage, planning
 Every subagent MUST:
 
 ```typescript
-// 1. Search for relevant past decisions
+// 1. Read project state
+Read(".goopspec/state.json")
+
+// 2. Read project knowledge base
+Read(".goopspec/PROJECT_KNOWLEDGE_BASE.md")  // If exists
+
+// 3. Search for relevant past decisions
 memory_search({ 
   query: "[task-specific query]",
   concepts: ["relevant", "concepts"],
   types: ["decision", "observation"]
 })
 
-// 2. Read the specification
+// 4. Read the specification
 Read(".goopspec/SPEC.md")
 
-// 3. Read current state
+// 5. Read current state
 Read(".goopspec/CHRONICLE.md")
 
-// 4. Read the task details
+// 6. Read the task details
 Read(".goopspec/BLUEPRINT.md")
 ```
 
@@ -164,31 +182,55 @@ Research findings. Research agents:
 
 ## Communication with Orchestrator
 
-### Response Format
-
-Subagents return structured results:
-
-```typescript
-interface SubagentResponse {
-  status: "complete" | "partial" | "blocked" | "failed";
-  summary: string;           // What was accomplished
-  files_modified?: string[]; // Changed files
-  files_created?: string[];  // New files
-  commit?: string;           // Commit hash if applicable
-  notes?: string[];          // Observations for orchestrator
-  blockers?: string[];       // If blocked/failed, why
-  next_steps?: string[];     // Suggestions if incomplete
-}
+### XML Response Envelope (MANDATORY)
+
+All subagent responses MUST end with an XML envelope. See `references/xml-response-schema.md` for the full specification.
+
+**Basic structure:**
+
+```xml
+<goop_report version="0.1.4">
+  <status>COMPLETE|PARTIAL|BLOCKED|CHECKPOINT</status>
+  <agent>goop-[type]</agent>
+  <task_name>Task description</task_name>
+  
+  <state>
+    <phase>plan|specify|execute|accept</phase>
+    <spec_locked>true|false</spec_locked>
+  </state>
+  
+  <summary>1-2 sentence summary</summary>
+  
+  <artifacts>
+    <files>
+      <file path="path/to/file" action="created|modified">reason</file>
+    </files>
+    <commits>
+      <commit sha="abc123">type(scope): message</commit>
+    </commits>
+  </artifacts>
+  
+  <memory>
+    <saved type="decision" importance="0.7">Memory title</saved>
+  </memory>
+  
+  <handoff>
+    <ready>true|false</ready>
+    <next_action agent="goop-[type]">Next task description</next_action>
+    <suggest_new_session>true|false</suggest_new_session>
+    <next_command>/goop-[command]</next_command>
+  </handoff>
+</goop_report>
 ```
 
 ### Status Meanings
 
 | Status | Meaning | Orchestrator Action |
 |--------|---------|---------------------|
-| `complete` | Task fully done | Move to next task |
-| `partial` | Some progress, more needed | Continue same task |
-| `blocked` | Cannot proceed | Assess and unblock |
-| `failed` | Task cannot be done | Apply deviation rules |
+| `COMPLETE` | Task fully done | Move to next task |
+| `PARTIAL` | Some progress, more needed | Continue same task |
+| `BLOCKED` | Cannot proceed | Assess blocker, may need user |
+| `CHECKPOINT` | Natural stopping point | Generate handoff, suggest new session |
 
 ### Raising Issues
 
@@ -379,15 +421,23 @@ memory_save({
 
 Every subagent execution:
 
+- [ ] Read state.json for current phase
+- [ ] Read PROJECT_KNOWLEDGE_BASE.md for conventions
 - [ ] Searched memory for relevant context
 - [ ] Read SPEC.md for requirements
 - [ ] Read CHRONICLE.md for current state
 - [ ] Read BLUEPRINT.md for task details
+- [ ] Aligned work with spec must-haves
 - [ ] Updated CHRONICLE.md with progress
 - [ ] Persisted learnings to memory
-- [ ] Returned structured response with:
-  - [ ] Clear status
+- [ ] Returned XML response envelope with:
+  - [ ] Status (COMPLETE/PARTIAL/BLOCKED/CHECKPOINT)
   - [ ] Summary of work
-  - [ ] Files modified
+  - [ ] Files modified with artifacts section
   - [ ] Commit hash (if applicable)
-  - [ ] Any notes/blockers
+  - [ ] Memory persisted section
+  - [ ] Handoff with next_action and suggest_new_session
+
+---
+
+*Subagent Protocol v0.1.4*

package/references/visual-style.md

@@ -0,0 +1,199 @@
+# GoopSpec Visual Style Guide
+
+A distinctive, minimal visual language for GoopSpec messages.
+
+## Brand Identity
+
+**Primary Icon:** 🔮 (Crystal Ball - represents foresight, planning, specification)
+
+**Philosophy:** Clean, minimal, precise. GoopSpec is about careful planning and clear contracts - the visual style should feel refined without being cluttered.
+
+## Header Styles
+
+### Primary Phase Header
+```
+## 🔮 GoopSpec · [Phase/Context]
+
+[Content here]
+
+---
+```
+
+### Success Header
+```
+## 🔮 GoopSpec · Phase Complete
+
+✨ [Success message]
+
+---
+```
+
+### Warning/Blocked Header
+```
+## 🔮 GoopSpec · Gate Blocked
+
+⚠️ [Warning message]
+
+→ Run: `/goop-[command]`
+
+---
+```
+
+## Phase Icons
+
+| Phase | Icon | Usage |
+|-------|------|-------|
+| Discuss | 💬 | Discovery interview |
+| Plan | 📋 | Blueprint creation |
+| Research | 🔬 | Investigation |
+| Specify | 📜 | Locking the contract |
+| Execute | ⚡ | Wave-based implementation |
+| Accept | ✅ | Verification & approval |
+| Idle | 🔮 | Ready state |
+
+## Status Indicators
+
+| Status | Icon | Meaning |
+|--------|------|---------|
+| Complete | ✓ | Task/phase done |
+| Pending | ⏳ | In progress or waiting |
+| Blocked | ✗ | Cannot proceed |
+| Locked | 🔒 | Spec is locked |
+| Unlocked | 🔓 | Spec can be modified |
+| Warning | ⚠️ | Attention needed |
+| Success | ✨ | Milestone achieved |
+| Error | ❌ | Something failed |
+
+## Message Templates
+
+### Phase Start
+```markdown
+## 🔮 GoopSpec · [Phase Name]
+
+[Phase description and context]
+
+---
+```
+
+### Gate Check - Pass
+```markdown
+## 🔮 GoopSpec · Gate Check
+
+✓ Gate passed. Proceeding...
+
+---
+```
+
+### Gate Check - Blocked
+```markdown
+## 🔮 GoopSpec · Gate Blocked
+
+✗ [Reason for block]
+
+→ Run: `/goop-[command]`
+
+---
+```
+
+### Progress Update
+```markdown
+## 🔮 GoopSpec · Progress
+
+**Phase:** ⚡ Execute | **Wave:** 2/3 | **Task:** 4/6
+
+### Completed
+- ✓ Task 2.1: [description]
+- ✓ Task 2.2: [description]
+
+### In Progress
+- ⏳ Task 2.3: [description]
+
+---
+```
+
+### Phase Complete
+```markdown
+## 🔮 GoopSpec · Phase Complete
+
+✨ [Phase Name] finished successfully
+
+### Summary
+[Summary content]
+
+### Next Step
+→ `/goop-[next-command]`
+
+---
+```
+
+### Decision Required
+```markdown
+## 🔮 GoopSpec · Decision Required
+
+⚠️ [Context about the decision]
+
+**Options:**
+- **A)** [Option A description]
+- **B)** [Option B description]
+
+Which option?
+
+---
+```
+
+### Handoff
+```markdown
+## 🔮 GoopSpec · Session Handoff
+
+### Accomplished
+- ✓ [Item 1]
+- ✓ [Item 2]
+
+### Current State
+**Phase:** [phase] | **Spec:** [locked/unlocked] | **Wave:** [N/M]
+
+### To Continue
+Start a new session, then run: `/goop-[command]`
+
+---
+```
+
+### Status Display
+```markdown
+## 🔮 GoopSpec · Status
+
+**Project:** [name]
+
+| Gate | Status |
+|------|--------|
+| Interview | ✓ Complete |
+| Spec Lock | 🔒 Locked |
+| Acceptance | ⏳ Pending |
+
+### Next Step
+→ `/goop-[command]`
+
+---
+```
+
+## Comparison: GoopSpec vs GSD
+
+| Element | GSD (Industrial) | GoopSpec (Minimal) |
+|---------|------------------|-------------------|
+| Primary icon | None | 🔮 |
+| Headers | `+====+ GOOPSPEC > PHASE` | `## 🔮 GoopSpec · Phase` |
+| Separators | `+----+` boxes | `---` dividers |
+| Feel | Industrial, rigid | Clean, minimal |
+
+## Usage Guidelines
+
+1. **Consistency:** Always use `## 🔮 GoopSpec · [Context]` for main headers
+2. **Dividers:** Use `---` to separate sections
+3. **Breathing room:** Include blank lines between sections
+4. **Bullet indicators:** Use ✓ ✗ ⏳ for status
+5. **Actions:** Use → for "next step" callouts
+6. **Phase awareness:** Use phase-specific icons (💬 📋 🔬 📜 ⚡ ✅) when relevant
+
+---
+
+*GoopSpec Visual Style v0.2.0*

package/references/xml-response-schema.md

@@ -0,0 +1,236 @@
+# XML Response Schema
+
+All GoopSpec agents use a standardized XML envelope for machine-parseable handoffs while keeping content human-readable in Markdown.
+
+## Why XML + Markdown Hybrid?
+
+1. **Machine Parsing**: Orchestrator can reliably extract status, next actions, and state
+2. **Human Readability**: Markdown inside XML remains easy to read
+3. **Structured Handoffs**: Clean session boundaries with explicit next steps
+4. **State Continuity**: Exact phase/wave/task tracking across sessions
+
+## Response Envelope Structure
+
+Every agent response MUST include this XML block at the END of their response:
+
+```xml
+<goop_report version="0.1.4">
+  <status>COMPLETE|PARTIAL|BLOCKED|CHECKPOINT</status>
+  <agent>goop-[type]</agent>
+  <task_id>W[wave].T[task]</task_id>
+  <task_name>Brief task description</task_name>
+  
+  <state>
+    <phase>plan|specify|execute|accept|research</phase>
+    <wave current="N" total="M"/>
+    <task current="X" total="Y"/>
+    <spec_locked>true|false</spec_locked>
+    <interview_complete>true|false</interview_complete>
+  </state>
+  
+  <summary>1-2 sentence summary of what was accomplished</summary>
+  
+  <artifacts>
+    <files>
+      <file path="path/to/file" action="created|modified|deleted">
+        Brief description of change
+      </file>
+    </files>
+    <commits>
+      <commit sha="abc1234">type(scope): commit message</commit>
+    </commits>
+  </artifacts>
+  
+  <memory>
+    <saved type="decision|observation|note" importance="0.8">
+      Title of memory saved
+    </saved>
+  </memory>
+  
+  <verification>
+    <check name="tests" passed="true|false">bun test - 42 passed</check>
+    <check name="typecheck" passed="true|false">No errors</check>
+    <check name="manual" passed="true|false">Description</check>
+  </verification>
+  
+  <handoff>
+    <ready>true|false</ready>
+    <next_action agent="goop-[type]">
+      Exact description of next task
+    </next_action>
+    <files_to_read>
+      <file>.goopspec/SPEC.md</file>
+      <file>.goopspec/BLUEPRINT.md</file>
+    </files_to_read>
+    <blockers>None | Description of blocker</blockers>
+    <suggest_new_session>true|false</suggest_new_session>
+    <next_command>/goop-[command]</next_command>
+  </handoff>
+</goop_report>
+```
+
+## Status Values
+
+| Status | When to Use | Orchestrator Action |
+|--------|-------------|---------------------|
+| `COMPLETE` | Task fully finished, verified | Move to next task |
+| `PARTIAL` | Some progress, need to continue | Resume same task |
+| `BLOCKED` | Cannot proceed without input | Assess blocker, may need user |
+| `CHECKPOINT` | Natural stopping point | Save state, may suggest new session |
+
+## Required vs Optional Elements
+
+### Always Required
+- `<status>` - Current completion status
+- `<agent>` - Which agent is responding
+- `<state>` - Current workflow state
+- `<summary>` - What was accomplished
+- `<handoff>` - Next steps
+
+### Required When Applicable
+- `<artifacts>` - When files changed or commits made
+- `<memory>` - When memory was persisted
+- `<verification>` - When verification commands were run
+
+### Optional
+- `<task_id>` - May not exist in research/explore phases
+- `<blockers>` - Only when blocked
+
+## Examples by Agent Type
+
+### Executor Response
+```xml
+<goop_report version="0.1.4">
+  <status>COMPLETE</status>
+  <agent>goop-executor</agent>
+  <task_id>W2.T3</task_id>
+  <task_name>Implement user authentication</task_name>
+  
+  <state>
+    <phase>execute</phase>
+    <wave current="2" total="3"/>
+    <task current="3" total="4"/>
+    <spec_locked>true</spec_locked>
+  </state>
+  
+  <summary>Implemented JWT-based authentication with login/logout endpoints and middleware.</summary>
+  
+  <artifacts>
+    <files>
+      <file path="src/auth/service.ts" action="created">Auth service with JWT generation</file>
+      <file path="src/auth/middleware.ts" action="created">Auth middleware for protected routes</file>
+      <file path="src/auth/types.ts" action="created">Auth type definitions</file>
+    </files>
+    <commits>
+      <commit sha="a1b2c3d">feat(auth): implement JWT authentication service</commit>
+    </commits>
+  </artifacts>
+  
+  <memory>
+    <saved type="decision" importance="0.8">Used jose library for JWT over jsonwebtoken</saved>
+  </memory>
+  
+  <verification>
+    <check name="tests" passed="true">bun test src/auth/ - 12 passed</check>
+    <check name="typecheck" passed="true">No errors</check>
+  </verification>
+  
+  <handoff>
+    <ready>true</ready>
+    <next_action agent="goop-executor">W2.T4: Implement session management</next_action>
+    <files_to_read>
+      <file>src/auth/service.ts</file>
+    </files_to_read>
+    <blockers>None</blockers>
+    <suggest_new_session>false</suggest_new_session>
+  </handoff>
+</goop_report>
+```
+
+### Planner Response
+```xml
+<goop_report version="0.1.4">
+  <status>COMPLETE</status>
+  <agent>goop-planner</agent>
+  <task_name>Create execution blueprint</task_name>
+  
+  <state>
+    <phase>plan</phase>
+    <spec_locked>false</spec_locked>
+    <interview_complete>true</interview_complete>
+  </state>
+  
+  <summary>Created 3-wave blueprint with 8 tasks covering all must-haves from SPEC.md.</summary>
+  
+  <artifacts>
+    <files>
+      <file path=".goopspec/BLUEPRINT.md" action="created">Execution blueprint</file>
+      <file path=".goopspec/SPEC.md" action="modified">Added traceability mapping</file>
+    </files>
+  </artifacts>
+  
+  <memory>
+    <saved type="decision" importance="0.7">Wave 1 foundation parallel, Wave 2-3 sequential</saved>
+  </memory>
+  
+  <handoff>
+    <ready>true</ready>
+    <next_action agent="orchestrator">Review blueprint with user, then /goop-specify</next_action>
+    <files_to_read>
+      <file>.goopspec/BLUEPRINT.md</file>
+    </files_to_read>
+    <blockers>None</blockers>
+    <suggest_new_session>true</suggest_new_session>
+    <next_command>/goop-specify</next_command>
+  </handoff>
+</goop_report>
+```
+
+### Blocked Response
+```xml
+<goop_report version="0.1.4">
+  <status>BLOCKED</status>
+  <agent>goop-executor</agent>
+  <task_id>W2.T2</task_id>
+  <task_name>Implement payment integration</task_name>
+  
+  <state>
+    <phase>execute</phase>
+    <wave current="2" total="3"/>
+    <task current="2" total="4"/>
+    <spec_locked>true</spec_locked>
+  </state>
+  
+  <summary>Cannot proceed - architectural decision required about payment provider.</summary>
+  
+  <handoff>
+    <ready>false</ready>
+    <blockers>
+      RULE 4 DEVIATION: Need user decision on payment provider.
+      Options: A) Stripe (recommended, better docs), B) PayPal (wider reach)
+    </blockers>
+    <suggest_new_session>false</suggest_new_session>
+  </handoff>
+</goop_report>
+```
+
+## Parsing Guidelines for Orchestrator
+
+1. **Extract status first** - Determines routing logic
+2. **Check blockers** - If blocked, present to user
+3. **Update CHRONICLE.md** - From artifacts and state
+4. **Route next action** - Based on handoff.next_action
+5. **Session boundary** - If suggest_new_session=true, generate HANDOFF.md
+
+## Validation Rules
+
+- Status must be one of: COMPLETE, PARTIAL, BLOCKED, CHECKPOINT
+- Agent must match the subagent_type that was invoked
+- State.phase must match current workflow phase
+- If COMPLETE, verification should have at least one check
+- If BLOCKED, blockers must be non-empty
+- handoff.next_action must specify which agent continues
+
+---
+
+*GoopSpec XML Response Schema v0.1.4*