opencode-goopspec 0.1.4 → 0.1.6

package/references/response-format.md

@@ -384,7 +384,7 @@ See `references/xml-response-schema.md` for the complete specification.
 **Minimal XML envelope:**
 
 ```xml
-<goop_report version="0.1.4">
+<goop_report version="0.1.6">
   <status>COMPLETE</status>
   <agent>goop-[type]</agent>
   <summary>Brief summary</summary>
@@ -415,4 +415,4 @@ See `references/xml-response-schema.md` for the complete specification.
 
 ---
 
-*Response Format v0.1.4*
+*Response Format v0.1.6*

package/references/specify-process.md

@@ -0,0 +1,251 @@
+# Specification Lock Process
+
+Detailed process for `/goop-specify` - locking the specification contract.
+
+## Phase 1: Gate Check
+
+**Execute BEFORE anything else:**
+
+```
+goop_status()
+Read(".goopspec/SPEC.md")
+Read(".goopspec/BLUEPRINT.md")
+```
+
+### 1.1 Check documents exist
+
+```
+IF .goopspec/SPEC.md does not exist:
+  REFUSE with:
+  
+  ## 🔮 GoopSpec · Gate Blocked
+  
+  ✗ No specification found.
+  
+  → Run: `/goop-plan`
+  
+  ---
+```
+
+### 1.2 Check traceability
+
+```
+IF traceability matrix shows < 100%:
+  REFUSE with:
+  
+  ## 🔮 GoopSpec · Traceability Incomplete
+  
+  ✗ Not all must-haves have mapped tasks.
+  
+  → Update BLUEPRINT.md or re-run `/goop-plan`
+  
+  ---
+```
+
+---
+
+## Phase 2: Present Contract
+
+**Display the contract for confirmation:**
+
+```
+## 🔮 GoopSpec · Contract Gate
+
+📜 Review and confirm the specification
+
+### SPECIFICATION: [Name]
+
+#### Must-Haves (The Contract)
+
+| ID | Requirement | Covered By |
+|----|-------------|------------|
+| MH1 | [Title] | Wave X, Tasks Y |
+| MH2 | [Title] | Wave X, Tasks Y |
+
+#### Out of Scope
+
+- [Item 1]
+- [Item 2]
+
+#### Execution Plan
+
+| Wave | Focus | Tasks |
+|------|-------|-------|
+| 1 | [Name] | [N] |
+| 2 | [Name] | [M] |
+
+✓ Traceability: 100%
+
+---
+
+⚠️ **Action Required:**
+- Type **"confirm"** to lock the specification
+- Type **"amend"** to modify requirements
+- Type **"cancel"** to return to planning
+```
+
+---
+
+## Phase 3: Handle Response
+
+**On "confirm":**
+
+1. Lock the spec using goop_state:
+```
+goop_state({ action: "lock-spec" })
+```
+
+2. Update SPEC.md:
+```markdown
+**Status:** Locked
+**Locked At:** [timestamp]
+```
+
+3. Save to memory:
+```
+memory_decision({
+  decision: "Spec locked for [feature]",
+  reasoning: "User confirmed requirements after review",
+  impact: "high"
+})
+```
+
+4. Generate HANDOFF.md:
+```markdown
+# Session Handoff
+
+**Phase:** specify
+
+## Accomplished
+- Spec locked with [N] must-haves
+- Traceability verified at 100%
+
+## Next Session
+Run: /goop-execute
+
+## Context
+Specification locked. Ready for execution.
+```
+
+5. Display completion:
+```
+## 🔮 GoopSpec · Specification Locked
+
+🔒 The spec is now a binding contract
+
+| Status | Value |
+|--------|-------|
+| Locked | ✓ Yes |
+| Must-Haves | [N] |
+| Waves | [M] |
+| Tasks | [P] |
+
+Changes now require `/goop-amend` with impact analysis.
+
+### Next Step
+
+**Begin execution** — Implement the blueprint
+
+→ `/goop-execute`
+
+---
+
+Start a **new session** for fresh context, then run the command.
+```
+
+**On "amend":**
+
+```
+## 🔮 GoopSpec · Amendment Mode
+
+What would you like to change?
+
+1. Add a must-have
+2. Remove a must-have
+3. Modify acceptance criteria
+4. Change out of scope
+5. Cancel
+
+---
+```
+
+Use `question` tool to get choice, then process amendment.
+
+**On "cancel":**
+
+```
+Specification not locked. Returning to planning.
+Run `/goop-plan` to modify or `/goop-discuss` to restart discovery.
+```
+
+---
+
+## Amendment Protocol (After Lock)
+
+Once locked, changes require formal amendment:
+
+1. **Propose change:** User describes modification
+2. **Impact analysis:** Orchestrator assesses affected tasks
+3. **Blueprint update:** Modify BLUEPRINT.md if needed
+4. **Re-confirm:** User confirms amended spec
+5. **Log amendment:** Add to SPEC.md amendment history
+
+```markdown
+## Amendment History
+
+| Version | Date | Change | Impact | Approved |
+|---------|------|--------|--------|----------|
+| 1.1 | [date] | Added MH3 | +1 task | User |
+```
+
+---
+
+## Examples
+
+### Successful Lock
+```
+User: /goop-specify
+
+Orchestrator:
+## 🔮 GoopSpec · Contract Gate
+
+### SPECIFICATION: Dark Mode Toggle
+
+#### Must-Haves
+| ID | Requirement | Covered By |
+|----|-------------|------------|
+| MH1 | Toggle UI | W1.T1 |
+| MH2 | Theme switch | W1.T2, W2.T1 |
+| MH3 | Persist preference | W2.T2 |
+
+#### Out of Scope
+- Multiple themes (beyond light/dark)
+- Per-component theming
+
+✓ Traceability: 100%
+
+Type "confirm" to lock.
+
+User: confirm
+
+Orchestrator:
+## 🔮 GoopSpec · Specification Locked
+
+→ Next: `/goop-execute`
+```
+
+### Gate Blocked
+```
+User: /goop-specify
+
+Orchestrator:
+## 🔮 GoopSpec · Gate Blocked
+
+✗ No specification found.
+
+→ Run: `/goop-plan`
+```
+
+---
+
+*Specification Lock Process v0.1.6*

package/references/status-process.md

@@ -0,0 +1,253 @@
+# Status Display Process
+
+Detailed process for `/goop-status` - showing current project state.
+
+## Data Sources
+
+| Source | Information |
+|--------|-------------|
+| `goop_state` | Phase, locks, timestamps |
+| `REQUIREMENTS.md` | Interview status |
+| `SPEC.md` | Must-haves, lock status |
+| `BLUEPRINT.md` | Waves, tasks, traceability |
+| `CHRONICLE.md` | Progress, decisions, blockers |
+| `HANDOFF.md` | Last session context |
+
+---
+
+## Status Dashboard Template
+
+```
+## 🔮 GoopSpec · Status
+
+### Project State
+
+| Attribute | Value |
+|-----------|-------|
+| Phase | [current phase] |
+| Interview Complete | [Yes/No] |
+| Spec Locked | [Yes/No] |
+| Wave | [N of M] |
+| Task | [X of Y] |
+
+### Gate Status
+
+| Gate | Status | Requirement |
+|------|--------|-------------|
+| Discovery | [PASSED/BLOCKED] | interview_complete |
+| Spec | [PASSED/BLOCKED] | spec_locked |
+| Execution | [PASSED/BLOCKED] | all_tasks_done |
+| Acceptance | [PASSED/BLOCKED] | verification_passed |
+
+### Progress
+
+[Progress bar and completion percentage]
+
+#### Completed
+- [x] [Item 1]
+- [x] [Item 2]
+
+#### In Progress
+- [ ] [Current item] <- **Current**
+
+#### Remaining
+- [ ] [Item 3]
+- [ ] [Item 4]
+
+### Active Blockers
+
+[None | List of blockers]
+
+### Pending Decisions
+
+[None | List of decisions awaiting user input]
+
+### Recent Activity
+
+| Time | Action | Agent |
+|------|--------|-------|
+| [time] | [action] | [agent] |
+
+---
+
+### Suggested Next Command
+
+Based on current state: `/goop-[command]`
+
+[Brief explanation]
+
+---
+```
+
+---
+
+## Gate Logic
+
+### Discovery Gate
+```
+IF REQUIREMENTS.md exists AND interview_complete == true:
+  PASSED
+ELSE:
+  BLOCKED - Run /goop-discuss
+```
+
+### Spec Gate
+```
+IF SPEC.md exists AND spec_locked == true:
+  PASSED
+ELSE:
+  BLOCKED - Run /goop-specify
+```
+
+### Execution Gate
+```
+IF CHRONICLE shows all waves complete:
+  PASSED
+ELSE:
+  BLOCKED - Continue /goop-execute
+```
+
+### Acceptance Gate
+```
+IF verification_passed == true AND user_accepted == true:
+  PASSED
+ELSE:
+  BLOCKED - Run /goop-accept
+```
+
+---
+
+## Command Suggestions
+
+| State | Suggested Command |
+|-------|-------------------|
+| No project | `/goop-discuss` to start discovery |
+| Interview incomplete | `/goop-discuss` to complete interview |
+| Interview complete, no spec | `/goop-plan` to create blueprint |
+| Spec draft, not locked | `/goop-specify` to lock |
+| Spec locked, not executing | `/goop-execute` to start |
+| Executing, tasks remaining | `/goop-execute` to continue |
+| Executing, all done | `/goop-accept` to verify |
+| Verified, not accepted | `/goop-accept` to accept |
+| Accepted | `/goop-complete` to archive |
+
+---
+
+## Verbose Mode
+
+With `--verbose`:
+
+```
+### Full Task History
+
+| Wave | Task | Status | Commit | Time |
+|------|------|--------|--------|------|
+| 1 | 1.1 | Complete | abc123 | 10m |
+| 1 | 1.2 | Complete | def456 | 15m |
+| 2 | 2.1 | In Progress | - | - |
+
+### Memory Stats
+
+- Total memories: [N]
+- Decisions: [M]
+- Observations: [P]
+- Recent: [list]
+
+### Recent Deviations
+
+| Rule | Description | Resolution |
+|------|-------------|------------|
+| [N] | [What happened] | [How resolved] |
+
+### Checkpoint History
+
+| ID | Phase | Wave | Created |
+|----|-------|------|---------|
+| [id] | [phase] | [wave] | [time] |
+```
+
+---
+
+## Examples
+
+### Fresh Project
+```
+User: /goop-status
+
+## 🔮 GoopSpec · Status
+
+### Project State
+
+| Attribute | Value |
+|-----------|-------|
+| Phase | idle |
+| Interview Complete | No |
+| Spec Locked | No |
+
+### Gate Status
+
+| Gate | Status |
+|------|--------|
+| Discovery | BLOCKED |
+| Spec | BLOCKED |
+| Execution | BLOCKED |
+| Acceptance | BLOCKED |
+
+### Suggested Next Command
+
+`/goop-discuss` - Start discovery interview
+
+No project documents found. Begin with discovery.
+```
+
+### Mid-Execution
+```
+User: /goop-status
+
+## 🔮 GoopSpec · Status
+
+### Project State
+
+| Attribute | Value |
+|-----------|-------|
+| Phase | execute |
+| Interview Complete | Yes |
+| Spec Locked | Yes |
+| Wave | 2 of 3 |
+| Task | 3 of 4 |
+
+### Gate Status
+
+| Gate | Status |
+|------|--------|
+| Discovery | PASSED |
+| Spec | PASSED |
+| Execution | In Progress |
+| Acceptance | Pending |
+
+### Progress
+
+[################____] 75%
+
+#### Completed
+- [x] Wave 1: Foundation (4/4 tasks)
+- [x] Wave 2.1: Define types
+- [x] Wave 2.2: Implement handler
+
+#### In Progress
+- [ ] Wave 2.3: Add validation <- **Current**
+
+#### Remaining
+- [ ] Wave 2.4: Add tests
+- [ ] Wave 3: Integration (3 tasks)
+
+### Suggested Next Command
+
+`/goop-execute` - Continue Wave 2
+
+2 tasks remaining in Wave 2, then Wave 3.
+```
+
+---
+
+*Status Process v0.1.6*

package/references/subagent-protocol.md

@@ -189,7 +189,7 @@ All subagent responses MUST end with an XML envelope. See `references/xml-respon
 **Basic structure:**
 
 ```xml
-<goop_report version="0.1.4">
+<goop_report version="0.1.6">
   <status>COMPLETE|PARTIAL|BLOCKED|CHECKPOINT</status>
   <agent>goop-[type]</agent>
   <task_name>Task description</task_name>
@@ -440,4 +440,4 @@ Every subagent execution:
 
 ---
 
-*Subagent Protocol v0.1.4*
+*Subagent Protocol v0.1.6*

package/references/team-coordination.md

@@ -0,0 +1,183 @@
+# Team Coordination Reference
+
+This reference documents how GoopSpec agents coordinate when running in parallel. It explains the registry, per-agent file patterns, merge workflow, conflict handling, and recommended practices.
+
+## Overview
+
+The team coordination system prevents parallel agents from overwriting shared files by:
+
+- Registering active agents and their claimed files in a central registry.
+- Redirecting shared outputs to per-agent files using a stable naming pattern.
+- Allowing the orchestrator to merge per-agent outputs into canonical files.
+- Detecting conflicts early and suggesting safe alternatives.
+
+Key artifacts live under `.goopspec/team/`.
+
+## Registry Structure and Operations
+
+**Registry location:** `.goopspec/team/registry.json` (with `.goopspec/team/registry.lock` for atomic writes).
+
+**Registry schema:**
+
+```json
+{
+  "version": 1,
+  "agents": {
+    "agent-id": {
+      "id": "agent-id",
+      "type": "goop-executor",
+      "task": "Implement registry",
+      "claimedFiles": ["src/features/team/registry.ts"],
+      "parentId": "parent-agent-id",
+      "startedAt": 1700000000000,
+      "ttl": 1800000
+    }
+  }
+}
+```
+
+**Fields:**
+
+- `id`: unique agent identifier.
+- `type`: agent type (e.g., `goop-researcher`).
+- `task`: short task description.
+- `claimedFiles`: files this agent intends to write.
+- `parentId`: parent agent identifier if delegated.
+- `startedAt`: registration time (ms epoch).
+- `ttl`: optional time-to-live for cleanup (ms).
+
+**Core operations:**
+
+- `getRegistry()` reads the registry state.
+- `registerAgent(registration)` registers an agent atomically.
+- `deregisterAgent(agentId)` removes the agent entry.
+- `getActiveAgents()` returns all active agents.
+- `getAgentsByType(type)` filters by agent type.
+- `isFileClaimed(filePath)` checks if any agent has claimed a file.
+
+**Atomic behavior:** registry updates use a lock file and atomic write to prevent race conditions.
+
+## Per-Agent File Patterns
+
+When multiple agents produce shared artifacts, each writes to its own file using:
+
+```
+{basename}-{shortId}.{ext}
+```
+
+Example: `RESEARCH.md` becomes `RESEARCH-a1b2c3.md` for agent `a1b2c3`.
+
+**Short ID rules:**
+
+- Derived from the agent ID with non-alphanumeric characters removed.
+- Length is clamped to 6-8 characters (default 7).
+- If a short ID is empty after normalization, the basename remains unchanged.
+
+**Helpers:**
+
+- `generateAgentFilePath(basePath, agentId, shortIdLength?)`
+- `extractAgentId(agentFilePath)`
+- `findAgentFiles(basePath, pattern?)`
+- `getCanonicalPath(agentFilePath)`
+
+### Per-Agent File Patterns by Agent Type
+
+Per-agent naming works for any shared output file. Common base files by agent type:
+
+| Agent Type | Typical Base File | Per-Agent Example |
+| --- | --- | --- |
+| `goop-researcher` | `RESEARCH.md` | `RESEARCH-res001.md` |
+| `goop-explorer` | `RESEARCH.md` | `RESEARCH-exp123.md` |
+| `goop-planner` | `BLUEPRINT.md` | `BLUEPRINT-plan42.md` |
+| `goop-verifier` | `CHRONICLE.md` | `CHRONICLE-ver789.md` |
+| `goop-writer` | `RESEARCH.md` or `SPEC.md` | `SPEC-wrt555.md` |
+| `goop-executor` | Shared docs when needed | `CHRONICLE-exe321.md` |
+| `goop-debugger` | `RESEARCH.md` | `RESEARCH-bug007.md` |
+
+These examples are illustrative; the pattern applies to any base file (e.g., `SPEC.md`, `BLUEPRINT.md`, `CHRONICLE.md`, `RESEARCH.md`, `HANDOFF.md`).
+
+## Merge Workflow
+
+After parallel work, the orchestrator merges per-agent outputs into a canonical file.
+
+**Merge steps:**
+
+1. Locate all per-agent files matching the canonical base path.
+2. Read registry to map short IDs to full agent IDs and tasks.
+3. Render a header for each section, then concatenate sections with separators.
+4. Write the merged content to the canonical output path.
+5. Optionally remove per-agent files after merge.
+
+**Header template:**
+
+```
+## Agent {{agentId}}
+
+Task: {{task}}
+```
+
+The merge utility replaces `{{agentId}}` and `{{task}}`, then joins sections using `---` separators.
+
+## Conflict Detection and Resolution
+
+Before writing a file, check for conflicts:
+
+1. Call `checkFileConflict(filePath, requestingAgentId)`.
+2. If `hasConflict` is `true`, read `warningMessage` and `suggestedPath`.
+3. Write to the suggested per-agent path instead of the claimed file.
+4. Notify the orchestrator to merge once all agents complete.
+
+If the file is claimed by the same agent, the conflict check allows the write.
+
+## Examples
+
+### Generate a Per-Agent File Path
+
+```ts
+import { generateAgentFilePath } from "../src/features/team/file-patterns.js";
+
+const agentFile = generateAgentFilePath("RESEARCH.md", "res-001");
+// => "RESEARCH-res001.md"
+```
+
+### Merge Per-Agent Outputs
+
+```ts
+import { mergeAgentOutputs } from "../src/features/team/merge.js";
+
+await mergeAgentOutputs({
+  basePath: ".goopspec/RESEARCH.md",
+  cleanup: false,
+});
+```
+
+### Conflict Warning (Example)
+
+```
+WARNING: File Conflict Detected
+
+The file you're trying to write is claimed by another agent:
+- Agent: exec-001 (goop-executor)
+- Task: Modify index
+
+Suggested action: Write to your per-agent file instead:
+→ RESEARCH-exec002.md
+```
+
+## Best Practices
+
+- Register early and claim files you intend to modify.
+- Use per-agent files for shared artifacts (research, plans, summaries).
+- Avoid writing directly to canonical files during parallel work.
+- Keep per-agent outputs focused and well-structured to ease merging.
+- Clean up per-agent files after a successful merge when possible.
+- If you must touch a claimed file, coordinate through the orchestrator.
+
+## Related Files
+
+- `src/features/team/types.ts` - Registry types
+- `src/features/team/registry.ts` - Registry operations
+- `src/features/team/file-patterns.ts` - File pattern helpers
+- `src/features/team/merge.ts` - Merge utilities
+- `src/features/team/conflict.ts` - Conflict detection
+- `src/features/team/cleanup.ts` - Cleanup utilities