opencode-goopspec 0.1.3 → 0.1.4

package/references/context-injection.md

@@ -0,0 +1,307 @@
+# Context Injection
+
+Context Injection ensures all subagents have access to project-level knowledge without the orchestrator manually including it in every delegation prompt.
+
+## Core Principle
+
+```
++================================================================+
+|  SUBAGENTS NEED CONTEXT TO MAKE GOOD DECISIONS.                 |
+|  Project knowledge flows automatically to every agent.          |
+|  No agent should hallucinate stack choices or conventions.      |
++================================================================+
+```
+
+## The Knowledge Base
+
+### PROJECT_KNOWLEDGE_BASE.md
+
+A living document maintained in `.goopspec/PROJECT_KNOWLEDGE_BASE.md` containing:
+
+```markdown
+# Project Knowledge Base
+
+**Last Updated:** [timestamp]
+**Updated By:** [agent/user]
+
+---
+
+## Project Identity
+
+**Name:** [Project name]
+**Type:** [Web app / CLI / Library / API / etc.]
+**Stage:** [New / Active / Maintenance]
+
+---
+
+## Stack (Non-Negotiable)
+
+### Runtime & Language
+- **Runtime:** [Node.js / Bun / Deno / Browser]
+- **Language:** [TypeScript / JavaScript]
+- **Version:** [Specific versions]
+
+### Frameworks & Libraries
+- **Framework:** [Express / Next.js / React / None]
+- **ORM:** [Prisma / Drizzle / None]
+- **Testing:** [Vitest / Jest / Bun test]
+- **Key Libraries:** [List with versions]
+
+### Infrastructure
+- **Database:** [PostgreSQL / SQLite / None]
+- **Cache:** [Redis / None]
+- **Deployment:** [Vercel / AWS / Docker]
+
+---
+
+## Conventions
+
+### File Naming
+- **Files:** [kebab-case / camelCase]
+- **Components:** [PascalCase]
+- **Tests:** [*.test.ts / *.spec.ts]
+
+### Code Style
+- **Functions:** [Arrow / Named]
+- **Exports:** [Named / Default]
+- **Types:** [Interfaces / Types]
+
+### Commits
+- **Format:** [type(scope): description]
+- **Types:** [feat, fix, refactor, test, docs, chore]
+
+---
+
+## Architecture Decisions
+
+### [Decision Category]
+- **Decision:** [What was decided]
+- **Rationale:** [Why]
+- **Date:** [When]
+
+---
+
+## Patterns in Use
+
+### [Pattern Name]
+- **Where:** [Files/areas]
+- **How:** [Brief description]
+- **Example:** `path/to/example.ts`
+
+---
+
+## Known Gotchas
+
+- [Gotcha 1]: [What to watch out for]
+- [Gotcha 2]: [What to watch out for]
+
+---
+
+## Integration Points
+
+- **Auth:** [Where auth is handled]
+- **API:** [API patterns/locations]
+- **Database:** [How data is accessed]
+
+---
+
+*Updated automatically by memory-distiller agent.*
+*Manual updates welcome for accuracy.*
+```
+
+## Injection Points
+
+### When Subagents Load Context
+
+Every subagent's `<first_steps>` section includes:
+
+```markdown
+**Step N: Load Project Knowledge**
+```
+Read(".goopspec/PROJECT_KNOWLEDGE_BASE.md")  # If exists
+```
+
+This happens AFTER loading state but BEFORE starting work.
+```
+
+### Orchestrator Delegation
+
+When orchestrator delegates via `task()`:
+
+```typescript
+task({
+  subagent_type: "goop-executor",
+  description: "Implement feature X",
+  prompt: `
+    ## PROJECT CONTEXT
+    [Auto-injected from PROJECT_KNOWLEDGE_BASE.md]
+    - Stack: Bun, TypeScript, Express
+    - Conventions: kebab-case files, named exports
+    - Testing: bun test
+    
+    ## TASK
+    [Specific task details]
+    ...
+  `
+})
+```
+
+## Automatic Updates
+
+### memory-distiller Responsibility
+
+The memory-distiller agent updates PROJECT_KNOWLEDGE_BASE.md:
+
+1. **After major decisions**: New architectural choices
+2. **After pattern discovery**: New patterns found in codebase
+3. **After gotcha discovery**: Issues to remember
+4. **At session end**: Consolidate session learnings
+
+### Update Protocol
+
+```markdown
+1. Read current PROJECT_KNOWLEDGE_BASE.md
+2. Merge new knowledge:
+   - Add new decisions
+   - Update patterns
+   - Add gotchas
+3. Remove outdated information
+4. Write updated file
+5. Log update to CHRONICLE.md
+```
+
+## What to Include
+
+### Always Include
+- Stack choices (runtime, framework, libraries)
+- Naming conventions
+- Commit format
+- Major architectural decisions
+- Known gotchas
+
+### Include When Relevant
+- Integration patterns
+- Error handling conventions
+- Testing patterns
+- Deployment configuration
+
+### Never Include
+- Sensitive data (API keys, passwords)
+- Temporary workarounds
+- Personal preferences
+- Speculation
+
+## What Subagents Should Do
+
+### With Injected Context
+
+1. **Follow stack choices**: Don't suggest alternative libraries
+2. **Match conventions**: Use the same naming, export style
+3. **Reference patterns**: Follow established patterns
+4. **Avoid gotchas**: Don't repeat known mistakes
+
+### When Context is Missing
+
+1. **Explore codebase**: Look for existing patterns
+2. **Ask orchestrator**: If critical decision needed
+3. **Document discovery**: Add to PROJECT_KNOWLEDGE_BASE via memory
+
+## Example: Context-Aware Executor
+
+### Without Context Injection (Bad)
+```
+Task: Add user validation
+
+Executor thinks: "I'll use Zod for validation..."
+Reality: Project uses Yup everywhere
+Result: Inconsistent validation libraries
+```
+
+### With Context Injection (Good)
+```
+Task: Add user validation
+
+PROJECT_KNOWLEDGE_BASE says:
+- Validation: Yup (see src/validation/schemas.ts)
+
+Executor thinks: "Project uses Yup, I'll follow the pattern in schemas.ts"
+Result: Consistent validation approach
+```
+
+## Integration with Memory
+
+### memory_search Enhancement
+
+Before starting work, agents should:
+
+```typescript
+// 1. Check PROJECT_KNOWLEDGE_BASE.md
+Read(".goopspec/PROJECT_KNOWLEDGE_BASE.md")
+
+// 2. Search memory for task-specific context
+memory_search({ 
+  query: "[task] patterns conventions",
+  concepts: ["patterns", "conventions", "decisions"]
+})
+```
+
+### memory_save for Future Context
+
+When discovering patterns:
+
+```typescript
+memory_save({
+  type: "observation",
+  title: "Pattern: [pattern name]",
+  content: "Found [pattern] used in [files]. Should be added to PROJECT_KNOWLEDGE_BASE.",
+  concepts: ["pattern", "convention", "knowledge-base"],
+  importance: 0.7
+})
+```
+
+## Bootstrap Process
+
+### For New Projects
+
+When starting a new GoopSpec project:
+
+1. **goop-explorer** maps codebase
+2. **Orchestrator** creates initial PROJECT_KNOWLEDGE_BASE.md from:
+   - package.json analysis
+   - Existing config files
+   - Code pattern detection
+3. **User** reviews and corrects
+4. **memory-distiller** maintains going forward
+
+### For Existing GoopSpec Projects
+
+1. Load existing PROJECT_KNOWLEDGE_BASE.md
+2. memory-distiller updates with session discoveries
+3. Accumulates institutional knowledge over time
+
+## Anti-Patterns
+
+### Bad: Ignoring Context
+```
+PROJECT_KNOWLEDGE_BASE says: Use named exports
+Agent does: export default function...
+```
+**Fix**: Always read and follow PROJECT_KNOWLEDGE_BASE.
+
+### Bad: Outdated Context
+```
+PROJECT_KNOWLEDGE_BASE says: Using Express
+Reality: Migrated to Fastify 3 months ago
+```
+**Fix**: memory-distiller should detect and update.
+
+### Bad: Over-Injection
+```
+Delegating to agent with 5000 tokens of context
+```
+**Fix**: Inject only relevant sections for the task.
+
+---
+
+*Context Injection Protocol v0.1.4*
+*"Shared knowledge, consistent decisions."*

package/references/discovery-interview.md

@@ -0,0 +1,278 @@
+# Discovery Interview
+
+The Discovery Interview is a mandatory gate before planning. It ensures requirements are "nailed down" before any work begins.
+
+## Core Principle
+
+```
++================================================================+
+|  NO PLANNING WITHOUT DISCOVERY.                                 |
+|  The interview ensures we build the RIGHT thing.                |
+|  Skipping discovery leads to scope creep and rework.            |
++================================================================+
+```
+
+## When to Run
+
+- **Required before**: `/goop-plan`
+- **Triggered by**: `/goop-discuss`
+- **Output**: `.goopspec/REQUIREMENTS.md`
+- **State update**: `interview_complete: true` in state.json
+
+## The Six Questions
+
+Every discovery interview MUST answer these questions:
+
+### 1. Vision (The What)
+```
+What are you trying to build?
+- What problem does this solve?
+- Who is this for?
+- What does success look like?
+```
+
+**Good answer**: "A JWT-based authentication system that allows users to securely log in, maintains sessions, and protects API routes. Success = users can sign up, log in, and access protected resources."
+
+**Bad answer**: "Auth stuff"
+
+### 2. Must-Haves (The Contract)
+```
+What are the non-negotiable requirements?
+- What MUST be delivered for this to be complete?
+- What are the acceptance criteria?
+```
+
+**Good answer**:
+- User registration with email/password
+- Login returns JWT token
+- Protected routes reject invalid tokens
+- Tokens expire after 24 hours
+- Password reset via email
+
+**Bad answer**: "It should work"
+
+### 3. Constraints (The Boundaries)
+```
+What are the technical and practical constraints?
+- What stack/frameworks are we using?
+- What are the performance requirements?
+- What's the timeline?
+- What existing code must we integrate with?
+```
+
+**Good answer**: "Must use existing Express.js backend, PostgreSQL for storage, jose library for JWT (already in package.json), must not break existing session middleware."
+
+**Bad answer**: "None"
+
+### 4. Out of Scope (The Guardrails)
+```
+What are we explicitly NOT building?
+- What features are deferred to later?
+- What approaches are we avoiding?
+```
+
+**Good answer**:
+- OAuth/social login (future phase)
+- Multi-factor authentication (future phase)
+- Rate limiting (handled by API gateway)
+- User profile management (separate feature)
+
+**Bad answer**: "Everything else I guess"
+
+### 5. Assumptions (The Baseline)
+```
+What are we assuming to be true?
+- What existing functionality are we relying on?
+- What decisions have already been made?
+```
+
+**Good answer**:
+- Database is already set up with users table
+- Email service is available via existing utility
+- Frontend will handle token storage (not our concern)
+- HTTPS is handled at infrastructure level
+
+**Bad answer**: "Standard stuff"
+
+### 6. Risks (The Unknowns)
+```
+What could go wrong?
+- What are we uncertain about?
+- What might change?
+- What dependencies could block us?
+```
+
+**Good answer**:
+- Risk: Password hashing library may have breaking changes
+  - Mitigation: Pin exact version, test migration path
+- Risk: Token refresh logic may conflict with existing session
+  - Mitigation: Research existing session code first
+- Risk: Email service rate limits may affect password reset
+  - Mitigation: Add retry logic with backoff
+
+**Bad answer**: "None, it'll be fine"
+
+## Interview Flow
+
+### Step 1: Open-Ended Discovery
+Ask broad questions to understand intent:
+- "What are you trying to accomplish?"
+- "Why is this needed now?"
+- "Who will use this?"
+
+### Step 2: Structured Questions
+Work through the six questions, prompting for specifics:
+- "What happens if [edge case]?"
+- "How should [error scenario] be handled?"
+- "What's the expected behavior when [boundary condition]?"
+
+### Step 3: Summarize and Confirm
+Present back:
+- Vision statement
+- Must-haves list
+- Constraints list
+- Out of scope list
+- Assumptions list
+- Risks with mitigations
+
+### Step 4: Lock Discovery
+- Generate REQUIREMENTS.md
+- Update state.json with `interview_complete: true`
+- Inform user: "Discovery complete. Run `/goop-plan` to create blueprint."
+
+## REQUIREMENTS.md Template
+
+```markdown
+# REQUIREMENTS: [Feature Name]
+
+**Generated:** [date]
+**Status:** Locked
+
+---
+
+## Vision
+
+[Vision statement - what and why]
+
+---
+
+## Must-Haves
+
+These are non-negotiable. The feature is incomplete without ALL of these:
+
+- [ ] [Requirement 1]
+- [ ] [Requirement 2]
+- [ ] [Requirement 3]
+
+---
+
+## Constraints
+
+### Technical
+- [Constraint 1]
+- [Constraint 2]
+
+### Practical
+- [Timeline, budget, resources]
+
+---
+
+## Out of Scope
+
+Explicitly excluded from this work:
+
+- [Item 1] - [reason/future phase]
+- [Item 2] - [reason/future phase]
+
+---
+
+## Assumptions
+
+We are assuming:
+
+- [Assumption 1]
+- [Assumption 2]
+
+---
+
+## Risks & Mitigations
+
+| Risk | Impact | Likelihood | Mitigation |
+|------|--------|------------|------------|
+| [Risk 1] | [H/M/L] | [H/M/L] | [Plan] |
+| [Risk 2] | [H/M/L] | [H/M/L] | [Plan] |
+
+---
+
+*Discovery interview completed. Ready for /goop-plan.*
+```
+
+## Enforcement
+
+### Pre-Plan Gate
+When `/goop-plan` is invoked:
+
+```
+1. Check state.json for interview_complete
+2. If false or missing:
+   - REFUSE to proceed
+   - Display: "Discovery interview required. Run /goop-discuss first."
+3. If true:
+   - Load REQUIREMENTS.md
+   - Proceed with planning
+```
+
+### Validation Rules
+Interview is NOT complete if:
+- Vision is vague (< 2 sentences)
+- Must-haves is empty
+- Out of scope is empty (everything has scope limits)
+- No risks identified (there are always risks)
+
+### Skip Conditions
+Discovery MAY be skipped only for:
+- `/goop-quick` small tasks (single file, < 30 min work)
+- Bug fixes with clear reproduction steps
+- Documentation-only changes
+
+## Anti-Patterns
+
+### Bad: Rushing Through
+```
+Q: What are you building?
+A: "Just some auth stuff"
+                           <- NOT ENOUGH
+```
+
+### Bad: No Scope Limits
+```
+Q: What's out of scope?
+A: "Nothing, we'll figure it out"
+                           <- SCOPE CREEP INCOMING
+```
+
+### Bad: No Risks
+```
+Q: What could go wrong?
+A: "Nothing, it's straightforward"
+                           <- FAMOUS LAST WORDS
+```
+
+### Good: Specific and Bounded
+```
+Q: What are you building?
+A: "JWT auth with login/logout, 24h token expiry, refresh tokens, 
+    protected route middleware. Uses existing users table."
+
+Q: What's out of scope?
+A: "OAuth (phase 2), MFA (phase 3), rate limiting (infra handles it)"
+
+Q: Risks?
+A: "Token refresh may conflict with existing session - need to check 
+    session.ts first. Also email service has rate limits."
+```
+
+---
+
+*Discovery Interview Protocol v0.1.4*
+*"Nail the spec before you write the code."*