opencode-goopspec 0.1.2 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goopspec",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "A spec-driven development plugin for OpenCode with user-guided planning, wave execution, and verification",
   "type": "module",
   "main": "dist/index.js",

package/references/interactive-questioning.md

@@ -0,0 +1,122 @@
+# Interactive Questioning Protocol
+
+**GoopSpec Voice:** Direct, Purposeful, Memory-First.
+
+We use interactive questioning to trade ambiguity for clarity without halting momentum. Every question must earn its right to interrupt the user.
+
+## Core Philosophy
+
+1.  **Memory First:** Never ask what you already know.
+2.  **Gate-Oriented:** Questions should drive towards a Decision Gate (Contract, Checkpoint, Acceptance).
+3.  **Skill-Backed:** Use skills to frame questions intelligently, not just to gather data.
+4.  **Progressive:** Start high-level; drill down only when necessary.
+
+---
+
+## 1. Memory-Aware Questioning
+
+Before formulating a question, you **MUST** search memory.
+
+### The Protocol
+1.  **Search:** `memory_search({ query: "[topic] preference" })`
+2.  **Evaluate:** Do I have a high-confidence answer (Importance > 7)?
+3.  **Action:**
+    *   **High Confidence:** Use it. Inform user: "Using saved preference for X."
+    *   **Medium Confidence:** Confirm. "I recall you prefer X. Still true?"
+    *   **No Data:** Ask. Then **SAVE** the answer.
+
+### Examples
+
+**❌ Bad (Amnesic):**
+> "What database should we use?"
+*(User has answered this 5 times before)*
+
+**✅ Good (Memory-Aware):**
+> ⬢ **Memory Recall:** You prefer **PostgreSQL** for new services.
+> Proceeding with Postgres? [Y/n]
+
+---
+
+## 2. Skill-Aware Questioning
+
+Don't just ask "What do you want?". Use loaded skills to provide *informed options*.
+
+### The Protocol
+1.  **Consult Skill:** Use `research` or `security` or `architecture` skills to analyze the situation.
+2.  **Frame Options:** Present choices based on expert analysis.
+3.  **Ask:** specific, constrained questions.
+
+### Examples
+
+**❌ Bad (Generic):**
+> "How should we handle authentication?"
+
+**✅ Good (Skill-Backed - Security):**
+> ⬢ **Security Skill Analysis:**
+> For this stack, I recommend **OAuth2 with PKCE** for these reasons:
+> 1. Matches your security baseline.
+> 2. Best support for mobile clients.
+>
+> **Decision:** Implement OAuth2? [Y/n] or "Explain alternatives"
+
+---
+
+## 3. Decision Gates
+
+Use formal Gates for high-impact questions. Stop the world.
+
+### Contract Gate (Planning Phase)
+*Must resolve scope before work begins.*
+
+> **Question:** "Are these MUST-HAVES correct and complete?"
+> **Trigger:** `/goop-specify`
+> **Action:** Lock SPEC.md upon confirmation.
+
+### Checkpoint Gate (Execution Phase)
+*Stop for architectural forks in the road.*
+
+> **Question:** "I found two valid patterns. A is faster, B is more scalable. Which path?"
+> **Trigger:** Rule 4 (Architectural Decision).
+> **Action:** Wait for user selection.
+
+### Acceptance Gate (Completion Phase)
+*Verify completion against the contract.*
+
+> **Question:** "I have verified requirements A, B, and C. Ready to accept?"
+> **Trigger:** `/goop-accept`
+> **Action:** Archive task and update memory.
+
+---
+
+## 4. Progressive Disclosure
+
+Don't wall-of-text the user. Reveal complexity in layers.
+
+### Level 1: The "Happy Path" Proposal
+State the most likely path and ask for confirmation.
+> "I plan to use **React Hook Form** for this form. Proceed?"
+
+### Level 2: The Fork
+If rejected or ambiguous, offer distinct high-level options.
+> "Okay. Options:
+> 1. **React Hook Form** (Standard, performant)
+> 2. **Formik** (Legacy compatibility)
+> 3. **Raw State** (Simple forms only)"
+
+### Level 3: The Deep Dive
+Only if requested, show full tradeoffs.
+> "Here is the detailed comparison of bundle size, re-render performance, and API surface..."
+
+---
+
+## Checklist: Before You Ask
+
+- [ ] **Did I search memory?** (Don't be amnesic)
+- [ ] **Is this a "One-Way Door" decision?** (If yes, use a Gate)
+- [ ] **Can I propose a default instead?** (Bias for action)
+- [ ] **Is the question binary or multiple choice?** (Reduce cognitive load)
+- [ ] **Am I ready to save the answer?** (Build the knowledge base)
+
+---
+
+**Remember:** Every question is a context switch. Make it count.

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/workflow-accept.md

@@ -1,17 +1,12 @@
 # Workflow: Accept Phase
 
-The Accept phase verifies the implementation against the specification and obtains user sign-off.
+**GoopSpec Voice:** Critical, Celebratory, Final.
+
+The Accept phase answers: **Did we deliver what we promised?** It is the final quality gate.
 
 ## Position in Workflow
 
 ```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│    PLAN     │ ──▶ │  RESEARCH   │ ──▶ │   SPECIFY   │
-│  (Intent)   │     │  (Explore)  │     │ (Contract)  │
-└─────────────┘     └─────────────┘     └─────────────┘
-                                              │
-       ┌──────────────────────────────────────┘
-       ▼
 ┌─────────────┐     ┌─────────────┐
 │   EXECUTE   │ ──▶ │   ACCEPT    │
 │   (Build)   │     │  (Verify)   │
@@ -20,117 +15,31 @@ The Accept phase verifies the implementation against the specification and obtai
                     (You are here)
 
        ╔══════════════════════════════════════════════╗
-       ║          ACCEPTANCE GATE                      ║
+       ║          ACCEPTANCE GATE                     ║
        ║   User MUST confirm completion               ║
        ╚══════════════════════════════════════════════╝
 ```
 
-## Purpose
-
-The Accept phase answers: **Did we deliver what we promised?**
-
-This is the final verification against the locked specification. The user confirms the work is complete before it's considered done.
-
-## Entry Criteria
-
-- Execute phase complete
-- All tasks finished
-- All tests passing
-- CHRONICLE.md updated
-
-## Verification Activities
-
-### 1. Spec Compliance Check
-
-Verify each must-have from SPEC.md:
-
-```markdown
-## Must-Have Verification
-
-| Requirement | Status | Evidence |
-|-------------|--------|----------|
-| User can log in | ✓ | Test: auth.test.ts:15 |
-| Session persists | ✓ | Test: session.test.ts:42 |
-| Error messages shown | ✓ | Manual verification |
-```
-
-### 2. Automated Verification
-
-Run all quality gates:
-
-```bash
-# Type checking
-npm run typecheck
+## Verification Protocol
 
-# Linting
-npm run lint
+Before asking the user, the agent runs the **Verifier**.
 
-# Tests
-npm test
+### 1. Automated Checks
+*   Linting
+*   Type Checking
+*   Unit/Integration Tests
+*   Build Verification
 
-# Build
-npm run build
-```
-
-### 3. Manual Verification
+### 2. Spec Compliance
+Compare `CHRONICLE.md` against `SPEC.md`.
+*   Are all "Must Haves" marked complete?
+*   Are there any open deviations?
 
-For behaviors that can't be automated:
+## The Acceptance Gate
 
-```markdown
-## Manual Verification Checklist
+Present the evidence clearly.
 
-- [ ] Login flow works end-to-end
-- [ ] Error states display correctly
-- [ ] Mobile responsive (if applicable)
-- [ ] Accessibility check (keyboard nav, screen reader)
-```
-
-### 4. Security Audit (If Applicable)
-
-For security-sensitive features:
-
-```markdown
-## Security Verification
-
-- [ ] Input validation present
-- [ ] No hardcoded secrets
-- [ ] Auth/authz properly enforced
-- [ ] No obvious vulnerabilities
-```
-
-## Verifier Agent
-
-Delegate comprehensive verification to goop-verifier:
-
-```
-task({
-  subagent_type: "general",
-  description: "Verify spec",
-  prompt: `
-    Verify implementation against specification.
-    
-    SPEC: .goopspec/SPEC.md
-    CHRONICLE: .goopspec/CHRONICLE.md
-    
-    Verify:
-    1. All must-haves implemented
-    2. Acceptance criteria met
-    3. No regressions introduced
-    4. Security considerations addressed
-    5. Code quality standards met
-    
-    Return: Detailed verification report
-  `
-})
-```
-
-## Acceptance Gate
-
-**CRITICAL**: User MUST explicitly accept the work.
-
-### Acceptance Prompt
-
-```
+```text
 ╭─ ⬢ GoopSpec ───────────────────────────────────────╮
 │                                                    │
 │  ✓ ACCEPTANCE GATE                                 │
@@ -138,188 +47,66 @@ task({
 │  Implementation complete. Verification results:    │
 │                                                    │
 │  MUST HAVES:                                       │
-│  ☑ User can log in - VERIFIED                      │
-│  ☑ Session persists - VERIFIED                     │
-│  ☑ Errors displayed - VERIFIED                     │
+│  ☑ Login Form - VERIFIED                           │
+│  ☑ API Integration - VERIFIED                      │
 │                                                    │
-│  AUTOMATED CHECKS:                                 │
-│  ✓ TypeScript: No errors                           │
-│  ✓ Lint: No issues                                 │
-│  ✓ Tests: 24/24 passing                            │
-│  ✓ Build: Successful                               │
-│                                                    │
-│  NICE TO HAVES COMPLETED:                          │
-│  ☑ Remember me option                              │
+│  QUALITY METRICS:                                  │
+│  ✓ Tests: 14/14 Passing                            │
+│  ✓ Build: Success                                  │
 │                                                    │
 │  ─────────────────────────────────────────────     │
-│  Type "accept" to confirm completion.              │
-│  Type "issues: [description]" to request fixes.    │
+│  ► Type "accept" to Archive and Complete.          │
+│  ► Type "issues: [details]" to Reject.             │
 │                                                    │
 ╰────────────────────────────────────────────────────╯
 ```
 
-### Acceptance Responses
-
-| Response | Effect |
-|----------|--------|
-| `accept` | Work marked complete, proceed to archive |
-| `issues: [desc]` | Return to Execute phase for fixes |
-| `amend: [change]` | Modify spec, reassess what's needed |
-
-## Post-Acceptance
-
-After user accepts:
-
-### 1. Generate Summary
+## Handling Rejection
 
-```markdown
-# Summary: [Feature Name]
+If the user types `issues: ...`:
+1.  **Log:** Create a new "Fix" Wave in `BLUEPRINT.md`.
+2.  **Execute:** Return to Execute Phase.
+3.  **Verify:** Re-run verification.
+4.  **Gate:** Re-present Acceptance Gate.
 
-**Completed:** [timestamp]
-**Duration:** [time]
-**Tasks:** 12 completed
-**Commits:** 12
+## Completion Activities
 
-## Delivered
-- Must-have 1 ✓
-- Must-have 2 ✓
-- Nice-to-have 1 ✓ (bonus)
+Once accepted:
 
-## Key Decisions
-- Used jose library for JWT (better ESM support)
-- Stored refresh tokens in httpOnly cookies
+1.  **Archive:** Move documents to `.goopspec/archive/`.
+2.  **Retrospective:** Generate `RETROSPECTIVE.md`.
+3.  **Memory Extraction:** The most important step for future intelligence.
 
-## Files Modified
-- src/auth/login.ts (new)
-- src/auth/session.ts (new)
-- src/routes/api.ts (modified)
-```
-
-### 2. Archive (For Milestones)
-
-If this completes a milestone:
+### Memory Extraction
+Extract **Patterns**, **Decisions**, and **Learnings**.
 
-```
-/goop-complete
-```
-
-This triggers:
-1. Move to archive/
-2. Generate RETROSPECTIVE.md
-3. Extract LEARNINGS.md
-4. Persist learnings to memory
-5. Tag git with version
-
-### 3. Clean Up
-
-- Clear active workflow state
-- Keep SPEC.md and CHRONICLE.md for reference
-- Ready for next task
-
-## Handling Issues
-
-### Minor Issues
-
-Issues that don't fundamentally change the spec:
-
-```
-User: "issues: Login button color should be blue, not gray"
-
-Agent:
-1. Note as fix task
-2. Delegate quick fix
-3. Re-verify affected area
-4. Present for re-acceptance
-```
-
-### Major Issues
-
-Issues that reveal missing requirements:
-
-```
-User: "issues: Wait, it also needs OAuth support"
-
-Agent:
-1. Note as spec change
-2. Prompt for `/goop-amend`
-3. Update SPEC.md
-4. Re-plan affected tasks
-5. Execute additions
-6. Re-verify
-```
-
-## Verification Report
-
-Full verification saved to CHRONICLE.md:
-
-```markdown
-## Verification Report
-
-**Date:** [timestamp]
-**Verifier:** goop-verifier
-
-### Spec Compliance
-| Must-Have | Status | Evidence |
-|-----------|--------|----------|
-| Req 1 | PASS | test:auth:15 |
-| Req 2 | PASS | test:session:42 |
-
-### Quality Metrics
-- TypeScript: Clean
-- Lint: Clean
-- Test Coverage: 87%
-- Build: Success
-
-### Security Review
-- Input validation: Present
-- Auth checks: Proper
-- No secrets: Verified
-
-### Recommendation
-READY FOR ACCEPTANCE
-```
-
-## Quick Mode Accept
-
-For Quick tasks:
-- Abbreviated verification
-- No formal report
-- Quick confirmation prompt
-- Direct archive to quick/
-
-## Memory Protocol
-
-### Before Verifying
-```
-memory_search({ 
-  query: "verification patterns, past issues",
-  types: ["observation"]
-})
-```
-
-### During Verification
-```
-memory_note({
-  note: "Verification passed for [feature]"
-})
-```
-
-### After Acceptance
-```
+```javascript
+// Example Extraction
 memory_save({
   type: "observation",
-  title: "Feature Accepted: [name]",
-  content: "[summary of delivered work]",
-  concepts: ["completed", "patterns-used"],
-  importance: 0.7
+  title: "Completed: Auth Feature",
+  content: "Successfully implemented Auth0. Key learning: User prefers JWT over session cookies.",
+  concepts: ["auth", "completion", "preference"],
+  importance: 0.9 // High importance for future recall
 })
 ```
 
 ## Commands
 
 | Command | Effect |
-|---------|--------|
-| `/goop-accept` | Trigger acceptance verification |
-| `/goop-status` | Check verification status |
-| `/goop-complete` | Complete and archive milestone |
-| `/goop-amend [change]` | Modify spec if issues found |
+| :--- | :--- |
+| `/goop-accept` | Trigger the Acceptance Gate. |
+| `/goop-complete` | Finalize, archive, and reset state. |
+| `/goop-milestone` | Start a new milestone after completion. |
+
+## The "Celebrate" Pattern
+
+End on a high note.
+
+```text
+⬢ Milestone Completed: Auth Feature 🚀
+  Saved to Archive: .goopspec/archive/v1.0-auth/
+  Memory Updated: +3 new patterns
+  
+  Ready for next plan?
+```