opencode-goopspec 0.1.2 → 0.1.4

package/references/workflow-research.md

@@ -1,6 +1,8 @@
 # Workflow: Research Phase
 
-The Research phase gathers context and explores implementation approaches before committing to a specification.
+**GoopSpec Voice:** Analytical, Thorough, Skill-Backed.
+
+The Research phase answers: **How should we build this?** It explores the problem space *before* we commit to a contract.
 
 ## Position in Workflow
 
@@ -13,222 +15,112 @@ The Research phase gathers context and explores implementation approaches before
                     (You are here)
 ```
 
-## Purpose
-
-The Research phase answers: **How should we build this?**
-
-It explores the problem space, gathers context, evaluates approaches, and informs specification decisions.
-
 ## Entry Criteria
+*   Plan phase complete.
+*   User selected **Deep Research** (or default for complex tasks).
+*   *Note: Quick Mode skips this phase entirely.*
 
-- Plan phase complete
-- Intent and requirements documented
-- User has confirmed understanding
-
-## Parallel Research Agents
-
-Research phase spawns multiple agents working simultaneously:
-
-| Agent | Focus |
-|-------|-------|
-| **Researcher** | Deep domain research - technologies, patterns, best practices |
-| **Explorer** | Codebase analysis - existing patterns, conventions, integration points |
-| **Librarian** | Documentation gathering - API docs, library guides, examples |
-| **Designer** | (For UI tasks) Visual research - patterns, components, UX |
+## Research Modes
 
-### Research Delegation
+### 1. The Explorer (Codebase Map)
+**Skill:** `octocode-research`
+*   **Goal:** Understand existing patterns.
+*   **Action:** Map relevant files, check conventions, find integration points.
 
+```text
+⬢ Exploring Codebase...
+  └─ ⚡ Mapped "src/auth/" (Found 3 files)
+  └─ ⚡ Identified pattern: "Repository Pattern"
 ```
-task({
-  subagent_type: "general",
-  description: "Research topic",
-  prompt: "Research [topic] for [project intent]. Focus on: ..."
-})
 
-task({
-  subagent_type: "explore",
-  description: "Explore codebase",
-  prompt: "Explore codebase for patterns related to [feature]. Map: ..."
-})
+### 2. The Scholar (External Knowledge)
+**Skill:** `exa_web_search`, `context7_query-docs`
+*   **Goal:** Find best practices and documentation.
+*   **Action:** Read docs, find libraries, compare options.
 
-task({
-  subagent_type: "general",
-  description: "Gather documentation",
-  prompt: "Gather documentation for [library/API]. Find: ..."
-})
+```text
+⬢ Researching: "Auth0 React SDK vs NextAuth"
+  └─ ⚡ Reading documentation...
+  └─ ⚡ Comparing community usage...
 ```
 
-## Research Areas
-
-### 1. Technology Research
-
-- Available libraries/frameworks
-- Tradeoffs between approaches
-- Performance characteristics
-- Security considerations
-- Community support/maturity
-
-### 2. Codebase Exploration
+## Research Output: RESEARCH.md
 
-- Existing patterns and conventions
-- Related implementations
-- Integration points
-- Potential conflicts
-- Test coverage gaps
-
-### 3. Domain Knowledge
-
-- Business rules
-- Edge cases
-- User expectations
-- Industry standards
-- Compliance requirements
-
-### 4. Visual Research (UI Tasks)
-
-- Design patterns
-- Component libraries
-- Accessibility requirements
-- Responsive considerations
-- Animation/interaction patterns
-
-## RESEARCH.md Output
-
-Research findings are consolidated into RESEARCH.md:
+Findings are consolidated into a structured document.
 
 ```markdown
 # Research: [Feature Name]
 
-## Domain Analysis
+## Analysis
+*   **Pattern:** Repository Pattern (matches codebase)
+*   **Library:** Auth0 SDK (matches preference)
 
-### Technology Options
+## Options
 | Option | Pros | Cons | Recommendation |
-|--------|------|------|----------------|
-| Option A | ... | ... | Recommended |
-| Option B | ... | ... | Alternative |
-
-### Relevant Documentation
-- [Link 1]: Key insight
-- [Link 2]: Key insight
-
-## Codebase Analysis
-
-### Existing Patterns
-- Pattern 1: Used in [files], suitable for [use case]
-- Pattern 2: Used in [files], suitable for [use case]
-
-### Integration Points
-- Component A: Will need [modification]
-- Service B: Already supports [capability]
-
-### Conventions Discovered
-- Naming: [convention]
-- Structure: [convention]
-- Testing: [convention]
-
-## Recommendations
+| :--- | :--- | :--- | :--- |
+| **A: Auth0 SDK** | Native support, secure | Vendor lock-in | ✅ Recommended |
+| **B: NextAuth** | Flexible provider | More setup | |
 
-### Approach
-[Recommended implementation approach]
-
-### Key Decisions Needed
-- Decision 1: [options]
-- Decision 2: [options]
-
-### Risks
-- Risk 1: [description, mitigation]
-- Risk 2: [description, mitigation]
-
-### Estimated Complexity
-[Low / Medium / High] - [rationale]
+## Risks
+*   Risk: API Rate limits on free tier.
+*   Mitigation: Implement caching.
 ```
 
-## Research Quality Criteria
-
-### Good Research
-- Multiple sources consulted
-- Alternatives considered
-- Tradeoffs explicitly stated
-- Recommendations justified
-- Risks identified
+## Interactive Decision Protocol
 
-### Bad Research
-- Single source only
-- First option accepted
-- No alternatives considered
-- Recommendations without rationale
-- No risk assessment
+When research reveals a fork in the road, use a **Skill-Backed Question**.
 
-## Transition to Specify Phase
+```text
+⬢ Decision Required: State Management
 
-Research phase is complete when:
-
-- [ ] All parallel agents have reported findings
-- [ ] RESEARCH.md consolidated and saved
-- [ ] Key decisions identified
-- [ ] Recommended approach documented
-- [ ] Risks catalogued
-
-**Transition prompt:**
+  I found two viable patterns for this feature:
+  
+  1. **Zustand** (Used in 'Settings' module, simpler)
+  2. **Redux** (Used in 'Core', but verbose)
+  
+  ► Recommendation: Zustand (Lower complexity).
+  ► Select [1-2]:
 ```
-"Research complete. Key findings:
-
-Recommended approach: [summary]
-Key decisions needed: [list]
-Main risks: [list]
 
-Ready to lock the specification?"
+## The Specification Gate
+
+The transition to Specify is a formal handoff.
+
+```text
+╭─ ⬢ GoopSpec ───────────────────────────────────────╮
+│                                                    │
+│  🚩 SPECIFICATION GATE                             │
+│                                                    │
+│  Research complete. I have a recommended approach. │
+│                                                    │
+│  • Approach: Use Auth0 SDK with Context API        │
+│  • Key Decision: Zustand for local state           │
+│  • Risks: None blocking                            │
+│                                                    │
+│  ► Type "proceed" to Draft Specification.          │
+│  ► Type "discuss" to review findings in detail.    │
+│                                                    │
+╰────────────────────────────────────────────────────╯
 ```
 
-## Quick Mode Shortcut
-
-For Quick tasks, Research phase is SKIPPED entirely:
-- Assume existing patterns are sufficient
-- No parallel agent spawning
-- Jump directly from Plan to Execute
+## Commands
 
-## Comprehensive Mode Extension
+| Command | Effect |
+| :--- | :--- |
+| `/goop-research` | Start deep research. |
+| `/goop-map-codebase` | Trigger specific codebase mapping task. |
+| `/goop-recall [query]` | Search past research. |
 
-For Comprehensive tasks:
-- Deeper research per agent
-- More alternatives explored
-- Extended timeframe
-- User reviews RESEARCH.md before Specify
+## Memory Triggers
 
-## Memory Protocol
+*   **Save:** New technology choices and rationale.
+*   **Save:** Discovered codebase patterns (for future "Explorer" runs).
 
-### Before Starting
-```
-memory_search({ 
-  query: "past research on [topic]",
-  concepts: ["technology", "pattern"]
-})
-```
-
-### During Research
-Each agent saves findings:
-```
-memory_save({
-  type: "observation",
-  title: "Research: [specific finding]",
-  concepts: ["relevant", "concepts"]
-})
-```
-
-### After Completing
-```
+```javascript
 memory_save({
   type: "observation",
-  title: "Research Summary: [feature]",
-  content: "[key findings]",
-  concepts: ["tech-choices", "patterns"]
+  title: "Research: Auth0 Pattern",
+  content: "Project uses Auth0 SDK wrapped in a custom provider.",
+  concepts: ["auth", "pattern", "react"]
 })
 ```
-
-## Commands
-
-| Command | Effect |
-|---------|--------|
-| `/goop-research` | Start Research phase |
-| `/goop-status` | Check research progress |
-| `/goop-recall [query]` | Search past research |

package/references/workflow-specify.md

@@ -1,6 +1,8 @@
 # Workflow: Specify Phase
 
-The Specify phase locks the specification - the CONTRACT between user and agent.
+**GoopSpec Voice:** Contractual, Precise, Binding.
+
+The Specify phase answers: **What exactly will we deliver?** This is the **CONTRACT**.
 
 ## Position in Workflow
 
@@ -13,167 +15,36 @@ The Specify phase locks the specification - the CONTRACT between user and agent.
                                         (You are here)
 
        ╔══════════════════════════════════════════════╗
-       ║          CONTRACT GATE                        ║
-       ║   User MUST confirm before execution begins   ║
+       ║          CONTRACT GATE                       ║
+       ║   User MUST confirm before execution begins  ║
        ╚══════════════════════════════════════════════╝
 ```
 
-## Purpose
-
-The Specify phase answers: **What exactly will we deliver?**
-
-This is the CONTRACT phase. Once locked, the specification becomes the binding agreement:
-- Agent commits to delivering must-haves
-- User commits to accepting if must-haves are met
-- Changes require explicit amendment
-
-## Entry Criteria
-
-- Plan phase complete (intent captured)
-- Research phase complete (approach researched)
-- RESEARCH.md available with recommendations
-
-## The Contract Concept
-
-### Why Contracts Matter
-
-Without a locked spec:
-- Scope creeps silently
-- "Almost done" never ends
-- Success criteria shift
-- Both parties frustrated
-
-With a locked spec:
-- Clear deliverables
-- Measurable completion
-- Explicit change process
-- Satisfied expectations
+## The Contract Philosophy
 
-### Contract Terms
+*   **No Surprises:** Everything implemented must be in the spec.
+*   **Must vs. Nice:** Ruthless prioritization.
+*   **Explicit Scope:** "Out of Scope" is as important as "Must Have".
 
-```markdown
-## Specification Contract
-
-### Must Haves (Guaranteed)
-If these aren't delivered, the work is incomplete.
-- [ ] Must-have 1
-- [ ] Must-have 2
-
-### Nice to Haves (Best Effort)
-Will attempt if time permits after must-haves.
-- [ ] Nice-to-have 1
-- [ ] Nice-to-have 2
-
-### Out of Scope (Explicitly Excluded)
-These are NOT part of this work.
-- Excluded item 1
-- Excluded item 2
-
-### Acceptance Criteria
-How we'll verify completion.
-1. Criterion 1
-2. Criterion 2
-```
-
-## SPEC.md Structure
-
-```markdown
-# Specification: [Feature Name]
+## Activities
 
-**Status:** LOCKED | DRAFT
-**Locked At:** [timestamp]
-**Locked By:** [user confirmation]
+### 1. Synthesize & Draft
+Combine Intent (Plan) + Approach (Research) into `SPEC.md`.
 
-## Intent
-[Summary from Plan phase]
+*   **Must Haves:** Non-negotiable deliverables.
+*   **Nice to Haves:** Best effort, time permitting.
+*   **Out of Scope:** Explicitly excluded to prevent creep.
 
-## Requirements
+### 2. The Blueprinting
+Create `BLUEPRINT.md` - the execution plan.
+*   Break down into **Waves**.
+*   Define **Atomic Tasks**.
 
-### Must Haves
-- [ ] Requirement 1
-  - Acceptance: [how to verify]
-- [ ] Requirement 2
-  - Acceptance: [how to verify]
+## The Contract Gate
 
-### Nice to Haves
-- [ ] Requirement 3
-- [ ] Requirement 4
+This is the most critical interaction in the GoopSpec workflow.
 
-### Out of Scope
-- Item 1 (reason: ...)
-- Item 2 (reason: ...)
-
-## Technical Approach
-[Summary from Research phase]
-
-## Target Files
-- `path/to/file1.ts` - [change description]
-- `path/to/file2.ts` - [change description]
-
-## Dependencies
-- Depends on: [list]
-- Blocks: [list]
-
-## Risks
-- Risk 1: [description, mitigation]
-
-## Estimated Effort
-[T-shirt size: XS, S, M, L, XL]
-```
-
-## Specify Activities
-
-### 1. Synthesize Plan + Research
-
-Combine intent (Plan) with approach (Research):
-- Match requirements to technical solutions
-- Identify which must-haves are feasible
-- Determine what should be nice-to-have vs out-of-scope
-
-### 2. Define Must-Haves
-
-Critical: Must-haves should be:
-- **Observable** - Can be seen/tested
-- **Achievable** - Within scope of work
-- **Specific** - No ambiguity
-- **Limited** - Keep list short (3-7 items)
-
-### 3. Set Boundaries
-
-Explicitly define what's out:
-- Features that seem related but aren't included
-- Edge cases that won't be handled
-- Future enhancements
-
-### 4. Create BLUEPRINT.md
-
-Transform spec into executable plan:
-
-```markdown
-# Blueprint: [Feature Name]
-
-## Wave 1: [Foundation]
-
-### Task 1.1: [Name]
-**Files:** path/to/file.ts
-**Action:** [What to do]
-**Verify:** [How to verify]
-**Done:** [Acceptance criterion]
-
-### Task 1.2: [Name]
-...
-
-## Wave 2: [Core]
-...
-```
-
-## Contract Gate
-
-**CRITICAL**: User MUST explicitly confirm the specification.
-
-### Confirmation Prompt
-
-```
+```text
 ╭─ ⬢ GoopSpec ───────────────────────────────────────╮
 │                                                    │
 │  🔒 CONTRACT GATE                                  │
@@ -181,98 +52,70 @@ Transform spec into executable plan:
 │  I'm ready to lock the specification.              │
 │                                                    │
 │  MUST HAVES (I commit to delivering):              │
-│  • Must-have 1                                     │
-│  • Must-have 2                                     │
+│  • User Login (Email/Pass)                         │
+│  • "Forgot Password" Flow                          │
 │                                                    │
 │  NICE TO HAVES (Best effort):                      │
-│  • Nice-to-have 1                                  │
+│  • Social Login (Google)                           │
 │                                                    │
 │  OUT OF SCOPE:                                     │
-│  • Excluded 1                                      │
-│                                                    │
-│  ACCEPTANCE CRITERIA:                              │
-│  1. Criterion 1                                    │
-│  2. Criterion 2                                    │
+│  • Admin Dashboard                                 │
 │                                                    │
 │  ─────────────────────────────────────────────     │
-│  Type "confirm" to lock and proceed.               │
-│  Type "amend" to request changes.                  │
+│  ► Type "confirm" to Lock Spec and Execute.        │
+│  ► Type "amend" to request changes.                │
 │                                                    │
 ╰────────────────────────────────────────────────────╯
 ```
 
-### After Confirmation
-
-- SPEC.md status changes to LOCKED
-- Timestamp recorded
-- Execution phase can begin
-- Changes require `/goop-amend` command
-
 ## Amendments
 
-If spec needs to change after locking:
+If the user rejects the contract or needs changes later:
 
-```
-/goop-amend "Add support for X"
-```
+1.  **Command:** `/goop-amend "Add Social Login to Must Haves"`
+2.  **Action:** Agent updates `SPEC.md` and `BLUEPRINT.md`.
+3.  **Gate:** Re-present the Contract Gate.
 
-Amendment process:
-1. Stop current execution
-2. Document the change request
-3. Assess impact on existing work
-4. User confirms amendment
-5. Update SPEC.md
-6. Resume or restart execution
+**Note:** Amending a locked spec during execution triggers a "Scope Change" warning.
 
-## Transition to Execute Phase
+## Output: SPEC.md & BLUEPRINT.md
+
+### SPEC.md
+The "What".
+```markdown
+# Specification: Auth Feature
+**Status:** LOCKED
 
-Specify phase is complete when:
+## Must Haves
+- [ ] Login Form
+- [ ] API Integration
+```
 
-- [ ] SPEC.md written with all sections
-- [ ] Must-haves clearly defined
-- [ ] Out-of-scope explicitly stated
-- [ ] BLUEPRINT.md created with waves/tasks
-- [ ] **User has confirmed the specification**
+### BLUEPRINT.md
+The "How".
+```markdown
+# Blueprint
+## Wave 1: Foundation
+- [ ] Task 1.1: Setup Auth0 Provider
+```
 
-## Quick Mode Shortcut
+## Commands
 
-For Quick tasks, Specify phase is SKIPPED:
-- Intent from Plan phase serves as implicit spec
-- No formal SPEC.md
-- Jump directly to Execute
+| Command | Effect |
+| :--- | :--- |
+| `/goop-specify` | Generate spec and trigger Contract Gate. |
+| `/goop-amend` | Modify a draft or locked spec. |
+| `/goop-status` | View current spec status. |
 
-## Memory Protocol
+## Memory Triggers
 
-### Before Starting
-```
-memory_search({ 
-  query: "past specs for similar features",
-  types: ["decision"]
-})
-```
+*   **Save:** The Locked Contract (High Importance).
+*   **Decision:** Scope exclusions (Why did we exclude X?).
 
-### During Specifying
-```
+```javascript
 memory_decision({
-  decision: "Feature X out of scope",
-  reasoning: "User confirmed focus on core functionality"
+  decision: "Excluded Admin Dashboard",
+  reasoning: "User wants to focus on consumer-facing features first.",
+  impact: "high"
 })
 ```
-
-### After Locking
-```
-memory_save({
-  type: "decision",
-  title: "Spec Locked: [feature]",
-  content: "[must-haves summary]",
-  importance: 0.8
-})
-```
-
-## Commands
-
-| Command | Effect |
-|---------|--------|
-| `/goop-specify` | Create and present spec for confirmation |
-| `/goop-amend [change]` | Request spec amendment |
-| `/goop-status` | Check spec lock status |