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
This commit is contained in:
gsxdsm
91
packages/cli/skill/fusion/references/best-practices.md
Normal file
91
packages/cli/skill/fusion/references/best-practices.md
Normal file
@@ -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
|
||||
117
packages/cli/skill/fusion/references/cli-commands.md
Normal file
117
packages/cli/skill/fusion/references/cli-commands.md
Normal file
@@ -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 |
|
||||
260
packages/cli/skill/fusion/references/extension-tools.md
Normal file
260
packages/cli/skill/fusion/references/extension-tools.md
Normal file
@@ -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 |
|
||||
116
packages/cli/skill/fusion/references/fusion-capabilities.md
Normal file
116
packages/cli/skill/fusion/references/fusion-capabilities.md
Normal file
@@ -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 |
|
||||
38
packages/cli/skill/fusion/references/skill-patterns.md
Normal file
38
packages/cli/skill/fusion/references/skill-patterns.md
Normal file
@@ -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
|
||||
153
packages/cli/skill/fusion/references/task-structure.md
Normal file
153
packages/cli/skill/fusion/references/task-structure.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user