orchestr8 2.6.0 → 2.7.0

package/SKILL.md

@@ -21,6 +21,9 @@ description: Run the Alex → Cass → Nigel → Codey pipeline using Task tool
 | `{HISTORY}` | `.claude/pipeline-history.json` |
 | `{RETRY_CONFIG}` | `.claude/retry-config.json` |
 | `{FEEDBACK_CONFIG}` | `.claude/feedback-config.json` |
+| `{HANDOFF_ALEX}` | `{FEAT_DIR}/handoff-alex.md` |
+| `{HANDOFF_CASS}` | `{FEAT_DIR}/handoff-cass.md` |
+| `{HANDOFF_NIGEL}` | `{FEAT_DIR}/handoff-nigel.md` |
 
 ## Invocation
 
@@ -154,37 +157,64 @@ historyEntry = {
 
 **History:** Record `stages.alex.startedAt` before spawning.
 
+**Runtime prompt:** `.blueprint/prompts/alex-runtime.md`
+
 Use the Task tool with `subagent_type="general-purpose"`:
 
 **Prompt:**
 ```
-You are Alex, the System Specification & Chief-of-Staff Agent.
+You are Alex, the System Specification Agent.
 
-Read your full specification from: .blueprint/agents/AGENT_SPECIFICATION_ALEX.md
+## Task
 
-## Your Task
-Create a feature specification for "{slug}".
+Create a feature specification for "{slug}" that translates system intent into a bounded, reviewable unit.
 
 ## Inputs (read these files)
 - System Spec: .blueprint/system_specification/SYSTEM_SPEC.md
 - Template: .blueprint/templates/FEATURE_SPEC.md
 - Business Context: .business_context/
 
-## Output (write this file)
-Write the feature spec to: {FEAT_DIR}/FEATURE_SPEC.md
+## Outputs (write these files)
+1. Write the feature spec to: {FEAT_DIR}/FEATURE_SPEC.md
+2. Write handoff summary to: {FEAT_DIR}/handoff-alex.md
+
+## Handoff Summary Format
+```markdown
+## Handoff Summary
+**For:** Cass
+**Feature:** {slug}
+
+### Key Decisions
+- (1-5 bullets: key architectural/scope decisions)
+
+### Files Created
+- {FEAT_DIR}/FEATURE_SPEC.md
+
+### Open Questions
+- (List any unresolved questions, or "None")
 
-## 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
+### Critical Context
+(Brief context Cass needs to write stories effectively)
+```
+
+## Rules
+- Write feature spec FIRST, then write handoff summary
+- Reference system spec by path, do not repeat its content
 - Keep Change Log to 1-2 entries max
+- Flag ambiguities explicitly rather than guessing
+- Ensure feature aligns with system boundaries
+- Make inferred interpretations explicit
+- Handoff summary must be under 30 lines
 
 ## Completion
 Brief summary (5 bullets max): intent, key behaviours, scope, story themes, tensions
+
+## Reference
+For detailed guidance, see: .blueprint/agents/AGENT_SPECIFICATION_ALEX.md
 ```
 
 **On completion:**
-1. Verify `{FEAT_SPEC}` exists
+1. Verify `{FEAT_SPEC}` and `{FEAT_DIR}/handoff-alex.md` exist
 2. **Record history:** `stages.alex = { completedAt, durationMs, status: "success" }`
 3. Update queue: move feature to `cassQueue`
 4. If `--pause-after=alex`: Show output path, ask user to continue
@@ -201,13 +231,9 @@ Unless `--no-feedback` flag is set, collect feedback before Cass writes stories:
 
 **Prompt addition to Cass:**
 ```
-FIRST, before writing stories, evaluate Alex's feature spec:
-- Rating (1-5): How clear and complete is the spec?
-- Issues: List any problems (e.g., "missing-error-handling", "unclear-scope")
-- Recommendation: "proceed" | "pause" | "revise"
-
-Output your feedback as:
-FEEDBACK: { "rating": N, "issues": [...], "recommendation": "..." }
+FEEDBACK FIRST: Rate Alex's spec 1-5, list issues (e.g., unclear-scope), recommend proceed|pause|revise.
+Format: FEEDBACK: {"rating":N,"issues":["..."],"rec":"proceed|pause|revise"}
+Then continue with your task.
 ```
 
 **Quality Gate Check:**
@@ -223,42 +249,73 @@ FEEDBACK: { "rating": N, "issues": [...], "recommendation": "..." }
 
 **History:** Record `stages.cass.startedAt` before spawning.
 
+**Runtime prompt:** `.blueprint/prompts/cass-runtime.md`
+
 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
+## Task
 
-## Your Task
-Create user stories for feature "{slug}".
+Create user stories for feature "{slug}" with explicit, testable acceptance criteria.
 
 ## Inputs (read these files)
-- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md
+- Handoff Summary: {FEAT_DIR}/handoff-alex.md (read FIRST for quick context)
+- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md (full details if needed)
 - 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)
+## Outputs (write these files)
+1. Create one markdown file per user story in {FEAT_DIR}/:
+   - story-{story-slug}.md (e.g., story-login.md, story-logout.md)
+2. Write handoff summary to: {FEAT_DIR}/handoff-cass.md
 
 Each story must include:
-- User story in standard format
+- User story in standard format (As a... I want... so that...)
 - Acceptance criteria (Given/When/Then) - max 5-7 per story
 - Out of scope items (brief list)
 
-## Output Rules
+## Handoff Summary Format
+```markdown
+## Handoff Summary
+**For:** Nigel
+**Feature:** {slug}
+
+### Key Decisions
+- (1-5 bullets: story structure decisions, AC approach)
+
+### Files Created
+- {FEAT_DIR}/story-*.md (list each file)
+
+### Open Questions
+- (List any unresolved questions, or "None")
+
+### Critical Context
+(Brief context Nigel needs to write tests effectively)
+```
+
+## Rules
+- Read Alex's handoff summary FIRST for quick orientation
 - Write ONE story file at a time, then move to next
+- Write handoff summary LAST after all stories complete
 - Keep each story focused - split large stories into multiple files
+- Make routing explicit (Previous, Continue, conditional paths)
 - Reference feature spec by path for shared context
-- Skip boilerplate sections (session shape only if non-obvious)
+- Do not guess policy detail without flagging assumptions
+- Avoid implicit behaviour - all routes must be explicit
+- Handoff summary must be under 30 lines
 
 ## Completion
 Brief summary: story count, filenames, behaviours covered (5 bullets max)
+
+## Reference
+For detailed guidance, see: .blueprint/agents/AGENT_BA_CASS.md
 ```
 
 **On completion:**
 1. Verify at least one `story-*.md` exists in `{FEAT_DIR}`
+2. Verify `{FEAT_DIR}/handoff-cass.md` exists
 2. **Record history:** `stages.cass = { completedAt, durationMs, status: "success" }`
 3. Update queue: move feature to `nigelQueue`
 4. If `--pause-after=cass`: Show story paths, ask user to continue
@@ -275,13 +332,9 @@ Unless `--no-feedback` flag is set:
 
 **Prompt addition to Nigel:**
 ```
-FIRST, before writing tests, evaluate Cass's user stories:
-- Rating (1-5): How testable are the stories?
-- Issues: List any problems (e.g., "ambiguous-ac", "missing-edge-cases")
-- Recommendation: "proceed" | "pause" | "revise"
-
-Output your feedback as:
-FEEDBACK: { "rating": N, "issues": [...], "recommendation": "..." }
+FEEDBACK FIRST: Rate Cass's stories 1-5, list issues (e.g., ambiguous-ac), recommend proceed|pause|revise.
+Format: FEEDBACK: {"rating":N,"issues":["..."],"rec":"proceed|pause|revise"}
+Then continue with your task.
 ```
 
 **Quality Gate Check:** Same as Step 6.5
@@ -294,45 +347,76 @@ FEEDBACK: { "rating": N, "issues": [...], "recommendation": "..." }
 
 **History:** Record `stages.nigel.startedAt` before spawning.
 
+**Runtime prompt:** `.blueprint/prompts/nigel-runtime.md`
+
 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
+## Task
 
-## Your Task
-Create tests for feature "{slug}".
+Create tests for feature "{slug}" that expose ambiguities and provide a stable contract for implementation.
 
 ## Inputs (read these files)
-- Stories: {FEAT_DIR}/story-*.md
-- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md
+- Handoff Summary: {FEAT_DIR}/handoff-cass.md (read FIRST for quick context)
+- Stories: {FEAT_DIR}/story-*.md (full details)
+- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md (if additional context needed)
 
-## Outputs (write these files IN ORDER, one at a time)
+## Outputs (write these files IN ORDER)
 
 Step 1: Write {TEST_DIR}/test-spec.md containing:
 - Brief understanding (5-10 lines)
-- AC → Test ID mapping table (compact)
+- AC to 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
-
-## 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
+- Executable tests (Jest or Node test runner)
+- One describe block per story
+- One test per acceptance criterion
+
+Step 3: Write handoff summary to: {FEAT_DIR}/handoff-nigel.md
+
+## Handoff Summary Format
+```markdown
+## Handoff Summary
+**For:** Codey
+**Feature:** {slug}
+
+### Key Decisions
+- (1-5 bullets: test approach, mocking strategy, coverage focus)
+
+### Files Created
+- {TEST_DIR}/test-spec.md
+- {TEST_FILE}
+
+### Open Questions
+- (List any unresolved questions, or "None")
+
+### Critical Context
+(Brief context Codey needs to implement effectively)
+```
+
+## Rules
+- Read Cass's handoff summary FIRST for quick orientation
+- Write test-spec.md FIRST, then write test file, then handoff summary LAST
+- Keep test-spec.md under 100 lines using table format
+- Tests should be self-documenting with minimal comments
 - Reference story files by path in test descriptions
+- Make failure states meaningful
+- Focus on externally observable behaviour
+- Handoff summary must be under 30 lines
 
 ## Completion
 Brief summary: test count, AC coverage %, assumptions (5 bullets max)
+
+## Reference
+For detailed guidance, see: .blueprint/agents/AGENT_TESTER_NIGEL.md
 ```
 
 **On completion:**
-1. Verify `{TEST_SPEC}` and `{TEST_FILE}` exist
+1. Verify `{TEST_SPEC}`, `{TEST_FILE}`, and `{FEAT_DIR}/handoff-nigel.md` exist
 2. **Record history:** `stages.nigel = { completedAt, durationMs, status: "success" }`
 3. Update queue: move feature to `codeyQueue`
 4. If `--pause-after=nigel`: Show test paths, ask user to continue
@@ -349,13 +433,9 @@ Unless `--no-feedback` flag is set:
 
 **Prompt addition to Codey (Plan phase):**
 ```
-FIRST, before creating the plan, evaluate Nigel's tests:
-- Rating (1-5): How implementable are the tests?
-- Issues: List any problems (e.g., "over-mocked", "missing-setup")
-- Recommendation: "proceed" | "pause" | "revise"
-
-Output your feedback as:
-FEEDBACK: { "rating": N, "issues": [...], "recommendation": "..." }
+FEEDBACK FIRST: Rate Nigel's tests 1-5, list issues (e.g., over-mocked), recommend proceed|pause|revise.
+Format: FEEDBACK: {"rating":N,"issues":["..."],"rec":"proceed|pause|revise"}
+Then continue with your task.
 ```
 
 **Quality Gate Check:** Same as Step 6.5
@@ -368,31 +448,47 @@ FEEDBACK: { "rating": N, "issues": [...], "recommendation": "..." }
 
 **History:** Record `stages.codeyPlan.startedAt` before spawning.
 
+**Runtime prompt:** `.blueprint/prompts/codey-plan-runtime.md`
+
 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
+## Task
 
-## Your Task
-Create an implementation plan for feature "{slug}". Do NOT implement yet.
+Create an implementation plan for feature "{slug}". Do NOT implement yet - planning only.
 
 ## Inputs (read these files)
-- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md
-- Stories: {FEAT_DIR}/story-*.md
+- Handoff Summary: {FEAT_DIR}/handoff-nigel.md (read FIRST for quick context)
 - Test Spec: {TEST_DIR}/test-spec.md
 - Tests: {TEST_FILE}
+- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md (if additional context needed)
+- Stories: {FEAT_DIR}/story-*.md (if additional context needed)
 
-## Output (write this file)
+## Outputs (write this file)
 Write implementation plan to: {FEAT_DIR}/IMPLEMENTATION_PLAN.md
 
-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)
+Plan structure (aim for under 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)
+
+## Rules
+- Read Nigel's handoff summary FIRST for quick orientation
+- Do NOT write implementation code in this phase
+- Keep plan concise and actionable
+- Order steps to make tests pass incrementally
+- Identify which tests each step addresses
+- Prefer editing existing files over creating new ones
+
+## Completion
+Brief summary: files planned, step count, identified risks
+
+## Reference
+For detailed guidance, see: .blueprint/agents/AGENT_DEVELOPER_CODEY.md
 ```
 
 **On completion:**
@@ -408,42 +504,46 @@ Plan structure (keep concise - aim for <80 lines total):
 
 **History:** Record `stages.codeyImplement.startedAt` before spawning.
 
+**Runtime prompt:** `.blueprint/prompts/codey-implement-runtime.md`
+
 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
+## Task
 
-## Your Task
-Implement feature "{slug}" according to the plan.
+Implement feature "{slug}" according to the plan. Work incrementally, making tests pass one group at a time.
 
 ## Inputs (read these files)
+- Handoff Summary: {FEAT_DIR}/handoff-nigel.md (read FIRST for quick context)
 - Implementation Plan: {FEAT_DIR}/IMPLEMENTATION_PLAN.md
 - Tests: {TEST_FILE}
 
 ## Process (INCREMENTAL - one file at a time)
-1. Run tests: node --test {TEST_FILE}
-2. For each failing test group:
+1. Read Nigel's handoff summary for orientation
+2. Run tests first: node --test {TEST_FILE}
+3. For each failing test group:
    a. Identify the minimal code needed
-   b. Write/edit ONE file
+   b. Write or edit ONE file
    c. Run tests again
    d. Repeat until group passes
 3. Move to next test group
 
-## Output Rules
+## 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
+- Keep functions small (under 30 lines)
+- Code should be self-documenting, minimal comments
 - Do NOT commit changes
 - Do NOT modify test assertions unless they contain bugs
 
 ## Completion
 Brief summary: files changed (list), test status (X/Y passing), blockers if any
+
+## Reference
+For detailed guidance, see: .blueprint/agents/AGENT_DEVELOPER_CODEY.md
 ```
 
 **On completion:**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestr8",
-  "version": "2.6.0",
+  "version": "2.7.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/agent-workflow.git"
+    "url": "git+https://github.com/NewmanJustice/orchestr8.git"
   },
   "license": "MIT",
   "engines": {

package/src/business-context.js

@@ -0,0 +1,91 @@
+/**
+ * Business context detection and conditional inclusion module.
+ *
+ * Implements lazy loading of business context by detecting references
+ * in feature specs and conditionally including the context directive
+ * based on agent name and detection results.
+ */
+
+/**
+ * Detects if a feature spec content references business context.
+ * Matches '.business_context' or 'business_context/' patterns.
+ *
+ * @param {string} featureSpecContent - The content of the feature spec
+ * @returns {boolean} True if business context references are found
+ */
+function needsBusinessContext(featureSpecContent) {
+  return featureSpecContent.includes('.business_context')
+    || featureSpecContent.includes('business_context/');
+}
+
+/**
+ * Parses command arguments for the --include-business-context flag.
+ *
+ * @param {string[]} args - Array of command line arguments
+ * @returns {boolean} True if the flag is present
+ */
+function parseIncludeBusinessContextFlag(args) {
+  return args.includes('--include-business-context');
+}
+
+/**
+ * Determines if an agent should receive business context.
+ * Alex always gets business context (exception).
+ * Override flag forces inclusion for all agents.
+ * Otherwise, uses detection result.
+ *
+ * @param {string} agentName - Name of the agent (alex, cass, nigel, codey)
+ * @param {boolean} detected - Whether business context was detected in spec
+ * @param {boolean} overrideFlag - Whether --include-business-context flag is set
+ * @returns {boolean} True if agent should receive business context
+ */
+function shouldIncludeBusinessContext(agentName, detected, overrideFlag) {
+  // Alex always gets business context
+  if (agentName.toLowerCase() === 'alex') {
+    return true;
+  }
+  // Override flag forces inclusion
+  if (overrideFlag) {
+    return true;
+  }
+  // Otherwise use detection result
+  return detected;
+}
+
+/**
+ * Builds queue state object with business context detection result.
+ *
+ * @param {string} featureSlug - The feature slug identifier
+ * @param {boolean} needsContext - Whether business context is needed
+ * @returns {object} Queue state object
+ */
+function buildQueueState(featureSlug, needsContext) {
+  return {
+    feature: featureSlug,
+    current: {
+      stage: 'pending',
+      needsBusinessContext: needsContext
+    }
+  };
+}
+
+/**
+ * Generates the business context directive for agent prompts.
+ *
+ * @param {boolean} includeContext - Whether to include the directive
+ * @returns {string} The directive string or empty string
+ */
+function generateBusinessContextDirective(includeContext) {
+  if (includeContext) {
+    return 'Business Context: .business_context/';
+  }
+  return '';
+}
+
+module.exports = {
+  needsBusinessContext,
+  parseIncludeBusinessContextFlag,
+  shouldIncludeBusinessContext,
+  buildQueueState,
+  generateBusinessContextDirective
+};