orchestr8 2.6.1 → 2.7.0

package/.blueprint/agents/AGENT_BA_CASS.md

@@ -179,77 +179,7 @@ Explicitly list what is **out of scope** and why deferral is safe.
 
 ## User story template
 
-```markdown
-# Screen [N] — [Title]
-
-## User story
-As a [role], I want [capability] so that [benefit].
-
----
-
-## Context / scope
-- Professional user (Solicitor)
-- England standard possession claim
-- Screen is reached when: [entry condition]
-- Route:
-  - `GET /claims/[route-name]`
-  - `POST /claims/[route-name]`
-- This screen captures: [what data]
-
----
-
-## Acceptance criteria
-
-**AC-1 — [Short description]**
-- Given [precondition],
-- When [action],
-- Then [expected result].
-
-**AC-2 — [Short description]**
-- Given [precondition],
-- When [action],
-- Then [expected result].
-
-<!-- Continue with AC-3, AC-4, etc. -->
-
-**AC-N — Previous navigation**
-- Given I click Previous,
-- Then I am returned to [previous route]
-- And any entered data is preserved in session.
-
-**AC-N+1 — Continue navigation**
-- Given I click Continue and validation passes,
-- Then I am redirected to [next route].
-
-**AC-N+2 — Cancel behaviour**
-- Given I click Cancel,
-- Then I am returned to /case-list
-- And the claim draft remains stored in session.
-
-**AC-N+3 — Accessibility compliance**
-- Given validation errors occur,
-- Then:
-  - a GOV.UK error summary is displayed at the top of the page,
-  - errors link to the relevant field,
-  - focus moves to the error summary,
-  - and all inputs are properly labelled and keyboard accessible.
-
----
-
-## Session persistence
-
-```js
-session.claim.fieldName = {
-  property: 'value' | null
-}
-```
-
----
-
-## Out of scope
-- [Item 1]
-- [Item 2]
-```
+See: `.blueprint/templates/STORY_TEMPLATE.md`
 
 ---
 
@@ -382,44 +312,4 @@ You have done your job well when:
 
 ## Guardrails
 
-### Allowed Sources
-You may use ONLY information from these sources:
-- System specification (`.blueprint/system_specification/SYSTEM_SPEC.md`)
-- Feature specifications (`.blueprint/features/*/FEATURE_SPEC.md`)
-- User stories (`story-*.md`) and test artifacts (`test-spec.md`, `*.test.js`)
-- Implementation code in the project
-- Business context (`.business_context/*`)
-- Templates (`.blueprint/templates/*`) and agent specifications
-
-### Prohibited Sources
-Do not use:
-- Social media, forums, blog posts, or external APIs
-- Training data for domain facts—do not invent business rules
-- External project or company references by name
-
-### Citation Requirements
-- Cite sources using: "Per [filename]: [claim]" or "[filename:section] states..."
-- Use section-level citations where feasible (e.g., "story-login.md:AC-3")
-- Reference `.business_context/` files for domain definitions
-- Maintain a traceable chain: downstream artifacts cite upstream sources
-
-### Assumptions vs Facts
-- Label assumptions explicitly: "ASSUMPTION: [statement]" or "NOTE: Assuming..."
-- Distinguish clearly between cited facts and assumptions
-- Do not guess—state "This information is not available in the provided inputs"
-
-### Confidentiality
-- Do not reproduce `.business_context/` content verbatim; summarise or use generic descriptions
-- Do not reference external entities, companies, or projects by name
-- Do not use external services that would expose project data
-- Outputs must be self-contained and understandable without access to confidential sources
-
-### Escalation Protocol
-Escalate to the user when:
-- Critical information is missing and cannot be safely assumed
-- Inputs are ambiguous with multiple possible interpretations—list options and ask for clarification
-- Source documents conflict—cite both sources and request resolution
-- Output would require violating confidentiality constraints
-
-When escalation is not warranted, you may proceed with an explicit assumption labelled as such.
-
+Read and apply the shared guardrails from: `.blueprint/agents/GUARDRAILS.md`

package/.blueprint/agents/AGENT_DEVELOPER_CODEY.md

@@ -425,43 +425,4 @@ By following this guide, Codey and Nigel can work together in a tight loop: Nige
 
 ## Guardrails
 
-### Allowed Sources
-You may use ONLY information from these sources:
-- System specification (`.blueprint/system_specification/SYSTEM_SPEC.md`)
-- Feature specifications (`.blueprint/features/*/FEATURE_SPEC.md`)
-- User stories (`story-*.md`) and test artifacts (`test-spec.md`, `*.test.js`)
-- Implementation code in the project
-- Business context (`.business_context/*`)
-- Templates (`.blueprint/templates/*`) and agent specifications
-
-### Prohibited Sources
-Do not use:
-- Social media, forums, blog posts, or external APIs
-- Training data for domain facts—do not invent business rules
-- External project or company references by name
-
-### Citation Requirements
-- Cite sources using: "Per [filename]: [claim]" or "[filename:section] states..."
-- Use section-level citations where feasible (e.g., "story-login.md:AC-3")
-- Reference `.business_context/` files for domain definitions
-- Maintain a traceable chain: downstream artifacts cite upstream sources
-
-### Assumptions vs Facts
-- Label assumptions explicitly: "ASSUMPTION: [statement]" or "NOTE: Assuming..."
-- Distinguish clearly between cited facts and assumptions
-- Do not guess—state "This information is not available in the provided inputs"
-
-### Confidentiality
-- Do not reproduce `.business_context/` content verbatim; summarise or use generic descriptions
-- Do not reference external entities, companies, or projects by name
-- Do not use external services that would expose project data
-- Outputs must be self-contained and understandable without access to confidential sources
-
-### Escalation Protocol
-Escalate to the user when:
-- Critical information is missing and cannot be safely assumed
-- Inputs are ambiguous with multiple possible interpretations—list options and ask for clarification
-- Source documents conflict—cite both sources and request resolution
-- Output would require violating confidentiality constraints
-
-When escalation is not warranted, you may proceed with an explicit assumption labelled as such.
+Read and apply the shared guardrails from: `.blueprint/agents/GUARDRAILS.md`

package/.blueprint/agents/AGENT_SPECIFICATION_ALEX.md

@@ -168,43 +168,4 @@ He ensures that what gets built is:
 
 ## Guardrails
 
-### Allowed Sources
-You may use ONLY information from these sources:
-- System specification (`.blueprint/system_specification/SYSTEM_SPEC.md`)
-- Feature specifications (`.blueprint/features/*/FEATURE_SPEC.md`)
-- User stories (`story-*.md`) and test artifacts (`test-spec.md`, `*.test.js`)
-- Implementation code in the project
-- Business context (`.business_context/*`)
-- Templates (`.blueprint/templates/*`) and agent specifications
-
-### Prohibited Sources
-Do not use:
-- Social media, forums, blog posts, or external APIs
-- Training data for domain facts—do not invent business rules
-- External project or company references by name
-
-### Citation Requirements
-- Cite sources using: "Per [filename]: [claim]" or "[filename:section] states..."
-- Use section-level citations where feasible (e.g., "story-login.md:AC-3")
-- Reference `.business_context/` files for domain definitions
-- Maintain a traceable chain: downstream artifacts cite upstream sources
-
-### Assumptions vs Facts
-- Label assumptions explicitly: "ASSUMPTION: [statement]" or "NOTE: Assuming..."
-- Distinguish clearly between cited facts and assumptions
-- Do not guess—state "This information is not available in the provided inputs"
-
-### Confidentiality
-- Do not reproduce `.business_context/` content verbatim; summarise or use generic descriptions
-- Do not reference external entities, companies, or projects by name
-- Do not use external services that would expose project data
-- Outputs must be self-contained and understandable without access to confidential sources
-
-### Escalation Protocol
-Escalate to the user when:
-- Critical information is missing and cannot be safely assumed
-- Inputs are ambiguous with multiple possible interpretations—list options and ask for clarification
-- Source documents conflict—cite both sources and request resolution
-- Output would require violating confidentiality constraints
-
-When escalation is not warranted, you may proceed with an explicit assumption labelled as such.
+Read and apply the shared guardrails from: `.blueprint/agents/GUARDRAILS.md`

package/.blueprint/agents/AGENT_TESTER_NIGEL.md

@@ -52,17 +52,9 @@ If critical information is missing or ambiguous, you should:
 
 **IMPORTANT: Write files ONE AT A TIME to avoid token limits.**
 
-Produce exactly 2 files:
+Produce exactly 2 files: **test-spec.md** and an **executable test file**.
 
-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)
-
-2. **Executable test file** (write SECOND)
-   - One `describe` block per user story
-   - One `it` block per acceptance criterion
-   - Self-documenting test names - minimal comments 
+See: `.blueprint/templates/TEST_TEMPLATE.md` for detailed format guidance. 
 
 ## 3. Standard workflow
 
@@ -173,44 +165,4 @@ When you receive a new story or feature, you can structure your response like th
 
 ## Guardrails
 
-### Allowed Sources
-You may use ONLY information from these sources:
-- System specification (`.blueprint/system_specification/SYSTEM_SPEC.md`)
-- Feature specifications (`.blueprint/features/*/FEATURE_SPEC.md`)
-- User stories (`story-*.md`) and test artifacts (`test-spec.md`, `*.test.js`)
-- Implementation code in the project
-- Business context (`.business_context/*`)
-- Templates (`.blueprint/templates/*`) and agent specifications
-
-### Prohibited Sources
-Do not use:
-- Social media, forums, blog posts, or external APIs
-- Training data for domain facts—do not invent business rules
-- External project or company references by name
-
-### Citation Requirements
-- Cite sources using: "Per [filename]: [claim]" or "[filename:section] states..."
-- Use section-level citations where feasible (e.g., "story-login.md:AC-3")
-- Reference `.business_context/` files for domain definitions
-- Maintain a traceable chain: downstream artifacts cite upstream sources
-
-### Assumptions vs Facts
-- Label assumptions explicitly: "ASSUMPTION: [statement]" or "NOTE: Assuming..."
-- Distinguish clearly between cited facts and assumptions
-- Do not guess—state "This information is not available in the provided inputs"
-
-### Confidentiality
-- Do not reproduce `.business_context/` content verbatim; summarise or use generic descriptions
-- Do not reference external entities, companies, or projects by name
-- Do not use external services that would expose project data
-- Outputs must be self-contained and understandable without access to confidential sources
-
-### Escalation Protocol
-Escalate to the user when:
-- Critical information is missing and cannot be safely assumed
-- Inputs are ambiguous with multiple possible interpretations—list options and ask for clarification
-- Source documents conflict—cite both sources and request resolution
-- Output would require violating confidentiality constraints
-
-When escalation is not warranted, you may proceed with an explicit assumption labelled as such.
-
+Read and apply the shared guardrails from: `.blueprint/agents/GUARDRAILS.md`

package/.blueprint/agents/GUARDRAILS.md

@@ -0,0 +1,42 @@
+# Guardrails
+
+### Allowed Sources
+You may use ONLY information from these sources:
+- System specification (`.blueprint/system_specification/SYSTEM_SPEC.md`)
+- Feature specifications (`.blueprint/features/*/FEATURE_SPEC.md`)
+- User stories (`story-*.md`) and test artifacts (`test-spec.md`, `*.test.js`)
+- Implementation code in the project
+- Business context (`.business_context/*`)
+- Templates (`.blueprint/templates/*`) and agent specifications
+
+### Prohibited Sources
+Do not use:
+- Social media, forums, blog posts, or external APIs
+- Training data for domain facts—do not invent business rules
+- External project or company references by name
+
+### Citation Requirements
+- Cite sources using: "Per [filename]: [claim]" or "[filename:section] states..."
+- Use section-level citations where feasible (e.g., "story-login.md:AC-3")
+- Reference `.business_context/` files for domain definitions
+- Maintain a traceable chain: downstream artifacts cite upstream sources
+
+### Assumptions vs Facts
+- Label assumptions explicitly: "ASSUMPTION: [statement]" or "NOTE: Assuming..."
+- Distinguish clearly between cited facts and assumptions
+- Do not guess—state "This information is not available in the provided inputs"
+
+### Confidentiality
+- Do not reproduce `.business_context/` content verbatim; summarise or use generic descriptions
+- Do not reference external entities, companies, or projects by name
+- Do not use external services that would expose project data
+- Outputs must be self-contained and understandable without access to confidential sources
+
+### Escalation Protocol
+Escalate to the user when:
+- Critical information is missing and cannot be safely assumed
+- Inputs are ambiguous with multiple possible interpretations—list options and ask for clarification
+- Source documents conflict—cite both sources and request resolution
+- Output would require violating confidentiality constraints
+
+When escalation is not warranted, you may proceed with an explicit assumption labelled as such.

package/.blueprint/features/feature_compressed-feedback/FEATURE_SPEC.md

@@ -0,0 +1,136 @@
+# Feature Specification — Compressed Feedback Prompts
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Current feedback prompts are verbose (~10 lines, ~200 tokens per stage)
+- Feedback is collected at 3 points: Cass→Alex, Nigel→Cass, Codey→Nigel
+- Total overhead: ~600 tokens per pipeline run
+- Compressed prompts achieve same result with ~3 lines each
+
+---
+
+## 2. Scope
+### In Scope
+- Rewrite feedback prompt sections to be more concise
+- Maintain same output format (JSON with rating, issues, recommendation)
+- Ensure feedback quality is not degraded
+
+### Out of Scope
+- Changing feedback data structure
+- Removing feedback collection
+- Changing quality gate thresholds
+
+---
+
+## 3. Actors Involved
+
+| Actor | Feedback Role |
+|-------|--------------|
+| Cass | Rates Alex's feature spec |
+| Nigel | Rates Cass's user stories |
+| Codey | Rates Nigel's tests |
+
+---
+
+## 4. Behaviour Overview
+
+**Current verbose prompt (~10 lines):**
+```
+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": "..." }
+```
+
+**Compressed prompt (~3 lines):**
+```
+FEEDBACK FIRST: Rate prior stage 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.
+```
+
+**Key outcomes:**
+- ~400 fewer tokens per pipeline run (3 stages × ~130 token savings)
+- Same feedback data collected
+- Same quality gate functionality
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- No state changes
+- Feedback format unchanged
+- Quality gate logic unchanged
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description |
+|------|-------------|
+| Same output format | JSON structure must remain compatible with feedback.js |
+| Abbreviations allowed | "rec" instead of "recommendation" in output |
+| Examples condensed | One inline example instead of multiple lines |
+
+---
+
+## 7. Dependencies
+
+- SKILL.md feedback sections updated
+- `src/feedback.js` may need to accept abbreviated keys ("rec" → "recommendation")
+- No other module changes
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Performance:** ~400 token reduction per run
+- **Clarity:** Compressed prompts must still be unambiguous
+- **Risk:** Agents may misinterpret terse instructions
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- Agents can parse terse instructions correctly
+- Abbreviated JSON keys are acceptable
+- Feedback quality won't degrade with shorter prompts
+
+**Open Questions:**
+- Should we A/B test compressed vs verbose prompts?
+- Is "rec" acceptable or should we keep "recommendation"?
+- Do we need to update feedback.js to normalize keys?
+
+---
+
+## 10. Impact on System Specification
+
+- No impact on system specification
+- Feedback behaviour unchanged
+- Quality gates unchanged
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Story themes:**
+- Rewrite Cass feedback prompt (rates Alex)
+- Rewrite Nigel feedback prompt (rates Cass)
+- Rewrite Codey feedback prompt (rates Nigel)
+- Update feedback.js if key normalization needed
+
+**Expected story boundaries:**
+- One story for prompt compression (all 3 stages)
+- One story for feedback.js updates if needed
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|-----|------|--------|-----------|
+| 2026-02-25 | Initial spec | Token efficiency improvement | Claude |

package/.blueprint/features/feature_compressed-feedback/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,40 @@
+# Implementation Plan — Compressed Feedback Prompts
+
+## Summary
+
+Compress verbose feedback prompts (~10 lines) to terse format (~3 lines) across three pipeline stages (Cass, Nigel, Codey). Update `src/feedback.js` to normalize the abbreviated "rec" key to "recommendation" and add a parsing function for extracting feedback JSON from agent output.
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `SKILL.md` | Modify | Compress feedback prompts in Steps 6.5, 7.5, 8.5 |
+| `src/feedback.js` | Modify | Add key normalization and output parsing functions |
+
+## Implementation Steps
+
+1. **Add `normalizeFeedbackKeys()` to feedback.js** — Function that converts `{rec: "..."}` to `{recommendation: "..."}` while preserving existing full key.
+
+2. **Add `parseFeedbackFromOutput()` to feedback.js** — Regex-based parser to extract `FEEDBACK: {...}` JSON from agent output text.
+
+3. **Update `validateFeedback()` in feedback.js** — Accept both "rec" and "recommendation" keys by checking either before validation.
+
+4. **Export new functions from feedback.js** — Add `normalizeFeedbackKeys` and `parseFeedbackFromOutput` to module.exports.
+
+5. **Compress Step 6.5 prompt in SKILL.md** — Replace Cass→Alex verbose prompt with:
+   ```
+   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.
+   ```
+
+6. **Compress Step 7.5 prompt in SKILL.md** — Replace Nigel→Cass verbose prompt with similar terse format.
+
+7. **Compress Step 8.5 prompt in SKILL.md** — Replace Codey→Nigel verbose prompt with similar terse format.
+
+8. **Run tests** — Execute `node --test test/feature_compressed-feedback.test.js` to verify implementation.
+
+## Risks/Questions
+
+- **Agent interpretation:** Terse prompts may occasionally confuse agents; monitor initial runs for correct feedback format.
+- **Key preference:** If both "rec" and "recommendation" appear, current implementation prefers "recommendation" — this matches test expectations.

package/.blueprint/features/feature_lazy-business-context/FEATURE_SPEC.md

@@ -0,0 +1,140 @@
+# Feature Specification — Lazy Business Context Loading
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Currently all agents are told to read `.business_context/*` directory
+- Many features don't require business context
+- Reading unnecessary files wastes tokens and processing time
+- Lazy loading reads business context only when the feature spec references it
+
+---
+
+## 2. Scope
+### In Scope
+- Detect whether feature spec cites `.business_context/` files
+- Include business context in agent prompt only if referenced
+- Provide mechanism for agents to request business context if needed mid-task
+
+### Out of Scope
+- Changing business context structure
+- Removing business context capability
+- Automatic business context summarization
+
+---
+
+## 3. Actors Involved
+
+| Actor | Business Context Usage |
+|-------|----------------------|
+| Alex | Primary consumer — grounds feature specs in domain context |
+| Cass | Secondary — references for domain terminology |
+| Nigel | Rare — may need for domain-specific test data |
+| Codey | Rare — may need for domain-specific implementation |
+
+---
+
+## 4. Behaviour Overview
+
+**Happy path (context needed):**
+1. Feature spec contains citation: "Per business_context/domain.md: ..."
+2. Pipeline detects citation during setup
+3. Agent prompt includes: "Business Context: .business_context/"
+4. Agent reads and applies business context
+
+**Happy path (context not needed):**
+1. Feature spec has no business context citations
+2. Pipeline skips business context directive
+3. Agent prompt omits business context reference
+4. Tokens saved
+
+**Detection logic:**
+```javascript
+const featureSpecContent = readFile(FEAT_SPEC);
+const needsBusinessContext = featureSpecContent.includes('.business_context')
+  || featureSpecContent.includes('business_context/');
+```
+
+**Key outcomes:**
+- Variable token savings (depends on business context size)
+- Faster processing for simple features
+- Business context still available when needed
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- No persistent state changes
+- Detection happens at pipeline setup (Step 5)
+- Flag stored in queue: `current.needsBusinessContext: boolean`
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description |
+|------|-------------|
+| Citation detection | Scan feature spec for business_context references |
+| Default to exclude | If no citation found, don't include business context |
+| Alex exception | Alex always has access (creates feature specs from business context) |
+| Explicit include | `--include-business-context` flag overrides detection |
+
+---
+
+## 7. Dependencies
+
+- SKILL.md updated with conditional business context inclusion
+- Pipeline setup (Step 5) performs detection
+- Queue stores detection result for downstream agents
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Performance:** Token savings proportional to business context size
+- **Correctness:** Risk of missing needed context if detection fails
+- **Flexibility:** Override flag provides escape hatch
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- Feature specs reliably cite business context when it's used
+- Detection can be simple string matching
+- Alex stage always needs business context access
+
+**Open Questions:**
+- Should detection be more sophisticated (AST parsing)?
+- What if an agent needs business context mid-task but it wasn't loaded?
+- Should there be a "request context" mechanism for agents?
+
+---
+
+## 10. Impact on System Specification
+
+- Reinforces efficiency goals
+- Adds conditional loading pattern to pipeline
+- No contradiction with system spec
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Story themes:**
+- Implement business context citation detection
+- Update pipeline setup to conditionally include context
+- Add override flag for explicit inclusion
+- Ensure Alex always has business context access
+
+**Expected story boundaries:**
+- One story for detection logic
+- One story for pipeline integration
+- One story for override flag
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|-----|------|--------|-----------|
+| 2026-02-25 | Initial spec | Token efficiency improvement | Claude |