opencode-goopspec 0.1.0 → 0.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-goopspec",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A spec-driven development plugin for OpenCode with user-guided planning, wave execution, and verification",
   "type": "module",
   "main": "dist/index.js",
@@ -64,10 +64,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/james/opencode-goopspec.git"
+    "url": "https://github.com/hffmnnj/opencode-goopspec.git"
   },
   "bugs": {
-    "url": "https://github.com/james/opencode-goopspec/issues"
+    "url": "https://github.com/hffmnnj/opencode-goopspec/issues"
   },
-  "homepage": "https://github.com/james/opencode-goopspec#readme"
+  "homepage": "https://github.com/hffmnnj/opencode-goopspec#readme"
 }

package/references/dispatch-patterns.md

@@ -2,6 +2,41 @@
 
 GoopSpec supports multiple patterns for spawning and coordinating specialized agents. Choose the right pattern based on task characteristics.
 
+## The Dispatch Tool (CRITICAL)
+
+**ALWAYS use the native `task` tool to dispatch agents.**
+
+```typescript
+// Correct: Use task tool directly
+task({
+  subagent_type: "goop-executor",  // Agent to spawn
+  description: "Implement auth",    // 3-5 word summary
+  prompt: `[Detailed task...]`      // Full context and instructions
+})
+```
+
+### Do NOT Use
+
+| Tool | Why Not |
+|------|---------|
+| `delegate` | Different system (async delegation), not GoopSpec |
+| `goop_delegate` alone | Only composes prompts, doesn't execute |
+
+### Optional: goop_delegate for Prompt Composition
+
+If you need help composing a rich prompt with skills/references injected:
+
+```typescript
+// Step 1: Compose prompt (optional)
+goop_delegate({ agent: "goop-executor", prompt: "..." })
+// Returns: <goop_delegation> with composedPrompt
+
+// Step 2: Execute with task (REQUIRED)
+task({ subagent_type: "goop-executor", prompt: composedPrompt })
+```
+
+**Most cases: Just use `task` directly.**
+
 ## Dispatch Modes
 
 ### Sequential Dispatch

package/references/response-format.md

@@ -0,0 +1,386 @@
+# Agent Response Format
+
+All GoopSpec subagents MUST return structured responses to the orchestrator. This enables clean handoffs, progress tracking, and next-step clarity.
+
+## Core Principle
+
+```
+╔════════════════════════════════════════════════════════════════╗
+║  EVERY RESPONSE MUST ANSWER THREE QUESTIONS:                   ║
+║  1. What did I do?                                              ║
+║  2. What is the current state?                                  ║
+║  3. What should happen next?                                    ║
+╚════════════════════════════════════════════════════════════════╝
+```
+
+## Response Structure
+
+Every subagent response follows this structure:
+
+```markdown
+## [STATUS INDICATOR]
+
+**Agent:** [agent-name]
+**Task:** [task description from prompt]
+**Duration:** [~X minutes]
+
+### Summary
+[1-3 sentences on what was accomplished]
+
+### Work Completed
+
+| Item | Details |
+|------|---------|
+| [Action 1] | [Specifics] |
+| [Action 2] | [Specifics] |
+
+### Files Modified
+- `path/to/file.ts` - [what changed]
+- `path/to/other.ts` - [what changed]
+
+### Commits (if applicable)
+- `abc123` - feat(scope): description
+
+### Decisions Made
+- **[Decision]**: [Reasoning]
+
+### Memory Persisted
+- Saved: "[memory title]"
+- Concepts: [tags]
+
+### Current State
+- Phase: [from state.json]
+- Spec locked: [yes/no]
+- Wave: [N of M] (if executing)
+
+---
+
+## NEXT STEPS
+
+[Clear guidance for orchestrator]
+```
+
+## Status Indicators
+
+Use these exact headers:
+
+| Status | Header | When |
+|--------|--------|------|
+| Complete | `## TASK COMPLETE` | Work finished successfully |
+| Partial | `## TASK PARTIAL` | Some progress, more needed |
+| Blocked | `## TASK BLOCKED` | Cannot proceed, need help |
+| Failed | `## TASK FAILED` | Cannot complete task |
+| Checkpoint | `## CHECKPOINT REACHED` | Need user decision/verification |
+
+## Next Steps Format
+
+The "NEXT STEPS" section is MANDATORY. Use this format:
+
+### For Orchestrator (Most Common)
+
+```markdown
+## NEXT STEPS
+
+**For Orchestrator:**
+1. [Immediate next action]
+2. [Follow-up action if applicable]
+
+**Suggested delegation:**
+- Agent: `goop-[agent]`
+- Task: "[specific task description]"
+```
+
+### When User Action Needed
+
+```markdown
+## NEXT STEPS
+
+**User action required:**
+- [What user needs to do]
+
+**After user completes:**
+- Run: `/goop-[command]`
+- Or: Orchestrator continues with [task]
+```
+
+### When Work Is Complete
+
+```markdown
+## NEXT STEPS
+
+**Wave [N] complete.** Ready to proceed.
+
+**Options:**
+1. Continue to Wave [N+1]: [brief description]
+2. Run verification: `bun test`
+3. Review changes before proceeding
+
+**Recommended:** [specific recommendation]
+```
+
+## Agent-Specific Formats
+
+### goop-executor
+
+```markdown
+## TASK COMPLETE
+
+**Agent:** goop-executor
+**Task:** [task from BLUEPRINT.md]
+**Duration:** ~X minutes
+
+### Summary
+Implemented [feature] following existing patterns. All tests pass.
+
+### Work Completed
+
+| Task | Status | Commit |
+|------|--------|--------|
+| [Task 1] | Done | `abc123` |
+| [Task 2] | Done | `def456` |
+
+### Files Modified
+- `src/feature/index.ts` - Added main implementation
+- `src/feature/index.test.ts` - Added unit tests
+
+### Commits
+- `abc123` - feat(feature): add main implementation
+- `def456` - test(feature): add unit tests
+
+### Verification
+- [x] `bun test` - All 42 tests pass
+- [x] `bun run typecheck` - No errors
+- [x] Manual verification - Works as expected
+
+### Decisions Made
+- **Used X over Y**: Consistent with existing patterns in `src/other/`
+
+### Memory Persisted
+- Saved: "Implemented [feature] using [pattern]"
+- Concepts: [feature, pattern, typescript]
+
+### Current State
+- Phase: execute
+- Wave: 2 of 3
+- Tasks remaining: 4
+
+---
+
+## NEXT STEPS
+
+**For Orchestrator:**
+Wave 2 Task 1 complete. Continue with Task 2.
+
+**Next task:**
+- Task 2.2: [name from BLUEPRINT.md]
+- Agent: `goop-executor`
+- Files: `src/next/file.ts`
+```
+
+### goop-researcher
+
+```markdown
+## TASK COMPLETE
+
+**Agent:** goop-researcher
+**Task:** Research [topic]
+**Duration:** ~X minutes
+**Sources:** N analyzed
+
+### Summary
+Researched [topic]. Found [key insight]. Recommend [approach].
+
+### Key Findings
+
+| Category | Finding | Confidence |
+|----------|---------|------------|
+| [Area 1] | [Finding] | High |
+| [Area 2] | [Finding] | Medium |
+
+### Recommendations
+1. **Use [X]** - [rationale]
+2. **Avoid [Y]** - [rationale]
+3. **Consider [Z]** - [when applicable]
+
+### Files Created
+- `.goopspec/RESEARCH.md` - Full research findings
+
+### Memory Persisted
+- Saved: "Research: [topic]"
+- Facts: ["fact 1", "fact 2"]
+- Concepts: [topic, technology, domain]
+
+---
+
+## NEXT STEPS
+
+**Research complete.** Ready to inform planning.
+
+**For Orchestrator:**
+1. Review RESEARCH.md with user
+2. Proceed to `/goop-specify` to lock specification
+3. Or request additional research on [gap area]
+```
+
+### goop-verifier
+
+```markdown
+## VERIFICATION COMPLETE
+
+**Agent:** goop-verifier
+**Scope:** [what was verified]
+**Result:** [PASSED | GAPS FOUND | SECURITY ISSUE]
+
+### Verification Summary
+
+| Requirement | Status | Evidence |
+|-------------|--------|----------|
+| [Must-have 1] | PASS | [proof] |
+| [Must-have 2] | FAIL | [gap detail] |
+
+### Security Audit
+- [x] No hardcoded secrets
+- [x] Input validation present
+- [ ] **ISSUE:** [security concern]
+
+### Gaps Found (if any)
+
+**Gap 1: [Title]**
+- Expected: [from SPEC.md]
+- Actual: [what code does]
+- Fix: [specific remediation]
+
+### Memory Persisted
+- Saved: "Verification: [scope]"
+- Concepts: [verification, security, quality]
+
+---
+
+## NEXT STEPS
+
+**[If PASSED]:**
+Ready for acceptance. Run `/goop-accept`.
+
+**[If GAPS FOUND]:**
+1. Fix gaps before proceeding
+2. Delegate to `goop-executor` with specific fixes
+3. Re-verify after fixes
+
+**[If SECURITY ISSUE]:**
+STOP. Address security issues before any further work.
+- Issue: [description]
+- Severity: [Critical/High/Medium]
+- Action: [remediation]
+```
+
+### goop-explorer
+
+```markdown
+## EXPLORATION COMPLETE
+
+**Agent:** goop-explorer
+**Scope:** [what was mapped]
+**Duration:** ~X minutes
+
+### Codebase Summary
+- **Stack:** [language, framework, runtime]
+- **Structure:** [architecture pattern]
+- **Size:** N files, M directories
+
+### Key Discoveries
+
+| Area | Finding |
+|------|---------|
+| Entry points | [files] |
+| Patterns | [patterns found] |
+| Conventions | [naming, style] |
+| Concerns | [issues noted] |
+
+### Directory Map
+```
+project/
+├── src/           # [description]
+├── tests/         # [description]
+└── config/        # [description]
+```
+
+### Memory Persisted
+- Saved: "Codebase map: [project]"
+- Concepts: [stack, patterns, structure]
+
+---
+
+## NEXT STEPS
+
+**Exploration complete.** Codebase mapped.
+
+**For Orchestrator:**
+1. Use findings to inform BLUEPRINT.md
+2. Note conventions for executor guidance
+3. Address concerns: [list if any]
+```
+
+## Checkpoint Format
+
+When a checkpoint is needed (user decision, verification, or manual action):
+
+```markdown
+## CHECKPOINT REACHED
+
+**Agent:** [agent-name]
+**Type:** [decision | verify | action]
+**Task:** [current task]
+**Progress:** [N/M tasks complete]
+
+### Completed So Far
+
+| Task | Status | Details |
+|------|--------|---------|
+| [Task 1] | Done | [summary] |
+| [Task 2] | Done | [summary] |
+
+### Current Task
+**Task [N]:** [name]
+**Status:** Awaiting [decision/verification/action]
+
+### Checkpoint Details
+
+**[For decision checkpoints]:**
+| Option | Pros | Cons |
+|--------|------|------|
+| A: [option] | [benefits] | [tradeoffs] |
+| B: [option] | [benefits] | [tradeoffs] |
+
+**[For verification checkpoints]:**
+- URL to check: [url]
+- What to verify: [criteria]
+- Expected behavior: [description]
+
+**[For action checkpoints]:**
+- What you need to do: [action]
+- I'll verify by: [check]
+
+---
+
+## AWAITING
+
+**[For decision]:** Select option A or B
+**[For verification]:** Type "approved" or describe issues
+**[For action]:** Type "done" when complete
+```
+
+## Anti-Patterns
+
+**NEVER return:**
+- "Done" (no context)
+- "It works now" (no verification)
+- Responses without NEXT STEPS
+- Unstructured text walls
+- Missing status indicators
+
+**ALWAYS include:**
+- Clear status header
+- Summary of work
+- Files touched
+- Memory persistence
+- NEXT STEPS section

package/skills/task-delegation/skill.md

@@ -94,22 +94,69 @@ Don't pass:
 - Unrelated file contents
 - Completed task details
 
-## Using task Tool
+## The Dispatch Tool (CRITICAL)
+
+**ALWAYS use the native `task` tool to dispatch agents.**
 
 ```typescript
 task({
-  subagent_type: "general",
+  subagent_type: "goop-executor",  // Use goop-[agent-name]
   description: "Implement authentication",
   prompt: `
     ## TASK
     Implement user authentication
 
     ## CONTEXT
-    - SPEC: .goopspec/phases/phase-1/SPEC.md
+    - SPEC: .goopspec/SPEC.md
+    - BLUEPRINT: .goopspec/BLUEPRINT.md
+    
+    ## REQUIREMENTS
+    [Specific requirements from SPEC.md]
+    
+    ## VERIFICATION
+    [How to confirm task completion]
   `
 })
 ```
 
+### Available subagent_types
+
+| subagent_type | Use For |
+|---------------|---------|
+| `goop-executor` | Code implementation, features, fixes |
+| `goop-explorer` | Fast codebase mapping, pattern detection |
+| `goop-researcher` | Deep domain research, technology evaluation |
+| `goop-planner` | Architecture design, blueprint creation |
+| `goop-verifier` | Verification against spec, security audit |
+| `goop-debugger` | Bug investigation, scientific debugging |
+| `goop-tester` | Test writing, coverage analysis |
+| `goop-designer` | UI/UX design, component architecture |
+| `goop-writer` | Documentation, technical writing |
+| `goop-librarian` | Code/docs search, information retrieval |
+| `general` | Fallback for any task |
+
+### Do NOT Use These Tools for Delegation
+
+| Tool | Why NOT |
+|------|---------|
+| `delegate` | Different system (async delegation), NOT GoopSpec agents |
+| `goop_delegate` alone | Only composes prompts, doesn't execute - must follow with `task` |
+
+### Optional: goop_delegate for Rich Prompts
+
+Use `goop_delegate` only when you need skills/references auto-injected:
+
+```typescript
+// Step 1: Compose prompt with goop_delegate (optional)
+const result = goop_delegate({ agent: "goop-executor", prompt: "..." })
+// Returns: <goop_delegation> JSON with composedPrompt
+
+// Step 2: Execute with task (REQUIRED)
+task({ subagent_type: "goop-executor", prompt: composedPrompt })
+```
+
+**For most cases: Just use `task` directly.**
+
 ## Error Handling
 
 If delegated task fails: