orchestr8 2.4.0 → 2.5.0

package/.blueprint/agents/AGENT_BA_CASS.md

@@ -95,13 +95,15 @@ If critical information is missing or ambiguous, you should:
 
 ## Outputs you must produce
 
-At minimum, for each screen or feature:
+**IMPORTANT: Write ONE story file at a time to avoid token limits.**
 
-1. **User story** in standard format
-2. **Context / scope** including routes
-3. **Acceptance criteria** (AC-1, AC-2, ...) in Given/When/Then format
-4. **Session / persistence** shape where relevant
-5. **Explicit non-goals** (what is out of scope)
+Each story file (story-{slug}.md) should contain:
+
+1. **User story** in standard format (1 sentence)
+2. **Acceptance criteria** (AC-1, AC-2, ...) in Given/When/Then - max 5-7 per story
+3. **Out of scope** (brief bullet list)
+
+Keep stories focused. If a feature needs >7 ACs, split into multiple story files.
 
 ### Output standards (non-negotiable)
 

package/.blueprint/agents/AGENT_DEVELOPER_CODEY.md

@@ -194,29 +194,23 @@ If critical information is missing or ambiguous, you should:
 
 ## Outputs you must produce
 
-For each story or feature you work on:
+**IMPORTANT: Write ONE file at a time to avoid token limits. Run tests after each file.**
 
-1. **Implementation code**
-   - New or updated modules (routes, controllers, services, helpers, middleware, view logic).
-   - Code that is:
-     - aligned with the stack’s conventions,
-     - easy to test, and
-     - consistent with existing project structure.
+For each story or feature:
 
-2. **Green test suite**
-   - All relevant Jest tests passing (including Nigel’s tests and any you add).
-   - No new flaky or brittle tests.
-   - No tests silently skipped without a clear reason (e.g. `test.skip` must be justified in comments and raised with Steve).
+1. **Implementation code** (incremental)
+   - Write/edit ONE source file, then run tests
+   - Repeat until test group passes, then move to next group
+   - Keep functions small (<30 lines)
 
-3. **Tooling compliance**
-   - `npm test` passes (or the project equivalent).
-   - `npm run lint` (or equivalent) passes.
-   - Any new code follows ESLint rules and formatting conventions.
+2. **Green test suite**
+   - All Jest/Node tests passing
+   - Run `node --test` or `npm test` after each file change
 
-4. **Change notes (at least in the PR / summary)**
-   - What you changed and why.
-   - Any assumptions or deviations from the tests/ACs.
-   - Any new technical debt or TODOs you had to introduce.
+3. **Brief completion summary**
+   - Files changed (list)
+   - Test status (X/Y passing)
+   - Blockers if any
 
 ---
 
@@ -227,20 +221,13 @@ For each story or feature:
 ### Step 1: Understand the requirements and tests
 
 1. Read:
-   - The **user story** and **acceptance criteria**.
-   - Nigel’s **Understanding** document.
-   - The **Test Plan** and Test Behaviour Matrix.
-   - The **executable tests** related to this story.
-
-2. Build a mental model of:
-   - The **happy path** behaviour.
-   - Key **edge cases** and **error flows**.
-   - Any **constraints** (validation rules, security, performance).
-
-3. Identify:
-   - What **already exists** in the codebase and tests.
-   - What is **new** for this story.
-   - Any **gaps** where behaviour is specified but not yet tested.
+   - The **user story** files (story-*.md)
+   - Nigel's **test-spec.md** (AC → Test mapping)
+   - The **executable tests**
+
+2. Build a mental model of: happy path, edge cases, error flows
+
+3. Identify what already exists vs what is new
 
 If something is unclear, **do not guess silently**: call it out and ask Steve.
 

package/.blueprint/agents/AGENT_TESTER_NIGEL.md

@@ -50,103 +50,49 @@ If critical information is missing or ambiguous, you should:
 
 ### Outputs you must produce
 
-At minimum, for each story:
-
-1. **Test Plan (high level)**
-   - Scope and assumptions
-   - Risks / unknowns
-   - Types of tests (unit, integration, contract, etc.)
-
-2. **Concrete Test Cases**
-   - Happy path
-   - Key edge cases
-   - Error / failure cases
-   Each test should have:
-   - A unique name / ID
-   - Preconditions / setup
-   - Action(s)
-   - Expected outcome(s)
-
-3. **Test Artefacts**
-   Produce:
-   - A **test case list** (table or bullets)
-   - Map each test back to **specific acceptance criteria**
-   - Clearly show which criteria have **no tests yet** (if any)
-   - An “Understanding” document to accompany each user story. 
+**IMPORTANT: Write files ONE AT A TIME to avoid token limits.**
 
-## 3. Standard workflow
+Produce exactly 2 files:
 
-For each story or feature you receive:
+1. **test-spec.md** (write FIRST, keep under 100 lines)
+   - Brief understanding (5-10 lines max)
+   - AC → Test ID mapping table (compact format)
+   - Key assumptions (bullet list)
 
-### Step 1: Understand and normalise
+2. **Executable test file** (write SECOND)
+   - One `describe` block per user story
+   - One `it` block per acceptance criterion
+   - Self-documenting test names - minimal comments 
 
-1. Summarise the story in your own words.
-2. Extract:
-   - **Primary behaviour** (“happy path”)
-   - **Variants** (input variations, roles, states)
-   - **Constraints** (business rules, limits, validation, security)
-3. Identify anything that is:
-   - Ambiguous  
-   - Under-specified  
-   - Conflicting with other criteria
+## 3. Standard workflow
 
-Output: a brief, bullet-point **“Understanding”** section.
+For each story or feature you receive:
 
----
+### Step 1: Understand (brief)
 
-### Step 2: Derive testable behaviours
+1. Read the story and acceptance criteria
+2. Identify: happy path, edge cases, error scenarios
+3. Note ambiguities as assumptions (don't block on them)
 
-From the story + acceptance criteria:
+### Step 2: Build AC → Test mapping
 
-1. Turn each acceptance criterion into **one or more testable statements**.
-2. Group tests into:
-   - **Happy path**
-   - **Edge and boundary cases**
-   - **Error / invalid scenarios**
-   - **Cross-cutting** (auth, permissions, logging, etc., when relevant)
-3. Make assumptions explicit:
-   - “Assuming max length of X is 255 chars…”
-   - “Assuming timestamps use UTC…”
+Create a compact table:
 
-Output: a **Test Behaviour Matrix**, e.g.:
+| AC | Test ID | Scenario |
+|----|---------|----------|
+| AC-1 | T-1.1 | Valid credentials → success |
+| AC-1 | T-1.2 | Invalid password → error |
 
-- AC-1: Users can log in with valid credentials  
-  - T-1.1: Valid username/password → success  
-  - T-1.2: Case sensitivity on username? (question)  
-  - T-1.3: Locked account → error message
+### Step 3: Write test-spec.md
 
----
+Combine understanding + mapping table + assumptions into one file (<100 lines).
+### Step 4: Write executable tests
+
+After writing test-spec.md, write the test file:
 
-### Step 3: Design concrete test cases
-
-For each behaviour:
-
-1. Define **specific inputs and expected outputs**, including:
-   - exact values (e.g. `"password123!"`, `"2025-05-01T12:00:00Z"`)
-   - system state (e.g. “account locked”, “cart has 3 items”)
-   - environment (e.g. locale, timezone, feature flags)
-
-2. Use a consistent format, for example:
-
-```text
-ID: T-1.1
-Relates to: AC-1 – “User can log in with valid credentials”
-
-Given a registered user with:
-  - username: "alice@example.com"
-  - password: "Password123!"
-When they submit the login form with those credentials
-Then:
-  - they are redirected to the dashboard
-  - their session token is created
-  - the login attempt is recorded as successful
-Highlight ambiguities as questions, not assumptions, e.g.:
-“Q: Should the error message reveal whether the username or password is incorrect?”
-```
-### Step 4: Create executable tests for Codey to develope against. 
-- Favour readable, behaviour-focused names, e.g.:
-it("logs in successfully with valid credentials", ...)
-- Keep tests small and isolated where possible:
+- One `describe` per story, one `it` per AC
+- Behaviour-focused names: `it("logs in successfully with valid credentials", ...)`
+- Keep tests small and isolated
 one main assertion per test
 clean, predictable setup/teardown
 - Make it obvious when a test is pending or blocked:

package/README.md

@@ -17,13 +17,13 @@ A multi-agent workflow framework for automated feature development. Four special
 npx orchestr8 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`.
+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`.
 
 ### Commands
 
 | Command | Description |
 |---------|-------------|
-| `npx orchestr8 init` | Initialize `.blueprint/` and `SKILL.md` in your project |
+| `npx orchestr8 init` | Initialize `.blueprint/`, `.business_context/`, and skill in your project |
 | `npx orchestr8 update` | Update agents, templates, and rituals to latest version |
 | `npx orchestr8 add-skills [agent]` | Install recommended skills for an agent (alex, cass, nigel, codey, all) |
 | `npx orchestr8 skills [agent]` | List recommended skills |
@@ -82,11 +82,13 @@ your-project/
 │   │   ├── 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)
+│   ├── features/                  # Feature specs (populated per feature)
+│   └── system_specification/      # System spec (populated on first run)
 ├── .business_context/             # Business context documents
 │   └── README.md
-└── SKILL.md
+└── .claude/
+    └── commands/
+        └── implement-feature.md   # The /implement-feature skill
 ```
 
 ## How It Works

package/SKILL.md

@@ -14,6 +14,7 @@ description: Run the Alex → Cass → Nigel → Codey pipeline using Task tool
 | `{FEAT_SPEC}` | `{FEAT_DIR}/FEATURE_SPEC.md` |
 | `{STORIES}` | `{FEAT_DIR}/story-*.md` |
 | `{TEST_DIR}` | `./test/artifacts/feature_{slug}` |
+| `{TEST_SPEC}` | `{TEST_DIR}/test-spec.md` |
 | `{TEST_FILE}` | `./test/feature_{slug}.test.js` |
 | `{PLAN}` | `{FEAT_DIR}/IMPLEMENTATION_PLAN.md` |
 | `{QUEUE}` | `.claude/implement-queue.json` |
@@ -44,6 +45,16 @@ description: Run the Alex → Cass → Nigel → Codey pipeline using Task tool
    SPAWN ALEX → SPAWN CASS → SPAWN NIGEL → SPAWN CODEY → AUTO-COMMIT
 ```
 
+## Output Constraints (CRITICAL)
+
+**All agents MUST follow these rules to avoid token limit errors:**
+
+1. **Write files incrementally** - Write each file separately, never combine multiple files in one response
+2. **Keep summaries brief** - Final completion summaries should be 5-10 bullet points max
+3. **Reference, don't repeat** - Use file paths instead of quoting content from other artifacts
+4. **One concern per file** - Don't merge unrelated content into single large files
+5. **Chunk large files** - If a file would exceed ~200 lines, split into logical parts
+
 ---
 
 ## Steps 1-5: Setup
@@ -87,13 +98,14 @@ Create a feature specification for "{slug}".
 ## Output (write this file)
 Write the feature spec to: {FEAT_DIR}/FEATURE_SPEC.md
 
+## Output Rules
+- Write file incrementally (section by section if large)
+- Only include sections relevant to this feature (skip empty/N/A sections)
+- Reference system spec by path, don't repeat its content
+- Keep Change Log to 1-2 entries max
+
 ## Completion
-When done, summarize:
-- Feature intent
-- Key behaviours
-- Scope boundaries
-- Story themes you recommend
-- Any system spec tensions found
+Brief summary (5 bullets max): intent, key behaviours, scope, story themes, tensions
 ```
 
 **On completion:**
@@ -128,16 +140,17 @@ Create one markdown file per user story in {FEAT_DIR}/:
 
 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
+- Acceptance criteria (Given/When/Then) - max 5-7 per story
+- Out of scope items (brief list)
+
+## Output Rules
+- Write ONE story file at a time, then move to next
+- Keep each story focused - split large stories into multiple files
+- Reference feature spec by path for shared context
+- Skip boilerplate sections (session shape only if non-obvious)
 
 ## Completion
-When done, summarize:
-- Number of stories created
-- Story filenames
-- Key behaviours covered
+Brief summary: story count, filenames, behaviours covered (5 bullets max)
 ```
 
 **On completion:**
@@ -165,27 +178,31 @@ 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
+## Outputs (write these files IN ORDER, one at a time)
+
+Step 1: Write {TEST_DIR}/test-spec.md containing:
+- Brief understanding (5-10 lines)
+- AC → Test ID mapping table (compact)
+- Key assumptions (bullet list)
+
+Step 2: Write {TEST_FILE} containing:
+- Executable tests (Jest/Node test runner)
+- Group by user story
+- One describe block per story, one test per AC
 
-2. Executable tests:
-   - {TEST_FILE}
+## Output Rules
+- Write test-spec.md FIRST, then write test file
+- Keep test-spec.md under 100 lines (table format, no prose)
+- Tests should be self-documenting - minimal comments
+- Reference story files by path in test descriptions
 
 ## Completion
-When done, summarize:
-- Test count
-- Coverage of acceptance criteria
-- Key assumptions made
+Brief summary: test count, AC coverage %, assumptions (5 bullets max)
 ```
 
 **On completion:**
-1. Verify `{TEST_FILE}` exists
+1. Verify `{TEST_SPEC}` and `{TEST_FILE}` exist
 2. Update queue: move feature to `codeyQueue`
 3. If `--pause-after=nigel`: Show test paths, ask user to continue
 
@@ -209,21 +226,17 @@ 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}/
+- Test Spec: {TEST_DIR}/test-spec.md
 - 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
+Plan structure (keep concise - aim for <80 lines total):
+## Summary (2-3 sentences)
+## Files to Create/Modify (table: path | action | purpose)
+## Implementation Steps (numbered, max 10 steps)
+## Risks/Questions (bullet list, only if non-obvious)
 ```
 
 **On completion:**
@@ -249,27 +262,29 @@ 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
+## Process (INCREMENTAL - one file at a time)
+1. Run tests: node --test {TEST_FILE}
+2. For each failing test group:
+   a. Identify the minimal code needed
+   b. Write/edit ONE file
+   c. Run tests again
+   d. Repeat until group passes
+3. Move to next test group
+
+## Output Rules
+- Write ONE source file at a time
+- Run tests after each file write
+- Keep functions small (<30 lines)
+- No explanatory comments in code - code should be self-documenting
 
 ## 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
+Brief summary: files changed (list), test status (X/Y passing), blockers if any
 ```
 
 **On completion:**

package/package.json

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

package/src/update.js

@@ -78,11 +78,18 @@ async function update() {
     }
   }
 
-  // Update SKILL.md
-  const answer = await prompt('\nUpdate SKILL.md? (Y/n): ');
+  // Update SKILL.md and .claude/commands/implement-feature.md
+  const answer = await prompt('\nUpdate SKILL.md and .claude/commands/implement-feature.md? (Y/n): ');
   if (answer !== 'n' && answer !== 'no') {
     fs.copyFileSync(skillSrc, skillDest);
     console.log('Updated SKILL.md');
+
+    // Also update the Claude Code skill command
+    const skillCommandDest = path.join(TARGET_DIR, '.claude', 'commands', 'implement-feature.md');
+    if (fs.existsSync(path.dirname(skillCommandDest))) {
+      fs.copyFileSync(skillSrc, skillCommandDest);
+      console.log('Updated .claude/commands/implement-feature.md');
+    }
   }
 
   console.log(`
@@ -93,6 +100,7 @@ Updated:
   - .blueprint/templates/
   - .blueprint/ways_of_working/
   - SKILL.md
+  - .claude/commands/implement-feature.md (if exists)
 
 Preserved:
   - .blueprint/features/