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/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>