feat(FN-3327): add agent delegation and org hierarchy tools to pi extension

Adds `list_agents` and `delegate_task` tools to the pi extension for inter-agent delegation, along with supporting reference docs and 248 new tests. The sync script was also updated to keep the skill tools in sync with the extension implementation.

Fusion-Task-Id: FN-3327

packages/cli/skill/fusion/SKILL.md

@@ -30,7 +30,7 @@ Mission → Milestone → Slice → Feature → Task
 - **Task tools** — `fn_task_create`, `fn_task_update`, `fn_task_list`, `fn_task_show`, `fn_task_attach`, `fn_task_pause`, `fn_task_unpause`, `fn_task_retry`, `fn_task_duplicate`, `fn_task_refine`, `fn_task_archive`, `fn_task_unarchive`, `fn_task_delete`, `fn_task_plan`
 - **GitHub tools** — `fn_task_import_github`, `fn_task_import_github_issue`, `fn_task_browse_github_issues`
 - **Mission tools** — `fn_mission_create`, `fn_mission_list`, `fn_mission_show`, `fn_mission_delete`, `fn_milestone_add`, `fn_slice_add`, `fn_feature_add`, `fn_slice_activate`, `fn_feature_link_task`
-- **Agent tools** — `fn_agent_stop`, `fn_agent_start`
+- **Agent tools** — `fn_agent_stop`, `fn_agent_start`, `fn_list_agents`, `fn_delegate_task`, `fn_agent_show`, `fn_agent_org_chart`
 - **Skills tools** — `fn_skills_search`, `fn_skills_install`
 - **Insight tools** — `fn_insight_list`, `fn_insight_show`, `fn_insight_run_list`, `fn_insight_run_show`
 - **Other tools** — `fn_research_run`, `fn_research_list`, `fn_research_get`, `fn_research_cancel`

packages/cli/skill/fusion/references/best-practices.md

@@ -89,3 +89,36 @@ For work larger than L, use missions to break it into phases.
 2. `fn_task_import_github_issue` for high-priority issues
 3. Tasks enter triage and get AI-specified
 4. Monitor board as AI works through them
+
+## Agent Management and Delegation
+
+Agents are AI workers in the Fusion system. Each agent has a role, state, and position in an organizational hierarchy. Use the agent management tools to discover, inspect, delegate to, and manage agents.
+
+**Discovering available agents:**
+1. `fn_list_agents` — see all agents, optionally filter by role or state
+2. `fn_agent_show` — get full details about a specific agent (including hierarchy)
+3. `fn_delegate_task` — create and assign a task to the chosen agent
+
+**Checking team structure before delegation:**
+1. `fn_agent_org_chart` — visualize the full org tree
+2. `fn_agent_show` — inspect a specific agent's capabilities and reports
+3. `fn_delegate_task` — assign work to the appropriate agent
+
+**Delegation patterns:**
+- **Delegate to reports** — an agent delegates to agents that report to it (downward delegation)
+- **Delegate to peers** — an agent delegates to another agent at the same level (lateral delegation)
+- **Delegate to other teams** — use `fn_agent_org_chart` to understand cross-team structure
+- Always verify the target agent is not ephemeral/runtime before delegating
+
+**Recovery — re-delegating stalled work:**
+1. `fn_agent_stop` — pause the stalled agent
+2. `fn_list_agents` — find an available agent to take over
+3. `fn_delegate_task` — create a new task for the replacement agent
+4. The original task can be refined or the new task can depend on it
+
+**Agent lifecycle states:**
+- `idle` — agent is available for work
+- `active` — agent is running and available for heartbeat cycles
+- `running` — agent is currently executing a task
+- `paused` — agent has been stopped (use `fn_agent_start` to resume)
+- `error` — agent encountered an error

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

@@ -263,6 +263,43 @@ Start a stopped agent — resumes its execution. Transitions the agent from paus
 |-----------|------|----------|-------------|
 | `id` | string | ✓ | Agent ID to start (e.g., agent-abc123) |
 
+### 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.
+
+| 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\"] |
+
+### 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

packages/cli/skill/fusion/references/fusion-capabilities.md

@@ -48,6 +48,10 @@ All skill/extension tool invocations in this catalog use the public `fn_*` names
 | `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. |
 | `fn_agent_stop` | Stop a running agent — pauses its execution. Transitions the agent from running/active to paused state. |
 | `fn_agent_start` | Start a stopped agent — resumes its execution. Transitions the agent from paused to active state. |
+| `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. |
+| `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. |
+| `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. |
+| `fn_agent_org_chart` | Show the organizational tree of agents, displaying the role hierarchy. Optionally filter to a subtree rooted at a specific agent. |
 | `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. |
 | `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. |
 <!-- END: fusion-capabilities-tool-table -->