anchi-toolkit 1.0.0

package/docs/ORCHESTRATION_RUNTIME.md

@@ -0,0 +1,173 @@
+# Dynamic Orchestration Runtime
+
+> **Quy trình AI tự động điều phối agents/skills khi thực thi command**
+
+---
+
+## 🔄 Execution Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ USER INPUT: /do "Add payment with Stripe"                   │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ STEP 1: LOAD ORCHESTRATION CONFIG                           │
+│                                                             │
+│   Read: .cursor/agent-skill-index.yaml                      │
+│   Read: .cursor/orchestration.yaml                          │
+│   Read: .cursor/failure-modes.yaml                          │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ STEP 2: ANALYZE USER REQUEST                                │
+│                                                             │
+│   Keywords detected: ["payment", "stripe"]                  │
+│   Files affected: [*.ts, prisma/schema.prisma]              │
+│   Complexity: medium                                        │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ STEP 3: DYNAMIC AGENT SELECTION                             │
+│                                                             │
+│   Check command_mapping:                                     │
+│   ├── /do → default: fullstack-developer                   │
+│   └── conditionals: none matched                             │
+│                                                             │
+│   Check agent boundaries:                                    │
+│   └── fullstack-developer.boundaries:                        │
+│       └── NOT: security_audit → security-auditor            │
+│                                                             │
+│   Result:                                                   │
+│   ├── PRIMARY: fullstack-developer (confidence: 0.85)       │
+│   └── SECONDARY: security-auditor (payment = sensitive)     │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ STEP 4: DYNAMIC SKILL ACTIVATION                            │
+│                                                             │
+│   Scan skills.activation rules:                              │
+│                                                             │
+│   payment-integration:                                       │
+│   ├── keyword: ["payment", "stripe"] → MATCH ✓              │
+│   ├── package: ["stripe"] → CHECK package.json              │
+│   └── requires_security_review: true → FLAG                 │
+│                                                             │
+│   databases:                                                 │
+│   └── file: prisma/schema.prisma → MATCH ✓                  │
+│                                                             │
+│   better-auth:                                               │
+│   └── keyword: ["auth", "login"] → NO MATCH                 │
+│                                                             │
+│   Activated: [payment-integration, databases]               │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ STEP 5: CHECK FAILURE MODES                                 │
+│                                                             │
+│   low_confidence:                                            │
+│   └── confidence 0.85 > 0.5 → OK                            │
+│                                                             │
+│   security_concern:                                          │
+│   └── payment = sensitive → ESCALATE to security-auditor    │
+│                                                             │
+│   architecture_violation:                                    │
+│   └── Check preset contract → OK                            │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ STEP 6: DETERMINE RISK LEVEL                                │
+│                                                             │
+│   Check orchestration.yaml risk_levels:                      │
+│   ├── keywords: ["payment"] → HIGH risk                     │
+│   └── chain: security_chain                                  │
+│                                                             │
+│   Required:                                                 │
+│   ├── auto_approve: false                                    │
+│   ├── require_review: true                                   │
+│   └── require_lead_approval: true                            │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ STEP 7: BUILD EXECUTION CHAIN                               │
+│                                                             │
+│   Chain: security_chain                                      │
+│   [1] planner → Create plan                                 │
+│   [2] fullstack-developer → Implement                       │
+│   [3] security-auditor → Security review                    │
+│   [4] code-reviewer → Final review                          │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ STEP 8: LOG TO AUDIT                                         │
+│                                                             │
+│   Write to .ai-audit/YYYY-MM-DD.jsonl:                       │
+│   {                                                         │
+│     "command": "/do 'Add payment'",                         │
+│     "agents": ["fullstack-developer", "security-auditor"],  │
+│     "skills": ["payment-integration", "databases"],         │
+│     "risk_level": "high",                                    │
+│     "chain": "security_chain"                                │
+│   }                                                         │
+└─────────────────────────────────────────────────────────────┘
+                           ↓
+┌─────────────────────────────────────────────────────────────┐
+│ STEP 9: EXECUTE WITH ORCHESTRATION                          │
+│                                                             │
+│   Apply agents, skills, and chain to implementation         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📋 Quy Tắc Điều Phối
+
+### Rule 1: Agent Selection Priority
+```
+1. Check command_mapping.conditionals
+2. If no match → Use command_mapping.default
+3. Check agent.boundaries for escalation
+4. Check skill.requires_security_review
+```
+
+### Rule 2: Skill Activation
+```
+FOR EACH skill IN agent-skill-index.yaml:
+  IF skill.activation.keyword MATCHES request:
+    ACTIVATE skill
+  IF skill.activation.file_pattern MATCHES affected_files:
+    ACTIVATE skill
+  IF skill.activation.package EXISTS IN package.json:
+    ACTIVATE skill
+```
+
+### Rule 3: Risk Assessment
+```
+Scan request for risk_levels keywords:
+  low: ["typo", "rename", "format"]
+  medium: ["feature", "component", "api"]
+  high: ["payment", "auth", "admin"]
+  critical: ["delete", "drop", "production"]
+
+Apply corresponding chain and approvals.
+```
+
+### Rule 4: Failure Mode Check
+```
+BEFORE execution:
+  IF confidence < 0.5 → ASK user
+  IF security_concern → ESCALATE
+  IF architecture_violation → STOP
+  IF outside_expertise → ESCALATE to appropriate agent
+```
+
+---
+
+## 🔗 Config Files
+
+| File | Purpose |
+|------|---------|
+| `.cursor/agent-skill-index.yaml` | Agent capabilities, skill activation |
+| `.cursor/orchestration.yaml` | Chains, risk levels, escalation |
+| `.cursor/failure-modes.yaml` | Stop conditions, restraints |
+| `.ai-audit/` | Audit logs |

package/docs/PROJECT.md

@@ -0,0 +1,140 @@
+# Project Overview & Requirements (PDR)
+
+> 📋 **Purpose:** PLANNING document - WHY & WHAT we're building
+> 
+> **For technical details (HOW):** See [CODEBASE.md](./CODEBASE.md)
+
+---
+
+## 🎯 Preset Đang Dùng
+
+- [ ] 🚀 **Rapid MVP** - Demo nhanh, prototype, < 2 tuần
+- [ ] 🏢 **Professional** - Sản phẩm thương mại, 1-6 tháng
+- [ ] 🏛️ **Enterprise** - Dự án lớn, DDD architecture, > 6 tháng
+
+---
+
+## 📌 Thông Tin Dự Án
+
+| Field | Value |
+|-------|-------|
+| **Project Name** | [Tên dự án] |
+| **Version** | 0.1.0 |
+| **Start Date** | [DD/MM/YYYY] |
+| **Target Launch** | [DD/MM/YYYY] |
+| **Team** | [Tên team] |
+
+---
+
+## 🎯 Problem & Solution
+
+### Vấn Đề Cần Giải Quyết
+
+[Mô tả pain points, problems mà dự án giải quyết]
+
+### Giải Pháp
+
+[Mô tả cách dự án giải quyết vấn đề]
+
+---
+
+## 👥 Target Users
+
+| User Type | Đặc điểm | Needs |
+|-----------|----------|-------|
+| [User 1] | [Mô tả] | [Needs] |
+| [User 2] | [Mô tả] | [Needs] |
+
+---
+
+## ✅ Features & Requirements
+
+### MVP Features (Phase 1)
+
+| Feature | Priority | Description |
+|---------|----------|-------------|
+| [Feature 1] | P0 | [Mô tả] |
+| [Feature 2] | P0 | [Mô tả] |
+| [Feature 3] | P1 | [Mô tả] |
+
+### Future Features (Phase 2+)
+
+| Feature | Priority | Description |
+|---------|----------|-------------|
+| [Feature 4] | P2 | [Mô tả] |
+
+---
+
+## 🔄 User Flows
+
+### Flow 1: [Tên Flow]
+
+```
+1. User vào trang home
+2. User click button X
+3. System hiển thị Y
+4. User submit form
+5. Done
+```
+
+### Flow 2: [Tên Flow]
+
+```
+[Mô tả flow]
+```
+
+---
+
+## 📊 Success Metrics
+
+| Metric | Target | How to Measure |
+|--------|--------|----------------|
+| [Metric 1] | [Value] | [Method] |
+| [Metric 2] | [Value] | [Method] |
+
+---
+
+## 📅 Timeline
+
+| Phase | Duration | Goals |
+|-------|----------|-------|
+| Phase 1: MVP | [X tuần] | [Goals] |
+| Phase 2: Enhancement | [X tuần] | [Goals] |
+
+---
+
+## ⚠️ Constraints & Risks
+
+### Constraints
+
+- **Budget:** [Constraint]
+- **Timeline:** [Constraint]
+- **Team Size:** [Constraint]
+
+### Risks
+
+| Risk | Impact | Mitigation |
+|------|--------|------------|
+| [Risk 1] | High | [Solution] |
+| [Risk 2] | Medium | [Solution] |
+
+---
+
+## 👥 Team
+
+| Role | Name | Responsibilities |
+|------|------|------------------|
+| Team Lead | [Name] | [Responsibilities] |
+| Developer | [Name] | [Responsibilities] |
+
+---
+
+## 🔗 References
+
+- [Design Files - Figma/etc]
+- [API Docs]
+- [Related Projects]
+
+---
+
+> 💡 **Note:** File này focus vào PLANNING. Xem [CODEBASE.md](./CODEBASE.md) cho technical details.

package/docs/ROADMAP.md

@@ -0,0 +1,184 @@
+# Project Roadmap
+
+> ⚠️ **Template:** Điền lộ trình phát triển của dự án.
+
+---
+
+## Current Status
+
+| Phase | Status | Progress |
+|-------|--------|----------|
+| Phase 1: MVP | 🔄 In Progress | [X]% |
+| Phase 2: Enhancement | ⏳ Planned | 0% |
+| Phase 3: Scale | ⏳ Planned | 0% |
+
+**Last Updated:** [DD/MM/YYYY]
+
+---
+
+## Phase 1: MVP
+
+**Timeline:** [Start Date] → [End Date]
+**Goal:** [Mục tiêu chính của phase này]
+
+### Features
+
+| Feature | Priority | Status | Owner | Notes |
+|---------|----------|--------|-------|-------|
+| [Feature 1] | 🔴 High | ✅ Done | [Name] | |
+| [Feature 2] | 🔴 High | 🔄 In Progress | [Name] | |
+| [Feature 3] | 🟡 Medium | ⬜ Planned | [Name] | |
+| [Feature 4] | 🟢 Low | ⬜ Planned | [Name] | |
+
+### Milestones
+
+| Milestone | Target Date | Status |
+|-----------|-------------|--------|
+| Core setup complete | [Date] | ✅ Done |
+| Auth working | [Date] | 🔄 In Progress |
+| MVP Demo | [Date] | ⬜ Planned |
+| MVP Launch | [Date] | ⬜ Planned |
+
+### Deliverables
+
+- [ ] [Deliverable 1]
+- [ ] [Deliverable 2]
+- [ ] [Deliverable 3]
+
+---
+
+## Phase 2: Enhancement
+
+**Timeline:** [Start Date] → [End Date]
+**Goal:** [Mục tiêu chính]
+
+### Features
+
+| Feature | Priority | Status | Description |
+|---------|----------|--------|-------------|
+| [Feature 5] | 🔴 High | ⬜ Planned | [Mô tả] |
+| [Feature 6] | 🟡 Medium | ⬜ Planned | [Mô tả] |
+
+### Technical Improvements
+
+| Improvement | Priority | Status | Description |
+|-------------|----------|--------|-------------|
+| Performance optimization | 🟡 Medium | ⬜ Planned | [Mô tả] |
+| Test coverage increase | 🟡 Medium | ⬜ Planned | [Mô tả] |
+
+---
+
+## Phase 3: Scale
+
+**Timeline:** [Start Date] → [End Date]
+**Goal:** [Mục tiêu chính]
+
+### Features
+
+| Feature | Priority | Status | Description |
+|---------|----------|--------|-------------|
+| [Feature 7] | 🔴 High | ⬜ Planned | [Mô tả] |
+| [Feature 8] | 🟡 Medium | ⬜ Planned | [Mô tả] |
+
+### Infrastructure
+
+| Task | Priority | Status | Description |
+|------|----------|--------|-------------|
+| [Scaling task] | 🔴 High | ⬜ Planned | [Mô tả] |
+
+---
+
+## Backlog
+
+### Features (Unscheduled)
+
+| Feature | Priority | Estimate | Notes |
+|---------|----------|----------|-------|
+| [Backlog item 1] | 🟢 Low | [X days] | [Notes] |
+| [Backlog item 2] | 🟢 Low | [X days] | [Notes] |
+
+### Technical Debt
+
+| Item | Priority | Estimate | Notes |
+|------|----------|----------|-------|
+| [Tech debt 1] | 🟡 Medium | [X days] | [Notes] |
+| [Tech debt 2] | 🟢 Low | [X days] | [Notes] |
+
+---
+
+## Completed
+
+### ✅ Done
+
+| Feature | Completed Date | Notes |
+|---------|----------------|-------|
+| [Completed feature 1] | [Date] | [Notes] |
+| [Completed feature 2] | [Date] | [Notes] |
+
+---
+
+## Changelog
+
+### [Version X.X.X] - [Date]
+
+**Added:**
+- [New feature 1]
+- [New feature 2]
+
+**Changed:**
+- [Change 1]
+
+**Fixed:**
+- [Bug fix 1]
+
+---
+
+### [Version X.X.X] - [Date]
+
+**Added:**
+- [New feature]
+
+---
+
+## Dependencies & Blockers
+
+### Current Blockers
+
+| Blocker | Impact | Owner | Resolution Plan |
+|---------|--------|-------|-----------------|
+| [Blocker 1] | High/Med/Low | [Name] | [Plan] |
+
+### Dependencies
+
+| Dependency | Depends On | Status |
+|------------|------------|--------|
+| [Feature X] | [Feature Y] | Waiting |
+
+---
+
+## Resource Allocation
+
+| Phase | Team Size | Duration |
+|-------|-----------|----------|
+| Phase 1 | [X] people | [X] weeks |
+| Phase 2 | [X] people | [X] weeks |
+| Phase 3 | [X] people | [X] weeks |
+
+---
+
+## Legend
+
+| Symbol | Meaning |
+|--------|---------|
+| ✅ | Done |
+| 🔄 | In Progress |
+| ⬜ | Planned |
+| ⏳ | Waiting |
+| ❌ | Cancelled |
+| 🔴 | High Priority |
+| 🟡 | Medium Priority |
+| 🟢 | Low Priority |
+
+---
+
+> 💡 **Tip:** Cập nhật file này mỗi tuần hoặc sau mỗi sprint. AI sẽ đọc file này khi bạn dùng `/plan` để đề xuất features phù hợp với roadmap.

package/docs/UX_MODES.md

@@ -0,0 +1,173 @@
+# UX Mode System
+
+> **Command mode → Command owns the UI
+> Prompt mode → AI Agent owns the UI**
+
+Hai mode **loại trừ nhau**, không bao giờ hiển thị song song.
+
+---
+
+## 📜 Rule #1: Mode Decides the Voice
+
+```
+IF user_input = command (starts with /)
+→ Command owns the UI
+
+ELSE (free text prompt)
+→ AI Agent owns the UI
+```
+
+**Không có ngoại lệ.**
+
+---
+
+## 1️⃣ Command Mode
+
+### Khi nào?
+User gõ command bắt đầu bằng `/`:
+```
+/do "Add login"
+/commit
+/test
+```
+
+### Hiển thị:
+- ✅ Command log (summary, files, status, risk)
+- ✅ Structured output
+- ✅ Governance indicators
+
+### Không hiển thị:
+- ❌ Agent progress narration
+- ❌ "AI decided…"
+- ❌ "User approved…"
+- ❌ Raw execution text
+
+> 👉 AI agent **im lặng hoàn toàn** ở UI.
+
+### Output Format:
+```
+📋 /do "Add user login"
+
+═══════════════════════════════════════════════
+📊 Analysis:
+├── Agent: fullstack-developer (0.85)
+├── Skills: better-auth, databases
+└── Risk: medium
+
+📋 Plan:
+1. Create AuthService
+2. Create login page
+3. Add session middleware
+
+⏱️ Estimated: 5-8 minutes
+═══════════════════════════════════════════════
+
+[Progress bar or status updates only]
+
+✅ Completed: 4 files created
+```
+
+---
+
+## 2️⃣ Prompt Mode (Chat Mode)
+
+### Khi nào?
+User gõ free text (không có `/`):
+```
+Create a walkthrough documentation for new users
+Can you help me understand the auth flow?
+```
+
+### Hiển thị:
+- ✅ AI agent narration
+- ✅ Progress updates
+- ✅ Explanations
+- ✅ "I'll create these files..."
+
+### Không hiển thị:
+- ❌ Command log format
+- ❌ Governance summary
+- ❌ Risk assessment
+
+> 👉 Đây là mode **exploratory**, không governance.
+
+### Output Format:
+```
+I'll help you create a walkthrough documentation for new users.
+
+Let me create the documentation file...
+
+[Creates docs/WALKTHROUGH.md]
+
+I've created the walkthrough with the following sections:
+- Day 1: Setup
+- Day 2: First feature
+...
+
+Would you like me to add anything else?
+```
+
+---
+
+## 📊 Comparison Table
+
+| Aspect | Command Mode | Prompt Mode |
+|--------|--------------|-------------|
+| **Purpose** | Controlled execution | Exploration |
+| **Narrator** | Command | AI Agent |
+| **UX** | Clean, tool-like | Rich, conversational |
+| **Log shown** | Command log | Agent narration |
+| **Best for** | Long-term, team | Quick trial, personal |
+| **Governance** | Yes | No |
+
+---
+
+## 🚨 Absolute Rules
+
+### ❌ Never Do:
+1. Show agent chat while in command mode
+2. Merge base log into command log
+3. Auto-switch to command log during free chat
+4. Mix narration styles
+
+### ✅ Always Do:
+1. Clear mode indicator
+2. Consistent log format per mode
+3. Let mode determine narrator
+4. Respect user's mode choice
+
+---
+
+## 🎯 Mode Indicator (Optional Enhancement)
+
+Display current mode to user:
+```
+┌─────────────────────────────────────┐
+│ Mode: Command 📋                    │
+└─────────────────────────────────────┘
+
+┌─────────────────────────────────────┐
+│ Mode: Chat 💬                       │
+└─────────────────────────────────────┘
+```
+
+User **luôn biết mình đang ở đâu**.
+
+---
+
+## 🧩 Why This Works
+
+| Benefit | Reason |
+|---------|--------|
+| No log conflict | Only 1 narrator at a time |
+| No overload | User sees only what they chose |
+| Matches kit philosophy | Command = governance, Prompt = freedom |
+| Easy to teach | "Want control → command", "Want explore → prompt" |
+
+---
+
+## 🔗 Related
+
+- [docs/ORCHESTRATION.md](./ORCHESTRATION.md) - AI meta-layer
+- [docs/AI_CONTRACT.md](./AI_CONTRACT.md) - Constitutional rules
+- [CURSOR.md](../CURSOR.md) - AI behavior configuration