orchestr8 2.8.0 → 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/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.
@@ -70,6 +96,9 @@ This updates `.blueprint/agents/`, `.blueprint/templates/`, `.blueprint/ways_of_
 
 | 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 |
@@ -197,6 +226,7 @@ orchestr8 includes these built-in modules for observability and self-improvement
 | **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
 
@@ -260,6 +290,7 @@ your-project/
 │   ├── 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

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`

package/bin/cli.js

@@ -12,6 +12,11 @@ const {
   setConfigValue: setFeedbackConfigValue,
   resetConfig: resetFeedbackConfig
 } = require('../src/feedback');
+const {
+  displayStackConfig,
+  setStackConfigValue,
+  resetStackConfig
+} = require('../src/stack');
 const { displayFeedbackInsights } = require('../src/insights');
 const {
   formatStatus,
@@ -145,6 +150,26 @@ const commands = {
     },
     description: 'Manage feedback loop configuration'
   },
+  'stack-config': {
+    fn: () => {
+      if (subArg === 'set') {
+        const key = args[2];
+        const value = args[3];
+        if (!key || !value) {
+          console.error('Usage: stack-config set <key> <value>');
+          console.error('Valid keys: language, runtime, packageManager, frameworks, testRunner, testCommand, linter, tools');
+          process.exit(1);
+        }
+        setStackConfigValue(key, value);
+      } else if (subArg === 'reset') {
+        resetStackConfig();
+        console.log('Stack configuration reset to defaults.');
+      } else {
+        displayStackConfig();
+      }
+    },
+    description: 'View or modify project tech stack configuration'
+  },
   'parallel-config': {
     fn: () => {
       if (subArg === 'set') {
@@ -307,6 +332,9 @@ 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
+  stack-config          View current tech stack configuration
+  stack-config set <key> <value>  Modify a config value (language, runtime, frameworks, etc.)
+  stack-config reset    Reset tech stack 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestr8",
-  "version": "2.8.0",
+  "version": "3.0.0",
   "description": "Multi-agent workflow framework for automated feature development",
   "main": "src/index.js",
   "bin": {
@@ -20,7 +20,7 @@
   "author": "NewmanJustice",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/NewmanJustice/orchestr8.git"
+    "url": "git+https://github.com/NewmanJustice/agent-workflow.git"
   },
   "license": "MIT",
   "engines": {