opencode-goopspec 0.1.0

package/commands/goop-complete.md

@@ -0,0 +1,206 @@
+---
+name: goop-complete
+description: Complete and archive a milestone
+---
+
+# GoopSpec Complete
+
+Complete and archive a milestone, extracting learnings and preparing for the next phase.
+
+## Usage
+
+```
+/goop-complete
+```
+
+## When to Use
+
+Use `/goop-complete` when:
+- A major milestone is finished
+- Multiple features are complete
+- Ready to close a development cycle
+- Want to extract learnings before next phase
+
+**Note:** For individual features, `/goop-accept` is sufficient. Use `/goop-complete` for larger milestones.
+
+## What Happens
+
+1. **Verify Completion** - Confirm all milestone features accepted
+2. **Generate RETROSPECTIVE.md** - Reflect on what worked/didn't
+3. **Extract LEARNINGS.md** - Document patterns, decisions, insights
+4. **Archive Files** - Move to `archive/milestone-N/`:
+   - SPEC.md
+   - BLUEPRINT.md
+   - CHRONICLE.md
+   - RESEARCH.md
+   - RETROSPECTIVE.md
+   - LEARNINGS.md
+5. **Persist to Memory** - Save key learnings for future reference
+6. **Tag Git** - Create version tag (e.g., `v1.0.0`)
+7. **Clean Workspace** - Clear active workflow state
+8. **Celebrate** - Acknowledge completion
+
+## RETROSPECTIVE.md
+
+Generated retrospective includes:
+
+```markdown
+# Retrospective: [Milestone Name]
+
+**Completed:** [Date]
+**Duration:** [Time period]
+**Features Delivered:** [Count]
+
+## What Went Well
+
+- [Success 1]
+- [Success 2]
+
+## What Could Improve
+
+- [Challenge 1]
+- [Challenge 2]
+
+## Key Decisions
+
+- [Decision 1]: [Rationale]
+- [Decision 2]: [Rationale]
+
+## Metrics
+
+- Tasks completed: [N]
+- Commits: [N]
+- Tests added: [N]
+- Files modified: [N]
+- Deviations: [N]
+
+## Team Feedback
+
+[User observations and feedback]
+```
+
+## LEARNINGS.md
+
+Extracted learnings include:
+
+```markdown
+# Learnings: [Milestone Name]
+
+## Technical Patterns
+
+### Pattern 1: [Name]
+**Context:** [When to use]
+**Implementation:** [How it works]
+**Benefits:** [Why it's good]
+**Files:** [Where it's used]
+
+## Architectural Decisions
+
+### Decision 1: [Name]
+**Problem:** [What we needed to solve]
+**Solution:** [What we chose]
+**Alternatives:** [What we didn't choose]
+**Rationale:** [Why this was best]
+
+## Gotchas Discovered
+
+- [Gotcha 1]: [How to avoid]
+- [Gotcha 2]: [How to avoid]
+
+## Reusable Components
+
+- [Component 1]: [Purpose and location]
+- [Component 2]: [Purpose and location]
+
+## Future Recommendations
+
+- [Recommendation 1]
+- [Recommendation 2]
+```
+
+## Archive Structure
+
+```
+archive/
+└── milestone-1-auth-system/
+    ├── SPEC.md
+    ├── BLUEPRINT.md
+    ├── CHRONICLE.md
+    ├── RESEARCH.md
+    ├── RETROSPECTIVE.md
+    └── LEARNINGS.md
+```
+
+## Memory Persistence
+
+Key information saved to memory:
+- Architectural decisions
+- Reusable patterns discovered
+- Gotchas and how to avoid them
+- Performance insights
+- Security considerations
+
+## Git Tagging
+
+Milestone tagged in git:
+
+```bash
+git tag -a v1.0.0 -m "Milestone 1: Authentication System"
+git push origin v1.0.0
+```
+
+## Completion Prompt
+
+```
+╭─ ⬢ GoopSpec ───────────────────────────────────────╮
+│                                                    │
+│  🎯 MILESTONE COMPLETE                             │
+│                                                    │
+│  Milestone: Authentication System                  │
+│                                                    │
+│  DELIVERED:                                        │
+│  • User login/logout                               │
+│  • Session management                              │
+│  • Password reset                                  │
+│  • OAuth integration                               │
+│                                                    │
+│  METRICS:                                          │
+│  • Duration: 3 days                                │
+│  • Tasks: 24 completed                             │
+│  • Commits: 24                                     │
+│  • Tests: 87% coverage                             │
+│                                                    │
+│  ARCHIVED:                                         │
+│  • Specifications                                  │
+│  • Research findings                               │
+│  • Learnings extracted                             │
+│  • Git tagged: v1.0.0                              │
+│                                                    │
+╰────────────────────────────────────────────────────╯
+
+What's next?
+• /goop-milestone [name] - Start next milestone
+• /goop-plan [feature] - Plan next feature
+• /goop-status - Check project status
+```
+
+## Example
+
+After completing authentication system milestone:
+
+```
+/goop-complete
+```
+
+Agent generates retrospective, extracts learnings, archives files, tags git, and prepares for next milestone.
+
+## Next Steps
+
+After completion:
+- `/goop-milestone [name]` - Start new milestone
+- `/goop-plan [feature]` - Plan next feature
+- Review LEARNINGS.md for insights
+
+---
+
+**GoopSpec**: Complete with reflection, start fresh with wisdom.

package/commands/goop-debug.md

@@ -0,0 +1,318 @@
+---
+name: goop-debug
+description: Systematic debugging using scientific method - investigate bugs with hypothesis testing
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  grep: true
+  glob: true
+---
+
+<objective>
+Systematic debugging using the scientific method.
+
+Investigates bugs through hypothesis testing, manages persistent debug sessions, and handles checkpoints when user input is needed.
+
+**Key principles:**
+- User = Reporter (knows symptoms), Claude = Investigator (finds cause)
+- Hypothesis testing with falsifiable predictions
+- Change one variable at a time
+- Document everything in DEBUG.md
+
+**Creates:**
+- `.goopspec/debug/DEBUG-{id}.md` - Debug session record
+</objective>
+
+<execution_context>
+<!-- Debug template is embedded in the process section above -->
+</execution_context>
+
+<context>
+@.goopspec/PROJECT.md
+@.goopspec/STATE.md
+</context>
+
+<process>
+## Phase 1: Gather Evidence
+
+**Opening questions:**
+
+"Tell me about the bug. What did you expect to happen, and what actually happened?"
+
+Listen for:
+- Expected behavior
+- Actual behavior
+- Error messages
+- When it started
+- Reproduction steps
+- Environment details
+
+**Do NOT ask:**
+- "What's causing it?" (User doesn't know)
+- "Which file has the bug?" (That's your job)
+- "How should we fix it?" (Investigate first)
+
+**DO ask about:**
+- "What were you doing when it happened?"
+- "Does it happen every time?"
+- "When did you first notice it?"
+- "What error messages did you see?"
+
+## Phase 2: Initialize Debug Session
+
+Create debug session file:
+
+```bash
+DEBUG_ID=$(date +%Y%m%d-%H%M%S)
+mkdir -p .goopspec/debug
+```
+
+Create `.goopspec/debug/DEBUG-$DEBUG_ID.md`:
+
+```markdown
+# Debug Session: $DEBUG_ID
+
+**Started:** [Timestamp]
+**Status:** In Progress
+**Severity:** [Critical/Major/Minor]
+
+## Problem Statement
+
+**Expected:** [What should happen]
+**Actual:** [What actually happens]
+**Impact:** [Who/what is affected]
+
+## Evidence Gathered
+
+### Error Messages
+```
+[Paste error messages]
+```
+
+### Reproduction Steps
+1. [Step 1]
+2. [Step 2]
+3. [Step 3]
+
+### Environment
+- [OS/Version]
+- [Runtime version]
+- [Relevant env vars]
+
+## Investigation Log
+
+### Hypothesis 1: [Brief description]
+**Prediction:** If true, [observable outcome]
+**Test:** [What to do]
+**Result:** [Pending/Confirmed/Refuted]
+**Conclusion:** [What we learned]
+
+---
+
+## Current Status
+
+**Active Hypothesis:** [Which one we're testing]
+**Next Step:** [What to do next]
+
+## Resolution
+
+**Root Cause:** [What was actually wrong]
+**Fix Applied:** [What was changed]
+**Verification:** [How we confirmed it's fixed]
+**Committed:** [Commit hash]
+
+---
+*Debug session following scientific method*
+```
+
+## Phase 3: Form Hypotheses
+
+Based on evidence, generate 3+ independent hypotheses:
+
+**Good hypotheses (falsifiable):**
+- "User state resets because component remounts on route change"
+- "API returns 404 because URL construction is wrong"
+- "Race condition between async operations"
+
+**Bad hypotheses (unfalsifiable):**
+- "Something is wrong with the state"
+- "The timing is off"
+- "There's a bug somewhere"
+
+For each hypothesis, design an experiment:
+
+```markdown
+### Hypothesis N: [Description]
+**Prediction:** If this hypothesis is true, I will observe [specific outcome]
+**Test:** [Exact steps to test]
+**Measurement:** [What to measure]
+**Success criteria:** [What confirms/refutes]
+```
+
+## Phase 4: Test Hypotheses
+
+**Rule: Change ONE variable at a time**
+
+For each hypothesis:
+1. Run the test
+2. Record the exact outcome
+3. Compare to prediction
+4. Document in DEBUG.md
+
+**If hypothesis confirmed:**
+- Move to Phase 5 (Action)
+- Update DEBUG.md with conclusion
+
+**If hypothesis refuted:**
+- Document what we learned (rules something out)
+- Form new hypothesis based on new information
+- Continue testing
+
+## Phase 5: Take Action
+
+**Only act when ALL are true:**
+1. Understand the mechanism (not just "what fails" but "why")
+2. Can reproduce reliably
+3. Have evidence, not just theory
+4. Ruled out alternatives
+
+**Action types:**
+
+### Fix the bug
+- Make minimal, targeted change
+- Update tests to prevent regression
+- Verify fix works
+- Document in DEBUG.md
+
+### Checkpoint (if blocked)
+If you need user input:
+```
+<task type="checkpoint:decision" gate="blocking">
+  <decision>[What needs deciding]</decision>
+  <context>[Why this matters]</context>
+  <options>[Available options]</options>
+</task>
+```
+
+## Phase 6: Document Resolution
+
+Update DEBUG.md:
+
+```markdown
+## Resolution
+
+**Root Cause:** [Clear explanation]
+**Fix Applied:** [What was changed]
+```diff
+- [Old code]
++ [New code]
+```
+
+**Verification:** [How confirmed]
+- [ ] Test passes
+- [ ] Manual verification
+- [ ] No regressions
+
+**Committed:** [Hash]
+**Duration:** [How long it took]
+**Status:** RESOLVED
+```
+
+## Phase 7: Offer Next Steps
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  GOOPSPEC > DEBUG COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Bug Resolved**
+
+Root Cause: [Brief description]
+Fix: [What was changed]
+Commit: [Hash]
+
+Debug record: .goopspec/debug/DEBUG-{id}.md
+
+───────────────────────────────────────────────────────────────
+
+## Lessons Learned
+
+[Key insight from this debug session]
+
+───────────────────────────────────────────────────────────────
+
+**Next steps:**
+- Continue with current work
+- /goop-status - Check overall progress
+- /goop-pause - Save checkpoint
+
+───────────────────────────────────────────────────────────────
+```
+</process>
+
+<methodology>
+**Scientific Method Steps:**
+
+1. **Observe precisely**
+   - Not "it's broken" but "counter shows 3 when clicking once, should show 1"
+
+2. **Form falsifiable hypotheses**
+   - Must be provable wrong
+   - Make specific, testable claims
+
+3. **Design experiments**
+   - One variable at a time
+   - Clear prediction
+   - Unambiguous outcome
+
+4. **Run experiments**
+   - Document exact results
+   - No interpretation yet
+
+5. **Conclude based on evidence**
+   - Update mental model
+   - Form new hypotheses if needed
+
+**Cognitive Biases to Avoid:**
+
+| Bias | Trap | Antidote |
+|------|------|----------|
+| Confirmation | Only look for supporting evidence | Actively seek disproof |
+| Anchoring | First explanation becomes anchor | Generate 3+ hypotheses |
+| Availability | Recent bugs -> similar cause | Treat each bug as novel |
+| Sunk Cost | Keep going despite evidence | "If I started fresh...?" |
+
+**When to Restart:**
+- 2+ hours with no progress
+- 3+ "fixes" that didn't work
+- Can't explain current behavior
+- Debugging the debugger
+
+**Restart protocol:**
+1. Close all files
+2. Write what you know for certain
+3. Write what you've ruled out
+4. List new hypotheses
+5. Begin again
+</methodology>
+
+<checkpoint_types>
+**When to use checkpoints in debugging:**
+
+**checkpoint:human-verify**
+- After implementing fix, need user to test
+- Can't reproduce in your environment
+- Needs specific hardware/data
+
+**checkpoint:decision**
+- Multiple possible fixes, user must choose
+- Fix has tradeoffs (performance vs simplicity)
+- Requires architectural change
+
+**checkpoint:human-action**
+- Needs user to provide data/credentials
+- Requires access to external system
+- Needs deployment to test environment
+</checkpoint_types>

package/commands/goop-discuss.md

@@ -0,0 +1,138 @@
+---
+name: goop-discuss
+description: Capture user vision before planning - the discovery conversation
+---
+
+# GoopSpec Discuss
+
+Capture user vision and gather requirements through structured conversation before formal planning.
+
+## Usage
+
+```
+/goop-discuss [brief description]
+```
+
+## Workflow Position
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   DISCUSS   │ ──▶ │    PLAN     │ ──▶ │  RESEARCH   │
+│  (Vision)   │     │  (Intent)   │     │  (Explore)  │
+└─────────────┘     └─────────────┘     └─────────────┘
+      ↑
+(You are here)
+```
+
+The Discuss phase answers: **What does the user really want?**
+
+## What Happens
+
+1. **Vision Capture** - Understand the high-level goal
+2. **Requirements Gathering** - Ask clarifying questions to understand:
+   - Functional requirements (what it should do)
+   - Non-functional requirements (performance, security, accessibility)
+   - Constraints (time, technology, compatibility)
+   - Success criteria (how to know it's done)
+3. **Scope Definition** - Identify boundaries
+4. **Priority Clarification** - Understand what matters most
+5. **Memory Search** - Check for relevant past context
+
+## Discussion Techniques
+
+**Ask Open-Ended Questions:**
+```
+"Can you walk me through how a user would interact with this?"
+"What happens if [edge case]?"
+"Are there any existing patterns in the codebase we should follow?"
+```
+
+**Validate Understanding:**
+```
+"Let me make sure I understand correctly:
+- The feature should [summary]
+- It needs to handle [edge cases]
+- Success looks like [acceptance criteria]
+
+Is that accurate?"
+```
+
+**Challenge Assumptions:**
+```
+"I notice you mentioned X. Have you considered Y as an alternative? 
+It might be simpler because [reason]."
+```
+
+## What to Gather
+
+### Functional Requirements
+- What should the feature DO?
+- What are the inputs and outputs?
+- What are the edge cases?
+- What happens on errors?
+
+### Non-Functional Requirements
+- Performance expectations?
+- Security considerations?
+- Accessibility needs?
+- Compatibility requirements?
+
+### Context & Constraints
+- Why is this needed? What problem does it solve?
+- What existing code/patterns should be followed?
+- Any technical constraints or limitations?
+- Timeline or priority considerations?
+
+### Acceptance Criteria
+- How will we know it's "done"?
+- What tests should pass?
+- What should the user experience be?
+
+## Artifacts Created
+
+- Understanding of requirements (informal)
+- Identified edge cases
+- Agreement on acceptance criteria
+- Technical research notes (if needed)
+
+## Example
+
+```
+/goop-discuss Add user authentication
+```
+
+Agent asks:
+- "What authentication methods? Email/password? OAuth?"
+- "Should sessions persist across browser closes?"
+- "Any specific security requirements?"
+- "How should errors be displayed?"
+
+After discussion, agent summarizes understanding and asks for confirmation.
+
+## Transition to Plan
+
+When requirements are clear:
+```
+"I have a clear picture of what we need:
+[Summary of requirements]
+
+Ready to move to planning? I'll capture the formal intent 
+and requirements in the Plan phase."
+```
+
+## Next Steps
+
+After discussion:
+- `/goop-plan [description]` - Capture formal intent and requirements
+
+## Tips
+
+- Don't rush to planning - thorough discussion prevents rework
+- Ask about edge cases early
+- Validate understanding frequently
+- Challenge assumptions respectfully
+- Search memory for relevant past context
+
+---
+
+**GoopSpec**: Understand deeply, build correctly.