feat(KB-328): bundle Fusion skill with CLI package for agent interoperability

- Add bundled Fusion skill at packages/cli/skill/fusion/ with SKILL.md and reference docs - Include workflow guides for task lifecycle, specifications, dashboard CLI, and task management - Add reference docs for CLI commands, extension tools, capabilities, best practices, and patterns - Add postinstall script to sync skill into ~/.pi/agent/skills/fusion on install - Add skill-sync test coverage and changeset for minor version bump
2026-04-02 13:26:08 -07:00
parent 88e213c4d7
commit 0518fdd977
15 changed files with 1435 additions and 0 deletions
--- a/packages/cli/skill/fusion/SKILL.md
+++ b/packages/cli/skill/fusion/SKILL.md
@@ -0,0 +1,101 @@
+---
+name: fusion
+description: AI-orchestrated task board (Fusion/kb) interface. Use when working with the Fusion task management system, creating or managing tasks, understanding task workflows, organizing work into missions, or interfacing with the kb dashboard. Triggers on "create a task", "list tasks", "show board", "plan a mission", "check task status", "import issues", or any Fusion/kb interaction.
+---
+
+<essential_principles>
+
+Fusion (kb) is an AI-orchestrated task board. You throw in rough ideas; AI specifies, executes, reviews, and delivers them.
+
+**Task lifecycle:** Triage → Todo → In Progress → In Review → Done → Archived
+
+- **Triage** — AI auto-generates a full specification (PROMPT.md) with steps, file scope, and acceptance criteria
+- **Todo** — Scheduler resolves dependencies and queues for execution
+- **In Progress** — Executor agent works in a git worktree: plan → review → execute → review per step
+- **In Review** — Completed work ready for merge (auto-merge or PR-based)
+- **Done** — Merged to main branch
+- **Archived** — Removed from active board view
+
+**Missions** provide hierarchical planning above tasks:
+Mission → Milestone → Slice → Feature → Task
+
+**Available tools:** Fusion registers tools via the pi extension (prefixed `kb_*`). No CLI commands or Bash needed — use the registered tools directly.
+
+**Tool categories:**
+- **Task tools** — `kb_task_create`, `kb_task_update`, `kb_task_list`, `kb_task_show`, `kb_task_attach`, `kb_task_pause`, `kb_task_unpause`, `kb_task_retry`, `kb_task_duplicate`, `kb_task_refine`, `kb_task_archive`, `kb_task_unarchive`, `kb_task_delete`, `kb_task_plan`
+- **GitHub tools** — `kb_task_import_github`, `kb_task_import_github_issue`, `kb_task_browse_github_issues`
+- **Mission tools** — `kb_mission_create`, `kb_mission_list`, `kb_mission_show`, `kb_mission_delete`, `kb_milestone_add`, `kb_slice_add`, `kb_feature_add`, `kb_slice_activate`, `kb_feature_link_task`
+- **Dashboard** — Use `/fn` command to start/stop the dashboard
+
+</essential_principles>
+
+<routing>
+
+Based on the user's request, route to the appropriate workflow:
+
+**Task operations:**
+- Create, list, show, manage tasks → workflows/task-management.md
+- Understand task columns, lifecycle, statuses → workflows/task-lifecycle.md
+
+**Planning and specifications:**
+- Plan complex work, break down ideas → workflows/specifications.md
+- Organize into missions, milestones, slices → workflows/specifications.md
+
+**Dashboard and CLI:**
+- Start dashboard, use CLI commands, settings → workflows/dashboard-cli.md
+
+**If the intent is simple and clear** (e.g., "create a task to fix the login bug"), execute directly using the appropriate `kb_*` tool without loading a workflow file. Only load workflows for guidance on complex operations or when the user needs help understanding Fusion concepts.
+
+</routing>
+
+<quick_reference>
+
+**Create a task:**
+Use `kb_task_create` with a descriptive message. Include the problem AND desired outcome.
+
+**List tasks:**
+Use `kb_task_list` to see all tasks grouped by column. Use `column` param to filter.
+
+**Show task details:**
+Use `kb_task_show` with the task ID (e.g., KB-001) to see steps, progress, and log.
+
+**Plan complex work:**
+Use `kb_task_plan` for AI-guided planning that interviews you before creating the task.
+
+**Import GitHub issues:**
+Use `kb_task_browse_github_issues` to preview, then `kb_task_import_github_issue` for specific issues.
+
+**Start dashboard:**
+Use `/fn` command. `/fn stop` to stop. `/fn status` to check.
+
+**Mission planning:**
+Use `kb_mission_create` for high-level objectives, then add milestones, slices, and features.
+
+</quick_reference>
+
+<known_limitations>
+
+These operations are **not available** via pi extension tools and require the dashboard or CLI:
+
+- **Moving tasks between columns** — No tool for column moves (handled by the AI engine)
+- **Workflow steps** — Creating/managing workflow step definitions requires the dashboard
+- **Settings** — Changing settings requires the dashboard or `fn settings set` CLI command
+- **Steering comments** — Adding steering comments to guide task execution requires CLI (`fn task steer`)
+- **Merge operations** — Merging completed tasks requires CLI (`fn task merge`) or auto-merge
+
+For these operations, guide the user to the dashboard (`/fn`) or CLI commands documented in workflows/dashboard-cli.md.
+
+</known_limitations>
+
+<reference_index>
+
+| Reference | When to Use |
+|-----------|-------------|
+| references/cli-commands.md | Full CLI command reference |
+| references/task-structure.md | Task file structure and storage |
+| references/extension-tools.md | All pi extension tools with parameters |
+| references/best-practices.md | Tips for effective Fusion usage |
+| references/fusion-capabilities.md | Complete feature catalog |
+| references/skill-patterns.md | Patterns used in this skill's design |
+
+</reference_index>
--- a/packages/cli/skill/fusion/references/best-practices.md
+++ b/packages/cli/skill/fusion/references/best-practices.md
@@ -0,0 +1,91 @@
+# Best Practices for Working with Fusion
+
+## Writing Task Descriptions
+
+**Do:**
+- State the problem AND desired outcome
+- Include specific file paths, technologies, or patterns to use
+- Mention what's out of scope to prevent scope creep
+- Reference related tasks by ID if there are dependencies
+- Include "current behavior" vs "expected behavior" for bugs
+
+**Don't:**
+- Write one-liner descriptions like "fix the bug"
+- Include implementation details the AI should figure out
+- Create tasks that are too large (break into smaller tasks or use missions)
+- Duplicate existing tasks — check `kb_task_list` first
+
+## Task Size Guidelines
+
+| Size | Scope | Examples |
+|------|-------|---------|
+| S | Single file change, simple fix | Fix typo, update config, add CSS rule |
+| M | 2-5 files, moderate complexity | Add form validation, create API endpoint |
+| L | 5+ files, significant feature | New page/component, refactor module, add auth |
+
+For work larger than L, use missions to break it into phases.
+
+## When to Use Each Tool
+
+| Scenario | Tool |
+|----------|------|
+| Quick task with clear scope | `kb_task_create` |
+| Vague idea needing refinement | `kb_task_plan` |
+| Large project with phases | `kb_mission_create` + hierarchy |
+| Task failed, needs retry | `kb_task_retry` |
+| Task needs manual intervention | `kb_task_pause` |
+| Completed task needs follow-up | `kb_task_refine` |
+| Clean up done tasks | `kb_task_archive` |
+| Import external work | `kb_task_import_github*` |
+
+## Dependency Management
+
+- Declare dependencies at creation time using the `depends` parameter
+- Dependencies must be valid task IDs that exist
+- Tasks wait in todo until all dependencies are in done or archived
+- Circular dependencies are rejected
+- Use missions for complex dependency graphs across many tasks
+
+## Working with the AI Engine
+
+- **Don't fight the automation** — let triage, scheduler, and executor do their jobs
+- **Pause if needed** — use `kb_task_pause` when you want manual control
+- **Steer don't micromanage** — use steering comments (via CLI `fn task steer`) to guide the AI without rewriting the spec
+- **Check progress** — use `kb_task_show` to monitor step completion
+- **Let it fail and retry** — if a task fails, check the log, then `kb_task_retry`
+
+## Mission Planning Tips
+
+1. **Start with the mission** — define the high-level goal first
+2. **Milestones are phases** — order them chronologically (what comes first?)
+3. **Slices are parallel tracks** — within a milestone, what can be done independently?
+4. **Features are deliverables** — each feature should map to one task
+5. **Activate slices sequentially** — only activate what's ready for implementation
+6. **Use auto-advance** — enable on the mission to automatically progress through slices
+
+## Common Patterns
+
+**Bug fix flow:**
+1. `kb_task_create` with bug description (current vs expected behavior)
+2. Wait for triage to generate specification
+3. Monitor with `kb_task_show` until done
+
+**Feature development flow:**
+1. `kb_task_plan` to refine requirements
+2. Check the task in triage → todo → in-progress
+3. Review in `kb_task_show` when in-review
+4. Task auto-merges to main
+
+**Large project flow:**
+1. `kb_mission_create` with project overview
+2. Add milestones for each phase
+3. Add slices and features for the first milestone
+4. Activate first slice, create and link tasks
+5. As tasks complete, features auto-complete
+6. Activate next slice (or use auto-advance)
+
+**GitHub issue triage flow:**
+1. `kb_task_browse_github_issues` to see what's open
+2. `kb_task_import_github_issue` for high-priority issues
+3. Tasks enter triage and get AI-specified
+4. Monitor board as AI works through them
--- a/packages/cli/skill/fusion/references/cli-commands.md
+++ b/packages/cli/skill/fusion/references/cli-commands.md
@@ -0,0 +1,117 @@
+# Fusion CLI Commands Reference
+
+The Fusion CLI is invoked with `fn` (short for fusion).
+
+## Dashboard
+
+```bash
+fn dashboard                              # Start web UI + AI engine (port 4040)
+fn dashboard --port 8080                  # Custom port
+fn dashboard --interactive                # Interactive port selection
+fn dashboard --paused                     # Start with automation paused
+fn dashboard --dev                        # Web UI only (no AI engine)
+```
+
+## Task Management
+
+```bash
+fn task create "description"              # Create task → triage
+fn task create "desc" --attach file.png   # Create with attachment
+fn task create "desc" --depends KB-001    # Create with dependency
+fn task plan "description"                # AI-guided planning mode
+fn task list                              # List all tasks by column
+fn task show KB-001                       # Show task details + steps + log
+fn task move KB-001 todo                  # Move task to column
+fn task merge KB-001                      # Merge in-review task to main
+fn task duplicate KB-001                  # Copy task to triage
+fn task refine KB-001 --feedback "..."    # Create follow-up task
+fn task archive KB-001                    # Move done → archived
+fn task unarchive KB-001                  # Move archived → done
+fn task delete KB-001 [--force]           # Permanently delete
+fn task retry KB-001                      # Retry failed task → todo
+fn task comment KB-001 "text"             # Add general comment
+fn task comments KB-001                   # List task comments
+fn task steer KB-001 "guidance"           # Add steering comment for AI
+fn task pause KB-001                      # Pause automation
+fn task unpause KB-001                    # Resume automation
+fn task logs KB-001                       # View agent execution logs
+fn task logs KB-001 --follow              # Stream logs in real-time
+fn task logs KB-001 --limit 50            # Limit log lines
+fn task logs KB-001 --type tool           # Filter by log type
+```
+
+## Mission Management
+
+```bash
+fn mission create "Title" "Description"   # Create a new mission
+fn mission list                            # List all missions
+fn mission show M-001                      # Show mission hierarchy
+fn mission delete M-001 [--force]          # Delete mission (cascades)
+fn mission activate-slice SL-001           # Manually activate a slice
+```
+
+## GitHub Integration
+
+```bash
+fn task import owner/repo                  # Import all open issues
+fn task import owner/repo --interactive    # Select issues interactively
+fn task import owner/repo --limit 10       # Limit import count
+fn task import owner/repo --labels bug     # Filter by labels
+fn task pr-create KB-001                   # Create GitHub PR
+fn task pr-create KB-001 --title "Fix"     # PR with custom title
+fn task pr-create KB-001 --base main       # PR targeting specific base
+```
+
+## Git Operations
+
+```bash
+fn git status                              # Branch, commit, dirty state
+fn git fetch [remote]                      # Fetch from remote
+fn git pull [--yes]                        # Pull current branch
+fn git push [--yes]                        # Push current branch
+```
+
+## Settings
+
+```bash
+fn settings                                # Show all settings
+fn settings set maxConcurrent 4            # Update a setting
+fn settings set autoMerge false            # Disable auto-merge
+fn settings set prCompletionMode pr-first  # Use PR workflow
+```
+
+## Backups
+
+```bash
+fn backup --create                         # Create backup now
+fn backup --list                           # List backups with sizes
+fn backup --restore <file>                 # Restore from backup
+fn backup --cleanup                        # Remove old backups
+```
+
+## Multi-Project
+
+```bash
+fn project list                            # List registered projects
+fn project add my-app /path/to/app         # Register project
+fn project remove my-app [--force]         # Unregister project
+fn project show my-app                     # Show project details
+fn project set-default my-app              # Set default project
+fn project detect                          # Detect current project
+
+# Use --project flag with any command
+fn task list --project my-app
+fn task create "desc" --project api
+fn settings --project my-app
+```
+
+## Columns (valid values for `fn task move`)
+
+| Column | Description |
+|--------|-------------|
+| `triage` | Awaiting specification |
+| `todo` | Specified, waiting for execution |
+| `in-progress` | Being executed by AI |
+| `in-review` | Ready for merge |
+| `done` | Merged to main |
+| `archived` | Removed from active view |
--- a/packages/cli/skill/fusion/references/extension-tools.md
+++ b/packages/cli/skill/fusion/references/extension-tools.md
@@ -0,0 +1,260 @@
+# Fusion Pi Extension Tools
+
+All tools are registered via the pi extension. They are available in any pi agent session when the Fusion extension is installed.
+
+## Task Tools
+
+### kb_task_create
+
+Create a new task on the Fusion board. Enters triage for AI specification.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `description` | string | ✓ | What needs to be done — be descriptive |
+| `depends` | string[] | — | Task IDs this depends on (e.g., ["KB-001"]) |
+
+Returns: task ID, column, dependencies, path
+
+### kb_task_update
+
+Update fields on an existing task (title, description, dependencies).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Task ID (e.g., KB-001) |
+| `title` | string | — | New task title |
+| `description` | string | — | New task description |
+| `depends` | string[] | — | New dependency list — replaces existing |
+
+Returns: task ID, list of updated fields
+
+### kb_task_list
+
+List all tasks grouped by column.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `column` | string | — | Filter to specific column |
+| `limit` | number | — | Max tasks per column (default: 10) |
+
+Returns: formatted task list grouped by column
+
+### kb_task_show
+
+Show full task details including steps, progress, prompt preview, and log.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Task ID (e.g., KB-001) |
+
+Returns: task details with steps, prompt preview (500 chars), last 5 log entries
+
+### kb_task_attach
+
+Attach a file to a task. Copies file to task's attachments directory.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Task ID |
+| `path` | string | ✓ | Path to file to attach |
+
+Supported formats: png, jpg, jpeg, gif, webp, txt, log, json, yaml, yml, toml, csv, xml
+
+### kb_task_pause
+
+Pause automation for a task. Scheduler and executor will skip this task.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Task ID |
+
+### kb_task_unpause
+
+Resume automation for a paused task.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Task ID |
+
+### kb_task_retry
+
+Retry a failed task. Clears error state, moves to todo for re-execution.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Task ID (must be in failed state) |
+
+### kb_task_duplicate
+
+Duplicate a task. Creates a fresh copy in triage with same title and description.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Source task ID to duplicate |
+
+### kb_task_refine
+
+Create a follow-up task for a completed task. New task depends on the original.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Task ID (must be done or in-review) |
+| `feedback` | string | ✓ | What needs to be refined (1-2000 chars) |
+
+### kb_task_archive
+
+Archive a done task. Moves from done → archived.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Task ID (must be in done column) |
+
+### kb_task_unarchive
+
+Restore an archived task. Moves from archived → done.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Task ID (must be in archived column) |
+
+### kb_task_delete
+
+Permanently delete a task. Cannot be undone.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Task ID |
+
+### kb_task_plan
+
+Create a task via AI-guided planning mode. Non-interactive when called from extension.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `description` | string | — | Initial plan description |
+
+## GitHub Tools
+
+### kb_task_import_github
+
+Batch import GitHub issues as Fusion tasks.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `ownerRepo` | string | ✓ | Repository (e.g., "owner/repo") |
+| `limit` | number | — | Max issues (default: 30, max: 100) |
+| `labels` | string[] | — | Label names to filter by |
+
+### kb_task_import_github_issue
+
+Import a single GitHub issue by number.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `owner` | string | ✓ | Repository owner |
+| `repo` | string | ✓ | Repository name |
+| `issueNumber` | number | ✓ | GitHub issue number |
+
+### kb_task_browse_github_issues
+
+Browse open issues from a repository before importing.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `owner` | string | ✓ | Repository owner |
+| `repo` | string | ✓ | Repository name |
+| `limit` | number | — | Max issues (default: 30, max: 100) |
+| `labels` | string[] | — | Label names to filter by |
+
+## Mission Tools
+
+### kb_mission_create
+
+Create a new mission — a high-level objective spanning multiple milestones.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `title` | string | ✓ | Mission title |
+| `description` | string | — | Detailed objectives and context |
+| `autoAdvance` | boolean | — | Auto-activate next slice on completion |
+
+### kb_mission_list
+
+List all missions with current status. No parameters.
+
+### kb_mission_show
+
+Show mission details with full hierarchy.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Mission ID (e.g., M-001) |
+
+### kb_mission_delete
+
+Delete a mission and all children. Tasks are NOT deleted.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Mission ID |
+
+### kb_milestone_add
+
+Add a milestone to a mission.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `missionId` | string | ✓ | Parent mission ID |
+| `title` | string | ✓ | Milestone title |
+| `description` | string | — | Milestone description |
+
+### kb_slice_add
+
+Add a slice to a milestone.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `milestoneId` | string | ✓ | Parent milestone ID |
+| `title` | string | ✓ | Slice title |
+| `description` | string | — | Slice description |
+
+### kb_feature_add
+
+Add a feature to a slice.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `sliceId` | string | ✓ | Parent slice ID |
+| `title` | string | ✓ | Feature title |
+| `description` | string | — | Feature description |
+| `acceptanceCriteria` | string | — | Acceptance criteria |
+
+### kb_slice_activate
+
+Activate a pending slice for implementation.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `id` | string | ✓ | Slice ID (must be pending) |
+
+### kb_feature_link_task
+
+Link a feature to a kb task. Updates feature status to triaged.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `featureId` | string | ✓ | Feature ID (e.g., F-001) |
+| `taskId` | string | ✓ | Task ID (e.g., KB-001) |
+
+## Dashboard Command
+
+### /fn
+
+Start or stop the Fusion dashboard from within a pi session.
+
+| Command | Description |
+|---------|-------------|
+| `/fn` | Start dashboard on port 4040 |
+| `/fn 8080` | Start on custom port |
+| `/fn stop` | Stop dashboard |
+| `/fn status` | Check if running |
--- a/packages/cli/skill/fusion/references/fusion-capabilities.md
+++ b/packages/cli/skill/fusion/references/fusion-capabilities.md
@@ -0,0 +1,116 @@
+# Fusion Capabilities Catalog
+
+## Overview
+
+Fusion (kb) is an AI-orchestrated task board. Tasks flow through columns:
+Triage → Todo → In Progress → In Review → Done → Archived
+
+## Pi Extension Tools (Available to Agents)
+
+| Tool | Purpose |
+|------|---------|
+| `kb_task_create` | Create a new task in triage |
+| `kb_task_update` | Update task title, description, or dependencies |
+| `kb_task_list` | List all tasks grouped by column |
+| `kb_task_show` | Show full task details, steps, log |
+| `kb_task_attach` | Attach a file to a task |
+| `kb_task_pause` | Pause automation for a task |
+| `kb_task_unpause` | Resume automation for a task |
+| `kb_task_retry` | Retry a failed task (clears error, moves to todo) |
+| `kb_task_duplicate` | Duplicate a task (copy to triage) |
+| `kb_task_refine` | Create refinement task for follow-up work |
+| `kb_task_archive` | Archive a done task |
+| `kb_task_unarchive` | Restore an archived task |
+| `kb_task_delete` | Permanently delete a task |
+| `kb_task_import_github` | Batch import GitHub issues as tasks |
+| `kb_task_import_github_issue` | Import a single GitHub issue |
+| `kb_task_browse_github_issues` | Browse GitHub issues before importing |
+| `kb_task_plan` | Create task via AI-guided planning mode |
+| `kb_mission_create` | Create a new mission |
+| `kb_mission_list` | List all missions |
+| `kb_mission_show` | Show mission hierarchy |
+| `kb_mission_delete` | Delete a mission |
+| `kb_milestone_add` | Add a milestone to a mission |
+| `kb_slice_add` | Add a slice to a milestone |
+| `kb_feature_add` | Add a feature to a slice |
+| `kb_slice_activate` | Activate a pending slice |
+| `kb_feature_link_task` | Link a feature to a task |
+
+## CLI Commands (fn)
+
+### Dashboard
+- `fn dashboard` — Start web UI + AI engine
+- `fn dashboard --paused` — Start with automation paused
+- `fn dashboard --dev` — Start web UI only (no AI engine)
+
+### Task Management
+- `fn task create "description"` — Create a new task
+- `fn task plan "description"` — AI-guided planning mode
+- `fn task list` — List all tasks
+- `fn task show KB-001` — Show task details
+- `fn task move KB-001 todo` — Move task to a column
+- `fn task merge KB-001` — Merge an in-review task
+- `fn task duplicate KB-001` — Duplicate a task
+- `fn task refine KB-001 --feedback "..."` — Create refinement task
+- `fn task archive/unarchive KB-001` — Archive/restore tasks
+- `fn task delete KB-001` — Delete a task
+- `fn task retry KB-001` — Retry a failed task
+- `fn task comment KB-001 "..."` — Add a task comment
+- `fn task steer KB-001 "..."` — Add steering comment
+- `fn task pause/unpause KB-001` — Control automation
+- `fn task logs KB-001` — View task agent logs
+
+### GitHub Integration
+- `fn task import owner/repo` — Batch import issues
+- `fn task import owner/repo -i` — Interactive import
+- `fn task pr-create KB-001` — Create PR for task
+
+### Git Commands
+- `fn git status/fetch/pull/push` — Git operations
+
+### Settings
+- `fn settings` — Show current settings
+- `fn settings set key value` — Update a setting
+
+## AI Engine Components
+
+1. **TriageProcessor** — Auto-specifications for tasks in triage column
+2. **Scheduler** — Dependency resolution, concurrency management
+3. **TaskExecutor** — Creates worktrees, executes tasks with coding tools
+
+## Task Storage Structure
+
+```
+.kb/
+├── kb.db                    # SQLite database (WAL mode)
+├── config.json              # Board config
+└── tasks/
+    └── KB-001/
+        ├── PROMPT.md        # Task specification
+        ├── agent.log        # Execution logs
+        └── attachments/     # File attachments
+```
+
+## Dashboard Features
+
+- Real-time kanban board with drag-and-drop
+- Board view and list view
+- Task detail modal with tabs (Details, Spec, Model, Workflow, Comments)
+- Git manager (commits, branches, worktrees)
+- Activity log
+- Settings modal
+- Workflow step manager
+- Scheduled tasks (automations)
+- GitHub import modal
+- Theme system (8+ themes, dark/light/system)
+
+## Key Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `maxConcurrent` | 2 | Concurrent task execution |
+| `autoMerge` | true | Auto-merge completed tasks |
+| `requirePlanApproval` | false | Manual approval for specs |
+| `prCompletionMode` | direct | Completion: direct/pr-first |
+| `taskStuckTimeoutMs` | — | Stuck task detection timeout |
+| `recycleWorktrees` | false | Pool and reuse worktrees |
--- a/packages/cli/skill/fusion/references/skill-patterns.md
+++ b/packages/cli/skill/fusion/references/skill-patterns.md
@@ -0,0 +1,38 @@
+# Skill Patterns Analysis
+
+## Patterns Observed from High-Quality Skills
+
+### 1. Router Pattern (create-skill)
+
+- SKILL.md acts as a router with `<routing>` section
+- Maps user intent to specific workflow files
+- Essential principles are inline in SKILL.md (always loaded)
+- Workflows have `<required_reading>`, `<process>`, `<success_criteria>`
+- References contain reusable domain knowledge
+
+### 2. Command Reference Pattern (agent-browser)
+
+- Core workflow presented upfront (navigate → snapshot → interact → re-snapshot)
+- Essential commands with examples inline
+- Common patterns section for frequent use cases
+- Deep-dive references linked at the bottom via table
+- Templates for ready-to-use scripts
+- Uses `allowed-tools` for Bash commands
+
+### 3. Search & Discover Pattern (find-skills)
+
+- Simple single-file skill (no router needed)
+- Clear "When to Use" triggers section
+- Step-by-step guidance for common flow
+- Fallback guidance when primary path fails
+- Tips section for optimization
+
+## Key Takeaways for Fusion Skill
+
+1. **Use router pattern** — Fusion has multiple distinct workflows (task management, lifecycle, specs, dashboard/CLI)
+2. **No `allowed-tools` needed** — Fusion tools are registered via pi extension, not Bash CLI
+3. **Inline essential concepts** — Task columns, workflow overview in SKILL.md
+4. **Progressive disclosure** — SKILL.md routes to workflows, workflows reference detailed docs
+5. **Pure XML structure** — No markdown headings (#, ##, ###) in body
+6. **Triggers section** — Clear when-to-use criteria
+7. **Under 500 lines** — Keep SKILL.md concise, split to workflows/references
--- a/packages/cli/skill/fusion/references/task-structure.md
+++ b/packages/cli/skill/fusion/references/task-structure.md
@@ -0,0 +1,153 @@
+# Fusion Task Storage Structure
+
+## Database Architecture
+
+Fusion uses a hybrid storage architecture: structured metadata in SQLite, large blobs on the filesystem.
+
+**Project database:** `.fusion/fusion.db` (SQLite with WAL mode)
+
+**Filesystem blobs:**
+```
+.fusion/
+├── fusion.db                # SQLite database (WAL mode)
+├── config.json              # Board config + workflow steps
+└── tasks/
+    └── KB-001/
+        ├── PROMPT.md        # Task specification (generated by triage AI)
+        ├── agent.log        # Execution logs from the AI agent
+        └── attachments/     # File attachments
+            ├── screenshot.png
+            └── data.json
+```
+
+## Task Metadata (in SQLite)
+
+Key fields stored in the `tasks` table:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | string | Task ID (e.g., KB-001) |
+| `title` | string? | Short title (optional, can be auto-generated) |
+| `description` | string | Full task description |
+| `column` | string | Current column: triage/todo/in-progress/in-review/done/archived |
+| `status` | string? | Sub-status: failed, paused, awaiting-approval |
+| `size` | string? | Size estimate: S, M, L |
+| `reviewLevel` | number? | Review intensity: 0-3 |
+| `currentStep` | number | Index of current execution step |
+| `steps` | JSON | Array of step objects with name, status |
+| `dependencies` | JSON | Array of task IDs this depends on |
+| `log` | JSON | Array of log entries (action, outcome, timestamp) |
+| `attachments` | JSON | Array of attachment metadata |
+| `prInfo` | JSON? | GitHub PR info (number, url, state) |
+| `issueInfo` | JSON? | GitHub issue info (number, url) |
+| `modelProvider` | string? | Per-task executor model provider |
+| `modelId` | string? | Per-task executor model ID |
+| `validatorModelProvider` | string? | Per-task reviewer model provider |
+| `validatorModelId` | string? | Per-task reviewer model ID |
+| `enabledWorkflowSteps` | JSON | Array of workflow step IDs to run |
+| `missionId` | string? | Linked mission ID |
+| `sliceId` | string? | Linked slice ID |
+| `paused` | boolean | Whether automation is paused |
+| `createdAt` | string | ISO timestamp |
+| `updatedAt` | string | ISO timestamp |
+
+## PROMPT.md Specification Format
+
+The AI triage agent generates this file with the following structure:
+
+```markdown
+# Task: KB-001 — Task Title
+
+**Created:** 2026-03-31
+**Size:** M
+
+## Review Level: 2 (Plan and Code)
+
+## Mission
+
+What the task should accomplish.
+
+## Dependencies
+
+- KB-040 — Prerequisite task description
+
+## Context to Read First
+
+- `path/to/relevant/file.ts` — Why to read this file
+
+## File Scope
+
+- `src/components/LoginForm.tsx` (modified)
+- `src/utils/validation.ts` (new)
+- `tests/LoginForm.test.ts` (new)
+
+## Steps
+
+### Step 1: Research existing patterns
+- [ ] Look at existing validation in SignupForm
+- [ ] Identify the validation utility pattern
+
+### Step 2: Implement email validation
+- [ ] Add validation function
+- [ ] Wire up to form submit
+
+## Acceptance Criteria
+
+- [ ] Email validation shows inline error
+- [ ] Existing tests pass
+- [ ] New validation has test coverage
+
+## Do NOT
+
+- Modify the API endpoints
+- Change the form layout
+
+## Testing Requirements
+
+1. Unit tests for email validation function
+2. Integration test for form submission with invalid email
+```
+
+## Config File
+
+`.fusion/config.json` stores board settings and workflow step definitions:
+
+```json
+{
+  "nextId": 42,
+  "settings": {
+    "maxConcurrent": 2,
+    "autoMerge": true,
+    "prCompletionMode": "direct"
+  },
+  "workflowSteps": [
+    {
+      "id": "WS-001",
+      "name": "Documentation Review",
+      "prompt": "Review the task changes...",
+      "enabled": true
+    }
+  ]
+}
+```
+
+## Global Settings
+
+User-level settings at `~/.pi/fusion/settings.json`:
+
+```json
+{
+  "themeMode": "dark",
+  "colorTheme": "default",
+  "defaultProvider": "anthropic",
+  "defaultModelId": "claude-sonnet-4-5",
+  "ntfyEnabled": false
+}
+```
+
+## Central Database (Multi-Project)
+
+For multi-project setups: `~/.pi/fusion/fusion-central.db`
+- Project registry
+- Unified activity feed
+- Global concurrency management
--- a/packages/cli/skill/fusion/workflows/dashboard-cli.md
+++ b/packages/cli/skill/fusion/workflows/dashboard-cli.md
@@ -0,0 +1,92 @@
+<required_reading>
+- references/cli-commands.md — Full CLI command reference
+</required_reading>
+
+<objective>
+Guide the agent through using the Fusion dashboard and CLI for operations not available via pi extension tools.
+</objective>
+
+<process>
+
+**Starting the dashboard:**
+
+Use the `/fn` command (registered by the pi extension):
+- `/fn` or `/fn 4040` — Start dashboard + AI engine on specified port (default 4040)
+- `/fn stop` — Stop the dashboard
+- `/fn status` — Check if dashboard is running
+
+The dashboard provides:
+- Real-time kanban board with drag-and-drop
+- Task detail modal with tabs: Details, Spec, Model, Workflow, Comments
+- Git manager (commits, branches, worktrees)
+- Activity log
+- Settings configuration
+- Workflow step manager
+- Mission hierarchy view (Cmd/Ctrl+Shift+M)
+- GitHub import modal
+- Theme system (8+ themes, dark/light/system)
+
+**Operations that require CLI or dashboard:**
+
+These cannot be done with pi extension tools:
+
+| Operation | CLI Command | Dashboard |
+|-----------|-------------|-----------|
+| Move task to column | `fn task move KB-001 todo` | Drag card between columns |
+| Merge completed task | `fn task merge KB-001` | Click merge in task detail |
+| Add steering comment | `fn task steer KB-001 "Use TypeScript"` | Comments tab in task detail |
+| Add general comment | `fn task comment KB-001 "Looks good"` | Comments tab in task detail |
+| View agent logs | `fn task logs KB-001 --follow` | Agent log tab in task detail |
+| Change settings | `fn settings set maxConcurrent 4` | Settings modal |
+| Create workflow steps | — | Workflow Steps button in header |
+| Git operations | `fn git status/fetch/pull/push` | Git manager panel |
+
+**Settings overview:**
+
+Key settings (configure via dashboard Settings or `fn settings set`):
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `maxConcurrent` | 2 | Concurrent task execution slots |
+| `autoMerge` | true | Auto-merge completed tasks to main |
+| `requirePlanApproval` | false | Manual approval for AI specifications |
+| `prCompletionMode` | "direct" | How tasks complete: "direct" (squash merge) or "pr-first" (GitHub PR) |
+| `recycleWorktrees` | false | Pool and reuse git worktrees |
+| `taskStuckTimeoutMs` | — | Timeout for detecting stuck tasks (ms) |
+| `autoBackupEnabled` | false | Automatic database backups |
+| `ntfyEnabled` | false | Push notifications via ntfy.sh |
+
+**Working with GitHub PRs:**
+
+When `prCompletionMode` is set to "pr-first":
+- Completed tasks create a GitHub PR instead of direct-merging
+- Use `fn task pr-create KB-001` to manually create a PR for any in-review task
+- PRs can be reviewed and merged through the normal GitHub workflow
+
+**Backup operations:**
+
+```bash
+fn backup --create         # Create a backup now
+fn backup --list           # List all backups
+fn backup --restore <file> # Restore from backup
+fn backup --cleanup        # Remove old backups
+```
+
+**Multi-project support:**
+
+If managing multiple projects, use `--project` flag:
+```bash
+fn task list --project my-app
+fn task create "Fix bug" --project api-service
+fn project list              # List all registered projects
+fn project add my-app /path  # Register a project
+fn project set-default main  # Set default project
+```
+
+</process>
+
+<success_criteria>
+- Agent knows when to direct user to dashboard vs. CLI
+- Settings are configured appropriately for the project's needs
+- Dashboard is accessible and running when needed
+</success_criteria>
--- a/packages/cli/skill/fusion/workflows/specifications.md
+++ b/packages/cli/skill/fusion/workflows/specifications.md
@@ -0,0 +1,124 @@
+<required_reading>
+- references/task-structure.md — PROMPT.md format and file structure
+- references/best-practices.md — Tips for writing effective specifications
+</required_reading>
+
+<objective>
+Guide the agent through creating well-specified tasks and organizing work using the mission hierarchy for complex multi-phase projects.
+</objective>
+
+<process>
+
+**Writing effective task descriptions:**
+
+The AI triage agent uses your description to write a PROMPT.md specification. Better descriptions produce better specs:
+
+1. **State the problem** — What's broken, missing, or needed?
+2. **Describe the outcome** — What should the result look like?
+3. **Add constraints** — Specific technologies, patterns, or files to use
+4. **Mention scope** — What's in scope and what's explicitly not
+
+Good example:
+```
+"The settings page loads all user preferences in a single API call, causing 3s delays.
+Split into lazy-loaded sections that fetch only when the tab is opened.
+Use React Suspense for loading states. Only affect the settings page — don't
+change the API endpoints themselves."
+```
+
+Bad example:
+```
+"Settings page is slow, fix it"
+```
+
+**Understanding the PROMPT.md specification:**
+
+After triage, each task gets a PROMPT.md at `.fusion/tasks/{ID}/PROMPT.md` containing:
+
+- **Mission** — What the task should accomplish
+- **Steps** — Ordered implementation steps with checkboxes
+- **File Scope** — Which files can be modified
+- **Acceptance Criteria** — How to verify the task is complete
+- **Review Level** — How much review is needed (0-3)
+- **Do NOT** — Explicit constraints and boundaries
+- **Testing Requirements** — What tests to write/run
+- **Dependencies** — Other tasks that must complete first
+
+The executor agent follows this specification step by step.
+
+**Using AI-guided planning:**
+
+For complex or vague ideas, use `kb_task_plan`:
+```
+kb_task_plan({ description: "Build a notification system for the app" })
+```
+
+The planning mode will:
+1. Ask clarifying questions about scope, channels (email, push, in-app), users
+2. Identify technical constraints and dependencies
+3. Suggest breaking the work into multiple tasks if needed
+4. Create a well-specified task (or multiple subtasks)
+
+**Organizing with Missions:**
+
+For large-scale projects spanning multiple tasks, use the mission hierarchy:
+
+1. **Create a mission** — The high-level objective
+   ```
+   kb_mission_create({ title: "Build Authentication System", description: "Complete auth with login, signup, password reset, and OAuth" })
+   ```
+
+2. **Add milestones** — Major phases
+   ```
+   kb_milestone_add({ missionId: "M-001", title: "Database Schema" })
+   kb_milestone_add({ missionId: "M-001", title: "API Endpoints" })
+   kb_milestone_add({ missionId: "M-001", title: "UI Integration" })
+   ```
+
+3. **Add slices** — Parallel work units within milestones
+   ```
+   kb_slice_add({ milestoneId: "MS-001", title: "User Tables" })
+   kb_slice_add({ milestoneId: "MS-001", title: "Token Storage" })
+   ```
+
+4. **Add features** — Individual deliverables
+   ```
+   kb_feature_add({ sliceId: "SL-001", title: "User model", description: "Create user table with email, password hash, timestamps" })
+   kb_feature_add({ sliceId: "SL-001", title: "Session table", description: "Create session table with token, expiry, user FK" })
+   ```
+
+5. **Activate a slice** — Enable it for implementation
+   ```
+   kb_slice_activate({ id: "SL-001" })
+   ```
+
+6. **Link features to tasks** — Connect features to kb tasks
+   ```
+   kb_task_create({ description: "Create user model with email, password hash, and timestamps" })
+   # → Created KB-101
+   kb_feature_link_task({ featureId: "F-001", taskId: "KB-101" })
+   ```
+
+**Mission status flows automatically:**
+- When linked tasks complete → feature status updates to done
+- When all features in a slice are done → slice completes
+- When all slices in a milestone are done → milestone completes
+- When all milestones are done → mission completes
+
+**Auto-advance:** Enable `autoAdvance` on a mission to automatically activate the next pending slice when the current one completes.
+
+**Viewing mission progress:**
+```
+kb_mission_show({ id: "M-001" })
+```
+Shows the full hierarchy with status icons:
+- `●` active, `○` pending, `✓` complete, `⚠` blocked
+
+</process>
+
+<success_criteria>
+- Task descriptions are specific enough for the AI to generate a useful specification
+- Complex work is broken down using missions when it spans 5+ tasks
+- Mission hierarchy follows the correct nesting: Mission → Milestone → Slice → Feature → Task
+- Features are linked to tasks after slice activation
+</success_criteria>
--- a/packages/cli/skill/fusion/workflows/task-lifecycle.md
+++ b/packages/cli/skill/fusion/workflows/task-lifecycle.md
@@ -0,0 +1,116 @@
+<required_reading>
+- references/task-structure.md — File structure and storage details
+</required_reading>
+
+<objective>
+Help the agent understand how tasks flow through the Fusion board, what happens at each stage, and how to interpret task state.
+</objective>
+
+<process>
+
+**Column flow:**
+
+```
+Triage → Todo → In Progress → In Review → Done → Archived
+```
+
+Each column transition is driven by the AI engine or user action:
+
+**Triage (specification)**
+- Task enters triage when created via `kb_task_create`
+- The **TriageProcessor** reads the project context and writes a full PROMPT.md specification
+- Specification includes: steps, file scope, acceptance criteria, review level, size estimate
+- If `requirePlanApproval` is enabled, task stays in triage as "awaiting-approval" until manually approved
+- After specification (and approval if required), task moves to **todo**
+
+**Todo (scheduling)**
+- The **Scheduler** watches the todo column
+- Resolves dependency graphs — tasks with unmet deps wait
+- Respects concurrency limits (default: 2 concurrent tasks)
+- When deps are satisfied and a slot is available, moves task to **in-progress**
+
+**In Progress (execution)**
+- The **TaskExecutor** creates a git worktree for isolation
+- Spawns a pi agent session with coding tools scoped to the worktree
+- For each step in the PROMPT.md:
+  1. Plan the implementation
+  2. Review the plan (if review level requires it)
+  3. Execute the plan
+  4. Review the code (if review level requires it)
+- If workflow steps are enabled, they run sequentially after all main steps
+- On completion, task moves to **in-review**
+
+**In Review (merge)**
+- Task work is complete and ready for merge
+- Depending on settings:
+  - `prCompletionMode: "direct"` — Auto squash-merge to main (default)
+  - `prCompletionMode: "pr-first"` — Creates a GitHub PR for manual review
+- After merge, task moves to **done**
+
+**Done**
+- Work is merged to main branch
+- Task is available for archival via `kb_task_archive`
+- Can be refined with `kb_task_refine` to create follow-up work
+
+**Archived**
+- Removed from active board view
+- Can be restored with `kb_task_unarchive`
+- Can be cleaned up to free disk space (removes task directory, keeps metadata)
+
+**Task statuses (within any column):**
+
+| Status | Meaning |
+|--------|---------|
+| (none) | Normal state |
+| `paused` | Automation suspended — scheduler/executor skip this task |
+| `failed` | Execution error — use `kb_task_retry` to reset |
+| `awaiting-approval` | Spec complete, waiting for manual approval (triage only) |
+
+**Review levels:**
+
+| Level | Description |
+|-------|-------------|
+| 0 | No reviews |
+| 1 | Plan review only |
+| 2 | Plan + code review |
+| 3 | Full review (plan + code + tests) |
+
+The AI triage agent sets the review level based on task complexity and risk assessment.
+
+**Dependencies:**
+
+- Tasks can depend on other tasks (by task ID)
+- Dependent tasks wait in todo until all dependencies are in **done** or **archived**
+- Circular dependencies are prevented
+- Use `depends` parameter on `kb_task_create` to declare dependencies
+
+**Interpreting `kb_task_show` output:**
+
+```
+KB-042: Fix login validation
+Column: In Progress · Size: M · Review: 2
+
+Steps (2/5):
+  [✓] 0: Research existing patterns
+  [✓] 1: Add email validation
+  [▸] 2: Add error display component  ◀  (current step)
+  [ ] 3: Write tests
+  [ ] 4: Update documentation
+
+Log (last 3):
+  14:30  Step 1 completed → Code review passed
+  14:32  Step 2 started
+  14:35  Plan approved for step 2
+```
+
+- `[✓]` = done, `[▸]` = in progress, `[–]` = skipped, `[ ]` = pending
+- `◀` marks the current step
+- Log shows recent activity with timestamps
+
+</process>
+
+<success_criteria>
+- Agent understands which column a task is in and why
+- Agent can interpret task status, steps, and progress
+- Agent knows when to intervene (pause, retry, refine) vs. let automation handle it
+</success_criteria>
--- a/packages/cli/skill/fusion/workflows/task-management.md
+++ b/packages/cli/skill/fusion/workflows/task-management.md
@@ -0,0 +1,90 @@
+<required_reading>
+- references/extension-tools.md — Full tool parameters and return values
+- references/best-practices.md — Tips for writing good task descriptions
+</required_reading>
+
+<objective>
+Guide the agent through creating, viewing, and managing tasks on the Fusion board using pi extension tools.
+</objective>
+
+<process>
+
+**Creating a task:**
+
+1. Use `kb_task_create` with a clear, descriptive message
+   - Include the problem AND the desired outcome
+   - Be specific — the AI triage agent uses your description to write the specification
+   - Optionally add dependencies with the `depends` parameter
+
+2. The task enters **triage** where the AI auto-generates a PROMPT.md with:
+   - Steps, file scope, acceptance criteria
+   - Review level assessment
+   - Size estimate (S/M/L)
+
+3. After specification, the task moves to **todo** and waits for the scheduler
+
+Example:
+```
+kb_task_create({
+  description: "The login form doesn't validate email format before submission. Add client-side email validation that shows an inline error message when the email is invalid. Use the existing form validation pattern from the signup form.",
+  depends: ["KB-042"]
+})
+```
+
+**AI-guided planning for complex tasks:**
+
+Use `kb_task_plan` when the idea is vague or complex. The AI will:
+1. Ask clarifying questions about scope, constraints, and approach
+2. Help break down the work into actionable pieces
+3. Create the task with a refined description
+
+**Listing tasks:**
+
+Use `kb_task_list` to see the board:
+- No params → all tasks grouped by column
+- `column: "in-progress"` → filter to specific column
+- `limit: 5` → limit tasks shown per column
+
+**Viewing task details:**
+
+Use `kb_task_show` with the task ID:
+- Shows steps with progress indicators (✓ done, ▸ in-progress, – skipped)
+- Shows prompt preview (truncated to 500 chars)
+- Shows recent log entries (last 5)
+
+**Managing task state:**
+
+| Action | Tool | Notes |
+|--------|------|-------|
+| Pause automation | `kb_task_pause` | Stops scheduler and executor from touching the task |
+| Resume automation | `kb_task_unpause` | Re-enables automated processing |
+| Retry failed task | `kb_task_retry` | Clears error, moves back to todo |
+| Duplicate task | `kb_task_duplicate` | Creates fresh copy in triage |
+| Refine completed task | `kb_task_refine` | Creates follow-up task with dependency on original |
+| Archive done task | `kb_task_archive` | Moves from done → archived |
+| Restore archived task | `kb_task_unarchive` | Moves from archived → done |
+| Delete task | `kb_task_delete` | Permanent — cannot be undone |
+
+**Attaching files:**
+
+Use `kb_task_attach` with the task ID and file path:
+- Supports images: png, jpg, gif, webp
+- Supports text: txt, log, json, yaml, csv, xml
+- Files are copied to `.fusion/tasks/{ID}/attachments/`
+
+**Importing from GitHub:**
+
+1. Browse issues first: `kb_task_browse_github_issues({ owner: "org", repo: "repo" })`
+   - Shows issue numbers, titles, labels
+   - Marks already-imported issues with ✓
+2. Import specific issue: `kb_task_import_github_issue({ owner: "org", repo: "repo", issueNumber: 42 })`
+3. Bulk import: `kb_task_import_github({ ownerRepo: "org/repo", limit: 20 })`
+
+</process>
+
+<success_criteria>
+- Task created with clear description that enables good AI specification
+- Dependencies declared correctly (task IDs exist and are valid)
+- Task state managed appropriately (pause for manual intervention, retry for failures)
+- GitHub issues imported without duplicates
+</success_criteria>