@vpxa/aikit 0.1.307 → 0.1.309

package/scaffold/dist/definitions/skills/multi-agents-development.mjs

@@ -1,4 +1,4 @@
-var e=[{file:`architecture-review-prompt.md`,content:`# Architecture Review Prompt Template
+var e=[{file:`references/architecture-review-prompt.md`,content:`# Architecture Review Prompt Template
 
 Use when dispatching **Architect-Reviewer-Alpha** and **Architect-Reviewer-Beta** for boundary, pattern, infra, or public API changes.
 
@@ -78,7 +78,7 @@ You are performing an architecture review. Focus on structural decisions, not co
 - Trigger for boundary, pattern, infra, or API-surface changes
 - Run Alpha and Beta in parallel
 - Shared blocker from both reviewers = likely real issue
-`},{file:`code-quality-review-prompt.md`,content:`# Code Quality Review Prompt Template
+`},{file:`references/code-quality-review-prompt.md`,content:`# Code Quality Review Prompt Template
 
 Use when dispatching **Code-Reviewer-Alpha** and **Code-Reviewer-Beta** for dual code review. Same prompt; different models catch different issues.
 
@@ -168,7 +168,7 @@ You are performing a code review. Your job is to evaluate HOW the implementation
 - Use for dual review or pair with spec-review prompt
 - Blocker = REQUEST_CHANGES
 - Minor/Nit = APPROVE_WITH_SUGGESTIONS
-`},{file:`implementer-prompt.md`,content:`# Implementer Dispatch Prompt Template
+`},{file:`references/implementer-prompt.md`,content:`# Implementer Dispatch Prompt Template
 
 Use when dispatching **Implementer**, **Frontend**, or **Refactor**. Provide all needed context; subagent should not search beyond scope.
 
@@ -258,7 +258,7 @@ Hit a wall and cannot proceed:
 - Keep scope to 1-3 files
 - Include failing test output for bug fixes
 - Add frontend or refactor-specific constraints when needed
-`},{file:`parallel-dispatch-example.md`,content:`# Parallel Dispatch Worked Example
+`},{file:`references/parallel-dispatch-example.md`,content:`# Parallel Dispatch Worked Example
 
 Shows parallel feature decomposition and review flow.
 
@@ -411,436 +411,126 @@ metadata:
 
 # Multi-Agent Development
 
-Patterns for parallel multi-agent work: decomposition, dispatch, context, status, review, recovery.
+Purpose: decompose work, dispatch focused agents, integrate evidence, recover cleanly. Orchestrator/Planner usually run as main agents; other agents usually run as subagents but must still handle direct mode.
 
-**Core Principle**: Dispatch focused agents with fresh context and explicit scope.
+## Operating Model
 
----
-
-## §1 Agent Roles & Model Selection
-
-### Role Categories
-
-| Role | Agents | When to Use | Parallelizable |
-|------|--------|-------------|----------------|
-| **Orchestration** | Orchestrator, Planner | Plan/control | No |
-| **Implementation** | Implementer, Frontend, Refactor | Code changes | Yes |
-| **Review** | Code-Reviewer-Alpha/Beta, Architect-Reviewer-Alpha/Beta | Verify | Yes |
-
-### Model Selection by Task Complexity
-
-| Complexity Signal | Model Tier | Example Agents |
-|-------------------|-----------|----------------|
-| Mechanical (rename, move, add field) | Fast model | Explorer |
-| Standard (implement spec, write tests) | Mid-tier | Implementer/Refactor |
-
-**Upgrade signal**: \`BLOCKED\` or \`DONE_WITH_CONCERNS\` on Standard task → re-dispatch to stronger model.
-
----
-
-## §2 Task Decomposition Rules
-
-### The Golden Rule
-> **One task = one focused problem domain = 1-3 files maximum.**
-
-### Decomposition Checklist
-
-For each task, specify:
-- [ ] **Target files** — exact paths
-- [ ] **Acceptance criteria** — testable done state
-- [ ] **Agent assignment** — who owns task
-- [ ] **Dependencies** — prerequisite tasks
-
-### Sizing Guide
-
-| Task Size | Files | Example | Agent |
-|-----------|-------|---------|-------|
-| **Standard** | 2-3 files | Service + controller + test | Implementer |
-
-### Splitting Strategies
-- **By layer**: Service + UI + tests
-
----
-
-## §3 Independence Decision Tree
-
-Before marking tasks parallel, walk this tree:
-
-\`\`\`
-Task A and Task B — can they run in parallel?
-│
-├─ Do they share ANY files? (create, modify, or delete same file)
-│   ├─ YES → SEQUENTIAL (or merge into one task)
-│   └─ NO ↓
-│
-├─ Do they share mutable state? (env vars, globals, same DB table, shared config)
-│   ├─ YES → SEQUENTIAL
-│   └─ NO ↓
-│
-├─ Does B need A's output? (B reads file A creates, B uses A's new export)
-│   ├─ YES → SEQUENTIAL (A before B)
-│   └─ NO ↓
-│
-├─ Would A's result change B's approach? (A discovers something that affects B)
-│   ├─ YES → SEQUENTIAL or single agent
-│   └─ NO ↓
-│
-├─ Resource contention? (same port, same build process, same lock file)
-│   ├─ YES → SEQUENTIAL
-│   └─ NO ↓
-│
-└─ ✅ SAFE TO PARALLELIZE
-\`\`\`
-
-### Edge Cases
-
-| Situation | Verdict | Why |
-|-----------|---------|-----|
-| Same shared import only | ✅ Parallel | Read-only |
-| Same index/package file | ❌ Sequential | Shared edit |
-
-### Integration Verification (after parallel batch completes)
-
-1. **Conflict check**: unexpected overlap?
-2. **Import check**: cross-references resolve?
-3. **Full suite**: \`check({})\` + \`test_run({})\`
-
----
-
-## §4 Parallel Dispatch Patterns
-
-### Dispatch Rules
-
-1. **Max 4 concurrent file-modifying agents** per batch
-2. **Read-only agents have no limit** — Explorer, Researcher*, Reviewer*, Security
-3. **Build dependency graph first** — dependency-free phases batch together
-4. **Never dispatch two implementers to same file**
-
-### Batch Strategy
-
-\`\`\`
-Phase Plan:
-  Phase 1: [Task A, Task B, Task C]  ← no dependencies between A/B/C
-  Phase 2: [Task D, Task E]          ← D depends on A, E depends on B
-  Phase 3: [Task F]                  ← F depends on D and E
-
-Execution:
-  Batch 1: dispatch(A, B, C) in parallel → review → gate
-  Batch 2: dispatch(D, E) in parallel → review → gate
-  Batch 3: dispatch(F) → review → gate
-\`\`\`
-
-### Anti-Patterns
-
-| ❌ Don't | ✅ Do Instead |
-|----------|--------------|
-| Dispatch 6 implementers at once | Max 4, queue rest |
-| Give one agent 10 files | Split tasks |
-| Skip review after batch | ALWAYS review + integrate |
-
----
-
-## §5 Context Crafting Guide
-
-### The Controller Principle
-> **The Orchestrator provides ALL context. Subagents never search for it.**
-
-Fresh prompt only. No inherited session state.
-
-### The 6-Point Prompt Template
-
-Every delegation prompt MUST include:
-
-\`\`\`markdown
-## 1. Scope
-Files to create/modify: [exact paths]
-Files to NOT touch: [boundaries]
-
-## 2. Goal
-[What the code should do — acceptance criteria, testable outcomes]
-
-## 3. Architectural Context
-[Relevant patterns, conventions, existing code structure]
-[Include actual code snippets from compact/digest — don't tell agent to "go read X"]
-
-## 4. Constraints
-- Follow [pattern/convention]
-- Do NOT modify [boundary files]
-- Use [specific library/approach]
-
-## 5. FORGE Context
-Tier: [Floor/Standard/Critical]
-Evidence requirements: [what evidence to collect]
-
-## 6. Self-Review & Status
-Before declaring DONE, verify:
-- [ ] All acceptance criteria met
-- [ ] No files outside scope modified
-- [ ] Tests pass (if applicable)
-- [ ] Code follows stated conventions
-
-End with status: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED
-\`\`\`
-
-### What to Include vs Omit
-
-| ✅ Include | ❌ Omit |
-|-----------|---------|
-| Exact file paths and snippets | Full session history |
-
-### Context Size Budget
-
-| Task Complexity | Context Target | Approach |
-|-----------------|---------------|----------|
-| Standard (2-3 files) | ~2000 tokens | \`digest\` + architecture |
-
----
+- Main agent owns plan, flow, user comms, gates, and final synthesis.
+- Subagents own one scoped research/review/implementation task.
+- Fresh prompt only. Assume no inherited session state.
+- Context flows through AI Kit: withdraw -> compact/digest -> dispatch -> deposit.
+- Token goal: send decisions, constraints, snippets, paths; skip raw history.
 
-## §6 Subagent Execution Cycle
+## Role Routing
 
-### Lifecycle
+| Need | Agent |
+|---|---|
+| Plan/lifecycle/gate | Orchestrator |
+| Implementation plan | Planner |
+| Feature/API/wiring | Implementer |
+| UI/styling/a11y | Frontend |
+| Cleanup/rename/reduce complexity | Refactor |
+| Bug/root cause | Debugger |
+| Auth/crypto/input/CVE | Security |
+| Unknown code area | Explorer or Researcher |
+| Docs | Documenter |
+| Correctness review | Code-Reviewer-Alpha/Beta |
+| Boundary review | Architect-Reviewer-Alpha/Beta |
 
-\`\`\`
-Orchestrator                          Subagent (fresh instance)
-    │                                      │
-    ├─ Craft focused prompt ──────────────►│
-    │  (6-point template)                  │
-    │                                      ├─ Understand scope
-    │                                      ├─ Implement changes
-    │                                      ├─ Self-review (checklist)
-    │◄─────────────────── Return status ───┤
-    │                                      │ (DONE/CONCERNS/NEEDS/BLOCKED)
-    │                                      │
-    ├─ Handle status (see §7)              ×  (subagent terminates)
-    │
-    ├─ Automated gate (check/test_run)
-    │
-    ├─ Dispatch reviewers (see §8)
-    │
-    └─ FORGE evidence_map gate
-\`\`\`
-
-### Key Rules
-
-1. **One subagent = one task**
-2. **Controller provides context**
-3. **Status is mandatory**
-
----
-
-## §7 Implementer Status Protocol
-
-### Status Codes
-
-Every implementer (Implementer, Frontend, Refactor) MUST end response with exactly ONE:
-
-| Status | Meaning | Orchestrator Action |
-|--------|---------|-------------------|
-| **DONE** | Complete, self-review passed | → Review → arch/security if needed → \`evidence_map\` gate |
-| **DONE_WITH_CONCERNS** | Complete, concerns raised | → Review + \`Assumed\` claims |
-| **NEEDS_CONTEXT** | Missing info | → Add context → re-dispatch |
-| **BLOCKED** | Cannot proceed | → Diagnose |
-
-### BLOCKED Diagnosis Tree
-
-\`\`\`
-Agent returned BLOCKED
-│
-├─ Missing context? (needs info not in prompt)
-│   → Provide context, re-dispatch
-│
-├─ Wrong model? (task too complex for assigned model)
-│   → Re-dispatch to stronger model (e.g., Implementer → Debugger)
-│
-├─ Scope too broad? (agent overwhelmed)
-│   → Split task further, re-dispatch smaller pieces
-│
-├─ Plan wrong? (implementation approach won't work)
-│   → Re-plan this phase, check AI Kit for alternatives
-│
-└─ External blocker? (dependency not ready, API unavailable)
-    → Park task, proceed with independent work, revisit later
-\`\`\`
-
-### FORGE Composition
-
-- **Status** = agent telemetry
-- **FORGE** = evidence-based quality gate
-
-\`\`\`
-DONE               → proceed to code review → conditional architecture/security review → FORGE evidence_map → present results
-DONE_WITH_CONCERNS → concerns become 'Assumed' claims → reviewers validate them → evidence_map likely HOLDs
-NEEDS_CONTEXT      → provide context, re-dispatch (no FORGE yet)
-BLOCKED            → diagnose:
-                      contract/security issue → HARD_BLOCK
-                      resource/scope issue → re-plan, no FORGE
-\`\`\`
-
-**Critical rule**: Every \`DONE\` must complete code review and any conditional architecture/security review BEFORE \`evidence_map({ action: "gate" })\`.
-
----
-
-## §8 Review Pipeline
-
-### Ordered Review Pipeline
-
-\`\`\`
-Stage 1: Implementer Self-Review (embedded in agent output)
-  └─ Checklist: scope respected, tests pass, conventions followed
-      │
-Stage 2: Dual Code Review (parallel)
-  ├─ Code-Reviewer-Alpha (GPT-5.4): code quality + Spec Alignment
-  └─ Code-Reviewer-Beta (Opus 4.6): code quality + Spec Alignment
-      │ Both review same code, different model perspectives
-      │ Spec Alignment = "Does this match what was asked?"
-      │
-Stage 3: Architecture Review (conditional)
-  └─ Trigger only for boundary changes, new modules, or pattern shifts
-      │
-Stage 4: Security Review (conditional)
-  └─ Trigger for auth, crypto, input handling, or external data
-      │
-Stage 5: FORGE Gate — evidence_map({ action: "gate" })
-  └─ YIELD → stop and present results
-  └─ HOLD → address flagged items → re-gate (**Max 2 retries** per task)
-  └─ HARD_BLOCK → escalate to user
-\`\`\`
-
-Use \`check({})\` + \`test_run({})\` for reviewer evidence; not gate.
-
-### Spec Alignment Dimension (for Code Reviewers)
-
-Check acceptance criteria, over-build, under-build, and expected file set.
-
-### When to Skip Stages
-
-| Stage | Skip When |
-|-------|-----------|
-| Architecture Review | No new modules/boundary changes/patterns |
-
----
+## Decompose
 
-## §9 Recovery & Escalation
+One subtask = one problem domain + explicit file boundary.
 
-### Retry Policy
+For each task define:
+- Goal and acceptance criteria.
+- Files to create/modify/read; files not to touch.
+- Dependencies and parallel batch.
+- Required skills/tools/tests.
+- FORGE tier, task_id, evidence expected.
 
-**Max 2 retries** per task. Include failure reason. Never reuse same prompt.
+Split by layer, package, endpoint, component, test surface, or risk class. Merge tasks when they share writable files.
 
-### Loop Detection
+## Parallelism
 
-If an agent returns the same error/status 2+ times:
-1. **STOP**
-2. Recheck approach
-3. Change agent, model, decomposition, or escalate
+Parallelize when tasks share no writable files, mutable state, generated artifact, port, lockfile, DB table, or output dependency.
 
-### Emergency Procedures
+Limits:
+- File-modifying agents: max 4 concurrent, disjoint files only.
+- Read-only agents: parallel freely.
+- Shared index/config/package files: sequential.
+- After each batch: integrate, check, test, review, gate before next dependent batch.
 
-When parallel batch causes cascading failures:
+## Dispatch Envelope
 
-\`\`\`
-STOP    → Halt all running agents immediately
-ASSESS  → git diff --stat + check({}) — how bad is it?
-CONTAIN → Limited (1-3 files): fix or re-delegate
-           Widespread (10+ files): git stash to preserve for analysis
-RECOVER → Partial: git checkout -- {specific files}
-           Full: git stash (preserves) or git checkout . (discards)
-           Nuclear: git reset --hard HEAD (last resort)
-DOCUMENT → remember what went wrong, update plan
-\`\`\`
+Every subagent prompt includes:
+1. Agent name and role.
+2. Goal + acceptance criteria.
+3. Files/boundary + do-not-touch list.
+4. Compressed context: relevant snippets, conventions, decisions, active flow paths.
+5. Constraints: skills to load, libraries/patterns, no present, no flow advance.
+6. FORGE: tier, task_id, evidence claims to add.
+7. Validation: expected check, test_run, or reason skipped.
+8. Return contract: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED, <=200 words unless blocked.
 
-### Scope Tripwires
+Use references/implementer-prompt.md for implementation dispatches and references/parallel-dispatch-example.md for batch shape.
 
-| Signal | Action |
-|--------|--------|
-| Agent modified **2x more files** than planned | Pause, review |
-| Agent returns \`ESCALATE\` or \`BLOCKED\` repeatedly | Diagnose before re-delegating |
-| Agent's output contradicts plan | Stop, compare, re-align |
-| Tests that were passing now fail | Immediate rollback of that agent's changes |
-
----
+## Context Broker
 
-## §10 Common Mistakes & Red Flags
+Before dispatch:
+- knowledge({ action: 'withdraw', scope: 'flow', profile: '<role>', budget: 6000 })
+- Add only missing snippets with compact/digest.
+- Paste context into dispatch; do not tell subagent to rediscover basics.
 
-### Delegation Anti-Patterns
+After subagent work:
+- Store durable findings with knowledge({ action: 'remember', scope: 'flow', ... }).
+- Summarize status/files/decisions/blockers into stash or session digest.
+- Flush flow context only when work completes.
 
-| ❌ Mistake | Why It Fails | ✅ Fix |
-|-----------|-------------|--------|
-| **Too broad scope** | Sprawling changes | Split tasks |
-| **Parallel on shared files** | Merge conflicts | Sequential or merge task |
-
-### Red Flags in Agent Output
-
-| Flag | What It Means | Action |
-|------|--------------|--------|
-| Files outside scope | Scope creep | Roll back, re-delegate tighter |
-
----
+Profiles: implementer, documenter, reviewer, researcher, debugger.
 
-## §11 Flow Context Sharing
-
-### Flow Context Broker
-
-The \`knowledge\` tool supports flow-scoped context sharing.
-
-**How it works:** auto-deposit captures tool output, Orchestrator calls \`withdraw\`, subagents can deposit findings, \`flush\` clears flow context.
-
-### Orchestrator Workflow
-
-#### Before Dispatching a Subagent
-
-\`\`\`
-// Get role-filtered context for the subagent
-knowledge({ action: 'withdraw', profile: '<role>', budget: 6000 })
-// Profiles: implementer, documenter, reviewer, researcher, debugger
-\`\`\`
+## Status Handling
 
-Paste withdrawn context into "## 3. Architectural Context" from §5.
+| Status | Meaning | Orchestrator action |
+|---|---|---|
+| DONE | Complete + self-check passed | review -> gate |
+| DONE_WITH_CONCERNS | Complete but risk/assumption remains | review concern, add assumed claim |
+| NEEDS_CONTEXT | Missing info | supply context, re-dispatch |
+| BLOCKED | Cannot proceed | diagnose; split/change agent/escalate |
 
-#### After All Work Completes
+Same failure twice -> stop loop, change plan/model/scope or ask user.
 
-\`\`\`
-// Clean up flow context on flow completion
-knowledge({ action: 'flush' })
-\`\`\`
-
-### Subagent Deposit Pattern
-
-\`\`\`
-// Subagent deposits a finding for future agents
-knowledge({ action: 'remember', scope: 'flow', title: 'API validation pattern', content: '...' })
-\`\`\`
-
-### Profile Filtering
-
-Use \`implementer\` profile for Implementer/Frontend/Refactor tasks.
-
-### Budget Management
-
-\`budget\` caps returned context. Standard implementation: 6000.
-
-### Integration with 6-Point Template
-
-Update the prompt template from §5 to include flow context:
-
-\`\`\`markdown
-## 3. Architectural Context
-[Paste the result of knowledge({ action: 'withdraw', profile: '<role>' })]
-[Supplement with additional compact/digest if the withdrawn context is insufficient]
-\`\`\`
+## Review Pipeline
 
-### Key Rules
+Standard path:
+1. Implementer self-check.
+2. Code review. Use dual reviewers for Standard+ when risk warrants.
+3. Architecture review for boundary/new-module/public-contract changes.
+4. Security review for auth/crypto/input/external-data changes.
+5. evidence_map({ action: 'gate' }): YIELD -> present, HOLD -> fix/retry max 2, HARD_BLOCK -> user.
 
-1. **Always withdraw before dispatch**
-2. **Flush on completion**
-3. **Profile matters**
+Reviewers add CRITICAL/HIGH evidence only; Orchestrator gates.
 
-## Prompt Template Reference
+## Recovery
+
+Tripwires:
+- Agent edits outside scope or 2x expected file count.
+- Parallel batch conflicts on same file/artifact.
+- Tests regress outside touched area.
+- Subagent contradicts plan or local conventions.
+- Auth/access failure appears.
+
+Recovery order: pause -> inspect diff/check output -> contain scope -> re-dispatch with better context -> escalate if evidence remains missing.
 
-| Template | File | Use When |
-|----------|------|----------|
-| Implementer dispatch | [\`implementer-prompt.md\`](implementer-prompt.md) | Implementer/Frontend/Refactor |
-| Parallel dispatch example | [\`parallel-dispatch-example.md\`](parallel-dispatch-example.md) | Worked example |
-`},{file:`spec-review-prompt.md`,content:`# Spec Alignment Review Prompt Template
+## Reference Prompts
+
+| Template | Load when |
+|---|---|
+| references/implementer-prompt.md | Implementation dispatch |
+| references/code-quality-review-prompt.md | Code-review dispatch |
+| references/architecture-review-prompt.md | Architecture review |
+| references/spec-review-prompt.md | Acceptance/spec alignment |
+| references/parallel-dispatch-example.md | Example batch/dependency shape |
+`},{file:`references/spec-review-prompt.md`,content:`# Spec Alignment Review Prompt Template
 
 Use when dispatching a code reviewer who should emphasize spec alignment during code review.