orchestr8 2.7.1 → 3.0.0

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

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

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

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

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

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

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

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

package/.blueprint/features/feature_interactive-alex/story-iterative-drafting.md

@@ -0,0 +1,65 @@
+# User Story: Iterative Spec Drafting
+
+## Story
+
+**As a** developer in an interactive session,
+**I want** Alex to gather context, ask targeted questions, and draft spec sections incrementally,
+**so that** the resulting specification accurately captures my intent with minimal revision cycles.
+
+## Acceptance Criteria
+
+### AC-1: Context Gathering Phase
+
+**Given** an interactive session has started
+**When** the user provides their initial feature description
+**Then** Alex acknowledges understanding by summarizing the core intent
+**And** Alex identifies 2-4 information gaps relative to the FEATURE_SPEC template
+
+### AC-2: Clarifying Questions
+
+**Given** Alex has identified information gaps
+**When** Alex asks clarifying questions
+**Then** questions are presented in a single batch (2-4 questions)
+**And** questions are specific and actionable (not open-ended)
+**And** Alex waits for user responses before proceeding
+
+### AC-3: Section-by-Section Drafting
+
+**Given** Alex has gathered sufficient context
+**When** Alex drafts spec sections
+**Then** sections are drafted incrementally (Intent first, then Scope, then Actors, etc.)
+**And** after each section, Alex presents the draft
+**And** Alex asks: "Does this capture your intent? Any changes?"
+
+### AC-4: Revision Handling
+
+**Given** Alex has presented a draft section
+**And** the user requests changes via `/change <feedback>`
+**When** Alex revises the section
+**Then** Alex incorporates the specific feedback
+**And** Alex presents the revised draft
+**And** Alex asks for approval again
+
+### AC-5: Progress Indication
+
+**Given** an interactive session is active
+**When** Alex transitions between sections
+**Then** Alex indicates which sections are complete
+**And** Alex indicates which sections remain
+
+### AC-6: Concise Responses
+
+**Given** Alex is drafting or responding in the session
+**When** Alex produces conversational output
+**Then** each response is under 200 words
+**And** focus is on actionable content, not filler
+
+## Out of Scope
+
+- Full-spec-at-once drafting mode
+- Configurable question count (fixed at 2-4)
+- Template customization during session
+
+## References
+
+- Feature Spec: `.blueprint/features/feature_interactive-alex/FEATURE_SPEC.md` (Section 4.3)

package/.blueprint/features/feature_interactive-alex/story-pipeline-integration.md

@@ -0,0 +1,66 @@
+# User Story: Pipeline Integration
+
+## Story
+
+**As a** developer completing an interactive session,
+**I want** the interactive mode to integrate seamlessly with the existing pipeline infrastructure,
+**so that** downstream agents receive proper handoffs and the pipeline can resume or record history as expected.
+
+## Acceptance Criteria
+
+### AC-1: Spec File Output
+
+**Given** an interactive session completes successfully (via `/approve` on final section or `/done`)
+**When** Alex finalizes the spec
+**Then** FEATURE_SPEC.md is written to `{FEAT_DIR}/FEATURE_SPEC.md`
+**And** the file includes all completed sections
+**And** skipped sections are marked as "TBD"
+**And** the file includes a note: "Created via interactive session"
+
+### AC-2: Handoff Artifact
+
+**Given** an interactive session completes successfully
+**When** Alex writes the spec file
+**Then** Alex also produces `handoff-alex.md` in the feature directory
+**And** the handoff includes key decisions, files created, and open questions
+
+### AC-3: Queue Update
+
+**Given** an interactive session completes successfully
+**When** the pipeline continues
+**Then** the queue is updated with the feature moving from `alexQueue` to `cassQueue`
+**And** `current.stage` reflects "cass" (or the next applicable stage)
+
+### AC-4: History Recording
+
+**Given** an interactive session completes (success or abort)
+**When** history is recorded (unless `--no-history` flag present)
+**Then** the `pipeline-history.json` entry includes `mode: "interactive"`
+**And** the entry includes question count, revision count, and session duration
+
+### AC-5: Pause After Alex
+
+**Given** an interactive session completes successfully
+**And** `--pause-after=alex` flag was provided
+**When** Alex finishes
+**Then** the pipeline pauses before spawning Cass
+**And** user can review the spec before continuing
+
+### AC-6: Continue to Downstream Agents
+
+**Given** an interactive session completes successfully
+**And** `--pause-after=alex` flag was NOT provided
+**When** Alex finishes
+**Then** the pipeline continues automatically
+**And** Cass is spawned with the produced FEATURE_SPEC.md as input
+
+## Out of Scope
+
+- Changes to Cass, Nigel, or Codey agent behaviour
+- Parallel pipeline execution
+- Multi-feature batch processing
+
+## References
+
+- Feature Spec: `.blueprint/features/feature_interactive-alex/FEATURE_SPEC.md` (Section 6)
+- System Spec: `.blueprint/system_specification/SYSTEM_SPEC.md` (Sections 6-7)

package/.blueprint/features/feature_interactive-alex/story-session-lifecycle.md

@@ -0,0 +1,75 @@
+# User Story: Interactive Session Lifecycle
+
+## Story
+
+**As a** developer entering interactive mode,
+**I want** a clear session lifecycle with explicit commands for controlling the conversation,
+**so that** I can navigate the spec creation process efficiently and exit gracefully when needed.
+
+## Acceptance Criteria
+
+### AC-1: Session Initialization
+
+**Given** interactive mode is activated (explicit flag or auto-detect)
+**When** the session starts
+**Then** Alex reads system spec (if exists), business context, and feature template
+**And** Alex presents an opening prompt: "Describe the feature you want to build. What problem does it solve and for whom?"
+
+### AC-2: Approve Command
+
+**Given** an interactive session is active
+**And** Alex has presented a draft section
+**When** the user responds with `/approve` or `yes`
+**Then** the current section is marked complete
+**And** Alex proceeds to the next section
+
+### AC-3: Change Command
+
+**Given** an interactive session is active
+**And** Alex has presented a draft section
+**When** the user responds with `/change <feedback>`
+**Then** Alex revises the current section based on the feedback
+**And** Alex presents the revised draft for approval
+
+### AC-4: Skip Command
+
+**Given** an interactive session is active
+**And** Alex has presented a draft section
+**When** the user responds with `/skip`
+**Then** the current section is marked as "TBD" in the spec
+**And** Alex proceeds to the next section
+
+### AC-5: Restart Command
+
+**Given** an interactive session is active
+**And** Alex is working on a section
+**When** the user responds with `/restart`
+**Then** Alex discards the current section draft
+**And** Alex starts the section from scratch with fresh questions
+
+### AC-6: Abort Command
+
+**Given** an interactive session is active
+**When** the user responds with `/abort`
+**Then** the session terminates immediately
+**And** no spec file is written to disk
+**And** the pipeline exits without proceeding to downstream agents
+
+### AC-7: Done Command
+
+**Given** an interactive session is active
+**And** at least Intent, Scope, and Actors sections are complete or skipped
+**When** the user responds with `/done`
+**Then** Alex finalizes the spec with completed sections
+**And** skipped sections are marked as "TBD"
+**And** the spec file is written to disk
+
+## Out of Scope
+
+- Session persistence between interrupted sessions
+- Timeout handling (session continues until user acts)
+- Multi-user concurrent sessions
+
+## References
+
+- Feature Spec: `.blueprint/features/feature_interactive-alex/FEATURE_SPEC.md` (Section 4.4)

package/.blueprint/features/feature_interactive-alex/story-system-spec-creation.md

@@ -0,0 +1,57 @@
+# User Story: Interactive System Spec Creation
+
+## Story
+
+**As a** developer initializing a new project without a system specification,
+**I want** Alex to guide me through creating a SYSTEM_SPEC.md interactively,
+**so that** I establish the project's boundaries and constraints before creating feature specs.
+
+## Acceptance Criteria
+
+### AC-1: System Spec Auto-Detection
+
+**Given** a user invokes `/implement-feature "my-feature"`
+**And** `.blueprint/system_specification/SYSTEM_SPEC.md` does not exist
+**When** the pipeline checks prerequisites
+**Then** interactive mode activates for system spec creation (not feature spec)
+
+### AC-2: System Spec Session Flow
+
+**Given** interactive system spec mode is active
+**When** Alex starts the session
+**Then** Alex asks about: purpose, actors, system boundaries, and governing rules
+**And** Alex drafts SYSTEM_SPEC.md sections incrementally
+**And** the same session commands apply (`/approve`, `/change`, `/skip`, `/restart`, `/abort`, `/done`)
+
+### AC-3: System Spec Output Location
+
+**Given** an interactive system spec session completes successfully
+**When** Alex writes the spec
+**Then** the file is written to `.blueprint/system_specification/SYSTEM_SPEC.md`
+**And** the file follows the SYSTEM_SPEC template structure
+
+### AC-4: Pipeline Gate Satisfied
+
+**Given** SYSTEM_SPEC.md is created via interactive session
+**When** the user re-invokes `/implement-feature "my-feature"`
+**Then** the system spec gate passes
+**And** the pipeline proceeds to feature spec creation (interactive or autonomous)
+
+### AC-5: System Spec Before Feature Spec
+
+**Given** a user invokes `/implement-feature "my-feature" --interactive`
+**And** SYSTEM_SPEC.md does not exist
+**When** the pipeline routing logic runs
+**Then** system spec interactive session runs first
+**And** only after system spec is complete does feature spec interactive session begin
+
+## Out of Scope
+
+- Updating existing SYSTEM_SPEC.md interactively (only creation)
+- Skipping system spec gate entirely
+- System spec versioning or change tracking
+
+## References
+
+- Feature Spec: `.blueprint/features/feature_interactive-alex/FEATURE_SPEC.md` (Section 4.1, Open Question 2)
+- System Spec: `.blueprint/system_specification/SYSTEM_SPEC.md` (Section 7 - System spec gate)

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

@@ -0,0 +1,117 @@
+# Feature Specification — Parallel Abort
+
+## 1. Feature Intent
+
+Provide a way to stop all running parallel pipelines and optionally clean up worktrees. Users need an escape hatch if something goes wrong or they need to stop execution mid-way.
+
+**Problem:** Once parallel pipelines start, there's no clean way to stop them. Users would have to manually find and kill processes, then clean up worktrees.
+
+**Solution:** `orchestr8 parallel abort` command that gracefully stops all pipelines and handles cleanup.
+
+---
+
+## 2. Scope
+
+### In Scope
+- Stop all running pipeline processes
+- Update queue state to 'aborted'
+- Option to preserve or remove worktrees
+- Handle Ctrl+C in main process
+- Clear status reporting
+
+### Out of Scope
+- Selective abort (single feature) — future enhancement
+- Rollback of completed merges
+
+---
+
+## 3. Behaviour Overview
+
+### Abort (Preserve Worktrees)
+
+```
+$ orchestr8 parallel abort
+
+Stopping parallel pipelines...
+
+[10:35:01] feat-a: Stopping process (PID: 12345)
+[10:35:01] feat-b: Stopping process (PID: 12346)
+[10:35:02] feat-a: Stopped
+[10:35:02] feat-b: Stopped
+
+Aborted 2 pipelines. Worktrees preserved for debugging:
+  • .claude/worktrees/feat-feat-a/
+  • .claude/worktrees/feat-feat-b/
+
+To clean up: orchestr8 parallel cleanup
+```
+
+### Abort with Cleanup
+
+```
+$ orchestr8 parallel abort --cleanup
+
+Stopping parallel pipelines...
+
+[10:35:01] feat-a: Stopping process (PID: 12345)
+[10:35:02] feat-a: Stopped
+[10:35:02] feat-a: Removing worktree
+
+Aborted 1 pipeline. Worktrees removed.
+```
+
+### Ctrl+C Handling
+
+```
+$ orchestr8 parallel feat-a feat-b feat-c
+
+Starting parallel pipelines...
+[10:30:01] feat-a: Started
+[10:30:02] feat-b: Started
+
+^C
+Received interrupt signal. Stopping pipelines...
+
+[10:31:15] feat-a: Stopped
+[10:31:15] feat-b: Stopped
+
+Aborted. Worktrees preserved. Run 'orchestr8 parallel cleanup' to remove.
+```
+
+### Nothing Running
+
+```
+$ orchestr8 parallel abort
+
+No parallel pipelines are currently running.
+```
+
+---
+
+## 4. Implementation Notes
+
+- Read PIDs from queue file or lock file
+- Send SIGTERM first, then SIGKILL after timeout
+- Update queue state for each feature to 'aborted'
+- Register handler for SIGINT (Ctrl+C) in main process
+- `--cleanup` flag triggers worktree removal after abort
+
+---
+
+## 5. Test Themes
+
+- Abort stops running processes
+- Queue state updated to 'aborted'
+- Worktrees preserved by default
+- `--cleanup` removes worktrees
+- Ctrl+C triggers graceful shutdown
+- No-op when nothing running
+- Lock file removed after abort
+
+---
+
+## 6. Change Log
+
+| Date | Change | Reason |
+|------|--------|--------|
+| 2026-02-25 | Initial spec | Parallel safeguards |

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

@@ -0,0 +1,90 @@
+# Feature Specification — Parallel Confirm
+
+## 1. Feature Intent
+
+Prevent accidental execution of parallel pipelines by requiring user confirmation before starting. Users should see exactly what will happen (worktrees created, pipelines spawned, estimated resources) and explicitly confirm they want to proceed.
+
+**Problem:** Running `orchestr8 parallel feat-a feat-b feat-c` immediately starts creating worktrees and spawning processes. Users might run this accidentally or without understanding the impact.
+
+**Solution:** Show a summary and prompt for confirmation before execution.
+
+---
+
+## 2. Scope
+
+### In Scope
+- Confirmation prompt showing execution plan
+- `--yes` / `-y` flag to skip confirmation (for automation)
+- Clear summary of what will happen
+
+### Out of Scope
+- Interactive editing of the plan
+- Cost estimation (separate feature)
+
+---
+
+## 3. Behaviour Overview
+
+### Happy Path
+
+```
+$ orchestr8 parallel user-auth dashboard notifications
+
+This will:
+  • Create 3 git worktrees in .claude/worktrees/
+  • Start 3 parallel pipelines (max concurrent: 3)
+  • Branches: feature/user-auth, feature/dashboard, feature/notifications
+
+Continue? [y/N] y
+
+Starting parallel pipelines...
+```
+
+### Skip Confirmation
+
+```
+$ orchestr8 parallel user-auth dashboard --yes
+Starting parallel pipelines...
+```
+
+### User Declines
+
+```
+$ orchestr8 parallel user-auth dashboard
+
+This will:
+  • Create 2 git worktrees in .claude/worktrees/
+  • Start 2 parallel pipelines (max concurrent: 3)
+
+Continue? [y/N] n
+
+Aborted.
+```
+
+---
+
+## 4. Implementation Notes
+
+- Add confirmation logic after dry-run check, before actual execution
+- Use `readline` for prompt in Node.js
+- Check `options.yes` flag to skip
+- Exit with code 0 on user abort (not an error)
+
+---
+
+## 5. Test Themes
+
+- Confirmation shown by default
+- `--yes` flag skips confirmation
+- `-y` shorthand works
+- User typing 'n' or Enter aborts
+- User typing 'y' or 'Y' proceeds
+- Abort exits cleanly (code 0)
+
+---
+
+## 6. Change Log
+
+| Date | Change | Reason |
+|------|--------|--------|
+| 2026-02-25 | Initial spec | Parallel safeguards |