autopilot

Files (7)

• SKILL.md
• templates.md · references/
• verification.md · references/
• audit-detect.mjs · scripts/
• audit-edit.mjs · scripts/
• audit-report.mjs · scripts/
• ship-pr.mjs · scripts/

SKILL.md (first lines)

# Put this repo on autopilot

Agents ship most changes; the human owns product decisions. Any stack, any code
host. Sections map to three pillars plus improvement loops.

The tools ship in the `kcd-skills` package: run
`npx kcd-skills@latest autopilot <command>` (`--help` on any command lists its
options). Commands work from local files and git; when one needs something only
the code host knows, it prints what to gather and the format, and you supply it
with whatever tools reach the host.

## Principles

**P1 Good PRs from the start**

1. The repo tells agents what to build and how to prove it.
2. One small `AGENTS.md` map and one verify command (local == CI).
3. Write down the "no": decisions agents would otherwise re-propose.
4. Guidance earns its place by use: keep the skills and docs agents cite.
   Generate maps from the source of truth.

**P2 Review, iteration, and verification through tests and local proof**

5. Scripts decide anything checkable (audit facts, CI, PR state); agents judge.
6. Agents run their own change before merge and claim only what they verified.
   Feature tests prove features; health checks prove the running version.

**P3 Limit blast radius when a mistake reaches production**

7. Risky changes ship dark, and recovery is tested.
8. Product calls and one-way doors go to the human.

**KI Keep improving**

9. Agents file friction after every PR with a priority; other agents fix it,
   highest priority first.

## Rules

- Start editing once the human approves the plan. One setup PR for every planned
  rung's file changes, using the repo's own tools and layout.
- Follow the contribution policy; stop if it excludes agent PRs. In community
  repos, add files and keep the existing CI.
- For libraries, self-hosted, CLI, and mobile projects, "deploy" means
  "release".
- Keep secrets out of files, issues, and PRs.
- Tell the human every manual step (secrets, app installs, access grants,
  settings you cannot apply). Use a concrete checklist: what, where, why. Give
  it at plan approval and again after the setup PR merges for anything still
  open.

## Rungs: done when (audit checklist and ladder)

**P1 Good PRs**

1. Agent map + verify: a short `AGENTS.md` (or equivalent) linking the docs
   agents use; one verify command (tests, typecheck where the language has one,
   lint, format) CI runs in full. Commit and pre-push hooks run the fast static
   checks (lint, format, typecheck, dead-code checks); CI time budgets fail only
   on real problems.
2. Decisions directory: ADRs for multi-PR decisions and the "no", each with
   "Revisit if".
3. Primitives catalog: building blocks, code roots, and an `adrs` list per entry
   (current records that shape it, `[]` when none), kept short. A PR that adds
   or reshapes a primitive, or writes or supersedes an ADR, updates the matching
   `adrs` lists in the same PR.
4. Self-verification: agents run their change locally with a project control CLI
   (`doctor`, `dev`, `login`, `request --contains`, `execute`, `browse`,
   `health --sha`) and a `control-<project>` skill. For apps with routes, a
   Feature Map generated from the framework's route list, with seed-and-reach
   notes, checked in CI. Previews cover production-like checks. Model: Kody's
   `control-kody`; see `npx kcd-skills@latest autopilot verification`.
5. PR template: Intent, Why, Door, Cleanup, Testing, System recap.

**P2 Review and verification**

6. Ship loop: Kody `ship-pr` or `kcd-skills autopilot ship-pr` + config, behind
   a thin `ship-pr` skill.
7. Reviewers + previews: AI reviewers per tier scrutinize test-expectation
   changes made with the code they test; previews for production-like changes;
   agent merge; running-version check after deploy. Reviewers check each PR
   against the project's principles (when it has them), and each principle a
   machine can check becomes a lint rule or test.

**P3 Blast radius**

8. Flags + rollback: flags with owner, metric, removal condition; rollback
   runbook.
9. Backups: scheduled, isolated restore test.

**KI Keep improving**

10. Friction form: issue form + `friction`, `friction-skipped` labels, filed by
    every ship loop and triaged (rung 11).
11. Triage: every issue agents file (friction, cleanup, errors) gets a priority
    and, when it needs a human call, the project's decision marker. Agents work
    the highest priority first; decision-marked issues wait for the human's
    call. Default: `P0`-`P3` labels + `needs-decision`; the team's own scheme
    (labels, a project-board field, a tracker priority field) from the interview
    takes its place.
12. Cleanup issues: `Cleanup:` issues with a falsifiable "ready when", triaged
    (rung 11).
13. Cleanup cron agents (daily friction sweep, errors → issues, docs freshness
    and pruning, test pruning, weekly legacy reaper) open PRs, highest priority
    first (rung 11); only low/medium risk with green CI auto-merges. See
    templates → **Cleanup automations**.

Order: P1 first (checkable), then P2/P3 (trust), then loops.

## 1. Audit (read only)

Leave tracked files unchanged; deploy, publish, release, and push wait for the
ladder. Installing dependencies is fine. Commands gather facts; you judge:

```sh
mkdir -p .autopilot
# Keep audit artifacts out of git (add .autopilot/ to .gitignore if needed).
npx kcd-skills@latest autopilot audit . --out .autopilot/before.json
```

From kentcdodds/kcd-skills, MIT.

More from kentcdodds/kcd-skills