opencode-goopspec 0.1.0

package/references/workflow-plan.md

@@ -0,0 +1,179 @@
+# Workflow: Plan Phase
+
+The Plan phase captures user intent and establishes the foundation for all subsequent work.
+
+## Position in Workflow
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│    PLAN     │ ──▶ │  RESEARCH   │ ──▶ │   SPECIFY   │
+│  (Intent)   │     │  (Explore)  │     │ (Contract)  │
+└─────────────┘     └─────────────┘     └─────────────┘
+     ↑
+(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
+
+### 1. Intent Capture
+
+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]
+```
+
+### 2. Clarifying Questions
+
+Ask questions to resolve ambiguity:
+
+- **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?"
+
+**Rule:** If ambiguity could lead to 2x+ effort difference, MUST ask before proceeding.
+
+### 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
+```
+
+### 4. Constraint Identification
+
+Document known constraints:
+
+- Technical constraints (existing stack, compatibility)
+- Time constraints (deadlines, urgency)
+- Resource constraints (budget, team)
+- Business constraints (compliance, brand)
+
+### 5. Success Criteria Definition
+
+Define how we'll know when we're done:
+
+```markdown
+## Success Criteria
+
+1. [Observable behavior 1]
+2. [Observable behavior 2]
+3. [Measurable outcome]
+```
+
+## Artifacts Produced
+
+| Artifact | Purpose |
+|----------|---------|
+| Intent statement | Clear understanding of what and why |
+| Requirements list | Categorized list of needs |
+| Constraints | Known limitations |
+| Success criteria | Acceptance conditions |
+
+## Transition to Research Phase
+
+The Plan phase is complete when:
+
+- [ ] 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
+
+**Transition prompt:**
+```
+"I understand you want to [intent summary].
+
+Must haves:
+- [list]
+
+Success looks like:
+- [criteria]
+
+Is this understanding correct? Ready to research implementation approaches?"
+```
+
+## 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
+
+## Memory Protocol
+
+### Before Starting
+```
+memory_search({ query: "similar features, past requirements" })
+```
+
+### During Planning
+```
+memory_note({ note: "User prefers X approach over Y" })
+```
+
+### After Completing
+```
+memory_save({ 
+  type: "note",
+  title: "Project Intent: [name]",
+  content: "[intent summary]"
+})
+```
+
+## Commands
+
+| Command | Effect |
+|---------|--------|
+| `/goop-plan [intent]` | Start Plan phase with initial intent |
+| `/goop-status` | Check current phase status |

package/references/workflow-research.md

@@ -0,0 +1,234 @@
+# Workflow: Research Phase
+
+The Research phase gathers context and explores implementation approaches before committing to a specification.
+
+## Position in Workflow
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│    PLAN     │ ──▶ │  RESEARCH   │ ──▶ │   SPECIFY   │
+│  (Intent)   │     │  (Explore)  │     │ (Contract)  │
+└─────────────┘     └─────────────┘     └─────────────┘
+                          ↑
+                    (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
+- 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 Delegation
+
+```
+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: ..."
+})
+
+task({
+  subagent_type: "general",
+  description: "Gather documentation",
+  prompt: "Gather documentation for [library/API]. Find: ..."
+})
+```
+
+## Research Areas
+
+### 1. Technology Research
+
+- Available libraries/frameworks
+- Tradeoffs between approaches
+- Performance characteristics
+- Security considerations
+- Community support/maturity
+
+### 2. Codebase Exploration
+
+- 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:
+
+```markdown
+# Research: [Feature Name]
+
+## Domain Analysis
+
+### Technology 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
+
+### 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]
+```
+
+## Research Quality Criteria
+
+### Good Research
+- Multiple sources consulted
+- Alternatives considered
+- Tradeoffs explicitly stated
+- Recommendations justified
+- Risks identified
+
+### Bad Research
+- Single source only
+- First option accepted
+- No alternatives considered
+- Recommendations without rationale
+- No risk assessment
+
+## Transition to Specify Phase
+
+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:**
+```
+"Research complete. Key findings:
+
+Recommended approach: [summary]
+Key decisions needed: [list]
+Main risks: [list]
+
+Ready to lock the specification?"
+```
+
+## 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
+
+## Comprehensive Mode Extension
+
+For Comprehensive tasks:
+- Deeper research per agent
+- More alternatives explored
+- Extended timeframe
+- User reviews RESEARCH.md before Specify
+
+## Memory Protocol
+
+### 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
+```
+memory_save({
+  type: "observation",
+  title: "Research Summary: [feature]",
+  content: "[key findings]",
+  concepts: ["tech-choices", "patterns"]
+})
+```
+
+## Commands
+
+| Command | Effect |
+|---------|--------|
+| `/goop-research` | Start Research phase |
+| `/goop-status` | Check research progress |
+| `/goop-recall [query]` | Search past research |

package/references/workflow-specify.md

@@ -0,0 +1,278 @@
+# Workflow: Specify Phase
+
+The Specify phase locks the specification - the CONTRACT between user and agent.
+
+## Position in Workflow
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│    PLAN     │ ──▶ │  RESEARCH   │ ──▶ │   SPECIFY   │
+│  (Intent)   │     │  (Explore)  │     │ (Contract)  │
+└─────────────┘     └─────────────┘     └─────────────┘
+                                              ↑
+                                        (You are here)
+
+       ╔══════════════════════════════════════════════╗
+       ║          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
+
+### Contract Terms
+
+```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]
+
+**Status:** LOCKED | DRAFT
+**Locked At:** [timestamp]
+**Locked By:** [user confirmation]
+
+## Intent
+[Summary from Plan phase]
+
+## Requirements
+
+### Must Haves
+- [ ] Requirement 1
+  - Acceptance: [how to verify]
+- [ ] Requirement 2
+  - Acceptance: [how to verify]
+
+### Nice to Haves
+- [ ] Requirement 3
+- [ ] Requirement 4
+
+### 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
+
+```
+╭─ ⬢ GoopSpec ───────────────────────────────────────╮
+│                                                    │
+│  🔒 CONTRACT GATE                                  │
+│                                                    │
+│  I'm ready to lock the specification.              │
+│                                                    │
+│  MUST HAVES (I commit to delivering):              │
+│  • Must-have 1                                     │
+│  • Must-have 2                                     │
+│                                                    │
+│  NICE TO HAVES (Best effort):                      │
+│  • Nice-to-have 1                                  │
+│                                                    │
+│  OUT OF SCOPE:                                     │
+│  • Excluded 1                                      │
+│                                                    │
+│  ACCEPTANCE CRITERIA:                              │
+│  1. Criterion 1                                    │
+│  2. Criterion 2                                    │
+│                                                    │
+│  ─────────────────────────────────────────────     │
+│  Type "confirm" to lock and proceed.               │
+│  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:
+
+```
+/goop-amend "Add support for X"
+```
+
+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
+
+## Transition to Execute Phase
+
+Specify phase is complete when:
+
+- [ ] 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**
+
+## Quick Mode Shortcut
+
+For Quick tasks, Specify phase is SKIPPED:
+- Intent from Plan phase serves as implicit spec
+- No formal SPEC.md
+- Jump directly to Execute
+
+## Memory Protocol
+
+### Before Starting
+```
+memory_search({ 
+  query: "past specs for similar features",
+  types: ["decision"]
+})
+```
+
+### During Specifying
+```
+memory_decision({
+  decision: "Feature X out of scope",
+  reasoning: "User confirmed focus on core functionality"
+})
+```
+
+### 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 |