@runfusion/fusion 0.0.1

package/skill/fusion/references/fusion-capabilities.md

@@ -0,0 +1,121 @@
+# 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 |
+|------|---------|
+| `fn_task_create` | Create a new task in triage |
+| `fn_task_update` | Update task title, description, or dependencies |
+| `fn_task_list` | List all tasks grouped by column |
+| `fn_task_show` | Show full task details, steps, log |
+| `fn_task_attach` | Attach a file to a task |
+| `fn_task_pause` | Pause automation for a task |
+| `fn_task_unpause` | Resume automation for a task |
+| `fn_task_retry` | Retry a failed task (clears error, moves to todo) |
+| `fn_task_duplicate` | Duplicate a task (copy to triage) |
+| `fn_task_refine` | Create refinement task for follow-up work |
+| `fn_task_archive` | Archive a done task |
+| `fn_task_unarchive` | Restore an archived task |
+| `fn_task_delete` | Permanently delete a task |
+| `fn_task_import_github` | Batch import GitHub issues as tasks |
+| `fn_task_import_github_issue` | Import a single GitHub issue |
+| `fn_task_browse_github_issues` | Browse GitHub issues before importing |
+| `fn_task_plan` | Create task via AI-guided planning mode |
+| `fn_mission_create` | Create a new mission |
+| `fn_mission_list` | List all missions |
+| `fn_mission_show` | Show mission hierarchy |
+| `fn_mission_delete` | Delete a mission |
+| `fn_milestone_add` | Add a milestone to a mission |
+| `fn_slice_add` | Add a slice to a milestone |
+| `fn_feature_add` | Add a feature to a slice |
+| `fn_slice_activate` | Activate a pending slice |
+| `fn_feature_link_task` | Link a feature to a task |
+| `fn_agent_stop` | Stop (pause) a running agent |
+| `fn_agent_start` | Start (resume) a stopped agent |
+| `fn_skills_search` | Search skills.sh for agent skills |
+| `fn_skills_install` | Install a skill from skills.sh |
+
+## 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 lanes (executor + merge). Triage/specification is controlled by `maxTriageConcurrent`. |
+| `maxTriageConcurrent` | 2 | Concurrent triage/specification agents. Falls back to `maxConcurrent` when undefined. |
+| `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 |

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

package/skill/fusion/references/task-structure.md

@@ -0,0 +1,158 @@
+# 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,
+      "defaultOn": true,
+      "modelProvider": "anthropic",
+      "modelId": "claude-sonnet-4-5"
+    }
+  ]
+}
+```
+
+> **Note:** `maxConcurrent` applies to task-lane agents (triage, execution, merge) only. Utility AI workflows—planning mode, subtask breakdown, mission interviews, agent heartbeat/chat wake, and title summarization—run outside this limit on a dedicated control-plane lane.
+
+## Global Settings
+
+User-level settings at `~/.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: `~/.fusion/fusion-central.db`
+- Project registry
+- Unified activity feed
+- Global concurrency management

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

package/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 `fn_task_plan`:
+```
+fn_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
+   ```
+   fn_mission_create({ title: "Build Authentication System", description: "Complete auth with login, signup, password reset, and OAuth" })
+   ```
+
+2. **Add milestones** — Major phases
+   ```
+   fn_milestone_add({ missionId: "M-001", title: "Database Schema" })
+   fn_milestone_add({ missionId: "M-001", title: "API Endpoints" })
+   fn_milestone_add({ missionId: "M-001", title: "UI Integration" })
+   ```
+
+3. **Add slices** — Parallel work units within milestones
+   ```
+   fn_slice_add({ milestoneId: "MS-001", title: "User Tables" })
+   fn_slice_add({ milestoneId: "MS-001", title: "Token Storage" })
+   ```
+
+4. **Add features** — Individual deliverables
+   ```
+   fn_feature_add({ sliceId: "SL-001", title: "User model", description: "Create user table with email, password hash, timestamps" })
+   fn_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
+   ```
+   fn_slice_activate({ id: "SL-001" })
+   ```
+
+6. **Link features to tasks** — Connect features to kb tasks
+   ```
+   fn_task_create({ description: "Create user model with email, password hash, and timestamps" })
+   # → Created KB-101
+   fn_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:**
+```
+fn_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>

package/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 `fn_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 `fn_task_archive`
+- Can be refined with `fn_task_refine` to create follow-up work
+
+**Archived**
+- Removed from active board view
+- Can be restored with `fn_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 `fn_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 `fn_task_create` to declare dependencies
+
+**Interpreting `fn_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>