orchestr8 2.1.3

package/README.md

@@ -0,0 +1,100 @@
+# agent-workflow
+
+A multi-agent workflow framework for automated feature development. Four specialized AI agents collaborate in sequence to take features from specification to implementation.
+
+## Agents
+
+| Agent | Role |
+|-------|------|
+| **Alex** | System Specification & Chief-of-Staff — creates/maintains specs, guards design coherence |
+| **Cass** | Story Writer/BA — translates specs into testable user stories |
+| **Nigel** | Tester — converts stories into executable tests and test plans |
+| **Codey** | Developer — implements code to satisfy tests (test-first) |
+
+## Installation
+
+```bash
+npx agent-workflow init
+```
+
+This installs the `.blueprint/` directory and `SKILL.md` into your project. If files already exist, you'll be prompted before overwriting. It also adds the workflow queue to `.gitignore`.
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `npx agent-workflow init` | Initialize `.blueprint/` and `SKILL.md` in your project |
+| `npx agent-workflow update` | Update agents, templates, and rituals to latest version |
+| `npx agent-workflow add-skills [agent]` | Install recommended skills for an agent (alex, cass, nigel, codey, all) |
+| `npx agent-workflow skills [agent]` | List recommended skills |
+| `npx agent-workflow help` | Show help |
+
+The `update` command preserves your content in `features/`, `system_specification/`, and `.business_context/` while updating the framework files.
+
+### Optional Skills
+
+Each agent has recommended skills from the [skills.sh](https://skills.sh) ecosystem that enhance their capabilities:
+
+| Agent | Skills |
+|-------|--------|
+| **Alex** | `avoid-feature-creep`, `feature-spec` |
+| **Cass** | `user-story-writing` |
+| **Nigel** | `javascript-testing-patterns`, `modern-javascript-patterns` |
+| **Codey** | `javascript-expert`, `modern-javascript-patterns` |
+
+```bash
+npx agent-workflow add-skills all     # Install all recommended skills
+npx agent-workflow add-skills codey   # Install skills for Codey only
+```
+
+## Usage
+
+Run the pipeline with the `/implement-feature` skill in Claude Code:
+
+```bash
+/implement-feature                                    # Interactive
+/implement-feature "user-auth"                        # New feature
+/implement-feature "user-auth" --update-feature-spec  # Update spec
+/implement-feature "user-auth" --update-story "login" # Update story
+/implement-feature --update-system-spec               # Update system spec
+```
+
+### Pipeline Flow
+
+```
+New Feature:    Alex → Cass → Nigel → Codey → Commit
+Update Story:   Cass → Nigel → Codey → Commit
+Update Feature: Alex → cascade check
+Update System:  Alex → cascade check
+```
+
+## Directory Structure
+
+```
+.blueprint/
+├── agents/                    # Agent specifications
+│   ├── AGENT_SPECIFICATION_ALEX.md
+│   ├── AGENT_BA_CASS.md
+│   ├── AGENT_TESTER_NIGEL.md
+│   └── AGENT_DEVELOPER_CODEY.md
+├── templates/                 # Spec templates
+│   ├── SYSTEM_SPEC.md
+│   └── FEATURE_SPEC.md
+├── ways_of_working/           # Development rituals
+├── features/                  # Feature specs (created per feature)
+├── system_specification/      # System spec (created on first run)
+└── .business_context/         # Project-specific context
+```
+
+## How It Works
+
+1. **Alex** gates on the system spec — creates it if missing, then routes to the appropriate workflow
+2. **Cass** writes user stories with acceptance criteria from the feature spec
+3. **Nigel** creates test plans, behavior matrices, and executable tests
+4. **Codey** implements code to pass the tests, then auto-commits
+
+The pipeline maintains a queue (`.claude/implement-queue.json`) to track progress and enable recovery on failure.
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,381 @@
+---
+name: implement-feature
+description: Run the Alex → Cass → Nigel → Codey pipeline using Task tool sub-agents
+---
+
+# Implement Feature Skill
+
+## Paths
+
+| Var | Path |
+|-----|------|
+| `{SYS_SPEC}` | `.blueprint/system_specification/SYSTEM_SPEC.md` |
+| `{FEAT_DIR}` | `.blueprint/features/feature_{slug}` |
+| `{FEAT_SPEC}` | `{FEAT_DIR}/FEATURE_SPEC.md` |
+| `{STORIES}` | `{FEAT_DIR}/story-*.md` |
+| `{TEST_DIR}` | `./test/artifacts/feature_{slug}` |
+| `{TEST_FILE}` | `./test/feature_{slug}.test.js` |
+| `{PLAN}` | `{FEAT_DIR}/IMPLEMENTATION_PLAN.md` |
+| `{QUEUE}` | `.claude/implement-queue.json` |
+
+## Invocation
+
+```bash
+/implement-feature                                    # Interactive
+/implement-feature "user-auth"                        # New feature
+/implement-feature "user-auth" --pause-after=alex|cass|nigel|codey-plan
+/implement-feature "user-auth" --no-commit
+```
+
+## Pipeline Overview
+
+```
+/implement-feature "slug"
+       │
+       ▼
+┌─────────────────────────────────────────┐
+│ 1. Parse args, get slug                 │
+│ 2. Check system spec exists (gate)      │
+│ 3. Initialize queue                     │
+│ 4. Route based on flags/state           │
+└─────────────────────────────────────────┘
+       │
+       ▼
+   SPAWN ALEX → SPAWN CASS → SPAWN NIGEL → SPAWN CODEY → AUTO-COMMIT
+```
+
+---
+
+## Steps 1-5: Setup
+
+### Step 1: Parse Arguments
+Extract: `{slug}`, pause gates (`--pause-after`), `--no-commit`
+
+### Step 2: Get Feature Slug
+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 4: Route
+- Slug exists at `{FEAT_DIR}` → ask: continue from last state or restart
+- No slug → new feature pipeline
+
+### Step 5: Initialize
+Create/read `{QUEUE}`. Ensure dirs exist: `mkdir -p {FEAT_DIR} {TEST_DIR}`
+
+---
+
+## Step 6: Spawn Alex Agent
+
+Use the Task tool with `subagent_type="general-purpose"`:
+
+**Prompt:**
+```
+You are Alex, the System Specification & Chief-of-Staff Agent.
+
+Read your full specification from: .blueprint/agents/AGENT_SPECIFICATION_ALEX.md
+
+## Your Task
+Create a feature specification for "{slug}".
+
+## Inputs (read these files)
+- System Spec: .blueprint/system_specification/SYSTEM_SPEC.md
+- Template: .blueprint/templates/FEATURE_SPEC.md
+- Business Context: .blueprint/.business_context/
+
+## Output (write this file)
+Write the feature spec to: {FEAT_DIR}/FEATURE_SPEC.md
+
+## Completion
+When done, summarize:
+- Feature intent
+- Key behaviours
+- Scope boundaries
+- Story themes you recommend
+- Any system spec tensions found
+```
+
+**On completion:**
+1. Verify `{FEAT_SPEC}` exists
+2. Update queue: move feature to `cassQueue`
+3. If `--pause-after=alex`: Show output path, ask user to continue
+
+**On failure:** Ask user (retry / skip / abort)
+
+---
+
+## Step 7: Spawn Cass Agent
+
+Use the Task tool with `subagent_type="general-purpose"`:
+
+**Prompt:**
+```
+You are Cass, the Story Writer Agent.
+
+Read your full specification from: .blueprint/agents/AGENT_BA_CASS.md
+
+## Your Task
+Create user stories for feature "{slug}".
+
+## Inputs (read these files)
+- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md
+- System Spec: .blueprint/system_specification/SYSTEM_SPEC.md
+
+## Output (write these files)
+Create one markdown file per user story in {FEAT_DIR}/:
+- story-{story-slug}.md (e.g., story-login.md, story-logout.md)
+
+Each story must include:
+- User story in standard format
+- Context/scope
+- Acceptance criteria (Given/When/Then)
+- Session persistence shape (if relevant)
+- Out of scope items
+
+## Completion
+When done, summarize:
+- Number of stories created
+- Story filenames
+- Key behaviours covered
+```
+
+**On completion:**
+1. Verify at least one `story-*.md` exists in `{FEAT_DIR}`
+2. Update queue: move feature to `nigelQueue`
+3. If `--pause-after=cass`: Show story paths, ask user to continue
+
+**On failure:** Ask user (retry / skip / abort)
+
+---
+
+## Step 8: Spawn Nigel Agent
+
+Use the Task tool with `subagent_type="general-purpose"`:
+
+**Prompt:**
+```
+You are Nigel, the Tester Agent.
+
+Read your full specification from: .blueprint/agents/AGENT_TESTER_NIGEL.md
+
+## Your Task
+Create tests for feature "{slug}".
+
+## Inputs (read these files)
+- Stories: {FEAT_DIR}/story-*.md
+- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md
+- System Spec: .blueprint/system_specification/SYSTEM_SPEC.md
+
+## Outputs (write these files)
+1. Test artifacts in {TEST_DIR}/:
+   - understanding.md
+   - test-plan.md
+   - test-behaviour-matrix.md
+   - implementation-guide.md
+
+2. Executable tests:
+   - {TEST_FILE}
+
+## Completion
+When done, summarize:
+- Test count
+- Coverage of acceptance criteria
+- Key assumptions made
+```
+
+**On completion:**
+1. Verify `{TEST_FILE}` exists
+2. Update queue: move feature to `codeyQueue`
+3. If `--pause-after=nigel`: Show test paths, ask user to continue
+
+**On failure:** Ask user (retry / skip / abort)
+
+---
+
+## Step 9: Spawn Codey Agent (Plan)
+
+Use the Task tool with `subagent_type="general-purpose"`:
+
+**Prompt:**
+```
+You are Codey, the Developer Agent.
+
+Read your full specification from: .blueprint/agents/AGENT_DEVELOPER_CODEY.md
+
+## Your Task
+Create an implementation plan for feature "{slug}". Do NOT implement yet.
+
+## Inputs (read these files)
+- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md
+- Stories: {FEAT_DIR}/story-*.md
+- Test Artifacts: {TEST_DIR}/
+- Tests: {TEST_FILE}
+
+## Output (write this file)
+Write implementation plan to: {FEAT_DIR}/IMPLEMENTATION_PLAN.md
+
+Plan structure:
+## Summary
+## Understanding (behaviors, test count)
+## Files to Create/Modify
+## Implementation Steps
+## Data Model (if applicable)
+## Validation Rules
+## Risks/Questions
+## Definition of Done
+```
+
+**On completion:**
+1. Verify `{PLAN}` exists
+2. If `--pause-after=codey-plan`: Show plan path, ask user to continue
+
+**On failure:** Ask user (retry / skip / abort)
+
+---
+
+## Step 10: Spawn Codey Agent (Implement)
+
+Use the Task tool with `subagent_type="general-purpose"`:
+
+**Prompt:**
+```
+You are Codey, the Developer Agent.
+
+Read your full specification from: .blueprint/agents/AGENT_DEVELOPER_CODEY.md
+
+## Your Task
+Implement feature "{slug}" according to the plan.
+
+## Inputs (read these files)
+- Implementation Plan: {FEAT_DIR}/IMPLEMENTATION_PLAN.md
+- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md
+- Stories: {FEAT_DIR}/story-*.md
+- Test Artifacts: {TEST_DIR}/
+- Tests: {TEST_FILE}
+
+## Process
+1. Run tests to establish baseline: npm test
+2. Implement code to make tests pass
+3. Run npm test to verify all tests pass
+4. Run npm run lint (if available) to verify code quality
+
+## Important
+- Do NOT commit changes
+- Do NOT modify test assertions unless they contain bugs
+- Focus on making tests pass
+
+## Completion
+When done, summarize:
+- Files created/modified
+- Test status (pass/fail count)
+- Any issues encountered
+```
+
+**On completion:**
+1. Run `npm test` to verify
+2. Update queue: move feature to `completed`
+3. Proceed to auto-commit (unless `--no-commit`)
+
+**On failure:** Ask user (retry / skip / abort)
+
+---
+
+## Step 11: Auto-commit
+
+If not `--no-commit`:
+
+```bash
+git add {FEAT_DIR}/ {TEST_DIR}/ {TEST_FILE}
+# Add any implementation files created by Codey
+git status --short
+```
+
+Commit message:
+```
+feat({slug}): Add {slug} feature
+
+Artifacts:
+- Feature spec by Alex
+- User stories by Cass
+- Tests by Nigel
+- Implementation by Codey
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+---
+
+## Step 12: Report Status
+
+```
+## Completed
+- feature_{slug}
+  - Stories: N
+  - Tests: N (all passing)
+  - Commit: {hash}
+
+## Next Action
+Pipeline complete. Run `npm test` to verify or `/implement-feature` for next feature.
+```
+
+---
+
+## Error Handling
+
+After each agent spawn, if the Task tool returns an error or output validation fails:
+
+**Ask the user:**
+1. **Retry** - Re-run the agent with same inputs
+2. **Skip** - Move to next stage anyway (with warning about missing artifacts)
+3. **Abort** - Stop pipeline, update queue with failure for recovery
+
+**On abort:** Update queue `failed` array with:
+```json
+{
+  "slug": "{slug}",
+  "stage": "{stage}",
+  "reason": "{error message}",
+  "timestamp": "{ISO timestamp}"
+}
+```
+
+---
+
+## Queue Structure
+
+Location: `.claude/implement-queue.json`
+
+```json
+{
+  "lastUpdated": "2025-02-01T12:00:00Z",
+  "current": {
+    "slug": "user-auth",
+    "stage": "cass",
+    "startedAt": "2025-02-01T11:55:00Z"
+  },
+  "alexQueue": [],
+  "cassQueue": [{ "slug": "user-auth", "featureSpec": "..." }],
+  "nigelQueue": [],
+  "codeyQueue": [],
+  "completed": [{ "slug": "...", "testCount": 5, "commitHash": "abc123" }],
+  "failed": []
+}
+```
+
+---
+
+## Recovery
+
+Run `/implement-feature` again - reads queue and resumes from `current.stage`.
+
+---
+
+## Agent References
+
+| Agent | File |
+|-------|------|
+| Alex | `.blueprint/agents/AGENT_SPECIFICATION_ALEX.md` |
+| Cass | `.blueprint/agents/AGENT_BA_CASS.md` |
+| Nigel | `.blueprint/agents/AGENT_TESTER_NIGEL.md` |
+| Codey | `.blueprint/agents/AGENT_DEVELOPER_CODEY.md` |

package/bin/cli.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+
+const { init } = require('../src/init');
+const { update } = require('../src/update');
+const { addSkills, listSkills } = require('../src/skills');
+const { displayQueue, resetQueue } = require('../src/orchestrator');
+
+const args = process.argv.slice(2);
+const command = args[0];
+const subArg = args[1];
+
+const commands = {
+  init: {
+    fn: init,
+    description: 'Initialize .blueprint directory in current project'
+  },
+  update: {
+    fn: update,
+    description: 'Update agents, templates, and rituals (preserves your content)'
+  },
+  'add-skills': {
+    fn: () => addSkills(subArg || 'all'),
+    description: 'Install recommended skills for an agent (or all)'
+  },
+  skills: {
+    fn: () => listSkills(subArg),
+    description: 'List recommended skills for agents'
+  },
+  queue: {
+    fn: () => {
+      if (subArg === 'reset') {
+        resetQueue();
+        console.log('Queue has been reset.');
+      } else {
+        displayQueue();
+      }
+    },
+    description: 'Show queue status (use "reset" to clear)'
+  },
+  help: {
+    fn: showHelp,
+    description: 'Show this help message'
+  }
+};
+
+function showHelp() {
+  console.log(`
+agent-workflow - Multi-agent workflow framework
+
+Usage: agent-workflow <command> [options]
+
+Commands:
+  init                  Initialize .blueprint directory in current project
+  update                Update agents, templates, and rituals (preserves your content)
+  add-skills [agent]    Install recommended skills for an agent (alex, cass, nigel, codey, all)
+  skills [agent]        List recommended skills for agents
+  queue                 Show current queue state for /implement-feature pipeline
+  queue reset           Clear the queue and reset all state
+  help                  Show this help message
+
+Examples:
+  npx agent-workflow init
+  npx agent-workflow update
+  npx agent-workflow add-skills all
+  npx agent-workflow add-skills codey
+  npx agent-workflow skills
+  npx agent-workflow queue
+  npx agent-workflow queue reset
+`);
+}
+
+async function main() {
+  if (!command || command === 'help' || command === '--help' || command === '-h') {
+    showHelp();
+    process.exit(0);
+  }
+
+  const cmd = commands[command];
+  if (!cmd) {
+    console.error(`Unknown command: ${command}`);
+    console.error('Run "agent-workflow help" for usage information.');
+    process.exit(1);
+  }
+
+  try {
+    await cmd.fn();
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "orchestr8",
+  "version": "2.1.3",
+  "description": "Multi-agent workflow framework for automated feature development",
+  "main": "src/index.js",
+  "bin": {
+    "orchestr8": "bin/cli.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "keywords": [
+    "agent",
+    "workflow",
+    "ai",
+    "automation",
+    "claude",
+    "feature-development"
+  ],
+  "author": "NewmanJustice",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NewmanJustice/agent-workflow.git"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin",
+    "src",
+    ".blueprint",
+    "SKILL.md"
+  ]
+}

package/src/index.js

@@ -0,0 +1,5 @@
+const { init } = require('./init');
+const { update } = require('./update');
+const { addSkills, listSkills, AGENT_SKILLS } = require('./skills');
+
+module.exports = { init, update, addSkills, listSkills, AGENT_SKILLS };