murmur8 4.1.1 → 4.3.0

package/.blueprint/features/feature_murm-subagent/SKILL_CHANGES.md

@@ -0,0 +1,345 @@
+# SKILL.md Changes for Multi-Feature Support
+
+This document outlines the changes needed to support parallel feature execution via Task sub-agents.
+
+---
+
+## 1. Update Invocation Section (replace lines 28-39)
+
+```markdown
+## Invocation
+
+```bash
+# Single feature (existing)
+/implement-feature                                    # Interactive slug prompt
+/implement-feature "user-auth"                        # New feature
+/implement-feature "user-auth" --interactive          # Force interactive spec creation
+/implement-feature "user-auth" --pause-after=alex|cass|nigel|codey-plan
+/implement-feature "user-auth" --no-commit
+/implement-feature "user-auth" --no-feedback
+/implement-feature "user-auth" --no-validate
+/implement-feature "user-auth" --no-history
+
+# Multiple features — parallel execution (NEW)
+/implement-feature feat-a feat-b feat-c              # Run 3 features in parallel
+/implement-feature feat-a feat-b --max-concurrency=2 # Limit parallelism
+/implement-feature feat-a feat-b --sequential        # Run one at a time (no worktrees)
+```
+```
+
+---
+
+## 2. Add Multi-Feature Paths (insert after line 27)
+
+```markdown
+## Multi-Feature Paths (Murmuration Mode)
+
+| Var | Path |
+|-----|------|
+| `{WORKTREE_DIR}` | `.claude/worktrees` |
+| `{WORKTREE_slug}` | `{WORKTREE_DIR}/feat-{slug}` |
+| `{MURM_QUEUE}` | `.claude/murm-queue.json` |
+| `{MURM_LOCK}` | `.claude/murm.lock` |
+```
+
+---
+
+## 3. Add Multi-Feature Pipeline Overview (insert after line 65)
+
+```markdown
+## Multi-Feature Pipeline Overview
+
+When multiple slugs are provided, the pipeline uses worktree isolation and parallel Task sub-agents:
+
+```
+/implement-feature slug-a slug-b slug-c
+       │
+       ▼
+┌─────────────────────────────────────────────────────┐
+│ M0. Detect multi-feature mode                       │
+│ M1. Pre-flight validation for ALL features          │
+│ M2. Check for file overlap conflicts                │
+│ M3. Create git worktrees (one per feature)          │
+└─────────────────────────────────────────────────────┘
+       │
+       ▼
+┌─────────────────────────────────────────────────────┐
+│ M4. Spawn PARALLEL Task sub-agents                  │
+│                                                     │
+│   Task(slug-a)  ─┐                                  │
+│   Task(slug-b)  ─┼─► Run concurrently               │
+│   Task(slug-c)  ─┘                                  │
+│                                                     │
+│   Each Task runs full pipeline in its worktree:     │
+│   Alex → [Cass] → Nigel → Codey                     │
+└─────────────────────────────────────────────────────┘
+       │
+       ▼
+┌─────────────────────────────────────────────────────┐
+│ M5. Collect results as sub-agents complete          │
+│ M6. Merge successful features to main               │
+│ M7. Report conflicts/failures                       │
+│ M8. Cleanup worktrees                               │
+└─────────────────────────────────────────────────────┘
+```
+```
+
+---
+
+## 4. Add Step M0-M3: Multi-Feature Setup (new section after Step 0)
+
+```markdown
+---
+
+## 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 }
+```
+
+If `slugs.length > 1`: Enter murmuration mode (Steps M1-M8)
+If `slugs.length === 1`: Continue to Step 1 (single-feature mode)
+
+---
+
+## 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)
+
+**Display validation table:**
+```
+Pre-flight Validation
+=====================
+
+✓ feat-a: Spec complete, 3 stories
+✓ feat-b: Spec complete, 2 stories
+✗ feat-c: Missing FEATURE_SPEC.md
+```
+
+**On any failure:**
+- Show which features are not ready
+- Suggest: `/implement-feature "feat-c" --pause-after=alex` to create spec
+- Ask: "Continue with ready features only?" or "Abort"
+
+---
+
+## Step M2: Conflict Detection
+
+Scan implementation plans (if they exist) for file overlap:
+
+```bash
+# For each feature with IMPLEMENTATION_PLAN.md, extract "Files to Create/Modify"
+grep -h "src/\|lib/\|bin/" .blueprint/features/feature_*/IMPLEMENTATION_PLAN.md
+```
+
+**Display if conflicts found:**
+```
+Conflict Analysis
+=================
+
+⚠ File overlap detected:
+  • src/utils.js: feat-a, feat-b both modify
+
+Recommendation: Run feat-a and feat-b sequentially, or resolve manually.
+```
+
+**On conflict:** Ask user to confirm or adjust feature list.
+
+---
+
+## Step M3: Create Worktrees
+
+For each validated slug, create an isolated git worktree:
+
+```bash
+# Ensure clean working tree
+git status --porcelain
+
+# Create worktrees
+git worktree add .claude/worktrees/feat-{slug-a} -b feature/{slug-a}
+git worktree add .claude/worktrees/feat-{slug-b} -b feature/{slug-b}
+git worktree add .claude/worktrees/feat-{slug-c} -b feature/{slug-c}
+```
+
+**Announce:**
+```
+Creating worktrees...
+  ✓ .claude/worktrees/feat-a → branch feature/feat-a
+  ✓ .claude/worktrees/feat-b → branch feature/feat-b
+  ✓ .claude/worktrees/feat-c → branch feature/feat-c
+```
+```
+
+---
+
+## 5. Add Step M4: Parallel Pipeline Execution (the key change)
+
+```markdown
+---
+
+## Step M4: Spawn Parallel Feature Pipelines
+
+**CRITICAL:** Use multiple Task tool calls IN THE SAME MESSAGE to run concurrently.
+
+For each feature, spawn a Task sub-agent that runs the COMPLETE pipeline in its worktree.
+
+**Spawn all Task sub-agents in parallel:**
+
+### Task for {slug-a}:
+Use the Task tool with `subagent_type="general-purpose"`:
+
+```
+You are running the implement-feature pipeline for "{slug-a}".
+
+## Working Directory
+All file operations must be relative to: .claude/worktrees/feat-{slug-a}
+
+## Task
+Run the complete feature pipeline:
+
+1. **Alex** — Read feature spec, create/verify handoff summary
+   - Input: .claude/worktrees/feat-{slug-a}/.blueprint/features/feature_{slug-a}/FEATURE_SPEC.md
+   - Output: handoff-alex.md (if missing)
+
+2. **Classify** — Determine if technical or user-facing
+   - Technical (refactoring, optimization, infra): Skip to Nigel
+   - User-facing: Continue to Cass
+
+3. **Cass** (if user-facing) — Write user stories
+   - Output: story-*.md files, handoff-cass.md
+
+4. **Nigel** — Create tests
+   - Output: test/artifacts/feature_{slug-a}/test-spec.md
+   - Output: test/feature_{slug-a}.test.js
+   - Output: handoff-nigel.md
+
+5. **Codey Plan** — Create implementation plan
+   - Output: IMPLEMENTATION_PLAN.md
+
+6. **Codey Implement** — Write code to pass tests
+   - Run tests: node --test test/feature_{slug-a}.test.js
+   - Iterate until tests pass
+
+## Rules
+- Work ONLY in .claude/worktrees/feat-{slug-a}
+- Do NOT commit changes
+- Do NOT modify files outside the worktree
+- Report final status: success/failed + summary
+
+## Completion
+Return JSON status:
+{"slug": "{slug-a}", "status": "success|failed", "tests": "X/Y passing", "files": ["list"]}
+```
+
+### Task for {slug-b}:
+(Same prompt structure, different slug and worktree path)
+
+### Task for {slug-c}:
+(Same prompt structure, different slug and worktree path)
+
+**Key:** All three Task tool calls are made in a SINGLE assistant message, enabling concurrent execution.
+```
+
+---
+
+## 6. Add Step M5-M8: Results & Cleanup (new section)
+
+```markdown
+---
+
+## Step M5: Collect Results
+
+As each Task sub-agent completes, collect its status:
+
+```javascript
+results = [
+  { slug: "feat-a", status: "success", tests: "5/5", files: [...] },
+  { slug: "feat-b", status: "success", tests: "3/3", files: [...] },
+  { slug: "feat-c", status: "failed", error: "Nigel tests failed" }
+]
+```
+
+---
+
+## Step M6: Merge Successful Features
+
+For each feature with `status: "success"`:
+
+```bash
+# Switch to main
+git checkout main
+
+# Merge feature branch
+git merge feature/{slug} --no-edit
+
+# On success: record merge
+# On conflict: preserve branch for manual resolution
+```
+
+**Handle merge conflicts:**
+- Do NOT force or abort
+- Record conflict: `{ slug, status: "conflict", branch: "feature/{slug}" }`
+- Worktree preserved for manual resolution
+
+---
+
+## Step M7: Report Summary
+
+**Display murmuration summary:**
+```
+--- Murmuration Complete ---
+
+## Landed (merged to main)
+  ✓ feat-a: 5 tests, 3 files
+  ✓ feat-b: 3 tests, 2 files
+
+## Turbulence (merge conflicts)
+  ⚠ (none)
+
+## Lost Formation (failed)
+  ✗ feat-c: Nigel tests failed
+    Worktree preserved: .claude/worktrees/feat-c
+    To retry: cd .claude/worktrees/feat-c && /implement-feature feat-c
+
+## Next Steps
+- Run `node --test` to verify all tests pass
+- Review any preserved worktrees
+```
+
+---
+
+## Step M8: Cleanup Worktrees
+
+For successfully merged features:
+```bash
+git worktree remove .claude/worktrees/feat-{slug} --force
+git branch -d feature/{slug}
+```
+
+Preserve worktrees for:
+- Failed features (for debugging)
+- Merge conflicts (for manual resolution)
+```
+
+---
+
+## Summary of Changes
+
+| Section | Change Type | Description |
+|---------|-------------|-------------|
+| Invocation | Modify | Add multi-slug syntax |
+| Paths | Add | Worktree path variables |
+| Pipeline Overview | Add | Multi-feature flow diagram |
+| Step M0 | Add | Multi-feature detection |
+| Step M1 | Add | Batch pre-flight validation |
+| Step M2 | Add | Conflict detection |
+| Step M3 | Add | Worktree creation |
+| Step M4 | Add | **Parallel Task spawning** |
+| Step M5-M8 | Add | Results, merge, cleanup |

package/.blueprint/features/feature_split-cli-commands/FEATURE_SPEC.md

@@ -0,0 +1,125 @@
+# Feature Specification — Split CLI Commands
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- `bin/cli.js` is 437 lines and growing — difficult to navigate and maintain
+- Command logic is mixed with routing, flag parsing, and help text
+- Adding new commands requires editing one large file
+- Supports modular architecture and separation of concerns
+
+> Technical refactoring feature — no user-facing behaviour change.
+
+---
+
+## 2. Scope
+### In Scope
+- Extract each command handler to `src/commands/<command>.js`
+- Reduce `bin/cli.js` to a thin router (~50-80 lines)
+- Preserve all existing CLI behaviour exactly
+- Maintain backward compatibility with all command aliases
+
+### Out of Scope
+- Adding new commands
+- Changing command syntax or flags
+- Modifying help text content (only moving it)
+- Performance optimizations
+
+---
+
+## 3. Actors Involved
+**Who interacts with this feature.**
+
+- **Developer**: Edits individual command files instead of monolithic cli.js
+- **CLI User**: No change in experience — all commands work identically
+
+---
+
+## 4. Behaviour Overview
+**What the feature does, conceptually.**
+
+- `bin/cli.js` becomes a router that:
+  1. Parses the command name from `process.argv`
+  2. Dynamically loads the appropriate handler from `src/commands/`
+  3. Passes args and invokes the handler
+  4. Handles errors and exit codes
+
+- Each `src/commands/<name>.js` exports:
+  - `run(args)` — the command handler
+  - `description` — short description for help
+  - `help()` — detailed help text (optional)
+
+---
+
+## 5. State & Lifecycle Interactions
+**How this feature touches the system lifecycle.**
+
+- No state changes — pure refactoring
+- File system structure changes only
+- No runtime behaviour differences
+
+---
+
+## 6. Rules & Decision Logic
+**New or exercised rules.**
+
+| Rule | Description |
+|------|-------------|
+| Command mapping | Command name maps to `src/commands/<name>.js` |
+| Alias resolution | Aliases (murm/parallel/murmuration) resolve before loading |
+| Flag parsing | Remains in individual command handlers, not centralized |
+| Error handling | Each command handles its own errors; router catches unhandled |
+
+---
+
+## 7. Dependencies
+**What this feature relies on.**
+
+- Node.js `require()` for dynamic loading
+- Existing module structure in `src/`
+- No external dependencies added
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Startup time**: Lazy loading commands means faster startup for simple commands
+- **Testability**: Individual command files are easier to unit test
+- **Maintainability**: Clear ownership of each command
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- All commands can be cleanly extracted without shared state
+- The `parseFlags()` helper can remain in cli.js or move to a utility
+
+**Open Questions:**
+- Should `parseFlags()` move to `src/utils.js` or stay in cli.js?
+- Should command files include their own validation or use a shared validator?
+
+---
+
+## 10. Impact on System Specification
+
+- No impact — internal refactoring only
+- Does not change system boundaries or behaviour
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Skip Cass stage** — this is a technical refactoring feature with no user stories needed.
+
+Direct handover to Nigel for test creation:
+- Tests should verify all commands still work after extraction
+- Tests should verify help output is unchanged
+- Tests should verify error handling is preserved
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-03-03 | Initial spec | Technical debt reduction | Alex |

package/.blueprint/features/feature_split-cli-commands/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,119 @@
+# Implementation Plan: Split CLI Commands
+
+## Overview
+Extract command handlers from `bin/cli.js` (437 lines) into `src/commands/` directory, leaving a thin router (~50-80 lines).
+
+## Phase 1: Create Directory Structure
+- Create `src/commands/` directory
+- Create `src/commands/utils.js` for shared utilities (parseFlags)
+
+## Phase 2: Extract Commands (in order of complexity)
+
+### Simple Commands (no subcommands)
+1. **init.js** - Direct passthrough to `src/init.js`
+2. **update.js** - Direct passthrough to `src/update.js`
+3. **help.js** - Contains showHelp() function
+
+### Commands with Flags
+4. **validate.js** - Calls validate(), formats output, sets exit code
+5. **insights.js** - Handles --bottlenecks, --failures, --json, --feedback flags
+
+### Commands with Subcommands
+6. **queue.js** - Handles `reset` subcommand
+7. **history.js** - Handles `clear`, `export`, --stats, --all flags
+8. **retry-config.js** - Handles `set`, `reset` subcommands
+9. **feedback-config.js** - Handles `set`, `reset` subcommands
+10. **stack-config.js** - Handles `set`, `reset` subcommands
+11. **murm-config.js** - Handles `set`, `reset` subcommands (with aliases)
+
+### Complex Commands
+12. **murm.js** - Handles status, rollback, cleanup, abort subcommands + main execution (with aliases)
+
+## Phase 3: Refactor Router
+- Replace inline handlers with dynamic loading from `src/commands/`
+- Handle aliases in router (murm/parallel/murmuration, murm-config/parallel-config)
+- Keep under 100 lines
+
+## File Structure After Refactoring
+
+```
+src/commands/
+  init.js
+  update.js
+  queue.js
+  validate.js
+  history.js
+  insights.js
+  retry-config.js
+  feedback-config.js
+  stack-config.js
+  murm-config.js
+  murm.js
+  help.js
+  utils.js          # parseFlags helper
+```
+
+## Command Module Template
+
+```javascript
+// src/commands/<name>.js
+const description = 'Short description for help';
+
+async function run(args) {
+  // Command implementation
+}
+
+module.exports = { run, description };
+```
+
+## Router Template (bin/cli.js)
+
+```javascript
+#!/usr/bin/env node
+const path = require('path');
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+// Alias resolution
+const aliases = {
+  'parallel': 'murm',
+  'murmuration': 'murm',
+  'parallel-config': 'murm-config'
+};
+
+const resolvedCommand = aliases[command] || command;
+
+// Dynamic loading
+async function main() {
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    const help = require('../src/commands/help');
+    help.run(args);
+    return;
+  }
+
+  const cmdPath = path.join(__dirname, '../src/commands', `${resolvedCommand}.js`);
+  try {
+    const cmd = require(cmdPath);
+    await cmd.run(args);
+  } catch (err) {
+    if (err.code === 'MODULE_NOT_FOUND') {
+      console.error(`Unknown command: ${command}`);
+      console.error('Run "agent-workflow help" for usage information.');
+      process.exit(1);
+    }
+    throw err;
+  }
+}
+
+main().catch(err => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});
+```
+
+## Test Command
+```bash
+cd /workspaces/agent-workflow/.claude/worktrees/feat-split-cli-commands
+node --test test/feature_split-cli-commands.test.js
+```

package/.blueprint/features/feature_split-cli-commands/handoff-nigel.md

@@ -0,0 +1,45 @@
+# Handoff: Nigel -> Codey
+
+## Feature: split-cli-commands
+
+## Test Summary
+- **Test file**: `test/feature_split-cli-commands.test.js`
+- **Test count**: 26 test cases
+- **Coverage**: Module structure, aliases, router constraints, command descriptions
+
+## Key Test Requirements
+
+1. **Directory structure**: `src/commands/` must exist with 12 command modules
+2. **Module interface**: Each command exports `run(args)` function and `description` string
+3. **Router constraint**: `bin/cli.js` must be <= 100 lines (thin router)
+4. **Aliases**: murm/parallel/murmuration and murm-config/parallel-config must work
+
+## Commands to Extract
+
+| Command | Source Lines (approx) |
+|---------|----------------------|
+| init | 3 lines |
+| update | 3 lines |
+| queue | 8 lines |
+| validate | 8 lines |
+| history | 28 lines |
+| insights | 12 lines |
+| retry-config | 16 lines |
+| feedback-config | 16 lines |
+| stack-config | 16 lines |
+| murm-config | 34 lines |
+| murm (parallel) | 86 lines |
+| help | 68 lines |
+
+## Implementation Notes
+
+- `parseFlags()` helper can stay in cli.js or move to `src/commands/utils.js`
+- Aliases should be handled in the router, not in individual commands
+- Each command file should be self-contained with its imports
+- Help text for each command should match current output exactly
+
+## Run Tests
+```bash
+cd /workspaces/agent-workflow/.claude/worktrees/feat-split-cli-commands
+node --test test/feature_split-cli-commands.test.js
+```