@leejungkiin/awkit 1.0.1 → 1.0.3

package/skills/beads-manager/SKILL.md

@@ -4,116 +4,243 @@ description: Smart Beads task management with Brain integration
 trigger: always
 ---
 
-# Beads Manager Skill (v5.0)
+# Beads Manager Skill (v6.5) — Hierarchical Epic Architecture
 
-> **Purpose:** Quản lý tasks trong Beads với Brain context awareness.
+> **Purpose:** Quản lý tasks trong Beads với 3-level hierarchy (Epic → Phase → Subtask),
+> Brain context awareness, và structured JSON output.
+>
+> **Requires:** Beads CLI v0.47+ (`bd version` to check)
+
+---
+
+## Architecture Overview
+
+```
+🏔️ EPIC (bd create -t epic)           ← 1 per /plan or /planExpert
+├── 📦 Phase Task (--parent <epic>)    ← Groups of related work
+│   ├── 📝 Subtask (--parent <phase>)  ← Atomic unit of work (~15-30 min)
+│   ├── 📝 Subtask
+│   └── 📝 Subtask
+├── 📦 Phase Task
+│   ├── 📝 Subtask
+│   └── 📝 Subtask
+└── ...
+```
+
+**Key Principles:**
+- 1 Epic = 1 Feature/Plan
+- Phase = sequential group (dependencies between phases)
+- Subtask = smallest unit AI executes in 1 session
+- All commands use `--json` for structured output
+- `bd ready --parent <epic>` = intelligent task selection
 
 ---
 
 ## Core Functions
 
-### 1. Smart Task Creation
+### 1. `plan_to_beads()` — Plan → Beads Sync
+
+**Trigger:** When `/planExpert` or `/plan` finishes generating plan files.
+
+**Process:**
 
-**Auto-Context:**
 ```bash
-# Khi tạo task, tự động:
-1. Detect current plan/phase từ Brain
-2. Link task to parent phase
-3. Set priority based on dependencies
-4. Add relevant labels
+# Step 1: Create epic (root node)
+EPIC_ID=$(bd create "Feature Name" -t epic -p 1 \
+  --description "Full feature description" \
+  --acceptance "High-level acceptance criteria" \
+  --design "Architecture approach (Clean Arch, MVVM, etc.)" \
+  --json | jq -r '.id')
+
+# Step 2: Create phase tasks as children of epic
+PHASE1_ID=$(bd create "Phase 1: Setup & Config" \
+  --parent $EPIC_ID -p 1 \
+  --description "Project scaffolding and configuration" \
+  --json | jq -r '.id')
+
+PHASE2_ID=$(bd create "Phase 2: Backend API" \
+  --parent $EPIC_ID -p 1 \
+  --description "RESTful API endpoints" \
+  --json | jq -r '.id')
+
+# Step 3: Create subtasks as children of phases
+bd create "Setup project structure" \
+  --parent $PHASE1_ID -p 2 \
+  --acceptance "Directory structure matches architecture" \
+  --json
+
+bd create "Configure database" \
+  --parent $PHASE1_ID -p 2 \
+  --acceptance "DB configured, migrations ready" \
+  --json
+
+# Step 4: Set inter-phase dependencies
+bd dep add $PHASE2_ID $PHASE1_ID   # Phase 2 depends on Phase 1
+bd dep add $PHASE3_ID $PHASE2_ID   # Phase 3 depends on Phase 2
+
+# Step 5: Save to brain
+# → Update brain/active_plans.json with epic mapping
 ```
 
-**Example:**
-```bash
-# User gõ
-bd create "Fix login bug"
-
-# Skill auto-enhance
-bd create "Fix login bug" \
-  --parent $CURRENT_PHASE_TASK \
-  --label bug \
-  --priority 0 \
-  --note "Related to plan: Shopping Cart, Phase 02"
+**Rules:**
+- Mỗi `/planExpert` hoặc `/plan` tạo **đúng 1 epic**
+- Epic chứa metadata tổng quan (acceptance + design)
+- Caps: max 8 phases/epic, max 5 subtasks/phase
+- Every subtask MUST have `--acceptance` criteria
+
+**Output Report:**
+```
+✅ PLAN CREATED — "Shopping Cart Feature"
+
+🏔️ Epic: bd-a3f8 (Shopping Cart Feature)
+├── 📦 bd-b1c2 Phase 1: Setup & Config (3 subtasks)
+├── 📦 bd-d3e4 Phase 2: Backend API (3 subtasks)
+├── 📦 bd-f5g6 Phase 3: Frontend UI (2 subtasks)
+└── 📦 bd-h7i8 Phase 4: Testing (2 subtasks)
+
+📊 Total: 1 epic, 4 phases, 10 subtasks
+📿 Dependencies: Phase 1 → 2 → 3 → 4
+
+➡️ Next: /codeExpert (starts first ready subtask)
 ```
 
 ---
 
-### 2. Task Status Tracking
+### 2. `smart_pick()` — Intelligent Task Selection
+
+**Trigger:** Session start, `/codeExpert`, `/next`
+
+**Process:**
 
-**Auto-Update:**
 ```bash
-# Khi workflow hoàn thành
-/codeExpert → Auto: bd update $TASK_ID --status done
+# Step 1: Get current epic from brain
+EPIC_ID=$(cat brain/active_plans.json | jq -r '.current.epic_id')
+
+# Step 2: Check in-progress first
+IN_PROGRESS=$(bd list --status in_progress --parent $EPIC_ID --json)
+if [ "$IN_PROGRESS" != "[]" ]; then
+  # Resume existing task
+  echo "🔁 Resuming: $(echo $IN_PROGRESS | jq -r '.[0].title')"
+  exit 0
+fi
+
+# Step 3: Get ready (unblocked) tasks
+READY=$(bd ready --parent $EPIC_ID --json --limit 5)
 
-# Khi gặp blocker
-/debugExpert fail → Auto: bd update $TASK_ID --status blocked
+# Step 4: Auto-claim first ready task
+TASK_ID=$(echo $READY | jq -r '.[0].id')
+bd update $TASK_ID --claim
 ```
 
-**Status Sync:**
-- `open` → Task mới tạo
-- `in_progress` → Đang làm
-- `blocked` → Bị chặn bởi task khác
-- `done` → Hoàn thành
-- `cancelled` → Hủy bỏ
+**Output:**
+```
+🎯 Working on: bd-x1y2 "Configure database"
+   📦 Phase: Phase 1: Setup & Config
+   ✅ Acceptance: DB configured, migrations ready
+   📋 Design: Use Room/SQLite with migration support
+```
+
+**Fallback (no epic):**
+```bash
+# Legacy flat mode for backward compatibility
+bd list --status in_progress --json
+# or
+bd ready --json --limit 5
+```
 
 ---
 
-### 3. Dependency Management
+### 3. `cascade_complete()` — Smart Completion
+
+**Trigger:** When a task/subtask is completed.
+
+**Process:**
 
-**Auto-Detect:**
 ```bash
-# Khi tạo task từ plan
-Phase 01 → Task A, B, C
-Phase 02 → Task D, E (depends on Phase 01)
-
-# Auto-create dependencies
-bd dep add D A
-bd dep add D B
-bd dep add D C
+# Step 1: Close the subtask
+bd close <subtask-id> --reason "Completed" --suggest-next
+
+# Step 2: Check if parent phase can be auto-closed
+bd epic close-eligible
+# → Auto-detects and closes phases/epics where all children are done
+
+# Step 3: Update brain/active_plans.json
+# → Mark completed phases, update progress
 ```
 
-**Blocker Alert:**
-```bash
-# Khi user chọn task bị block
-/codeExpert → Check dependencies
-→ "Task #125 blocked by #120 (not done yet)"
-→ Suggest: "Do task #120 first?"
+**Example Cascade:**
 ```
+Close bd-z1 (last subtask of Phase 1)
+  ✅ bd-z1 closed — "Setup project structure"
+  ✅ bd-b1c2 auto-closed — Phase 1: Setup & Config (all 3/3 subtasks done)
+  → Next ready: bd-x2y3 "Create Cart model" (Phase 2, now unblocked)
+```
+
+**Rules:**
+- Auto-close phase when ALL its subtasks are done
+- Auto-close epic when ALL its phases are done
+- Always `--suggest-next` to show what's unblocked
+- No user confirmation needed (low friction)
 
 ---
 
-### 4. Task Filtering & Search
+### 4. `progress_dashboard()` — Visual Progress
 
-**Smart Filters:**
-```bash
-# By status
-bd list --status open
-bd list --status in_progress
+**Trigger:** `/todo`, session start, after each task completion.
 
-# By label
-bd list --label bug
-bd list --label feature
+**Process:**
 
-# By priority
-bd list --priority 0    # Critical
-bd list --priority 1    # High
-bd list --priority 2    # Normal
+```bash
+# Get epic status
+bd epic status --json
+# Get hierarchy tree
+bd list --parent $EPIC_ID --tree
+```
 
-# Ready to work (no blockers)
-bd ready
+**Output:**
+```
+🏔️ Shopping Cart Feature [████████░░] 60%
+
+✅ Phase 1: Setup & Config [3/3] — DONE
+🔵 Phase 2: Backend API [1/3] — IN PROGRESS
+   ✅ bd-x2y3 Create Cart model
+   🔵 bd-x3y4 Cart CRUD API ← CURRENT
+   ⬜ bd-x4y5 Payment integration
+⬜ Phase 3: Frontend UI [0/2] — BLOCKED (by Phase 2)
+⬜ Phase 4: Testing [0/2] — BLOCKED (by Phase 3)
+```
+
+**Fallback (no epic):**
+```bash
+# Legacy mode
+bd list --status open --limit 10
+bd list --status in_progress
 ```
 
 ---
 
-### 5. Task Completion Flow
+### 5. `track_metadata()` — Rich Task Data
+
+**Trigger:** When creating or updating any task.
+
+**Fields to use:**
 
-**When task done:**
+| Flag | Purpose | Example |
+|------|---------|---------| 
+| `--description` | Detailed task description | "Implement REST endpoints for cart CRUD" |
+| `--acceptance` | Definition of Done (DoD) | "All 4 endpoints return correct status codes" |
+| `--design` | Architecture / implementation approach | "Repository pattern + Use Cases" |
+| `--notes` | Runtime findings, blockers | "Found N+1 query issue, need optimization" |
+| `--body-file` | Link to detailed spec file | "docs/specs/cart-api.md" |
+
+**Example:**
 ```bash
-1. bd update $TASK_ID --status done
-2. Check if phase complete (all tasks done)
-3. If phase complete → Update plan.md progress
-4. Suggest next task: bd ready
-5. Prompt: "Save knowledge? /save-brain"
+bd create "Implement Cart API" \
+  --parent $PHASE_ID -p 1 \
+  --description "REST endpoints: GET/POST/PUT/DELETE /api/cart" \
+  --acceptance "All CRUD ops work, validation on input, 401 for unauth" \
+  --design "Repository pattern, DTOs for request/response" \
+  --json
 ```
 
 ---
@@ -123,116 +250,130 @@ bd ready
 ### `/planExpert` Integration
 
 ```bash
-# After plan generation
-1. Call sync_plan_to_beads.sh
-2. Create parent + phase + task hierarchy
-3. Set dependencies
-4. Report: "Created 42 tasks in Beads"
+# After plan generation — replaces flat loop
+1. bd create "<feature>" -t epic -p 1 --json           # Create epic
+2. For each phase: bd create "<phase>" --parent <epic> --json  # Phases
+3. For each task: bd create "<task>" --parent <phase> --acceptance "..." --json  # Subtasks
+4. bd dep add <phase-N+1> <phase-N>                     # Sequential deps
+5. Save epic mapping → brain/active_plans.json
+6. Report tree view
 ```
 
 ### `/codeExpert` Integration
 
 ```bash
-# Before coding
-1. bd list --status in_progress
-2. If found → Resume that task
-3. If not → bd ready → Pick P0 task
-4. Update task status to in_progress
-
-# After coding
-1. Run tests
-2. If pass → bd update --status done
-3. If fail → bd update --status blocked + create bug task
+# Before coding — replaces manual bd list
+1. smart_pick() → Get current or next ready task from epic
+2. Load acceptance criteria as DoD
+3. Code against acceptance criteria
+
+# After coding — replaces bd update --status done
+1. cascade_complete() → Close task + auto-close parent if eligible
+2. Suggest next ready task
 ```
 
-### `/debugExpert` Integration
+### `/plan` (Guided Mode) Integration
 
-```bash
-# When bug found
-1. bd create "Fix: $ERROR_MESSAGE" --label bug --priority 0
-2. Link to failing task (if any)
-3. After fix → bd update --status done
-```
+Same as `/planExpert` but phases/tasks created incrementally as user confirms each phase.
 
 ---
 
 ## Brain Integration
 
-### Active Plans Tracking
+### `active_plans.json` Schema (v6.5)
 
 ```json
-// brain/active_plans.json
 {
   "current": {
-    "plan_path": "plans/260130-1025-shopping-cart/",
+    "epic_id": "bd-a3f8",
     "feature": "Shopping Cart",
-    "beads_parent_id": 456,
+    "plan_path": "plans/260301-2109-shopping-cart/",
     "phases": [
       {
-        "name": "Phase 01: Setup",
-        "beads_id": 457,
-        "status": "done"
+        "beads_id": "bd-b1c2",
+        "name": "Phase 1: Setup & Config",
+        "subtasks": ["bd-c1d2", "bd-c3d4", "bd-c5d6"],
+        "status": "done",
+        "depends_on": null
       },
       {
-        "name": "Phase 02: Backend",
-        "beads_id": 458,
+        "beads_id": "bd-d3e4",
+        "name": "Phase 2: Backend API",
+        "subtasks": ["bd-e1f2", "bd-e3f4", "bd-e5f6"],
         "status": "in_progress",
-        "tasks": [123, 124, 125]
+        "depends_on": "bd-b1c2"
       }
     ]
-  }
+  },
+  "plans": []
 }
 ```
 
 ### Task-Knowledge Linking
 
 ```bash
-# When save knowledge
+# When saving knowledge during a task
 /save-brain "How to fix N+1 query"
-
-# Auto-link to current task
-→ Save to: brain/solutions/n1-query-fix_#123.md
-→ Add reference in task: bd update 123 --note "Solution: brain/solutions/..."
+→ Save to: brain/solutions/n1-query-fix.md
+→ Update task notes: bd update <id> --notes "Solution: brain/solutions/..."
 ```
 
 ---
 
-## Commands Reference
+## Gate Updates Reference
 
-### Basic Commands
+### Gate 0 — Session Start
 
 ```bash
-# Create task
-bd create "Task name" [--priority 0-2] [--label tag]
-
-# List tasks
-bd list [--status STATUS] [--label LABEL]
+# Check active epic
+EPIC_ID=$(cat brain/active_plans.json | jq -r '.current.epic_id // empty')
+
+if [ -n "$EPIC_ID" ]; then
+  # Hierarchical mode
+  bd epic status --json            # Epic progress
+  bd list --parent $EPIC_ID --tree # Tree view
+else
+  # Legacy flat mode
+  bd list --status in_progress
+  bd list --status open --limit 3
+fi
+```
 
-# Update task
-bd update <id> --status STATUS
+### Gate 1 — Before Coding
 
-# Show task details
-bd show <id>
+```bash
+if [ -n "$EPIC_ID" ]; then
+  smart_pick()  # From epic hierarchy
+else
+  # Legacy: create flat task
+  bd create "[task summary]" --priority 1
+  bd update <id> --status in_progress
+fi
+```
 
-# Add dependency
-bd dep add <child> <parent>
+### Gate 2 — After Completion
 
-# Ready tasks (no blockers)
-bd ready
+```bash
+if [ -n "$EPIC_ID" ]; then
+  cascade_complete()  # Close + auto-cascade + suggest next
+else
+  bd update <id> --status done
+  bd list --status open --limit 3
+fi
 ```
 
-### Enhanced Commands (via Skill)
+---
 
-```bash
-# Smart create (auto-context)
-/task "Task name"    # Alias, auto-add context
+## Backward Compatibility
 
-# Quick status
-/todo                # Alias for bd list
-/done "Note"         # Mark current task done + save note
+```
+Detection logic:
+  1. Read brain/active_plans.json
+  2. If "current.epic_id" exists → Hierarchical mode (v6.5)
+  3. If "current.epic_id" missing → Legacy flat mode (v5.0)
+  4. All legacy bd commands continue to work
 
-# Task navigation
-/next                # Show next recommended task
+No breaking changes. Existing flat tasks are unaffected.
 ```
 
 ---
@@ -243,68 +384,41 @@ bd ready
 
 ```bash
 if ! command -v bd &> /dev/null; then
-    echo "⚠️ Beads not installed"
-    echo "Fallback: Use Brain-only mode"
-    # Continue without task tracking
+    echo "⚠️ Beads CLI not installed"
+    echo "Fallback: Brain-only mode (active_plans.json tracking)"
 fi
 ```
 
-### Task Not Found
+### Beads Version Too Old
 
 ```bash
-bd show 999
-→ "❌ Task #999 not found"
-→ Suggest: "bd list to see all tasks"
+BD_VERSION=$(bd version 2>/dev/null | grep -oP '\d+\.\d+\.\d+')
+# Require 0.47+ for --parent, -t epic, --json, bd epic
+if [ "$(printf '%s\n' "0.47.0" "$BD_VERSION" | sort -V | head -n1)" != "0.47.0" ]; then
+    echo "⚠️ Beads $BD_VERSION too old. Need 0.47+. Falling back to flat mode."
+fi
 ```
 
-### Circular Dependency
+### No Active Epic
 
 ```bash
-bd dep add A B
-bd dep add B A
-→ "❌ Circular dependency detected"
-→ Suggest: "Remove one dependency"
+# Graceful fallback to legacy flat mode
+# All functions check for epic_id first, fall back to flat commands
 ```
 
 ---
 
-## Performance
-
-- **Task Creation:** < 100ms
-- **List Tasks:** < 200ms (for 100 tasks)
-- **Dependency Check:** < 50ms
-- **Brain Sync:** < 500ms
-
----
-
-## Example Workflow
+## Commands Quick Reference
 
-```bash
-# 1. Create plan
-/planExpert "Shopping Cart"
-→ Creates 42 tasks in Beads
-
-# 2. Check tasks
-bd list
-→ Shows all tasks with status
-
-# 3. Start coding
-/codeExpert
-→ Auto-picks task #123 (P0, ready)
-→ Updates status to in_progress
-
-# 4. Complete task
-→ Tests pass
-→ Auto: bd update 123 --status done
-
-# 5. Next task
-/next
-→ Suggests task #124 (next P0)
-
-# 6. Save knowledge
-/save-brain "Login API implementation"
-→ Links to task #123
-```
+| Command | v5.0 (Old) | v6.5 (New) |
+|---------|------------|------------|
+| Create plan tasks | `bd create` loop | `bd create -t epic` + `--parent` hierarchy |
+| Pick next task | `bd list --status open` | `bd ready --parent <epic> --json` |
+| Claim task | `bd update --status in_progress` | `bd update --claim` |
+| Complete task | `bd update --status done` | `bd close --reason --suggest-next` |
+| Close phase | Manual | `bd epic close-eligible` (auto) |
+| View progress | `bd list` | `bd list --parent <epic> --tree` |
+| Epic status | N/A | `bd epic status --json` |
 
 ---
 
@@ -317,7 +431,10 @@ bd list
     "auto_create": true,
     "auto_update": true,
     "default_priority": 2,
-    "labels": ["feature", "bug", "refactor"]
+    "max_phases_per_epic": 8,
+    "max_subtasks_per_phase": 5,
+    "use_hierarchy": true,
+    "labels": ["feature", "bug", "refactor", "chore"]
   }
 }
 ```