murmur8 3.5.0

package/.blueprint/system_specification/SYSTEM_SPEC.md

@@ -0,0 +1,248 @@
+# System Specification — murmur8
+
+## 1. Purpose & Intent
+
+**murmur8** is a multi-agent workflow framework that automates feature development from specification to implementation. It coordinates four specialized AI agents (Alex, Cass, Nigel, Codey) through a sequential pipeline, ensuring that features are explicitly specified, documented with user stories, tested, and implemented with traceability.
+
+**Why this system exists:**
+- To transform feature ideas into working, tested code through a structured, repeatable process
+- To maintain coherence between specifications, stories, tests, and implementation
+- To reduce ambiguity and drift by enforcing explicit handoffs between agents
+
+**Who it exists for:**
+- Developers using Claude Code who want automated, spec-driven feature development
+- Teams seeking a structured approach to AI-assisted software engineering
+
+**What success looks like:**
+- Features are implemented with full traceability from spec to code
+- Tests are written before implementation, providing a stable contract
+- All artifacts (specs, stories, tests, code) are aligned and consistent
+
+**What must not be compromised:**
+- Explicit specification before implementation
+- Test-first development contracts
+- Agent role boundaries and handoff integrity
+
+---
+
+## 2. Business & Domain Context
+
+murmur8 operates in the domain of AI-assisted software development, specifically within the Claude Code CLI environment.
+
+**Relevant drivers:**
+- Growing adoption of AI coding assistants
+- Need for structured processes to guide AI-generated code
+- Requirement for traceability and quality assurance in automated development
+
+**Domain constraints:**
+- Operates within Claude Code's Task tool for spawning sub-agents
+- Subject to Claude's token limits (optimized via incremental writes)
+- Relies on file-based artifacts for persistence and handoffs
+
+**Assumptions:**
+- Users have Node.js 18+ installed
+- Users have Claude Code CLI available
+- Projects use standard testing frameworks (Jest, Node test runner)
+- The `.business_context/` directory contains project-specific domain knowledge
+
+---
+
+## 3. System Boundaries
+
+### In Scope
+
+- **CLI tooling:** `init`, `update`, `skills`, `add-skills`, `queue` commands
+- **Agent orchestration:** Sequential pipeline via `/implement-feature` skill
+- **Artifact management:** Feature specs, user stories, test specs, tests, implementation plans
+- **Queue persistence:** Recovery and resumption from `.claude/implement-queue.json`
+- **Skills integration:** Installing optional skills from skills.sh ecosystem
+
+### Out of Scope
+
+- Runtime test execution environment (assumes existing test infrastructure)
+- CI/CD integration (users configure their own pipelines)
+- Project-specific business logic (provided via `.business_context/`)
+- IDE integration beyond Claude Code CLI
+
+---
+
+## 4. Actors & Roles
+
+### Human User
+- **Description:** Developer invoking murmur8 commands and the `/implement-feature` skill
+- **Primary goals:** Automate feature development, maintain control over scope and quality
+- **Authority:** Final arbiter on intent, scope, and breaking changes; can pause/abort pipeline
+
+### Alex (System Specification & Chief-of-Staff)
+- **Description:** Creates and maintains system and feature specifications
+- **Primary goals:** Prevent drift, ensure coherence, produce feature specs for downstream agents
+- **Authority:** Can define and evolve specifications; cannot make unilateral product decisions
+
+### Cass (Story Writer / Business Analyst)
+- **Description:** Translates feature specs into user stories and acceptance criteria
+- **Primary goals:** Produce explicit, testable, behaviour-first stories
+- **Authority:** Elaborates specifications into stories; does not introduce unspecified behaviour
+
+### Nigel (Tester)
+- **Description:** Creates test specifications and executable tests from user stories
+- **Primary goals:** Expose ambiguities, provide stable test contracts
+- **Authority:** Defines test coverage; does not implement production code
+
+### Codey (Developer)
+- **Description:** Implements features according to plans and test contracts
+- **Primary goals:** Make tests pass, maintain code quality
+- **Authority:** Writes implementation code; does not modify tests without agreement
+
+---
+
+## 5. Core Domain Concepts
+
+### Feature
+- **Definition:** A bounded unit of functionality identified by a slug (e.g., `user-auth`)
+- **Key attributes:** slug, feature spec, user stories, tests, implementation plan
+- **Lifecycle:** Created by Alex, elaborated by Cass, tested by Nigel, implemented by Codey
+
+### Pipeline Stage
+- **Definition:** A discrete phase in the feature development workflow
+- **Key attributes:** agent owner, input artifacts, output artifacts
+- **Stages:** alex, cass, nigel, codey-plan, codey-implement, auto-commit
+
+### Queue
+- **Definition:** Persistent state tracking features through the pipeline
+- **Key attributes:** current, alexQueue, cassQueue, nigelQueue, codeyQueue, completed, failed
+- **Lifecycle:** Created on first run, updated at each stage transition, cleared on completion
+
+### Artifact
+- **Definition:** A file produced by an agent as output
+- **Types:** SYSTEM_SPEC.md, FEATURE_SPEC.md, story-*.md, test-spec.md, *.test.js, IMPLEMENTATION_PLAN.md
+
+### Skill
+- **Definition:** A Claude Code command that provides specialized agent capabilities
+- **Key attributes:** name, description, prompt template
+- **Lifecycle:** Installed via `add-skills`, invoked via slash commands
+
+---
+
+## 6. High-Level Lifecycle & State Model
+
+### Pipeline Lifecycle
+
+```
+INIT → ALEX → CASS → NIGEL → CODEY_PLAN → CODEY_IMPLEMENT → COMMIT → COMPLETE
+                                ↓
+                             PAUSED (--pause-after)
+                                ↓
+                             RESUME
+```
+
+### Feature States
+
+| State | Entry Condition | Exit Condition |
+|-------|----------------|----------------|
+| **pending** | Feature slug provided | Agent starts processing |
+| **in_progress** | Agent spawned for stage | Agent completes or fails |
+| **completed** | All stages pass, commit done | Moved to completed list |
+| **failed** | Agent error or abort | Moved to failed list |
+
+### Recovery
+- On re-invocation, pipeline reads `current.stage` from queue and resumes
+- Failed features can be retried or restarted from scratch
+
+---
+
+## 7. Governing Rules & Invariants
+
+### Pipeline Rules
+- **Sequential execution:** Agents execute in order (Alex → Cass → Nigel → Codey)
+- **Artifact gates:** Each stage requires output artifacts before proceeding
+- **System spec gate:** Pipeline cannot proceed without SYSTEM_SPEC.md
+
+### Agent Rules
+- **Single responsibility:** Each agent has defined inputs and outputs; no overlap
+- **No silent changes:** Agents flag deviations; do not silently alter specifications
+- **Incremental output:** All agents write one file at a time to avoid token limits
+
+### Queue Rules
+- **Single current:** Only one feature can be `current` at a time
+- **Immutable completed:** Completed features are not re-processed unless explicitly restarted
+- **Recovery-safe:** Queue file enables resumption after failures
+
+### Implementation Rules
+- **Tests are contracts:** Codey implements against tests, not around them
+- **No test deletion:** Tests cannot be removed without explicit approval
+- **Green suite required:** Implementation is complete only when all tests pass
+
+---
+
+## 8. Cross-Cutting Concerns
+
+### Traceability
+- Every test maps to acceptance criteria (AC → Test ID table)
+- Every story maps to feature spec sections
+- Commit messages reference artifacts and agents
+
+### Token Limit Management
+- Incremental file writes (one file at a time)
+- Brief summaries (5 bullets max)
+- Reference by path instead of quoting content
+- Consolidated artifacts (Nigel: 2 files, not 4)
+
+### Failure Handling
+- Each agent spawn offers: retry, skip, abort
+- Failures are recorded with stage, reason, and timestamp
+- Queue persists state for recovery
+
+### Observability
+- Queue status available via `murmur8 queue`
+- Each agent provides completion summary
+- Commit messages document pipeline execution
+
+---
+
+## 9. Non-Functional Expectations
+
+### Reliability
+- Pipeline resumes from last checkpoint on failure
+- Queue file is gitignored to avoid conflicts
+- Deterministic output given same inputs
+
+### Performance
+- Optimized for Claude's 4096 output token limit
+- Incremental processing reduces memory pressure
+- Skills installed once per project
+
+### Extensibility
+- Skills can be added per-agent from skills.sh ecosystem
+- Agent specifications can be customized in `.blueprint/agents/`
+- Business context directory allows project-specific grounding
+
+### Maintainability
+- `update` command replaces framework files while preserving user content
+- Clear separation: framework dirs (replaced) vs user dirs (preserved)
+
+---
+
+## 10. Known Gaps, Risks & Open Questions
+
+### Known Limitations
+- Pipeline is sequential; no parallel agent execution
+- Single-feature focus; no batch processing
+- Assumes Node.js testing ecosystem
+
+### Risks
+- Token limit errors if agents generate excessive output
+- Agent specifications may need tuning for non-standard projects
+- Skill installation requires network access
+
+### Open Questions
+- Should agents support alternative testing frameworks?
+- Could pipeline stages be made configurable or skippable?
+- How to handle features that span multiple repositories?
+
+---
+
+## 11. Change Log (System-Level)
+
+| Date | Change | Reason | Approved By |
+|------|--------|--------|-------------|
+| 2026-02-24 | Initial system specification | Document murmur8 v2.5.0 | Alex |

package/.blueprint/templates/FEATURE_SPEC.md

@@ -0,0 +1,125 @@
+# Feature Specification — <Feature Name>
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Problem being addressed
+- User or system need
+- How this supports the system purpose
+
+> If this does not clearly align to the System Spec, Alex must flag it.
+
+---
+
+## 2. Scope
+### In Scope
+- Behaviours, flows, or decisions this feature introduces
+
+### Out of Scope
+- Explicit exclusions
+- Deferred behaviour
+
+---
+
+## 3. Actors Involved
+**Who interacts with this feature.**
+
+For each actor:
+- Actor name
+- What they can do in this feature
+- What they cannot do
+
+---
+
+## 4. Behaviour Overview
+**What the feature does, conceptually.**
+
+- Happy-path behaviour
+- Key alternatives or branches
+- User-visible outcomes
+
+(No UI detail here — behaviour only.)
+
+---
+
+## 5. State & Lifecycle Interactions
+**How this feature touches the system lifecycle.**
+
+- States entered
+- States exited
+- States modified
+- Whether this feature is:
+  - state-creating
+  - state-transitioning
+  - state-constraining
+
+---
+
+## 6. Rules & Decision Logic
+**New or exercised rules.**
+
+For each rule:
+- Description
+- Inputs
+- Outputs
+- Deterministic vs discretionary
+
+---
+
+## 7. Dependencies
+**What this feature relies on.**
+
+- System components
+- External systems
+- Policy or legislative dependencies
+- Operational dependencies
+
+---
+
+## 8. Non-Functional Considerations
+**Only where relevant.**
+
+- Performance sensitivity
+- Audit/logging needs
+- Error tolerance
+- Security implications
+
+---
+
+## 9. Assumptions & Open Questions
+**What must be true for this feature to work.**
+
+- Assumptions
+- Unknowns
+- Areas needing confirmation
+
+---
+
+## 10. Impact on System Specification
+**Alex-owned reconciliation section.**
+
+- Does this feature:
+  - Reinforce existing system assumptions?
+  - Stretch them?
+  - Contradict them?
+
+If contradiction exists:
+- Describe the tension
+- Propose a system spec change (do not apply it)
+- Flag for decision
+
+---
+
+## 11. Handover to BA (Cass)
+**What Cass should derive from this spec.**
+
+- Story themes
+- Expected story boundaries
+- Areas needing careful story framing
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|-----|------|--------|-----------|
+|     |      |        |           |

package/.blueprint/templates/STORY_TEMPLATE.md

@@ -0,0 +1,96 @@
+# User Story Template
+
+Use this template when writing user stories and acceptance criteria.
+
+---
+
+## Screen [N] — [Title]
+
+### User story
+As a [role], I want [capability] so that [benefit].
+
+---
+
+### Context / scope
+- Professional user (Solicitor)
+- England standard possession claim
+- Screen is reached when: [entry condition]
+- Route:
+  - `GET /claims/[route-name]`
+  - `POST /claims/[route-name]`
+- This screen captures: [what data]
+
+---
+
+### Acceptance criteria
+
+Write ACs in **Given/When/Then** format (precondition, action, result):
+
+**AC-1 — [Short description]**
+- Given [precondition],
+- When [action],
+- Then [expected result].
+
+**AC-2 — [Short description]**
+- Given [precondition],
+- When [action],
+- Then [expected result].
+
+<!-- Continue with AC-3, AC-4, etc. -->
+
+**AC-N — Previous navigation**
+- Given I click Previous,
+- Then I am returned to [previous route]
+- And any entered data is preserved in session.
+
+**AC-N+1 — Continue navigation**
+- Given I click Continue and validation passes,
+- Then I am redirected to [next route].
+
+**AC-N+2 — Cancel behaviour**
+- Given I click Cancel,
+- Then I am returned to /case-list
+- And the claim draft remains stored in session.
+
+**AC-N+3 — Accessibility compliance**
+- Given validation errors occur,
+- Then:
+  - a GOV.UK error summary is displayed at the top of the page,
+  - errors link to the relevant field,
+  - focus moves to the error summary,
+  - and all inputs are properly labelled and keyboard accessible.
+
+---
+
+### Session persistence
+
+```js
+session.claim.fieldName = {
+  property: 'value' | null
+}
+```
+
+---
+
+### Out of scope
+- [Item 1]
+- [Item 2]
+
+---
+
+## Guidelines for writing user stories
+
+### Every AC must be:
+- Deterministic
+- Observable via the UI or session
+- Unambiguous
+
+### Routing must be explicit for:
+- Previous link
+- Continue button
+- Cancel link
+- Any conditional paths
+
+### Keep stories focused:
+- Maximum 5-7 ACs per story
+- If more needed, split into multiple story files

package/.blueprint/templates/SYSTEM_SPEC.md

@@ -0,0 +1,128 @@
+# System Specification — <System Name>
+
+## 1. Purpose & Intent
+**Why this system exists.**
+
+- Problem the system is solving
+- Who it exists for
+- What success looks like in business terms
+- What *must not* be compromised
+
+> This section anchors all future decisions.  
+> If a feature contradicts this, Alex must flag it.
+
+---
+
+## 2. Business & Domain Context
+**Grounded in `.business_context`.**
+
+- Relevant policy, legislation, or organisational drivers
+- Domain constraints the system must respect
+- Known external pressures (operational, judicial, regulatory, etc.)
+
+**Assumptions**
+- Explicit assumptions currently being made
+- What is expected to change over time
+
+---
+
+## 3. System Boundaries
+**What is in scope vs out of scope.**
+
+### In Scope
+- Capabilities this system explicitly owns
+
+### Out of Scope
+- Capabilities intentionally excluded
+- Adjacent systems or manual processes
+
+---
+
+## 4. Actors & Roles
+**Who interacts with the system and how.**
+
+For each actor:
+- Actor name
+- Description
+- Primary goals
+- Authority level (what they can and cannot do)
+
+---
+
+## 5. Core Domain Concepts
+**Shared language and meanings.**
+
+For each concept:
+- Name
+- Definition
+- Key attributes
+- Lifecycle relevance (if applicable)
+
+> This is the canonical vocabulary.  
+> Feature specs and stories must not redefine these silently.
+
+---
+
+## 6. High-Level Lifecycle & State Model
+**How the system behaves over time.**
+
+- Key lifecycle phases
+- High-level states
+- Entry / exit conditions
+- Terminal vs non-terminal states
+
+Notes:
+- Known complexity or ambiguity
+- Areas expected to evolve
+
+---
+
+## 7. Governing Rules & Invariants
+**What must always be true.**
+
+- Business rules that must not be violated
+- Legal or policy invariants
+- Cross-feature constraints
+
+Examples:
+- “X cannot occur unless Y has happened”
+- “Once in state Z, only A or B are permitted”
+
+---
+
+## 8. Cross-Cutting Concerns
+**Concerns that affect multiple features.**
+
+- Multi-party behaviour
+- Divergence / convergence
+- Auditability
+- Transparency
+- Accessibility
+- Observability
+- Resilience / failure handling
+
+---
+
+## 9. Non-Functional Expectations (System-Level)
+**Not exhaustive NFRs, but system intent.**
+
+- Performance expectations (qualitative)
+- Reliability expectations
+- Security posture
+- Scalability assumptions
+
+---
+
+## 10. Known Gaps, Risks & Open Questions
+**Explicit uncertainty.**
+
+- Known weak points in the design
+- Open policy or domain questions
+- Areas where future features are expected to challenge the system
+
+---
+
+## 11. Change Log (System-Level)
+| Date | Change | Reason | Approved By |
+|-----|------|--------|-------------|
+|     |      |        |             |

package/.blueprint/templates/TEST_TEMPLATE.md

@@ -0,0 +1,76 @@
+# Test Template
+
+Use this template when writing test specifications and executable tests.
+
+---
+
+## Outputs you must produce
+
+### 1. test-spec.md (write FIRST, keep under 100 lines)
+- Brief understanding (5-10 lines max)
+- AC to Test ID mapping table (compact format)
+- Key assumptions (bullet list)
+
+### 2. Executable test file (write SECOND)
+- One `describe` block per user story
+- One `it` block per acceptance criterion
+- Self-documenting test names with minimal comments
+
+---
+
+## AC to Test ID Mapping Table Format
+
+| AC | Test ID | Scenario |
+|----|---------|----------|
+| AC-1 | T-1.1 | Valid credentials leads to success |
+| AC-1 | T-1.2 | Invalid password leads to error |
+| AC-2 | T-2.1 | Missing field shows validation |
+
+---
+
+## Traceability Table Format
+
+| Acceptance Criterion | Test IDs | Notes |
+|---------------------|----------|-------|
+| AC-1 | T-1.1, T-1.2 | Happy path covered |
+| AC-2 | T-2.1 | Edge case pending |
+
+---
+
+## Test Design Principles
+
+- **Clarity over cleverness**: Prioritise readability with explicit steps
+- **Determinism**: Avoid flaky patterns and random inputs
+- **Coverage with intent**: Focus on behavioural coverage, not test count
+- **Boundaries and edge cases**: Consider min/max, empty/null, invalid formats
+
+---
+
+## Test Structure Example
+
+```javascript
+describe('Feature: [Feature Name]', () => {
+  describe('[User Story Reference]', () => {
+    it('T-1.1: [behaviour description]', async () => {
+      // Given [precondition]
+      // When [action]
+      // Then [expected result]
+    });
+
+    it('T-1.2: [another behaviour]', () => {
+      // Test implementation
+    });
+  });
+});
+```
+
+---
+
+## Guidelines
+
+- Make failure states meaningful with expected error messages
+- Avoid over-prescribing implementation details
+- Focus on externally observable behaviour
+- Keep tests small and isolated with one main assertion per test
+- Clean up async tasks and resources at test end
+- Use `it.skip` or `test.todo` for pending/blocked tests