|
| 1 | +--- |
| 2 | +description: Create an Aviator Runbook — Aviator's agent writes the code from your spec |
| 3 | +--- |
| 4 | + |
| 5 | +# Create a Runbook |
| 6 | + |
| 7 | +Create an Aviator Runbook from the current Claude Code session context. **Aviator's agent writes the code** from the spec you submit, so this flow carries full implementation detail — intent, scope, ordered steps, and acceptance criteria — and includes an implementation discussion with you before kicking off. |
| 8 | + |
| 9 | +> Writing the code yourself and just want Aviator to verify it against intent + acceptance criteria? Use `/verify-submit` instead — it captures intent and AC with no implementation steps. |
| 10 | +
|
| 11 | +**Load the `spec-submission` skill** (Skill tool → `aviator:spec-submission`) before you start — it carries the shared mechanics this flow relies on: how the message reads, the Acceptance Criteria review loop, the `specSubmit` call, and the PR directive. This command file only covers what's specific to a Runbook. |
| 12 | + |
| 13 | +## Arguments |
| 14 | + |
| 15 | +$ARGUMENTS - Optional additional context or instructions for the runbook. |
| 16 | + |
| 17 | +## Step 1: Generate Message + Spec |
| 18 | + |
| 19 | +Write the message per the `spec-submission` skill, and the Acceptance Criteria per the `acceptance-criteria` skill — **AC are the primary output of this step.** What's specific to a Runbook is that the spec **carries implementation detail** — the agent uses it to write the code. |
| 20 | + |
| 21 | +### Spec file |
| 22 | + |
| 23 | +The spec provides the supporting context the AC needs to be unambiguous, plus the implementation detail the agent works from. Don't pad. |
| 24 | + |
| 25 | +If a plan file exists from plan mode (check the plan file path mentioned in the system prompt), read it and check whether its content is relevant to the user's current intent. If it is, use it as-is — do not restructure, reformat, or rewrite it. Pass its content through directly as the spec. If the plan file is unrelated to the current task, ignore it and generate a new spec instead. |
| 26 | + |
| 27 | +Similarly, if a spec file already exists in the conversation — one the user wrote, one generated earlier, or one provided via `$ARGUMENTS` — use it as-is. Do not restructure, reformat, or rewrite an existing spec. When the spec comes from a file, preserve the original filename. |
| 28 | + |
| 29 | +If no existing spec is available, generate one. Keep it **free-form** — there's no required structure or fixed set of sections. Write whatever best conveys the change to the agent that will implement it: the intent and the implementation approach or steps, shaped to the task rather than forced into headings. (The acceptance criteria are passed separately as the `acceptance_criteria` argument — you don't hand-embed them; the backend folds them into the spec the agent works from.) |
| 30 | + |
| 31 | +## Step 2: Review with the user |
| 32 | + |
| 33 | +Before submitting, show the user three things and get their sign-off: |
| 34 | + |
| 35 | +1. **The intent** — the short intent message, for grounding. |
| 36 | +2. **The Acceptance Criteria** — run the review loop from the `spec-submission` skill, iterating until the user explicitly confirms. |
| 37 | +3. **Any pertinent questions or callouts** — while writing the free-form spec, notice anything the user should weigh in on before submitting: a consequential choice (a new dependency, a data migration, a public API change, an area to leave untouched), an ambiguity in the approach, or a decision you made that they haven't seen. Raise only what's genuinely open — if the approach was already settled earlier in this session, don't re-litigate it. |
| 38 | + |
| 39 | +A simple "yes" or "go ahead" is enough to submit. |
| 40 | + |
| 41 | +## Step 3: Create Runbook |
| 42 | + |
| 43 | +Submit via the `specSubmit` call described in the `spec-submission` skill. For a Runbook: |
| 44 | + |
| 45 | +- `submission_type`: **`"runbook"`** — the agent writes the code from the spec. This is the default, but pass it explicitly. |
| 46 | +- `acceptance_criteria`: the confirmed AC as a JSON array of strings (optional but recommended — they're folded into the spec the agent works from). |
| 47 | +- `spec_files`: include only if a spec was generated; always a single file. |
| 48 | +- `target_branch`: **optional** — the base branch the runbook builds on and checks out; the generated PR opens against it. Omit for the repo default (trunk). (Runbook mode generates its own PR, so there's no `working_branch` to connect here.) |
| 49 | + |
| 50 | +Then return the Runbook URL and set the PR directive, both per the `spec-submission` skill. The expected PR body shape: |
| 51 | + |
| 52 | +``` |
| 53 | +Runbook: <runbook-url> |
| 54 | +
|
| 55 | +## Summary |
| 56 | +… |
| 57 | +
|
| 58 | +## Test plan |
| 59 | +… |
| 60 | +``` |
0 commit comments