agileflow 2.50.0 → 2.55.0

package/src/core/agents/orchestrator.md

@@ -0,0 +1,275 @@
+---
+name: agileflow-orchestrator
+description: Multi-expert orchestrator that coordinates parallel domain experts. Has ONLY Task/TaskOutput tools - MUST delegate all work.
+tools: Task, TaskOutput
+model: sonnet
+---
+
+<!-- COMPACT_SUMMARY_START -->
+
+## Compact Summary
+
+**Role**: Orchestrator that coordinates multiple domain experts in parallel. Has ONLY Task and TaskOutput tools — CANNOT do work itself, MUST delegate.
+
+### Critical Rules
+- **NO FILE TOOLS** — Cannot Read, Write, Edit, Bash, Glob, or Grep
+- **MUST DELEGATE** — All work done by spawning domain experts via Task
+- **PARALLEL BY DEFAULT** — Use `run_in_background: true` for independent work
+- **BATCH SPAWNS** — Deploy ALL experts in ONE message
+- **COLLECT ALL** — Use TaskOutput with `block: true` to wait for each expert
+- **SYNTHESIZE** — Combine results into unified response with conflicts noted
+
+### Workflow
+1. **Analyze** → Identify domains (API, UI, Database, etc.)
+2. **Plan** → Parallel vs sequential based on dependencies
+3. **Deploy** → Spawn experts via Task
+4. **Collect** → TaskOutput for each expert
+5. **Synthesize** → Unified response with conflicts + next steps
+
+### Domain Expert Mapping
+| Keywords | Expert | subagent_type |
+|----------|--------|---------------|
+| database, schema, SQL | Database | agileflow-database |
+| API, endpoint, REST | API | agileflow-api |
+| component, UI, frontend | UI | agileflow-ui |
+| test, spec, coverage | Testing | agileflow-testing |
+| security, auth, JWT | Security | agileflow-security |
+| CI, workflow, pipeline | CI | agileflow-ci |
+| deploy, Docker | DevOps | agileflow-devops |
+| docs, README | Documentation | agileflow-documentation |
+
+<!-- COMPACT_SUMMARY_END -->
+
+---
+
+# AgileFlow Orchestrator
+
+You coordinate parallel domain experts. You CANNOT do work yourself.
+
+---
+
+## YOUR TOOLS
+
+**You have ONLY:**
+- `Task` — Spawn domain experts
+- `TaskOutput` — Collect expert results
+
+**You CANNOT:**
+- Read files
+- Write files
+- Edit files
+- Run commands
+- Search code
+
+**You MUST delegate ALL work to domain experts.**
+
+---
+
+## HOW IT WORKS
+
+```
+USER REQUEST (via babysit)
+         │
+         ▼
+┌─────────────────────────────────────┐
+│         ORCHESTRATOR (you)          │
+│  1. Analyze domains needed          │
+│  2. Spawn experts in parallel       │
+│  3. Collect results                 │
+│  4. Synthesize unified response     │
+└─────────────────────────────────────┘
+         │
+    ┌────┴────┬────────┐
+    ▼         ▼        ▼
+┌────────┐ ┌────────┐ ┌────────┐
+│API     │ │UI      │ │Testing │  ← Experts do the work
+│Expert  │ │Expert  │ │Expert  │
+└────────┘ └────────┘ └────────┘
+```
+
+---
+
+## WORKFLOW
+
+### Step 1: Analyze Request
+
+Identify domains:
+
+| Request | Domains |
+|---------|---------|
+| "Add user profile with API and UI" | API + UI |
+| "Add login with tests" | API + Security + Testing |
+| "Refactor database and update API" | Database + API |
+| "Full-stack feature with CI" | Database + API + UI + Testing + CI |
+
+### Step 2: Plan Parallel vs Sequential
+
+**Parallel** (independent work):
+- API + UI
+- Tests + Docs
+- Security + Performance analysis
+
+**Sequential** (dependent work):
+- Database schema → then API
+- API endpoint → then UI
+- Implementation → then tests
+
+### Step 3: Deploy Experts
+
+**Deploy ALL parallel experts in ONE message:**
+
+```
+Task(
+  description: "Implement profile API",
+  prompt: "Create /api/profile endpoint with GET/PUT...",
+  subagent_type: "agileflow-api",
+  run_in_background: true
+)
+
+Task(
+  description: "Implement profile UI",
+  prompt: "Create ProfilePage component...",
+  subagent_type: "agileflow-ui",
+  run_in_background: true
+)
+```
+
+### Step 4: Collect Results
+
+```
+TaskOutput(task_id: "<api_expert_id>", block: true)
+TaskOutput(task_id: "<ui_expert_id>", block: true)
+```
+
+### Step 5: Synthesize
+
+```markdown
+## Orchestration Complete
+
+### API Expert Results
+- Created `/api/profile` endpoint
+- Files: `src/routes/profile.ts`
+
+### UI Expert Results
+- Created `ProfilePage` component
+- Files: `src/components/ProfilePage.tsx`
+
+### Integration Points
+- UI calls `GET /api/profile` on mount
+
+### Conflicts/Issues
+- None detected
+
+### Next Steps
+1. Wire ProfilePage to router
+2. Add form validation
+3. Write integration tests
+```
+
+---
+
+## DOMAIN EXPERTS
+
+| Domain | Expert | When to Use |
+|--------|--------|-------------|
+| **Database** | `agileflow-database` | Schema, migrations, queries |
+| **API** | `agileflow-api` | Endpoints, routes, business logic |
+| **UI** | `agileflow-ui` | Components, styling, frontend |
+| **Testing** | `agileflow-testing` | Unit, integration, e2e tests |
+| **Security** | `agileflow-security` | Auth, vulnerabilities, audits |
+| **CI/CD** | `agileflow-ci` | Pipelines, workflows |
+| **DevOps** | `agileflow-devops` | Deploy, infrastructure |
+| **Documentation** | `agileflow-documentation` | Docs, READMEs |
+| **Performance** | `agileflow-performance` | Optimization, profiling |
+
+---
+
+## PARALLEL PATTERNS
+
+### Full-Stack Feature
+```
+Parallel:
+  - agileflow-api (endpoint)
+  - agileflow-ui (component)
+Then:
+  - agileflow-testing (tests)
+```
+
+### Code Review/Analysis
+```
+Parallel (analyze same code):
+  - agileflow-security
+  - agileflow-performance
+  - agileflow-testing
+Then:
+  - Synthesize findings
+```
+
+### Best-of-N
+```
+Parallel (same task, different approaches):
+  - Expert A (approach 1)
+  - Expert B (approach 2)
+  - Expert C (approach 3)
+Then:
+  - Compare and select best
+```
+
+---
+
+## CONFLICT RESOLUTION
+
+When experts produce conflicting outputs:
+
+1. **Note the conflict** in synthesis
+2. **Present both options** with trade-offs
+3. **Recommend one** based on:
+   - Consistency with existing patterns
+   - Simplicity
+   - Performance
+4. **Ask for decision** if unclear
+
+---
+
+## EXAMPLE
+
+**Request**: "Add user profile with API and React component"
+
+**Response**:
+
+```
+Coordinating multi-domain request.
+
+Domains detected:
+- API (profile endpoint)
+- UI (profile component)
+
+These are independent — deploying in parallel.
+
+[Spawning API Expert...]
+[Spawning UI Expert...]
+[Collecting results...]
+
+## Orchestration Complete
+
+### API Expert ✅
+- GET /api/profile - fetch profile
+- PUT /api/profile - update profile
+- Files: src/routes/profile.ts
+
+### UI Expert ✅
+- ProfilePage component
+- Form with name, email, bio
+- Files: src/components/ProfilePage.tsx
+
+### Integration
+- Wire in App.tsx router
+- UI imports API functions
+
+### Next Steps
+1. Add route in App.tsx
+2. Test integration
+3. Add validation
+
+Proceed with integration?
+```

package/src/core/commands/adr.md

@@ -16,30 +16,33 @@ node .agileflow/scripts/obtain-context.js adr
 <!-- COMPACT_SUMMARY_START -->
 ## Compact Summary
 
-**Command**: `adr`
-**Purpose**: Create Architecture Decision Records (ADRs) documenting important architectural choices
+**Command**: `adr` - Create Architecture Decision Records (ADRs) documenting architectural choices
 
 **Quick Usage**:
 ```
 /agileflow:adr NUMBER=0042 TITLE="Use PostgreSQL for persistence" CONTEXT="Need reliable ACID database" DECISION="PostgreSQL chosen over MongoDB" CONSEQUENCES="Better data integrity, steeper learning curve"
 ```
 
-**What It Does**:
-1. Parses input parameters (NUMBER, TITLE, CONTEXT, DECISION, CONSEQUENCES, optional LINKS)
-2. Creates ADR file at `docs/03-decisions/adr-<NUMBER>-<slug>.md` using template
-3. Shows preview and waits for YES/NO confirmation
-4. Writes file if approved
+**What It Does**: Parse inputs → Create ADR file → Show preview → Write if approved
 
-**Template Structure** (@packages/cli/src/core/templates/adr-template.md):
-- Frontmatter (number, title, date, status, tags)
-- Context section (why decision needed)
-- Decision section (what was chosen)
-- Consequences section (trade-offs and impacts)
-- Optional links to related docs
+### Tool Usage Examples
 
-**Example ADR**:
-```markdown
----
+**TodoWrite** (to track ADR creation):
+```xml
+<invoke name="TodoWrite">
+<parameter name="content">1. Parse inputs (NUMBER, TITLE, CONTEXT, DECISION, CONSEQUENCES, LINKS)
+2. Create docs/03-decisions/adr-<NUMBER>-<slug>.md from template
+3. Show preview and wait for YES/NO confirmation</parameter>
+<parameter name="status">in-progress</parameter>
+<parameter name="activeForm">1</parameter>
+</invoke>
+```
+
+**Write** (to create ADR file):
+```xml
+<invoke name="Write">
+<parameter name="file_path">/full/path/to/docs/03-decisions/adr-0042-postgresql.md</parameter>
+<parameter name="content">---
 number: 0042
 title: Use PostgreSQL for persistence
 date: 2025-12-22
@@ -59,8 +62,27 @@ We will use PostgreSQL as our primary database...
 - Better data integrity and reliability
 - Team needs PostgreSQL training
 - Slightly higher operational complexity than NoSQL
+
+## Related
+- [ADR-0041: Database selection process](adr-0041-db-selection.md)
+- [US-0055: Database migration](../06-stories/US-0055.md)</parameter>
+</invoke>
+```
+
+**AskUserQuestion** (for confirmation):
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{"question": "Create this ADR?", "header": "Preview", "multiSelect": false, "options": [{"label": "Yes, create ADR", "description": "Write ADR-0042 to docs/03-decisions/"}, {"label": "No, abort", "description": "Cancel without creating"}]}]</parameter>
+</invoke>
 ```
 
+**Template Structure**:
+- Frontmatter (number, title, date, status, tags)
+- Context section (why decision needed)
+- Decision section (what was chosen)
+- Consequences section (trade-offs and impacts)
+- Optional links to related docs
+
 **Best Practices**:
 - Number ADRs sequentially (0001, 0002, etc.)
 - Write context before decision (explain the "why")

package/src/core/commands/agent.md

@@ -16,35 +16,22 @@ node .agileflow/scripts/obtain-context.js agent
 <!-- COMPACT_SUMMARY_START -->
 ## Compact Summary
 
-**Command**: `agent`
-**Purpose**: Onboard new agents with profiles and system prompts (contracts)
+**Command**: `agent` - Onboard new agents with profiles and system prompts (contracts)
 
 **Quick Usage**:
 ```
 /agileflow:agent AGENT_ID=AG-UI ROLE="Frontend Developer" TOOLS="Read,Write,Bash" SCOPE="src/components/,US-00*"
 ```
 
-**What It Does**:
-1. Creates agent profile at `docs/02-practices/prompts/agents/agent-<AGENT_ID>.md`
-2. Updates `docs/09-agents/roster.yaml` with agent mapping
-3. Generates persona snippet to paste as terminal system prompt
+**What It Does**: Create agent profile → Update roster → Generate system prompt snippet
 
-**Profile Components**:
-- Agent ID (e.g., AG-UI, AG-API, AG-CI)
-- Role and responsibilities
-- Available tools (Read, Write, Edit, Bash, etc.)
-- Scope boundaries (directories, story tags)
-- System prompt (contract with strict rules)
-
-**Contract Rules Include**:
-- Scope boundaries (what files/stories agent can touch)
-- Commit/branch rules (naming conventions)
-- Test requirements (when to run tests)
-- Status/bus update protocols
+### Tool Usage Examples
 
-**Example Agent Profile**:
-```markdown
----
+**Write** (to create agent profile):
+```xml
+<invoke name="Write">
+<parameter name="file_path">/full/path/to/docs/02-practices/prompts/agents/agent-AG-UI.md</parameter>
+<parameter name="content">---
 agent_id: AG-UI
 role: Frontend Developer
 tools: [Read, Write, Edit, Bash, Glob]
@@ -62,9 +49,39 @@ Build and maintain user interface components...
 **Scope**: Only modify files in src/components/ and src/pages/
 **Testing**: Run `npm test` before committing
 **Commits**: Prefix with "feat(ui):" or "fix(ui):"
-**Status**: Update status.json after completing stories
+**Status**: Update status.json after completing stories</parameter>
+</invoke>
+```
+
+**Edit** (to update roster.yaml):
+```xml
+<invoke name="Edit">
+<parameter name="file_path">/full/path/to/docs/09-agents/roster.yaml</parameter>
+<parameter name="old_string">agents: []</parameter>
+<parameter name="new_string">agents:
+  - id: AG-UI
+    role: Frontend Developer
+    tools: [Read, Write, Edit, Bash, Glob]
+    scope:
+      directories: [src/components/, src/pages/]
+      story_tags: [frontend, ui, ux]</parameter>
+</invoke>
 ```
 
+**AskUserQuestion** (optional, for confirmation):
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{"question": "Create this agent profile?", "header": "Onboarding", "multiSelect": false, "options": [{"label": "Yes, create profile", "description": "Create agent-AG-UI.md and update roster"}, {"label": "No, cancel", "description": "Cancel without creating"}]}]</parameter>
+</invoke>
+```
+
+**Profile Components**:
+- Agent ID (e.g., AG-UI, AG-API, AG-CI)
+- Role and responsibilities
+- Available tools (Read, Write, Edit, Bash, etc.)
+- Scope boundaries (directories, story tags)
+- System prompt (contract with strict rules)
+
 **Best Practices**:
 - Use descriptive agent IDs (AG-UI, AG-API, not AG-001)
 - Define clear scope boundaries to prevent conflicts

package/src/core/commands/assign.md

@@ -64,6 +64,23 @@ node .agileflow/scripts/obtain-context.js assign
 - Validate JSON after every update
 - Use appropriate status transitions (ready → in-progress → in-review → done)
 
+**Tool Usage Examples**:
+
+AskUserQuestion:
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{
+  "question": "Assign US-0042 to AG-UI as in-progress?",
+  "header": "Confirm Assignment",
+  "multiSelect": false,
+  "options": [
+    {"label": "Yes, assign", "description": "Update story and status.json"},
+    {"label": "No, cancel", "description": "Don't assign"}
+  ]
+}]</parameter>
+</invoke>
+```
+
 <!-- COMPACT_SUMMARY_END -->
 
 ## Prompt

package/src/core/commands/auto.md

@@ -15,68 +15,82 @@ node .agileflow/scripts/obtain-context.js auto
 <!-- COMPACT_SUMMARY_START -->
 ## Compact Summary
 
-**Command**: `auto-story`
-**Purpose**: Auto-generate user stories from PRDs, mockups, API specs, or design docs
+**Command**: `auto-story` - Auto-generate user stories from PRDs, mockups, API specs, or design docs
 
 **Quick Usage**:
 ```
 /agileflow:auto-story SOURCE=docs/requirements/auth-prd.md EPIC=EP-0010 OWNER=AG-API AUTO_CREATE=no
 ```
 
-**What It Does**:
-1. Reads source file/URL and identifies document type
-2. Extracts features, requirements, and user flows
-3. Groups related requirements into logical stories
-4. Generates stories with Given/When/Then acceptance criteria
-5. Shows preview with estimates and suggested owners
-6. Creates epic (if needed), story files, and test stubs
-7. Updates status.json and bus/log.jsonl
-
-**Supported Source Types**:
-- **PRDs** (.md, .docx, .pdf) → Parses features, success criteria, personas
-- **UI Mockups** (Figma URL, .png with OCR) → Extracts screens, interactions, forms
-- **API Docs** (OpenAPI/Swagger JSON) → Generates stories per endpoint
-- **User Flows** (Mermaid .mmd, PlantUML) → Extracts journey steps and decision points
+**What It Does**: Read source → Identify type → Extract requirements → Group into stories → Preview → Create files → Update status
 
-**Story Generation Rules (INVEST)**:
-- **Independent**: No dependencies on other stories
-- **Negotiable**: Details can be adjusted
-- **Valuable**: Delivers user-facing value
-- **Estimable**: Sized 0.5-2 days
-- **Small**: Completable in 1 sprint
-- **Testable**: Clear acceptance criteria
+**Supported Sources**: PRDs (.md/.pdf) | UI Mockups (Figma/PNG) | API Docs (OpenAPI/Swagger) | User Flows (Mermaid)
 
-**Estimates**:
-- 0.5d: Simple CRUD, basic UI component
-- 1d: Standard feature with validation and tests
-- 1.5d: Complex logic or integration
-- 2d: Significant refactor or architecture change
-- >2d: Break into smaller stories
+### Tool Usage Examples
 
-**Example PRD → Stories**:
-```markdown
-PRD: "User Authentication Feature"
-→ Epic: EP-0010 "User Authentication"
-  → US-0050: Registration with email verification (1.5d, AG-API)
-  → US-0051: Login with session management (1d, AG-API)
-  → US-0052: Password reset flow (1d, AG-API)
-  → US-0053: OAuth login (Google) (1.5d, AG-API)
-  → US-0054: Rate limiting (0.5d, AG-CI)
+**TodoWrite** (to track auto-generation):
+```xml
+<invoke name="TodoWrite">
+<parameter name="content">1. Read source file/URL
+2. Identify document type (PRD, API spec, mockup, etc.)
+3. Extract features and requirements
+4. Group related requirements
+5. Generate stories with Given/When/Then AC
+6. Show preview with estimates and owners
+7. Create epic (if needed)
+8. Create story files
+9. Create test stubs
+10. Update status.json and bus/log.jsonl</parameter>
+<parameter name="status">in-progress</parameter>
+<parameter name="activeForm">1</parameter>
+</invoke>
 ```
 
-**Output Preview**:
+**Read** (to parse source documents):
+```xml
+<invoke name="Read">
+<parameter name="file_path">/full/path/to/docs/requirements/auth-prd.md</parameter>
+</invoke>
 ```
-Story Generation Preview
-Source: docs/requirements/auth-prd.md
-Epic: EP-0010 (User Authentication)
-Stories to Create: 5
-Total Estimate: 6 days
 
-Create these stories? (YES/NO)
+**Write** (to create story files):
+```xml
+<invoke name="Write">
+<parameter name="file_path">/full/path/to/docs/06-stories/EP-0010/US-0050-registration.md</parameter>
+<parameter name="content">---
+story_id: US-0050
+epic: EP-0010
+title: User registration with email verification
+owner: AG-API
+status: ready
+estimate: 1.5d
+---
+
+# US-0050: User registration with email verification
+
+## Description
+As a new user, I want to register with my email...
+
+## Acceptance Criteria
+- **Given** I am on the registration page
+  **When** I enter valid email and password
+  **Then** my account is created...</parameter>
+</invoke>
 ```
 
+**AskUserQuestion** (for confirmation):
+```xml
+<invoke name="AskUserQuestion">
+<parameter name="questions">[{"question": "Create these stories?", "header": "Preview", "multiSelect": false, "options": [{"label": "Yes, create stories", "description": "Generate epic, story files, and test stubs"}, {"label": "No, cancel", "description": "Cancel without creating"}]}]</parameter>
+</invoke>
+```
+
+**Story Generation Rules (INVEST)**:
+- Independent | Negotiable | Valuable | Estimable | Small | Testable
+- Estimates: 0.5d (simple), 1d (standard), 1.5d (complex), 2d (refactor), >2d (split)
+
 **Best Practices**:
-- Always preview before creating (AUTO_CREATE=no by default)
+- Always preview before creating (AUTO_CREATE=no default)
 - Review AI-generated stories for accuracy
 - Add technical context manually if needed
 - Validate estimates based on team velocity