murmur8 4.2.0 → 4.3.1

package/.blueprint/features/feature_theme-adoption/FEATURE_SPEC.md

@@ -0,0 +1,143 @@
+# Feature Specification — Theme Adoption
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- `src/theme.js` provides consistent murmuration-themed formatting (glyphs, colors, progress bars)
+- Currently only used by murm.js for parallel execution output
+- Other CLI output (history, insights, validate, configs) uses plain text
+- Inconsistent visual experience across commands
+- Theme constants and helpers should be reused project-wide
+
+> Technical enhancement — adopt theme.js across all CLI output.
+
+---
+
+## 2. Scope
+### In Scope
+- Use `colorize()` for success/error/warning messages across all commands
+- Use `formatStageStart()` pattern for pipeline stage output in SKILL.md execution
+- Use `progressBar()` where applicable (history stats, insights)
+- Use status icons consistently (checkmarks, X marks, warnings)
+- Respect TTY detection for color output
+
+### Out of Scope
+- Creating new theme elements
+- Changing the banner or glyph design
+- Adding animation or spinners to non-murm commands
+- Changing the fundamental output structure of commands
+
+---
+
+## 3. Actors Involved
+**Who interacts with this feature.**
+
+- **CLI User**: Sees consistent, themed output across all commands
+- **Developer**: Uses theme.js helpers instead of inline ANSI codes
+
+---
+
+## 4. Behaviour Overview
+**What the feature does, conceptually.**
+
+Before:
+```
+Retry Configuration
+  Max retries:            3
+  Window size:            10
+```
+
+After:
+```
+Retry Configuration
+
+  Max retries:            3
+  Window size:            10
+  High failure threshold: 0.2
+
+  Stage Strategies:
+    alex            : simplify-prompt -> add-context
+```
+(With colored headers when TTY detected)
+
+**Files to update:**
+- `src/validate.js` — use `colorize()` for pass/fail indicators
+- `src/history.js` — use status icons and colors for status display
+- `src/insights.js` — use `colorize()` for recommendations
+- `src/retry.js` — use `colorize()` in `displayConfig()`
+- `src/feedback.js` — use `colorize()` in `displayConfig()`
+- `src/stack.js` — use `colorize()` in `displayStackConfig()`
+
+---
+
+## 5. State & Lifecycle Interactions
+**How this feature touches the system lifecycle.**
+
+- No state changes — output formatting only
+- Respects existing TTY detection patterns
+
+---
+
+## 6. Rules & Decision Logic
+**New or exercised rules.**
+
+| Rule | Description |
+|------|-------------|
+| TTY detection | Use `process.stdout.isTTY` to enable/disable colors |
+| Success indicators | Green checkmark (✓) or `colorize(text, 'green')` |
+| Error indicators | Red X (✗) or `colorize(text, 'red')` |
+| Warning indicators | Yellow warning (⚠) or `colorize(text, 'yellow')` |
+| Headers | Cyan for section headers |
+
+---
+
+## 7. Dependencies
+**What this feature relies on.**
+
+- `src/theme.js` — already exists with all needed exports
+- No new dependencies
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Accessibility**: Plain text fallback when not TTY (pipes, redirects)
+- **Consistency**: Same visual language across all commands
+- **Maintainability**: Centralized theme makes future changes easy
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- All modules can safely import from theme.js without circular dependencies
+- TTY detection is sufficient for determining color support
+
+**Open Questions:**
+- Should `STATUS_ICONS` in theme.js be updated from `parallel_*` to `murm_*`? (See fix-status-icons in FEATURE_IDEAS.md)
+- Should a `--no-color` flag be added globally?
+
+---
+
+## 10. Impact on System Specification
+
+- No impact — visual enhancement only
+- Does not change system boundaries or behaviour
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Skip Cass stage** — this is a technical enhancement feature with no user stories needed.
+
+Direct handover to Nigel for test creation:
+- Tests should verify output includes expected formatting
+- Tests should verify TTY=false produces plain text
+- Tests should verify no regressions in output content
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-03-03 | Initial spec | Consistent CLI theming | Alex |

package/.blueprint/features/feature_theme-adoption/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,68 @@
+# Implementation Plan — Theme Adoption
+
+## Overview
+Adopt theme.js across all CLI output modules for consistent visual formatting. Replace inline ANSI codes with centralized `colorize()` helper.
+
+## Changes Required
+
+### 1. src/validate.js
+**Current state:** Uses inline ANSI codes for colors
+**Change:** Import `colorize` from theme.js and use it
+
+```javascript
+// Before
+const green = useColor ? '\x1b[32m' : '';
+const red = useColor ? '\x1b[31m' : '';
+const reset = useColor ? '\x1b[0m' : '';
+
+// After
+const { colorize } = require('./theme');
+// Use colorize(text, 'green', useColor)
+```
+
+### 2. src/insights.js
+**Current state:** No theme imports, plain section headers
+**Change:** Import `colorize`, apply to section headers
+
+- Header "Pipeline Insights" - cyan
+- Section headers (BOTTLENECK ANALYSIS, etc.) - cyan
+- Recommendations - yellow
+
+### 3. src/retry.js
+**Current state:** Plain text output in displayConfig()
+**Change:** Import `colorize`, apply to header
+
+- Header "Retry Configuration" - cyan
+- Section "Stage Strategies" - cyan
+
+### 4. src/feedback.js
+**Current state:** Plain text output in displayConfig()
+**Change:** Import `colorize`, apply to header
+
+- Header "Feedback Configuration" - cyan
+- Section "Issue Mappings" - cyan
+
+### 5. src/stack.js
+**Current state:** Plain text output in displayStackConfig()
+**Change:** Import `colorize`, apply to header
+
+- Header "Stack Configuration" - cyan
+
+### 6. src/history.js
+**Current state:** Already imports colorize from theme.js
+**Change:** No changes needed - already compliant
+
+## TTY Detection Pattern
+All display functions should:
+1. Check `process.stdout.isTTY` to determine if colors should be enabled
+2. Pass this as `useColor` parameter to `colorize()`
+
+## Implementation Order
+1. validate.js - Replace inline ANSI with colorize import
+2. insights.js - Add colorize for headers
+3. retry.js - Add colorize for displayConfig
+4. feedback.js - Add colorize for displayConfig
+5. stack.js - Add colorize for displayStackConfig
+
+## Testing
+Run `node --test test/feature_theme-adoption.test.js` after each change.

package/.blueprint/features/feature_theme-adoption/handoff-nigel.md

@@ -0,0 +1,35 @@
+# Nigel Handoff — Theme Adoption
+
+## Summary
+Created test suite for theme adoption across CLI modules. Tests verify:
+- `colorize()` function usage for colored output
+- TTY detection pattern (useColor parameter)
+- Plain text fallback when colors disabled
+- Consistent status icons (checkmark/X)
+- Section headers in config displays
+
+## Test File
+`test/feature_theme-adoption.test.js`
+
+## Test Coverage
+| Module | Tests |
+|--------|-------|
+| theme.js | Exports, colorize behavior |
+| validate.js | formatOutput with/without color |
+| insights.js | Section headers |
+| retry.js | displayConfig output |
+| feedback.js | displayConfig output |
+| stack.js | displayStackConfig output |
+
+## Implementation Notes for Codey
+1. **validate.js** - Replace inline ANSI codes with `colorize()` import from theme.js
+2. **insights.js** - Add colorize import, apply to section headers (BOTTLENECK ANALYSIS, etc.)
+3. **retry.js** - Add colorize import, theme the header and optionally section labels
+4. **feedback.js** - Add colorize import, theme the header
+5. **stack.js** - Add colorize import, theme the header
+6. **history.js** - Already imports colorize, verify consistent usage
+
+## Key Patterns
+- Use `process.stdout.isTTY` to determine `useColor`
+- Pass `useColor` boolean to `colorize(text, color, useColor)`
+- Green for success, red for error, yellow for warning, cyan for headers

package/.blueprint/templates/BACKLOG_TEMPLATE.md

@@ -0,0 +1,46 @@
+# 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 | example-feature | Brief description of what this feature does |
+
+---
+
+## Details
+
+### example-feature
+
+Additional context only if the one-line description is insufficient. Keep brief.
+
+---
+
+## Notes
+
+- Items removed automatically when pipeline completes successfully
+- Run with: `/implement-feature "slug"` or `npx murmur8 murm slug-a slug-b`

package/README.md

@@ -1,9 +1,17 @@
 # murmur8
 
-A multi-agent workflow framework for automated feature development In Claude Code and Copilot CLI. Four specialised AI agents collaborate in sequence to take features from specification to implementation, with built-in feedback loops and self-improvement capabilities.
+A multi-agent workflow framework for automated feature development. Four specialised AI agents collaborate in sequence to take features from specification to implementation, with built-in feedback loops and self-improvement capabilities. 
 
 Like a murmuration of starlings, individual agents move together as one, each responding to its neighbours to create something greater than the sum of its parts.
 
+# TLDR - Using murmur8
+
+## Using murmur8 inside Claude Code or Copilot CLI
+Initialize with `npx murmur8 init`, then run `/implement-feature your-feature` in Claude Code or Copilot CLI. Four AI agents collaborate to turn your idea into tested, working code — from spec to implementation. Add up to 3 feature slugs and the murmuration magic will build them in paralell in an isolated git worktree. 
+
+## Using murmur8 outside of Claude Code or Copilot CLI
+Initialize with `npx murmur8 init`, then run `npx murmur8 murm feature-a feature-b` from your terminal. Each feature gets an isolated git worktree and runs its own pipeline. Successful features auto-merge to main. Use `--dry-run` to preview the plan first.
+
 ## Upgrading to v4.0
 
 v4.0 completes the murmuration theming by renaming all parallel internals. Existing users should be aware of the following breaking changes.
@@ -95,7 +103,9 @@ This updates `.blueprint/agents/`, `.blueprint/templates/`, `.blueprint/ways_of_
 | Command | Description |
 |---------|-------------|
 | `npx murmur8 history` | View recent pipeline runs |
+| `npx murmur8 history --cost` | View runs with cost breakdown |
 | `npx murmur8 history --stats` | View aggregate statistics |
+| `npx murmur8 history --stats --cost` | View stats with cost metrics |
 | `npx murmur8 history --all` | View all runs |
 | `npx murmur8 history clear` | Clear history |
 | `npx murmur8 history export` | Export history as CSV (default) |
@@ -128,6 +138,9 @@ This updates `.blueprint/agents/`, `.blueprint/templates/`, `.blueprint/ways_of_
 | `npx murmur8 stack-config` | View detected tech stack |
 | `npx murmur8 stack-config set <key> <value>` | Modify stack settings (language, frameworks, testRunner, etc.) |
 | `npx murmur8 stack-config reset` | Reset to empty defaults |
+| `npx murmur8 cost-config` | View cost tracking pricing |
+| `npx murmur8 cost-config set <key> <value>` | Modify pricing (inputPrice, outputPrice) |
+| `npx murmur8 cost-config reset` | Reset to default Claude pricing |
 | `npx murmur8 retry-config` | View retry configuration |
 | `npx murmur8 retry-config set <key> <value>` | Modify retry settings |
 | `npx murmur8 retry-config reset` | Reset to defaults |
@@ -136,20 +149,22 @@ This updates `.blueprint/agents/`, `.blueprint/templates/`, `.blueprint/ways_of_
 | `npx murmur8 murm-config` | View murmuration pipeline configuration |
 | `npx murmur8 murm-config set <key> <value>` | Modify murmuration settings |
 
-## Usage
+## Skill usage
 
 Run the pipeline with the `/implement-feature` skill in Claude Code:
 
 ```bash
 /implement-feature                           # Interactive
-/implement-feature "user-auth"               # New feature
-/implement-feature "user-auth" --no-feedback # Skip feedback collection
-/implement-feature "user-auth" --no-validate # Skip pre-flight validation
-/implement-feature "user-auth" --no-history  # Skip history recording
-/implement-feature "user-auth" --no-commit   # Skip auto-commit
-/implement-feature "user-auth" --pause-after=alex|cass|nigel|codey-plan
-/implement-feature "user-auth" --with-stories  # Force include Cass stage
-/implement-feature "user-auth" --skip-stories  # Force skip Cass stage
+/implement-feature "Your Slug"               # New feature
+/implement-feature "Your Slug" --no-feedback # Skip feedback collection
+/implement-feature "Your Slug" --no-validate # Skip pre-flight validation
+/implement-feature "Your Slug" --no-history  # Skip history recording
+/implement-feature "Your Slug" --no-commit   # Skip auto-commit
+/implement-feature "Your Slug" --no-diff-preview  # Skip diff preview before commit
+/implement-feature "Your Slug" --pause-after=alex|cass|nigel|codey-plan
+/implement-feature "Your Slug" --with-stories  # Force include Cass stage
+/implement-feature "Your Slug" --skip-stories  # Force skip Cass stage
+/implement-feature "Your Slug A" "Your Slug B" "Your Slug C" # Runs murmuration with sub agents within a single instance of the CLI.
 ```
 
 ## Smart Story Routing (v2.7)
@@ -234,8 +249,15 @@ The pipeline includes validation, smart routing, feedback loops, and history tra
                               │
                               ▼
 ┌─────────────────────────────────────────────────────────────────┐
+│  Diff Preview (unless --no-diff-preview)                        │
+│  • Show file changes (added/modified/deleted)                   │
+│  • User confirms: commit / abort / view full diff               │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
 │  Auto-commit → Record to History                                │
-│  • Duration, feedback scores, outcome                           │
+│  • Duration, feedback scores, token cost, outcome               │
 └─────────────────────────────────────────────────────────────────┘
 ```
 
@@ -246,7 +268,7 @@ murmur8 includes these built-in modules for observability and self-improvement:
 | Module | Purpose |
 |--------|---------|
 | **validate** | Pre-flight checks before pipeline runs |
-| **history** | Records execution data (timing, status, feedback) |
+| **history** | Records execution data (timing, status, feedback, cost) |
 | **insights** | Analyzes patterns, detects bottlenecks, recommends improvements |
 | **retry** | Smart retry strategies based on failure history |
 | **feedback** | Agent-to-agent quality assessment with correlation tracking |
@@ -256,6 +278,8 @@ murmur8 includes these built-in modules for observability and self-improvement:
 | **tools** | Tool schemas and validation for Claude native features |
 | **murm** | Murmuration pipeline execution using git worktrees |
 | **stack** | Configurable tech stack detection and configuration |
+| **cost** | Token usage tracking and cost estimation per stage |
+| **diff-preview** | Pre-commit change review with user confirmation |
 
 ### How They Work Together
 
@@ -264,8 +288,12 @@ Pipeline Run
      │
      ├──► history.js records timing at each stage
      │
+     ├──► cost.js tracks token usage per stage
+     │
      ├──► feedback.js collects quality ratings between stages
      │
+     ├──► diff-preview.js shows changes before commit
+     │
      └──► On completion/failure, data stored in pipeline-history.json
                               │
                               ▼
@@ -317,6 +345,7 @@ your-project/
 │   ├── pipeline-history.json      # Execution history (gitignored)
 │   ├── retry-config.json          # Retry configuration (gitignored)
 │   ├── feedback-config.json       # Feedback thresholds (gitignored)
+│   ├── cost-config.json           # Cost tracking pricing (gitignored)
 │   ├── murm-config.json            # Murmuration execution config (gitignored)
 │   ├── murm-queue.json             # Murmuration pipeline state (gitignored)
 │   ├── stack-config.json          # Tech stack configuration (gitignored)
@@ -410,6 +439,44 @@ Version 2.7 introduces several optimizations to reduce token usage:
 
 **Total estimated savings: 10,000+ tokens per pipeline run** (more for technical features)
 
+## Cost Tracking
+
+Track token usage and estimated costs per pipeline stage:
+
+```bash
+# View costs in history
+npx murmur8 history --cost
+
+SLUG                STATUS    DURATION   TOTAL COST
+user-auth           success   12m 30s    $0.088
+api-validation      success    8m 15s    $0.062
+
+# View cost statistics
+npx murmur8 history --stats --cost
+
+Avg cost per run:        $0.075
+Total cost (all runs):   $1.12
+Most expensive stage:    codey-implement
+```
+
+### Configuration
+
+Default pricing uses Claude Sonnet rates ($3/M input, $15/M output):
+
+```bash
+# View current pricing
+npx murmur8 cost-config
+
+# Customize pricing (per million tokens)
+npx murmur8 cost-config set inputPrice 3
+npx murmur8 cost-config set outputPrice 15
+
+# Reset to defaults
+npx murmur8 cost-config reset
+```
+
+Cost data is stored in `pipeline-history.json` alongside timing and feedback data.
+
 ## Murmuration
 
 Run multiple feature pipelines simultaneously using git worktrees for isolation. Each feature gets its own worktree and branch, allowing true parallel development without conflicts.