orchestr8 2.7.0 → 2.8.0

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

@@ -0,0 +1,105 @@
+# Feature Specification — Parallel Logging
+
+## 1. Feature Intent
+
+Write each pipeline's output to a dedicated log file instead of interleaving on console. When multiple pipelines run simultaneously, their output becomes unreadable. Logging to files keeps the console clean while preserving full output for debugging.
+
+**Problem:** With 3 pipelines running in parallel, console output is an unreadable mess of interleaved messages from different agents.
+
+**Solution:** Write each pipeline's stdout/stderr to a log file; show only summary status on console.
+
+---
+
+## 2. Scope
+
+### In Scope
+- Log file per pipeline: `.claude/worktrees/feat-{slug}/pipeline.log`
+- Summary status on console (started, completed, failed)
+- `--verbose` flag to also stream to console
+- Timestamps on log entries
+
+### Out of Scope
+- Log rotation
+- Log compression
+- Remote log shipping
+
+---
+
+## 3. Behaviour Overview
+
+### Default (Quiet Console)
+
+```
+$ orchestr8 parallel feat-a feat-b feat-c
+
+Starting parallel pipelines...
+
+[10:30:01] feat-a: Started (log: .claude/worktrees/feat-feat-a/pipeline.log)
+[10:30:02] feat-b: Started (log: .claude/worktrees/feat-feat-b/pipeline.log)
+[10:30:03] feat-c: Started (log: .claude/worktrees/feat-feat-c/pipeline.log)
+[10:35:15] feat-b: Completed ✓
+[10:36:22] feat-a: Completed ✓
+[10:38:45] feat-c: Failed ✗ (see log for details)
+
+Summary: 2 completed, 1 failed
+```
+
+### Verbose Mode
+
+```
+$ orchestr8 parallel feat-a --verbose
+
+Starting parallel pipelines...
+
+[10:30:01] feat-a: Started
+--- feat-a output ---
+You are Alex, the System Specification Agent...
+[Alex output streams here]
+...
+--- end feat-a output ---
+
+[10:35:15] feat-a: Completed ✓
+```
+
+---
+
+## 4. Log File Format
+
+Location: `.claude/worktrees/feat-{slug}/pipeline.log`
+
+```
+[2026-02-25T10:30:01.123Z] Pipeline started for feat-a
+[2026-02-25T10:30:01.456Z] [stdout] You are Alex, the System Specification Agent...
+[2026-02-25T10:30:02.789Z] [stdout] Reading feature spec...
+[2026-02-25T10:35:15.000Z] [stderr] Warning: some warning
+[2026-02-25T10:35:15.100Z] Pipeline completed with exit code 0
+```
+
+---
+
+## 5. Implementation Notes
+
+- Change `stdio: 'inherit'` to `stdio: 'pipe'`
+- Create write stream to log file
+- Prefix each line with timestamp and stream type
+- On `--verbose`, also pipe to `process.stdout`
+- Console shows only status updates (not full output)
+
+---
+
+## 6. Test Themes
+
+- Log file created in worktree directory
+- Log contains timestamped output
+- Console shows only status by default
+- `--verbose` streams output to console
+- Log preserved on failure for debugging
+- Multiple pipelines don't interleave in logs
+
+---
+
+## 7. Change Log
+
+| Date | Change | Reason |
+|------|--------|--------|
+| 2026-02-25 | Initial spec | Parallel safeguards |

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/README.md

@@ -55,6 +55,17 @@ 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 |
@@ -64,6 +75,8 @@ This updates `.blueprint/agents/`, `.blueprint/templates/`, `.blueprint/ways_of_
 | `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 +196,7 @@ 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 |
 
 ### How They Work Together
 
@@ -239,9 +253,13 @@ 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)
 │   └── implement-queue.json       # Pipeline queue state (gitignored)
 └── test/
     ├── artifacts/                 # Test specs per feature
@@ -308,6 +326,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/bin/cli.js

@@ -13,6 +13,22 @@ const {
   resetConfig: resetFeedbackConfig
 } = require('../src/feedback');
 const { displayFeedbackInsights } = require('../src/insights');
+const {
+  formatStatus,
+  getDefaultConfig,
+  splitByLimit,
+  runParallel,
+  loadQueue,
+  cleanupWorktrees,
+  readParallelConfig,
+  writeParallelConfig,
+  getDefaultParallelConfig,
+  abortParallel,
+  getLockInfo,
+  getDetailedStatus,
+  formatDetailedStatus,
+  rollbackParallel
+} = require('../src/parallel');
 
 const args = process.argv.slice(2);
 const command = args[0];
@@ -129,6 +145,134 @@ const commands = {
     },
     description: 'Manage feedback loop configuration'
   },
+  'parallel-config': {
+    fn: () => {
+      if (subArg === 'set') {
+        const key = args[2];
+        const value = args[3];
+        if (!key || !value) {
+          console.error('Usage: parallel-config set <key> <value>');
+          console.error('Valid keys: cli, skill, skillFlags, worktreeDir, maxConcurrency, queueFile');
+          process.exit(1);
+        }
+        const config = readParallelConfig();
+        if (key === 'maxConcurrency') {
+          config[key] = parseInt(value, 10);
+        } else {
+          config[key] = value;
+        }
+        writeParallelConfig(config);
+        console.log(`Set ${key} = ${value}`);
+      } else if (subArg === 'reset') {
+        writeParallelConfig(getDefaultParallelConfig());
+        console.log('Parallel configuration reset to defaults.');
+      } else {
+        const config = readParallelConfig();
+        console.log('Parallel Configuration\n');
+        console.log(`  cli:            ${config.cli}`);
+        console.log(`  skill:          ${config.skill}`);
+        console.log(`  skillFlags:     ${config.skillFlags}`);
+        console.log(`  worktreeDir:    ${config.worktreeDir}`);
+        console.log(`  maxConcurrency: ${config.maxConcurrency}`);
+        console.log(`  maxFeatures:    ${config.maxFeatures}`);
+        console.log(`  timeout:        ${config.timeout} min`);
+        console.log(`  minDiskSpaceMB: ${config.minDiskSpaceMB}`);
+        console.log(`  queueFile:      ${config.queueFile}`);
+        console.log('\nTo change: orchestr8 parallel-config set <key> <value>');
+      }
+    },
+    description: 'View or modify parallel pipeline configuration'
+  },
+  parallel: {
+    fn: async () => {
+      if (subArg === 'status') {
+        const detailed = args.includes('--detailed') || args.includes('-d');
+        const lock = getLockInfo();
+
+        if (detailed) {
+          const details = getDetailedStatus();
+          console.log(formatDetailedStatus(details));
+        } else {
+          const queue = loadQueue();
+
+          if (!queue.features || queue.features.length === 0) {
+            if (lock) {
+              console.log(`Parallel execution in progress (PID: ${lock.pid})`);
+              console.log(`Started: ${lock.startedAt}`);
+              console.log(`Features: ${lock.features.join(', ')}`);
+            } else {
+              console.log('No parallel pipelines active.');
+            }
+            return;
+          }
+
+          console.log('Parallel Pipeline Status\n');
+          console.log(formatStatus(queue.features));
+          const summary = {
+            running: queue.features.filter(f => f.status === 'parallel_running').length,
+            pending: queue.features.filter(f => f.status === 'parallel_queued').length,
+            completed: queue.features.filter(f => f.status === 'parallel_complete').length,
+            failed: queue.features.filter(f => f.status === 'parallel_failed').length,
+            conflicts: queue.features.filter(f => f.status === 'merge_conflict').length
+          };
+          console.log(`\nRunning: ${summary.running} | Pending: ${summary.pending} | Completed: ${summary.completed} | Failed: ${summary.failed} | Conflicts: ${summary.conflicts}`);
+
+          // Show log paths for running/failed
+          const withLogs = queue.features.filter(f =>
+            f.logPath && (f.status === 'parallel_running' || f.status === 'parallel_failed')
+          );
+          if (withLogs.length > 0) {
+            console.log('\nLog files:');
+            withLogs.forEach(f => console.log(`  ${f.slug}: ${f.logPath}`));
+          }
+
+          console.log('\nTip: Use --detailed for progress bars');
+        }
+      } else if (subArg === 'rollback') {
+        const dryRunFlag = args.includes('--dry-run');
+        const forceFlag = args.includes('--force');
+        await rollbackParallel({ dryRun: dryRunFlag, force: forceFlag });
+      } else if (subArg === 'cleanup') {
+        const cleaned = await cleanupWorktrees();
+        console.log(`Cleaned ${cleaned} worktree(s).`);
+      } else if (subArg === 'abort') {
+        const cleanupFlag = args.includes('--cleanup');
+        await abortParallel({ cleanup: cleanupFlag });
+      } else {
+        const slugs = args.slice(1).filter(a => !a.startsWith('--') && !a.startsWith('-'));
+        if (slugs.length === 0) {
+          console.error('Usage: orchestr8 parallel <slug1> <slug2> ... [options]');
+          console.error('\nOptions:');
+          console.error('  --dry-run            Preview execution plan without running');
+          console.error('  --yes, -y            Skip confirmation prompt');
+          console.error('  --force              Override existing lock');
+          console.error('  --verbose            Stream output to console (not just logs)');
+          console.error('  --skip-preflight     Skip feature validation checks');
+          console.error('  --max-concurrency=N  Set max parallel pipelines (default: 3)');
+          console.error('\nSubcommands:');
+          console.error('  parallel status    Show status of all pipelines');
+          console.error('  parallel abort     Stop all running pipelines');
+          console.error('  parallel cleanup   Remove completed/aborted worktrees');
+          process.exit(1);
+        }
+
+        const maxFlag = args.find(a => a.startsWith('--max-concurrency='));
+        const options = {
+          dryRun: args.includes('--dry-run'),
+          yes: args.includes('--yes') || args.includes('-y'),
+          force: args.includes('--force'),
+          verbose: args.includes('--verbose'),
+          skipPreflight: args.includes('--skip-preflight')
+        };
+        if (maxFlag) {
+          options.maxConcurrency = parseInt(maxFlag.split('=')[1], 10);
+        }
+        const result = await runParallel(slugs, options);
+        process.exit(result.success ? 0 : 1);
+      }
+    },
+    description: 'Run multiple feature pipelines in parallel using git worktrees'
+  },
   help: {
     fn: showHelp,
     description: 'Show this help message'
@@ -163,6 +307,21 @@ Commands:
   feedback-config       View current feedback loop configuration
   feedback-config set <key> <value>  Modify a config value (minRatingThreshold, enabled)
   feedback-config reset Reset feedback configuration to defaults
+  parallel <slugs...>   Run multiple feature pipelines in parallel
+  parallel <slugs...> --dry-run  Show execution plan without running
+  parallel <slugs...> --yes      Skip confirmation prompt
+  parallel <slugs...> --verbose  Stream output to console
+  parallel <slugs...> --skip-preflight  Skip feature validation checks
+  parallel status       Show status of all parallel pipelines
+  parallel status --detailed  Show progress bars and stage info
+  parallel abort        Stop all running pipelines
+  parallel abort --cleanup  Stop all and remove worktrees
+  parallel rollback     Undo completed merges and cleanup failures
+  parallel rollback --dry-run  Preview what would be rolled back
+  parallel cleanup      Remove completed/aborted worktrees
+  parallel-config       View parallel pipeline configuration
+  parallel-config set <key> <value>  Modify config (cli, skill, skillFlags, etc.)
+  parallel-config reset Reset parallel configuration to defaults
   help                  Show this help message
 
 Examples:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestr8",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Multi-agent workflow framework for automated feature development",
   "main": "src/index.js",
   "bin": {