orchestr8 2.7.1 → 3.0.0

package/.blueprint/features/feature_parallel-preflight/FEATURE_SPEC.md

@@ -0,0 +1,141 @@
+# Feature Specification — Parallel Pre-flight Validation
+
+## 1. Feature Intent
+
+Validate that a batch of features is safe to run in parallel before execution begins. This prevents wasted resources from features that would fail due to conflicts, missing specs, or dependencies.
+
+**Problem:** Users can queue features for parallel execution without knowing if they'll conflict. Discovering issues mid-execution wastes time and creates cleanup work.
+
+**Solution:** Pre-flight validation that checks feature readiness, detects conflicts, and estimates scope before any worktrees are created.
+
+---
+
+## 2. Scope
+
+### In Scope
+- Check feature specs exist and are complete
+- Detect dependencies between features in batch
+- Detect file overlap from implementation plans
+- Estimate scope and warn about timeout risk
+- Integrate with existing dry-run flow
+
+### Out of Scope
+- Automatic dependency resolution
+- Automatic batching suggestions
+- Cross-repo validation
+
+---
+
+## 3. Behaviour Overview
+
+### Pre-flight Check Output
+
+```
+$ orchestr8 parallel feat-a feat-b feat-c --dry-run
+
+Pre-flight Validation
+=====================
+
+✓ feat-a: Spec complete, plan exists
+✓ feat-b: Spec complete, plan exists
+✗ feat-c: Missing FEATURE_SPEC.md
+
+Conflict Analysis
+=================
+
+⚠ File overlap detected:
+  • src/utils.js: feat-a, feat-b both modify
+  • bin/cli.js: feat-a, feat-c both modify
+
+Recommendation: Run feat-a alone, then feat-b + feat-c
+
+Scope Estimation
+================
+
+  Feature   | Stories | Tests | Est. Time
+  ----------|---------|-------|----------
+  feat-a    | 3       | 12    | ~15 min
+  feat-b    | 2       | 8     | ~10 min
+  feat-c    | 1       | 4     | ~5 min
+
+Total estimated: ~30 min (parallel: ~15 min)
+
+Proceed? [y/N]
+```
+
+### Validation Failures Block Execution
+
+```
+$ orchestr8 parallel feat-a feat-b
+
+Pre-flight Validation
+=====================
+
+✗ feat-a: Missing FEATURE_SPEC.md
+✗ feat-b: Missing user stories
+
+Cannot proceed. Run these commands first:
+  /implement-feature feat-a --pause-after=alex
+  /implement-feature feat-b --pause-after=cass
+```
+
+### Override with --skip-preflight
+
+```
+$ orchestr8 parallel feat-a feat-b --skip-preflight
+
+⚠ Skipping pre-flight validation (not recommended)
+
+Starting parallel pipelines...
+```
+
+---
+
+## 4. Implementation Notes
+
+### Validation Checks
+
+1. **Spec Completeness**
+   - FEATURE_SPEC.md exists and has required sections
+   - At least one story-*.md file exists
+   - Test file exists (optional - may be created by pipeline)
+
+2. **Dependency Detection**
+   - Parse feature specs for "depends_on" or similar markers
+   - Scan for references to other feature slugs
+   - Warn if features reference each other
+
+3. **File Overlap Detection**
+   - Parse IMPLEMENTATION_PLAN.md for "Files to Create/Modify" section
+   - Extract file paths from each feature's plan
+   - Flag any files that appear in multiple features
+
+4. **Scope Estimation**
+   - Count stories and acceptance criteria
+   - Count existing tests
+   - Use history averages to estimate duration
+
+### Integration Points
+
+- Called from `runParallel()` before worktree creation
+- Results displayed in dry-run output
+- Blocking by default, override with `--skip-preflight`
+
+---
+
+## 5. Test Themes
+
+- Detects missing feature specs
+- Detects missing stories
+- Detects file overlap from plans
+- Allows override with flag
+- Integrates with dry-run
+- Scope estimation uses history
+
+---
+
+## 6. Change Log
+
+| Date | Change | Reason |
+|------|--------|--------|
+| 2026-02-25 | Initial spec | Upfront validation for parallel safety |

package/.blueprint/prompts/codey-implement-runtime.md

@@ -11,7 +11,7 @@ Implement the feature according to the plan. Work incrementally, making tests pa
 
 ## Process (INCREMENTAL - one file at a time)
 
-1. Run tests first: node --test {TEST_FILE}
+1. Run tests using the project's test command (see `.claude/stack-config.json`)
 2. For each failing test group:
    a. Identify the minimal code needed
    b. Write or edit ONE file

package/.blueprint/prompts/nigel-runtime.md

@@ -17,7 +17,7 @@ Step 1: Write {TEST_DIR}/test-spec.md containing:
 - Key assumptions (bullet list)
 
 Step 2: Write {TEST_FILE} containing:
-- Executable tests (Jest or Node test runner)
+- Executable tests using the project's test runner (see `.claude/stack-config.json`)
 - One describe block per story
 - One test per acceptance criterion
 

package/.blueprint/ways_of_working/DEVELOPMENT_RITUAL.md

@@ -41,7 +41,7 @@ Before writing tests:
 [ ] Ambiguities identified
 [ ] Assumptions written down
 
-Before handover to Steve to pass to Claude:
+Before handover to the human to pass to Claude:
 [ ] Understanding summary written
 [ ] Test plan created
 [ ] Happy path tests written
@@ -50,7 +50,7 @@ Before handover to Steve to pass to Claude:
 [ ] Traceability table complete
 [ ] Open questions listed
 
-If any box is unchecked → raise it with Steve that its not ready to hand over. If all boxes are checked, let Steve know that its ready to handover to Claude. 
+If any box is unchecked → raise it with the human that its not ready to hand over. If all boxes are checked, let the human know that its ready to handover to Claude. 
 
 🧑‍💻 Developer CLI Ritual (Claude)
 Before coding:
@@ -64,7 +64,7 @@ During coding:
 [ ] Ran relevant tests after each change
 [ ] Did not weaken or delete tests
 
-Before handover to Steve:
+Before handover to the human:
 [ ] All tests passing
 [ ] Lint passing
 [ ] No unexplained skip/todo
@@ -139,4 +139,4 @@ Outcome:
 ❗ Green builds are necessary, not sufficient
 ❗ Assumptions must be written down
 ❗ No silent changes
-❗ When in doubt, slow down and ask Steve
+❗ When in doubt, slow down and ask the human

package/README.md

@@ -19,6 +19,32 @@ npx orchestr8 init
 
 This installs the `.blueprint/` directory, `.business_context/`, and the `/implement-feature` skill to `.claude/commands/`. If files already exist, you'll be prompted before overwriting. It also adds the workflow queue to `.gitignore`.
 
+During initialization, orchestr8 **auto-detects your project's tech stack** from manifest files (`package.json`, `pyproject.toml`, `go.mod`, etc.) and writes the result to `.claude/stack-config.json`. The agents (Nigel and Codey) read this file at runtime to adapt their testing and implementation approach to your stack.
+
+```bash
+# Review what was detected
+npx orchestr8 stack-config
+
+# Adjust if needed
+npx orchestr8 stack-config set language TypeScript
+npx orchestr8 stack-config set frameworks '["next","react"]'
+npx orchestr8 stack-config set testRunner vitest
+npx orchestr8 stack-config set testCommand "npx vitest run"
+```
+
+If you're working with a non-JavaScript project, set the stack config before running the pipeline:
+
+```bash
+# Python/Django example
+npx orchestr8 stack-config set language Python
+npx orchestr8 stack-config set runtime "Python 3.12"
+npx orchestr8 stack-config set packageManager pip
+npx orchestr8 stack-config set frameworks '["django"]'
+npx orchestr8 stack-config set testRunner pytest
+npx orchestr8 stack-config set testCommand "pytest"
+npx orchestr8 stack-config set linter ruff
+```
+
 ## Keeping Up to Date
 
 **Modules** (history, insights, feedback, retry, validate) are part of the npm package and update automatically when you use `npx` - no action needed.
@@ -55,15 +81,31 @@ This updates `.blueprint/agents/`, `.blueprint/templates/`, `.blueprint/ways_of_
 | `npx orchestr8 insights --bottlenecks` | View bottleneck analysis |
 | `npx orchestr8 insights --failures` | View failure pattern analysis |
 
+### Parallel Execution
+
+| Command | Description |
+|---------|-------------|
+| `npx orchestr8 parallel <slugs...>` | Run multiple features in parallel |
+| `npx orchestr8 parallel <slugs...> --dry-run` | Preview execution plan |
+| `npx orchestr8 parallel status` | Show status of running pipelines |
+| `npx orchestr8 parallel cleanup` | Remove completed worktrees |
+| `npx orchestr8 parallel-config` | View parallel configuration |
+| `npx orchestr8 parallel-config set <key> <value>` | Modify parallel settings |
+
 ### Configuration
 
 | Command | Description |
 |---------|-------------|
+| `npx orchestr8 stack-config` | View detected tech stack |
+| `npx orchestr8 stack-config set <key> <value>` | Modify stack settings (language, frameworks, testRunner, etc.) |
+| `npx orchestr8 stack-config reset` | Reset to empty defaults |
 | `npx orchestr8 retry-config` | View retry configuration |
 | `npx orchestr8 retry-config set <key> <value>` | Modify retry settings |
 | `npx orchestr8 retry-config reset` | Reset to defaults |
 | `npx orchestr8 feedback-config` | View feedback thresholds |
 | `npx orchestr8 feedback-config set <key> <value>` | Modify feedback settings |
+| `npx orchestr8 parallel-config` | View parallel pipeline configuration |
+| `npx orchestr8 parallel-config set <key> <value>` | Modify parallel settings |
 
 ## Usage
 
@@ -183,6 +225,8 @@ orchestr8 includes these built-in modules for observability and self-improvement
 | **handoff** | Structured summaries between agents for token efficiency |
 | **business-context** | Lazy loading of business context based on feature needs |
 | **tools** | Tool schemas and validation for Claude native features |
+| **parallel** | Parallel pipeline execution using git worktrees |
+| **stack** | Configurable tech stack detection and configuration |
 
 ### How They Work Together
 
@@ -239,9 +283,14 @@ your-project/
 ├── .claude/
 │   ├── commands/
 │   │   └── implement-feature.md   # The /implement-feature skill
+│   ├── worktrees/                 # Git worktrees for parallel execution
+│   │   └── feat-{slug}/           # Isolated worktree per feature
 │   ├── pipeline-history.json      # Execution history (gitignored)
 │   ├── retry-config.json          # Retry configuration (gitignored)
 │   ├── feedback-config.json       # Feedback thresholds (gitignored)
+│   ├── parallel-config.json       # Parallel execution config (gitignored)
+│   ├── parallel-queue.json        # Parallel pipeline state (gitignored)
+│   ├── stack-config.json          # Tech stack configuration (gitignored)
 │   └── implement-queue.json       # Pipeline queue state (gitignored)
 └── test/
     ├── artifacts/                 # Test specs per feature
@@ -308,6 +357,206 @@ Version 2.7 introduces several optimizations to reduce token usage:
 
 **Total estimated savings: 10,000+ tokens per pipeline run** (more for technical features)
 
+## Parallel Execution with Git Worktrees
+
+Run multiple feature pipelines simultaneously using git worktrees for isolation. Each feature gets its own worktree and branch, allowing true parallel development without conflicts.
+
+### How It Works
+
+```
+orchestr8 parallel user-auth dashboard notifications
+                    │
+                    ▼
+    ┌───────────────────────────────────────┐
+    │  Pre-flight Validation                │
+    │  • Git repository check               │
+    │  • Clean working tree required        │
+    │  • Git 2.5+ for worktree support      │
+    │  • Feature specs exist & complete     │
+    │  • File overlap detection             │
+    │  • Dependency detection               │
+    │  • Scope estimation                   │
+    └───────────────────────────────────────┘
+                    │
+                    ▼
+    ┌───────────────────────────────────────┐
+    │  Create Isolated Worktrees            │
+    │                                       │
+    │  .claude/worktrees/feat-user-auth/    │
+    │       └─ branch: feature/user-auth    │
+    │                                       │
+    │  .claude/worktrees/feat-dashboard/    │
+    │       └─ branch: feature/dashboard    │
+    │                                       │
+    │  .claude/worktrees/feat-notifications/│
+    │       └─ branch: feature/notifications│
+    └───────────────────────────────────────┘
+                    │
+                    ▼
+    ┌───────────────────────────────────────┐
+    │  Spawn Parallel Pipelines             │
+    │  (max 3 concurrent by default)        │
+    │                                       │
+    │  Each runs: Alex → Nigel → Codey      │
+    │  in its isolated worktree             │
+    └───────────────────────────────────────┘
+                    │
+                    ▼
+    ┌───────────────────────────────────────┐
+    │  Merge on Completion                  │
+    │  • First finished = first merged      │
+    │  • Conflicts preserved for resolution │
+    │  • Successful worktrees cleaned up    │
+    └───────────────────────────────────────┘
+```
+
+### Usage
+
+```bash
+# Run 3 features in parallel (default concurrency)
+npx orchestr8 parallel user-auth dashboard notifications
+
+# Preview what would happen without executing
+npx orchestr8 parallel user-auth dashboard --dry-run
+
+# Limit concurrent pipelines
+npx orchestr8 parallel feat-a feat-b feat-c feat-d --max-concurrency=2
+
+# Check status of running pipelines
+npx orchestr8 parallel status
+
+# Skip pre-flight feature validation
+npx orchestr8 parallel user-auth dashboard --skip-preflight
+
+# Clean up completed/aborted worktrees
+npx orchestr8 parallel cleanup
+```
+
+### Pre-flight Batch Validation (v2.8)
+
+Before parallel execution, the system validates the batch to prevent wasted resources:
+
+```
+$ npx orchestr8 parallel feat-a feat-b feat-c --dry-run
+
+Pre-flight Validation
+=====================
+
+✓ feat-a: Spec complete, 3 stories, Plan exists
+✓ feat-b: Spec complete, 2 stories
+✗ feat-c: Not ready
+    ✗ Missing FEATURE_SPEC.md
+
+Conflict Analysis
+=================
+
+⚠ File overlap detected:
+  • src/utils.js: feat-a, feat-b both modify
+
+Scope Estimation
+================
+
+  Feature   | Stories | Files | Est. Time
+  ----------|---------|-------|----------
+  feat-a    |       3 |     4 | ~27 min
+  feat-b    |       2 |     2 | ~24 min
+  feat-c    |       0 |     0 | ~10 min
+
+Total estimated: ~61 min (parallel: ~27 min)
+```
+
+**Validation checks:**
+- Feature specs exist and have required sections
+- User stories present (warns if missing)
+- Implementation plans scanned for file overlap
+- Dependencies between features detected
+- Scope estimated from story/file counts
+
+**On validation failure:**
+```
+Cannot proceed. Fix issues above or use --skip-preflight to override.
+
+Suggested commands:
+  /implement-feature "feat-c" --pause-after=alex
+```
+
+### Configuration
+
+The parallel module is **CLI-agnostic** — configure it to work with different AI coding tools:
+
+```bash
+# View current configuration
+npx orchestr8 parallel-config
+
+# Output:
+#   cli:            npx claude
+#   skill:          /implement-feature
+#   skillFlags:     --no-commit
+#   worktreeDir:    .claude/worktrees
+#   maxConcurrency: 3
+#   queueFile:      .claude/parallel-queue.json
+```
+
+#### Configuration Options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `cli` | `npx claude` | The CLI tool to invoke |
+| `skill` | `/implement-feature` | The command/skill to run |
+| `skillFlags` | `--no-commit` | Additional flags for the skill |
+| `worktreeDir` | `.claude/worktrees` | Where to create worktrees |
+| `maxConcurrency` | `3` | Maximum parallel pipelines |
+| `maxFeatures` | `10` | Maximum features per batch |
+| `timeout` | `30` | Timeout per pipeline (minutes) |
+| `minDiskSpaceMB` | `500` | Minimum disk space warning threshold |
+| `queueFile` | `.claude/parallel-queue.json` | State persistence file |
+
+#### Examples for Different CLIs
+
+```bash
+# Claude Code (default)
+npx orchestr8 parallel-config set cli "npx claude"
+npx orchestr8 parallel-config set skill "/implement-feature"
+
+# Cursor
+npx orchestr8 parallel-config set cli "cursor"
+npx orchestr8 parallel-config set skill "composer"
+npx orchestr8 parallel-config set skillFlags ""
+
+# Aider
+npx orchestr8 parallel-config set cli "aider"
+npx orchestr8 parallel-config set skill "--message"
+npx orchestr8 parallel-config set skillFlags "implement feature:"
+
+# Custom agent script
+npx orchestr8 parallel-config set cli "./my-agent.sh"
+npx orchestr8 parallel-config set skill "run"
+
+# Reset to defaults
+npx orchestr8 parallel-config reset
+```
+
+### State Management
+
+Each feature progresses through these states:
+
+```
+parallel_queued → worktree_created → parallel_running → merge_pending → parallel_complete
+                                           │                  │
+                                           ▼                  ▼
+                                    parallel_failed    merge_conflict
+```
+
+- **Successful features**: Merged to main, worktree cleaned up
+- **Failed pipelines**: Worktree preserved for debugging
+- **Merge conflicts**: Branch preserved, manual resolution required
+
+### Requirements
+
+- **Git 2.5+** (worktree support)
+- **Clean working tree** (no uncommitted changes)
+- **Sufficient disk space** (each worktree is a full checkout)
+
 ## License
 
 MIT

package/SKILL.md

@@ -28,8 +28,9 @@ description: Run the Alex → Cass → Nigel → Codey pipeline using Task tool
 ## Invocation
 
 ```bash
-/implement-feature                                    # Interactive
+/implement-feature                                    # Interactive slug prompt
 /implement-feature "user-auth"                        # New feature
+/implement-feature "user-auth" --interactive          # Force interactive spec creation
 /implement-feature "user-auth" --pause-after=alex|cass|nigel|codey-plan
 /implement-feature "user-auth" --no-commit
 /implement-feature "user-auth" --no-feedback          # Skip feedback collection
@@ -113,6 +114,39 @@ If not provided: Ask user, convert to slug format (lowercase, hyphens), confirm.
 ### Step 3: System Spec Gate
 Check `{SYS_SPEC}` exists. If not: run Alex to create it, then **stop for review**.
 
+### Step 3a: Interactive Mode Detection
+
+**Module:** `src/interactive.js`
+
+The pipeline automatically enters interactive mode when:
+1. `--interactive` flag is explicitly passed
+2. System spec (`{SYS_SPEC}`) is missing - creates system spec interactively
+3. Feature spec (`{FEAT_SPEC}`) is missing - creates feature spec interactively
+
+**Interactive Session Flow:**
+```
+idle → gathering → questioning → drafting → finalizing
+```
+
+**Available Commands During Session:**
+| Command | Action |
+|---------|--------|
+| `/approve` or `yes` | Mark section complete, proceed to next |
+| `/change <feedback>` | Revise current section with feedback |
+| `/skip` | Mark section TBD, proceed to next |
+| `/restart` | Discard draft, restart current section |
+| `/abort` | Exit without writing spec |
+| `/done` | Finalize spec (if min sections complete) |
+
+**Minimum Required Sections:**
+- Feature spec: Intent, Scope, Actors
+- System spec: Purpose, Actors, Boundaries
+
+**On Interactive Completion:**
+- Writes spec to appropriate path
+- Generates `handoff-alex.md` with session metrics
+- Records `mode: "interactive"` in history entry
+
 ### Step 3.5: Insights Preview (NEW)
 
 **Module:** `src/insights.js`