agent-runbook

Files (1)

• SKILL.md

SKILL.md (first lines)

# agent-runbook

Operational routing rules for engineering work on this machine. Replaces tribal-knowledge mode selection with an explicit pipeline.

**What this skill IS:** a router. Input: a task description (or a stage you're in). Output: a composed pipeline of stages + tools + gates.

**What this skill is NOT:** a governance framework, a planner, or a replacement for any underlying tool. GSD still plans, ao still executes, OMC still spikes — this skill just decides who runs what.

## Why this exists

The agent stack has accumulated ~12 execution surfaces (ao spawn, ao batch-spawn, GSD, OMC `/team`, `:autopilot`, `:ralph`, `:ultrawork`, `/goal`, `/loop`, `/schedule`, inline, codex, gemini, Claude Flow swarm). Choosing wrong wastes time and erodes review gates. Past mistakes (pushing wrong content to a misnamed forge repo; force-pushing without codex pre-review; routing trivial code change inline when it should have been a PR) trace back to bad routing.

Codex's LLM-as-judge review on 2026-05-21 flagged that earlier single-mode routing hid composed workflows, missed Linear/CI/browser tooling, and treated destructive ops too thinly. This skill is v2 — composed pipelines, mandatory pre-flight gates, golden routing tests.

## Lifecycle stages (5)

Most tasks touch a subset. The decision card identifies the current stage and routes ONE step at a time.

| # | Stage | Question | Tools |
|---|---|---|---|
| 1 | Clarify | Do we know what 'done' looks like? + Which mode? | `/gsd-spec-phase`, `/gsd-discuss-phase`, OMC `:deep-interview`, inline Q&A. **Mode selection is part of this stage** — Decide-mode is not a separate stage. |
| 2 | Execute | Do the work | `ao spawn`, `/gsd-execute-phase`, `/team`, `/goal`, OMC `:autopilot`/`:ralph`/`:ultrawork` (spike-only), inline (whitelist only), Claude Flow swarm (research/analysis only) |
| 3 | Review | Code review + pre-merge gates | `prepare-clean-mr`, `/code-review`, OMC `:critic`, **codex pre-review (mandatory for destructive)** |
| 4 | Verify | Did it actually work? | `/verify`, `/gsd-verify-work`, OMC `:verify`, `:ultraqa`, CI green-check (`gh run list`, `glab ci status`), browser/UI verification for frontend |
| 5 | Ship | PR/MR merge + notify | `/gsd-ship`, `gh pr merge`, `glab mr merge`, ClickUp DM via `clickup-api` skill |

Capture (idea → todo) and Reflect (extract learnings) are intentionally OUT of scope here — `/gsd-note`, `/gsd-add-backlog`, `/learn`, `:learner`, `:skillify` handle those independently.

## Mandatory pre-flight checks (BEFORE any execution)

These run regardless of mode and must pass:

1. **Supergit-trap check.** For any task involving push/rewrite/MR against a repo under `~/Sync/...`: run `git rev-parse --show-toplevel` from the target dir. If it returns `$HOME/Sync`, that subdir is NOT its own repo. Clone fresh outside `~/Sync` (e.g. `/tmp/<name>-<timestamp>/` or `~/work/<name>/`) before planning.

2. **Destructive Ops Gate.** Force-push, `git filter-repo`, `git reset --hard` on protected branches, `git rm` of >5 files, bulk DB ops, or any shared-history rewrite triggers a MANDATORY codex pre-review. See CLAUDE.md "Destructive Ops Gate" section for the spec format and the codex invocation. Verdict DO-NOT-PROCEED or any blocker → STOP and surface to user.

3. **Repo identity verification.** For any forge-bound operation, a fresh clone's README and root tree must match the expected project name. URL ≠ contents. (`dash-hubspot-sales-pipeline.git` actually hosted a `rotorooter-infrastructure-` mirror — we caught it via codex; we shouldn't rely on luck.)

4. **prepare-clean-mr preflight.** Before opening or updating an MR, run the `prepare-clean-mr` skill — catches drifted merge base, build artifacts, oversized assets, stale planning files, secrets in `.env`, debug code, stale Co-Authored-By trailers.

## Decision tree (Stage 1 — Clarify, includes mode selection)

```
Trivial code change matching the whitelist?
(CLAUDE.md/settings/AGENTS.md edit, ~/.claude/ files, .omc/ files,
 single-line config value)
└─ YES → inline immediately. Skip rest of tree.

Is this a code change at all?
├─ NO → What kind?
│  ├─ Research / analysis → inline OR codex-smart (hard q's, live data via --search)
│  │                        OR Claude Flow swarm (parallel multi-angle research)
│  ├─ Multi-repo survey → loop gh/glab CLI inline, OR codex-smart for synthesis
│  ├─ Read-only monitoring → `claude agents` (background session, read-only)
│  └─ Outbound comms → inline + `clickup-api` skill for ClickUp DMs
│                       (validate roster, prefix 🧞)
│
└─ YES → Destructive? (force-push, filter-repo, bulk delete, shared-history rewrite)
   ├─ YES → Destructive Ops Gate (codex pre-review) → inline w/ --force-with-lease
   │
   └─ NO → Multi-phase / spec-required / .planning/ already exists?
      ├─ YES → GSD: /gsd-discuss-phase or /gsd-plan-phase, then /gsd-execute-phase
      │        (execute-phase dispatches per-task to ao spawn)
      │
      └─ NO → Frontend / UI change?
         ├─ YES → ao spawn (PR) + browser/UI verify in Verify stage
         │
         └─ NO → How many independent sub-tasks?
            ├─ 1 → ao spawn (PR-gated default)
            ├─ N independent → ao batch-spawn
            ├─ N coordinated (live) → /team
            └─ N durable (cross-session) → /goal

      Recurring?
      ├─ Interval poll → /loop
      └─ Cron schedule → /schedule

      Exploratory spike?
      ├─ Solo loop → OMC :autopilot or :ralph (spike-only — production result
      │             must be re-implemented via ao spawn afterward)
      └─ N competing approaches → ao batch-spawn with variant prompts
                                  (kill-rate prototyping)

      High-throughput single task?
      └─ OMC :ultrawork (production result still re-implemented via ao spawn)
```

## Decision card format (the skill's output)

When invoked, output exactly this structure:

```
TASK: <one-line summary>
CURRENT STAGE: <1-5>
PIPELINE: <stage-by-stage tool list>
GATES TRIGGERED: <none | destructive-ops | supergit-trap | codex-pre-review | prepare-clean-mr | browser-verify>
NEXT ACTION: <single command for the current stage only>
WHY: <2-sentence rationale>
```

Example for "Fix a one-line bug in app/main.py":

```
TASK: Fix one-line bug in app/main.py (TypeError on None deal)
CURRENT STAGE: 1 (Clarify) — already clear, ready to Execute
PIPELINE: ao spawn → prepare-clean-mr → /code-review → /verify → /gsd-ship
GATES TRIGGERED: prepare-clean-mr (at Review)
NEXT ACTION: ao spawn --prompt "Fix TypeError on None deal in app/main.py line 42 — add guard before .amount access"
WHY: Production code change to a deployed file. Not in the inline whitelist; not destructive; single task. ao spawn is the PR-gated default.
```

Example for "Investigate flaky CI test and fix it":

```
TASK: Investigate flaky test_rate_limiter (CI failure rate ~30%)
CURRENT STAGE: 1 (Clarify) — diagnosis first, then code change
PIPELINE: inline (read-only diagnosis: gh run list + log inspection)
        → /gsd-discuss-phase (if cause is non-trivial)
        → ao spawn (fix)

From search-atlas-group/amm-founding-circle, MIT.

More from search-atlas-group/amm-founding-circle