opencode-goopspec 0.1.0

package/commands/goop-execute.md

@@ -0,0 +1,137 @@
+---
+name: goop-execute
+description: Start the Execute phase - wave-based implementation
+---
+
+# GoopSpec Execute
+
+Implement the specification through wave-based task execution with orchestrated subagents.
+
+## Usage
+
+```
+/goop-execute
+```
+
+## Workflow Position
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│    PLAN     │ ──▶ │  RESEARCH   │ ──▶ │   SPECIFY   │
+│  (Intent)   │     │  (Explore)  │     │ (Contract)  │
+└─────────────┘     └─────────────┘     └─────────────┘
+                                              │
+       ┌──────────────────────────────────────┘
+       ▼
+┌─────────────┐     ┌─────────────┐
+│   EXECUTE   │ ──▶ │   ACCEPT    │
+│   (Build)   │     │  (Verify)   │
+└─────────────┘     └─────────────┘
+       ↑
+ (You are here)
+```
+
+The Execute phase answers: **Build exactly what the spec says.**
+
+## What Happens
+
+1. **Wave-Based Execution** - Tasks grouped into sequential waves:
+   - **Wave 1: Foundation** - Setup, configuration, base structures
+   - **Wave 2: Core** - Main feature, business logic, data handling
+   - **Wave 3: Integration** - Connect components, wire to existing system
+   - **Wave 4: Polish** - Error handling, edge cases, documentation
+
+2. **Orchestrator Coordination** - Orchestrator acts as CONDUCTOR:
+   - Delegates tasks to specialized subagents
+   - Tracks progress in CHRONICLE.md
+   - Applies deviation rules automatically
+   - Handles blockers and checkpoints
+   - **NEVER writes code itself**
+
+3. **Task Execution** - For each task:
+   - Read from BLUEPRINT.md
+   - Check deviation rules
+   - Delegate to goop-executor agent
+   - Agent implements with memory protocol
+   - Atomic commit per task
+   - Update CHRONICLE.md
+   - Verify tests pass
+
+4. **Deviation Handling** - Auto-fix without asking:
+   - **Rule 1:** Bugs (type errors, logic errors, crashes)
+   - **Rule 2:** Missing critical functionality (validation, error handling)
+   - **Rule 3:** Blocking issues (missing deps, broken imports)
+   - **Rule 4:** STOP for architectural decisions (new tables, framework changes)
+
+5. **Checkpoint Handling** - Pause for user input when needed:
+   - `checkpoint:verify` - User verifies functionality
+   - `checkpoint:decision` - User makes decision
+   - `checkpoint:action` - User performs action
+
+## Wave Principles
+
+1. **Sequential waves** - Wave N completes before Wave N+1 starts
+2. **Vertical slices** - Each wave delivers working functionality
+3. **Atomic commits** - Each task = one commit
+4. **Verification gates** - Tests must pass between waves
+
+## Artifacts Created/Updated
+
+- `CHRONICLE.md` - Real-time progress tracking:
+  - Current wave and task
+  - Completed tasks with commit hashes
+  - Deviations logged
+  - Blockers noted
+
+- Git commits - One per task:
+  ```
+  feat(wave-task): description
+  
+  - Change 1
+  - Change 2
+  ```
+
+## Example
+
+After spec locked for authentication:
+
+```
+/goop-execute
+```
+
+Orchestrator executes:
+- Wave 1: Setup auth directory, install jose library
+- Wave 2: Implement login function, session management
+- Wave 3: Wire to API routes, connect to user model
+- Wave 4: Add error handling, write tests
+
+Each task delegated to goop-executor, committed atomically.
+
+## Continuation Enforcement
+
+The agent **CANNOT stop** with incomplete tasks:
+- Incomplete todos = forced continuation
+- Only checkpoints allow pause
+- User must explicitly confirm completion
+- Max continuation prompts before escalation
+
+## Next Steps
+
+After execution:
+- `/goop-accept` - Verify and accept completion (ACCEPTANCE GATE)
+
+During execution:
+- `/goop-status` - Check progress
+- `/goop-pause` - Save checkpoint manually
+
+## Quick Mode Execution
+
+For Quick tasks:
+- Abbreviated waves (often just 1-2)
+- Faster delegation
+- Less formal tracking
+- Direct to Accept phase
+
+---
+
+**GoopSpec**: Execute with precision, deliver with confidence.

package/commands/goop-help.md

@@ -0,0 +1,82 @@
+---
+name: goop-help
+description: Show help and information about GoopSpec
+---
+
+# GoopSpec Help
+
+Display help information and available commands.
+
+## Usage
+
+```
+/goop-help
+```
+
+## Available Commands
+
+**Project Management:**
+- `/goop-status` - Show current status
+- `/goop-milestone [name]` - Start a new milestone
+- `/goop-complete` - Complete and archive a milestone
+
+**Discovery:**
+- `/goop-discuss [description]` - Capture user vision before planning
+- `/goop-research` - Domain research for complex phases
+- `/goop-map-codebase` - Brownfield codebase analysis
+
+**Phase Workflow:**
+- `/goop-plan [description]` - Plan a feature or phase
+- `/goop-specify` - Lock the specification (CONTRACT GATE)
+- `/goop-execute` - Execute wave-based implementation
+- `/goop-accept` - Verify and accept completion (ACCEPTANCE GATE)
+- `/goop-amend [change]` - Propose changes to locked spec
+- `/goop-debug` - Debug with scientific method workflow
+- `/goop-quick [description]` - Small tasks without full phase planning
+
+**Session Management:**
+- `/goop-pause [name]` - Save checkpoint
+- `/goop-resume [id]` - Resume from checkpoint
+
+**Memory:**
+- `/goop-remember [content]` - Save to persistent memory
+- `/goop-recall [query]` - Search persistent memory
+- `/goop-memory` - View memory system status
+
+**Setup:**
+- `/goop-setup` - First-time setup wizard
+- `/goop-help` - Show this help
+
+**Quick Keywords:**
+Say these in any message:
+- `"goopspec"` or `"goop"` - Activate GoopSpec mode
+- `"spec it"` - Create a spec for current task
+- `"finish it"` - Enforced continuation mode (complete all)
+- `"checkpoint"` - Save checkpoint
+
+## Concepts
+
+**Enforced Task Continuation:** The agent keeps working until tasks are complete, with clear checkpoints for user confirmation.
+
+**Spec-Driven Development:** Every task starts with a clear specification. The agent follows the spec, and changes require explicit agreement.
+
+**Fresh Context:** Each phase uses fresh context to keep plans and execution precise and focused.
+
+**Audit and Confirmation:** After execution, run verification and confirm with the user before planning the next phase.
+
+## Configuration
+
+Edit `.goopspec/config.json` to customize:
+- Enforced task continuation settings (max prompts, interval)
+- Spec enforcement (strict mode)
+- Agent models
+- Auto-save options
+
+## Links
+
+- GitHub: https://github.com/james/opencode-goopspec
+- Documentation: See README.md
+
+---
+
+**GoopSpec**: Spec-first execution with user confirmation gates.

package/commands/goop-map-codebase.md

@@ -0,0 +1,501 @@
+---
+name: goop-map-codebase
+description: Map an existing codebase for brownfield projects - understand architecture, stack, and conventions
+tools:
+  read: true
+  write: true
+  bash: true
+  task: true
+  glob: true
+  grep: true
+---
+
+<objective>
+Map an existing codebase for brownfield projects.
+
+Analyzes codebase with parallel Explore agents. Creates `.goopspec/codebase/` with 7 focused documents covering stack, architecture, structure, conventions, testing, integrations, and concerns.
+
+Use before `/goop-new` on existing codebases. Provides the context needed to extend rather than replace.
+
+**Creates:**
+- `.goopspec/codebase/STACK.md` - Technology stack
+- `.goopspec/codebase/ARCHITECTURE.md` - Architecture overview
+- `.goopspec/codebase/STRUCTURE.md` - Directory structure
+- `.goopspec/codebase/CONVENTIONS.md` - Code conventions
+- `.goopspec/codebase/TESTING.md` - Testing approach
+- `.goopspec/codebase/INTEGRATIONS.md` - External integrations
+- `.goopspec/codebase/CONCERNS.md` - Known issues and tech debt
+</objective>
+
+<execution_context>
+@/home/james/Documents/opencode-goopspec/templates/codebase/stack.md
+@/home/james/Documents/opencode-goopspec/templates/codebase/architecture.md
+@/home/james/Documents/opencode-goopspec/templates/codebase/conventions.md
+</execution_context>
+
+<process>
+## Phase 1: Setup
+
+1. **Check for existing codebase map**
+   ```bash
+   [ -d .goopspec/codebase ] && echo "Codebase map already exists"
+   ```
+
+2. **Initialize .goopspec if needed**
+   ```bash
+   mkdir -p .goopspec/codebase
+   ```
+
+3. **Detect project type**
+   ```bash
+   # Check for common project indicators
+   [ -f package.json ] && echo "Node.js project"
+   [ -f requirements.txt ] && echo "Python project"
+   [ -f Cargo.toml ] && echo "Rust project"
+   [ -f go.mod ] && echo "Go project"
+   [ -f pom.xml ] && echo "Java/Maven project"
+   [ -f build.gradle ] && echo "Java/Gradle project"
+   ls -la
+   ```
+
+## Phase 2: Parallel Exploration
+
+Spawn 7 parallel explore agents via `task` tool:
+
+### Explorer 1: Stack Detection
+```
+Analyze the technology stack of this codebase.
+- Programming languages
+- Frameworks and libraries
+- Build tools
+- Database
+- Testing frameworks
+- Dev tools (linting, formatting, etc.)
+
+Create .goopspec/codebase/STACK.md
+```
+
+### Explorer 2: Architecture Analysis
+```
+Analyze the architecture of this codebase.
+- Overall pattern (MVC, layered, hexagonal, etc.)
+- Component relationships
+- Data flow
+- Key abstractions
+- Design patterns used
+
+Create .goopspec/codebase/ARCHITECTURE.md
+```
+
+### Explorer 3: Structure Mapping
+```
+Map the directory and file structure.
+- Top-level organization
+- Module/package boundaries
+- Where different types of code live
+- Configuration locations
+- Asset locations
+
+Create .goopspec/codebase/STRUCTURE.md
+```
+
+### Explorer 4: Conventions Discovery
+```
+Identify code conventions and patterns.
+- Naming conventions
+- File organization
+- Code style
+- Import patterns
+- Error handling patterns
+- Documentation style
+
+Create .goopspec/codebase/CONVENTIONS.md
+```
+
+### Explorer 5: Testing Analysis
+```
+Analyze the testing approach.
+- Testing frameworks used
+- Test organization
+- Coverage patterns
+- Test types (unit, integration, e2e)
+- Testing gaps
+
+Create .goopspec/codebase/TESTING.md
+```
+
+### Explorer 6: Integrations Inventory
+```
+Identify external integrations.
+- APIs consumed
+- Services used
+- Third-party dependencies
+- Environment requirements
+- Secrets/configuration needed
+
+Create .goopspec/codebase/INTEGRATIONS.md
+```
+
+### Explorer 7: Concerns & Debt
+```
+Identify issues, concerns, and tech debt.
+- Code smells
+- Security concerns
+- Performance issues
+- Outdated dependencies
+- Known bugs or limitations
+- Areas needing attention
+
+Create .goopspec/codebase/CONCERNS.md
+```
+
+Wait for all explorers to complete.
+
+## Phase 3: Synthesize Findings
+
+Collect and organize findings from all 7 explorers:
+
+1. Check for conflicts between explorers
+2. Identify the most critical insights
+3. Summarize for quick reference
+4. Flag areas needing clarification
+
+## Phase 4: Write Codebase Documents
+
+### STACK.md
+```markdown
+# Technology Stack
+
+**Analyzed:** [Date]
+**Project Type:** [Detected type]
+
+## Languages
+- [Language] [version] - [Primary use]
+
+## Frameworks & Libraries
+### Core
+- [Framework] [version] - [Purpose]
+
+### Supporting
+- [Library] [version] - [Purpose]
+
+## Build & Dev Tools
+- [Tool] - [Purpose]
+
+## Database
+- [Database] [version] - [Usage pattern]
+
+## Testing
+- [Framework] - [Test types]
+
+## Key Dependencies
+```json
+{
+  "critical": ["dep1", "dep2"],
+  "utility": ["dep3", "dep4"]
+}
+```
+
+## Version Info
+- Node/Python/Rust/etc: [version]
+- Package manager: [npm/pip/cargo/etc]
+```
+
+### ARCHITECTURE.md
+```markdown
+# Architecture Overview
+
+**Pattern:** [MVC/Layered/Hexagonal/etc]
+**Complexity:** [Simple/Moderate/Complex]
+
+## High-Level Structure
+
+[Diagram or description of major components]
+
+## Component Relationships
+
+### [Component A]
+- **Responsibility:** [What it does]
+- **Depends on:** [Other components]
+- **Used by:** [Other components]
+
+### [Component B]
+- **Responsibility:** [What it does]
+- **Depends on:** [Other components]
+- **Used by:** [Other components]
+
+## Data Flow
+
+[Description of how data moves through the system]
+
+## Key Abstractions
+
+1. **[Abstraction]** - [Purpose and usage]
+2. **[Abstraction]** - [Purpose and usage]
+
+## Design Patterns
+
+- **[Pattern]** - [Where used and why]
+
+## Entry Points
+
+- [Entry 1] - [Purpose]
+- [Entry 2] - [Purpose]
+```
+
+### STRUCTURE.md
+```markdown
+# Directory Structure
+
+```
+project/
+├── [dir]/          # [Purpose]
+│   ├── [subdir]/   # [Purpose]
+│   └── ...
+├── [dir]/          # [Purpose]
+└── ...
+```
+
+## Directory Purposes
+
+### /[directory]
+- **Contains:** [What lives here]
+- **Convention:** [How files organized]
+- **Examples:** [Key files]
+
+## File Organization Patterns
+
+- [Pattern 1]
+- [Pattern 2]
+
+## Configuration Locations
+
+- [Config 1] - [Purpose]
+- [Config 2] - [Purpose]
+```
+
+### CONVENTIONS.md
+```markdown
+# Code Conventions
+
+## Naming
+- **Variables:** [convention]
+- **Functions:** [convention]
+- **Classes:** [convention]
+- **Files:** [convention]
+
+## Code Style
+- **Indentation:** [spaces/tabs, count]
+- **Line length:** [max]
+- **Quotes:** [single/double]
+- **Semicolons:** [required/optional]
+
+## Organization
+- **Imports:** [order and style]
+- **Exports:** [pattern]
+- **File length:** [typical max]
+
+## Patterns
+- **Error handling:** [pattern]
+- **Async:** [pattern - callbacks/promises/async-await]
+- **Null checking:** [pattern]
+- **Comments:** [style and when used]
+
+## Documentation
+- **Required:** [what must be documented]
+- **Style:** [JSDoc/TSDoc/etc]
+
+## Anti-Patterns Present
+- [Anti-pattern] - [Where found]
+```
+
+### TESTING.md
+```markdown
+# Testing Approach
+
+## Frameworks
+- **[Framework]** - [Unit/Integration/E2E]
+
+## Test Organization
+- **Location:** [Where tests live]
+- **Naming:** [Test file naming]
+- **Structure:** [Describe/It blocks, etc.]
+
+## Coverage
+- **Current:** [Estimated % or "unknown"]
+- **Gaps:** [Areas lacking tests]
+
+## Test Types
+- **Unit:** [What gets unit tested]
+- **Integration:** [What gets integration tested]
+- **E2E:** [What gets E2E tested]
+
+## Running Tests
+```bash
+[Command to run tests]
+```
+
+## Testing Gaps
+- [Gap 1] - [Impact]
+- [Gap 2] - [Impact]
+```
+
+### INTEGRATIONS.md
+```markdown
+# External Integrations
+
+## APIs Consumed
+
+### [API Name]
+- **Endpoint:** [URL]
+- **Auth:** [Method]
+- **Usage:** [How used in codebase]
+- **Env vars:** [Required variables]
+
+## Services
+
+### [Service Name]
+- **Type:** [Database/Cache/Queue/etc]
+- **Provider:** [AWS/Railway/etc]
+- **Connection:** [How connected]
+
+## Third-Party Libraries
+
+### Critical
+- [Library] - [Purpose] - [Version constraint]
+
+### Nice-to-Have
+- [Library] - [Purpose]
+
+## Environment Requirements
+
+### Required Variables
+```
+VARIABLE_NAME=[description]
+```
+
+### Optional Variables
+```
+OPTIONAL_VAR=[description]
+```
+
+## Secrets Management
+- **Approach:** [How secrets handled]
+- **Location:** [Where stored]
+```
+
+### CONCERNS.md
+```markdown
+# Known Issues & Concerns
+
+## Code Smells
+
+### [Concern 1]
+- **Location:** [Files affected]
+- **Issue:** [Description]
+- **Impact:** [Severity]
+- **Recommendation:** [What to do]
+
+## Security Concerns
+
+### [Security Issue]
+- **Risk:** [Description]
+- **Severity:** [Critical/High/Medium/Low]
+- **Mitigation:** [If any]
+
+## Performance Issues
+
+### [Performance Issue]
+- **Symptom:** [What happens]
+- **Cause:** [Root cause]
+- **Impact:** [How bad]
+
+## Outdated Dependencies
+
+- **[Dependency]** [current] -> [latest] - [Risk level]
+
+## Tech Debt
+
+### [Debt Item]
+- **Description:** [What needs refactoring]
+- **Effort:** [Estimated]
+- **Priority:** [When to address]
+
+## Recommended Priorities
+
+1. **[Priority 1]** - [Why urgent]
+2. **[Priority 2]** - [Why important]
+```
+
+## Phase 5: Update State
+
+Update STATE.md:
+- Mark codebase as mapped
+- Add timestamp
+- Link to codebase docs
+
+## Phase 6: Offer Next Steps
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  GOOPSPEC > CODEBASE MAPPED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**Codebase Analysis Complete**
+
+7 explorers analyzed your codebase:
+- Stack identified
+- Architecture mapped
+- Structure documented
+- Conventions discovered
+- Testing analyzed
+- Integrations inventoried
+- Concerns flagged
+
+Created in .goopspec/codebase/:
+- STACK.md
+- ARCHITECTURE.md
+- STRUCTURE.md
+- CONVENTIONS.md
+- TESTING.md
+- INTEGRATIONS.md
+- CONCERNS.md
+
+───────────────────────────────────────────────────────────────
+
+## Next Up
+
+**Initialize GoopSpec project** with brownfield context
+
+/goop-new [project-name]
+
+<sub>Will use codebase map to understand existing code</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- cat .goopspec/codebase/CONCERNS.md - Review issues first
+- cat .goopspec/codebase/ARCHITECTURE.md - Understand structure
+
+───────────────────────────────────────────────────────────────
+```
+</process>
+
+<notes>
+**When to map codebase:**
+- Joining an existing project
+- Before extending unfamiliar code
+- When inheriting a codebase
+- Before major refactoring
+
+**What to do with concerns:**
+- Review CONCERNS.md before planning
+- Address critical security issues first
+- Factor tech debt into phase planning
+- Use as context for estimates
+
+**Updating the map:**
+- Re-run `/goop-map-codebase` periodically
+- Update after major refactors
+- Keep as living documentation
+</notes>