murmur8 4.1.1 → 4.3.0

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.
@@ -98,6 +106,13 @@ This updates `.blueprint/agents/`, `.blueprint/templates/`, `.blueprint/ways_of_
 | `npx murmur8 history --stats` | View aggregate statistics |
 | `npx murmur8 history --all` | View all runs |
 | `npx murmur8 history clear` | Clear history |
+| `npx murmur8 history export` | Export history as CSV (default) |
+| `npx murmur8 history export --format=json` | Export as JSON |
+| `npx murmur8 history export --since=YYYY-MM-DD` | Filter by start date |
+| `npx murmur8 history export --until=YYYY-MM-DD` | Filter by end date |
+| `npx murmur8 history export --status=<status>` | Filter by status (success/failed/paused) |
+| `npx murmur8 history export --feature=<slug>` | Filter by feature slug |
+| `npx murmur8 history export --output=<path>` | Write to file instead of stdout |
 | `npx murmur8 insights` | Analyze patterns and get recommendations |
 | `npx murmur8 insights --feedback` | View feedback correlation analysis |
 | `npx murmur8 insights --bottlenecks` | View bottleneck analysis |
@@ -129,20 +144,21 @@ 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" --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)