murmur8 3.5.0

package/.blueprint/features/feature_feedback-loop/story-feedback-config.md

@@ -0,0 +1,61 @@
+# Story — Feedback Configuration
+
+## User Story
+
+As a **developer**, I want **CLI commands to view and modify feedback thresholds** so that **I can tune quality gate sensitivity based on my project's needs**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 7, configuration is stored in `.claude/feedback-config.json`
+- Per FEATURE_SPEC.md:Section 7, new CLI commands: `murmur8 feedback-config` and `murmur8 feedback-config set <key> <value>`
+- Parallel track to quality gates — configuration can be set independently
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — View feedback configuration**
+- Given the user runs `murmur8 feedback-config`,
+- When the command executes,
+- Then the current configuration is displayed including:
+  - `minRatingThreshold` (default: 3.0)
+  - `enabled` (default: true)
+  - Any custom issue-to-strategy mappings
+
+**AC-2 — Set threshold value**
+- Given the user runs `murmur8 feedback-config set minRating <value>`,
+- When the value is a number between 1.0 and 5.0,
+- Then the threshold is updated in `.claude/feedback-config.json`,
+- And a confirmation message is displayed.
+
+**AC-3 — Invalid threshold rejected**
+- Given the user runs `murmur8 feedback-config set minRating <value>`,
+- When the value is outside 1.0-5.0 range or not a number,
+- Then an error message is displayed,
+- And the configuration is not modified.
+
+**AC-4 — Enable/disable feedback system**
+- Given the user runs `murmur8 feedback-config set enabled <true|false>`,
+- When the command executes,
+- Then the `enabled` flag is updated,
+- And when disabled, feedback collection and quality gates are skipped.
+
+**AC-5 — Configuration file created on first set**
+- Given `.claude/feedback-config.json` does not exist,
+- When the user runs a `feedback-config set` command,
+- Then the file is created with default values plus the specified override.
+
+**AC-6 — Configuration file is gitignored**
+- Given a project is initialised with murmur8,
+- When feedback configuration is created,
+- Then `.claude/feedback-config.json` is included in gitignore patterns.
+
+---
+
+## Out of Scope
+
+- Per-agent threshold configuration (single global threshold for MVP)
+- Custom issue code definition via CLI
+- Configuration import/export

package/.blueprint/features/feature_feedback-loop/story-feedback-insights.md

@@ -0,0 +1,63 @@
+# Story — Feedback Insights
+
+## User Story
+
+As a **developer**, I want **correlation analysis between feedback scores and pipeline outcomes** so that **I can understand how predictive agent feedback is and tune thresholds accordingly**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 7, extends `src/insights.js` with feedback analysis functions
+- Per FEATURE_SPEC.md:Section 6 (Rule 4), calculates agent calibration as correlation between ratings and outcomes
+- Depends on feedback being stored in history (story-feedback-collection.md)
+- Per FEATURE_SPEC.md:Section 9, requires 10+ completed runs for meaningful results
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — Feedback analysis command**
+- Given the user runs `murmur8 insights --feedback`,
+- When sufficient history exists (10+ completed runs with feedback),
+- Then a feedback analysis report is displayed.
+
+**AC-2 — Agent calibration scoring**
+- Given the feedback analysis runs,
+- When calibration is calculated per agent,
+- Then each agent receives a calibration score (0.0-1.0):
+  - 0.0 = feedback uncorrelated with outcomes
+  - 1.0 = perfect predictor of success/failure
+- And the score is displayed as "Cass calibration: 0.72" format.
+
+**AC-3 — Issue pattern correlation**
+- Given feedback history contains issue codes,
+- When the analysis runs,
+- Then issue codes are correlated with failure outcomes,
+- And frequently predictive issues are highlighted (e.g., "`unclear-scope` preceded 80% of failures").
+
+**AC-4 — Threshold recommendation**
+- Given sufficient calibration data exists,
+- When the analysis runs,
+- Then a recommended `minRatingThreshold` is suggested based on historical data,
+- And the recommendation balances false positives (unnecessary pauses) and false negatives (missed quality issues).
+
+**AC-5 — Insufficient data handling**
+- Given the user runs `murmur8 insights --feedback`,
+- When fewer than 10 completed runs with feedback exist,
+- Then a message is displayed: "Insufficient data for feedback analysis. {N}/10 runs with feedback available."
+
+**AC-6 — Retry strategy mapping**
+- Given feedback analysis identifies predictive issue patterns,
+- When the user views insights,
+- Then issue-to-strategy mappings are displayed (per FEATURE_SPEC.md:Rule 3),
+- And the user can see which retry strategies are recommended for common issues.
+
+---
+
+## Out of Scope
+
+- Cross-pipeline feedback aggregation (each project is independent)
+- Real-time calibration updates during pipeline execution
+- Natural language interpretation of feedback patterns
+- Automatic threshold adjustment (user must run `feedback-config set`)

package/.blueprint/features/feature_feedback-loop/story-quality-gates.md

@@ -0,0 +1,57 @@
+# Story — Quality Gates
+
+## User Story
+
+As a **developer**, I want **the pipeline to pause when feedback indicates quality concerns** so that **I can review and address issues before proceeding with flawed inputs**.
+
+---
+
+## Context / Scope
+
+- Per FEATURE_SPEC.md:Section 4 (Alternative: Quality Gate Triggers Pause), pipeline pauses when rating < threshold or recommendation is "pause"
+- Default threshold is 3.0 (per FEATURE_SPEC.md:Section 4)
+- Depends on feedback collection (story-feedback-collection.md)
+- Per SYSTEM_SPEC.md:Section 8, failure handling already supports pause/review — quality gates extend this
+
+---
+
+## Acceptance Criteria
+
+**AC-1 — Quality gate evaluation**
+- Given feedback is collected from an agent,
+- When the orchestrator evaluates the feedback,
+- Then `shouldPause` is true if:
+  - `rating < minRatingThreshold`, OR
+  - `recommendation === "pause"`
+
+**AC-2 — Pipeline pauses on quality gate trigger**
+- Given `shouldPause` evaluates to true,
+- When the quality gate is triggered,
+- Then the pipeline pauses before the current agent begins its main work,
+- And the user is prompted with: "Quality gate triggered. {Agent} rated previous stage {rating}/5. Issues: {issues}. (review/proceed/abort)"
+
+**AC-3 — User can proceed past quality gate**
+- Given the pipeline is paused at a quality gate,
+- When the user chooses "proceed",
+- Then the pipeline continues with the current agent's main work,
+- And the decision is recorded in history.
+
+**AC-4 — User can abort at quality gate**
+- Given the pipeline is paused at a quality gate,
+- When the user chooses "abort",
+- Then the pipeline stops,
+- And the feature is moved to the failed list with reason "quality_gate_abort".
+
+**AC-5 — User can review at quality gate**
+- Given the pipeline is paused at a quality gate,
+- When the user chooses "review",
+- Then the pipeline remains paused,
+- And the user can examine upstream artifacts before deciding to proceed or abort.
+
+---
+
+## Out of Scope
+
+- Automatic remediation or revision of upstream artifacts
+- Multiple threshold levels per agent (single global threshold for MVP)
+- Bypassing quality gates without explicit user action

package/.blueprint/features/feature_interactive-alex/FEATURE_SPEC.md

@@ -0,0 +1,263 @@
+# Feature Specification: Interactive Alex
+
+## 1. Feature Intent
+
+**Problem:** Currently, Alex runs as a one-shot sub-agent via the Task tool, producing feature specifications autonomously without user input. This works well when users have clear requirements, but leads to suboptimal specs when requirements are ambiguous or incomplete. Users must either accept potentially misaligned specs or manually restart the pipeline after reviewing and editing.
+
+**Solution:** Add an interactive conversational mode where Alex engages in back-and-forth dialogue with the user to collaboratively create specifications. This mode triggers automatically when no spec exists, or explicitly via the `--interactive` flag.
+
+**Why this matters:**
+- Reduces spec revision cycles by capturing user intent upfront
+- Improves spec quality through targeted clarifying questions
+- Maintains Alex's role as system conscience while adding user collaboration
+- Aligns with Alex's existing "guiding but revisable" design philosophy
+
+---
+
+## 2. Scope
+
+### In Scope
+
+- `--interactive` flag for `/implement-feature` command
+- Auto-detection: trigger interactive mode when SYSTEM_SPEC.md or FEATURE_SPEC.md is missing
+- Interactive session flow for both system specs and feature specs
+- Conversational draft-review-approve cycle
+- Integration with existing `--pause-after=alex` flag for exit control
+- Session state management (in-memory, not persisted to queue)
+
+### Out of Scope
+
+- Interactive modes for other agents (Cass, Nigel, Codey) - future features
+- Persistent conversation history between sessions
+- Multi-user collaboration (only single user supported)
+- GUI or rich terminal UI (text-based conversation only)
+- Changes to the agent sub-agent runtime prompt format
+
+---
+
+## 3. Actors
+
+### Primary: Human User
+- Invokes `/implement-feature` with optional `--interactive` flag
+- Provides feature context and answers Alex's clarifying questions
+- Reviews and approves draft spec sections
+- Decides whether to continue pipeline or pause for further review
+
+### Secondary: Alex Agent
+- Operates in conversational mode instead of autonomous mode
+- Asks clarifying questions to understand user intent
+- Drafts spec sections incrementally for user feedback
+- Produces final FEATURE_SPEC.md (or SYSTEM_SPEC.md) upon approval
+
+### Affected: Downstream Pipeline
+- Cass, Nigel, Codey continue to operate autonomously after Alex completes
+- No changes to their behaviour or prompts
+
+---
+
+## 4. Behaviour Model
+
+### 4.1 Trigger Conditions
+
+Interactive mode activates when ANY of these conditions are true:
+
+| Condition | Artifact Missing | Flag Present | Mode |
+|-----------|------------------|--------------|------|
+| No system spec | SYSTEM_SPEC.md | - | Interactive system spec creation |
+| No feature spec | FEATURE_SPEC.md | - | Interactive feature spec creation |
+| Explicit request | - | `--interactive` | Interactive feature spec creation |
+| Both flags | - | `--interactive --pause-after=alex` | Interactive, then pause |
+
+### 4.2 Session Flow
+
+```
+User: /implement-feature "user-auth"
+      │
+      ▼
+┌─────────────────────────────────────────┐
+│ Check: SYSTEM_SPEC.md exists?           │
+│   No  → Enter Interactive System Spec   │
+│   Yes → Continue                        │
+└─────────────────────────────────────────┘
+      │
+      ▼
+┌─────────────────────────────────────────┐
+│ Check: FEATURE_SPEC.md exists?          │
+│   No  → Enter Interactive Feature Spec  │
+│ Check: --interactive flag?              │
+│   Yes → Enter Interactive Feature Spec  │
+│   No  → Run autonomous Alex             │
+└─────────────────────────────────────────┘
+      │
+      ▼
+┌─────────────────────────────────────────┐
+│ INTERACTIVE SESSION                     │
+│ 1. Alex: "Describe what you want..."    │
+│ 2. User: provides description           │
+│ 3. Alex: asks clarifying questions      │
+│ 4. User: answers questions              │
+│ 5. Alex: drafts spec section            │
+│ 6. User: approves / requests changes    │
+│ 7. Repeat 3-6 until spec complete       │
+│ 8. Alex: writes final spec file         │
+└─────────────────────────────────────────┘
+      │
+      ▼
+┌─────────────────────────────────────────┐
+│ Exit: --pause-after=alex present?       │
+│   Yes → Stop for review                 │
+│   No  → Continue pipeline (Cass, etc.)  │
+└─────────────────────────────────────────┘
+```
+
+### 4.3 Conversational Phases
+
+**Phase 1: Context Gathering**
+- Alex reads system spec (if exists), business context, and any existing feature artifacts
+- Alex asks: "Describe the feature you want to build. What problem does it solve and for whom?"
+- User provides initial description
+- Alex acknowledges understanding and identifies gaps
+
+**Phase 2: Clarifying Questions**
+- Alex asks 2-4 targeted questions based on:
+  - Missing information relative to FEATURE_SPEC template sections
+  - Ambiguities in user description
+  - Potential conflicts with system spec
+- Questions are asked one batch at a time, not all at once
+- User answers in natural language
+- Alex confirms understanding before proceeding
+
+**Phase 3: Iterative Drafting**
+- Alex drafts spec sections incrementally (Intent first, then Scope, etc.)
+- After each section, Alex presents draft and asks: "Does this capture your intent? Any changes?"
+- User can: approve, request changes, or add context
+- Alex revises based on feedback
+- Process continues until all relevant sections are complete
+
+**Phase 4: Finalization**
+- Alex presents complete spec summary
+- User gives final approval
+- Alex writes FEATURE_SPEC.md to disk
+- Alex produces handoff summary as normal
+
+### 4.4 Session Commands
+
+During interactive session, user can issue commands:
+
+| Command | Effect |
+|---------|--------|
+| `/approve` or `yes` | Approve current draft, proceed to next section |
+| `/change <feedback>` | Request specific changes to current section |
+| `/skip` | Skip current section (mark as "TBD" in spec) |
+| `/restart` | Restart current section from scratch |
+| `/abort` | Exit interactive mode without writing spec |
+| `/done` | Finalize spec even if some sections incomplete |
+
+---
+
+## 5. Dependencies
+
+### System Dependencies
+- Requires SKILL.md update to support `--interactive` flag parsing
+- Requires change to pipeline routing logic (Steps 2-3 in SKILL.md)
+- Uses existing Task tool infrastructure for Alex agent spawning
+
+### Artifact Dependencies
+- Reads: `.blueprint/system_specification/SYSTEM_SPEC.md` (if exists)
+- Reads: `.business_context/` directory
+- Reads: `.blueprint/templates/FEATURE_SPEC.md` (for section guidance)
+- Writes: `{FEAT_DIR}/FEATURE_SPEC.md`
+- Writes: `{FEAT_DIR}/handoff-alex.md`
+
+### Configuration Dependencies
+- No new config files required
+- May optionally respect `feedback-config.json` thresholds for self-assessment
+
+---
+
+## 6. Rules & Constraints
+
+### Session Rules
+1. **Single active session:** Only one interactive session can run at a time
+2. **In-memory state:** Session state is not persisted; if user aborts mid-session, no partial spec is saved
+3. **Timeout handling:** No explicit timeout; session continues until user approves or aborts
+4. **No parallelism:** Interactive mode is inherently sequential
+
+### Spec Quality Rules
+1. **Template alignment:** Final spec must include at minimum: Intent, Scope, and Actors sections
+2. **Flagged assumptions:** All inferences must be explicitly marked as assumptions
+3. **System spec alignment:** Feature spec must not contradict system spec boundaries
+
+### Pipeline Integration Rules
+1. **Gate preservation:** System spec gate still applies - if no system spec, must create one first
+2. **Handoff required:** Interactive Alex still produces `handoff-alex.md` for Cass
+3. **Queue update:** On completion, queue is updated as normal (feature moves to cassQueue)
+4. **History recording:** Interactive sessions are recorded in pipeline-history.json with `mode: "interactive"`
+
+---
+
+## 7. Non-Functional Considerations
+
+### Usability
+- Alex's questions should be clear and actionable (not open-ended)
+- Each conversational turn should be concise (under 200 words for Alex)
+- Progress indication: show which sections are complete vs remaining
+
+### Performance
+- No additional file I/O until final spec write
+- No external API calls beyond existing Claude conversation
+
+### Auditability
+- Final spec includes note: "Created via interactive session"
+- History entry includes: question count, revision count, session duration
+
+---
+
+## 8. Assumptions & Open Questions
+
+### Assumptions
+1. Users prefer conversational UX over form-filling for spec creation
+2. 2-4 clarifying questions is sufficient for most features
+3. Iterative section-by-section drafting is more effective than full-spec-at-once
+4. Users will invoke interactive mode for ambiguous or novel features
+
+### Open Questions
+1. **Q:** Should interactive mode support resumption if session is interrupted?
+   - **Tentative:** No, keep simple for v1. User can restart if interrupted.
+
+2. **Q:** Should Alex offer to create SYSTEM_SPEC.md interactively if missing?
+   - **Tentative:** Yes, same interactive flow applies.
+
+3. **Q:** Should there be a `--no-interactive` flag to force autonomous mode even when spec is missing?
+   - **Tentative:** No, the auto-trigger is a reasonable default. Users can create empty placeholder specs to skip.
+
+---
+
+## 9. Story Themes
+
+The following themes will guide user story creation:
+
+1. **Flag Parsing & Routing** - Handling `--interactive` flag and auto-detection logic
+2. **Conversational Session Management** - Session lifecycle, commands, state tracking
+3. **Iterative Spec Drafting** - Question flow, section drafting, revision handling
+4. **Pipeline Integration** - Queue updates, history recording, downstream handoff
+5. **Error & Edge Cases** - Abort handling, incomplete specs, timeout scenarios
+
+---
+
+## 10. Design Tensions & Trade-offs
+
+| Tension | Resolution |
+|---------|------------|
+| **Autonomy vs Control:** Alex's value is autonomous coherence enforcement, but interactive mode prioritizes user control | Interactive mode is opt-in/auto-trigger, not default. Alex still enforces coherence through questions and flagging, just collaboratively. |
+| **Speed vs Quality:** Interactive mode is slower than autonomous | Users self-select: clear requirements = autonomous mode; unclear requirements = interactive mode. Net quality improvement expected. |
+| **Simplicity vs Persistence:** Session state could be persisted for resumption | V1 keeps state in-memory for simplicity. Persistence is a future enhancement if users request it. |
+| **Single agent vs Multi-agent:** Could extend interactive mode to all agents | Scoped to Alex for v1. Alex is the upstream bottleneck; downstream agents benefit from clearer specs without needing interactivity. |
+
+---
+
+## Change Log
+
+| Date | Change | Reason |
+|------|--------|--------|
+| 2026-02-26 | Initial feature specification | Define interactive Alex mode for collaborative spec creation |

package/.blueprint/features/feature_interactive-alex/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,69 @@
+# Implementation Plan: Interactive Alex
+
+## Summary
+
+Create `src/interactive.js` module implementing a state machine for interactive spec creation sessions. The module exports functions for flag parsing, mode detection, session lifecycle management, and pipeline integration. SKILL.md routing logic will be updated to check for `--interactive` flag and missing specs, delegating to the new module.
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/interactive.js` | Create | Session state machine and command handlers |
+| `SKILL.md` | Modify | Add `--interactive` flag docs, update routing logic |
+| `src/orchestrator.js` | Modify | Add interactive mode history fields |
+| `src/history.js` | Modify | Support `mode: "interactive"` and session metrics |
+
+## Implementation Steps
+
+1. **Create `src/interactive.js` with core exports**
+   - `parseFlags(args)` - Extract `--interactive` and `--pause-after` flags
+   - `shouldEnterInteractiveMode(flags, hasSystemSpec, hasFeatureSpec)` - Routing logic
+   - Export constants: `SESSION_STATES`, `SECTION_ORDER`, `MIN_REQUIRED_SECTIONS`
+
+2. **Implement session state machine**
+   - States: `idle` → `gathering` → `questioning` → `drafting` → `finalizing`
+   - `createSession(target)` - Initialize session for 'system' or 'feature' spec
+   - `getSessionProgress(session)` - Return complete vs remaining section counts
+
+3. **Implement command handlers**
+   - `handleCommand(session, command)` - Route `/approve`, `/change`, `/skip`, `/restart`, `/abort`, `/done`
+   - Each handler mutates session state and returns next action indicator
+   - `/change <feedback>` increments `revisionCount`, stores feedback
+
+4. **Implement section drafting flow**
+   - `getNextSection(session)` - Return next section to draft based on `SECTION_ORDER`
+   - `markSectionComplete(session, section)` - Update section status
+   - `markSectionTBD(session, section)` - Mark skipped sections
+
+5. **Implement context gathering**
+   - `gatherContext(session)` - Read system spec, business context, templates
+   - `identifyGaps(session, userDescription)` - Return 2-4 information gaps
+   - `generateQuestions(gaps)` - Produce actionable questions
+
+6. **Implement finalization**
+   - `canFinalize(session)` - Check if Intent, Scope, Actors are complete/TBD
+   - `generateSpec(session)` - Produce spec content with TBD markers and note
+   - `writeSpec(session, outputPath)` - Write FEATURE_SPEC.md or SYSTEM_SPEC.md
+
+7. **Implement handoff generation**
+   - `generateHandoff(session)` - Produce handoff-alex.md content
+   - Include: key decisions, files created, question/revision counts
+
+8. **Update history.js for interactive metrics**
+   - Add `mode`, `questionCount`, `revisionCount`, `sessionDurationMs` fields
+   - Update `recordEntry()` to accept interactive session data
+
+9. **Update SKILL.md routing logic**
+   - Document `--interactive` flag in usage section
+   - Add conditional check after system spec gate: if interactive mode, enter session loop
+   - On session complete, continue to downstream agents or pause
+
+10. **Wire up orchestrator queue transitions**
+    - Ensure `moveToNextStage()` works with interactive completion
+    - No structural changes needed, just ensure integration works
+
+## Risks/Questions
+
+- **Token limits**: Interactive session loop may accumulate context. Consider clearing conversation history between sections if Claude context fills up.
+- **Testing gaps**: Current tests use inline stubs. After implementation, update tests to import from `src/interactive.js` directly.
+- **Word count enforcement**: The 200-word limit for Alex responses is a prompt constraint, not code-enforced. Document this in SKILL.md.

package/.blueprint/features/feature_interactive-alex/handoff-alex.md

@@ -0,0 +1,19 @@
+## Handoff Summary
+**For:** Cass
+**Feature:** interactive-alex
+
+### Key Decisions
+- Interactive mode triggers automatically when specs are missing, or explicitly via `--interactive` flag
+- Session flow: context gathering → clarifying questions → iterative drafting → finalization
+- In-memory state only (no persistence for v1)
+- Supports both SYSTEM_SPEC.md and FEATURE_SPEC.md creation
+- Integrates with existing `--pause-after=alex` for exit control
+
+### Files Created
+- .blueprint/features/feature_interactive-alex/FEATURE_SPEC.md
+
+### Open Questions
+- None - all resolved in spec
+
+### Critical Context
+Focus stories on: flag parsing/routing, conversational session management, iterative spec drafting, pipeline integration. The feature modifies SKILL.md routing and adds a new interaction pattern while keeping downstream agents (Cass, Nigel, Codey) unchanged.

package/.blueprint/features/feature_interactive-alex/handoff-cass.md

@@ -0,0 +1,21 @@
+## Handoff Summary
+**For:** Nigel
+**Feature:** interactive-alex
+
+### Key Decisions
+- Split into 5 stories covering distinct concerns: routing, session lifecycle, drafting, pipeline integration, system spec creation
+- Each story has 5-7 testable acceptance criteria in Given/When/Then format
+- Focused on observable behavior and user commands
+
+### Files Created
+- story-flag-routing.md - `--interactive` flag parsing and auto-detection
+- story-session-lifecycle.md - Session commands (/approve, /change, /skip, /restart, /abort, /done)
+- story-iterative-drafting.md - Context gathering, questions, section drafting
+- story-pipeline-integration.md - Spec output, handoff, queue, history
+- story-system-spec-creation.md - Interactive SYSTEM_SPEC.md creation when missing
+
+### Open Questions
+- None
+
+### Critical Context
+Tests should focus on SKILL.md routing logic and the new `src/interactive.js` module. Mock the conversation loop for unit tests; the iterative drafting can use state machine patterns.

package/.blueprint/features/feature_interactive-alex/handoff-nigel.md

@@ -0,0 +1,19 @@
+## Handoff Summary
+**For:** Codey
+**Feature:** interactive-alex
+
+### Key Decisions
+- 29 tests covering all 5 stories with 100% AC coverage
+- Tests use Node.js built-in test runner (node:test)
+- Mock-based testing for session state machine and routing
+- State machine pattern for session lifecycle
+
+### Files Created
+- test/artifacts/feature_interactive-alex/test-spec.md
+- test/feature_interactive-alex.test.js
+
+### Open Questions
+- None
+
+### Critical Context
+Create `src/interactive.js` with session state machine (idle → gathering → questioning → drafting → finalizing). Update SKILL.md routing logic to check for `--interactive` flag and missing specs. All tests currently pass with stubs - implement the actual logic.

package/.blueprint/features/feature_interactive-alex/story-flag-routing.md

@@ -0,0 +1,54 @@
+# User Story: Flag Parsing & Mode Routing
+
+## Story
+
+**As a** developer using murmur8,
+**I want** the `/implement-feature` command to detect when interactive mode is needed and route accordingly,
+**so that** I get a collaborative spec experience for new/unclear features without manual flag management.
+
+## Acceptance Criteria
+
+### AC-1: Explicit Interactive Flag
+
+**Given** a user invokes `/implement-feature "my-feature" --interactive`
+**When** the command parses flags
+**Then** interactive mode is activated regardless of existing spec files
+
+### AC-2: Auto-Detect Missing System Spec
+
+**Given** a user invokes `/implement-feature "my-feature"` without `--interactive`
+**And** `.blueprint/system_specification/SYSTEM_SPEC.md` does not exist
+**When** the pipeline routing logic runs
+**Then** interactive mode is activated for system spec creation
+
+### AC-3: Auto-Detect Missing Feature Spec
+
+**Given** a user invokes `/implement-feature "my-feature"` without `--interactive`
+**And** `SYSTEM_SPEC.md` exists
+**And** `.blueprint/features/feature_my-feature/FEATURE_SPEC.md` does not exist
+**When** the pipeline routing logic runs
+**Then** interactive mode is activated for feature spec creation
+
+### AC-4: Autonomous Mode When Specs Exist
+
+**Given** a user invokes `/implement-feature "my-feature"` without `--interactive`
+**And** both `SYSTEM_SPEC.md` and `FEATURE_SPEC.md` exist
+**When** the pipeline routing logic runs
+**Then** Alex runs in autonomous (non-interactive) mode
+
+### AC-5: Combined Flags
+
+**Given** a user invokes `/implement-feature "my-feature" --interactive --pause-after=alex`
+**When** the command parses flags
+**Then** interactive mode is activated
+**And** the pipeline will pause after Alex completes (before Cass)
+
+## Out of Scope
+
+- `--no-interactive` flag to force autonomous mode (users can create placeholder specs)
+- Interactive modes for agents other than Alex
+- Flag validation errors (handled by existing CLI parsing)
+
+## References
+
+- Feature Spec: `.blueprint/features/feature_interactive-alex/FEATURE_SPEC.md` (Section 4.1)