murmur8 4.3.3 → 4.4.0

package/.blueprint/agents/AGENT_BA_CASS.md

@@ -20,7 +20,7 @@ Primary focus:
 - User stories and acceptance criteria
 - Maintaining a shared mental model across policy, delivery, and engineering
 
-Cass operates **upstream of implementation**, ensuring that what gets built is **explicit, testable, and intentional** before code is written.
+Cass operates **upstream of implementation**, ensuring that what gets built is **explicit, testable, and intentional** before code is written. Cass creates atomic pieces of work for Nigel, and subsequently Codey, to work from. 
 
 ---
 
@@ -116,11 +116,12 @@ For each feature or user touchpoint you receive:
 ### Step 3: Write the user story and ACs
 
 1. Use the template below.
-2. Ensure every AC is:
+2. Ensure every story is a small, encapsulated piece of work for Nigel and Codey. You may have to combine multiple stories to create a feature. 
+3. Ensure every AC is:
    - Deterministic
    - Observable via the UI or session
    - Unambiguous
-3. Make routing explicit for:
+4. Make routing explicit for:
    - Previous link
    - Continue button
    - Cancel link
@@ -228,12 +229,3 @@ You have done your job well when:
 - the human can look at the Markdown specs and say:
   > "Yes — this is exactly what we mean."
 
----
-
-## Values
-
-Read and apply the team values from: `.blueprint/agents/TEAM_MANIFESTO.md`
-
-## Guardrails
-
-Read and apply the shared guardrails from: `.blueprint/agents/GUARDRAILS.md`

package/.blueprint/agents/AGENT_DEVELOPER_CODEY.md

@@ -143,6 +143,7 @@ Before you write code, read the project's technology stack from `.claude/stack-c
 3. Plan small, incremental steps:
    - Implement one slice of behaviour at a time
    - Keep diffs readable and localised where possible
+   - Keep steps small enough to fit within the token limit
 
 ---
 
@@ -297,12 +298,3 @@ When you receive a new story or feature, you can structure your work/output like
 
 By following this guide, Codey and Nigel can work together in a tight loop: Nigel defines and codifies the behaviour, you implement it and keep the system healthy, and the human provides final oversight and QA.
 
----
-
-## Values
-
-Read and apply the team values from: `.blueprint/agents/TEAM_MANIFESTO.md`
-
-## Guardrails
-
-Read and apply the shared guardrails from: `.blueprint/agents/GUARDRAILS.md`

package/.blueprint/agents/AGENT_SPECIFICATION_ALEX.md

@@ -202,12 +202,3 @@ He ensures that what gets built is:
 - coherent over time,
 - and traceable back to a clearly articulated system design — even as that design evolves.
 
----
-
-## Values
-
-Read and apply the team values from: `.blueprint/agents/TEAM_MANIFESTO.md`
-
-## Guardrails
-
-Read and apply the shared guardrails from: `.blueprint/agents/GUARDRAILS.md`

package/.blueprint/agents/AGENT_TESTER_NIGEL.md

@@ -148,12 +148,3 @@ When you receive a new story or feature, you can structure your response like th
 - Traceability Table
 - Open Questions & Risks
 
----
-
-## Values
-
-Read and apply the team values from: `.blueprint/agents/TEAM_MANIFESTO.md`
-
-## Guardrails
-
-Read and apply the shared guardrails from: `.blueprint/agents/GUARDRAILS.md`

package/.blueprint/agents/GUARDRAILS.md

@@ -80,4 +80,4 @@ Do not use:
 
 ---
 
-*Last updated: v3.4.0*
+*Last updated: v4.4.0*

package/.blueprint/features/BACKLOG.md

@@ -0,0 +1,91 @@
+# Feature Backlog
+
+## Definitions
+
+| Priority | Meaning |
+|----------|---------|
+| P0 | Critical — blocker |
+| P1 | High — do soon |
+| P2 | Medium — planned |
+| P3 | Low — future |
+
+| Effort | Meaning |
+|--------|---------|
+| S | Small — <1 hour |
+| M | Medium — 1-3 hours |
+| L | Large — 3-8 hours |
+| XL | Extra Large — 1+ days |
+
+| Status | Meaning |
+|--------|---------|
+| ⏳ | Ready to implement |
+| 🚧 | In progress |
+| ❓ | Needs clarification |
+
+---
+
+## Backlog
+
+| Status | P | E | Slug | Description |
+|--------|---|---|------|-------------|
+| ❓ | P1 | M | murm-subagent | Use Task tool sub-agents instead of spawning CLI processes |
+| ⏳ | P2 | M | agent-timeouts | Configurable timeouts per agent stage |
+| ⏳ | P2 | M | rollback | Revert a feature's commits |
+| ⏳ | P2 | M | agent-overrides | Per-project agent customization |
+| ⏳ | P2 | M | resume-from-stage | Resume pipeline from specific stage |
+| ⏳ | P3 | M | dry-run-mode | Validate inputs without running agents |
+| ⏳ | P3 | M | feature-dependencies | Define execution order for related features |
+| ⏳ | P3 | L | webhook-notifications | Slack/email on completion |
+| ⏳ | P3 | XL | mcp-integration | Expose murmur8 as MCP tools |
+| ⏳ | P3 | XL | mcp-repos-server | Cross-repo context for distributed monoliths |
+| ⏳ | P3 | S | cli-doctor | Diagnose CLI setup issues |
+| ⏳ | P3 | M | cross-cli-insights | Track which CLI used per run |
+| ⏳ | P3 | S | skill-lint | Validate skill YAML frontmatter |
+| ⏳ | P3 | M | aider-adapter | Support for Aider CLI |
+| ⏳ | P3 | M | cursor-adapter | Support for Cursor Composer |
+| ⏳ | P3 | L | docey-agent | Fifth agent to update docs after implementation |
+| ⏳ | P3 | M | backlog-tooling | CLI commands for backlog management |
+| ⏳ | P3 | L | skill-modularize | Split SKILL.md into composable sections |
+
+---
+
+## Details
+
+### murm-subagent
+
+Murmuration currently spawns separate CLI processes. This doesn't work inside an existing Claude Code session. Should use Task tool sub-agents instead for parallel features.
+
+### agent-timeouts
+
+Configurable timeout per stage (default: 5 min). Support `--timeout=10m` flag. Graceful termination with status recording.
+
+### rollback
+
+`murmur8 rollback <feature-slug>` to revert commits. Uses git history to find commits by feature. Supports `--dry-run`.
+
+### agent-overrides
+
+Per-project agent customization via `.blueprint/agents/overrides/AGENT_*.md`. Override content appended to base specs.
+
+### resume-from-stage
+
+More granular than queue-based resume. `--resume-from=nigel` to skip earlier stages. Validates artifacts exist first.
+
+### docey-agent
+
+Fifth agent to update README/CLAUDE.md after Codey implements. Identifies user-facing changes and updates docs automatically.
+
+### mcp-repos-server
+
+MCP server for cross-repository context in distributed architectures. See FEATURE_IDEAS.md for full specification.
+
+### backlog-tooling
+
+CLI commands: `npx murmur8 backlog`, `backlog add`, `backlog next`, `backlog murm P1`.
+
+---
+
+## Notes
+
+- Items removed automatically when pipeline completes successfully
+- Run with: `/implement-feature "slug"` or `npx murmur8 murm slug-a slug-b`

package/.blueprint/prompts/TEMPLATE.md

@@ -49,11 +49,11 @@ Start with: `You are {Name}, the {Role} Agent.`
 
 Include 5-7 rules. Focus on critical constraints only. Do NOT duplicate information already in the task or outputs sections. Avoid redundant or repetitive rules.
 
-### 6. Full Spec Reference (required)
+### 6. Completion (required)
 
 ```markdown
-## Reference
-For detailed guidance, see: .blueprint/agents/AGENT_{NAME}.md
+## Completion
+Brief summary: {what to report when done} (5 bullets max).
 ```
 
 ## Guidelines
@@ -62,4 +62,6 @@ For detailed guidance, see: .blueprint/agents/AGENT_{NAME}.md
 - Be concise: every line should add value
 - No boilerplate: skip sections that would be empty
 - Task-specific: include only what this invocation needs
-- Reference full spec: agents can read detailed guidance if needed
+- Self-contained: do NOT reference external docs (agent specs, guardrails, manifesto)
+- Inline the 2-3 critical rules from guardrails directly into the Rules section
+- Always include: "Label assumptions explicitly" and "If unclear, escalate"

package/.blueprint/prompts/alex-runtime.md

@@ -25,7 +25,6 @@ Include these sections (skip if not applicable):
 
 ## Rules
 
-- Follow the shared constraints in `.blueprint/agents/GUARDRAILS.md` (source restrictions, confidentiality, citations)
 - Write file incrementally, section by section if large
 - Reference system spec by path, do not repeat its content
 - Keep Change Log to 1-2 entries maximum
@@ -33,6 +32,9 @@ Include these sections (skip if not applicable):
 - Ensure feature aligns with system boundaries
 - Make inferred interpretations explicit
 - Propose breaking changes only with clear justification
+- Label assumptions explicitly: `ASSUMPTION: [statement]`
+- Use only project sources (specs, code, .business_context/) — no external references
+- Summarise business context rather than reproducing verbatim
 
 ## Output Format
 
@@ -43,7 +45,3 @@ Include these sections (skip if not applicable):
 ## Completion
 
 Brief summary (5 bullets max): intent, key behaviours, scope, story themes, tensions.
-
-## Reference
-
-For detailed guidance, see: .blueprint/agents/AGENT_SPECIFICATION_ALEX.md

package/.blueprint/prompts/cass-runtime.md

@@ -6,8 +6,8 @@ Create user stories with acceptance criteria from the feature specification. Sto
 
 ## Inputs (read these files)
 
+- Handoff Summary: {FEAT_DIR}/handoff-alex.md
 - Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md
-- System Spec: .blueprint/system_specification/SYSTEM_SPEC.md
 
 ## Outputs (write these files)
 
@@ -21,14 +21,16 @@ Each story file must include:
 
 ## Rules
 
-- Follow the shared constraints in `.blueprint/agents/GUARDRAILS.md` (source restrictions, confidentiality, citations)
 - Write ONE story file at a time, then move to next
 - Keep each story focused with 5-7 acceptance criteria maximum
 - Split large stories into multiple files
 - Make routing explicit (Previous, Continue, conditional paths)
 - Reference feature spec by path for shared context
 - Do not guess policy or legal detail without flagging assumptions
-- Avoid implicit behaviour - all routes must be explicit
+- Avoid implicit behaviour — all routes must be explicit
+- Label assumptions explicitly: `ASSUMPTION: [statement]`
+- Use only project sources (specs, code, .business_context/) — no external references
+- If unclear, escalate to the human — do not guess silently
 
 ## Output Format
 
@@ -40,7 +42,3 @@ Use consistent Markdown structure:
 ## Completion
 
 Brief summary: story count, filenames, behaviours covered (5 bullets max).
-
-## Reference
-
-For detailed guidance, see: .blueprint/agents/AGENT_BA_CASS.md

package/.blueprint/prompts/codey-implement-runtime.md

@@ -26,7 +26,6 @@ Implement the feature according to the plan. Work incrementally, making tests pa
 
 ## Rules
 
-- Follow the shared constraints in `.blueprint/agents/GUARDRAILS.md` (source restrictions, confidentiality, citations)
 - Write ONE source file at a time
 - Run tests after each file write
 - Keep functions small (under 30 lines)
@@ -34,6 +33,8 @@ Implement the feature according to the plan. Work incrementally, making tests pa
 - Do NOT commit changes
 - Do NOT modify test assertions unless they contain bugs
 - Prefer editing existing files over creating new ones
+- Label assumptions explicitly: `ASSUMPTION: [statement]`
+- If tests pass but behaviour feels wrong, stop and flag to the human
 
 ## Implementation Principles
 
@@ -41,12 +42,7 @@ Implement the feature according to the plan. Work incrementally, making tests pa
 - Match existing patterns in the codebase
 - Validate inputs defensively
 - Handle errors gracefully
-- If tests pass but behaviour feels wrong or forced, consult the failure-mode rituals in `.blueprint/ways_of_working/DEVELOPMENT_RITUAL.md`
 
 ## Completion
 
 Brief summary: files changed (list), test status (X/Y passing), blockers if any.
-
-## Reference
-
-For detailed guidance, see: .blueprint/agents/AGENT_DEVELOPER_CODEY.md

package/.blueprint/prompts/codey-plan-runtime.md

@@ -6,8 +6,7 @@ Create an implementation plan for the feature. Do NOT implement yet - planning o
 
 ## Inputs (read these files)
 
-- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md
-- Stories: {FEAT_DIR}/story-*.md
+- Handoff Summary: {FEAT_DIR}/handoff-nigel.md
 - Test Spec: {TEST_DIR}/test-spec.md
 - Tests: {TEST_FILE}
 
@@ -15,33 +14,34 @@ Create an implementation plan for the feature. Do NOT implement yet - planning o
 
 Write implementation plan to: {FEAT_DIR}/IMPLEMENTATION_PLAN.md
 
-Plan structure (aim for under 80 lines total):
-- Summary (2-3 sentences)
-- Files to Create/Modify (table: path | action | purpose)
-- Implementation Steps (numbered, max 10 steps)
-- Risks/Questions (bullet list, only if non-obvious)
+Plan format (aim for under 60 lines):
+
+```markdown
+## Summary
+(2-3 sentences)
+
+## Steps
+1. [path/to/file.ext] CREATE|MODIFY — purpose | Tests: T-X.Y, T-X.Z
+2. [path/to/file.ext] CREATE|MODIFY — purpose | Tests: T-X.Y
+...
+
+## Risks
+- (only if non-obvious, otherwise omit)
+```
+
+**CRITICAL:** Each step MUST be one line: `N. [file] ACTION — desc | Tests: IDs`
 
 ## Rules
 
-- Follow the shared constraints in `.blueprint/agents/GUARDRAILS.md` (source restrictions, confidentiality, citations)
 - Do NOT write implementation code in this phase
-- Keep plan concise and actionable
+- One line per step, max 10 steps
 - Order steps to make tests pass incrementally
-- Identify which tests each step addresses
+- Each step targets a single file and specific test IDs
 - Prefer editing existing files over creating new ones
-- Keep functions small (under 30 lines)
 - Flag dependencies between steps
-
-## Planning Principles
-
-- Work against tests as the primary contract
-- Separate concerns: routes, controllers, helpers
-- Plan for incremental verification after each step
+- Label assumptions explicitly: `ASSUMPTION: [statement]`
+- If unclear, escalate to the human — do not guess silently
 
 ## Completion
 
 Brief summary: files planned, step count, identified risks.
-
-## Reference
-
-For detailed guidance, see: .blueprint/agents/AGENT_DEVELOPER_CODEY.md

package/.blueprint/prompts/nigel-runtime.md

@@ -6,8 +6,8 @@ Create tests from user stories and acceptance criteria. Tests must expose ambigu
 
 ## Inputs (read these files)
 
+- Handoff Summary: {FEAT_DIR}/handoff-cass.md
 - Stories: {FEAT_DIR}/story-*.md
-- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md
 
 ## Outputs (write these files IN ORDER)
 
@@ -23,7 +23,6 @@ Step 2: Write {TEST_FILE} containing:
 
 ## Rules
 
-- Follow the shared constraints in `.blueprint/agents/GUARDRAILS.md` (source restrictions, confidentiality, citations)
 - Write test-spec.md FIRST, then write test file
 - Keep test-spec.md under 100 lines using table format
 - Tests should be self-documenting with minimal comments
@@ -31,6 +30,9 @@ Step 2: Write {TEST_FILE} containing:
 - Make failure states meaningful with expected error messages
 - Do not over-prescribe implementation details
 - Focus on externally observable behaviour
+- Label assumptions explicitly: `ASSUMPTION: [statement]`
+- If a feature requires more than 8 test cases, split across two files: `feature_{slug}.test.js` and `feature_{slug}-edge.test.js`
+- If unclear, escalate to the human — do not guess silently
 
 ## Test Design Principles
 
@@ -41,7 +43,3 @@ Step 2: Write {TEST_FILE} containing:
 ## Completion
 
 Brief summary: test count, AC coverage %, assumptions (5 bullets max).
-
-## Reference
-
-For detailed guidance, see: .blueprint/agents/AGENT_TESTER_NIGEL.md

package/.blueprint/prompts/skill-error-recovery.md

@@ -0,0 +1,86 @@
+# Error Handling & Recovery
+
+Load this file when a pipeline stage fails or on resume from queue.
+
+---
+
+## Error Handling with Smart Retry
+
+**Modules:** `src/retry.js`, `src/feedback.js`, `src/insights.js`
+
+After each agent spawn, if the Task tool returns an error or output validation fails:
+
+### 1. Analyze Failure Context
+
+- Check feedback chain for clues (e.g., Cass flagged "unclear-scope")
+- Check history for patterns: `node bin/cli.js insights --failures --json`
+- If stage has >20% failure rate, suggest alternative strategy
+
+### 2. Get Retry Strategy Recommendation
+
+**Available strategies:**
+| Strategy | Effect |
+|----------|--------|
+| `retry` | Simple retry with same prompt |
+| `simplify-prompt` | Reduce scope: "Focus only on core happy path" |
+| `add-context` | Include more output from previous stages |
+| `reduce-stories` | Ask for fewer, more focused stories |
+| `simplify-tests` | Ask for fewer, essential tests only |
+| `incremental` | Implement one test at a time |
+
+### 3. Ask User with Recommendation
+
+```
+## Stage Failed: {stage}
+
+Feedback context: {relevant feedback issues}
+History: This stage fails {rate}% of the time
+Recommended strategy: {strategy}
+
+Options:
+1. Retry with "{strategy}" strategy (recommended)
+2. Retry with simple retry
+3. Skip this stage (warning: missing artifacts)
+4. Abort pipeline
+```
+
+### 4. Apply Strategy and Retry
+
+Modify the agent prompt with additional context based on chosen strategy.
+
+### 5. Record Failure in History
+
+```javascript
+historyEntry.stages[stage] = {
+  status: "failed",
+  failedAt: "...",
+  attempts: N,
+  lastStrategy: "{strategy}",
+  feedbackContext: ["{issues}"]
+};
+```
+
+---
+
+## Queue Structure
+
+Location: `.claude/implement-queue.json`
+
+```json
+{
+  "lastUpdated": "ISO timestamp",
+  "current": { "slug": "...", "stage": "...", "startedAt": "..." },
+  "alexQueue": [],
+  "cassQueue": [],
+  "nigelQueue": [],
+  "codeyQueue": [],
+  "completed": [{ "slug": "...", "testCount": N, "commitHash": "..." }],
+  "failed": [{ "slug": "...", "stage": "...", "reason": "...", "attemptCount": N }]
+}
+```
+
+---
+
+## Recovery
+
+Run `/implement-feature` again — reads queue and resumes from `current.stage`.

package/.blueprint/prompts/skill-murm-mode.md

@@ -0,0 +1,143 @@
+# Murmuration Mode (Steps M0-M8)
+
+Load this file when multiple slugs are detected in `/implement-feature` arguments.
+
+---
+
+## Step M0: Multi-Feature Detection
+
+**Trigger:** More than one slug provided in arguments.
+
+Parse all slugs from arguments:
+```
+/implement-feature feat-a feat-b feat-c --no-commit
+→ slugs = ["feat-a", "feat-b", "feat-c"]
+→ flags = { noCommit: true }
+```
+
+**Routing:**
+- If `slugs.length > 1`: Enter murmuration mode (Steps M1-M8)
+- If `slugs.length === 1`: Continue to Step 1 (single-feature mode)
+- If `--sequential` flag: Run features one at a time without worktrees
+
+---
+
+## Step M1: Multi-Feature Pre-flight Validation
+
+For EACH slug, verify:
+1. Feature spec exists at `.blueprint/features/feature_{slug}/FEATURE_SPEC.md`
+2. Spec has required sections (Intent, Scope, Actors)
+
+**On any failure:**
+- Show which features are not ready
+- Ask: "Continue with ready features only?" or "Abort"
+
+---
+
+## Step M2: Conflict Detection
+
+Scan implementation plans (if they exist) for file overlap:
+
+```bash
+grep -h "src/\|lib/\|bin/" .blueprint/features/feature_*/IMPLEMENTATION_PLAN.md
+```
+
+**On conflict:** Ask user to confirm or adjust feature list.
+
+---
+
+## Step M3: Create Worktrees
+
+```bash
+git status --porcelain
+git worktree add .claude/worktrees/feat-{slug} -b feature/{slug}
+```
+
+---
+
+## Step M4: Spawn Parallel Feature Pipelines
+
+**CRITICAL:** Use multiple Task tool calls IN THE SAME MESSAGE to run concurrently.
+
+### Task Prompt Template (for each slug):
+
+```
+You are running the implement-feature pipeline for "{slug}".
+
+## Working Directory
+All file operations must use this worktree: .claude/worktrees/feat-{slug}
+
+## Task
+Run the complete feature pipeline in the worktree:
+
+1. Read Feature Spec: .claude/worktrees/feat-{slug}/.blueprint/features/feature_{slug}/FEATURE_SPEC.md
+2. Classify Feature (technical → skip step 3)
+3. Cass (if user-facing) — Write story-*.md + handoff-cass.md
+4. Nigel — Write test-spec.md + test file + handoff-nigel.md
+5. Codey Plan — Write IMPLEMENTATION_PLAN.md
+6. Codey Implement — Write code, iterate until tests pass
+
+## Rules
+- Work ONLY within .claude/worktrees/feat-{slug}
+- Do NOT commit changes (will be merged later)
+- Run tests from within the worktree directory
+
+## Completion
+PIPELINE_RESULT: {"slug": "{slug}", "status": "success|failed", "tests": "X/Y passing", "files": [...], "error": "if failed, why"}
+```
+
+---
+
+## Step M5: Collect Results
+
+Wait for ALL sub-agents to complete. Parse each PIPELINE_RESULT.
+
+---
+
+## Step M5.5: Diff Preview & Commit Worktree Changes
+
+For each successful pipeline (unless `--no-diff-preview`):
+- Show diff, user approves/aborts per worktree
+- Commit approved worktrees:
+
+```bash
+cd /absolute/path/to/.claude/worktrees/feat-{slug}
+git add -A
+git commit -m "feat({slug}): {summary}
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+Return to main repo before merging.
+
+---
+
+## Step M6: Merge Successful Features
+
+```bash
+git checkout main
+git merge feature/{slug} --no-ff -m "feat({slug}): Add {slug} feature
+
+Co-Authored-By: Claude <noreply@anthropic.com>"
+```
+
+**On merge conflict:** Record conflict, preserve worktree, continue with others.
+
+After all merges, remove merged features from `{BACKLOG}` (if it exists).
+
+---
+
+## Step M7: Report Summary
+
+Report: landed features, conflicts, failed pipelines, next steps.
+
+---
+
+## Step M8: Cleanup Worktrees
+
+```bash
+git worktree remove .claude/worktrees/feat-{slug} --force
+git branch -d feature/{slug}
+```
+
+Preserve worktrees for failed pipelines and merge conflicts.