opencode-goopspec 0.1.2 → 0.1.4

package/references/enforcement-system.md

@@ -0,0 +1,213 @@
+# Orchestration Enforcement System
+
+GoopSpec enforces workflow rules through a layered enforcement system. This document describes how enforcement works and how to configure it.
+
+## Overview
+
+The enforcement system transforms GoopSpec from a "suggestions-based" system into an **enforced workflow** where:
+- Commands trigger actual state transitions
+- Documents are scaffolded automatically
+- Phase gates block progression until requirements are met
+- The orchestrator is forced to delegate code work
+
+## Components
+
+### 1. Phase Context Builder
+
+**Location:** `src/features/enforcement/phase-context.ts`
+
+Generates phase-specific enforcement rules for injection into system prompts.
+
+**Key Functions:**
+- `buildPhaseEnforcement(phase, state)` - Generates MUST DO / MUST NOT DO lists
+- `buildStateContext(state)` - Generates current state information
+- `buildEnforcementContext(state)` - Combines both for system prompt injection
+- `isOperationAllowed(phase, operation)` - Checks if operation is valid in phase
+
+### 2. Document Scaffolder
+
+**Location:** `src/features/enforcement/scaffolder.ts`
+
+Automatically creates phase directory structure with templated documents.
+
+**Key Functions:**
+- `scaffoldPhaseDocuments(ctx, phaseName, phase)` - Creates `.goopspec/phases/[name]/` with documents
+- `checkPhaseDocuments(ctx, phaseName, phase)` - Validates required documents exist
+- `getPhaseDir(ctx, phaseName)` - Returns phase directory path
+
+**Document Types:**
+| Type | File | Required In |
+|------|------|-------------|
+| spec | SPEC.md | plan, research, specify, execute, accept |
+| blueprint | BLUEPRINT.md | specify, execute, accept |
+| chronicle | CHRONICLE.md | plan, research, specify, execute, accept |
+| research | RESEARCH.md | research, specify |
+
+### 3. Validators
+
+**Location:** `src/features/enforcement/validators.ts`
+
+Validates operations against current workflow phase.
+
+**Key Functions:**
+- `validateWriteOperation(phase, filePath)` - Checks if file write is allowed
+- `validatePhaseTransition(ctx, from, to)` - Validates transition preconditions
+- `isImplementationFile(filePath)` - Detects code vs config files
+
+**Protected Directories:**
+- `src/`, `lib/`, `app/`, `apps/`
+- `packages/`, `server/`, `client/`
+
+## Hooks
+
+### System Transform Hook
+
+**Location:** `src/hooks/system-transform.ts`
+
+Injects enforcement context into every system prompt:
+- Current phase and state information
+- Phase-specific MUST DO / MUST NOT DO rules
+- Delegation reminders in execute phase
+- Memory context for continuity
+
+### Command Processor Hook
+
+**Location:** `src/hooks/command-processor.ts`
+
+Processes `/goop-*` slash commands:
+- Triggers state transitions (e.g., `/goop-plan` → plan phase)
+- Scaffolds phase documents automatically
+- Logs command processing to ADL
+
+**Command Mappings:**
+| Command | Target Phase |
+|---------|--------------|
+| /goop-plan | plan |
+| /goop-discuss | plan |
+| /goop-research | research |
+| /goop-specify | specify |
+| /goop-execute | execute |
+| /goop-accept | accept |
+| /goop-complete | idle |
+
+### Orchestrator Enforcement Hook
+
+**Location:** `src/hooks/orchestrator-enforcement.ts`
+
+Enforces delegation rules for the orchestrator agent:
+
+**Code Blocking:**
+- Blocks `edit`/`write` on code files for orchestrator
+- Allows planning files (`.goopspec/`, `.md`, `.json`)
+- Injects delegation guidance when blocked
+
+**Delegation Enforcement:**
+- Detects `goop_delegate` calls
+- Injects `task()` invocation reminders
+- Tracks pending delegations per session
+
+## Phase Rules
+
+### Plan Phase
+**MUST DO:**
+- Ask clarifying questions
+- Create SPEC.md with must-haves, nice-to-haves, out-of-scope
+- Get user confirmation before proceeding
+
+**MUST NOT DO:**
+- Write ANY implementation code
+- Use write/edit tools on src/ files
+- Skip requirement gathering
+
+### Research Phase
+**MUST DO:**
+- Read SPEC.md to understand requirements
+- Create RESEARCH.md with findings
+- Document trade-offs and recommendations
+
+**MUST NOT DO:**
+- Write implementation code
+- Modify source files
+
+### Specify Phase
+**MUST DO:**
+- Create BLUEPRINT.md with wave-based plan
+- Map all must-haves to specific tasks
+- Get user confirmation to lock specification
+
+**MUST NOT DO:**
+- Write implementation code
+- Proceed without locked specification
+
+### Execute Phase
+**MUST DO:**
+- DELEGATE all code work using `task()` tool
+- Track progress in CHRONICLE.md
+- Follow wave order
+- Save checkpoints at wave boundaries
+
+**MUST NOT DO:**
+- Write code directly
+- Use 'delegate' tool (use 'task' instead)
+- Skip verification steps
+
+### Accept Phase
+**MUST DO:**
+- Verify ALL must-haves from SPEC.md
+- Run all tests
+- Get explicit user acceptance
+
+**MUST NOT DO:**
+- Mark complete without verification
+- Skip user confirmation
+
+## Configuration
+
+Enforcement is enabled by default. No configuration currently required.
+
+Future configuration options (planned):
+```json
+{
+  "enforcement": {
+    "level": "strict",  // assist | warn | strict
+    "codeBlocking": true,
+    "delegationEnforcement": true
+  }
+}
+```
+
+## Troubleshooting
+
+### "Cannot write to file" errors
+The orchestrator is blocked from writing code files. Delegate to goop-executor:
+```
+task({
+  subagent_type: "goop-executor",
+  description: "Implement feature X",
+  prompt: "..."
+})
+```
+
+### Phase transition rejected
+Ensure required documents exist before transitioning:
+- `execute` requires SPEC.md
+- `accept` requires SPEC.md, BLUEPRINT.md, CHRONICLE.md
+
+### Commands not triggering state changes
+Verify the command is processed by checking ADL.md for logged entries.
+
+### Enforcement context not appearing
+Ensure memory injection is enabled in config:
+```json
+{
+  "memory": {
+    "injection": {
+      "enabled": true
+    }
+  }
+}
+```
+
+---
+
+*GoopSpec v0.1.0 - Enforcement System Documentation*

package/references/handoff-protocol.md

@@ -0,0 +1,290 @@
+# Handoff Protocol
+
+The Handoff Protocol ensures clean context transitions between sessions. Following the GSD pattern, each phase ends with full documentation enabling a fresh agent to continue with a clean 200k context window.
+
+## Core Principle
+
+```
++================================================================+
+|  CONTEXT IS PRECIOUS. FRESH CONTEXT = QUALITY WORK.             |
+|  At natural boundaries, generate HANDOFF.md and suggest         |
+|  starting a new session for clean context.                      |
++================================================================+
+```
+
+## When to Generate Handoff
+
+### Mandatory Handoff Points
+1. **Phase completion** - After plan, specify, execute, accept
+2. **Wave completion** - After each wave in execution
+3. **Checkpoint reached** - User decision needed
+4. **Context getting full** - Long session with many files read
+
+### Optional Handoff Points
+1. **Natural pause** - User stepping away
+2. **Complex task boundary** - Before major implementation
+3. **Research complete** - Before acting on findings
+
+## HANDOFF.md Structure
+
+```markdown
+# Session Handoff
+
+**Generated:** [timestamp]
+**Phase:** [current phase]
+**Session:** [session_id if available]
+
+---
+
+## Accomplished This Session
+
+### Completed
+- [x] [Task/milestone 1]
+- [x] [Task/milestone 2]
+- [x] [Task/milestone 3]
+
+### Key Outcomes
+- [Significant outcome 1]
+- [Significant outcome 2]
+
+### Decisions Made
+- **[Decision 1]**: [Choice made] - [Rationale]
+- **[Decision 2]**: [Choice made] - [Rationale]
+
+---
+
+## Current State
+
+### Workflow Position
+- **Phase:** [plan|specify|execute|accept]
+- **Spec Locked:** [yes|no]
+- **Wave:** [N of M] (if executing)
+- **Task:** [X of Y] (if executing)
+
+### Files Modified
+- `path/to/file1.ts` - [what changed]
+- `path/to/file2.ts` - [what changed]
+
+### Commits Made
+- `abc1234` - type(scope): message
+- `def5678` - type(scope): message
+
+---
+
+## Next Session Instructions
+
+### Command to Run
+```
+/goop-[command]
+```
+
+### Files to Read First
+1. `.goopspec/SPEC.md` - Requirements contract
+2. `.goopspec/BLUEPRINT.md` - Execution plan
+3. `.goopspec/CHRONICLE.md` - Progress log
+4. [Additional relevant files]
+
+### Context Summary
+[2-4 sentences of essential context the next session needs to know.
+Focus on decisions made, patterns established, and gotchas discovered.]
+
+### Immediate Next Task
+**Task:** [Exact task description]
+**Files:** `path/to/files`
+**Action:** [What needs to be done]
+**Verify:** [How to verify completion]
+
+---
+
+## Warnings & Blockers
+
+### Active Blockers
+[None | List of blockers with context]
+
+### Gotchas Discovered
+- [Pattern or issue to be aware of]
+- [Dependency or integration concern]
+
+### Pending Decisions
+[None | Decisions that need user input]
+
+---
+
+*Start a new session for fresh context.*
+*Run the command above to continue.*
+```
+
+## Handoff Generation Rules
+
+### What to Include
+- All tasks completed this session
+- Key decisions with rationale
+- Exact workflow position
+- Files modified with descriptions
+- Critical context for continuation
+- Explicit next steps
+
+### What NOT to Include
+- Full file contents (just paths)
+- Detailed implementation code
+- Speculation about future work
+- Information already in SPEC/BLUEPRINT/CHRONICLE
+
+### Context Summary Guidelines
+The context summary should be:
+- **Concise**: 2-4 sentences max
+- **Actionable**: Focus on what matters for next task
+- **Specific**: Mention actual file names, patterns, decisions
+- **Fresh**: Don't repeat what's in planning files
+
+**Good example**:
+> "Auth service implemented in src/auth/ using jose for JWT. Decided to use 24h expiry with refresh tokens stored in httpOnly cookies. Note: existing session.ts has a conflict with our middleware - need to refactor the order in next session."
+
+**Bad example**:
+> "Made good progress on auth. Some things were implemented. There might be some issues to look at."
+
+## Integration with Other Files
+
+### CHRONICLE.md Update
+Before generating HANDOFF.md:
+```markdown
+## Session [date]
+
+### Completed
+- Task 2.1: [description] (commit: abc123)
+- Task 2.2: [description] (commit: def456)
+
+### State
+- Wave 2: 2/4 tasks complete
+- Next: Task 2.3
+
+### Handoff Generated
+See: .goopspec/HANDOFF.md
+```
+
+### STATE.md Update
+Human-readable state mirror:
+```markdown
+# Current State
+
+**Phase:** execute
+**Wave:** 2 of 3
+**Task:** 3 of 4
+**Last Updated:** [timestamp]
+
+## Quick Resume
+Run `/goop-execute` to continue Wave 2.
+```
+
+### Memory Persistence
+Before handoff:
+```typescript
+memory_save({
+  type: "observation",
+  title: "Session handoff: [feature]",
+  content: "[key context for future sessions]",
+  concepts: ["handoff", "feature-name", "phase"],
+  importance: 0.7
+})
+```
+
+## Agent Responsibilities
+
+### Orchestrator
+- Detect handoff points
+- Generate HANDOFF.md
+- Update CHRONICLE.md
+- Suggest new session to user
+
+### Subagents
+- Return `suggest_new_session: true` in XML when:
+  - Complex task completed
+  - Significant context accumulated
+  - Natural pause point reached
+- Include handoff-ready summary in response
+
+## User Communication
+
+### At Handoff Point
+```markdown
+## Session Checkpoint
+
+I've completed [summary of work] and saved the state.
+
+**Current position:** Phase [X], Wave [N], Task [M]
+
+### To Continue
+1. Start a **new session** for fresh context
+2. Run: `/goop-execute`
+
+The new session will have:
+- Full 200k context window
+- All state from HANDOFF.md
+- Clear next steps
+
+### Files Saved
+- `.goopspec/HANDOFF.md` - Session handoff
+- `.goopspec/CHRONICLE.md` - Progress log
+- `.goopspec/STATE.md` - Current state
+
+Ready to continue in new session!
+```
+
+### Quick Resume (Same Session)
+If user wants to continue without new session:
+```markdown
+Continuing in current session.
+
+**Note:** Context is at [X]% - quality may degrade with complex tasks.
+Consider starting fresh if encountering issues.
+
+Proceeding with Task [N]...
+```
+
+## Anti-Patterns
+
+### Bad: No Context in Handoff
+```markdown
+## Next Session
+Run /goop-execute
+```
+**Problem**: Next session has no context about what happened.
+
+### Bad: Too Much Detail
+```markdown
+## Context Summary
+[500 lines of implementation details]
+```
+**Problem**: Defeats the purpose of clean handoff.
+
+### Bad: Missing Next Steps
+```markdown
+## Completed
+- Task 1
+- Task 2
+```
+**Problem**: Next session doesn't know what to do.
+
+### Good: Clean and Actionable
+```markdown
+## Next Session Instructions
+
+### Command to Run
+/goop-execute
+
+### Context Summary
+Completed auth service with JWT. Using jose library, 24h expiry. 
+Middleware in src/auth/middleware.ts protects routes. 
+Next: Add refresh token logic to extend sessions.
+
+### Immediate Next Task
+**Task:** W2.T3 - Implement refresh tokens
+**Files:** src/auth/refresh.ts, src/auth/service.ts
+**Action:** Add refresh endpoint and token rotation
+**Verify:** bun test src/auth/
+```
+
+---
+
+*Handoff Protocol v0.1.4*
+*"Fresh context, quality work."*

package/references/interactive-questioning.md

@@ -0,0 +1,122 @@
+# Interactive Questioning Protocol
+
+**GoopSpec Voice:** Direct, Purposeful, Memory-First.
+
+We use interactive questioning to trade ambiguity for clarity without halting momentum. Every question must earn its right to interrupt the user.
+
+## Core Philosophy
+
+1.  **Memory First:** Never ask what you already know.
+2.  **Gate-Oriented:** Questions should drive towards a Decision Gate (Contract, Checkpoint, Acceptance).
+3.  **Skill-Backed:** Use skills to frame questions intelligently, not just to gather data.
+4.  **Progressive:** Start high-level; drill down only when necessary.
+
+---
+
+## 1. Memory-Aware Questioning
+
+Before formulating a question, you **MUST** search memory.
+
+### The Protocol
+1.  **Search:** `memory_search({ query: "[topic] preference" })`
+2.  **Evaluate:** Do I have a high-confidence answer (Importance > 7)?
+3.  **Action:**
+    *   **High Confidence:** Use it. Inform user: "Using saved preference for X."
+    *   **Medium Confidence:** Confirm. "I recall you prefer X. Still true?"
+    *   **No Data:** Ask. Then **SAVE** the answer.
+
+### Examples
+
+**❌ Bad (Amnesic):**
+> "What database should we use?"
+*(User has answered this 5 times before)*
+
+**✅ Good (Memory-Aware):**
+> ⬢ **Memory Recall:** You prefer **PostgreSQL** for new services.
+> Proceeding with Postgres? [Y/n]
+
+---
+
+## 2. Skill-Aware Questioning
+
+Don't just ask "What do you want?". Use loaded skills to provide *informed options*.
+
+### The Protocol
+1.  **Consult Skill:** Use `research` or `security` or `architecture` skills to analyze the situation.
+2.  **Frame Options:** Present choices based on expert analysis.
+3.  **Ask:** specific, constrained questions.
+
+### Examples
+
+**❌ Bad (Generic):**
+> "How should we handle authentication?"
+
+**✅ Good (Skill-Backed - Security):**
+> ⬢ **Security Skill Analysis:**
+> For this stack, I recommend **OAuth2 with PKCE** for these reasons:
+> 1. Matches your security baseline.
+> 2. Best support for mobile clients.
+>
+> **Decision:** Implement OAuth2? [Y/n] or "Explain alternatives"
+
+---
+
+## 3. Decision Gates
+
+Use formal Gates for high-impact questions. Stop the world.
+
+### Contract Gate (Planning Phase)
+*Must resolve scope before work begins.*
+
+> **Question:** "Are these MUST-HAVES correct and complete?"
+> **Trigger:** `/goop-specify`
+> **Action:** Lock SPEC.md upon confirmation.
+
+### Checkpoint Gate (Execution Phase)
+*Stop for architectural forks in the road.*
+
+> **Question:** "I found two valid patterns. A is faster, B is more scalable. Which path?"
+> **Trigger:** Rule 4 (Architectural Decision).
+> **Action:** Wait for user selection.
+
+### Acceptance Gate (Completion Phase)
+*Verify completion against the contract.*
+
+> **Question:** "I have verified requirements A, B, and C. Ready to accept?"
+> **Trigger:** `/goop-accept`
+> **Action:** Archive task and update memory.
+
+---
+
+## 4. Progressive Disclosure
+
+Don't wall-of-text the user. Reveal complexity in layers.
+
+### Level 1: The "Happy Path" Proposal
+State the most likely path and ask for confirmation.
+> "I plan to use **React Hook Form** for this form. Proceed?"
+
+### Level 2: The Fork
+If rejected or ambiguous, offer distinct high-level options.
+> "Okay. Options:
+> 1. **React Hook Form** (Standard, performant)
+> 2. **Formik** (Legacy compatibility)
+> 3. **Raw State** (Simple forms only)"
+
+### Level 3: The Deep Dive
+Only if requested, show full tradeoffs.
+> "Here is the detailed comparison of bundle size, re-render performance, and API surface..."
+
+---
+
+## Checklist: Before You Ask
+
+- [ ] **Did I search memory?** (Don't be amnesic)
+- [ ] **Is this a "One-Way Door" decision?** (If yes, use a Gate)
+- [ ] **Can I propose a default instead?** (Bias for action)
+- [ ] **Is the question binary or multiple choice?** (Reduce cognitive load)
+- [ ] **Am I ready to save the answer?** (Build the knowledge base)
+
+---
+
+**Remember:** Every question is a context switch. Make it count.

package/references/model-profiles.md

@@ -14,7 +14,7 @@ Model profiles control which model each GoopSpec agent uses. This enables optima
 | goop-orchestrator | anthropic/claude-opus-4-5 | Complex orchestration, task delegation, context management |
 | goop-planner | anthropic/claude-opus-4-5 | Best for complex architecture decisions, goal decomposition, reasoning-heavy planning |
 | goop-researcher | openai/gpt-5.2 | Best for research, technology evaluation, knowledge synthesis |
-| goop-tester | opencode/kimi-k2.5-free | Cost-effective for test writing, quality assurance, coverage thinking |
+| goop-tester | kimi-for-coding/k2p5 | Cost-effective for test writing, quality assurance, coverage thinking |
 | goop-verifier | openai/gpt-5.2-codex | Best for code verification, security analysis, catching subtle bugs |
 | goop-writer | google/antigravity-gemini-3-pro-high | Documentation, structured writing, comprehensive coverage |
 | memory-distiller | anthropic/claude-haiku-3-5 | Fast, lightweight distillation of events into structured memories |