orchestr8 2.8.0 → 3.1.0

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.1.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": {

package/src/index.js

@@ -50,6 +50,37 @@ const {
   TECHNICAL_KEYWORDS,
   USER_FACING_KEYWORDS
 } = require('./classifier');
+const {
+  parseFlags: parseInteractiveFlags,
+  shouldEnterInteractiveMode,
+  createSession,
+  getSessionProgress,
+  handleCommand,
+  getNextSection,
+  markSectionComplete,
+  markSectionTBD,
+  gatherContext,
+  identifyGaps,
+  generateQuestions,
+  canFinalize,
+  generateSpec,
+  writeSpec,
+  generateHandoff,
+  getOutputPath,
+  SESSION_STATES,
+  SECTION_ORDER,
+  MIN_REQUIRED_SECTIONS,
+  SYSTEM_SPEC_QUESTIONS
+} = require('./interactive');
+const {
+  getDefaultStackConfig,
+  readStackConfig,
+  writeStackConfig,
+  resetStackConfig,
+  setStackConfigValue,
+  detectStackConfig,
+  displayStackConfig
+} = require('./stack');
 const tools = require('./tools');
 
 module.exports = {
@@ -105,6 +136,35 @@ module.exports = {
   logClassification,
   TECHNICAL_KEYWORDS,
   USER_FACING_KEYWORDS,
+  // Stack config exports
+  getDefaultStackConfig,
+  readStackConfig,
+  writeStackConfig,
+  resetStackConfig,
+  setStackConfigValue,
+  detectStackConfig,
+  displayStackConfig,
   // Tools module (model native features)
-  tools
+  tools,
+  // Interactive mode exports
+  parseInteractiveFlags,
+  shouldEnterInteractiveMode,
+  createSession,
+  getSessionProgress,
+  handleCommand,
+  getNextSection,
+  markSectionComplete,
+  markSectionTBD,
+  gatherContext,
+  identifyGaps,
+  generateQuestions,
+  canFinalize,
+  generateSpec,
+  writeSpec,
+  generateHandoff,
+  getOutputPath,
+  SESSION_STATES,
+  SECTION_ORDER,
+  MIN_REQUIRED_SECTIONS,
+  SYSTEM_SPEC_QUESTIONS
 };

package/src/init.js

@@ -2,6 +2,8 @@ const fs = require('fs');
 const path = require('path');
 const readline = require('readline');
 
+const { detectStackConfig, writeStackConfig, CONFIG_FILE: STACK_CONFIG_FILE } = require('./stack');
+
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TARGET_DIR = process.cwd();
 
@@ -41,7 +43,8 @@ function updateGitignore() {
   const entriesToAdd = [
     '# agent-workflow',
     '.claude/implement-queue.json',
-    '.claude/pipeline-history.json'
+    '.claude/pipeline-history.json',
+    '.claude/stack-config.json'
   ];
 
   let content = '';
@@ -109,12 +112,27 @@ async function init() {
   // Update .gitignore
   updateGitignore();
 
+  // Auto-detect tech stack
+  const stackConfigPath = path.join(TARGET_DIR, STACK_CONFIG_FILE);
+  if (!fs.existsSync(stackConfigPath)) {
+    const detected = detectStackConfig(TARGET_DIR);
+    const hasValues = detected.language || detected.runtime;
+    if (hasValues) {
+      writeStackConfig(detected);
+      const parts = [detected.language, detected.runtime, ...detected.frameworks, detected.testRunner].filter(Boolean);
+      console.log(`Detected tech stack: ${parts.join(', ')}`);
+    }
+  } else {
+    console.log('Stack config already exists, skipping detection');
+  }
+
   console.log(`
 orchestr8 initialized successfully!
 
 Next steps:
-1. Add business context documents to .business_context/
-2. Run /implement-feature in Claude Code to start your first feature
+1. Review your tech stack with \`npx orchestr8 stack-config\`
+2. Add business context documents to .business_context/
+3. Run /implement-feature in Claude Code to start your first feature
 `);
 }