/nav-pilot

name: nav-pilot
description: Dispatch a Navigator task doc to Pilot as a labeled GitHub issue. Use when user says "dispatch TASK-XX to Pilot", "hand off to Pilot", "send to Pilot", or "queue for Pilot". One-way handoff (Navigator authors the spec, Pilot executes autonomously).
allowed-tools: Read, Edit, Bash, Glob
version: 1.0.0

Navigator → Pilot Dispatch Skill

Hand a finished Navigator task doc off to Pilot by creating the `pilot`-labeled GitHub issue Pilot polls, then record the issue back into the doc.

**This skill does NOT validate the doc.** Spec checking is Pilot's job (its `spec_validator`). nav-pilot only resolves the doc, creates the labeled issue, and records the result. It consumes what `nav-task` authored — it does not author or archive docs itself.

When to Invoke

Invoke when the user says:

• "Dispatch TASK-XX to Pilot"
• "Hand this off to Pilot" / "send to Pilot"
• "Queue TASK-XX for Pilot" / "create the Pilot issue"

**DO NOT invoke** when:

• User is authoring/archiving a task doc (that's `nav-task`)
• User wants Pilot worker status (out of scope — this skill is one-way)
• No task doc exists yet (tell them to create one with `nav-task` first)

Execution Steps

Step 1: Resolve the Target Task Doc

• **Explicit ID** ("TASK-07"): use `.agent/tasks/TASK-07-*.md`.
• **No ID**: pick the active/in-progress task. If ambiguous, list candidates

(`ls .agent/tasks/*.md`) and ask which one.

• If the file does not exist, stop and tell the user to author it first.

Read the doc and extract:

• **Title** = the first H1 (`# TASK-XX: <name>`), stripped of the `TASK-XX:` prefix

if present (or keep the full H1 — match what Pilot expects).

• **Body file path** = the doc itself (passed via `--body-file`, never inlined).

Step 2: Load Pilot Config

Read `pilot` from `.agent/.nav-config.json`:

"pilot": {
  "enabled": true,
  "label": "pilot",
  "repo": null
}

• `label` (default `"pilot"`): the label Pilot polls for.
• `repo` (default `null`): target `owner/name`. When `null`, `gh` uses the

current git repository's origin — do NOT pass `--repo`.

If `pilot.enabled` is `false`, stop and tell the user to enable it.

Step 3: Build the Command

gh issue create \
  --title "<H1 title>" \
  --label "<pilot.label>" \
  --body-file ".agent/tasks/TASK-XX-<slug>.md" \
  [--repo "<pilot.repo>"]   # only when pilot.repo is set

Step 4: Pre-flight Confirmation (ToM Checkpoint — high-stakes)

Creating a GitHub issue is an outward-facing action. ALWAYS confirm first:

About to dispatch to Pilot:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Repo:  <pilot.repo or "current origin (gh default)">
Title: <H1 title>
Label: <pilot.label>
Body:  .agent/tasks/TASK-XX-<slug>.md (<N> lines)

Command:
  gh issue create --title "..." --label "pilot" --body-file "..."
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Create this issue? [Enter to dispatch / "dry-run" / corrections]

**`--dry-run` mode**: if the user asked for a dry run (or says "dry-run" here), print the exact `gh` command and STOP. Do not execute.

Step 5: Dispatch

Run the `gh issue create` command. Capture the returned issue URL from stdout (`gh issue create` prints the URL on success).

If `gh` fails:

• not authenticated → tell the user to run `gh auth login`
• label missing on the repo → offer `gh label create pilot`
• no git remote / repo not found → ask for `pilot.repo` in config

Step 6: Record Back Into the Doc

Edit the task doc:

• Add the issue URL under `## Refs`:

`- Pilot issue: <url>`

• Update the status line to `**Status**: 🚀 Dispatched to Pilot`.
• Update `**Last Updated**:` to today.

Step 7: Confirm

✅ Dispatched to Pilot

Issue:  <url>
Label:  pilot
Task:   TASK-XX — <title>

Recorded back into .agent/tasks/TASK-XX-<slug>.md (status → 🚀 Dispatched).
Pilot will pick it up on its next poll of `pilot`-labeled issues.

If the knowledge graph is enabled, the Edit will sync via the normal PostToolUse hook — no extra action needed.

Error Handling

| Situation | Response | |-----------|----------| | No task doc found | Ask which task; suggest `nav-task` to create one | | `pilot.enabled: false` | Stop; tell user to enable in `.nav-config.json` | | `gh` not authenticated | Prompt `gh auth login` | | `pilot` label missing | Offer `gh label create pilot` | | No remote / repo unknown | Ask user to set `pilot.repo` |

Success Criteria

• [ ] Correct task doc resolved and H1 used as the issue title
• [ ] Pre-flight confirmation shown before any network call
• [ ] `--dry-run` prints the command without executing
• [ ] Issue created with the `pilot` label
• [ ] Issue URL recorded back into the doc; status → 🚀 Dispatched

Notes

• One-way by design: monitoring Pilot workers and pulling results back are out

of scope (see `.agent/tasks/TASK-54-nav-pilot-dispatch-skill.md`).

• Validation is intentionally absent — Pilot's `spec_validator` owns that.
• Pairs with `nav-task` (authors the doc) → `nav-pilot` (dispatches it).