orchestr8 2.4.0 → 2.6.0

package/.blueprint/features/feature_pipeline-insights/story-trend-analysis.md

@@ -0,0 +1,78 @@
+# Story — Trend Analysis
+
+## User story
+
+As a developer, I want to track whether pipeline performance is improving or degrading over time so that I can understand the impact of changes and maintain development efficiency.
+
+---
+
+## Context / scope
+
+- User has accumulated sufficient history to compare earlier vs later runs
+- Analysis compares first half vs second half of history data
+- Requires minimum 6 runs to compute meaningful trends
+- This is a read-only analysis; no pipeline state is modified
+- Route: `orchestr8 insights` (trends section included by default)
+
+Per FEATURE_SPEC.md:Section 6 (Rule: Trend Analysis):
+- Improving: >10% better in second half
+- Degrading: >10% worse in second half
+- Stable: within 10% variance
+- Minimum data: 6 runs required
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Display success rate trend**
+- Given the history file contains at least 6 pipeline runs,
+- When the user runs `orchestr8 insights`,
+- Then the output includes a "Trends" section showing success rate trend as "improving", "stable", or "degrading".
+
+**AC-2 — Display duration trend**
+- Given the history file contains at least 6 pipeline runs,
+- When the user runs `orchestr8 insights`,
+- Then the output includes average duration trend as "improving" (faster), "stable", or "degrading" (slower).
+
+**AC-3 — Calculate trend by comparing halves**
+- Given the history contains N runs (where N >= 6),
+- When trend analysis is performed,
+- Then the first N/2 runs are compared against the last N/2 runs to determine trend direction.
+
+**AC-4 — Apply threshold for trend classification**
+- Given the percentage change between halves is calculated,
+- When classifying the trend,
+- Then >10% improvement shows "improving", >10% degradation shows "degrading", and within 10% shows "stable".
+
+**AC-5 — Generate recommendation for degrading trend**
+- Given either success rate or duration trend is "degrading",
+- When the analysis completes,
+- Then the output includes the recommendation: "Review recent changes to agent specifications or system spec".
+
+**AC-6 — Insufficient data for trends**
+- Given the history file contains fewer than 6 runs,
+- When trend analysis is attempted,
+- Then it is skipped with explanation: "Insufficient data for trend analysis. Need at least 6 runs."
+
+**AC-7 — Show percentage change**
+- Given trend analysis completes successfully,
+- When the output is displayed,
+- Then the percentage change for both success rate and duration is shown alongside the trend indicator.
+
+---
+
+## Out of scope
+
+- Sliding window trend analysis (uses fixed first-half/second-half)
+- Time-based trend analysis (e.g., last 30 days)
+- Per-stage trend analysis
+- Trend visualization or charting
+- Predictive modelling of future performance
+
+---
+
+## References
+
+- Feature spec: `.blueprint/features/feature_pipeline-insights/FEATURE_SPEC.md`
+- Upstream dependency: `.blueprint/features/feature_pipeline-history/FEATURE_SPEC.md`
+- System spec: `.blueprint/system_specification/SYSTEM_SPEC.md`

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 `orchestr8 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 `orchestr8 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 `orchestr8 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 `orchestr8 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 `orchestr8 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 `orchestr8 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 `orchestr8 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

package/.blueprint/features/feature_validate-command/story-failure-output.md

@@ -0,0 +1,61 @@
+# Story — Validation Failure Output
+
+## User story
+As a developer, I want to see what is missing and how to fix it when validation checks fail so that I can resolve issues and get my project ready for the pipeline.
+
+---
+
+## Context / scope
+- Developer using orchestr8 CLI
+- Project is missing one or more required artifacts
+- This story covers failure output and actionable guidance
+
+See feature spec: `.blueprint/features/feature_validate-command/FEATURE_SPEC.md`
+
+---
+
+## Acceptance criteria
+
+**AC-1 — X mark displayed for failed checks**
+- Given one or more required files/directories are missing,
+- When I run `orchestr8 validate`,
+- Then each failed check displays an X indicator.
+
+**AC-2 — Colorized failure output when supported**
+- Given my terminal supports color output,
+- When I run `orchestr8 validate` and checks fail,
+- Then X marks are displayed in red.
+
+**AC-3 — Description of what is missing**
+- Given a check fails,
+- When the status line is printed,
+- Then it includes a description of what is missing (e.g., "Missing: .blueprint/system_specification/SYSTEM_SPEC.md").
+
+**AC-4 — Actionable fix suggestions**
+- Given one or more checks fail,
+- When all checks have completed,
+- Then actionable fix suggestions are displayed:
+  - Missing `.blueprint/` directory: "Run `orchestr8 init` to initialize project"
+  - Missing agent specs: "Run `orchestr8 init` to create agent specification files"
+  - Missing skills: "Run `orchestr8 init` to install required skills"
+  - Empty business context: "Add at least one file to `.business_context/` directory"
+  - Node.js version: "Upgrade Node.js to version 18 or higher"
+
+**AC-5 — Exit code non-zero on failure**
+- Given one or more validation checks fail,
+- When the command completes,
+- Then the process exits with a non-zero exit code (1)
+- And this exit code can be used in scripts/CI pipelines to detect failures.
+
+**AC-6 — All checks still run on failure**
+- Given the first check fails,
+- When I run `orchestr8 validate`,
+- Then all remaining checks are still executed
+- And a complete picture of missing items is shown.
+
+---
+
+## Out of scope
+- `--fix` flag to automatically remediate issues
+- Prioritization of which issues to fix first
+- JSON output format (deferred)

package/.blueprint/features/feature_validate-command/story-node-version-check.md

@@ -0,0 +1,52 @@
+# Story — Node.js Version Check
+
+## User story
+As a developer, I want the validation to check my Node.js version so that I am warned before attempting to run the pipeline on an unsupported runtime.
+
+---
+
+## Context / scope
+- Developer using orchestr8 CLI
+- Node.js version may or may not meet minimum requirement (>=18)
+- This check should work even on older Node.js versions to report the issue
+
+See feature spec: `.blueprint/features/feature_validate-command/FEATURE_SPEC.md`
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Version check passes on Node 18+**
+- Given I am running Node.js version 18 or higher,
+- When I run `orchestr8 validate`,
+- Then the Node.js version check displays a pass indicator.
+
+**AC-2 — Version check fails on Node < 18**
+- Given I am running Node.js version lower than 18,
+- When I run `orchestr8 validate`,
+- Then the Node.js version check displays a fail indicator
+- And the current version is shown in the output.
+
+**AC-3 — Command does not crash on old Node**
+- Given I am running an older Node.js version,
+- When I run `orchestr8 validate`,
+- Then the command executes and reports the version failure
+- And the command does not throw a runtime exception.
+
+**AC-4 — Clear upgrade guidance**
+- Given the Node.js version check fails,
+- When fix suggestions are displayed,
+- Then guidance includes "Upgrade Node.js to version 18 or higher"
+- And the current detected version is shown.
+
+**AC-5 — Version detected from runtime**
+- Given I run `orchestr8 validate`,
+- When the Node.js version check executes,
+- Then the version is detected from `process.version` (not from package.json or external sources).
+
+---
+
+## Out of scope
+- Checking for specific minor/patch versions
+- Checking for Node.js feature availability beyond version number
+- nvm or version manager integration

package/.blueprint/features/feature_validate-command/story-run-validation.md

@@ -0,0 +1,59 @@
+# Story — Run Validation Command
+
+## User story
+As a developer, I want to run `orchestr8 validate` in my project directory so that I can check whether my environment is correctly configured before running the pipeline.
+
+---
+
+## Context / scope
+- Developer using orchestr8 CLI
+- Command can be run in any directory (initialized or not)
+- Route: `orchestr8 validate` via `bin/cli.js`
+- This is the primary entry point for the validate feature
+
+See feature spec: `.blueprint/features/feature_validate-command/FEATURE_SPEC.md`
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Command is available**
+- Given I have orchestr8 installed,
+- When I run `orchestr8 validate`,
+- Then the command executes without throwing an exception.
+
+**AC-2 — Checks execute in sequence**
+- Given I run `orchestr8 validate`,
+- When the command executes,
+- Then all validation checks are performed:
+  - Directory existence (`.blueprint/`, `.business_context/`, `.claude/commands/`)
+  - System spec existence (`.blueprint/system_specification/SYSTEM_SPEC.md`)
+  - Agent spec files existence (4 files in `.blueprint/agents/`)
+  - Business context non-empty check
+  - Skills installed check (`.claude/commands/implement-feature.md`)
+  - Node.js version check (>=18)
+
+**AC-3 — Each check produces a status line**
+- Given I run `orchestr8 validate`,
+- When each check completes,
+- Then a status line is printed showing pass or fail for that check.
+
+**AC-4 — Command completes without crashes**
+- Given any combination of missing/present files,
+- When I run `orchestr8 validate`,
+- Then the command completes gracefully (does not throw exceptions)
+- And all checks are wrapped to handle missing paths.
+
+**AC-5 — Idempotent execution**
+- Given I run `orchestr8 validate` multiple times,
+- When each execution completes,
+- Then no files are created, modified, or deleted
+- And each run produces the same output for the same state.
+
+---
+
+## Out of scope
+- Validation of file contents (e.g., SYSTEM_SPEC.md is well-formed)
+- Automatic remediation of issues
+- Network checks
+- Queue state validation

package/.blueprint/features/feature_validate-command/story-success-output.md

@@ -0,0 +1,50 @@
+# Story — Validation Success Output
+
+## User story
+As a developer, I want to see clear success indicators when all validation checks pass so that I have confidence my project is ready to run the pipeline.
+
+---
+
+## Context / scope
+- Developer using orchestr8 CLI
+- Project is fully initialized with all required artifacts
+- This story covers the happy path output formatting
+
+See feature spec: `.blueprint/features/feature_validate-command/FEATURE_SPEC.md`
+
+---
+
+## Acceptance criteria
+
+**AC-1 — Checkmark displayed for passed checks**
+- Given all required files and directories exist,
+- When I run `orchestr8 validate`,
+- Then each passed check displays a checkmark indicator.
+
+**AC-2 — Colorized output when supported**
+- Given my terminal supports color output,
+- When I run `orchestr8 validate` and checks pass,
+- Then checkmarks are displayed in green.
+
+**AC-3 — ASCII fallback for non-color terminals**
+- Given my terminal does not support color output,
+- When I run `orchestr8 validate`,
+- Then success indicators use ASCII-compatible characters
+- And output remains readable.
+
+**AC-4 — Overall success message**
+- Given all validation checks pass,
+- When the command completes,
+- Then an overall success message is printed indicating the project is ready.
+
+**AC-5 — Exit code zero on success**
+- Given all validation checks pass,
+- When the command completes,
+- Then the process exits with code 0
+- And this exit code can be used in scripts/CI pipelines.
+
+---
+
+## Out of scope
+- JSON output format (deferred)
+- Verbose mode with additional details