opencode-goopspec 0.1.2 → 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/ui-interaction-patterns.md

@@ -0,0 +1,133 @@
+# UI Interaction Patterns
+
+**GoopSpec Voice:** Clean, Consistent, Terminal-First.
+
+Our UI communicates reliability and structured thinking. It distinguishes between *information*, *questions*, and *gates*.
+
+## Visual Language
+
+*   **Hexagon (`⬢`):** The GoopSpec anchor. Use for system messages and prompts.
+*   **Borders:** Use for Gates and Checkpoints to arrest attention.
+*   **Indentation:** Hierarchy is meaning.
+*   **Colors:** (Implicit)
+    *   **Blue/Cyan:** Info & Progress
+    *   **Green:** Success & Memory Recall
+    *   **Yellow:** Warning & Checkpoints
+    *   **Red:** Errors & Blockers
+
+---
+
+## Interaction Primitives
+
+### 1. The Inline Notice
+*For status updates, memory recalls, and skill activations.*
+
+**Format:** `⬢ [Category] Message`
+
+```text
+⬢ Memory: Using preference "TypeScript Strict Mode"
+⬢ Skill: Loading "octocode-research"...
+⬢ Status: Analyzing dependency tree...
+```
+
+### 2. The Structured Prompt
+*For standard questions and choices.*
+
+**Format:** Question followed by clear options.
+
+```text
+⬢ Decision Required: Database Selection
+  
+  1. PostgreSQL (Recommended based on project)
+  2. SQLite (Simpler setup)
+  
+  ► Select [1-2]: 
+```
+
+### 3. The Gate (Boxed)
+*For critical stops: Contract, Checkpoint, Acceptance.*
+
+**Format:** ASCII Box with Title and Action.
+
+```text
+╭─ ⬢ GoopSpec ───────────────────────────────────────╮
+│                                                    │
+│  🔒 CONTRACT GATE                                  │
+│                                                    │
+│  Summary: Login Feature                            │
+│  • Auth Provider: Auth0                            │
+│  • MFA: Required                                   │
+│                                                    │
+│  ► Type "confirm" to Lock Spec and Plan.           │
+│                                                    │
+╰────────────────────────────────────────────────────╯
+```
+
+---
+
+## Patterns
+
+### The "Recall & Confirm"
+*Don't just apply memory silently; validate it lightly.*
+
+```text
+⬢ Memory: I see you use Tailwind in other projects.
+  Apply Tailwind to this project too? [Y/n]
+```
+
+### The "Skill Injection"
+*Show that an agent is doing deep work.*
+
+```text
+⬢ Researching: "Best state management for Svelte 5"
+  └─ ⚡ Found 3 relevant libraries
+  └─ ⚡ Analyzed GitHub stars & issues
+  
+  Recommendation: Runes (Native)
+```
+
+### The "Progressive Drill-Down"
+*Handle complexity without overwhelm.*
+
+**Step 1 (High Level):**
+```text
+⬢ Strategy: I recommend a "Feature Folder" structure.
+  Proceed? [Y/n/details]
+```
+
+**Step 2 (If 'details' selected):**
+```text
+⬢ Feature Folder Structure:
+  src/features/auth/
+    ├── components/
+    ├── api/
+    └── types.ts
+  
+  Pros: Scalable, self-contained.
+  Cons: More initial boilerplate.
+  
+  ► Confirm structure? [Y/n]
+```
+
+---
+
+## Anti-Patterns (Don't Do This)
+
+*   **The Wall of Text:** unstructured paragraphs mixing info and questions.
+*   **The Hidden Question:** burying a question in the middle of a log.
+*   **The "Double Ask":** asking for info, then asking for confirmation of the info in the same turn.
+*   **The "Fake Choice":** offering options that are clearly bad/wrong.
+
+---
+
+## Checklist: UI Audit
+
+- [ ] **Is the Hexagon present?** (Brand anchor)
+- [ ] **Is the hierarchy clear?** (Indentation)
+- [ ] **Are options numbered or binary?** (Ease of input)
+- [ ] **Is the critical info boxed?** (Gates)
+- [ ] **Did I acknowledge memory/skills?** (Show intelligence)
+
+---
+
+**Goal:** The user should be able to scan the output and know exactly *where they are* and *what they need to do*.

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*