opencode-goopspec 0.1.2 → 0.1.4

package/references/phase-gates.md

@@ -0,0 +1,360 @@
+# Phase Gates
+
+Phase Gates are mandatory checkpoints that ensure quality and prevent premature progression through the GoopSpec workflow.
+
+## Core Principle
+
+```
++================================================================+
+|  GATES ENFORCE QUALITY. NO SHORTCUTS.                           |
+|  Each phase must satisfy its gate before proceeding.            |
+|  Gates prevent scope creep, rework, and missed requirements.    |
++================================================================+
+```
+
+## Gate Overview
+
+| Gate | Location | Purpose | Enforced By |
+|------|----------|---------|-------------|
+| **Discovery Gate** | Before /goop-plan | Ensure requirements understood | Orchestrator |
+| **Spec Gate** | Before /goop-execute | Lock contract with user | /goop-specify |
+| **Execution Gate** | Before /goop-accept | Verify all tasks complete | Orchestrator |
+| **Acceptance Gate** | Before /goop-complete | User accepts deliverable | /goop-accept |
+
+---
+
+## Gate 1: Discovery Gate
+
+### Location
+Between discussion and planning (`/goop-discuss` → `/goop-plan`)
+
+### Purpose
+Ensure the six discovery questions are answered before any planning begins.
+
+### Requirements
+| Requirement | Validation |
+|-------------|------------|
+| Vision defined | Non-empty, > 2 sentences |
+| Must-haves listed | At least 1 item |
+| Constraints documented | Non-empty |
+| Out of scope defined | At least 1 item |
+| Assumptions listed | Non-empty |
+| Risks identified | At least 1 with mitigation |
+
+### State Check
+```json
+{
+  "interview_complete": true
+}
+```
+
+### File Check
+```
+.goopspec/REQUIREMENTS.md exists
+```
+
+### Enforcement
+```
+/goop-plan invoked:
+  IF state.interview_complete != true:
+    REFUSE: "Discovery interview required. Run /goop-discuss first."
+  IF REQUIREMENTS.md does not exist:
+    REFUSE: "No requirements found. Run /goop-discuss first."
+  ELSE:
+    PROCEED with planning
+```
+
+### Bypass Conditions
+- `/goop-quick` for small tasks (single file, < 30 min)
+- Bug fixes with clear reproduction
+- Documentation-only changes
+
+---
+
+## Gate 2: Spec Gate
+
+### Location
+Between planning and execution (`/goop-plan` → `/goop-execute`)
+
+### Purpose
+Lock the specification contract with explicit user confirmation.
+
+### Requirements
+| Requirement | Validation |
+|-------------|------------|
+| SPEC.md exists | File present |
+| Must-haves defined | At least 1 item |
+| Out of scope defined | At least 1 item |
+| BLUEPRINT.md exists | File present |
+| Traceability mapping | Every must-have maps to task(s) |
+| User confirmation | Explicit "confirm" or equivalent |
+
+### State Check
+```json
+{
+  "spec_locked": true,
+  "locked_at": "[timestamp]",
+  "locked_by": "[user]"
+}
+```
+
+### Enforcement
+```
+/goop-execute invoked:
+  IF state.spec_locked != true:
+    REFUSE: "Specification not locked. Run /goop-specify first."
+  IF SPEC.md traceability incomplete:
+    REFUSE: "Traceability incomplete. Every must-have needs mapped tasks."
+  ELSE:
+    PROCEED with execution
+```
+
+### Lock Process
+1. Display SPEC.md must-haves and out-of-scope
+2. Display BLUEPRINT.md wave summary
+3. Show traceability matrix
+4. Request user confirmation: "Type 'confirm' to lock specification"
+5. On confirm: Set `spec_locked: true`, log to memory, proceed
+
+### Amendment After Lock
+Once locked, changes require `/goop-amend`:
+1. Document requested change
+2. Assess impact on BLUEPRINT.md
+3. Get user approval for change
+4. Update SPEC.md with amendment history
+5. Update BLUEPRINT.md if needed
+6. Continue execution
+
+---
+
+## Gate 3: Execution Gate
+
+### Location
+Between execution and acceptance (`/goop-execute` → `/goop-accept`)
+
+### Purpose
+Verify all planned tasks are complete before verification.
+
+### Requirements
+| Requirement | Validation |
+|-------------|------------|
+| All waves complete | CHRONICLE.md shows all waves done |
+| All tasks complete | No pending tasks in BLUEPRINT.md |
+| Verification passing | Tests pass, typecheck clean |
+| No blockers | No unresolved BLOCKED status |
+
+### State Check
+```json
+{
+  "phase": "execute",
+  "waves_complete": true,
+  "all_tasks_done": true
+}
+```
+
+### File Check
+```
+CHRONICLE.md shows:
+- All waves marked complete
+- All tasks checked off
+- Final verification results
+```
+
+### Enforcement
+```
+/goop-accept invoked:
+  IF CHRONICLE.md shows incomplete waves:
+    REFUSE: "Execution incomplete. [N] tasks remaining in Wave [M]."
+  IF blockers exist:
+    REFUSE: "Blockers unresolved: [list]"
+  ELSE:
+    PROCEED with acceptance
+```
+
+### Partial Completion Handling
+If some tasks are optional (nice-to-haves):
+1. Must-haves MUST all be complete
+2. Nice-to-haves MAY be deferred
+3. Deferred items logged in CHRONICLE.md
+4. User confirms proceeding without nice-to-haves
+
+---
+
+## Gate 4: Acceptance Gate
+
+### Location
+Between acceptance and completion (`/goop-accept` → `/goop-complete`)
+
+### Purpose
+User explicitly accepts the deliverable as meeting requirements.
+
+### Requirements
+| Requirement | Validation |
+|-------------|------------|
+| Verification report | goop-verifier produced report |
+| All must-haves PASS | Requirement matrix shows all green |
+| Security check | Security checklist reviewed |
+| User acceptance | Explicit "accept" from user |
+
+### State Check
+```json
+{
+  "phase": "accept",
+  "verification_passed": true,
+  "user_accepted": true,
+  "accepted_at": "[timestamp]"
+}
+```
+
+### Verification Report
+goop-verifier produces:
+```markdown
+## Verification Report
+
+### Must-Have Matrix
+
+| Requirement | Status | Evidence |
+|-------------|--------|----------|
+| [MH1] | PASS | [test/file/commit] |
+| [MH2] | PASS | [test/file/commit] |
+
+### Test Results
+- Unit: 42/42 passing
+- Integration: 8/8 passing
+- E2E: 3/3 passing
+
+### Security Review
+- [x] No hardcoded secrets
+- [x] Input validation present
+- [x] Auth checks on protected routes
+
+### Recommendation
+ACCEPT / REJECT with [reasons]
+```
+
+### Enforcement
+```
+/goop-complete invoked:
+  IF verification_passed != true:
+    REFUSE: "Verification not passed. Review report."
+  IF user_accepted != true:
+    REFUSE: "User acceptance required. Type 'accept' to proceed."
+  IF must-haves have FAIL status:
+    REFUSE: "Must-haves incomplete: [list]"
+  ELSE:
+    PROCEED with completion
+```
+
+### Acceptance Process
+1. Present verification report
+2. Highlight any concerns
+3. Request user acceptance: "Type 'accept' to complete this milestone"
+4. On accept: Archive milestone, extract learnings, reset for next
+
+---
+
+## Gate Bypass Protocol
+
+### When Bypass is Allowed
+
+| Gate | Bypass Allowed | Conditions |
+|------|----------------|------------|
+| Discovery | Yes | /goop-quick, bug fixes, docs-only |
+| Spec | No | Never - spec lock is fundamental |
+| Execution | Partial | Nice-to-haves may be deferred |
+| Acceptance | No | Never - user must accept |
+
+### Bypass Logging
+
+All bypasses MUST be logged:
+```typescript
+goop_adl({
+  action: "append",
+  type: "deviation",
+  description: "Discovery gate bypassed for quick task",
+  rule: 0,  // No rule applies
+  entry_action: "Proceeded with /goop-quick without interview"
+})
+```
+
+---
+
+## Gate State Machine
+
+```
+[idle]
+   │
+   ▼
+/goop-discuss
+   │
+   ▼
+[interview] ──── DISCOVERY GATE ────┐
+   │                                │
+   │ (interview_complete)           │ (bypass: /goop-quick)
+   ▼                                ▼
+/goop-plan                      [quick-execute]
+   │                                │
+   ▼                                ▼
+[plan] ────── SPEC GATE ───────────[done]
+   │
+   │ (spec_locked + user confirm)
+   ▼
+/goop-specify
+   │
+   ▼
+/goop-execute
+   │
+   ▼
+[execute] ─── EXECUTION GATE ──────┐
+   │                               │
+   │ (all tasks complete)          │ (blockers)
+   ▼                               ▼
+/goop-accept                    [blocked]
+   │
+   ▼
+[accept] ──── ACCEPTANCE GATE ─────┐
+   │                               │
+   │ (user accepts)                │ (verification fails)
+   ▼                               ▼
+/goop-complete                  [rework]
+   │
+   ▼
+[done] → archive → [idle]
+```
+
+---
+
+## Gate Failure Handling
+
+### Discovery Gate Failure
+```
+Message: "Discovery interview incomplete."
+Action: Run /goop-discuss to complete interview
+Recovery: Answer remaining questions
+```
+
+### Spec Gate Failure
+```
+Message: "Specification not ready for lock."
+Action: Review SPEC.md and BLUEPRINT.md
+Recovery: Complete traceability, get user confirm
+```
+
+### Execution Gate Failure
+```
+Message: "Execution incomplete."
+Action: Review CHRONICLE.md for remaining tasks
+Recovery: Complete tasks or defer nice-to-haves
+```
+
+### Acceptance Gate Failure
+```
+Message: "Verification failed."
+Action: Review verification report
+Recovery: Fix failing requirements, re-verify
+```
+
+---
+
+*Phase Gates Protocol v0.1.4*
+*"Quality requires discipline."*

package/references/plugin-architecture.md

@@ -0,0 +1,212 @@
+# GoopSpec Plugin Architecture
+
+This reference documents the plugin's tools, hooks, and features. Load this to understand how the plugin supports your work.
+
+---
+
+## Design Philosophy
+
+- **Memory-First**: Search before acting, save after completing
+- **State-Aware**: Check phase and gates before executing
+- **Phase Enforcement**: Actions are validated against workflow state
+- **Context Injection**: Relevant memory injected into every LLM call
+
+## Workflow Phases
+
+```
+idle → plan → research → specify → execute → accept → archive
+```
+
+## Key Directories
+
+| Directory | Purpose |
+|-----------|---------|
+| `.goopspec/` | Project state, specs, blueprints, chronicles |
+| `src/tools/` | MCP tool implementations |
+| `src/hooks/` | Event handlers for lifecycle |
+| `src/features/` | Feature modules (state, memory, enforcement) |
+
+---
+
+## Available Tools
+
+### Workflow/State Tools
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `goop_status` | Shows workflow state, phase, progress, pending tasks | `verbose` (boolean) |
+| `goop_setup` | Configures plugin, initializes projects | `action` (detect/init/plan/apply/verify/reset/models/status), `scope`, `projectName` |
+| `goop_adl` | Manages Automated Decision Log entries | `action` (read/append), `type` (decision/deviation/observation), `description`, `entry_action`, `rule`, `files` |
+| `goop_checkpoint` | Manages execution checkpoints for pause/resume | `action` (save/load/list), `id`, `context` (JSON) |
+| `goop_spec` | Reads/validates SPEC.md and PLAN.md files | `action` (read/list/validate), `phase`, `file` (spec/plan/both) |
+
+### Agent/Resource Tools
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `goop_delegate` | Prepares task for specialized agent with context injection | `agent`, `prompt`, `context`, `list` (boolean), `session_id` |
+| `goop_skill` | Loads step-by-step skill guidance | `name`, `list` (boolean) |
+| `goop_reference` | Loads protocols, checklists, templates | `name`, `type` (reference/template/all), `section`, `list` (boolean) |
+| `slashcommand` | Executes GoopSpec slash commands | `command` (string, e.g., "/goop-plan help") |
+
+### Memory Tools
+
+| Tool | Purpose | Key Parameters |
+|------|---------|----------------|
+| `memory_save` | Saves structured info to persistent memory | `title` (required), `content` (required), `type` (observation/decision/note/todo), `facts`, `concepts`, `importance` (1-10), `sourceFiles` |
+| `memory_search` | Hybrid semantic+keyword search across memories | `query` (required), `limit` (1-20), `types`, `concepts`, `minImportance` |
+| `memory_note` | Quick observation capture (simplified save) | `note` (required), `concepts` |
+| `memory_decision` | Records architectural decisions with structure | `decision` (required), `reasoning` (required), `alternatives`, `impact` (low/medium/high), `concepts` |
+| `memory_forget` | Deletes memories by ID or query | `id`, `query`, `confirm` (required for query-based) |
+| `session_search` | Searches past session history logs | `query`, `recent` (boolean), `limit`, `types` (tool_call/phase_change/etc), `startDate`, `endDate` |
+
+---
+
+## Hook System
+
+| Hook | Trigger | Effect |
+|------|---------|--------|
+| `chat.message` | User sends message | Updates `workflow.lastActivity`, captures significant prompts to memory |
+| `tool.execute.before` | Before tool runs | Caches arguments for post-execution analysis, tracks file states |
+| `tool.execute.after` | After tool completes | **Phase transitions**, memory capture, orchestrator enforcement, auto-progression, code quality warnings |
+| `event` | Session lifecycle (created/idle/deleted) | Continuation enforcer, session summaries, idle detection |
+| `permission.ask` | File permission request | **Blocks orchestrator from writing code** - denies file modifications in protected dirs |
+| `experimental.chat.system.transform` | Before LLM call | **Injects phase rules and relevant memories into system prompt** |
+
+### Critical Behaviors
+
+- **`tool.execute.after`**: Auto-progresses phases when conditions met (e.g., execute → accept when all waves complete)
+- **`permission.ask`**: Enforces the "Orchestrator vs Executor" boundary - orchestrator CANNOT write implementation files
+- **`system.transform`**: Injects `<goopspec_context>` block with current state, phase rules, and relevant memories
+
+---
+
+## Feature Modules
+
+| Feature | Location | Purpose |
+|---------|----------|---------|
+| **State Manager** | `src/features/state-manager/` | Central workflow persistence - phases, waves, ADL, checkpoints |
+| **Memory System** | `src/features/memory/` | Persistent semantic memory with SQLite + vector storage |
+| **Enforcement** | `src/features/enforcement/` | Phase-based action validation, file write blocking, required docs |
+| **Parallel Research** | `src/features/parallel-research/` | Concurrent multi-agent research orchestration |
+| **Mode Detection** | `src/features/mode-detection/` | Analyzes prompts to suggest quick/standard/comprehensive mode |
+| **Routing** | `src/features/routing/` | Maps task descriptions to appropriate agent categories |
+| **Archive** | `src/features/archive/` | Milestone archival, learnings extraction, retrospectives |
+| **Workflow Memory** | `src/features/workflow-memory/` | Phase-specific memory retrieval optimization |
+| **Setup** | `src/features/setup/` | Environment detection, config management, MCP setup |
+
+---
+
+## Integration Patterns
+
+### Memory-First Pattern
+
+Always search memory before starting work, save learnings after:
+
+```
+1. memory_search({ query: "[current task]", limit: 5 })  # Check what we know
+2. ... do work ...
+3. memory_save/memory_decision/memory_note({ ... })      # Persist learnings
+```
+
+### State-Aware Pattern
+
+Check state before taking actions:
+
+```
+1. goop_status()                    # Know current phase, gates, progress
+2. Read(".goopspec/state.json")     # Direct state access if needed
+3. Check phase allows intended action
+```
+
+### Phase Enforcement
+
+Hooks automatically enforce what's allowed in each phase:
+
+| Phase | Allowed Actions |
+|-------|-----------------|
+| `idle` | Any action allowed |
+| `plan` | Can create plans, cannot execute |
+| `specify` | Can lock spec, cannot execute |
+| `execute` | Can write code, must align to spec |
+| `accept` | Verification only, no new features |
+
+### Delegation Lifecycle
+
+How orchestrator delegates to specialized agents:
+
+```
+1. goop_delegate({ agent: "goop-executor", prompt: "...", context: "..." })
+2. Returns <goop_delegation> with prepared payload
+3. Orchestrator uses task() tool with the delegation
+4. Subagent executes, returns XML envelope response
+5. Orchestrator parses response, updates state/chronicle
+```
+
+---
+
+## Tool Quick Reference by Role
+
+| Agent | Primary Tools | When to Use |
+|-------|---------------|-------------|
+| **Orchestrator** | `goop_status`, `goop_checkpoint`, `slashcommand`, `goop_delegate` | Coordination, delegation, phase management |
+| **Executor** | `goop_spec`, `goop_adl`, `memory_save`, `memory_note` | Implementation, deviation logging, discovery capture |
+| **Planner** | `goop_spec`, `goop_reference`, `memory_decision` | Architecture decisions, template loading |
+| **Researcher** | `memory_save`, `memory_search`, `goop_skill`, `session_search` | Research persistence, prior work discovery |
+| **Verifier** | `goop_spec`, `goop_reference`, `memory_save`, `goop_adl` | Spec validation, security checklist, gap logging |
+| **Explorer** | `memory_save`, `memory_note`, `session_search` | Pattern cataloging, codebase insights |
+| **Debugger** | `goop_checkpoint`, `memory_search`, `memory_decision` | State snapshots, prior bugs, fix decisions |
+| **Designer** | `memory_search`, `memory_save`, `goop_skill` | Design patterns, component specs |
+| **Tester** | `memory_search`, `memory_save`, `goop_skill` | Test patterns, coverage findings |
+| **Writer** | `memory_search`, `memory_save`, `goop_reference` | Doc conventions, templates |
+| **Librarian** | `memory_search`, `memory_save`, `session_search` | Prior findings, synthesized results |
+| **Memory Distiller** | `session_search`, `memory_save` | Raw events → structured memories |
+
+---
+
+## Common Tool Patterns
+
+### Starting a Session
+
+```
+goop_status()                                    # Current state
+memory_search({ query: "[task]", limit: 5 })     # Prior context
+Read(".goopspec/SPEC.md")                        # Requirements
+Read(".goopspec/BLUEPRINT.md")                   # Plan
+```
+
+### Ending a Session
+
+```
+memory_save({ title: "...", content: "...", type: "observation" })
+goop_checkpoint({ action: "save", id: "session-end" })
+```
+
+### Recording a Decision
+
+```
+memory_decision({
+  decision: "Use Vitest for testing",
+  reasoning: "Better Bun integration, faster execution",
+  alternatives: ["Jest", "Mocha"],
+  impact: "high"
+})
+```
+
+### Logging a Deviation
+
+```
+goop_adl({
+  action: "append",
+  type: "deviation",
+  description: "Changed API structure from spec",
+  entry_action: "Modified endpoint to accept array instead of object",
+  files: ["src/api/handler.ts"]
+})
+```
+
+---
+
+## Version
+
+Plugin Architecture Reference v0.1.4

package/references/response-format.md

@@ -1,16 +1,22 @@
 # Agent Response Format
 
-All GoopSpec subagents MUST return structured responses to the orchestrator. This enables clean handoffs, progress tracking, and next-step clarity.
+All GoopSpec subagents MUST return structured responses to the orchestrator using XML envelopes. This enables clean handoffs, progress tracking, and machine-parseable next-step clarity.
 
-## Core Principle
+## Core Principles
 
 ```
-╔════════════════════════════════════════════════════════════════╗
-║  EVERY RESPONSE MUST ANSWER THREE QUESTIONS:                   ║
-║  1. What did I do?                                              ║
-║  2. What is the current state?                                  ║
-║  3. What should happen next?                                    ║
-╚════════════════════════════════════════════════════════════════╝
++================================================================+
+|  EVERY RESPONSE MUST ANSWER THREE QUESTIONS:                    |
+|  1. What did I do?                                               |
+|  2. What is the current state?                                   |
+|  3. What should happen next?                                     |
++================================================================+
+
++================================================================+
+|  USE XML ENVELOPE FOR MACHINE PARSING.                          |
+|  Keep Markdown content inside for human readability.            |
+|  See references/xml-response-schema.md for full specification.  |
++================================================================+
 ```
 
 ## Response Structure
@@ -369,18 +375,44 @@ When a checkpoint is needed (user decision, verification, or manual action):
 **[For action]:** Type "done" when complete
 ```
 
+## XML Envelope Requirement
+
+**All responses MUST end with an XML envelope.** The Markdown content provides human readability; the XML provides machine-parseable structure for the orchestrator.
+
+See `references/xml-response-schema.md` for the complete specification.
+
+**Minimal XML envelope:**
+
+```xml
+<goop_report version="0.1.4">
+  <status>COMPLETE</status>
+  <agent>goop-[type]</agent>
+  <summary>Brief summary</summary>
+  <handoff>
+    <ready>true</ready>
+    <next_action agent="goop-[type]">Next task</next_action>
+  </handoff>
+</goop_report>
+```
+
 ## Anti-Patterns
 
 **NEVER return:**
 - "Done" (no context)
 - "It works now" (no verification)
+- Responses without XML envelope
 - Responses without NEXT STEPS
 - Unstructured text walls
 - Missing status indicators
 
 **ALWAYS include:**
-- Clear status header
+- Clear status header (Markdown)
 - Summary of work
 - Files touched
 - Memory persistence
 - NEXT STEPS section
+- XML envelope at the end
+
+---
+
+*Response Format v0.1.4*