opencode-goopspec 0.1.2 → 0.1.3

package/references/workflow-execute.md

@@ -1,17 +1,12 @@
 # Workflow: Execute Phase
 
-The Execute phase implements the specification through wave-based task execution.
+**GoopSpec Voice:** Industrial, Atomic, Transparent.
+
+The Execute phase answers: **Build exactly what the spec says.** Implementation happens in **Waves**.
 
 ## Position in Workflow
 
 ```
-┌─────────────┐     ┌─────────────┐     ┌─────────────┐
-│    PLAN     │ ──▶ │  RESEARCH   │ ──▶ │   SPECIFY   │
-│  (Intent)   │     │  (Explore)  │     │ (Contract)  │
-└─────────────┘     └─────────────┘     └─────────────┘
-                                              │
-       ┌──────────────────────────────────────┘
-       ▼
 ┌─────────────┐     ┌─────────────┐
 │   EXECUTE   │ ──▶ │   ACCEPT    │
 │   (Build)   │     │  (Verify)   │
@@ -20,296 +15,90 @@ The Execute phase implements the specification through wave-based task execution
  (You are here)
 ```
 
-## Purpose
-
-The Execute phase answers: **Build exactly what the spec says.**
-
-Implementation happens in waves, with the orchestrator coordinating specialized subagents. Progress is tracked in CHRONICLE.md.
-
-## Entry Criteria
-
-- Specify phase complete
-- SPEC.md locked and confirmed
-- BLUEPRINT.md ready with waves and tasks
+## Core Protocol: The Wave Cycle
 
-## Wave-Based Execution
+Execution is not a monolith. It is a series of controlled loops.
 
-### Wave Structure
+**1. The Wave:** A logical grouping of tasks (e.g., "Foundation", "Core", "Polish").
+**2. The Task:** A single, atomic unit of work (one commit).
+**3. The Checkpoint:** A mandatory pause for verification or decision.
 
-```
-Wave 1: Foundation
-  ├── Task 1.1: Setup
-  ├── Task 1.2: Configuration
-  └── Task 1.3: Base structures
-
-Wave 2: Core
-  ├── Task 2.1: Main feature
-  ├── Task 2.2: Business logic
-  └── Task 2.3: Data handling
-
-Wave 3: Integration
-  ├── Task 3.1: Connect components
-  └── Task 3.2: Wire to existing system
-
-Wave 4: Polish
-  ├── Task 4.1: Error handling
-  ├── Task 4.2: Edge cases
-  └── Task 4.3: Documentation
-```
-
-### Wave Principles
-
-1. **Sequential waves** - Wave N completes before Wave N+1 starts
-2. **Vertical slices** - Each wave delivers working functionality
-3. **Atomic commits** - Each task = one commit
-4. **Verification gates** - Tests must pass between waves
-
-## Orchestrator Role
-
-The orchestrator is a CONDUCTOR - it coordinates but NEVER writes code.
-
-### Orchestrator Does
-- Delegate tasks to subagents
-- Track progress in CHRONICLE.md
-- Apply deviation rules
-- Coordinate between waves
-- Handle blockers
-
-### Orchestrator Does NOT
-- Write implementation code
-- Make architectural decisions alone
-- Modify files directly
-- "Quickly fix" things itself
-
-### Delegation Pattern
-
-```
-task({
-  subagent_type: "general",
-  description: "Execute auth task",
-  prompt: `
-    Execute Task 2.1: Implement user authentication
-    
-    SPEC Reference: .goopspec/SPEC.md
-    BLUEPRINT: .goopspec/BLUEPRINT.md
-    
-    Files to modify:
-    - src/auth/login.ts
-    - src/auth/session.ts
-    
-    Acceptance criteria:
-    - User can log in with email/password
-    - Session persists across refresh
-    
-    Constraints:
-    - Follow existing patterns in src/auth/
-    - Use jose library (per RESEARCH.md)
-  `
-})
-```
+### Orchestrator's Role (The Conductor)
+*   **Delegate:** Hand tasks to `goop-executor` (Subagent).
+*   **Track:** Update `CHRONICLE.md`.
+*   **Verify:** Ensure tests pass between tasks.
+*   **Correct:** Apply Deviation Rules (Auto-fix vs. Ask).
 
-## Task Execution Flow
+## Interaction Patterns
 
-For each task:
+### 1. Progress Updates
+Keep the user informed without spamming. Use "Inline Notices".
 
+```text
+⬢ Wave 1: Foundation
+  ├─ ⚡ Task 1.1: Setup Provider... [DONE] (abc1234)
+  └─ ⚡ Task 1.2: Login Component... [IN PROGRESS]
 ```
-1. Read task from BLUEPRINT.md
-2. Check deviation rules (can auto-fix?)
-3. Delegate to appropriate agent
-4. Agent implements with memory protocol
-5. Agent commits atomically
-6. Update CHRONICLE.md
-7. Verify (tests pass?)
-8. Move to next task or wave
-```
-
-### Task Types
-
-| Type | Behavior |
-|------|----------|
-| `auto` | Execute automatically via delegation |
-| `checkpoint:verify` | Pause for user verification |
-| `checkpoint:decision` | Pause for user decision |
-| `checkpoint:action` | Pause for user action |
 
-### Checkpoint Handling
+### 2. The Checkpoint Gate
+When the blueprint calls for a pause, or a **Rule 4 (Architectural Decision)** is triggered.
 
-```markdown
-### Task 2.4 (checkpoint:verify): Verify Auth Flow
-
-**What Built:** Authentication system
-**How to Verify:**
-1. Start dev server
-2. Navigate to /login
-3. Test with credentials
-
-**Resume Signal:** "verified" or list issues
+```text
+╭─ ⬢ GoopSpec ───────────────────────────────────────╮
+│                                                    │
+│  🚧 CHECKPOINT REACHED                             │
+│                                                    │
+│  Task: Configure OAuth Callbacks                   │
+│                                                    │
+│  I need a callback URL for the production env.     │
+│  Currently using: localhost:3000                   │
+│                                                    │
+│  ► Please provide the Production URL:              │
+│                                                    │
+╰────────────────────────────────────────────────────╯
 ```
 
-When checkpoint reached:
-1. Save state to CHRONICLE.md
-2. Present verification instructions
-3. Wait for user signal
-4. Resume or address issues
+### 3. Deviation Handling
+*   **Rule 1-3 (Minor):** Auto-fix and log.
+    *   `⬢ Notice: Auto-fixed missing import in auth.ts`
+*   **Rule 4 (Major):** Stop and Ask (Checkpoint Gate).
 
-## CHRONICLE.md Tracking
+## Output: CHRONICLE.md
 
-Progress tracked in real-time:
+The living history of execution.
 
 ```markdown
-# Chronicle: [Feature Name]
-
-## Current State
-- Phase: Execute
-- Wave: 2 of 4
-- Task: 2.3 of 3
-- Status: In Progress
-
-## Wave History
+# Chronicle
+## Wave 1 [COMPLETE]
+- [x] Task 1.1 (commit: 7f8a9d)
+- [x] Task 1.2 (commit: 3b2c1a)
 
-### Wave 1: Foundation [COMPLETE]
-- [x] Task 1.1: Setup (commit: abc123)
-- [x] Task 1.2: Config (commit: def456)
-- [x] Task 1.3: Base (commit: ghi789)
-
-### Wave 2: Core [IN PROGRESS]
-- [x] Task 2.1: Auth (commit: jkl012)
-- [x] Task 2.2: Logic (commit: mno345)
-- [ ] Task 2.3: Data [WORKING]
-
-### Wave 3: Integration [PENDING]
-...
-
-## Deviations
-- DEV-001: Fixed missing validation (Rule 2)
-- DEV-002: Added error handler (Rule 2)
-
-## Blockers
-- (none currently)
+## Wave 2 [IN PROGRESS]
+- [ ] Task 2.1
 ```
 
-## Deviation Handling
-
-Apply deviation rules during execution:
-
-| Rule | Trigger | Action |
-|------|---------|--------|
-| Rule 1 | Bug found | Auto-fix |
-| Rule 2 | Missing critical functionality | Auto-add |
-| Rule 3 | Blocking issue | Auto-fix |
-| Rule 4 | Architectural decision | STOP and ask |
-
-All deviations logged to CHRONICLE.md.
-
 ## Commit Protocol
 
-### Commit Format
+*   **Atomic:** One task = One commit.
+*   **Conventional:** `feat(auth): add login form`.
+*   **Verified:** Tests MUST pass (or be skipped with reason) before commit.
 
-```
-type(wave-task): description
-
-- Change 1
-- Change 2
-```
-
-### Commit Timing
-
-- One commit per completed task
-- NEVER batch multiple tasks
-- NEVER commit incomplete work (except checkpoints)
-
-### Pre-Commit Checks
-
-Before each commit:
-1. Run linter
-2. Run type checker
-3. Run relevant tests
-4. Verify changes match task
-
-## Error Recovery
-
-### On Task Failure
-
-1. Log error to CHRONICLE.md
-2. Attempt auto-recovery (deviation rules)
-3. If 3 failures: pause and notify user
-
-### On Agent Context Overflow
-
-1. Save checkpoint
-2. Spawn fresh agent with handoff:
-   - Current spec reference
-   - Incomplete tasks
-   - Recent decisions
-3. Resume from checkpoint
-
-## Continuation Enforcement
-
-The agent CANNOT stop with incomplete tasks:
-
-- Incomplete todos = forced continuation
-- Only checkpoints allow pause
-- User must explicitly confirm completion
-- Max continuation prompts before escalation
-
-## Transition to Accept Phase
-
-Execute phase is complete when:
-
-- [ ] All waves executed
-- [ ] All tasks completed
-- [ ] All tests passing
-- [ ] All deviations logged
-- [ ] CHRONICLE.md up to date
-
-**Transition:**
-```
-"Execution complete.
-
-Tasks: 12/12 completed
-Commits: 12 atomic commits
-Tests: All passing
-
-Ready for acceptance verification?"
-```
-
-## Memory Protocol
+## Commands
 
-### Before Starting
-```
-memory_search({ 
-  query: "past implementation patterns for [feature]",
-  concepts: ["implementation"]
-})
-```
+| Command | Effect |
+| :--- | :--- |
+| `/goop-execute` | Start or resume execution. |
+| `/goop-pause` | Pause at next safe checkpoint. |
+| `/goop-status` | Show current Wave/Task progress. |
+| `/goop-checkpoint` | Force a checkpoint save. |
 
-### During Execution
-```
-memory_note({ 
-  note: "Pattern discovered: [description]" 
-})
+## Memory Triggers
 
-memory_decision({
-  decision: "Used approach X over Y",
-  reasoning: "[rationale]"
-})
-```
+*   **Note:** Implementation details ("Used X library version Y").
+*   **Observation:** Issues encountered and how they were fixed.
 
-### After Completing
-```
-memory_save({
-  type: "observation",
-  title: "Execution: [feature] complete",
-  content: "[summary of approach taken]",
-  concepts: ["patterns-used"]
+```javascript
+memory_note({
+  note: "Fixed build error in Task 1.2 by upgrading dependency Z."
 })
 ```
-
-## Commands
-
-| Command | Effect |
-|---------|--------|
-| `/goop-execute` | Start/resume execution |
-| `/goop-status` | Check execution progress |
-| `/goop-checkpoint` | Save progress manually |
-| `/goop-pause` | Pause execution |

package/references/workflow-plan.md

@@ -1,6 +1,8 @@
 # Workflow: Plan Phase
 
-The Plan phase captures user intent and establishes the foundation for all subsequent work.
+**GoopSpec Voice:** Direct, Purposeful, Memory-First.
+
+The Plan phase captures user intent and establishes the foundation for all subsequent work. It answers: **What does the user want and why?**
 
 ## Position in Workflow
 
@@ -13,167 +15,118 @@ The Plan phase captures user intent and establishes the foundation for all subse
 (You are here)
 ```
 
-## Purpose
-
-The Plan phase answers: **What does the user want and why?**
-
-This is NOT about HOW to build it - that comes later. The Plan phase focuses purely on understanding intent, constraints, and success criteria.
-
-## Entry Criteria
-
-- User has expressed a need or request
-- Orchestrator has classified the work (Quick, Standard, Comprehensive, Milestone)
-
-## Activities
+## Core Protocol
 
-### 1. Intent Capture
+### 1. Memory-First Context Loading
+**Before** asking the user anything, the agent **MUST** search memory.
 
-Extract the core intent from the user's request:
-
-```markdown
-## Intent
-
-**User wants to:** [Action] [Target] [Context]
-**Because:** [Motivation/Problem being solved]
-**Success looks like:** [Observable outcome]
+```javascript
+// Search for similar past requests, preferences, and project context
+memory_search({ query: "intent similar requests [project_name]" })
 ```
 
-### 2. Clarifying Questions
-
-Ask questions to resolve ambiguity:
+### 2. Intent Capture
+Extract the core intent using the **Interactive Questioning Protocol**.
 
-- **Scope questions:** "Should this include X or just Y?"
-- **Priority questions:** "Is A more important than B?"
-- **Constraint questions:** "Are there performance/security requirements?"
-- **Integration questions:** "How should this work with existing feature Z?"
+*   **Goal:** Move from "vague request" to "structured intent".
+*   **Method:** Progressive Disclosure.
 
-**Rule:** If ambiguity could lead to 2x+ effort difference, MUST ask before proceeding.
+**Example Interaction:**
+```text
+⬢ User Request: "I need a login page."
 
-### 3. Requirements Gathering
-
-Categorize requirements:
-
-```markdown
-## Requirements
-
-### Must Have (Non-negotiable)
-- Requirement 1
-- Requirement 2
-
-### Should Have (Important)
-- Requirement 3
-- Requirement 4
-
-### Could Have (Nice to have)
-- Requirement 5
-
-### Won't Have (Explicitly excluded)
-- Out of scope item 1
+⬢ Memory Recall: You prefer **Auth0** for authentication (Confidence: High).
+  Proceed with Auth0? [Y/n]
 ```
 
-### 4. Constraint Identification
+### 3. The "Why" and "Success"
+Every plan must have a defined outcome.
 
-Document known constraints:
+*   **Intent:** Action + Target + Context.
+*   **Motivation:** Why now? What problem does this solve?
+*   **Success Criteria:** Observable outcomes (e.g., "User can log in", "Response time < 200ms").
 
-- Technical constraints (existing stack, compatibility)
-- Time constraints (deadlines, urgency)
-- Resource constraints (budget, team)
-- Business constraints (compliance, brand)
+## Clarifying Questions Protocol
 
-### 5. Success Criteria Definition
+**Rule:** Only ask if it resolves ambiguity that changes effort by 2x+.
 
-Define how we'll know when we're done:
+1.  **Search:** Do I already know this?
+2.  **Skill:** Can I deduce this? (e.g., "Standard practice for React is...")
+3.  **Ask:** If neither, ask a **Structured Prompt**.
 
-```markdown
-## Success Criteria
-
-1. [Observable behavior 1]
-2. [Observable behavior 2]
-3. [Measurable outcome]
+```text
+⬢ Decision Required: UI Framework
+  
+  1. Tailwind CSS (Consistent with project)
+  2. CSS Modules (Used in legacy components)
+  
+  ► Select [1-2]:
 ```
 
-## Artifacts Produced
+## Output: PLAN.md
 
-| Artifact | Purpose |
-|----------|---------|
-| Intent statement | Clear understanding of what and why |
-| Requirements list | Categorized list of needs |
-| Constraints | Known limitations |
-| Success criteria | Acceptance conditions |
+The result of this phase is a clear `PLAN.md` (internal state) or simple structured context.
 
-## Transition to Research Phase
+```markdown
+# Plan: [Feature Name]
 
-The Plan phase is complete when:
+## Intent
+**User wants to:** Create a login page
+**Because:** Users need to access private dashboards
+**Success:** Successful login redirects to /dashboard
 
-- [ ] Intent is clearly understood and documented
-- [ ] All critical ambiguities resolved
-- [ ] Requirements categorized (must/should/could/won't)
-- [ ] Success criteria defined
-- [ ] User confirms understanding is correct
+## Requirements
+### Must Have
+- Email/Password form
+- "Forgot Password" link
 
-**Transition prompt:**
+### Constraints
+- Must use existing Auth0 tenant
+- Mobile responsive
 ```
-"I understand you want to [intent summary].
-
-Must haves:
-- [list]
 
-Success looks like:
-- [criteria]
-
-Is this understanding correct? Ready to research implementation approaches?"
+## The Research Gate
+
+The transition to Research is a formal **Decision Gate**.
+
+```text
+╭─ ⬢ GoopSpec ───────────────────────────────────────╮
+│                                                    │
+│  🚩 RESEARCH GATE                                  │
+│                                                    │
+│  I understand the intent. How should we proceed?   │
+│                                                    │
+│  1. ⚡ Quick Mode                                  │
+│     Skip research. Use standard patterns.          │
+│     Best for: Simple fixes, standard features.     │
+│                                                    │
+│  2. 🔍 Deep Research                               │
+│     Explore options, read docs, map codebase.      │
+│     Best for: New tech, complex feats, unknown.    │
+│                                                    │
+│  ► Select [1-2]:                                   │
+│                                                    │
+╰────────────────────────────────────────────────────╯
 ```
 
-## Quick Mode Shortcut
-
-For Quick tasks, Plan phase is abbreviated:
-- Capture intent in 1-2 sentences
-- Skip detailed requirements (scope is small)
-- Define one clear success criterion
-- Proceed directly to Execute
-
-## Common Pitfalls
-
-### Over-planning
-**Symptom:** Spending hours documenting a 30-minute fix
-**Fix:** Match planning depth to task complexity
-
-### Under-planning
-**Symptom:** Starting work without clear success criteria
-**Fix:** Always define at least one observable success criterion
-
-### Assumption accumulation
-**Symptom:** Making multiple assumptions without noting them
-**Fix:** Document assumptions explicitly, validate critical ones
-
-### Scope creep during planning
-**Symptom:** Requirements keep growing
-**Fix:** Establish must-haves first, push additions to could-have
+## Commands
 
-## Memory Protocol
+| Command | Effect |
+| :--- | :--- |
+| `/goop-plan [intent]` | Start Plan phase with initial intent. |
+| `/goop-discuss` | Open-ended discussion to clarify vague intent. |
+| `/goop-status` | Check current phase status. |
 
-### Before Starting
-```
-memory_search({ query: "similar features, past requirements" })
-```
+## Memory Triggers
 
-### During Planning
-```
-memory_note({ note: "User prefers X approach over Y" })
-```
+*   **Save:** User preferences discovered during questioning.
+*   **Save:** The finalized "Project Intent" for future reference.
 
-### After Completing
-```
-memory_save({ 
+```javascript
+memory_save({
   type: "note",
-  title: "Project Intent: [name]",
-  content: "[intent summary]"
+  title: "Project Intent: [Name]",
+  content: "User wants to... [Summary]",
+  concepts: ["intent", "scope"]
 })
 ```
-
-## Commands
-
-| Command | Effect |
-|---------|--------|
-| `/goop-plan [intent]` | Start Plan phase with initial intent |
-| `/goop-status` | Check current phase status |