opencode-goopspec 0.1.5 → 0.1.6

package/references/execute-process.md

@@ -0,0 +1,358 @@
+# Execution Process
+
+Detailed process for `/goop-execute` - wave-based implementation of the blueprint.
+
+## Phase 1: Gate Check
+
+**Execute BEFORE anything else:**
+
+```
+goop_status()
+goop_state({ action: "get" })        # NEVER read state.json directly
+Read(".goopspec/BLUEPRINT.md")
+```
+
+### 1.1 Check specLocked
+
+```
+IF state.specLocked != true:
+  REFUSE with:
+  
+  ## 🔮 GoopSpec · Gate Blocked
+  
+  ✗ Specification must be locked before execution.
+  
+  → Run: `/goop-specify`
+  
+  ---
+```
+
+### 1.2 Gate passed
+
+```
+## 🔮 GoopSpec · Execution
+
+✓ Spec gate passed
+
+⚡ Starting wave-based execution...
+
+---
+```
+
+---
+
+## Phase 2: Load Context
+
+```
+Read(".goopspec/SPEC.md")           # Must-haves
+Read(".goopspec/BLUEPRINT.md")      # Waves and tasks
+Read(".goopspec/CHRONICLE.md")      # Progress (if resuming)
+Read(".goopspec/PROJECT_KNOWLEDGE_BASE.md")  # Conventions
+
+memory_search({ query: "[feature] implementation patterns" })
+```
+
+Identify:
+- Current wave (from CHRONICLE or start at 1)
+- Tasks to execute
+- Dependencies between tasks
+
+---
+
+## Phase 3: Wave Execution Loop
+
+**Display wave start:**
+
+```
+## 🔮 GoopSpec · Wave [N] of [M]: [Wave Name]
+
+**Tasks:** [X] | **Execution:** [Parallel/Sequential]
+
+---
+```
+
+**For each task in wave:**
+
+### 3.1 Delegate to executor
+
+```
+task({
+  subagent_type: "goop-executor",
+  description: "Execute Task [N.M]",
+  prompt: `
+## TASK
+Wave [N], Task [M]: [Task Name]
+
+## PROJECT CONTEXT
+[From PROJECT_KNOWLEDGE_BASE.md]
+
+## SPEC REQUIREMENTS
+[Relevant must-have from SPEC.md]
+
+## TASK DETAILS
+[From BLUEPRINT.md]
+
+Intent: [intent]
+Deliverables: [list]
+Files: [paths]
+Verification: [command]
+Acceptance: [criteria]
+
+## INSTRUCTIONS
+1. Implement following existing patterns
+2. Commit atomically
+3. Return XML response envelope
+4. Include spec coverage in response
+  `
+})
+```
+
+### 3.2 Parse XML response
+
+- Extract status (COMPLETE/PARTIAL/BLOCKED)
+- Extract artifacts (files, commits)
+- Extract handoff instructions
+
+### 3.3 Update CHRONICLE.md
+
+```markdown
+### Task [N.M]: [Name]
+- Status: [Complete/Partial/Blocked]
+- Commit: [sha]
+- Files: [list]
+- Time: [timestamp]
+```
+
+### 3.4 Handle status
+
+| Status | Action |
+|--------|--------|
+| COMPLETE | Continue to next task |
+| PARTIAL | Resume with partial context |
+| BLOCKED | Check deviation rules |
+
+---
+
+## Phase 4: Deviation Handling
+
+**Apply deviation rules:**
+
+| Rule | Trigger | Action |
+|------|---------|--------|
+| Rule 1 | Bug found | Auto-fix, document |
+| Rule 2 | Missing critical | Auto-add, document |
+| Rule 3 | Blocking issue | Auto-fix, document |
+| Rule 4 | Architectural | **STOP**, ask user |
+
+**On Rule 4:**
+```
+## 🔮 GoopSpec · Decision Required
+
+⚠️ **Type:** Architectural Decision
+
+**Context:** [From executor response]
+
+**Options:**
+- **A)** [option] — [impact]
+- **B)** [option] — [impact]
+
+**Recommendation:** [If any]
+
+Which option? (A/B/other)
+
+---
+```
+
+Use `question` tool, then resume with decision.
+
+---
+
+## Phase 5: Wave Completion
+
+**At end of each wave:**
+
+### 5.1 Run wave verification
+```
+Spawn goop-verifier for wave-level checks
+```
+
+### 5.2 Update CHRONICLE.md
+```markdown
+## Wave [N]: COMPLETE
+- Tasks: [X/X]
+- Commits: [list]
+- Verification: PASSED
+- Time: [timestamp]
+```
+
+### 5.3 Save checkpoint
+```
+goop_checkpoint({ 
+  action: "save",
+  context: { wave: N, phase: "execute" }
+})
+```
+
+### 5.4 Generate HANDOFF.md
+```markdown
+# Session Handoff
+
+**Phase:** execute
+**Wave:** [N] of [M] complete
+
+## Accomplished
+- [x] Task N.1: [description]
+- [x] Task N.2: [description]
+
+## Next Session
+Run: /goop-execute
+
+## Context
+Wave [N] complete. Starting Wave [N+1] next.
+```
+
+### 5.5 Suggest new session
+```
+## 🔮 GoopSpec · Wave [N] Complete
+
+✨ Wave finished successfully
+
+| Metric | Status |
+|--------|--------|
+| Tasks | ✓ [X/X] complete |
+| Commits | [Y] |
+| Verification | ✓ PASSED |
+
+### Next
+
+**Option A:** Continue to Wave [N+1] (current session)
+**Option B:** Start new session for fresh context (Recommended)
+
+For Option B:
+1. Start a new session
+2. Run: `/goop-execute`
+
+---
+```
+
+---
+
+## Phase 6: Execution Complete
+
+**When all waves done:**
+
+```
+## 🔮 GoopSpec · Execution Complete
+
+✨ All waves finished successfully
+
+| Metric | Status |
+|--------|--------|
+| Waves | ✓ [M/M] complete |
+| Tasks | ✓ [P/P] complete |
+| Commits | [Q] |
+
+All must-haves implemented and verified.
+```
+
+### 6.1 Offer Pull Request Creation
+
+Use `question` tool:
+- header: "Pull Request"
+- question: "Execution complete. Would you like to create a pull request now?"
+- options:
+  - "Create PR" — Create a well-formatted pull request
+  - "Create draft PR" — Create as draft, finalize after acceptance
+  - "Skip for now (Recommended)" — Create PR after verification in /goop-accept
+
+**On "Create PR" or "Create draft PR":**
+
+Follow the PR creation process from git-workflow reference:
+
+1. Check branch status:
+```bash
+git branch --show-current
+git log main..HEAD --oneline
+git diff main...HEAD --stat
+```
+
+2. Generate PR title and description:
+- **Title:** `type(scope): Descriptive summary` (no GoopSpec terminology)
+- **Body:** Summary, Changes, Testing (from CHRONICLE.md), Notes
+
+3. Create PR:
+```bash
+gh pr create --title "type(scope): Title" --body "..." [--draft]
+```
+
+4. Display PR URL
+
+### 6.2 Display next steps
+
+```
+### Next Step
+
+**Verify and accept** — Final verification against spec
+
+→ `/goop-accept`
+
+---
+
+Start a new session for fresh context.
+```
+
+Update state using goop_state:
+```
+goop_state({ action: "transition", phase: "accept" })
+```
+
+---
+
+## Examples
+
+### Starting Execution
+```
+User: /goop-execute
+
+Orchestrator:
+## 🔮 GoopSpec · Execution
+
+✓ Spec gate passed
+
+## 🔮 GoopSpec · Wave 1 of 3: Foundation
+
+[Delegating Task 1.1...]
+
+goop-executor: Task 1.1 COMPLETE (commit: abc123)
+
+[Delegating Task 1.2...]
+
+goop-executor: Task 1.2 COMPLETE (commit: def456)
+
+## 🔮 GoopSpec · Wave 1 Complete
+
+**Recommend:** Start new session for Wave 2
+```
+
+### Checkpoint Reached
+```
+goop-executor: BLOCKED - Rule 4 deviation
+
+## 🔮 GoopSpec · Decision Required
+
+**Context:** Database schema change needed
+
+**Options:**
+| A | Add index | Better performance |
+| B | Skip index | Faster deployment |
+
+Which option?
+
+User: A
+
+Orchestrator: Resuming with Option A...
+```
+
+---
+
+*Execution Process v0.1.6*

package/references/git-workflow.md

@@ -0,0 +1,349 @@
+# Git Workflow
+
+Best practices for Git operations in GoopSpec agents. All commits should be professional, well-formatted, and universally understandable by any developer.
+
+## Core Principles
+
+### Universal Commit Messages
+
+**CRITICAL:** Commit messages must be understandable by anyone. Never reference:
+- GoopSpec phases, waves, or task IDs
+- Internal planning documents (SPEC.md, BLUEPRINT.md, etc.)
+- Agent names or orchestration concepts
+- Tool names or MCP terminology
+
+Write commits as if you're on a team where no one knows GoopSpec exists.
+
+### Professional Quality
+
+Commits should:
+- Be indistinguishable from expert human developers
+- Follow conventional commit format
+- Explain the "why" not just the "what"
+- Be atomic (one logical change per commit)
+
+---
+
+## Commit Message Format
+
+```
+type(scope): concise but descriptive title (max 72 chars)
+
+[2-4 sentence paragraph explaining context, motivation, and approach.
+Why was this change needed? What problem does it solve?]
+
+Changes:
+- Specific change with context
+- Another change with why it matters
+- Include file/module names when helpful
+
+[Optional: Breaking changes, migration notes, or follow-up needed]
+```
+
+### Types
+
+| Type | Use For |
+|------|---------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `refactor` | Code restructuring (no behavior change) |
+| `docs` | Documentation only |
+| `test` | Adding or updating tests |
+| `chore` | Config, deps, build tooling |
+| `style` | Formatting, whitespace (no logic change) |
+| `perf` | Performance improvements |
+
+### Scope
+
+The affected area/module. Required for non-trivial changes.
+
+Examples: `auth`, `api`, `ui`, `database`, `config`, `deps`
+
+---
+
+## Good vs Bad Examples
+
+### Title Examples
+
+**Good:**
+```
+feat(auth): Add OAuth2 login with Google and GitHub
+fix(api): Resolve race condition in concurrent requests
+refactor(ui): Extract shared button styles into component
+perf(database): Add index to users.email for faster lookups
+```
+
+**Bad:**
+```
+Update files                      # Too vague
+Fix bug                           # Says nothing
+feat: W2.T4 complete              # References internal task
+chore: Task from BLUEPRINT.md     # References planning docs
+feat(auth): Added feature         # Redundant, past tense
+```
+
+### Full Message Examples
+
+**Good commit:**
+```
+feat(users): Add avatar upload with image resizing
+
+Users can now upload profile avatars. The system accepts common image
+formats and automatically resizes them to standard dimensions (150x150
+for thumbnails, 400x400 for full size) to optimize storage and load times.
+
+Changes:
+- Add AvatarUpload component with drag-and-drop support
+- Implement server-side image processing with Sharp
+- Create avatar storage service with S3 integration
+- Add migration for avatar_url column on users table
+```
+
+**Bad commit:**
+```
+feat(users): Wave 2 Task 3 - implement avatar upload per SPEC MH-04
+
+Completed task W2.T3 from BLUEPRINT.md. This satisfies must-have MH-04
+from the specification. Moving to next task in the wave.
+
+Changes:
+- Implemented the feature as specified
+- Added required files
+- Tests pass
+```
+
+---
+
+## Single vs Multiple Commits
+
+### Use Single Commit When:
+- All changes serve one purpose
+- Changes are tightly coupled
+- Total changes are small (<100 lines or <5 files)
+
+### Use Multiple Commits When:
+- Changes include unrelated fixes/features
+- Cleanup/refactoring mixed with new functionality
+- Tests added separately from implementation
+- Documentation updated independently
+- Config changes separate from code changes
+
+### Multi-Commit Order
+
+When splitting into multiple commits, order from independent to dependent:
+
+```
+1. chore(deps): Update axios to v1.6.0
+2. fix(ui): Correct typo in welcome message
+3. feat(users): Add avatar upload with resizing
+```
+
+---
+
+## Branching
+
+### Branch Naming
+
+Format: `type/short-description`
+
+```
+feat/user-avatars
+fix/login-race-condition
+refactor/button-components
+chore/update-dependencies
+```
+
+### Creating Branches
+
+Before creating:
+1. Check existing branches: `git branch --list`
+2. Ensure name is unique and descriptive
+3. If similar exists, make more specific: `feat/auth` → `feat/auth-oauth`
+
+---
+
+## Pre-Commit Checklist
+
+Before committing, verify:
+
+- [ ] All tests pass
+- [ ] No TypeScript/linting errors
+- [ ] No console.log or debug statements
+- [ ] Commit message is specific (not generic)
+- [ ] Message explains WHY, not just WHAT
+- [ ] No internal references (phases, waves, tasks)
+- [ ] Someone unfamiliar could understand the change
+
+---
+
+## Commit Workflow
+
+### Step 1: Review Changes
+
+```bash
+git status                    # See modified files
+git diff                      # Review unstaged changes
+git diff --staged             # Review staged changes
+```
+
+### Step 2: Stage Thoughtfully
+
+Stage related changes together:
+
+```bash
+git add src/components/Avatar.tsx
+git add src/services/avatar.ts
+git add tests/avatar.test.ts
+```
+
+Or stage all if changes are cohesive:
+
+```bash
+git add -A
+```
+
+### Step 3: Commit with Quality Message
+
+```bash
+git commit -m "type(scope): title" -m "Body paragraph explaining why."
+```
+
+Or for longer messages, let the editor open:
+
+```bash
+git commit
+```
+
+### Step 4: Verify
+
+```bash
+git log -1                    # Review the commit
+git show HEAD --stat          # See files changed
+```
+
+---
+
+## Pull Request Guidelines
+
+### PR Title
+
+Same format as commits: `type(scope): Descriptive summary`
+
+### PR Description Template
+
+```markdown
+## Summary
+
+[2-4 sentences: WHAT this PR does and WHY it was needed.
+What problem does it solve? What's the approach?]
+
+## Changes
+
+- [Specific change with context]
+- [Another change with why it matters]
+- [Group related changes together]
+
+## Testing
+
+- [How was this tested?]
+- [Manual testing performed]
+- [Automated tests added/modified]
+
+## Notes
+
+[Breaking changes, migration steps, follow-up work, deployment notes]
+```
+
+---
+
+## Safety Rules
+
+### Never
+
+- Force push to main/master without explicit user request
+- Commit secrets, credentials, or .env files
+- Skip GPG signing if configured
+- Create empty commits
+- Commit with `--no-verify` (skips hooks)
+- Add AI attribution or "Generated with" footers
+
+### Always
+
+- Run tests before committing
+- Preserve GPG signing configuration
+- Check for sensitive files before staging
+- Use atomic commits (one logical change each)
+
+---
+
+## Handling Merge Conflicts
+
+### Step 1: Identify Conflicts
+
+```bash
+git status                    # Shows conflicted files
+```
+
+### Step 2: Resolve
+
+Open each conflicted file and resolve:
+- Keep their changes: accept incoming
+- Keep your changes: accept current
+- Combine both: manual merge
+
+### Step 3: Mark Resolved
+
+```bash
+git add <resolved-file>
+git commit                    # Complete the merge
+```
+
+---
+
+## Recovery Commands
+
+### Undo Last Commit (Keep Changes)
+
+```bash
+git reset --soft HEAD~1
+```
+
+### Undo Last Commit (Discard Changes)
+
+```bash
+git reset --hard HEAD~1
+```
+
+### Amend Last Commit
+
+Only if NOT pushed:
+
+```bash
+git commit --amend
+```
+
+### Stash Changes
+
+```bash
+git stash                     # Save changes
+git stash pop                 # Restore changes
+git stash list                # See stashed items
+```
+
+---
+
+## Quality Checklist for Agents
+
+Before any commit, verify:
+
+1. **Message is universal** - No GoopSpec terminology
+2. **Title is specific** - Not "Update files" or "Fix bug"
+3. **Body explains why** - Context and motivation included
+4. **Changes are atomic** - One logical unit of work
+5. **Tests pass** - Verified before committing
+6. **No debug code** - console.log removed
+7. **GPG preserved** - Don't disable signing
+
+---
+
+*Git Workflow Reference v1.0*

package/references/handoff-protocol.md

@@ -286,5 +286,5 @@ Next: Add refresh token logic to extend sessions.
 
 ---
 
-*Handoff Protocol v0.1.5*
+*Handoff Protocol v0.1.6*
 *"Fresh context, quality work."*