opencode-goopspec 0.1.5 → 0.1.6

package/references/plan-process.md

@@ -0,0 +1,397 @@
+# Planning Process
+
+Detailed process for `/goop-plan` - creating SPEC.md and BLUEPRINT.md from discovery.
+
+## Phase 1: Gate Check
+
+**Execute BEFORE anything else:**
+
+```
+goop_status()
+goop_state({ action: "get" })          # NEVER read state.json directly
+Read(".goopspec/REQUIREMENTS.md")
+```
+
+### 1.1 Check interviewComplete
+
+```
+IF state.interviewComplete != true:
+  REFUSE with:
+  
+  ## 🔮 GoopSpec · Gate Blocked
+  
+  ✗ Discovery interview required before planning.
+  
+  → Run: `/goop-discuss`
+  
+  ---
+  
+  EXIT command.
+```
+
+### 1.2 Check REQUIREMENTS.md exists
+
+```
+IF .goopspec/REQUIREMENTS.md does not exist:
+  REFUSE with:
+  
+  ## 🔮 GoopSpec · Gate Blocked
+  
+  ✗ No discovery output found.
+  
+  → Run: `/goop-discuss`
+  
+  ---
+  
+  EXIT command.
+```
+
+### 1.3 Gate passed
+
+```
+## 🔮 GoopSpec · Planning
+
+✓ Discovery gate passed
+
+⏳ Creating specification and blueprint...
+
+---
+```
+
+---
+
+## Phase 2: Load Context
+
+**Note:** Existing document archiving is handled in `/goop-discuss` Phase 1.2. 
+By this point, any prior milestone has already been archived or the user chose to continue it.
+
+### 2.1 Load discovery interview
+
+```
+Read(".goopspec/REQUIREMENTS.md")
+```
+
+Extract:
+- Vision
+- Must-haves (with acceptance criteria)
+- Constraints
+- Out of scope
+- Assumptions
+- Risks
+
+### 2.2 Search memory
+
+```
+memory_search({ query: "[feature] architecture decisions patterns", limit: 5 })
+```
+
+### 2.3 Create or load project knowledge
+
+```
+Read(".goopspec/PROJECT_KNOWLEDGE_BASE.md")
+```
+
+**If PROJECT_KNOWLEDGE_BASE.md does not exist, CREATE IT:**
+
+```markdown
+# Project Knowledge Base
+
+**Last Updated:** [timestamp]
+**Updated By:** orchestrator (auto-generated from discovery)
+
+---
+
+## Project Identity
+
+**Name:** [From REQUIREMENTS.md vision]
+**Type:** [Inferred from constraints]
+**Stage:** Active
+
+---
+
+## Stack (Non-Negotiable)
+
+[Extract from REQUIREMENTS.md Constraints section]
+
+### Runtime & Language
+- **Runtime:** [e.g., Node.js / Bun / Browser]
+- **Language:** [e.g., TypeScript]
+
+### Frameworks & Libraries
+- **Framework:** [From constraints]
+- **Testing:** [From constraints or infer from package.json]
+
+---
+
+## Conventions
+
+[Extract from REQUIREMENTS.md or infer from codebase]
+
+### File Naming
+- **Files:** [kebab-case / camelCase]
+- **Tests:** [*.test.ts / *.spec.ts]
+
+### Code Style
+- **Exports:** [Named / Default]
+
+---
+
+## Architecture Decisions
+
+*To be populated during planning and execution.*
+
+---
+
+## Known Gotchas
+
+*To be populated as issues are discovered.*
+
+---
+
+*Auto-generated from discovery interview. Update as project evolves.*
+```
+
+Write to `.goopspec/PROJECT_KNOWLEDGE_BASE.md` before proceeding.
+
+---
+
+## Phase 3: Spawn Planner
+
+**Display banner:**
+```
+## 🔮 GoopSpec · Creating Documents
+
+⏳ Spawning planner to create SPEC.md and BLUEPRINT.md...
+
+---
+```
+
+**Spawn goop-planner with full context:**
+
+```
+task({
+  subagent_type: "goop-planner",
+  description: "Create SPEC and BLUEPRINT",
+  prompt: `
+## TASK
+Create specification and blueprint from discovery interview.
+
+## PROJECT CONTEXT
+[From PROJECT_KNOWLEDGE_BASE.md if exists]
+- Stack: [technologies]
+- Conventions: [naming, patterns]
+
+## DISCOVERY INTERVIEW OUTPUT
+[Full content of REQUIREMENTS.md]
+
+## INSTRUCTIONS
+
+1. **Verify discovery completeness:**
+   - Vision defined? 
+   - Must-haves listed with acceptance criteria?
+   - Out of scope defined?
+   - Risks identified?
+   
+   If missing critical info, return BLOCKED.
+
+2. **Create .goopspec/SPEC.md:**
+   - Transform must-haves into formal requirements (MH1, MH2, etc.)
+   - Include acceptance criteria for each
+   - Add traceability section (will be filled after blueprint)
+   - Mark status as "Draft"
+
+3. **Create .goopspec/BLUEPRINT.md:**
+   - Design wave architecture
+   - Create tasks that cover ALL must-haves
+   - Add spec coverage to each task
+   - Build traceability matrix
+
+4. **Update .goopspec/SPEC.md:**
+   - Fill traceability matrix (must-have → tasks)
+   - Verify 100% coverage
+
+5. **Initialize .goopspec/CHRONICLE.md:**
+   - Phase: plan → ready for specify
+   - Documents created with timestamps
+
+6. **Save to memory:**
+   - Key architectural decisions
+   - Technology choices with rationale
+
+7. **Return XML response envelope** with:
+   - BLUEPRINT COMPLETE status
+   - Wave summary
+   - Traceability summary
+   - Handoff instructions
+
+## VERIFICATION
+Before returning COMPLETE:
+- [ ] Every must-have has mapped tasks
+- [ ] Every task has spec coverage
+- [ ] Traceability matrix shows 100%
+- [ ] SPEC.md has all sections filled
+- [ ] BLUEPRINT.md has verification commands
+  `
+})
+```
+
+---
+
+## Phase 4: Handle Response
+
+**Parse XML response from planner.**
+
+**On `COMPLETE` status:**
+
+Read created documents:
+```
+Read(".goopspec/SPEC.md")
+Read(".goopspec/BLUEPRINT.md")
+```
+
+Display completion:
+```
+## 🔮 GoopSpec · Planning Complete
+
+✨ Blueprint created successfully
+
+**Feature:** [Name from SPEC.md]
+
+| Document | Status | Location |
+|----------|--------|----------|
+| Spec | ✓ Created | .goopspec/SPEC.md |
+| Blueprint | ✓ Created | .goopspec/BLUEPRINT.md |
+| Chronicle | ✓ Created | .goopspec/CHRONICLE.md |
+
+**[N] must-haves** | **[M] waves** | **[P] tasks**
+
+### Traceability
+| Must-Have | Covered By |
+|-----------|------------|
+| MH1 | Wave X, Tasks Y |
+| MH2 | Wave X, Tasks Y |
+
+✓ Coverage: 100%
+
+### Next Step
+
+**Lock the specification** — Confirm requirements before execution
+
+→ `/goop-specify`
+
+---
+
+Start a **new session** for fresh context, then run the command.
+```
+
+**Generate HANDOFF.md:**
+
+```markdown
+# Session Handoff
+
+**Generated:** [timestamp]
+**Phase:** plan
+
+## Accomplished
+- [x] Discovery interview completed
+- [x] SPEC.md created with [N] must-haves
+- [x] BLUEPRINT.md created with [M] waves, [P] tasks
+- [x] 100% traceability achieved
+
+## Current State
+- Phase: plan
+- Interview: complete
+- Spec: draft (not locked)
+
+## Next Session
+Run: /goop-specify
+
+## Files to Read
+1. .goopspec/SPEC.md — Requirements
+2. .goopspec/BLUEPRINT.md — Execution plan
+
+## Context Summary
+Planning complete for [feature]. [N] must-haves mapped to [P] tasks
+across [M] waves. Ready to lock specification.
+```
+
+**On `BLOCKED` status:**
+
+```
+## 🔮 GoopSpec · Planning Blocked
+
+✗ Cannot proceed
+
+**Blocker:** [From planner response]
+
+**Options:**
+1. Provide more context → `/goop-discuss`
+2. Research the unknown → `/goop-research [topic]`
+
+---
+```
+
+Use `question` tool to get user choice.
+
+---
+
+## Phase 5: Memory Persistence
+
+After successful planning:
+
+```
+memory_save({
+  type: "note",
+  title: "Plan: [Feature Name]",
+  content: "Created [N]-wave blueprint. Key decisions: [list]. Must-haves: [summary].",
+  concepts: ["planning", "blueprint", "[domain]"],
+  importance: 0.7
+})
+```
+
+---
+
+## Examples
+
+### Gate Passed
+```
+User: /goop-plan
+
+Orchestrator: 
+## 🔮 GoopSpec · Planning
+
+✓ Discovery gate passed
+
+[Spawns goop-planner]
+
+...
+
+## 🔮 GoopSpec · Planning Complete
+
+**Feature:** Dark Mode Toggle
+
+| Document   | Status  |
+|------------|---------|
+| Spec       | Created |
+| Blueprint  | Created |
+
+**3 must-haves** | **2 waves** | **5 tasks**
+
+→ Next: `/goop-specify`
+```
+
+### Gate Blocked
+```
+User: /goop-plan
+
+Orchestrator:
+## 🔮 GoopSpec · Gate Blocked
+
+✗ Discovery interview required before planning.
+
+→ Run: `/goop-discuss`
+```
+
+---
+
+*Planning Process v0.1.6*

package/references/plugin-architecture.md

@@ -209,4 +209,4 @@ goop_adl({
 
 ## Version
 
-Plugin Architecture Reference v0.1.5
+Plugin Architecture Reference v0.1.6

package/references/quick-process.md

@@ -0,0 +1,343 @@
+# Quick Mode Process
+
+Detailed process for `/goop-quick` - fast-track execution for small, well-defined tasks.
+
+## Phase 1: Qualify
+
+**Execute BEFORE any implementation:**
+
+### 1.1 Check current state
+
+```
+goop_status()
+goop_state({ action: "get" })        # NEVER read state.json directly
+```
+
+### 1.2 Validate quick criteria
+
+The task MUST pass ALL five criteria:
+
+| Criterion | Check | Pass? |
+|-----------|-------|-------|
+| **Scope** | Single file OR max 3 tightly coupled files | [ ] |
+| **Clarity** | Intent is clear and unambiguous | [ ] |
+| **Complexity** | No architectural decisions required | [ ] |
+| **Effort** | Estimated < 15 minutes of work | [ ] |
+| **Dependencies** | No new packages/dependencies needed | [ ] |
+
+**If ANY criterion fails:**
+
+```
+## 🔮 GoopSpec · Quick Mode Denied
+
+✗ Task does not qualify for quick mode.
+
+**Failed criteria:**
+- [List failed criteria]
+
+**Recommendation:** This task needs proper planning.
+
+→ Run: `/goop-discuss [task]`
+
+---
+```
+
+### 1.3 Search for prior context
+
+```
+memory_search({ query: "[task topic] [file/component names]", limit: 3 })
+```
+
+Check for:
+- Similar past fixes
+- Related decisions
+- Known patterns in this area
+
+---
+
+## Phase 2: Capture
+
+**Display quick mode banner:**
+
+```
+## 🔮 GoopSpec · Quick Mode
+
+**Task:** [Task description]
+
+---
+```
+
+### 2.1 Define the plan (one sentence)
+
+Format:
+> **Plan:** [Action verb] [what] in [where].
+
+Examples:
+- "Adjust z-index in Modal.css."
+- "Fix typo in navbar component."
+- "Add null check in useAuth hook."
+
+### 2.2 Define success criterion (one statement)
+
+Format:
+> **Success:** [Observable outcome].
+
+Examples:
+- "Modal appears above overlay."
+- "Navbar displays 'Settings' instead of 'Settnigs'."
+- "No crash when user is null."
+
+### 2.3 Display the capture
+
+```
+## 🔮 GoopSpec · Quick Plan
+
+**Plan:** [One sentence]
+
+**Success:** [One criterion]
+
+**Files:** [List of files to modify]
+
+Proceeding to execute...
+
+---
+```
+
+### 2.4 Log to ADL
+
+```
+goop_adl({
+  action: "append",
+  type: "decision",
+  description: "Quick fix: [brief description]",
+  entry_action: "Using quick mode for small, scoped change",
+  files: ["path/to/file.ts"]
+})
+```
+
+---
+
+## Phase 3: Execute
+
+### 3.1 Read the target files
+
+```
+Read("[target file(s)]")
+```
+
+Understand the current state before making changes.
+
+### 3.2 Make the change
+
+Apply the fix using `Edit` or `Write` tools.
+
+**Rules:**
+- ONE logical change per file
+- Follow existing code patterns
+- No scope creep - stick to the plan
+
+### 3.3 Verify the change works
+
+Run relevant checks:
+
+```bash
+# Type check (if TypeScript)
+bun run typecheck
+
+# Run tests (if applicable)
+bun test [relevant test file]
+
+# Or manual verification
+[command to verify]
+```
+
+### 3.4 Create atomic commit
+
+```bash
+git add [files]
+git commit -m "fix: [brief description]"
+```
+
+Commit message format:
+- `fix:` for bug fixes
+- `chore:` for maintenance
+- `docs:` for documentation
+- `style:` for formatting
+
+---
+
+## Phase 4: Verify & Accept
+
+### 4.1 Confirm success criterion
+
+Check that the defined success criterion is met.
+
+**If verification fails:**
+```
+## 🔮 GoopSpec · Quick Fix Failed
+
+✗ Verification failed.
+
+**Expected:** [success criterion]
+**Actual:** [what happened]
+
+Options:
+1. Retry with adjusted approach
+2. Escalate to full workflow
+
+---
+```
+
+### 4.2 Display completion
+
+```
+## 🔮 GoopSpec · Quick Fix Complete
+
+✨ Task completed successfully
+
+**Task:** [Description]
+**Commit:** [sha]
+**Files:** [list]
+
+**Verification:** ✓ [success criterion met]
+
+---
+
+Type **'accept'** to confirm, or describe any issues.
+```
+
+### 4.3 Handle user response
+
+| Response | Action |
+|----------|--------|
+| "accept" / "done" / "looks good" | Mark complete, thank user |
+| Describes issue | Assess if fixable in quick mode, or escalate |
+| Silence (continues other work) | Consider task accepted |
+
+### 4.4 Final confirmation
+
+```
+## 🔮 GoopSpec · Accepted
+
+✓ Quick fix confirmed.
+
+**Summary:**
+- [One line summary]
+- Commit: [sha]
+
+---
+```
+
+---
+
+## Escalation Rules
+
+**Immediately escalate to `/goop-discuss` if:**
+
+| Situation | Why |
+|-----------|-----|
+| Fix requires touching 4+ files | Scope too large for quick mode |
+| Architectural decision needed | Requires deliberation |
+| New dependency required | Has ripple effects |
+| Fix doesn't work after 2 attempts | Deeper issue exists |
+| User requests change in scope | Needs proper planning |
+
+**Escalation message:**
+
+```
+## 🔮 GoopSpec · Escalating
+
+This task has grown beyond quick mode scope.
+
+**Reason:** [Why escalating]
+
+**Recommendation:** Start a proper discovery interview.
+
+→ Run: `/goop-discuss [task description]`
+
+---
+```
+
+---
+
+## Examples
+
+### Simple Fix
+
+```
+User: /goop-quick Fix the z-index on the modal
+
+Orchestrator:
+## 🔮 GoopSpec · Quick Mode
+
+**Task:** Fix the z-index on the modal
+
+---
+
+[Checking quick criteria...]
+✓ Single file (Modal.css)
+✓ Clear intent (z-index issue)
+✓ No architecture decisions
+✓ < 15 min effort
+✓ No new dependencies
+
+## 🔮 GoopSpec · Quick Plan
+
+**Plan:** Increase z-index value in Modal.css.
+
+**Success:** Modal appears above overlay.
+
+**Files:** src/components/Modal.css
+
+Proceeding to execute...
+
+---
+
+[Reads file, makes change, commits]
+
+## 🔮 GoopSpec · Quick Fix Complete
+
+✨ Task completed successfully
+
+**Task:** Fix the z-index on the modal
+**Commit:** abc1234
+**Files:** src/components/Modal.css
+
+**Verification:** ✓ Modal now has z-index: 1000, above overlay (z-index: 100)
+
+---
+
+Type **'accept'** to confirm.
+
+User: accept
+
+## 🔮 GoopSpec · Accepted
+
+✓ Quick fix confirmed.
+```
+
+### Escalation Example
+
+```
+User: /goop-quick Add user authentication
+
+Orchestrator:
+## 🔮 GoopSpec · Quick Mode Denied
+
+✗ Task does not qualify for quick mode.
+
+**Failed criteria:**
+- Scope: Auth affects many files (routes, middleware, UI)
+- Complexity: Requires architectural decisions (JWT vs sessions)
+- Dependencies: Likely needs new packages
+
+**Recommendation:** This task needs proper planning.
+
+→ Run: `/goop-discuss Add user authentication`
+
+---
+```
+
+---
+
+*Quick Mode Process v0.1.6*