murmur8 3.5.0

package/.blueprint/features/feature_interactive-alex/story-iterative-drafting.md

@@ -0,0 +1,65 @@
+# User Story: Iterative Spec Drafting
+
+## Story
+
+**As a** developer in an interactive session,
+**I want** Alex to gather context, ask targeted questions, and draft spec sections incrementally,
+**so that** the resulting specification accurately captures my intent with minimal revision cycles.
+
+## Acceptance Criteria
+
+### AC-1: Context Gathering Phase
+
+**Given** an interactive session has started
+**When** the user provides their initial feature description
+**Then** Alex acknowledges understanding by summarizing the core intent
+**And** Alex identifies 2-4 information gaps relative to the FEATURE_SPEC template
+
+### AC-2: Clarifying Questions
+
+**Given** Alex has identified information gaps
+**When** Alex asks clarifying questions
+**Then** questions are presented in a single batch (2-4 questions)
+**And** questions are specific and actionable (not open-ended)
+**And** Alex waits for user responses before proceeding
+
+### AC-3: Section-by-Section Drafting
+
+**Given** Alex has gathered sufficient context
+**When** Alex drafts spec sections
+**Then** sections are drafted incrementally (Intent first, then Scope, then Actors, etc.)
+**And** after each section, Alex presents the draft
+**And** Alex asks: "Does this capture your intent? Any changes?"
+
+### AC-4: Revision Handling
+
+**Given** Alex has presented a draft section
+**And** the user requests changes via `/change <feedback>`
+**When** Alex revises the section
+**Then** Alex incorporates the specific feedback
+**And** Alex presents the revised draft
+**And** Alex asks for approval again
+
+### AC-5: Progress Indication
+
+**Given** an interactive session is active
+**When** Alex transitions between sections
+**Then** Alex indicates which sections are complete
+**And** Alex indicates which sections remain
+
+### AC-6: Concise Responses
+
+**Given** Alex is drafting or responding in the session
+**When** Alex produces conversational output
+**Then** each response is under 200 words
+**And** focus is on actionable content, not filler
+
+## Out of Scope
+
+- Full-spec-at-once drafting mode
+- Configurable question count (fixed at 2-4)
+- Template customization during session
+
+## References
+
+- Feature Spec: `.blueprint/features/feature_interactive-alex/FEATURE_SPEC.md` (Section 4.3)

package/.blueprint/features/feature_interactive-alex/story-pipeline-integration.md

@@ -0,0 +1,66 @@
+# User Story: Pipeline Integration
+
+## Story
+
+**As a** developer completing an interactive session,
+**I want** the interactive mode to integrate seamlessly with the existing pipeline infrastructure,
+**so that** downstream agents receive proper handoffs and the pipeline can resume or record history as expected.
+
+## Acceptance Criteria
+
+### AC-1: Spec File Output
+
+**Given** an interactive session completes successfully (via `/approve` on final section or `/done`)
+**When** Alex finalizes the spec
+**Then** FEATURE_SPEC.md is written to `{FEAT_DIR}/FEATURE_SPEC.md`
+**And** the file includes all completed sections
+**And** skipped sections are marked as "TBD"
+**And** the file includes a note: "Created via interactive session"
+
+### AC-2: Handoff Artifact
+
+**Given** an interactive session completes successfully
+**When** Alex writes the spec file
+**Then** Alex also produces `handoff-alex.md` in the feature directory
+**And** the handoff includes key decisions, files created, and open questions
+
+### AC-3: Queue Update
+
+**Given** an interactive session completes successfully
+**When** the pipeline continues
+**Then** the queue is updated with the feature moving from `alexQueue` to `cassQueue`
+**And** `current.stage` reflects "cass" (or the next applicable stage)
+
+### AC-4: History Recording
+
+**Given** an interactive session completes (success or abort)
+**When** history is recorded (unless `--no-history` flag present)
+**Then** the `pipeline-history.json` entry includes `mode: "interactive"`
+**And** the entry includes question count, revision count, and session duration
+
+### AC-5: Pause After Alex
+
+**Given** an interactive session completes successfully
+**And** `--pause-after=alex` flag was provided
+**When** Alex finishes
+**Then** the pipeline pauses before spawning Cass
+**And** user can review the spec before continuing
+
+### AC-6: Continue to Downstream Agents
+
+**Given** an interactive session completes successfully
+**And** `--pause-after=alex` flag was NOT provided
+**When** Alex finishes
+**Then** the pipeline continues automatically
+**And** Cass is spawned with the produced FEATURE_SPEC.md as input
+
+## Out of Scope
+
+- Changes to Cass, Nigel, or Codey agent behaviour
+- Parallel pipeline execution
+- Multi-feature batch processing
+
+## References
+
+- Feature Spec: `.blueprint/features/feature_interactive-alex/FEATURE_SPEC.md` (Section 6)
+- System Spec: `.blueprint/system_specification/SYSTEM_SPEC.md` (Sections 6-7)

package/.blueprint/features/feature_interactive-alex/story-session-lifecycle.md

@@ -0,0 +1,75 @@
+# User Story: Interactive Session Lifecycle
+
+## Story
+
+**As a** developer entering interactive mode,
+**I want** a clear session lifecycle with explicit commands for controlling the conversation,
+**so that** I can navigate the spec creation process efficiently and exit gracefully when needed.
+
+## Acceptance Criteria
+
+### AC-1: Session Initialization
+
+**Given** interactive mode is activated (explicit flag or auto-detect)
+**When** the session starts
+**Then** Alex reads system spec (if exists), business context, and feature template
+**And** Alex presents an opening prompt: "Describe the feature you want to build. What problem does it solve and for whom?"
+
+### AC-2: Approve Command
+
+**Given** an interactive session is active
+**And** Alex has presented a draft section
+**When** the user responds with `/approve` or `yes`
+**Then** the current section is marked complete
+**And** Alex proceeds to the next section
+
+### AC-3: Change Command
+
+**Given** an interactive session is active
+**And** Alex has presented a draft section
+**When** the user responds with `/change <feedback>`
+**Then** Alex revises the current section based on the feedback
+**And** Alex presents the revised draft for approval
+
+### AC-4: Skip Command
+
+**Given** an interactive session is active
+**And** Alex has presented a draft section
+**When** the user responds with `/skip`
+**Then** the current section is marked as "TBD" in the spec
+**And** Alex proceeds to the next section
+
+### AC-5: Restart Command
+
+**Given** an interactive session is active
+**And** Alex is working on a section
+**When** the user responds with `/restart`
+**Then** Alex discards the current section draft
+**And** Alex starts the section from scratch with fresh questions
+
+### AC-6: Abort Command
+
+**Given** an interactive session is active
+**When** the user responds with `/abort`
+**Then** the session terminates immediately
+**And** no spec file is written to disk
+**And** the pipeline exits without proceeding to downstream agents
+
+### AC-7: Done Command
+
+**Given** an interactive session is active
+**And** at least Intent, Scope, and Actors sections are complete or skipped
+**When** the user responds with `/done`
+**Then** Alex finalizes the spec with completed sections
+**And** skipped sections are marked as "TBD"
+**And** the spec file is written to disk
+
+## Out of Scope
+
+- Session persistence between interrupted sessions
+- Timeout handling (session continues until user acts)
+- Multi-user concurrent sessions
+
+## References
+
+- Feature Spec: `.blueprint/features/feature_interactive-alex/FEATURE_SPEC.md` (Section 4.4)

package/.blueprint/features/feature_interactive-alex/story-system-spec-creation.md

@@ -0,0 +1,57 @@
+# User Story: Interactive System Spec Creation
+
+## Story
+
+**As a** developer initializing a new project without a system specification,
+**I want** Alex to guide me through creating a SYSTEM_SPEC.md interactively,
+**so that** I establish the project's boundaries and constraints before creating feature specs.
+
+## Acceptance Criteria
+
+### AC-1: System Spec Auto-Detection
+
+**Given** a user invokes `/implement-feature "my-feature"`
+**And** `.blueprint/system_specification/SYSTEM_SPEC.md` does not exist
+**When** the pipeline checks prerequisites
+**Then** interactive mode activates for system spec creation (not feature spec)
+
+### AC-2: System Spec Session Flow
+
+**Given** interactive system spec mode is active
+**When** Alex starts the session
+**Then** Alex asks about: purpose, actors, system boundaries, and governing rules
+**And** Alex drafts SYSTEM_SPEC.md sections incrementally
+**And** the same session commands apply (`/approve`, `/change`, `/skip`, `/restart`, `/abort`, `/done`)
+
+### AC-3: System Spec Output Location
+
+**Given** an interactive system spec session completes successfully
+**When** Alex writes the spec
+**Then** the file is written to `.blueprint/system_specification/SYSTEM_SPEC.md`
+**And** the file follows the SYSTEM_SPEC template structure
+
+### AC-4: Pipeline Gate Satisfied
+
+**Given** SYSTEM_SPEC.md is created via interactive session
+**When** the user re-invokes `/implement-feature "my-feature"`
+**Then** the system spec gate passes
+**And** the pipeline proceeds to feature spec creation (interactive or autonomous)
+
+### AC-5: System Spec Before Feature Spec
+
+**Given** a user invokes `/implement-feature "my-feature" --interactive`
+**And** SYSTEM_SPEC.md does not exist
+**When** the pipeline routing logic runs
+**Then** system spec interactive session runs first
+**And** only after system spec is complete does feature spec interactive session begin
+
+## Out of Scope
+
+- Updating existing SYSTEM_SPEC.md interactively (only creation)
+- Skipping system spec gate entirely
+- System spec versioning or change tracking
+
+## References
+
+- Feature Spec: `.blueprint/features/feature_interactive-alex/FEATURE_SPEC.md` (Section 4.1, Open Question 2)
+- System Spec: `.blueprint/system_specification/SYSTEM_SPEC.md` (Section 7 - System spec gate)

package/.blueprint/features/feature_lazy-business-context/FEATURE_SPEC.md

@@ -0,0 +1,140 @@
+# Feature Specification — Lazy Business Context Loading
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Currently all agents are told to read `.business_context/*` directory
+- Many features don't require business context
+- Reading unnecessary files wastes tokens and processing time
+- Lazy loading reads business context only when the feature spec references it
+
+---
+
+## 2. Scope
+### In Scope
+- Detect whether feature spec cites `.business_context/` files
+- Include business context in agent prompt only if referenced
+- Provide mechanism for agents to request business context if needed mid-task
+
+### Out of Scope
+- Changing business context structure
+- Removing business context capability
+- Automatic business context summarization
+
+---
+
+## 3. Actors Involved
+
+| Actor | Business Context Usage |
+|-------|----------------------|
+| Alex | Primary consumer — grounds feature specs in domain context |
+| Cass | Secondary — references for domain terminology |
+| Nigel | Rare — may need for domain-specific test data |
+| Codey | Rare — may need for domain-specific implementation |
+
+---
+
+## 4. Behaviour Overview
+
+**Happy path (context needed):**
+1. Feature spec contains citation: "Per business_context/domain.md: ..."
+2. Pipeline detects citation during setup
+3. Agent prompt includes: "Business Context: .business_context/"
+4. Agent reads and applies business context
+
+**Happy path (context not needed):**
+1. Feature spec has no business context citations
+2. Pipeline skips business context directive
+3. Agent prompt omits business context reference
+4. Tokens saved
+
+**Detection logic:**
+```javascript
+const featureSpecContent = readFile(FEAT_SPEC);
+const needsBusinessContext = featureSpecContent.includes('.business_context')
+  || featureSpecContent.includes('business_context/');
+```
+
+**Key outcomes:**
+- Variable token savings (depends on business context size)
+- Faster processing for simple features
+- Business context still available when needed
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- No persistent state changes
+- Detection happens at pipeline setup (Step 5)
+- Flag stored in queue: `current.needsBusinessContext: boolean`
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description |
+|------|-------------|
+| Citation detection | Scan feature spec for business_context references |
+| Default to exclude | If no citation found, don't include business context |
+| Alex exception | Alex always has access (creates feature specs from business context) |
+| Explicit include | `--include-business-context` flag overrides detection |
+
+---
+
+## 7. Dependencies
+
+- SKILL.md updated with conditional business context inclusion
+- Pipeline setup (Step 5) performs detection
+- Queue stores detection result for downstream agents
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Performance:** Token savings proportional to business context size
+- **Correctness:** Risk of missing needed context if detection fails
+- **Flexibility:** Override flag provides escape hatch
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- Feature specs reliably cite business context when it's used
+- Detection can be simple string matching
+- Alex stage always needs business context access
+
+**Open Questions:**
+- Should detection be more sophisticated (AST parsing)?
+- What if an agent needs business context mid-task but it wasn't loaded?
+- Should there be a "request context" mechanism for agents?
+
+---
+
+## 10. Impact on System Specification
+
+- Reinforces efficiency goals
+- Adds conditional loading pattern to pipeline
+- No contradiction with system spec
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Story themes:**
+- Implement business context citation detection
+- Update pipeline setup to conditionally include context
+- Add override flag for explicit inclusion
+- Ensure Alex always has business context access
+
+**Expected story boundaries:**
+- One story for detection logic
+- One story for pipeline integration
+- One story for override flag
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|-----|------|--------|-----------|
+| 2026-02-25 | Initial spec | Token efficiency improvement | Claude |

package/.blueprint/features/feature_lazy-business-context/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,54 @@
+# Implementation Plan - Lazy Business Context Loading
+
+## Summary
+
+Implement lazy loading of business context by adding a detection function that scans feature specs for `.business_context` or `business_context/` references. Update the orchestrator to store the detection result in the queue and modify SKILL.md agent prompts to conditionally include the business context directive based on agent name (Alex always gets it) and detection/override flag state.
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/business-context.js` | Create | Detection logic and context inclusion functions |
+| `src/orchestrator.js` | Modify | Integrate detection during queue initialization |
+| `SKILL.md` | Modify | Update agent prompts with conditional business context |
+| `bin/cli.js` | Modify | Add `--include-business-context` flag parsing |
+
+## Implementation Steps
+
+1. **Create `src/business-context.js` module**
+   - Export `needsBusinessContext(featureSpecContent)` - returns boolean based on string matching
+   - Export `parseIncludeBusinessContextFlag(args)` - returns boolean for flag presence
+   - Export `shouldIncludeBusinessContext(agentName, detected, overrideFlag)` - determines if agent gets context
+   - Export `generateBusinessContextDirective(includeContext)` - returns directive string or empty
+   - Tests covered: T-DL-1 through T-DL-5, T-OF-1, T-AE-1 through T-AE-5, T-CI-1, T-CI-2
+
+2. **Update `src/orchestrator.js` queue structure**
+   - Modify `setCurrent()` to accept optional `needsBusinessContext` parameter
+   - Add field to `current` object: `needsBusinessContext: boolean`
+   - Tests covered: T-CI-3, T-CI-4
+
+3. **Update `bin/cli.js` argument parsing**
+   - Add `--include-business-context` to recognized flags
+   - Pass flag value to orchestrator when initializing queue
+   - Tests covered: T-OF-1, T-OF-4
+
+4. **Integrate detection in pipeline setup (Step 5)**
+   - Read feature spec content when initializing queue
+   - Call `needsBusinessContext()` on content
+   - Apply override flag if present
+   - Store result in queue `current.needsBusinessContext`
+   - Tests covered: T-INT-1, T-INT-2, T-INT-3
+
+5. **Update SKILL.md agent prompts conditionally**
+   - Add conditional note in Step 6 (Alex): "Business Context: .business_context/" always included
+   - Add conditional note in Steps 7-10: "Business Context: .business_context/" only if `needsBusinessContext: true`
+   - Document new `--include-business-context` flag in Invocation section
+   - Tests covered: T-CI-1, T-CI-2, T-AE-1 through T-AE-3
+
+6. **Add exports to `src/index.js`**
+   - Export business-context module functions for external use
+
+## Risks/Questions
+
+- **Risk**: Feature specs that need business context but don't explicitly cite it will miss context. Mitigation: The `--include-business-context` override flag provides escape hatch.
+- **Question**: Should detection log when it skips business context for debugging? Recommend: Add optional verbose logging but default to silent.

package/.blueprint/features/feature_model-native-features/FEATURE_SPEC.md

@@ -0,0 +1,174 @@
+# Feature Specification — Model Native Features
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Claude and other LLMs have native features that are more token-efficient than text equivalents
+- System prompts are processed differently than user messages (potentially lower cost)
+- Tool use provides structured outputs without parsing overhead
+- Leveraging these features can significantly reduce token usage and improve reliability
+
+---
+
+## 2. Scope
+### In Scope
+- Use system prompts for static agent context (specs, guardrails)
+- Use tool definitions for structured outputs (feedback, handoff summaries)
+- Investigate prompt caching for repeated context
+- Document model-specific optimizations
+
+### Out of Scope
+- Changing pipeline logic
+- Supporting multiple LLM providers (Claude-focused initially)
+- Real-time model switching
+
+---
+
+## 3. Actors Involved
+
+| Actor | Native Feature Usage |
+|-------|---------------------|
+| All Agents | System prompt for static context |
+| All Agents | Tool use for structured outputs |
+| Pipeline | Prompt caching for repeated context |
+
+---
+
+## 4. Behaviour Overview
+
+### System Prompts for Static Context
+
+**Current approach:**
+```
+User: You are Alex, the System Specification Agent.
+Read your full specification from: .blueprint/agents/AGENT_SPECIFICATION_ALEX.md
+...
+```
+
+**Native approach:**
+```
+System: [Agent spec content loaded here - potentially cached/cheaper]
+User: Create a feature specification for "user-auth".
+Inputs: ...
+Outputs: ...
+```
+
+### Tool Use for Structured Outputs
+
+**Current approach:**
+```
+Output your feedback as:
+FEEDBACK: { "rating": N, "issues": [...], "recommendation": "..." }
+```
+
+**Native approach:**
+```javascript
+tools: [{
+  name: "submit_feedback",
+  description: "Submit quality rating for prior stage",
+  input_schema: {
+    type: "object",
+    properties: {
+      rating: { type: "number", minimum: 1, maximum: 5 },
+      issues: { type: "array", items: { type: "string" } },
+      recommendation: { enum: ["proceed", "pause", "revise"] }
+    },
+    required: ["rating", "issues", "recommendation"]
+  }
+}]
+```
+
+### Prompt Caching
+
+- Cache static content (agent specs, guardrails, templates)
+- Reduce repeated token transmission
+- Leverage Claude's prompt caching feature when available
+
+**Key outcomes:**
+- Reduced token costs for static content
+- More reliable structured outputs (no parsing errors)
+- Faster responses with cached prompts
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- No pipeline state changes
+- Tool responses integrated into existing feedback flow
+- Caching is transparent to pipeline logic
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description |
+|------|-------------|
+| System prompt for static | Agent specs, guardrails go in system prompt |
+| User prompt for dynamic | Task-specific instructions in user message |
+| Tools for structure | Any JSON output should use tool definitions |
+| Cache when possible | Repeated context should leverage caching |
+
+---
+
+## 7. Dependencies
+
+- Claude API access with system prompt support
+- Tool use capability in Task tool
+- Prompt caching feature (if available)
+- SKILL.md restructured for system/user prompt split
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Performance:** Significant token reduction (system prompts may be cached/cheaper)
+- **Reliability:** Tool use eliminates JSON parsing errors
+- **Complexity:** Requires understanding model-specific features
+- **Portability:** Optimizations may be Claude-specific
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- Task tool can be configured to use system prompts
+- Tool definitions can be passed to sub-agents
+- Prompt caching provides meaningful savings
+
+**Open Questions:**
+- How does Task tool handle system prompts currently?
+- What's the actual cost difference for system vs user tokens?
+- Is prompt caching available and how is it triggered?
+- Should we abstract these features for multi-model support later?
+
+---
+
+## 10. Impact on System Specification
+
+- Adds model-specific optimization layer
+- May need to document Claude-specific features in system spec
+- Consider portability implications if multi-model support is planned
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Story themes:**
+- Investigate system prompt support in Task tool
+- Restructure SKILL.md for system/user prompt split
+- Define tool schemas for structured outputs (feedback, handoff)
+- Implement tool-based feedback collection
+- Investigate and document prompt caching
+
+**Expected story boundaries:**
+- One story for system prompt investigation and implementation
+- One story for tool schema definitions
+- One story for feedback tool integration
+- One story for prompt caching investigation
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|-----|------|--------|-----------|
+| 2026-02-25 | Initial spec | Token efficiency improvement | Claude |

package/.blueprint/features/feature_model-native-features/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,45 @@
+# Implementation Plan - Model Native Features
+
+## Summary
+
+This feature extracts model-native constructs (tool schemas, prompt structure helpers) into reusable modules to improve token efficiency and output reliability. The implementation focuses on creating exportable tool schema definitions and prompt builder utilities that can be integrated into the pipeline's existing feedback and handoff systems.
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/tools/schemas.js` | Create | Define tool schemas for feedback and handoff |
+| `src/tools/validation.js` | Create | Tool input validation utilities |
+| `src/tools/prompts.js` | Create | System/user prompt structure builders |
+| `src/tools/index.js` | Create | Module exports |
+| `src/feedback.js` | Modify | Use schema validation from tools module |
+| `src/handoff.js` | Modify | Add handoff tool schema support |
+| `test/feature_model-native-features.test.js` | Modify | Import from implementation modules |
+
+## Implementation Steps
+
+1. **Create `src/tools/schemas.js`** - Define `FEEDBACK_TOOL_SCHEMA` and `HANDOFF_TOOL_SCHEMA` as exportable constants matching the test definitions. Include name, description, and input_schema with all property constraints.
+
+2. **Create `src/tools/validation.js`** - Implement `validateToolInput(schema, input)` function that validates inputs against schema constraints (type checking, bounds, enums, required fields). Return `{ valid, errors }` format.
+
+3. **Create `src/tools/prompts.js`** - Implement `buildPromptMessages(staticContent, dynamicContent)` returning array with system and user messages. Include `cache_control: { type: 'ephemeral' }` on system prompt. Add `identifyCacheableContent(content)` helper.
+
+4. **Create `src/tools/index.js`** - Export all schemas, validation, and prompt utilities from single entry point.
+
+5. **Update `src/feedback.js`** - Replace inline validation logic with imported `validateToolInput` using `FEEDBACK_TOOL_SCHEMA`. Maintain backward compatibility with existing `parseFeedbackFromOutput` function.
+
+6. **Update `src/handoff.js`** - Add `validateHandoffToolInput` function using `HANDOFF_TOOL_SCHEMA`. Keep existing markdown-based validation for backward compatibility.
+
+7. **Update tests** - Modify test file to import schemas and validation from `src/tools/` instead of inline definitions. Ensure all 12 test cases pass.
+
+8. **Add module to main exports** - Update `src/index.js` to export tools module for external use.
+
+9. **Run full test suite** - Verify all tests pass with `node --test`.
+
+10. **Document usage** - Add brief note to SKILL.md about tool schema availability (optional, if time permits).
+
+## Risks/Questions
+
+- **Task tool system prompt support**: The feature spec notes uncertainty about how Task tool handles system prompts. Implementation focuses on schemas/utilities first; actual Task tool integration may require separate investigation.
+- **Prompt caching availability**: Claude's prompt caching feature availability is undetermined. The `cache_control` structure is included but actual caching benefits depend on API support.
+- **Backward compatibility**: Both feedback.js and handoff.js must maintain existing text-based parsing alongside new tool validation to avoid breaking current pipeline.