aiox-core 5.0.3 → 5.0.4

package/scripts/glue/README.md

@@ -1,355 +0,0 @@
-# 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*