opencode-goopspec 0.1.2 → 0.1.4

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*

package/templates/blueprint.md

@@ -2,6 +2,7 @@
 
 **Spec Version:** {{spec_version}}
 **Created:** {{created_date}}
+**Last Updated:** {{updated_date}}
 **Mode:** {{mode}}
 
 ---
@@ -12,8 +13,26 @@
 
 **Approach:** {{approach}}
 
-**Waves:** {{wave_count}}
-**Estimated Tasks:** {{task_count}}
+| Metric | Value |
+|--------|-------|
+| Waves | {{wave_count}} |
+| Total Tasks | {{task_count}} |
+| Parallel Execution | {{parallel_percentage}}% |
+| Estimated Effort | {{estimated_effort}} |
+
+---
+
+## Spec Mapping
+
+Every must-have from SPEC.md is covered:
+
+| Must-Have | Tasks | Coverage |
+|-----------|-------|----------|
+{{#spec_mapping}}
+| MH{{number}}: {{title}} | {{tasks}} | {{coverage}} |
+{{/spec_mapping}}
+
+**Total Coverage:** {{total_coverage}}%
 
 ---
 
@@ -21,8 +40,10 @@
 
 ```
 {{#waves}}
-Wave {{number}}: {{name}} {{#parallel}}(parallel){{/parallel}}{{^parallel}}(sequential){{/parallel}}
-{{#depends_on}}  └── depends on Wave {{.}}{{/depends_on}}
+Wave {{number}}: {{name}} {{#parallel}}[PARALLEL]{{/parallel}}{{^parallel}}[SEQUENTIAL]{{/parallel}}
+{{#tasks}}  ├── Task {{wave}}.{{number}}: {{name}}
+{{/tasks}}{{#depends_on}}  └── depends on Wave {{.}}
+{{/depends_on}}
 {{/waves}}
 ```
 
@@ -32,17 +53,31 @@ Wave {{number}}: {{name}} {{#parallel}}(parallel){{/parallel}}{{^parallel}}(sequ
 ## Wave {{number}}: {{name}}
 
 **Goal:** {{goal}}
-**Parallel:** {{#parallel}}Yes — tasks can run concurrently{{/parallel}}{{^parallel}}No — sequential execution{{/parallel}}
-{{#depends_on}}
-**Depends On:** Wave {{.}}
-{{/depends_on}}
 
-### Tasks
+**Execution:** {{#parallel}}Parallel — tasks can run concurrently{{/parallel}}{{^parallel}}Sequential — tasks must run in order{{/parallel}}
+
+{{#depends_on}}**Depends On:** Wave {{.}} must complete first{{/depends_on}}
+
+### Verification Matrix
+
+| Check | Command | Expected |
+|-------|---------|----------|
+{{#verification_matrix}}
+| {{check}} | `{{command}}` | {{expected}} |
+{{/verification_matrix}}
+
+---
 
 {{#tasks}}
 ### Task {{wave}}.{{number}}: {{name}}
 
-**Intent:** {{intent}}
+| Attribute | Value |
+|-----------|-------|
+| **Intent** | {{intent}} |
+| **Parallel** | {{#parallel}}Yes{{/parallel}}{{^parallel}}No{{/parallel}} |
+{{#depends_on}}| **Depends On** | Task {{depends_on}} |{{/depends_on}}
+{{#blocks}}| **Blocks** | Task {{blocks}} |{{/blocks}}
+| **Spec Coverage** | {{spec_coverage}} |
 
 **Deliverables:**
 {{#deliverables}}
@@ -51,30 +86,25 @@ Wave {{number}}: {{name}} {{#parallel}}(parallel){{/parallel}}{{^parallel}}(sequ
 
 **Files:**
 {{#files}}
-- `{{.}}`
+- `{{path}}` — {{action}}
 {{/files}}
 
 **Verification:**
 ```bash
-{{verification}}
+{{verification_command}}
 ```
 
 **Acceptance:**
 {{acceptance}}
 
-{{#blocks}}
-**Blocks:** {{blocks}}
-{{/blocks}}
-
 ---
 
 {{/tasks}}
-
 {{/waves}}
 
 ## Verification Checklist
 
-Before marking complete:
+Before marking blueprint complete:
 
 {{#verification_checklist}}
 - [ ] {{.}}
@@ -82,25 +112,22 @@ Before marking complete:
 
 ---
 
-## Must-Haves Traceability
+## Risk Assessment
 
-Mapping tasks to spec requirements:
+{{#risks}}
+### Risk: {{title}}
 
-| Must-Have | Covered By |
-|-----------|------------|
-{{#must_have_mapping}}
-| {{must_have}} | Wave {{wave}}, Task {{task}} |
-{{/must_have_mapping}}
+| Attribute | Value |
+|-----------|-------|
+| Likelihood | {{likelihood}} |
+| Impact | {{impact}} |
+| Affected Tasks | {{affected_tasks}} |
 
----
+**Mitigation:** {{mitigation}}
 
-## Risk Assessment
+**Contingency:** {{contingency}}
 
-{{#risks}}
-### {{risk}}
-- **Likelihood:** {{likelihood}}
-- **Impact:** {{impact}}
-- **Mitigation:** {{mitigation}}
+---
 {{/risks}}
 
 {{^risks}}
@@ -109,33 +136,53 @@ No significant risks identified.
 
 ---
 
+## Deviation Protocol
+
+If issues are encountered during execution:
+
+| Rule | Trigger | Action |
+|------|---------|--------|
+| **Rule 1** | Bug found in existing code | Auto-fix, document in CHRONICLE |
+| **Rule 2** | Missing critical functionality | Auto-add, document in CHRONICLE |
+| **Rule 3** | Blocking issue (deps, imports) | Auto-fix, document in CHRONICLE |
+| **Rule 4** | Architectural decision needed | **STOP**, ask user, log to memory |
+
+---
+
 ## Execution Notes
 
 ### For Orchestrator
 - Delegate ALL code tasks to executor agents
 - Track progress in CHRONICLE.md
-- Save to memory at wave boundaries
+- Save checkpoint at wave boundaries
+- Generate HANDOFF.md when suggesting new session
 - Confirm with user at CONTRACT GATES
 
 ### For Subagents
 - Read SPEC.md for requirements
 - Check CHRONICLE.md for context
+- Load PROJECT_KNOWLEDGE_BASE.md for conventions
 - Use memory_search before decisions
 - Persist learnings with memory_save
+- Return XML response envelope
 
----
+### Parallel Execution Rules
+- Tasks within a parallel wave can run concurrently
+- Wait for all tasks in wave before proceeding to next wave
+- If any task blocks, continue others and handle blocker separately
 
-## Deviation Protocol
+---
 
-If you encounter issues:
+## Handoff Protocol
 
-1. **Bug Found** → Auto-fix, document in CHRONICLE.md
-2. **Missing Functionality** → Auto-add if critical, document
-3. **Blocking Issue** → Auto-fix (deps, imports), document
-4. **Architectural Decision** → STOP, ask user, log to memory
+At wave boundaries:
+1. Update CHRONICLE.md with completed tasks
+2. Save checkpoint with goop_checkpoint
+3. If context full or natural pause, generate HANDOFF.md
+4. Suggest: "Start new session and run `/goop-execute`"
 
 ---
 
 *Blueprint derived from SPEC.md*
 *Execute with confidence — the plan is the contract*
-*GoopSpec v0.1.0*
+*GoopSpec v0.1.4*

package/templates/chronicle.md

@@ -2,6 +2,7 @@
 
 **Last Updated:** {{last_updated}}
 **Current Phase:** {{current_phase}}
+**Session:** {{session_id}}
 
 ---
 
@@ -15,10 +16,12 @@
 
 | Metric | Value |
 |--------|-------|
+| Phase | {{current_phase}} |
+| Interview Complete | {{interview_complete}} |
+| Spec Locked | {{spec_locked}} |
 | Waves Completed | {{waves_completed}}/{{waves_total}} |
-| Tasks Done | {{tasks_completed}} |
+| Tasks Done | {{tasks_completed}}/{{tasks_total}} |
 | Time Invested | {{total_time}} |
-| Current Mode | {{mode}} |
 
 ---
 
@@ -28,31 +31,93 @@
 
 **Status:** {{wave_status}}
 **Started:** {{wave_started}}
+**Execution:** {{#parallel}}Parallel{{/parallel}}{{^parallel}}Sequential{{/parallel}}
 
 **Tasks:**
 {{#wave_tasks}}
-- [{{status}}] {{name}}
+- [{{status}}] Task {{wave}}.{{number}}: {{name}} {{#commit}}(`{{commit}}`){{/commit}}
 {{/wave_tasks}}
 
-**Blockers:**
+**Progress:** {{wave_progress}}%
+
+---
+
+## Active Blockers
+
 {{#blockers}}
-- **[{{severity}}]** {{description}}
+### {{title}}
+
+| Attribute | Value |
+|-----------|-------|
+| Severity | {{severity}} |
+| Type | {{type}} |
+| Blocking | Task {{blocking_task}} |
+| Since | {{since}} |
+
+**Description:** {{description}}
+
+**Resolution:** {{resolution}}
+
+---
 {{/blockers}}
+
 {{^blockers}}
-None
+No active blockers.
 {{/blockers}}
 
 ---
 
+## Pending Decisions
+
+Decisions awaiting user input (Rule 4 deviations):
+
+{{#pending_decisions}}
+### {{title}}
+
+**Context:** {{context}}
+
+**Options:**
+{{#options}}
+- **{{label}}:** {{description}}
+{{/options}}
+
+**Recommendation:** {{recommendation}}
+
+**Impact:** {{impact}}
+
+---
+{{/pending_decisions}}
+
+{{^pending_decisions}}
+No pending decisions.
+{{/pending_decisions}}
+
+---
+
 ## Recent Activity
 
 {{#recent_activity}}
-### {{timestamp}}
-- **Action:** {{action}}
-- **Outcome:** {{outcome}}
+### {{timestamp}} — {{agent}}
+
+**Action:** {{action}}
+
+**Outcome:** {{outcome}}
+
+{{#files_changed}}
+**Files:** {{files_changed}}
+{{/files_changed}}
+
+{{#commit}}
+**Commit:** `{{commit}}` — {{commit_message}}
+{{/commit}}
+
 {{#decision}}
-- **Decision:** {{decision}} — *Reason: {{reason}}*
+**Decision:** {{decision}}
+- Reason: {{reason}}
+- Saved to memory: {{saved_to_memory}}
 {{/decision}}
+
+---
 {{/recent_activity}}
 
 ---
@@ -63,10 +128,18 @@ Significant choices captured for future reference.
 
 {{#decisions}}
 ### {{date}}: {{title}}
-- **Choice:** {{choice}}
-- **Alternatives:** {{alternatives}}
-- **Reasoning:** {{reasoning}}
-- **Impact:** {{impact}}
+
+| Attribute | Value |
+|-----------|-------|
+| Choice | {{choice}} |
+| Alternatives | {{alternatives}} |
+| Impact | {{impact}} |
+
+**Reasoning:** {{reasoning}}
+
+**Memory ID:** {{memory_id}}
+
+---
 {{/decisions}}
 
 {{^decisions}}
@@ -81,6 +154,8 @@ Insights gained during this journey.
 
 {{#learnings}}
 - **{{topic}}:** {{insight}}
+  - Discovered: {{discovered_at}}
+  - Memory: {{memory_id}}
 {{/learnings}}
 
 {{^learnings}}
@@ -89,6 +164,22 @@ No learnings captured yet.
 
 ---
 
+## Session History
+
+### Current Session
+- Started: {{session_start}}
+- Tasks Completed: {{session_tasks_completed}}
+- Commits: {{session_commits}}
+
+### Previous Sessions
+{{#previous_sessions}}
+| Session | Date | Accomplishments |
+|---------|------|-----------------|
+| {{session_id}} | {{date}} | {{accomplishments}} |
+{{/previous_sessions}}
+
+---
+
 ## Checkpoints
 
 Saved positions for recovery.
@@ -105,6 +196,21 @@ No checkpoints saved.
 
 ---
 
+## Handoff History
+
+{{#handoffs}}
+### {{timestamp}}
+- Phase: {{phase}}
+- Next Command: `{{next_command}}`
+- Handoff File: `{{handoff_file}}`
+{{/handoffs}}
+
+{{^handoffs}}
+No handoffs generated yet.
+{{/handoffs}}
+
+---
+
 ## Memory Integration
 
 ### Recent Memory Entries
@@ -131,6 +237,11 @@ No checkpoints saved.
 - {{.}}
 {{/after_wave}}
 
+### Suggested Command
+```
+{{next_command}}
+```
+
 ---
 
 ## Quick Commands
@@ -143,7 +254,10 @@ No checkpoints saved.
 /goop-execute
 
 # Save checkpoint
-/goop-checkpoint
+/goop-pause
+
+# Resume from checkpoint
+/goop-resume
 
 # Search past work
 /goop-recall "{{query}}"
@@ -153,4 +267,4 @@ No checkpoints saved.
 
 *Chronicle auto-updated by GoopSpec after each action*
 *This is your journey log — decisions persist, context flows*
-*GoopSpec v0.1.0*
+*GoopSpec v0.1.4*