anchi-kit 1.1.2

package/docs/ORCHESTRATION.md

@@ -0,0 +1,704 @@
+# Agent Orchestration System v2.0
+
+> Meta-layer điều phối AI: Tự nhận thức, tự kiểm soát, tự giải thích  
+> **100% Dynamic Orchestration - Zero Static Mappings**
+
+---
+
+## 📜 Mục Lục
+
+1. [Overview](#overview---whats-new-in-v20)
+2. [Agent Capability](#2-agent-capability--boundary)
+3. [Skill Activation](#3-skill-activation-dynamic)
+4. [Multi-Agent Chain](#4-multi-agent-orchestration)
+5. [Dynamic Command Mapping](#5-dynamic-command-mapping-new)
+6. [Confidence & Risk](#6-confidence--risk-aware)
+7. [Explainability](#7-explainability-layer)
+8. [Failure Mode](#8-failure-mode--self-restraint)
+9. [Agent-Skill Index](#9-agent-skill-index-v20)
+
+---
+
+## 1️⃣ Overview - What's New in v2.0
+
+### ✅ Achievements
+
+| Metric               | v1.x             | v2.0                | Improvement |
+| -------------------- | ---------------- | ------------------- | ----------- |
+| **Static Mappings**  | 7 commands (33%) | **0 commands (0%)** | ✅ -100%    |
+| **Dynamic Commands** | 14 (67%)         | **22 (100%)**       | ✅ +50%     |
+| **Skills Mapped**    | ~35 (64%)        | **55 (100%)**       | ✅ +57%     |
+| **Agents Utilized**  | 17/21 (81%)      | **21/21 (100%)**    | ✅ +24%     |
+
+### 🎯 Core Principles
+
+1. **No Hardcoding:** Every command uses conditionals
+2. **Context-First:** Decisions based on project structure, keywords, files
+3. **Auto-Escalation:** Security/critical tasks auto-escalate
+4. **Multi-Skill:** Tasks can activate multiple skills simultaneously
+5. **Explainable:** Every decision logged and explainable via `/why`
+
+---
+
+## 2️⃣ Agent Capability & Boundary
+
+Mỗi agent tự khai báo năng lực và giới hạn:
+
+```yaml
+# .cursor/agent-skill-index.yaml
+agents:
+  fullstack-developer:
+    capabilities:
+      - frontend_development
+      - backend_development
+      - api_design
+      - database_queries
+
+    boundaries:
+      - NOT: security_audit → security-auditor
+      - NOT: infrastructure → devops-engineer
+      - NOT: pure_ui_design → ui-ux-designer
+
+    primary_skills:
+      - frontend-development
+      - backend-development
+      - web-frameworks
+
+    secondary_skills:
+      - databases
+      - testing
+      - advanced-coding
+
+    confidence:
+      frontend: 0.9
+      backend: 0.85
+      devops: 0.3
+```
+
+### All 21 Agents Defined
+
+**Development (6):**
+
+- `fullstack-developer` - General development
+- `debugger` - Error analysis, performance
+- `tester` - Unit, E2E, TDD
+- `security-auditor` - Security review (auto-escalated)
+- `devops-engineer` - Infrastructure, deployment
+- `git-manager` - Version control
+
+**Design (3):**
+
+- `ui-ux-designer` - Visual design, UX flows
+- `design-system-architect` - Component libraries, tokens
+- `copywriter` - Content writing
+
+**Architecture (2):**
+
+- `ddd-architect` - Domain modeling
+- `database-admin` - Schema design, optimization
+
+**Research (3):**
+
+- `researcher` - Technology research
+- `scout` - Codebase exploration
+- `scout-external` - External tools, MCP
+
+**Management (2):**
+
+- `planner` - Task breakdown, orchestration
+- `project-manager` - Status reporting, organization
+
+**Content (3):**
+
+- `docs-manager` - Documentation
+- `journal-writer` - Progress tracking
+- `copywriter` - UX copy
+
+**Quality (2):**
+
+- `code-reviewer` - Code quality
+- `data-analyst` - Data analysis, visualization
+
+**Specialized (3):**
+
+- `mcp-manager` - MCP integration
+- `graph-architect` - Dependency analysis
+- `trend-watcher` - Skill updates
+
+---
+
+## 3️⃣ Skill Activation (Dynamic)
+
+Skills tự kích hoạt dựa trên context:
+
+```yaml
+# Example: payment-integration skill
+skills:
+  payment-integration:
+    agents: [fullstack-developer]
+
+    activation:
+      - keyword: ["payment", "stripe", "checkout", "billing"]
+      - package: ["stripe", "@stripe/stripe-js"]
+      - file_pattern: ["*payment*.ts", "*checkout*.tsx"]
+
+    requires_security_review: true # Auto-escalates!
+```
+
+### All 55 Skills with Triggers
+
+**Frontend (8):**
+
+- `frontend-development`: `*.tsx`, `components/`, "react"
+- `ui-styling`: `*.css`, `tailwindcss`, "theme"
+- `aesthetic`: "beautiful", "premium", "modern"
+- `canvas-design`: "canvas", "svg", `konva`
+- `frontend-design`: "layout", "responsive"
+- `frontend-design-pro`: "advanced ui", "complex"
+- `ui-ux-pro-max`: "ux flow", "wireframe"
+- `theme-factory`: "dark mode", `/theme`
+
+**Backend (5):**
+
+- `backend-development`: `api/`, `*.ts`, "server"
+- `databases`: `schema.prisma`, "migration", `drizzle-orm`
+- `ddd-modular-monolith`: "domain", `domain/`, "aggregate"
+- `web-frameworks`: `next`, `express`, `fastify`
+- `software-architecture`: "architecture", `/design --domain`
+
+**Integration (3):**
+
+- `payment-integration`: "stripe", `stripe` package, **AUTO-ESCALATE**
+- `better-auth`: "auth", "login", `next-auth`, **AUTO-ESCALATE**
+- `shopify`: "shopify", `@shopify/app`
+
+**Testing (6):**
+
+- `test-driven-development`: `/test`, "tdd"
+- `playwright-testing`: `@playwright/test`, "--e2e"
+- `test-fixing`: "fix test", "broken test"
+- `pypict-testing`: "combinatorial", "pairwise"
+- `debugging`: "debug", "error", "bug"
+- `chrome-devtools`: "devtools", "performance"
+
+**And 33 more skills...** (see [agent-skill-index.yaml](../.cursor/agent-skill-index.yaml))
+
+---
+
+## 4️⃣ Multi-Agent Orchestration
+
+AI tự động xây dựng execution chains:
+
+```yaml
+# .cursor/orchestration.yaml
+chains:
+  feature_development:
+    - agent: planner
+      output: implementation_plan
+
+    - agent: fullstack-developer
+      input: implementation_plan
+      output: code
+
+    - agent: tester
+      input: code
+      output: test_results
+
+    - agent: code-reviewer
+      input: [code, test_results]
+      output: review_feedback
+
+  security_chain:
+    - agent: planner
+      output: security_plan
+
+    - agent: fullstack-developer
+      input: security_plan
+      output: code
+
+    - agent: security-auditor # Auto-added for payment/auth
+      input: code
+      output: security_review
+
+    - agent: code-reviewer
+      input: [code, security_review]
+      output: final_review
+```
+
+### Risk-Based Execution
+
+```yaml
+risk_levels:
+  low:
+    keywords: ["typo", "rename", "format", "comment"]
+    chain: quick_fix
+    auto_approve: true
+
+  medium:
+    keywords: ["feature", "component", "api"]
+    chain: feature_development
+    require_review: true
+
+  high:
+    keywords: ["payment", "auth", "security", "database migration"]
+    chain: security_chain
+    require_lead_approval: true
+
+  critical:
+    keywords: ["delete", "drop", "production", "deploy"]
+    require_backup: true
+    manual_confirmation: true
+```
+
+---
+
+## 5️⃣ Dynamic Command Mapping ✨ NEW
+
+**Zero static mappings - 100% conditionals:**
+
+```yaml
+# .cursor/agent-skill-index.yaml
+command_mapping:
+  /do:
+    default: fullstack-developer
+    conditionals:
+      - if: "bug OR fix OR error" → debugger
+      - if: "design OR ui OR layout" → ui-ux-designer
+      - if: "plan OR roadmap" → planner
+      - if: "security OR auth OR payment" → security-auditor (escalate)
+      - if: "database OR schema" → database-admin (support)
+      - if: "deploy OR docker OR ci/cd" → devops-engineer
+      - if: "3d OR webgl" → ui-ux-designer + threejs
+      - if: "mobile OR react-native" → fullstack-developer + mobile-development
+    skills:
+      - auto-detect from request + tech stack
+
+  /demo:
+    default: fullstack-developer
+    conditionals:
+      - if: "docker-compose.yml exists" → devops-engineer
+      - if: "Dockerfile exists" → devops-engineer
+      - if: "vercel.json exists" → devops-engineer
+      - if: ".platform/ exists" → devops-engineer (AWS)
+      - if: "k8s/ exists" → devops-engineer
+    skills:
+      - devops
+      - aws-deployment (if AWS detected)
+      - web-frameworks
+
+  /commit:
+    default: git-manager
+    conditionals:
+      - if: "BREAKING change detected" → +changelog-generator
+      - if: "conventional format" → +git-automation
+      - if: "files > 20" → code-reviewer (review first)
+      - if: "auth OR payment files" → security-auditor (review first)
+    skills:
+      - git-automation
+      - changelog-generator
+
+  /clean:  # NEW in v2.0
+    default: project-manager
+    conditionals:
+      - if: "--memory" → docs-manager
+      - if: "--audit" → code-reviewer
+      - if: "--all" → project-manager + file-organizer
+    skills:
+      - file-organizer
+      - document-skills
+      - kaizen
+```
+
+### All 22 Commands Mapped
+
+Every command now has:
+
+- ✅ `default` agent (fallback)
+- ✅ `conditionals` (smart routing)
+- ✅ `skills` (auto-activation)
+
+---
+
+## 6️⃣ Confidence & Risk-Aware
+
+AI tự đánh giá confidence và risk:
+
+```yaml
+# Example: /do "add Stripe payment"
+
+Step 1: Keyword Analysis
+✅ "stripe" → payment-integration skill
+✅ "payment" → HIGH RISK keyword
+
+Step 2: Agent Selection
+- Primary: fullstack-developer (confidence: 0.85)
+- Escalate to: security-auditor (required for payment)
+
+Step 3: Risk Assessment
+- Risk Level: HIGH
+- Chain: security_chain (not quick_fix)
+- Requires: security review + lead approval
+
+Step 4: Skill Activation
+✅ payment-integration/
+✅ security-best-practices/
+✅ backend-development/
+✅ frontend-development/
+
+Step 5: Execute with Safety
+- Auto-backup before changes
+- Security checklist required
+- Manual confirmation before deploy
+```
+
+### Automatic Escalation
+
+```yaml
+escalation:
+  security_concern:
+    from: any
+    to: security-auditor
+    automatic: true
+    triggers:
+      - keyword: ["payment", "auth", "password", "token"]
+      - file: ["*auth*", "*payment*", "*.env"]
+      - package: ["stripe", "bcrypt", "jsonwebtoken"]
+
+  database_design:
+    from: fullstack-developer
+    to: database-admin
+    automatic: true
+    triggers:
+      - keyword: ["schema", "migration", "index", "query optimization"]
+      - complexity: high
+      - file: ["prisma/", "drizzle/"]
+```
+
+---
+
+## 7️⃣ Explainability Layer
+
+Mọi quyết định đều được giải thích qua `/why`:
+
+```bash
+User: /do "add payment"
+
+AI: [Executes task]
+
+User: /why
+
+AI: 📊 Decision Analysis for Last Task
+
+════════════════════════════════════════
+
+🎯 Task: "add payment"
+
+🤖 Agent Selection:
+  Primary: fullstack-developer
+    Reason: General development capability (0.85 confidence)
+
+  Escalated: security-auditor
+    Reason: "payment" keyword triggered security review
+    Automatic: Yes (requires_security_review: true)
+
+🧠 Skill Activation:
+  ✅ payment-integration/
+    Trigger: keyword "payment"
+
+  ✅ security-best-practices/
+    Trigger: auto-escalation to security-auditor
+
+  ✅ backend-development/
+    Trigger: API creation needed
+
+  ✅ frontend-development/
+    Trigger: UI components needed
+
+📋 Rules Applied:
+  1. agent-skill-index.yaml → command_mapping./do
+  2. Conditional: "payment" → security-auditor
+  3. orchestration.yaml → security_chain
+  4. failure-modes.yaml → requires_security_review
+
+⚠️ Risk Assessment:
+  Level: HIGH
+  Chain: security_chain (not quick_fix)
+  Requirements:
+    - Security review: Required
+    - Lead approval: Required
+    - Backup: Automatic
+
+  Auto-escalation: Triggered
+  Manual confirmation: Required before deploy
+
+📁 Files Affected:
+  - api/payment.ts (created)
+  - components/Checkout.tsx (created)
+  - __tests__/payment.test.ts (created)
+
+⏱️ Duration: 2m 34s
+
+🔧 Model Used:
+  Primary: Sonnet 4.5 (security tasks)
+  Support: GPT-5.1 Codex (code generation)
+
+════════════════════════════════════════
+```
+
+---
+
+## 8️⃣ Failure Mode & Self-Restraint
+
+AI tự kiểm soát khi gặp tình huống nguy hiểm:
+
+```yaml
+# .cursor/failure-modes.yaml
+stop_conditions:
+  - file_pattern: ["*.env", "*.key", ".secret*"]
+    action: ASK_USER
+    message: "⚠️ Modifying secret files. Confirm? [Y/n]"
+
+  - keyword: ["DROP TABLE", "DELETE FROM", "rm -rf"]
+    action: BLOCK
+    message: "🛑 Destructive operation detected. Use /do with --force"
+
+  - complexity: very_high
+    confidence: < 0.5
+    action: ESCALATE
+    to: planner
+    message: "🤔 Task too complex. Creating implementation plan first..."
+
+restraint_rules:
+  payment_logic:
+    never_modify:
+      - "without security review"
+      - "in production without backup"
+    always_validate:
+      - "PCI compliance checklist"
+      - "Test with test keys first"
+
+  database_migration:
+    must_have:
+      - "Backup strategy"
+      - "Rollback plan"
+      - "Test on staging first"
+```
+
+---
+
+## 9️⃣ Agent-Skill Index v2.0
+
+**Complete mapping:** [.cursor/agent-skill-index.yaml](../.cursor/agent-skill-index.yaml)
+
+### Stats
+
+- **Agents:** 21/21 (100% utilized)
+- **Skills:** 55/55 (100% mapped)
+- **Commands:** 22/22 (100% dynamic)
+- **Static mappings:** 0 (eliminated)
+
+### Structure
+
+```yaml
+# Top-level sections:
+
+agents:
+  # 21 agents with capabilities, boundaries, skills
+
+skills:
+  # 55 skills with activation triggers
+
+command_mapping:
+  # 22 commands with dynamic conditionals
+```
+
+### Example: Full Skill Definition
+
+```yaml
+skills:
+  payment-integration:
+    agents: [fullstack-developer]
+
+    activation:
+      - keyword: ["payment", "stripe", "checkout", "billing"]
+      - package: ["stripe", "@stripe/stripe-js"]
+      - file_pattern: ["*payment*.ts"]
+      - command: ["/do", "/integrate"]
+
+    requires_security_review: true
+
+    dependencies:
+      - backend-development
+      - frontend-development
+
+    auto_escalate_to: security-auditor
+
+    risk_level: high
+```
+
+---
+
+## 🎯 How It Works: End-to-End Example
+
+```bash
+User: /do "create dashboard with 3D charts and real-time updates"
+
+════════════════════════════════════════
+[1] ANALYZE REQUEST
+
+Keywords detected:
+  - "dashboard" → ui-related
+  - "3d" → threejs skill
+  - "charts" → d3-visualization skill
+  - "real-time" → websockets
+
+File patterns: none (new feature)
+Project structure: React + TypeScript detected
+
+════════════════════════════════════════
+[2] SELECT AGENTS
+
+Primary: ui-ux-designer
+  Reason: "dashboard" + "3d" → UI focus
+  Confidence: 0.9
+
+Support: fullstack-developer
+  Reason: "real-time" needs backend
+  Confidence: 0.85
+
+No escalation needed (no security concerns)
+
+════════════════════════════════════════
+[3] ACTIVATE SKILLS
+
+✅ threejs/
+   Trigger: keyword "3d"
+
+✅ d3-visualization/
+   Trigger: keyword "charts"
+
+✅ ui-styling/
+   Trigger: UI task, auto-activated
+
+✅ aesthetic/
+   Trigger: dashboard → premium design
+
+✅ websockets/
+   Trigger: keyword "real-time"
+
+✅ frontend-development/
+   Trigger: always for UI tasks
+
+════════════════════════════════════════
+[4] BUILD EXECUTION CHAIN
+
+orchestration.yaml → feature_development chain:
+
+1. planner
+   - Create implementation plan
+   - Break down: 3D scene + charts + WebSocket
+
+2. ui-ux-designer (primary)
+   - Design dashboard layout
+   - Plan 3D scene structure
+   - Design chart components
+
+3. fullstack-developer (support)
+   - Implement WebSocket server
+   - Create real-time data API
+   - Backend infrastructure
+
+4. tester
+   - Write component tests
+   - Test WebSocket connection
+   - Performance testing
+
+5. code-reviewer
+   - Review for performance
+   - Check accessibility
+   - Final approval
+
+════════════════════════════════════════
+[5] EXECUTE WITH INTELLIGENCE
+
+✅ Created:
+   - components/Dashboard.tsx
+   - components/3DChart.tsx
+   - lib/websocket.ts
+   - api/realtime.ts
+   - __tests__/dashboard.test.tsx
+
+✅ Skills used: 6
+✅ Agents coordinated: 5
+✅ Risk level: medium
+✅ Duration: 5m 12s
+
+════════════════════════════════════════
+[6] LOG & EXPLAIN
+
+Logged to: .ai-audit/2025-12-27.jsonl
+
+Available via: /why
+```
+
+---
+
+## 📊 Migration from v1.x to v2.0
+
+### Breaking Changes
+
+**None for end users.** Internal structure changed but commands work the same.
+
+### What Changed
+
+| Component                | v1.x                       | v2.0                           |
+| ------------------------ | -------------------------- | ------------------------------ |
+| `agent-skill-index.yaml` | 500 lines                  | 834 lines (rewritten)          |
+| Command docs             | Some missing orchestration | All have orchestration section |
+| Commands                 | 21                         | 22 (+/clean)                   |
+| Static mappings          | 7                          | 0 (eliminated)                 |
+
+### Recommended Actions
+
+1. **Review `/why` output** - See improved decision-making
+2. **Try `/clean`** - New self-healing command
+3. **Test security escalation** - Try `/ "add payment"`
+4. **Explore multi-skill** - Try `/do "3D chart dashboard"`
+
+---
+
+## 🎓 Best Practices
+
+### For AI Developers
+
+1. **Always define conditionals** - No hardcoded agents
+2. **Use activation triggers** - Skills auto-activate
+3. **Document boundaries** - Clear agent limits
+4. **Implement escalation** - Auto-escalate risks
+5. **Log decisions** - For `/why` transparency
+
+### For Users
+
+1. **Trust the system** - Let AI choose agents
+2. **Use `/why`** - Understand decisions
+3. **Add keywords** - Help AI detect context
+4. **Review with `/clean`** - Maintain system health
+5. **Learn from `/audit`** - See decision patterns
+
+---
+
+## 🔮 Future Enhancements
+
+v2.1 Planned:
+
+- **Auto-learning** - Skills learn from success/failure
+- **MCP auto-detection** - Dynamic tool discovery
+- **Community skills** - Skill marketplace
+- **Performance metrics** - Decision quality tracking
+
+---
+
+**v2.0 - Zero Static Mappings, 100% Intelligence** 🚀
+
+**Updated:** 2025-12-27  
+**Maintainer:** Anchi Kit Team