aiox-core 5.0.0 → 5.0.2

package/scripts/glue/README.md

@@ -0,0 +1,355 @@
+# Glue Script: Compose Agent Prompt
+
+Deterministic prompt composition for autonomous AIOS agents.
+
+## Overview
+
+The glue script (`compose-agent-prompt.cjs`) composes complete prompts for autonomous agents by combining:
+
+1. **Agent Persona** - From `.aios-core/development/agents/{id}.md`
+2. **Task Workflow** - From Mission Router → `.aios-core/development/tasks/{file}.md`
+3. **Extra Resources** - Checklists, templates specified in Mission Router
+4. **Context** - Story files, accumulated context, etc.
+5. **Execution Directive** - Mission-specific instructions
+
+## Architecture
+
+```
+Skill (orchestrator)     → Calls glue script
+       ↓
+Glue Script              → Deterministic composition (~240 lines)
+       ↓ outputs 1500-2000 lines
+Task(general-purpose)    → Agent receives COMPLETE prompt
+       ↓
+Autonomous Execution     → No additional Reads needed
+```
+
+**Benefits:**
+- Lead doesn't burn context with Reads per spawn
+- Agent receives everything upfront (fresh context)
+- Deterministic: same inputs → same output
+- Validatable and testable
+
+## Installation
+
+```bash
+# Already included in project
+# No additional dependencies needed
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Develop a story
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent dev \
+  --mission develop-story \
+  --context path/to/story.md
+
+# Validate a story
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent po \
+  --mission validate-story \
+  --context path/to/expanded.md
+
+# Review implementation
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent qa \
+  --mission gate \
+  --context path/to/story.md \
+  --context path/to/impl-log.md
+```
+
+### Options
+
+| Option | Description | Example |
+|--------|-------------|---------|
+| `--agent <id>` | Agent ID (dev, qa, po, db-sage, etc.) | `--agent dev` |
+| `--mission <keyword>` | Mission from Agent's Router | `--mission develop-story` |
+| `--context <path>` | Context file (repeatable) | `--context story.md` |
+| `--squad <name>` | Explicit squad name for agent resolution | `--squad design` |
+| `--extra-instruction` | Additional instruction | `--extra-instruction "Focus on tests"` |
+| `--verbose` | Show debug info to stderr | `--verbose` |
+| `--list-missions` | List available missions | `--list-missions` |
+
+### Multiple Contexts
+
+```bash
+# Story + accumulated context
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent po \
+  --mission validate \
+  --context story.md \
+  --context accumulated-context.md
+
+# Story + implementation log
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent qa \
+  --mission gate \
+  --context expanded.md \
+  --context impl-log.md
+```
+
+### Mission Aliases
+
+Common shortcuts for mission keywords:
+
+| Alias | Resolves To |
+|-------|-------------|
+| `review` | `gate` |
+| `validate` | `validate-story` |
+| `expand` | `create-story` |
+| `develop` | `develop-story` |
+| `implement` | `develop-story` |
+| `backlog` | `backlog-review` |
+| `draft` | `create-story` |
+
+### List Available Missions
+
+```bash
+# List missions for QA agent
+node scripts/glue/compose-agent-prompt.cjs --agent qa --list-missions
+
+# List missions for PO agent
+node scripts/glue/compose-agent-prompt.cjs --agent po --list-missions
+```
+
+## Integration with Task Tool
+
+```javascript
+// 1. Compose the prompt
+const prompt = await Bash(
+  `node scripts/glue/compose-agent-prompt.cjs \
+    --agent dev \
+    --mission develop-story \
+    --context ${storyPath}`
+);
+
+// 2. Spawn agent with complete prompt
+Task({
+  subagent_type: "general-purpose",
+  model: "opus",  // or "sonnet" for mechanical tasks
+  mode: "bypassPermissions",
+  prompt: prompt.stdout
+});
+```
+
+## Execute-Epic Pipeline
+
+The glue script supports the full execute-epic pipeline:
+
+### Phase 1: Backlog Review (PO)
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent po \
+  --mission backlog-review \
+  --context path/to/epic.md
+```
+
+### Phase 2: Development Cycle
+
+**2.1 Expand Story (SM)**
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent sm \
+  --mission expand \
+  --context path/to/epic.md \
+  --extra-instruction "Extract story X"
+```
+
+**2.2 Validate Story (PO)**
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent po \
+  --mission validate \
+  --context path/to/expanded.md
+```
+
+**2.3 Implement (Dev)**
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent dev \
+  --mission develop \
+  --context path/to/expanded.md \
+  --context path/to/accumulated-context.md
+```
+
+**2.4 Review (QA)**
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent qa \
+  --mission review \
+  --context path/to/expanded.md \
+  --context path/to/impl-log.md
+```
+
+### Phase 3: Retrospective (PO)
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent po \
+  --mission retrospective \
+  --context path/to/accumulated-context.md
+```
+
+## Agent Reference
+
+### Agent Resolution Priority
+
+The glue script resolves agents in this order:
+
+1. `.claude/agents/aios-{id}.md` (AIOS core agents)
+2. `.claude/agents/{id}.md` (standalone agents like db-sage)
+3. `squads/{squad}/agents/{id}.md` (squad-specific agents)
+
+### AIOS Core Agents
+
+| Agent ID | Role | Common Missions |
+|----------|------|-----------------|
+| `dev` | Developer | `develop-story`, `apply-qa-fixes` |
+| `qa` | Quality Assurance | `gate`, `review-story`, `security-scan` |
+| `po` | Product Owner | `validate-story`, `backlog-review` |
+| `sm` | Scrum Master | `create-story`, `expand` |
+| `architect` | Architect | `analyze-impact`, `create-fullstack-arch` |
+| `devops` | DevOps | `commit`, `pre-push`, `create-pr` |
+| `analyst` | Analyst | `market-research`, `competitor-analysis` |
+| `data-engineer` | Data Engineer | `develop-story`, `migration`, `schema-audit` |
+| `ux` | UX Designer | `wireframe`, `audit`, `develop-story` |
+| `pm` | Product Manager | `create-prd`, `create-epic` |
+
+### Specialized Squad Agents
+
+| Agent ID | Squad | Replaces | Common Missions |
+|----------|-------|----------|-----------------|
+| `db-sage` | db-sage | data-engineer (for DB) | `kiss`, `kiss-schema-check`, `setup` |
+| `brad-frost` | design | — | Uses internal `*command` system |
+| `design-chief` | design | — | Squad orchestration |
+| `cyber-chief` | cybersecurity | — | Security audits |
+
+**Note:** Squad agents may use different mission systems. Use `--list-missions` to check available missions for each agent.
+
+### Squad Agent Usage
+
+```bash
+# db-sage uses Mission Router
+node scripts/glue/compose-agent-prompt.cjs --agent db-sage --mission kiss
+
+# brad-frost uses internal command system (load persona only)
+node scripts/glue/compose-agent-prompt.cjs --agent brad-frost --mission audit \
+  --extra-instruction "Execute *audit command from your configuration"
+
+# Explicit squad specification
+node scripts/glue/compose-agent-prompt.cjs --agent my-agent --squad my-squad --mission task
+```
+
+## Prompt Structure
+
+The output prompt has the following structure:
+
+```markdown
+## Agent Persona
+
+[Full agent definition from .aios-core/development/agents/{id}.md]
+
+---
+
+## Task Workflow: {mission}
+
+[Task workflow from .aios-core/development/tasks/{file}.md]
+
+---
+
+## Checklist: {resource}.md
+
+[Checklists specified in Mission Router]
+
+---
+
+## Context
+
+### Context 1: {filename}
+
+[File content]
+
+### Context 2: {filename}
+
+[File content]
+
+---
+
+## Execution Directive
+
+Execute the mission "{mission}" following the task workflow above.
+- Follow ALL steps in the task workflow exactly
+- Use Self-Critique checkpoints if defined in the workflow
+- Output artifacts as specified in the workflow
+- Mark success/failure clearly at the end
+
+**Additional Instruction:** {extra-instruction if provided}
+```
+
+## Verbose Mode
+
+Use `--verbose` to see debug information:
+
+```bash
+node scripts/glue/compose-agent-prompt.cjs \
+  --agent dev \
+  --mission develop \
+  --context story.md \
+  --verbose
+```
+
+Output (to stderr):
+```
+[glue] Agent: dev, Mission: develop, Resolved: develop-story
+[glue] Task file: dev-develop-story.md
+[glue] Extra resources: story-dod-checklist.md, self-critique-checklist.md
+[glue] Loading context: story.md
+
+[glue] Prompt stats: 1773 lines, 60117 chars
+[glue] Sections: 6 (persona, task, 2 checklists, 1 contexts, directive)
+```
+
+## Troubleshooting
+
+### Agent file not found
+```
+Error: Agent file not found: .claude/agents/aios-foo.md
+```
+Check that the agent ID is valid. Use one of: dev, qa, po, sm, architect, devops, analyst, data-engineer, ux, pm.
+
+### Mission not found
+```
+## Mission: foo
+No router entry found. Execute mission based on agent expertise.
+```
+Use `--list-missions` to see available missions for the agent.
+
+### Context file not found
+```
+### Context 1
+File not found: /path/to/missing.md
+```
+Verify the context file path is correct.
+
+## Test Results
+
+Pipeline tested with MMOS epic stories:
+
+| Story | Phase | Agent | Duration | Result |
+|-------|-------|-------|----------|--------|
+| MMOS-001 | Develop | dev | 227s | ✅ COMPLETED (verified existing impl) |
+| MMOS-002 | Validate | po | 60s | ✅ APPROVED (impl exists) |
+| MMOS-002 | Review | qa | 345s | ✅ APPROVED (38/38 tests pass) |
+
+**Key Metrics:**
+- Prompt size: 1500-1850 lines per agent
+- Agent autonomy: 100% (no manual intervention)
+- Test pass rate: 100%
+
+---
+
+*Created: 2026-02-06*
+*Version: 1.0.0*