fusion/packages/cli/skill/fusion/references/extension-tools.md

Fusion Extension Tools

All tools are registered via the Fusion extension. They are available in any agent session when Fusion is configured.

Naming contract: all externally exposed Fusion extension tools are fn_* (for example fn_task_create). Engine runtime sessions also inject additional fn_* tools (for example fn_review_step, fn_spawn_agent, fn_task_document_write) that are separate from this extension surface and documented in engine-tools.md.

Task Tools

fn_task_create

Create a new task on the Fusion task board. The task enters the planning column where the AI planning agent will plan it into a full prompt with steps, file scope, and acceptance criteria. Optionally pass workflow_id to select a workflow at creation time; use fn_workflow_list to discover valid IDs.

Parameter	Type	Required	Description
description	string	✓	What needs to be done — be descriptive
depends	array	—	Task IDs this depends on (e.g. ['FN-001', 'FN-002'])
agentId	string	—	Agent ID to assign this task to (e.g. 'agent-abc123')
priority	string(enum)	—	Task priority (low, normal, high, urgent)
workflow_id	string	—	Workflow ID to select for the new task (e.g. 'WF-003' or 'builtin:coding').

fn_task_update

Update fields on an existing task. Supports modifying the title, description, dependencies, assigned agent, priority, and workflow_id after task creation. Set workflow_id to a workflow ID to select it, or null to clear the workflow selection.

Parameter	Type	Required	Description
id	string	✓	Task ID (e.g. FN-001)
title	string	—	New task title
description	string	—	New task description
depends	array	—	New dependency list — replaces existing dependencies (e.g. ['FN-001', 'FN-002'])
agentId	union	—	Agent ID to assign this task to, or null to clear (e.g. 'agent-abc123')
nodeId	union	—	Node ID override for this task, or null to clear
priority	string(enum)	—	Task priority (low, normal, high, urgent)
workflow_id	union	—	Workflow ID to select for this task (e.g. 'WF-003' or 'builtin:coding'),

fn_task_list

List all tasks on the Fusion board, grouped by column.

Parameter	Type	Required	Description
column	string(enum)	—	Filter to a specific column
limit	number	—	Max tasks to show per column (default: 10)

fn_task_show

Show full details for a task including steps, progress, and log entries.

Parameter	Type	Required	Description
id	string	✓	Task ID (e.g. FN-001)

fn_task_attach

Attach a file to a task. Supports images (png, jpg, gif, webp) and text files (txt, log, json, yaml, yml, toml, csv, xml).

Parameter	Type	Required	Description
id	string	✓	Task ID (e.g. FN-001)
path	string	✓	Path to the file to attach

fn_task_pause

Pause a task — stops all automated agent and scheduler interaction for this task.

Parameter	Type	Required	Description
id	string	✓	Task ID (e.g. FN-001)

fn_task_unpause

Unpause a task — resumes automated agent and scheduler interaction.

Parameter	Type	Required	Description
id	string	✓	Task ID (e.g. FN-001)

fn_task_retry

Retry a failed task — clears the error state. Non-review failures move to todo; in-review execution failures move to todo preserving progress; in-review merge failures stay in-place for auto-merge retry.

Parameter	Type	Required	Description
id	string	✓	Task ID to retry (e.g. FN-001). Must be in 'failed' state.

fn_task_duplicate

Duplicate an existing task, creating a fresh copy in planning. Copies the title and description but resets all execution state. The AI planning agent will replan the new task.

Parameter	Type	Required	Description
id	string	✓	Source task ID to duplicate (e.g. FN-001)

fn_task_refine

Request a refinement of a completed or in-review task. Creates a new follow-up task in planning that references the original task as a dependency. Use this when a done or in-review task needs additional work, improvements, or follow-up changes.

Parameter	Type	Required	Description
id	string	✓	Task ID to refine (e.g. FN-001). Must be in 'done' or 'in-review' column.
feedback	string	✓	Description of what needs to be refined or improved

fn_task_archive

Archive a done task (move from done → archived). Archived tasks are preserved for historical reference but moved out of the main board view.

Parameter	Type	Required	Description
id	string	✓	Task ID to archive (e.g. FN-001). Must be in 'done' column.

fn_task_unarchive

Unarchive an archived task (move from archived → done). Restores the task to the done column.

Parameter	Type	Required	Description
id	string	✓	Task ID to unarchive (e.g. FN-001). Must be in 'archived' column.

fn_task_delete

Soft-delete a task from active Fusion board views. The task row and artifacts are preserved; optional allowResurrection marks the ID for intentional recreation.

Parameter	Type	Required	Description
id	string	✓	Task ID to delete (e.g. FN-001)
allowResurrection	boolean	—	When true, mark this tombstone as explicitly reusable for future recreation.

fn_task_plan

Create a task via AI-guided planning mode — interactive conversation to refine your idea into a well-specified task.

Parameter	Type	Required	Description
description	string	—	Initial plan description (optional) — the AI will ask clarifying questions if not provided
baseBranch	string	—	Optional base branch for the task created from this planning session

GitHub Tools

fn_task_import_github

Import GitHub issues as Fusion tasks. Fetches open issues from a repository and creates tasks in the planning column. Each task includes the issue title and body with a link to the source issue.

Parameter	Type	Required	Description
ownerRepo	string	✓	Repository in owner/repo format (e.g., 'dustinbyrne/fusion')
limit	number	—	Max issues to import (default: 30, max: 100)
labels	array	—	Label names to filter by

fn_task_import_github_issue

Import a specific GitHub issue as a Fusion task. Fetches the issue by number and creates a single task in the planning column with the issue title and body.

Parameter	Type	Required	Description
owner	string	✓	Repository owner (e.g., 'dustinbyrne')
repo	string	✓	Repository name (e.g., 'fusion')
issueNumber	number	✓	GitHub issue number to import

fn_task_browse_github_issues

List open GitHub issues from a repository to browse before importing. Returns issue numbers, titles, and URLs for selection. Use with fn_task_import_github_issue to import specific issues by number.

Parameter	Type	Required	Description
owner	string	✓	Repository owner (e.g., 'dustinbyrne')
repo	string	✓	Repository name (e.g., 'fusion')
limit	number	—	Max issues to show (default: 30, max: 100)
labels	array	—	Label names to filter by

Mission Tools

fn_mission_create

Create a new mission — a high-level objective that can span multiple milestones. Missions contain milestones that break down work into phases.

Parameter	Type	Required	Description
title	string	✓	Mission title — brief but descriptive
description	string	—	Detailed mission objectives and context
autoAdvance	boolean	—	Automatically activate the next pending slice when the current slice completes
baseBranch	string	—	Optional integration base branch for tasks triaged from this mission

fn_mission_list

List all missions with their current status.

Parameter	Type	Required	Description
includeDrafts	boolean	—	Include in-flight mission interview drafts (default: true)

fn_mission_show

Show mission details with full hierarchy: milestones → slices → features.

Parameter	Type	Required	Description
id	string	✓	Mission ID (e.g., M-001)

fn_mission_list_goals

List goals linked to a mission.

Parameter	Type	Required	Description
missionId	string	✓	Mission ID (e.g., M-001)

fn_mission_link_goal

Link a goal to a mission.

Parameter	Type	Required	Description
missionId	string	✓	Mission ID (e.g., M-001)
goalId	string	✓	Goal ID (e.g., G-001)

fn_mission_unlink_goal

Unlink a goal from a mission.

Parameter	Type	Required	Description
missionId	string	✓	Mission ID (e.g., M-001)
goalId	string	✓	Goal ID (e.g., G-001)

fn_mission_backfill_assertions

Backfill mission assertions by deriving and linking one store-managed assertion for each feature without linked assertions. Supports dry-run mode.

Parameter	Type	Required	Description
missionId	string	—	Mission ID to scope backfill to (e.g., M-001)
dryRun	boolean	—	When true, preview repairs without writing changes (default: true)

fn_mission_delete

Delete a mission and all its milestones, slices, and features. Cannot be undone.

Parameter	Type	Required	Description
id	string	✓	Mission ID to delete (e.g., M-001)

fn_mission_update

Update an existing mission's title or description. Partial patches leave untouched fields intact.

Parameter	Type	Required	Description
id	string	✓	Mission ID to update (e.g., M-001)
title	string	—	Updated mission title
description	string	—	Updated mission description

fn_milestone_add

Add a milestone to a mission. Milestones represent phases of work.

Parameter	Type	Required	Description
missionId	string	✓	Parent mission ID (e.g., M-001)
title	string	✓	Milestone title
description	string	—	Milestone description

fn_slice_add

Add a slice to a milestone. Slices are work units that can be activated for implementation.

Parameter	Type	Required	Description
milestoneId	string	✓	Parent milestone ID (e.g., MS-001)
title	string	✓	Slice title
description	string	—	Slice description

fn_feature_add

Add a feature to a slice. Features are deliverables that can be linked to tasks.

Parameter	Type	Required	Description
sliceId	string	✓	Parent slice ID (e.g., SL-001)
title	string	✓	Feature title
description	string	—	Feature description
acceptanceCriteria	string	—	Acceptance criteria for completing the feature

fn_feature_delete

Delete a feature. Rejects deletion when linked to a live task unless force=true.

Parameter	Type	Required	Description
featureId	string	✓	Feature ID to delete (e.g., F-001)
force	boolean	—	Override linked-task guard

fn_slice_delete

Delete a slice and its features. Rejects deletion when child features link to live tasks unless force=true.

Parameter	Type	Required	Description
sliceId	string	✓	Slice ID to delete (e.g., SL-001)
force	boolean	—	Override linked-task guard

fn_milestone_delete

Delete a milestone and all descendant slices/features. Rejects deletion when child features link to live tasks unless force=true.

Parameter	Type	Required	Description
milestoneId	string	✓	Milestone ID to delete (e.g., MS-001)
force	boolean	—	Override linked-task guard

fn_slice_activate

Activate a pending slice for implementation. Sets status to 'active' and enables task linking for its features.

Parameter	Type	Required	Description
id	string	✓	Slice ID to activate (e.g., SL-001)

fn_feature_link_task

Link a feature to a fn task for implementation. Updates the feature status to 'triaged' and associates it with the task. If the target task is not on the active board (for example archived, deleted, or never created), the tool returns a clear validation error indicating that only active tasks can be linked.

Parameter	Type	Required	Description
featureId	string	✓	Feature ID to link (e.g., F-001)
taskId	string	✓	Task ID to link to (e.g., FN-001)

fn_feature_update

Update an existing feature's title, description, or acceptance criteria. Partial patches leave untouched fields intact.

Parameter	Type	Required	Description
id	string	✓	Feature ID to update (e.g., F-001)
title	string	—	Updated feature title
description	string	—	Updated feature description
acceptanceCriteria	string	—	Updated acceptance criteria for completing the feature

fn_milestone_update

Update an existing milestone's title, description, or acceptance criteria (the structured pass/fail bar, distinct from verification's free-form how-to-confirm notes). Partial patches leave untouched fields intact.

Parameter	Type	Required	Description
id	string	✓	Milestone ID to update (e.g., MS-001)
title	string	—	Updated milestone title
description	string	—	Updated milestone description
acceptanceCriteria	string	—	Updated acceptance criteria for completing the milestone

Goal Tools

fn_goal_list

List goals by status with active-goal warning details.

Parameter	Type	Required	Description
status	union	—	Filter by goal status (default: active)

fn_goal_create

Create a new project goal.

Parameter	Type	Required	Description
title	string	✓	Goal title — brief but descriptive
description	string	—	Long-form goal description (free-text markdown)

fn_goal_archive

Archive a goal by ID.

Parameter	Type	Required	Description
id	string	✓	Goal ID (G-…) to archive

fn_goal_show

Show full details for a single goal by ID.

Parameter	Type	Required	Description
id	string	✓	Goal ID (G-…)

Agent Tools

fn_agent_stop

Stop a running agent — pauses its execution. Transitions the agent from running/active to paused state.

Parameter	Type	Required	Description
id	string	✓	Agent ID to stop (e.g., agent-abc123)

fn_agent_start

Start a stopped agent — resumes its execution. Transitions the agent from paused to active state.

Parameter	Type	Required	Description
id	string	✓	Agent ID to start (e.g., agent-abc123)

fn_agent_create

Create a new non-ephemeral agent.

Parameter	Type	Required	Description
name	string	✓	Agent name
role	union	✓	Agent role/capability
soul	string	—	Agent personality/identity text
instructions_text	string	—	Inline custom instructions
instructions_path	string	—	Path to instructions markdown
reportsTo	string	—	Manager agent ID
heartbeat_interval_ms	number	—
heartbeat_timeout_ms	number	—
max_concurrent_runs	number	—
message_response_mode	union	—

fn_agent_delete

Delete a non-ephemeral agent.

Parameter	Type	Required	Description
agent_id	string	✓	Agent ID to delete
force	boolean	—	Force delete when holding checkout
reassign_to	string	—	Optional replacement agent for assigned tasks

fn_list_agents

List all available agents in the system. Shows each agent's name, role, state, personality (soul), and current assignment. Use this to discover which agents exist and what they specialize in before delegating work.

Parameter	Type	Required	Description
role	string	—	Filter by agent role/capability (e.g., 'executor', 'reviewer', 'qa')
state	string	—	Filter by agent state (e.g., 'idle', 'active', 'running')
includeEphemeral	boolean	—	Include ephemeral/runtime agents (default: false)

fn_delegate_task

Create a new task and assign it to a specific agent for execution. The task goes to 'todo' and will be picked up by the target agent on their next heartbeat cycle. Use fn_list_agents first to find available agents and their capabilities. Optionally pass workflow_id to select a workflow at creation time; use fn_workflow_list to discover valid IDs.

Parameter	Type	Required	Description
agent_id	string	✓	The agent ID to delegate work to
description	string	✓	What needs to be done
dependencies	array	—	Task IDs this new task depends on (e.g. ["KB-001"]
workflow_id	string	—	Workflow ID to select for the new task (e.g. 'WF-003' or 'builtin:coding').
override	boolean	—	Set true to bypass executor-role assignment policy

fn_agent_show

Show detailed information about a single agent, including their role, state, position in the org hierarchy (reports-to, direct reports), skills, and current assignment.

Parameter	Type	Required	Description
id	string	✓	Agent ID or resolvable name

fn_agent_org_chart

Show the organizational tree of agents, displaying the role hierarchy. Optionally filter to a subtree rooted at a specific agent.

Parameter	Type	Required	Description
root_agent_id	string	—	If provided, show only the subtree rooted at this agent
include_ephemeral	boolean	—	Include ephemeral/runtime agents (default: false)

Skills Tools

fn_skills_search

Search the skills.sh directory for agent skills. Returns matching skills with names, sources (owner/repo), install counts, and install commands. Use fn_skills_install to install a selected skill.

Parameter	Type	Required	Description
query	string	✓	Search query — framework name, technology, or capability (e.g., 'react', 'firebase', 'testing', 'docker')
limit	number	—	Max results to return (default: 10, max: 50)

fn_skills_install

Install an agent skill from skills.sh into the current project. Downloads skill files into the project's skill directories (.fusion/skills/, legacy .pi/skills/, .agents/skills/). The skill becomes available to AI agents in subsequent sessions.

Parameter	Type	Required	Description
source	string	✓	GitHub source in owner/repo format (e.g., 'firebase/agent-skills')
skill	string	—	Specific skill name to install (e.g., 'firebase-basics'). Omit to install all skills from the source.

Insight Tools

fn_insight_list

List persisted project insights with optional category/status filters.

Parameter	Type	Required	Description
category	string(enum)	—	Filter by insight category
status	string(enum)	—	Filter by insight status
runId	string	—	Filter to insights linked to a specific run ID
limit	number	—	Max insights to return
offset	number	—	Number of rows to skip

fn_insight_show

Show a single persisted insight by ID.

Parameter	Type	Required	Description
id	string	✓	Insight ID (e.g. INS-XXXXX)

fn_insight_run_list

List recent insight-generation runs with optional status/trigger filters.

Parameter	Type	Required	Description
status	string(enum)	—	Filter by run status
trigger	string(enum)	—	Filter by run trigger
limit	number	—	Max runs to return
offset	number	—	Number of runs to skip

fn_insight_run_show

Show a single insight-generation run by ID.

Parameter	Type	Required	Description
id	string	✓	Insight run ID (e.g. INSR-XXXXX)

Other Tools

fn_web_fetch

Lightweight URL fetch (no JS rendering). Use agent-browser skill for JS-heavy pages. URL to fetch (http/https) Optional extraction hint for downstream summarization Timeout in milliseconds (default: 30000) Max bytes to return (default: 512000)

Parameter	Type	Required	Description
url	string	✓	URL to fetch (http/https)
prompt	string	—	Optional extraction hint for downstream summarization
timeoutMs	number	—	Timeout in milliseconds (default: 30000)
maxBytes	number	—	Max bytes to return (default: 512000)

fn_secret_get

Read a secret by key using per-secret access policy.

Parameter	Type	Required	Description
key	string	✓	Secret key
scope	union	—	Optional scope

fn_research_run

Cited-research pipeline: create a bounded search/fetch/synthesis run (not an autonomous experiment loop) and optionally wait for completion.

Parameter	Type	Required	Description
query	string	✓	Research query or question
wait_for_completion	boolean	—	Wait for the run to complete before returning (default: false)
max_wait_ms	number	—	Max wait time when wait_for_completion=true (default: 90000, capped by settings)

fn_research_list

Cited-research pipeline: list recent search/fetch/synthesis runs (not experiment-loop sessions).

Parameter	Type	Required	Description
status	string(enum)	—	Filter by run status
limit	number	—	Max runs to return (default: 10)

fn_research_get

Cited-research pipeline: get one run with structured findings and citations (not experiment-loop state).

Parameter	Type	Required	Description
id	string	✓	Research run ID

fn_research_cancel

Cited-research pipeline: cancel an in-flight run; terminal runs return INVALID_TRANSITION (does not control experiment loops).

Parameter	Type	Required	Description
id	string	✓	Research run ID

fn_research_retry

Cited-research pipeline: retry a failed run when lifecycle marks it retryable (not an autonomous experiment loop retry).

Parameter	Type	Required	Description
id	string	✓	Research run ID

fn_experiment_finalize

Group kept experiment runs into reviewable branches and finalize the session. Use dryRun=true to preview the plan without touching git.

Parameter	Type	Required	Description
sessionId	string	✓	Experiment session ID
integrationBranch	string	—	Integration branch to compute merge-base against (default: main)
dryRun	boolean	—	Preview plan only; do not create branches
planOverride	unknown	—	Optional plan override payload
summary	string	—	Optional finalize summary

Goal retrieval contract notes

Goal-show response contract

• Success: returns details.goal as the complete goal JSON object (id, title, optional description, status, createdAt, updatedAt) and content[0].text with those same human-readable fields.
• Not found: returns isError: true with details.code: "GOAL_NOT_FOUND" and details.goalId set to the requested id.

Dashboard Command

/fn

Start or stop the Fusion dashboard from within an agent session.

Command	Description
/fn	Start dashboard on port 4040
/fn 8080	Start on custom port
/fn stop	Stop dashboard
/fn status	Check if running