orchestr8 2.6.0 → 2.7.0

package/.blueprint/features/feature_template-extraction/FEATURE_SPEC.md

@@ -0,0 +1,134 @@
+# Feature Specification — Template Extraction
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Agent specs contain verbose template sections and examples (~70-100 lines each)
+- Templates are reference material, not needed for every invocation
+- Extracting templates to separate files reduces base agent spec size
+- Agents can read templates only when creating new artifacts
+
+---
+
+## 2. Scope
+### In Scope
+- Extract user story template from Cass spec → `.blueprint/templates/STORY_TEMPLATE.md`
+- Extract test template from Nigel spec → `.blueprint/templates/TEST_TEMPLATE.md`
+- Extract interaction templates from agent specs
+- Trim workflow sections to concise bullet points
+- Update agent specs to reference templates by path
+
+### Out of Scope
+- Changing template content
+- Removing templates entirely
+- Creating new templates
+
+---
+
+## 3. Actors Involved
+
+| Actor | Template Used | When |
+|-------|--------------|------|
+| Cass | STORY_TEMPLATE.md | When writing new stories |
+| Nigel | TEST_TEMPLATE.md | When writing new tests |
+| Codey | None extracted | Workflow condensed only |
+| Alex | FEATURE_SPEC.md (existing) | When writing feature specs |
+
+---
+
+## 4. Behaviour Overview
+
+**Happy path:**
+1. Agent receives task prompt
+2. Agent reads slim spec (templates removed)
+3. When creating artifact, agent reads relevant template file
+4. Agent uses template structure for output
+
+**Content to extract:**
+
+| From | Content | To |
+|------|---------|-----|
+| AGENT_BA_CASS.md | User story template (~70 lines) | STORY_TEMPLATE.md |
+| AGENT_TESTER_NIGEL.md | Test output format (~30 lines) | TEST_TEMPLATE.md |
+| All agents | Verbose workflow steps | Condensed to ~10 bullets each |
+
+**Key outcomes:**
+- ~800 fewer tokens in agent specs
+- Templates still available when needed
+- Specs more focused on behaviour, less on format
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- No state changes
+- Templates are static reference files
+- No pipeline flow changes
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description |
+|------|-------------|
+| Reference not inline | Agent specs reference templates, don't inline them |
+| Read when needed | Agents read templates only when creating that artifact type |
+| Templates are examples | Templates show structure, not mandatory content |
+
+---
+
+## 7. Dependencies
+
+- `.blueprint/templates/` directory (already exists)
+- Agent spec files updated
+- SKILL.md prompts may need to specify "read template from X"
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Performance:** ~800 token reduction in agent specs
+- **Maintainability:** Templates can be updated independently of agent specs
+- **Clarity:** Agent specs focus on behaviour, templates on format
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- Agents can follow references to read template files
+- Templates are used infrequently enough that lazy loading is beneficial
+- Condensed workflow bullets provide sufficient guidance
+
+**Open Questions:**
+- Should templates be versioned separately from agent specs?
+- How much can workflow sections be condensed without losing clarity?
+
+---
+
+## 10. Impact on System Specification
+
+- Reinforces separation of concerns (behaviour vs format)
+- No contradiction with system spec
+- No system spec change required
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Story themes:**
+- Extract Cass story template to separate file
+- Extract Nigel test template to separate file
+- Condense workflow sections in all agent specs
+- Update agent specs to reference templates
+
+**Expected story boundaries:**
+- One story for template extraction
+- One story for workflow condensation
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|-----|------|--------|-----------|
+| 2026-02-25 | Initial spec | Token efficiency improvement | Claude |

package/.blueprint/features/feature_template-extraction/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,46 @@
+# Implementation Plan: Template Extraction
+
+## Summary
+
+Extract verbose template sections from AGENT_BA_CASS.md and AGENT_TESTER_NIGEL.md into standalone template files (STORY_TEMPLATE.md and TEST_TEMPLATE.md) in `.blueprint/templates/`. Update agent specs to reference templates by path and condense workflow sections to ~10 bullet points each. This reduces agent spec token count by ~800 tokens while keeping templates accessible when needed.
+
+## Files to Create/Modify
+
+| Action | File | Description |
+|--------|------|-------------|
+| Create | `.blueprint/templates/STORY_TEMPLATE.md` | User story template extracted from Cass spec (lines 180-252) |
+| Create | `.blueprint/templates/TEST_TEMPLATE.md` | Test output format guidance extracted from Nigel spec |
+| Modify | `.blueprint/agents/AGENT_BA_CASS.md` | Remove inline template, add reference, condense workflow |
+| Modify | `.blueprint/agents/AGENT_TESTER_NIGEL.md` | Add template reference, condense workflow section |
+
+## Implementation Steps
+
+1. **Create STORY_TEMPLATE.md** - Extract the user story template block (lines 180-252) from AGENT_BA_CASS.md into `.blueprint/templates/STORY_TEMPLATE.md`. Include the full markdown template with Screen [N], User story, Context/scope, Acceptance criteria, Session persistence, and Out of scope sections.
+
+2. **Create TEST_TEMPLATE.md** - Extract test output format guidance from AGENT_TESTER_NIGEL.md sections 3-5 (test design principles, AC mapping table format, traceability table format) into a standalone template.
+
+3. **Update Cass spec - Remove template** - Replace the inline user story template (lines 180-252) with a reference: `Read the user story template from: .blueprint/templates/STORY_TEMPLATE.md`
+
+4. **Update Cass spec - Condense workflow** - Simplify "Standard workflow" section (lines 127-177) from 5 detailed steps with sub-bullets to ~10 concise top-level bullets covering: understand, clarify, write story, document session, flag deferrals.
+
+5. **Update Nigel spec - Add template reference** - Add reference to TEST_TEMPLATE.md in the "Outputs you must produce" section for detailed format guidance.
+
+6. **Update Nigel spec - Condense workflow** - Simplify section 3 "Standard workflow" (lines 69-109) to ~10 concise bullets covering: understand, map ACs, write spec, write tests, traceability.
+
+7. **Preserve required sections** - Ensure both specs retain: YAML frontmatter, identity sections, job descriptions, input/output sections, collaboration notes, anti-patterns, GUARDRAILS.md reference.
+
+8. **Verify existing templates preserved** - Confirm FEATURE_SPEC.md and SYSTEM_SPEC.md remain unchanged in `.blueprint/templates/`.
+
+9. **Run tests** - Execute `node --test test/feature_template-extraction.test.js` to verify all 16 tests pass.
+
+10. **Manual verification** - Check that condensed workflow sections remain actionable and template references are clear paths.
+
+## Risks/Questions
+
+| Risk | Mitigation |
+|------|------------|
+| Condensed workflows lose critical guidance | Keep essential steps, move details to templates |
+| Test regex patterns may be too strict | Review test patterns if failures occur, adjust template content to match expected patterns |
+| Token savings may vary | Actual reduction depends on final content; ~800 is estimate |
+
+**Open question from spec:** Should templates be versioned separately? Recommendation: No, keep in same repo for now. Templates change rarely and should stay in sync with agent specs.

package/.blueprint/features/feature_upstream-summaries/FEATURE_SPEC.md

@@ -0,0 +1,150 @@
+# Feature Specification — Upstream Summaries
+
+## 1. Feature Intent
+**Why this feature exists.**
+
+- Currently, downstream agents read full upstream artifacts (feature specs, stories, test specs)
+- Codey reads: feature spec + all stories + test spec + plan = potentially 1,000+ lines
+- Much of this content is not needed for the downstream task
+- Structured handoff summaries reduce input tokens by 30-50% for later stages
+
+---
+
+## 2. Scope
+### In Scope
+- Each agent produces a structured "Handoff Summary" at end of output
+- Downstream agents read summary + their direct inputs only
+- Summary format standardized across all agents
+
+### Out of Scope
+- Changing what agents produce (full artifacts still created)
+- Removing ability to read full upstream files if needed
+- Automated summary generation (agents write summaries manually)
+
+---
+
+## 3. Actors Involved
+
+| Actor | Produces Summary For | Reads Summary From |
+|-------|---------------------|-------------------|
+| Alex | Cass | N/A (first in chain) |
+| Cass | Nigel | Alex |
+| Nigel | Codey | Cass |
+| Codey | N/A (last in chain) | Nigel |
+
+---
+
+## 4. Behaviour Overview
+
+**Happy path:**
+1. Alex creates feature spec + writes handoff summary
+2. Cass reads Alex's summary (not full spec), writes stories + handoff summary
+3. Nigel reads Cass's summary + stories, writes tests + handoff summary
+4. Codey reads Nigel's summary + tests + plan, implements
+
+**Handoff summary format:**
+```markdown
+## Handoff Summary
+**For:** {Next Agent}
+**Feature:** {slug}
+
+### Key Decisions
+- {Decision 1}
+- {Decision 2}
+- {Decision 3}
+
+### Files Created
+- {path/to/file1.md}
+- {path/to/file2.md}
+
+### Open Questions
+- {Question if any, or "None"}
+
+### Critical Context
+{1-2 sentences of must-know information}
+```
+
+**Key outcomes:**
+- ~2,000-4,000 fewer tokens for Nigel and Codey stages
+- Faster downstream processing
+- Clearer handoffs between agents
+
+---
+
+## 5. State & Lifecycle Interactions
+
+- Summaries are written to the feature directory
+- New file per stage: `{FEAT_DIR}/handoff-{agent}.md`
+- Pipeline reads summary file paths from queue
+
+---
+
+## 6. Rules & Decision Logic
+
+| Rule | Description |
+|------|-------------|
+| Summary required | Every agent (except Codey-implement) must produce a handoff summary |
+| Max length | Summaries must be <30 lines |
+| No duplication | Don't repeat content that's in the main artifact |
+| Actionable | Focus on what downstream agent needs to know |
+
+---
+
+## 7. Dependencies
+
+- SKILL.md prompts updated to require summaries
+- SKILL.md prompts updated to read summaries instead of full upstream files
+- Queue may need to track summary file paths
+
+---
+
+## 8. Non-Functional Considerations
+
+- **Performance:** 30-50% reduction in downstream agent input tokens
+- **Clarity:** Explicit handoffs improve traceability
+- **Overhead:** Small increase in upstream agent output (~30 lines)
+
+---
+
+## 9. Assumptions & Open Questions
+
+**Assumptions:**
+- Agents can write useful summaries
+- Summaries capture enough context for downstream success
+- Full files remain available if summary is insufficient
+
+**Open Questions:**
+- Should summaries be separate files or appended to main artifacts?
+- What happens if an agent needs info not in the summary?
+- Should the pipeline validate summary quality?
+
+---
+
+## 10. Impact on System Specification
+
+- Reinforces principle of explicit handoffs between agents
+- Adds new artifact type (handoff summaries) to pipeline
+- No contradiction with system spec
+
+---
+
+## 11. Handover to BA (Cass)
+
+**Story themes:**
+- Define handoff summary format
+- Update Alex to produce summary
+- Update Cass to read summary + produce summary
+- Update Nigel to read summary + produce summary
+- Update Codey to read summary
+- Update SKILL.md with new prompt structure
+
+**Expected story boundaries:**
+- One story for summary format definition
+- One story per agent update
+
+---
+
+## 12. Change Log (Feature-Level)
+| Date | Change | Reason | Raised By |
+|-----|------|--------|-----------|
+| 2026-02-25 | Initial spec | Token efficiency improvement | Claude |

package/.blueprint/features/feature_upstream-summaries/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,70 @@
+# Implementation Plan: Upstream Summaries
+
+## Summary
+
+Add structured "Handoff Summary" artifacts to the agent pipeline. Each agent (Alex, Cass, Nigel) will produce a `handoff-{agent}.md` file containing key decisions, files created, open questions, and critical context. SKILL.md prompts will be updated to instruct agents to write summaries and read upstream summaries instead of full artifacts.
+
+---
+
+## Files to Create/Modify
+
+| Path | Action | Purpose |
+|------|--------|---------|
+| `SKILL.md` | Modify | Update Alex/Cass/Nigel prompts to require handoff summary output |
+| `SKILL.md` | Modify | Update Cass/Nigel/Codey prompts to read upstream handoff summary |
+| `SKILL.md` | Modify | Add `{HANDOFF_*}` path variables to Paths table |
+| `src/handoff.js` | Create | Helper functions to parse/validate handoff summary format |
+
+---
+
+## Implementation Steps
+
+1. **Add handoff path variables to SKILL.md**
+   - Add `{HANDOFF_ALEX}`, `{HANDOFF_CASS}`, `{HANDOFF_NIGEL}` to Paths table
+   - Pattern: `{FEAT_DIR}/handoff-{agent}.md`
+   - Tests: T-3.4, T-4.2
+
+2. **Create src/handoff.js helper module**
+   - Export `parseHandoffSummary(content)` function matching test implementation
+   - Export `validateHandoffSummary(content)` for line count and format checks
+   - Export `extractSection(content, sectionName)` for parsing sections
+   - Tests: T-1.1 through T-1.7, T-2.1 through T-2.3
+
+3. **Update Alex prompt in SKILL.md (Step 6)**
+   - Add output: write `{FEAT_DIR}/handoff-alex.md`
+   - Add summary format template to prompt
+   - Specify: `**For:** Cass`, feature slug, key decisions, files created
+   - Tests: T-3.1
+
+4. **Update Cass prompt in SKILL.md (Step 7)**
+   - Add input: read `{FEAT_DIR}/handoff-alex.md` instead of full feature spec
+   - Add output: write `{FEAT_DIR}/handoff-cass.md`
+   - Specify: `**For:** Nigel`
+   - Tests: T-3.2
+
+5. **Update Nigel prompt in SKILL.md (Step 8)**
+   - Add input: read `{FEAT_DIR}/handoff-cass.md` instead of full stories
+   - Add output: write `{FEAT_DIR}/handoff-nigel.md`
+   - Specify: `**For:** Codey`
+   - Tests: T-3.3
+
+6. **Update Codey prompts in SKILL.md (Steps 9, 10)**
+   - Add input: read `{FEAT_DIR}/handoff-nigel.md` instead of full test spec
+   - No output summary (last in chain)
+   - Tests: T-4.1
+
+7. **Update queue structure for handoff paths (optional)**
+   - Add `upstreamSummary` field to queue entries if needed for recovery
+   - Tests: T-4.1
+
+8. **Run tests and verify**
+   - Execute `node --test test/feature_upstream-summaries.test.js`
+   - All 15 tests should pass
+
+---
+
+## Risks/Questions
+
+- **Backward compatibility**: Existing features without handoff files may break if prompts strictly require them. Mitigation: Add "if exists" fallback in prompts.
+- **Token savings**: Actual savings depend on how well agents write concise summaries. May need guidance on brevity.
+- **Full file access**: Spec says full files remain available. Consider adding "For additional context, see: {path}" to summaries.

package/.blueprint/prompts/TEMPLATE.md

@@ -0,0 +1,65 @@
+# Runtime Prompt Template
+
+This template defines the standard structure for slim runtime prompts. Each runtime prompt should have 30-50 non-blank lines.
+
+## Structure
+
+Every runtime prompt must follow this structure:
+
+### 1. Role Identity Line (required)
+
+Start with: `You are {Name}, the {Role} Agent.`
+
+### 2. Task Section (required)
+
+```markdown
+## Task
+{Brief description of what this agent must accomplish in this invocation}
+```
+
+### 3. Inputs Section (required)
+
+```markdown
+## Inputs (read these files)
+- {Input 1}: {path/to/file.md}
+- {Input 2}: {path/to/directory/}
+```
+
+### 4. Outputs Section (required)
+
+```markdown
+## Outputs (write these files)
+- {Output file}: {path/to/output.md}
+
+{Brief format requirements}
+```
+
+### 5. Rules Section (required)
+
+```markdown
+## Rules
+- {Rule 1 - most critical constraint}
+- {Rule 2}
+- {Rule 3}
+- {Rule 4}
+- {Rule 5}
+- {Rule 6 - optional}
+- {Rule 7 - optional}
+```
+
+Include 5-7 rules. Focus on critical constraints only. Do NOT duplicate information already in the task or outputs sections. Avoid redundant or repetitive rules.
+
+### 6. Full Spec Reference (required)
+
+```markdown
+## Reference
+For detailed guidance, see: .blueprint/agents/AGENT_{NAME}.md
+```
+
+## Guidelines
+
+- Target: 30-50 non-blank lines per runtime prompt
+- Be concise: every line should add value
+- No boilerplate: skip sections that would be empty
+- Task-specific: include only what this invocation needs
+- Reference full spec: agents can read detailed guidance if needed

package/.blueprint/prompts/alex-runtime.md

@@ -0,0 +1,48 @@
+You are Alex, the System Specification Agent.
+
+## Task
+
+Create a feature specification that translates system intent into a bounded, reviewable unit. The feature spec serves as the contract between business requirements and implementation.
+
+## Inputs (read these files)
+
+- System Spec: .blueprint/system_specification/SYSTEM_SPEC.md
+- Template: .blueprint/templates/FEATURE_SPEC.md
+- Business Context: .business_context/
+
+## Outputs (write this file)
+
+Write feature spec to: {FEAT_DIR}/FEATURE_SPEC.md
+
+Include these sections (skip if not applicable):
+- Feature intent (problem it solves, why it exists)
+- In-scope / out-of-scope boundaries
+- Primary and secondary actors
+- State and lifecycle interactions
+- Rules and decision logic
+- Dependencies
+- Assumptions and open questions
+
+## Rules
+
+- Write file incrementally, section by section if large
+- Reference system spec by path, do not repeat its content
+- Keep Change Log to 1-2 entries maximum
+- Flag ambiguities explicitly rather than guessing
+- Ensure feature aligns with system boundaries
+- Make inferred interpretations explicit
+- Propose breaking changes only with clear justification
+
+## Output Format
+
+- Use Markdown with clear headings
+- Keep sections concise and scannable
+- Include only sections relevant to this feature
+
+## Completion
+
+Brief summary (5 bullets max): intent, key behaviours, scope, story themes, tensions.
+
+## Reference
+
+For detailed guidance, see: .blueprint/agents/AGENT_SPECIFICATION_ALEX.md

package/.blueprint/prompts/cass-runtime.md

@@ -0,0 +1,45 @@
+You are Cass, the Story Writer Agent.
+
+## Task
+
+Create user stories with acceptance criteria from the feature specification. Stories must be explicit, testable, and provide a stable behavioural contract for testing and implementation.
+
+## Inputs (read these files)
+
+- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md
+- System Spec: .blueprint/system_specification/SYSTEM_SPEC.md
+
+## Outputs (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 file must include:
+- User story in standard format (As a... I want... so that...)
+- Acceptance criteria (Given/When/Then format)
+- Out of scope items (brief list)
+
+## Rules
+
+- Write ONE story file at a time, then move to next
+- Keep each story focused with 5-7 acceptance criteria maximum
+- Split large stories into multiple files
+- Make routing explicit (Previous, Continue, conditional paths)
+- Reference feature spec by path for shared context
+- Do not guess policy or legal detail without flagging assumptions
+- Avoid implicit behaviour - all routes must be explicit
+
+## Output Format
+
+Use consistent Markdown structure:
+- AC-1, AC-2, etc. for acceptance criteria
+- Given/When/Then for each criterion
+- Clear section headers
+
+## Completion
+
+Brief summary: story count, filenames, behaviours covered (5 bullets max).
+
+## Reference
+
+For detailed guidance, see: .blueprint/agents/AGENT_BA_CASS.md

package/.blueprint/prompts/codey-implement-runtime.md

@@ -0,0 +1,50 @@
+You are Codey, the Developer Agent.
+
+## Task
+
+Implement the feature according to the plan. Work incrementally, making tests pass one group at a time.
+
+## Inputs (read these files)
+
+- Implementation Plan: {FEAT_DIR}/IMPLEMENTATION_PLAN.md
+- Tests: {TEST_FILE}
+
+## Process (INCREMENTAL - one file at a time)
+
+1. Run tests first: node --test {TEST_FILE}
+2. For each failing test group:
+   a. Identify the minimal code needed
+   b. Write or edit ONE file
+   c. Run tests again
+   d. Repeat until group passes
+3. Move to next test group
+
+## Outputs
+
+- Source files as specified in the implementation plan
+- All tests passing
+
+## Rules
+
+- Write ONE source file at a time
+- Run tests after each file write
+- 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
+- Prefer editing existing files over creating new ones
+
+## Implementation Principles
+
+- Clarity over cleverness
+- Match existing patterns in the codebase
+- Validate inputs defensively
+- Handle errors gracefully
+
+## 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

package/.blueprint/prompts/codey-plan-runtime.md

@@ -0,0 +1,46 @@
+You are Codey, the Developer Agent.
+
+## Task
+
+Create an implementation plan for the feature. Do NOT implement yet - planning only. The plan guides incremental implementation against the test suite.
+
+## Inputs (read these files)
+
+- Feature Spec: {FEAT_DIR}/FEATURE_SPEC.md
+- Stories: {FEAT_DIR}/story-*.md
+- Test Spec: {TEST_DIR}/test-spec.md
+- Tests: {TEST_FILE}
+
+## Outputs (write this file)
+
+Write implementation plan to: {FEAT_DIR}/IMPLEMENTATION_PLAN.md
+
+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
+
+- 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
+- Keep functions small (under 30 lines)
+- Flag dependencies between steps
+
+## Planning Principles
+
+- Work against tests as the primary contract
+- Separate concerns: routes, controllers, helpers
+- Plan for incremental verification after each step
+
+## Completion
+
+Brief summary: files planned, step count, identified risks.
+
+## Reference
+
+For detailed guidance, see: .blueprint/agents/AGENT_DEVELOPER_CODEY.md