autopilot

An agentic Claude Code setup. A project-manager agent plans the work, role agents execute it, and you keep two gates: promote draft → ready, and merge the PR. Everything else — subagents, slash commands, permissions, plugins — is the tooling the autopilot runs on top of.

Built for Opus 4.8 with stacked-PR workflows in mind. Tuned for Node.js / TypeScript projects.

---

The autopilot — plan and execute

This is the point of the repo. agentic-project-manager/ is a reusable control panel for a small crew of background AI agents that plans and executes work against your product repos. It is deliberately simple: one loop, two roles, two human gates.

• Plan — a project-manager agent refines draft tasks into a concrete spec (acceptance criteria, open questions) and dispatches ready ones.
• Execute — role agents (software-engineer, devops-engineer, qa-reviewer) implement in the target repo and open a PR.
• You — promote draft → ready when the plan looks good, and merge the PR when the work looks good.

A task is a markdown file with typed YAML frontmatter. /pm-loop is one idempotent tick over the current state — refine drafts, dispatch ready tasks, reflect merges. No separate objectives / knowledge / cataloguer layer.

The loop

/new-project <desc>  ──▶  draft  ──(PM refines)──▶  draft*  ──(you promote)──▶  ready
                                                                                   │
                                                                       (PM dispatches)
                                                                                   ▼
                        done  ◀──(you merge)──  in-review  ◀──(role agent PR)──  in-progress

Structure

You stamp out an instance (its own repo, typically a agentic-project-manager/ directory beside the product repos it manages) and drive it from a Claude session inside that directory.

Part	What's there
symlink/ — machinery, symlinked into every instance	Role agents project-manager, software-engineer, devops-engineer, qa-reviewer; commands /pm-loop, /new-project, /pr-review-request, /todo; SCHEMA.md; commit-as.sh for per-agent commit authorship; a SessionStart hook that surfaces open todos
seed/ — copied once, then yours	instance.config.json, the instance CLAUDE.md, an empty projects/, todos.md, and agentic-project-manager.code-workspace (multi-root editor view)
install.sh	Stamps out / refreshes an instance: file-granular symlinks + seed copy + managed .gitignore block

The agentic-project-manager/ subtree is deliberately separate from ~/.claude: the user-wide install.sh never touches it, and its agents/commands install into instances, not ~/.claude.

→ Full guide: agentic-project-manager/README.md.

---

Getting started

git clone https://github.com/<your-fork>/autopilot.git ~/path/to/autopilot
cd ~/path/to/autopilot
./install.sh

That installs the supporting tooling (agents, commands, skills, defaults) into ~/.claude so every project sees them. In any project: claude, then /init to bootstrap its CLAUDE.md.

To stand up an autopilot instance for the PM workflow:

mkdir -p ~/workspace/agentic-project-manager
~/path/to/autopilot/agentic-project-manager/install.sh ~/workspace/agentic-project-manager
cd ~/workspace/agentic-project-manager
$EDITOR instance.config.json           # set org, reposRoot, authorEmail
git init && git add -A && git commit -m "chore: bootstrap autopilot instance"
claude                                 # now /pm-loop and role agents load

Prefer a frozen per-project copy of the supporting tooling? See Install → Option B.

---

Supporting tooling

The config layer the autopilot — and your everyday coding — runs on: agents, commands, skills, and settings that install into ~/.claude.

Agents (.claude/agents/)

Generic Node/TS agents — they infer your toolchain from package.json instead of hardcoding paths.

Agent	Model	Purpose	Invoked by commands
build-validator	Sonnet	Typecheck / lint / test / build. --deep = clean-install + sequenced unit→int→e2e	/verify
code-architect	Opus	Staff-level review of staged + unstaged changes	/grill (grill fallback, no Workflow), direct dispatch
deep-bug-scan	Opus	Deep scan for logic bugs, null risks, race conditions, SQL issues, weak tests	/scan
oncall-guide	Sonnet	Diagnoses test/CI failures and classifies the cause	/verify (on failure)
plan-architect	Opus	Critiques an implementation plan before code is written	/plan (grill fallback, no Workflow)
stack-navigator	Sonnet	Reads gh stack view and proposes the next safe action in a stacked-PR flow	/stack (no args)

For cleaning up recently changed code, use the built-in /simplify skill.

Slash commands (.claude/commands/)

One .md per command; filename becomes /<name>. No frontmatter required; $ARGUMENTS expands to whatever the user typed. See .claude/README.md for the command-vs-skill distinction.

Command	What it does	Dispatches agents
/acp	Stage, commit with a generated message, and push (stack-aware)	—
/dave	Critique current diff/plan via Dave AI (org-internal review tool — requires dave CLI)	—
/grill	Adversarial fan-out over your own diff — find what's wrong before a reviewer does	diff-grill workflow; code-architect (fallback)
/plan	Draft → adversarial workflow grill → save plan to .claude/plans/<slug>.md (rides with the stack)	plan-grill workflow; plan-architect (fallback)
/rabbit	Run CodeRabbit review on the current branch against main	—
/scan [dir]	Deep bug scan of a folder; appends findings to .claude/potential-bugs.md	deep-bug-scan
/stack	gh-stack wrapper (bare = smart recommendation, args = specific actions)	stack-navigator (no args)
/techdebt	Scan for duplication/dead code; defer/apply/reject per item. Backlog in .claude/techdebt.md	—
/verify	Pre-PR gate: typecheck / lint / test / build. --deep = full install + e2e	build-validator, oncall-guide

Picking among the review commands:

Command	Scope	Timing	Output
/plan	an approach	before code	.claude/plans/
/grill	current diff	pre-PR	ephemeral
/scan	a folder	anytime	potential-bugs.md
/techdebt	whole repo	anytime	techdebt.md
/simplify (built-in)	current diff	pre-PR	inline cleanup

/plan and /grill share the same adversarial fan-out — often used on the same task: /plan to decide how, /grill once it's built. See .claude/README.md for the full workflow patterns.

Skills (.claude/skills/)

Auto-invocable capabilities — Claude fires them on intent match (no /<name>). One subdirectory per skill with a SKILL.md.

Skill	Fires when	What it does
test-locators	Building or editing frontend UI	Adds stable test locators (data-testid/data-test) and a11y handles with business-meaningful kebab-case names, so E2E tests don't go flaky

The skill is the canonical definition — /grill and /plan pull it in as a locators review lens on frontend changes. /dave and CodeRabbit restate the rules inline / in their web config (they run outside Claude Code and can't reach the skill).

Settings (.claude/settings.json)

Pre-allows common safe operations so you see fewer permission prompts:

• Read-only git and gh commands
• gh stack navigation (view, up, down, top, bottom, checkout)
• Package-manager run / install / test for npm, pnpm, yarn, bun (scoped)
• npx tsc, eslint, prettier, vitest, jest (and bunx / yarn equivalents)
• Read / Edit / Write scoped to the current repo (./**)

Denies dangerous defaults: git push --force …, git push -f … (flag-first only), git reset --hard …, git clean -f …, rm -rf / / ~ / $HOME, .env reads and writes, SSH private keys, AWS credentials, sudo.

Note on deny patterns. Mid-pattern wildcards (e.g. git push * --force) are fragile — Anthropic's docs warn they don't survive flag re-ordering, redirects, env-var substitution, or extra whitespace. Deny rules here only catch flag-first orderings. For stronger coverage, add a PreToolUse hook in settings.local.json.

Per-machine overrides go in .claude/settings.local.json (gitignored).

Plugins enabled by default

settings.json enables three plugins from the official marketplace (claude-plugins-official) — no extraKnownMarketplaces needed, it's registered automatically:

Plugin	Why it's a default
superpowers	Skills framework — brainstorming, subagent-driven development, systematic debugging, red/green TDD
typescript-lsp	Adds the LSP tool backed by a TS language server, for the Node/TS stack this repo targets
security-guidance	Surfaces secure-coding guidance during development; additive, no overlap with shipped commands

The set is intentionally small — most other official plugins (code-review, pr-review-toolkit, code-simplifier, commit-commands, feature-dev) duplicate commands this repo already ships.

Trust gate, not silent install. Claude Code shows a "trust this folder?" prompt on a fresh clone; only after you trust do plugins auto-enable. To disable one without forking, set it false in your settings.local.json (e.g. "superpowers@claude-plugins-official": false).

Opt-in, MCP-backed plugins — github, linear, and context7 are not in the baseline (same rule as MCP servers — kept out so consumers choose to wire them up). Copy the entries you want from .claude/settings.plugins.example.json.

Hooks shipped in the baseline

settings.json wires up one hook by default — anything narrower stays in opt-in .example.json files.

Hook	Event	Behavior
format-on-write.sh	PostToolUse (Write|Edit)	Formats the file Claude just wrote, if the nearest package.json declares @biomejs/biome (preferred) or prettier. Uses npx --no-install, so a missing formatter is a silent no-op. Never blocks the tool.

The script self-detects — projects without a declared formatter, files outside the project, and unsupported extensions all no-op cleanly. Disable by removing the hooks block or shadowing it in settings.local.json.

---

Install

Option A — Adopt as user-wide defaults (recommended)

install.sh symlinks each tracked default (agents/, commands/, skills/, hooks/, MEMORY.md, claude-defaults.md) into your real ~/.claude — file-granular, not a whole-dir symlink. Two consequences worth knowing:

• Your ~/.claude keeps owning its runtime state (plugins/, sessions/, history.jsonl, settings.local.json). A whole-dir symlink would either no-op or drag all that state into the repo.
• It's idempotent and self-updating. New tracked defaults are picked up automatically (via git ls-files); anything about to be overwritten is backed up to *.bak.<timestamp>. Whole existing dirs (your personal commands/ / agents/ / skills/) get moved aside — keep those per-project going forward.

settings.json is only linked if you don't have one; if you do, it's left alone and the script prints how to fold in the baseline while keeping machine-specific bits in settings.local.json.

Updates are live — git pull and changes apply on the next session. ./install.sh --uninstall removes only the symlinks it created.

Option B — Per-project

Use this when you want stability per project (frozen defaults that don't track the repo), or for project-specific tweaks. This is a copy, not a link.

For a fresh project (no existing .claude/):

cp -r ~/path/to/autopilot/.claude ~/path/to/your-project/.claude

For a project that already has a .claude/:

rsync -a --exclude='settings.local.json' ~/path/to/autopilot/.claude/ ~/path/to/your-project/.claude/

That single exclusion is enough — .claude/potential-bugs.md, techdebt.md, and plans/ are auto-created in the target on first run and gitignored. CLAUDE.md at the project root is never touched. If you've customised .claude/MEMORY.md, back it up first.

Bootstrap a CLAUDE.md

Run /init — it generates a CLAUDE.md from the codebase. Then append these three sections; /init won't produce them because they're workflow conventions, not codebase facts:

## Working with Claude here

@~/.claude/claude-defaults.md
@~/.claude/MEMORY.md

## Things Claude has learned here

<!-- Add one-liners as you correct Claude, e.g.:
- Never import from `lodash` — we use `remeda`.
- API handlers must call `logger.withContext(req)` before any awaits. -->

## Out of scope / do not touch

<!-- e.g.:
- `generated/` — regenerated from schema, edits will be lost
- `migrations/` — never edit past migrations, always add new -->

Two gotchas:

• On per-project installs (no ~/.claude symlink), swap both imports to @.claude/... and make sure those files exist locally.
• Claude Code shows a one-time approval dialog the first time it sees a new @ import — approve it, or the defaults silently won't load.

Why imports instead of inlining? You edit the rules once in ~/.claude/claude-defaults.md (this repo, via the symlink) and every project picks up the change. Keep your CLAUDE.md + imports around 200 lines total — every line is re-sent every turn.

---

Stacked pull requests (gh-stack)

This repo is built around github/gh-stack, GitHub's official stacked-PR extension.

Install:

gh extension install github/gh-stack

(Requires gh v2.0+ and the feature enabled on your account.)

Typical flow with Claude:

> /stack view                        # where am I?
> /stack add feat/api-endpoints      # next branch on top
> (edit + commit)
> /stack submit                      # push and open/update PRs
> /stack sync                        # after a PR below merges
> /stack merge                       # land the bottom PR

Use the stack-navigator agent when you want a summary plus the recommended next action:

> use stack-navigator to tell me what to do next

Pre-allowed in settings.json: read-only gh stack commands (view, up, down, top, bottom, checkout). Mutating commands (submit, sync, unstack, rebase) still prompt.

Plans ride with the work. /plan saves the refined plan to .claude/plans/<slug>.md (slug = Jira key when detected, else a kebab-case verb-prefixed summary). The file is checked in alongside the related PR(s) and updated in-place as steps land. Delete it once the work merges to main.

---

Memory (mempalace, optional)

If you want local-first session memory, mempalace indexes Claude Code transcripts for semantic + keyword search (offline, no API calls). .claude/settings.mempalace.example.json ships the MCP + hooks shape — copy the blocks into your own settings.json after pip install mempalace && mempalace init ..

---

Opus 4.8

This config targets Opus 4.8 for planning and review, Sonnet 4.6 for implementation.

Key behaviours worth internalizing:

• Default effort is xhigh. Use /model to adjust — high for concurrent sessions, max for gnarly problems only.
• Adaptive thinking. Fixed thinking budgets aren't supported; nudge with "think carefully and step-by-step" or "respond directly."
• Less delegation by default. Tell it explicitly: "Spawn subagents in parallel for each..."
• Fewer tool calls. Tell it explicitly: "Grep thoroughly before answering."
• Front-load the spec. Every turn adds reasoning overhead — state constraints, acceptance criteria, and file locations in turn one.

---

Customizing

• Add a command: drop an .md file in .claude/commands/ — the filename (minus .md) becomes the /command. Use $ARGUMENTS. No frontmatter needed. Don't put a README.md in .claude/commands/ — Claude Code registers every .md there as a command.
• Add an agent: drop an .md file in .claude/agents/ with YAML frontmatter (name, description, optional model, isolation: worktree).
• Adjust permissions: edit .claude/settings.json for team-shared rules, .claude/settings.local.json for this machine only.
• Compounding engineering: when Claude does something wrong, add the rule to your project's CLAUDE.md so it doesn't recur.

Restart after adding commands or agents. Claude Code scans .claude/commands/ and .claude/agents/ at session start — /exit, then claude.

Commands vs skills: this repo uses .claude/commands/ for explicit /name invocations. For auto-invoked capabilities, use .claude/skills/<name>/SKILL.md.

---

Conventions in this repo

• .claude/settings.json — checked in, team-shared permissions baseline
• .claude/settings.local.json — gitignored, per-machine overrides
• .claude/settings.mempalace.example.json — reference only, copy blocks out to opt in
• .claude/settings.plugins.example.json — reference only, opt-in MCP-backed plugins
• .claude/potential-bugs.md, .claude/techdebt.md, .claude/plans/ — gitignored, auto-created on first run
• agentic-project-manager/ — the autopilot's control-panel template (separate subtree, its own installer)
• CLAUDE.md (root) — guidance for editing this config repo itself, not a template

---

License

MIT. See LICENSE.