murmur8 3.5.0

package/.blueprint/features/feature_template-extraction/FEATURE_SPEC.md

@@ -0,0 +1,134 @@
+# Feature Specification — Template Extraction
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Agent specs contain verbose template sections and examples (~70-100 lines each)
+- Templates are reference material, not needed for every invocation
+- Extracting templates to separate files reduces base agent spec size
+- Agents can read templates only when creating new artifacts
+
+---
+
+## 2. Scope
+### In Scope
+- Extract user story template from Cass spec → `.blueprint/templates/STORY_TEMPLATE.md`
+- Extract test template from Nigel spec → `.blueprint/templates/TEST_TEMPLATE.md`
+- Extract interaction templates from agent specs
+- Trim workflow sections to concise bullet points
+- Update agent specs to reference templates by path
+
+### Out of Scope
+- Changing template content
+- Removing templates entirely
+- Creating new templates
+
+---
+
+## 3. Actors Involved
+
+| Actor | Template Used | When |
+|-------|--------------|------|
+| Cass | STORY_TEMPLATE.md | When writing new stories |
+| Nigel | TEST_TEMPLATE.md | When writing new tests |
+| Codey | None extracted | Workflow condensed only |
+| Alex | FEATURE_SPEC.md (existing) | When writing feature specs |
+
+---
+
+## 4. Behaviour Overview
+
+**Happy path:**
+1. Agent receives task prompt
+2. Agent reads slim spec (templates removed)
+3. When creating artifact, agent reads relevant template file
+4. Agent uses template structure for output
+
+**Content to extract:**
+
+| From | Content | To |
+|------|---------|-----|
+| AGENT_BA_CASS.md | User story template (~70 lines) | STORY_TEMPLATE.md |
+| AGENT_TESTER_NIGEL.md | Test output format (~30 lines) | TEST_TEMPLATE.md |
+| All agents | Verbose workflow steps | Condensed to ~10 bullets each |
+
+**Key outcomes:**
+- ~800 fewer tokens in agent specs
+- Templates still available when needed
+- Specs more focused on behaviour, less on format
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- No state changes
+- Templates are static reference files
+- No pipeline flow changes
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description |
+|------|-------------|
+| Reference not inline | Agent specs reference templates, don't inline them |
+| Read when needed | Agents read templates only when creating that artifact type |
+| Templates are examples | Templates show structure, not mandatory content |
+
+---
+
+## 7. Dependencies
+
+- `.blueprint/templates/` directory (already exists)
+- Agent spec files updated
+- SKILL.md prompts may need to specify "read template from X"
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Performance:** ~800 token reduction in agent specs
+- **Maintainability:** Templates can be updated independently of agent specs
+- **Clarity:** Agent specs focus on behaviour, templates on format
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- Agents can follow references to read template files
+- Templates are used infrequently enough that lazy loading is beneficial
+- Condensed workflow bullets provide sufficient guidance
+
+**Open Questions:**
+- Should templates be versioned separately from agent specs?
+- How much can workflow sections be condensed without losing clarity?
+
+---
+
+## 10. Impact on System Specification
+
+- Reinforces separation of concerns (behaviour vs format)
+- No contradiction with system spec
+- No system spec change required
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Story themes:**
+- Extract Cass story template to separate file
+- Extract Nigel test template to separate file
+- Condense workflow sections in all agent specs
+- Update agent specs to reference templates
+
+**Expected story boundaries:**
+- One story for template extraction
+- One story for workflow condensation
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|-----|------|--------|-----------|
+| 2026-02-25 | Initial spec | Token efficiency improvement | Claude |

package/.blueprint/features/feature_template-extraction/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,46 @@
+# Implementation Plan: Template Extraction
+
+## Summary
+
+Extract verbose template sections from AGENT_BA_CASS.md and AGENT_TESTER_NIGEL.md into standalone template files (STORY_TEMPLATE.md and TEST_TEMPLATE.md) in `.blueprint/templates/`. Update agent specs to reference templates by path and condense workflow sections to ~10 bullet points each. This reduces agent spec token count by ~800 tokens while keeping templates accessible when needed.
+
+## Files to Create/Modify
+
+| Action | File | Description |
+|--------|------|-------------|
+| Create | `.blueprint/templates/STORY_TEMPLATE.md` | User story template extracted from Cass spec (lines 180-252) |
+| Create | `.blueprint/templates/TEST_TEMPLATE.md` | Test output format guidance extracted from Nigel spec |
+| Modify | `.blueprint/agents/AGENT_BA_CASS.md` | Remove inline template, add reference, condense workflow |
+| Modify | `.blueprint/agents/AGENT_TESTER_NIGEL.md` | Add template reference, condense workflow section |
+
+## Implementation Steps
+
+1. **Create STORY_TEMPLATE.md** - Extract the user story template block (lines 180-252) from AGENT_BA_CASS.md into `.blueprint/templates/STORY_TEMPLATE.md`. Include the full markdown template with Screen [N], User story, Context/scope, Acceptance criteria, Session persistence, and Out of scope sections.
+
+2. **Create TEST_TEMPLATE.md** - Extract test output format guidance from AGENT_TESTER_NIGEL.md sections 3-5 (test design principles, AC mapping table format, traceability table format) into a standalone template.
+
+3. **Update Cass spec - Remove template** - Replace the inline user story template (lines 180-252) with a reference: `Read the user story template from: .blueprint/templates/STORY_TEMPLATE.md`
+
+4. **Update Cass spec - Condense workflow** - Simplify "Standard workflow" section (lines 127-177) from 5 detailed steps with sub-bullets to ~10 concise top-level bullets covering: understand, clarify, write story, document session, flag deferrals.
+
+5. **Update Nigel spec - Add template reference** - Add reference to TEST_TEMPLATE.md in the "Outputs you must produce" section for detailed format guidance.
+
+6. **Update Nigel spec - Condense workflow** - Simplify section 3 "Standard workflow" (lines 69-109) to ~10 concise bullets covering: understand, map ACs, write spec, write tests, traceability.
+
+7. **Preserve required sections** - Ensure both specs retain: YAML frontmatter, identity sections, job descriptions, input/output sections, collaboration notes, anti-patterns, GUARDRAILS.md reference.
+
+8. **Verify existing templates preserved** - Confirm FEATURE_SPEC.md and SYSTEM_SPEC.md remain unchanged in `.blueprint/templates/`.
+
+9. **Run tests** - Execute `node --test test/feature_template-extraction.test.js` to verify all 16 tests pass.
+
+10. **Manual verification** - Check that condensed workflow sections remain actionable and template references are clear paths.
+
+## Risks/Questions
+
+| Risk | Mitigation |
+|------|------------|
+| Condensed workflows lose critical guidance | Keep essential steps, move details to templates |
+| Test regex patterns may be too strict | Review test patterns if failures occur, adjust template content to match expected patterns |
+| Token savings may vary | Actual reduction depends on final content; ~800 is estimate |
+
+**Open question from spec:** Should templates be versioned separately? Recommendation: No, keep in same repo for now. Templates change rarely and should stay in sync with agent specs.

package/.blueprint/features/feature_upstream-summaries/FEATURE_SPEC.md

@@ -0,0 +1,150 @@
+# Feature Specification — Upstream Summaries
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Currently, downstream agents read full upstream artifacts (feature specs, stories, test specs)
+- Codey reads: feature spec + all stories + test spec + plan = potentially 1,000+ lines
+- Much of this content is not needed for the downstream task
+- Structured handoff summaries reduce input tokens by 30-50% for later stages
+
+---
+
+## 2. Scope
+### In Scope
+- Each agent produces a structured "Handoff Summary" at end of output
+- Downstream agents read summary + their direct inputs only
+- Summary format standardized across all agents
+
+### Out of Scope
+- Changing what agents produce (full artifacts still created)
+- Removing ability to read full upstream files if needed
+- Automated summary generation (agents write summaries manually)
+
+---
+
+## 3. Actors Involved
+
+| Actor | Produces Summary For | Reads Summary From |
+|-------|---------------------|-------------------|
+| Alex | Cass | N/A (first in chain) |
+| Cass | Nigel | Alex |
+| Nigel | Codey | Cass |
+| Codey | N/A (last in chain) | Nigel |
+
+---
+
+## 4. Behaviour Overview
+
+**Happy path:**
+1. Alex creates feature spec + writes handoff summary
+2. Cass reads Alex's summary (not full spec), writes stories + handoff summary
+3. Nigel reads Cass's summary + stories, writes tests + handoff summary
+4. Codey reads Nigel's summary + tests + plan, implements
+
+**Handoff summary format:**
+```markdown
+## Handoff Summary
+**For:** {Next Agent}
+**Feature:** {slug}
+
+### Key Decisions
+- {Decision 1}
+- {Decision 2}
+- {Decision 3}
+
+### Files Created
+- {path/to/file1.md}
+- {path/to/file2.md}
+
+### Open Questions
+- {Question if any, or "None"}
+
+### Critical Context
+{1-2 sentences of must-know information}
+```
+
+**Key outcomes:**
+- ~2,000-4,000 fewer tokens for Nigel and Codey stages
+- Faster downstream processing
+- Clearer handoffs between agents
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- Summaries are written to the feature directory
+- New file per stage: `{FEAT_DIR}/handoff-{agent}.md`
+- Pipeline reads summary file paths from queue
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description |
+|------|-------------|
+| Summary required | Every agent (except Codey-implement) must produce a handoff summary |
+| Max length | Summaries must be <30 lines |
+| No duplication | Don't repeat content that's in the main artifact |
+| Actionable | Focus on what downstream agent needs to know |
+
+---
+
+## 7. Dependencies
+
+- SKILL.md prompts updated to require summaries
+- SKILL.md prompts updated to read summaries instead of full upstream files
+- Queue may need to track summary file paths
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Performance:** 30-50% reduction in downstream agent input tokens
+- **Clarity:** Explicit handoffs improve traceability
+- **Overhead:** Small increase in upstream agent output (~30 lines)
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- Agents can write useful summaries
+- Summaries capture enough context for downstream success
+- Full files remain available if summary is insufficient
+
+**Open Questions:**
+- Should summaries be separate files or appended to main artifacts?
+- What happens if an agent needs info not in the summary?
+- Should the pipeline validate summary quality?
+
+---
+
+## 10. Impact on System Specification
+
+- Reinforces principle of explicit handoffs between agents
+- Adds new artifact type (handoff summaries) to pipeline
+- No contradiction with system spec
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Story themes:**
+- Define handoff summary format
+- Update Alex to produce summary
+- Update Cass to read summary + produce summary
+- Update Nigel to read summary + produce summary
+- Update Codey to read summary
+- Update SKILL.md with new prompt structure
+
+**Expected story boundaries:**
+- One story for summary format definition
+- One story per agent update
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|-----|------|--------|-----------|
+| 2026-02-25 | Initial spec | Token efficiency improvement | Claude |

package/.blueprint/features/feature_upstream-summaries/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,70 @@
+# Implementation Plan: Upstream Summaries
+
+## Summary
+
+Add structured "Handoff Summary" artifacts to the agent pipeline. Each agent (Alex, Cass, Nigel) will produce a `handoff-{agent}.md` file containing key decisions, files created, open questions, and critical context. SKILL.md prompts will be updated to instruct agents to write summaries and read upstream summaries instead of full artifacts.
+
+---
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `SKILL.md` | Modify | Update Alex/Cass/Nigel prompts to require handoff summary output |
+| `SKILL.md` | Modify | Update Cass/Nigel/Codey prompts to read upstream handoff summary |
+| `SKILL.md` | Modify | Add `{HANDOFF_*}` path variables to Paths table |
+| `src/handoff.js` | Create | Helper functions to parse/validate handoff summary format |
+
+---
+
+## Implementation Steps
+
+1. **Add handoff path variables to SKILL.md**
+   - Add `{HANDOFF_ALEX}`, `{HANDOFF_CASS}`, `{HANDOFF_NIGEL}` to Paths table
+   - Pattern: `{FEAT_DIR}/handoff-{agent}.md`
+   - Tests: T-3.4, T-4.2
+
+2. **Create src/handoff.js helper module**
+   - Export `parseHandoffSummary(content)` function matching test implementation
+   - Export `validateHandoffSummary(content)` for line count and format checks
+   - Export `extractSection(content, sectionName)` for parsing sections
+   - Tests: T-1.1 through T-1.7, T-2.1 through T-2.3
+
+3. **Update Alex prompt in SKILL.md (Step 6)**
+   - Add output: write `{FEAT_DIR}/handoff-alex.md`
+   - Add summary format template to prompt
+   - Specify: `**For:** Cass`, feature slug, key decisions, files created
+   - Tests: T-3.1
+
+4. **Update Cass prompt in SKILL.md (Step 7)**
+   - Add input: read `{FEAT_DIR}/handoff-alex.md` instead of full feature spec
+   - Add output: write `{FEAT_DIR}/handoff-cass.md`
+   - Specify: `**For:** Nigel`
+   - Tests: T-3.2
+
+5. **Update Nigel prompt in SKILL.md (Step 8)**
+   - Add input: read `{FEAT_DIR}/handoff-cass.md` instead of full stories
+   - Add output: write `{FEAT_DIR}/handoff-nigel.md`
+   - Specify: `**For:** Codey`
+   - Tests: T-3.3
+
+6. **Update Codey prompts in SKILL.md (Steps 9, 10)**
+   - Add input: read `{FEAT_DIR}/handoff-nigel.md` instead of full test spec
+   - No output summary (last in chain)
+   - Tests: T-4.1
+
+7. **Update queue structure for handoff paths (optional)**
+   - Add `upstreamSummary` field to queue entries if needed for recovery
+   - Tests: T-4.1
+
+8. **Run tests and verify**
+   - Execute `node --test test/feature_upstream-summaries.test.js`
+   - All 15 tests should pass
+
+---
+
+## Risks/Questions
+
+- **Backward compatibility**: Existing features without handoff files may break if prompts strictly require them. Mitigation: Add "if exists" fallback in prompts.
+- **Token savings**: Actual savings depend on how well agents write concise summaries. May need guidance on brevity.
+- **Full file access**: Spec says full files remain available. Consider adding "For additional context, see: {path}" to summaries.

package/.blueprint/features/feature_validate-command/FEATURE_SPEC.md

@@ -0,0 +1,209 @@
+# Feature Specification — Validate Command
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+The `murmur8 validate` command provides pre-flight checks to ensure the environment is correctly configured before running the `/implement-feature` pipeline. This addresses a common failure mode where users invoke the pipeline without required artifacts in place, leading to mid-pipeline failures that are harder to diagnose and recover from.
+
+**Problem being addressed:**
+- Pipeline failures mid-execution due to missing system spec, agent files, or skills
+- Poor developer experience when prerequisites are unclear
+- No visibility into "readiness" state before committing to a full pipeline run
+
+**User need:**
+- Developers need confidence that their project is correctly set up before invoking the pipeline
+- Teams need actionable guidance when setup is incomplete
+
+**How this supports the system purpose:**
+- Aligns with the system's goal of reducing ambiguity and drift by enforcing explicit prerequisites
+- Supports the "System spec gate" rule defined in the system specification (Section 7)
+- Reduces failed pipeline runs by catching issues early
+
+---
+
+## 2. Scope
+
+### In Scope
+- New CLI command `murmur8 validate` accessible via `bin/cli.js`
+- Check: System spec exists at `.blueprint/system_specification/SYSTEM_SPEC.md`
+- Check: Required directories exist (`.blueprint/`, `.business_context/`, `.claude/commands/`)
+- Check: Agent spec files exist in `.blueprint/agents/` (AGENT_SPECIFICATION_ALEX.md, AGENT_BA_CASS.md, AGENT_TESTER_NIGEL.md, AGENT_DEVELOPER_CODEY.md)
+- Check: Business context directory has at least one file (not empty)
+- Check: Skills installed (`.claude/commands/implement-feature.md` exists)
+- Check: Node.js version meets requirements (>=18)
+- Success output: Print success message with checkmarks for each passed check
+- Failure output: Print what is missing with actionable fix suggestions for each failed check
+- Exit code: 0 on all checks pass, non-zero on any failure
+
+### Out of Scope
+- Validation of file contents (e.g., SYSTEM_SPEC.md is well-formed)
+- Validation of business context quality or completeness
+- Automatic remediation (the command reports issues, not fixes them)
+- Network checks (e.g., can reach skills.sh)
+- Validation of queue state or in-progress features
+
+---
+
+## 3. Actors Involved
+
+### Human User (Developer)
+- **Can do:** Invoke `murmur8 validate` to check project readiness
+- **Can do:** Review validation output to understand what is missing
+- **Cannot do:** Auto-fix issues via this command (must run `init` or manually create files)
+
+---
+
+## 4. Behaviour Overview
+
+**Happy-path behaviour:**
+1. User runs `murmur8 validate` in a project directory
+2. Command performs all checks in sequence
+3. Each check prints a status line (checkmark for pass, X for fail)
+4. If all checks pass, prints overall success message and exits with code 0
+
+**Failure behaviour:**
+1. User runs `murmur8 validate` in an incomplete project
+2. Command performs all checks in sequence
+3. Failed checks print X with a description of what is missing
+4. After all checks, failed items include actionable fix suggestions (e.g., "Run `murmur8 init` to create .blueprint directory")
+5. Command exits with non-zero exit code
+
+**User-visible outcomes:**
+- Clear, scannable output showing pass/fail status for each prerequisite
+- Actionable guidance for resolving failures
+- Machine-parseable exit code for scripting/CI integration
+
+---
+
+## 5. State & Lifecycle Interactions
+
+This feature is **state-inspecting only**. It does not create, transition, or modify any system state.
+
+- **States inspected:** File system state (existence of files/directories), Node.js runtime version
+- **States entered:** None
+- **States exited:** None
+- **States modified:** None
+
+The command is idempotent and safe to run repeatedly without side effects.
+
+---
+
+## 6. Rules & Decision Logic
+
+### R1: Directory Existence Check
+- **Description:** Verify required directories exist
+- **Inputs:** Directory paths (`.blueprint/`, `.business_context/`, `.claude/commands/`)
+- **Outputs:** Pass/fail for each directory
+- **Deterministic:** Yes
+
+### R2: System Spec Existence Check
+- **Description:** Verify SYSTEM_SPEC.md exists at expected path
+- **Inputs:** Path `.blueprint/system_specification/SYSTEM_SPEC.md`
+- **Outputs:** Pass/fail
+- **Deterministic:** Yes
+
+### R3: Agent Specs Existence Check
+- **Description:** Verify all four agent specification files exist
+- **Inputs:** Paths in `.blueprint/agents/` (AGENT_SPECIFICATION_ALEX.md, AGENT_BA_CASS.md, AGENT_TESTER_NIGEL.md, AGENT_DEVELOPER_CODEY.md)
+- **Outputs:** Pass/fail, listing any missing files
+- **Deterministic:** Yes
+
+### R4: Business Context Non-Empty Check
+- **Description:** Verify `.business_context/` contains at least one file
+- **Inputs:** Directory listing of `.business_context/`
+- **Outputs:** Pass/fail
+- **Deterministic:** Yes
+
+### R5: Skills Installed Check
+- **Description:** Verify implement-feature skill is installed
+- **Inputs:** Path `.claude/commands/implement-feature.md`
+- **Outputs:** Pass/fail
+- **Deterministic:** Yes
+
+### R6: Node.js Version Check
+- **Description:** Verify Node.js version is 18 or higher
+- **Inputs:** `process.version`
+- **Outputs:** Pass/fail with current version
+- **Deterministic:** Yes
+
+### R7: Exit Code Logic
+- **Description:** Return exit code based on overall result
+- **Inputs:** All check results
+- **Outputs:** Exit code 0 if all pass, exit code 1 if any fail
+- **Deterministic:** Yes
+
+---
+
+## 7. Dependencies
+
+### System Components
+- `fs` module for file system checks
+- `process.version` for Node.js version check
+- CLI routing in `bin/cli.js`
+
+### Technical Dependencies
+- Node.js >= 18 (the check itself should work on lower versions to report the failure)
+
+---
+
+## 8. Non-Functional Considerations
+
+### Performance
+- All checks are local file system operations; should complete in < 100ms
+
+### Error Tolerance
+- Command should not throw exceptions; all checks should be wrapped to handle missing paths gracefully
+
+### User Experience
+- Output should be colorized if terminal supports it (green checkmarks, red X marks)
+- Output should be readable in non-color terminals (using ASCII fallback)
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+- The four agent spec files have fixed names matching current convention
+- `.business_context/` having any file (including README.md) counts as non-empty
+- The Node.js version check should report failure but not crash on old versions
+
+### Open Questions
+- Should there be a `--json` flag for machine-readable output?
+- Should there be a `--fix` flag that runs `init` if missing? (Deferred - out of scope)
+
+---
+
+## 10. Impact on System Specification
+
+This feature **reinforces** existing system assumptions:
+- Validates the prerequisites implied by "System spec gate" rule in Section 7
+- Aligns with system boundary definition (CLI tooling in scope)
+- Consistent with existing command patterns (`init`, `update`, `queue`)
+
+No contradictions or tensions with the current system specification.
+
+---
+
+## 11. Handover to BA (Cass)
+
+### Story Themes
+1. **Core validation flow** - User runs validate and sees results
+2. **Success path** - All checks pass, user sees green checkmarks
+3. **Failure path with guidance** - Checks fail, user sees actionable fixes
+4. **Node.js version edge case** - Running on unsupported Node version
+
+### Expected Story Boundaries
+- Each check type could be a separate acceptance criterion within a single story
+- Success/failure output formatting is a story concern
+- Exit codes are a story concern (affects CI integration)
+
+### Areas Needing Careful Story Framing
+- The distinction between "check failed" and "command error" (the command itself should not fail/throw, even if checks fail)
+- How to phrase fix suggestions to be helpful without being prescriptive
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|------|--------|--------|-----------|
+| 2026-02-24 | Initial feature specification | New feature request for pre-flight validation | Alex |

package/.blueprint/features/feature_validate-command/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,59 @@
+# Implementation Plan — Validate Command
+
+## Summary
+
+Implement a new `murmur8 validate` CLI command that performs pre-flight checks for directory existence, file presence, and Node.js version. The command outputs pass/fail status for each check with colorized indicators, provides actionable fix suggestions for failures, and returns appropriate exit codes (0 for success, 1 for failure).
+
+---
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `src/validate.js` | Create | Core validation logic with `validate()`, `formatOutput()`, and `checkNodeVersion()` exports |
+| `src/index.js` | Modify | Export validate module for library consumers |
+| `bin/cli.js` | Modify | Add `validate` command routing |
+
+---
+
+## Implementation Steps
+
+1. **Create `src/validate.js` with check functions**
+   - Implement `checkDirectories()` for `.blueprint/`, `.business_context/`, `.claude/commands/`
+   - Implement `checkSystemSpec()` for `.blueprint/system_specification/SYSTEM_SPEC.md`
+   - Implement `checkAgentSpecs()` for the four agent files in `.blueprint/agents/`
+   - Implement `checkBusinessContext()` to verify directory is non-empty
+   - Implement `checkSkillsInstalled()` for `.claude/commands/implement-feature.md`
+   - Implement `checkNodeVersion()` exported separately for tests, parsing `process.version`
+
+2. **Implement main `validate()` function**
+   - Run all checks sequentially, collecting results in an array
+   - Each check returns `{ name, passed, message, fix?, detectedVersion? }`
+   - Compute `success` (all passed) and `exitCode` (0 or 1)
+   - Return `{ success, exitCode, checks }`
+
+3. **Implement `formatOutput()` function**
+   - Accept result object and color flag (detect via `process.stdout.isTTY`)
+   - Use `✓`/`✗` for color terminals, `[PASS]`/`[FAIL]` for ASCII fallback
+   - Apply green/red ANSI codes when color is enabled
+   - Include fix suggestions after failed checks
+   - Print overall success/failure summary at end
+
+4. **Add CLI routing in `bin/cli.js`**
+   - Import `validate` and `formatOutput` from `src/validate.js`
+   - Add `validate` command that runs validation, prints output, and calls `process.exit(result.exitCode)`
+
+5. **Export from `src/index.js`**
+   - Add `validate` to module exports for programmatic usage
+
+6. **Run tests and iterate**
+   - Execute `node --test test/feature_validate-command.test.js`
+   - Fix any failing assertions
+
+---
+
+## Risks/Questions
+
+- **Color detection**: Tests mock TTY state; implementation should use `process.stdout.isTTY` or accept a parameter for testability
+- **Agent file names**: Tests expect exact names (AGENT_SPECIFICATION_ALEX.md, AGENT_BA_CASS.md, AGENT_TESTER_NIGEL.md, AGENT_DEVELOPER_CODEY.md) - verify these match production
+- **Node version parsing**: Use `parseInt(process.version.slice(1).split('.')[0], 10)` to extract major version safely