Reusable agents, skills, standards, rules, and hooks for Claude Code. Drop this into your ~/.claude directory to get an opinionated, productivity-focused setup — from a single edit up to a full Linear-driven, issue-to-merge workflow.
Not an engineer? Linear for stakeholders explains how the agents read your Linear board and how to influence what they work on next — labels, priority, cycles, and how to unblock a parked issue.
Want to set up your own project? Project setup takes a fresh Mac from nothing to a working setup — your GitHub repository, your Linear board, and this toolkit — in seven steps, most of which Claude does for you.
This started as a fix for one problem and grew into an opinionated operating system for agentic development.
The original problem — context rot. LLMs degrade as their context fills with too much information. The fix is agent delegation: specialized agents (developer, debugger, reviewer, researcher) each get their own clean context while you stay the main thread, orchestrating from above. Each agent reports back a tight summary, keeping both the top-level and the agent contexts small and focused. Opus drives orchestration, implementation, and review; Sonnet handles research and writing. Since every current model holds instruction-following steady across a 1M-token window, the routing lever is now mostly effort rather than model tier — see the agent table. For a deeper overview of this pattern, read ClaudeLog: You Are the Main Thread.
What it became. On top of that foundation, this repo is now a complete, mostly self-maintaining toolkit:
- A Linear-native issue lifecycle — plan → start → review → finish → next — driven by slash-command skills that assign issues, cut branches, run an adversarial review-and-fix loop, then mark work Ready For Release.
- Worktree parallelism so multiple issues (and multiple concurrent Claude sessions) run in isolation, with background launchd daemons that reap finished worktrees and drain deferred merges on their own.
- Safety rails and quality gates baked in as hooks — destructive git commands blocked, Biome and markdownlint auto-fixing every edit.
- Codified standards and path-scoped rules so every agent shares the same conventions for git, commenting, problem-solving, and language-specific style.
How we use it below ties these together end to end.
Top-down, in the order the work actually flows: research the idea, turn it into certified Linear issues, then ship the backlog with a fleet. The hands-on tiers below that — targeted /auto, /full, /start//finish — are the same machinery driven one step at a time, for when a single issue needs your judgment mid-flight.
| Step | Command | Notes |
|---|---|---|
| Research | /do research foo bar baz, write your analysis to doc/analysis-foo.md |
Delegates to research agents; lands an analysis doc you can review |
| Plan | Read @doc/analysis-foo.md and create an implementation plan as doc/plan-foo.md |
Use plan mode. Consider workstreams and agent teams unless single-threaded |
| Step | Command | Notes |
|---|---|---|
| Linear setup | Optionally set $LINEAR_TEAM (single key or comma list, e.g. PL,BF) to pin the team scope |
Unset = /next and /spec search every team in the workspace |
| Create issues | /prd @doc/plan-foo.md |
Review stages and accuracy before approving; approval creates the issues in Linear |
| Triage | /triage |
Reviews dependencies, identifies blockers, suggests priorities |
| Prioritize | Move stage 1 to "Planned", stage 2 to "Backlog" | |
| Certify | /spec |
Interviews you, rewrites the issue in the canonical spec shape, and adds the specified label — the certification gate /auto requires. Interactive only; no args surfaces the top uncertified issues, including the Triage inbox |
The primary shipping mode: N parallel autonomous sessions draining the certified backlog as background agents in claude agents, bookended by prep and retro.
| Step | Command | Notes |
|---|---|---|
| Prep | /auto-prep |
Certification honesty audit (the needs decision / solo / human gates), family consolidation, blocks edges between file-colliding issues, and a recommended session count — interactive; run it before every launch |
| Forecast | /fleet-forecast 12 hours |
Optional dry run of the drain — projected pick order as waves, when Planned burns down into Backlog, what the horizon can't reach, and what is stranded behind blockers the fleet can never ship. Read-only; an estimate, never a plan |
| Launch | /fleet-launch 3 10 hours |
Staggered background sessions. Count defaults to prep's persisted recommendation (an explicit count is your quota throttle); the duration winds the fleet down cleanly at the deadline |
| Watch | /fleet-status |
One screen, any time, read-only: time remaining, per-session shipped/failed ledgers with liveness, in-flight issues, merges cross-checked against git, remaining runway |
| End early | /fleet-stop |
Rationing quota or done for the day — ends the timer; in-flight issues finish; nothing is killed |
| Post-mortem | /fleet-retro |
Where the capacity went, what the run filed, what to fix before the next launch — its findings feed the next /auto-prep |
Top-ups compose (/fleet-launch 2 <remaining> adds two sessions) — but every launch resets the shared deadline, so re-pass the remaining duration. What keeps N sessions honest is the label contract (standards/issue-spec.md) plus worktree isolation and the serialized merge — see Parallel safety.
Every tier runs the same pipeline (/start → /quality-review → /finish); each step down trades autonomy for control.
| Tier | Command | You decide | It decides |
|---|---|---|---|
| One autonomous session | /loop /auto |
when to stop | everything else |
| Targeted auto | /auto BF-123 |
the issue | plan, review, merge — fully unattended |
| End-to-end, attended | /full wt BF-123 |
the issue, plan approval, the deferred-items call | implementation and review flow |
| Two-command loop | /start wt BF-123 … /finish |
everything above, plus when to finish | review still runs inside /start |
| Human in a worktree | /start interactive BF-123 |
all of it — claims the issue, sets up the isolated worktree, hands off | nothing |
The wt token is what makes fan-out safe — it is how every fleet session runs, and the same mechanics protect a hand-driven fan-out:
agent 1: /full wt PL-1
agent 2: /full wt PL-2
agent 3: /full wt PL-3
Each runs end to end independently, and the machinery keeps them from colliding:
- Isolation by worktree.
/start wtchecks out the issue's branch in its own git worktree under<repo>/.claude/worktrees/<issue>, so every agent gets a private working tree and branch — edits, installs, and checkpoints never step on each other or on your main checkout. - Serialized merge. When each
/finishlands, it advances the shared source branch under a per-repo lock (scripts/with-repo-lock.py): the worktree branch is first brought up to source's tip inside its own worktree (any conflicts resolved there, never in the main checkout), then source moves by a cleangit merge --ff-onlyor an atomicgit update-ref. Concurrent finishes block briefly and merge in turn, so source is only ever advanced cleanly. - Deferred, never forced. A merge that can't advance right now — e.g. the main checkout is sitting on the shared branch with another session's WIP — is enqueued rather than failed: it leaves the worktree intact and a launchd drainer retries every ~15 min until it lands. Inspect with
/merge-queue; conflicts are never resolved unattended. - Self-cleanup. Finished worktrees are reclaimed by the hourly reaper — check with
/reap-worktrees. - Human alongside.
/start interactive PL-4claims an issue and sets up its worktree (opened in its own VS Code window), then hands off without planning or implementing — so you can work by hand in the same isolation while background agents keep shipping.
For heavy fan-out, keep your main checkout parked on a quiet branch (not the shared integration branch) so every merge advances source by a ref-only update and the queue rarely engages. The full merge protocol lives in standards/git.md.
Reach for these as needed — between loop steps or on their own:
| Skill | When |
|---|---|
/checkpoint |
Mid-task — commits WIP and posts a progress update to Linear |
/quality-review |
On demand — adversarial review + triage/fix loop until convergence (also auto-runs inside /start) |
/next |
Starting a day or week — suggests the best next issue to pick up |
/update |
Start of day, and first thing to try when a tool is missing or a skill behaves like an older version — pulls the latest project code and ~/.claude, then re-runs the setup script |
/auto is the engine every fleet session runs — the pick-and-ship loop with the human taken out, or in targeted mode out of everything but the pick — and /loop is what keeps it running unattended. /fleet-launch dispatches N of these as background agents; this section is the single-session mechanics reference.
/autoships exactly one Linear issue per invocation, end to end: finish any in-flight work, pick the best unblocked issue via/next specified(certified issues only), ship it via/full auto wt, record the outcome. Worktree mode is always on (so successive issues chain without stacking branches), and every underlyingautodefault chooses abort/preserve over guess — the worst acceptable outcome is "nothing happened and Linear says why," never "something wrong shipped." Invoking/autois the run-scoped grant for the commits and pushes it makes (see standards/git.md)./auto BF-123is targeted mode — same run, your pick. It skips the/nextpick and ships exactly that issue: still certified-only (the issue must carry thespecifiedlabel —/specit first if not, or drop to/full wt BF-123for an interactive run), still always-worktree, still the full unattended gauntlet (plan composed and posted to Linear with no approval pause, adversarial review, finish/merge, a Linear comment on failure). One-shot by nature — run it directly, not under/loop. This is the middle ground between driving/full wtby hand and letting the loop choose./loop /autois the way you actually run it./loopsupplies the recurrence — its wakeup machinery re-invokes/autofor the next issue — while each/autocall stays a single, self-contained iteration. (Deliberately: in-prose "keep going" scaffolding is the documented failure mode of autonomous macros, so/autoleans on/loop's reliable recurrence instead of inventing its own.) Iterations run back-to-back:/autoschedules its next wakeup at the 60s minimum, because the backlog is the work queue and there is nothing external to wait on —/loop's 20–30 minute idle-tick default is for polling loops and would otherwise idle away hours between ships.
Launch it with --model opus[1m] --effort xhigh. Not opusplan — that means "Opus in plan mode, Sonnet otherwise", and /start auto skips plan mode entirely, so an opusplan run executes end-to-end on Sonnet. [1m] because context accumulates across iterations.
Point it at a seeded, certified (via /prd or /spec) backlog and walk away. It works the queue one issue at a time and ends itself — no runaway loop:
NO-CANDIDATES— the backlog has no more certified, workable issues. Certify more via/spec(or seed via/prd), delete the run'stmp/auto-state-<runKey>.json, and re-invoke.AUTO-HALTED— the circuit breaker tripped (two consecutive failures, likely systemic) or an environment halt (e.g. a dirty tree it can't attribute). Each failing issue gets a Linear comment explaining why before the loop stops.
/loop /auto never clears or compacts the session — the harness's automatic summarization keeps context in check as it grows (/compact and /clear are user commands the loop must never invoke). Because summarization can drop detail, the run's actual memory lives in tmp/auto-state-<runKey>.json (shipped / skipped / failed lists + the failure counter, keyed by the session's own id), not the conversation — so the run survives summarization across iterations, and the terminal halt stays sticky even under a fixed-interval /loop 15m /auto. A human starts a fresh run by deleting that file — or simply by starting a new session, whose fresh PID names a fresh file.
Parallel and stoppable. Several /loop /auto sessions can drain the same repo concurrently: Linear claims keep their picks disjoint, every worktree is stamped with its owning session's identity (session id + harness PID — id-first, so claude agents fleets that share one root process still resolve correctly) so a live sibling's in-flight issue is never mistaken for an orphaned dead run (only a provably dead owner gets resumed), run state is per-session, and the per-repo lock serializes every git mutation. Stopping is scoped, too — telling a session "don't run another loop" ends the recurrence, while the in-flight issue still completes normally; parking work mid-issue takes explicit words.
/loop /auto ── the autonomous driver: re-invokes /auto each iteration
│
▼
┌─────────────────────── one iteration = one issue ───────────────────────┐
│ │
│ 0 re-anchor + read tmp/auto-state-<runKey>.json (cross-iteration memory) │
│ 1 preflight ......... finish any in-flight work / resume orphaned wt │
│ 2 /next specified ... rank certified, unblocked candidates, take top one │
│ 3 /full auto wt <ISSUE> │
│ ├─ /start auto ........... branch · plan → Linear · implement │
│ ├─ /quality-review auto .. adversarial review + fix loop │
│ └─ /finish auto .......... commit · push · merge · Ready For Release │
│ 4 record outcome → tmp/auto-state-<runKey>.json, emit one lifecycle tag │
│ │
└──────────────────────────────────────┬──────────────────────────────────────┘
│
AUTO-CONTINUE ─────────────┤ shipped / skipped / recorded-failure
▼ → /loop wakes the next iteration
─────────────────────────────────────────────────────────────────
NO-CANDIDATES (backlog drained of certified issues) ─┐
AUTO-HALTED (2 consecutive fails / env) ─┴─► loop stops, awaits a human
/auto accepts two optional tokens: pr opens a PR per issue instead of merging (use only when the queued issues are independent, since the source branch won't advance until PRs land), and a team scope (BF, or a comma list PL,BF) restricts the run to those teams' certified backlogs.
Specialized personas the main thread delegates to — directly, or through skills like /do, /start, and /quality-review.
| Agent | Role | Model |
|---|---|---|
| architect | Solution design, ADRs, technical recommendations | Opus · max |
| developer | Code implementation from specifications | Opus · high |
| debugger | Root cause analysis through systematic evidence gathering | Opus · xhigh |
| quality-reviewer | Adversarial review — edge cases, contract violations, security | Opus · xhigh |
| quality-verifier | Verification pass over a fix delta, and the simple tier's scoped review |
Sonnet · high |
| research-lead | Multi-perspective research and synthesis | Sonnet · high |
| technical-writer | Concise documentation for completed features | Sonnet · low |
Every agent pins both keys, so none inherits the session default. max is reserved for architect,
which only runs as /quality-review's escalation path; xhigh is the working default for coding and
review. Effort is the primary cost lever — step developer down to sonnet · xhigh if the spend
outweighs the completeness gain.
Automated multi-step workflows invoked by trigger phrases or slash commands.
Linear Integration: (see CLI)
In workflow order — seed, certify, fleet, then the per-issue tiers and upkeep:
| Skill | Description |
|---|---|
| linear | linear-cli quick-reference — the gotchas (anchored comments, dependency graph, parent-linked create) + helper scripts |
| prd | Create agent-friendly tickets with PRDs and success criteria |
| spec | Groom and certify an issue into a specified spec — the certification gate /auto requires |
| triage | Analyze backlog for staleness, blockers, and priority suggestions |
| next | Suggest best next issue using cycle, dependency, and triage signals |
| auto-prep | Fleet prep — certification honesty audit (needs decision / solo / human), family consolidation, collision blocks edges, recommended session count |
| fleet-forecast | Read-only projection of what a fleet would ship over a horizon — pick order as waves, the Planned→Backlog crossover, stranded candidates |
| fleet-launch | Launch N parallel /loop /auto background sessions, staggered and deadline-bounded |
| fleet-stop | Wind a running fleet down early — in-flight issues finish, no new picks; nothing is killed |
| fleet-status | Read-only mid-run readout — time remaining, per-session ledgers with liveness, in-flight issues, merges cross-checked against git, runway |
| fleet-retro | Post-mortem a finished fleet — capacity metrics, filed-issue audit, state reconciliation; feeds the next prep |
| auto | Autonomous backlog iteration — ships one issue per invocation; run continuously as /loop /auto (see Autonomous) |
| full | End-to-end macro: /start → /quality-review → /finish, gated on verdict |
| start | Start a Linear issue — check blockers, assign, create branch, plan, execute, auto-review |
| checkpoint | Save progress — commit WIP and post progress update to Linear |
| quality-review | Adversarial review + triage/fix loop until convergence (gates pnpm check); the simple label or token runs a lighter verifier-only tier that escalates fail-closed |
| finish | Finish an issue — read verdict, commit/push, mark Ready For Release |
| merge-queue | Inspect and drain /finish merges that were deferred, then retried by the launchd drainer |
| reap-worktrees | Inspect and reclaim leftover /start wt worktrees (PR/branch merged, or issue Done/Canceled) |
| reflect | Turn session friction into shared-config edits — auto-applies the safe ones, files the rest as Linear issues (scheduled surface is /fleet-retro's batched reflect fleet step; sweep mode audits a project's config against its codebase) |
| keeper | Interactive pickup for the config work autonomous runs cannot ship — uncommitted ~/.claude edits, keeper-labeled issues, and contributor proposal PRs, adjudicated in one pass |
Development skills:
| Skill | Description |
|---|---|
| update | Bring the machine current — pull the latest project code and ~/.claude, then run the update script (the project's .claude/update.sh, or ~/.claude/update.sh) |
| pr-update | Generate PR titles and descriptions from actual code changes |
| dependency-updater | Orchestrate dependency updates with research and validation |
| deprecation-handler | Migrate deprecated APIs with safe patterns |
| semver-advisor | Classify version changes as MAJOR/MINOR/PATCH |
| react-component-generator | Generate React components following project conventions |
| standardize-tooling | Converge a TypeScript project onto house tooling — pnpm 11, Biome, tsdown, the standardized check suite; adaptive and idempotent |
External Skills (installed by update.sh):
| Skill | Source | Description |
|---|---|---|
| agent-browser | vercel-labs/agent-browser | Browser automation for AI agents |
| skill-creator | vercel-labs/agent-browser | Guide for creating new skills |
| vercel-react-best-practices | vercel-labs/agent-skills | React/Next.js performance optimization |
| vercel-composition-patterns | vercel-labs/agent-skills | React composition patterns that scale |
Universal rules governing agent behavior. standards/README.md is the index and owns the per-standard summaries.
Path-specific conventions applied automatically when editing matching files.
| Rule | Applies To |
|---|---|
| comments | all files (**/*) — default to no comments; size to the reader; no provenance decoration |
| typescript | **/*.ts, **/*.tsx |
| react | **/*.tsx, **/*.jsx |
| markdown | **/*.md, **/*.mdx |
| package-manager | **/package.json, lockfiles |
| env-vars | **/*.ts, **/*.tsx, **/*.mts — required-env-var handling; assertEnvVariable, no silent defaults |
| biome | **/*.ts, **/*.tsx, **/*.js, **/*.jsx, **/*.mjs, **/*.cjs, **/*.json, **/*.jsonc — Biome projects only, self-nullifies elsewhere |
Automatic quality checks that run without manual invocation.
| Hook | Trigger | What It Does |
|---|---|---|
| git-permissions | Before git commands | Blocks destructive operations (reset --hard/--mixed, restore/checkout <file>, clean -f, --force) |
| scratch-path-guard | Before bash commands | Denies scratch writes to bare root paths and system /tmp (session scratchpads exempt), steering to project-relative tmp/ — the model self-corrects instead of stalling an autonomous run on a dangerous-path prompt |
| full-continue | On stop | Keeps /full going: re-dispatches /finish if the macro stalls after READY-FOR-FINISH |
| auto-heartbeat | On stop | Keeps a self-paced /loop /auto alive — blocks a turn that ended without arming the next wakeup, which otherwise kills the loop silently |
| no-blind-sleep | Before bash commands | Refuses a sleep wait that cannot end early; marker-polling loops with an exit condition still run |
| linear-create-state-guard | Before bash commands | Refuses a raw linear-cli issues create with no --state — it would land in the team default (Triage) and be invisible to /next and /auto forever |
| auto-deadline-gate | Before bash commands | Refuses a new /auto pick once the fleet deadline has passed, so a wind-down actually returns the machine |
| finish-flow-guard | Before bash commands | Refuses PR mode in an unattended run whose invocation carried no pr token — in PR mode source never advances and blocks edges never release |
Local launchd agents installed by update.sh (macOS only) that keep the worktree and merge machinery tidy without any manual step.
| Daemon | Cadence | What It Does |
|---|---|---|
| merge-queue-drain | Every 15 min | Lands /finish merges that were deferred — e.g. main was busy with another session's WIP |
| worktree-reap | Hourly | Reclaims completed or abandoned /start wt worktrees |
| auto-stall-watch | Every 10 min | Surfaces a /loop /auto background session gone silent mid-iteration — the one silent-death shape no Stop hook can catch, since an API-killed turn fires none |
| Command | Description |
|---|---|
| /do | Plan execution — breaks work into phases, delegates to specialized agents, validates each step |
curl -fsSL https://claude.ai/install.sh | bashAssuming you already have a ~/.claude directory from using Claude Code, add this repo:
cd ~/.claude
git init
git remote add origin https://github.com/alienfast/claude.git
git fetch
git checkout -b main origin/main
git pullNote: This supplements your user directory with reusable configurations — it does not overwrite personal settings or data. Always check before committing to ensure no local user data is included, and adjust
.gitignoreaccordingly.
Prerequisites: Homebrew, Node, pnpm, git, and Claude Code must already be installed — the script bootstraps everything else and fails fast if Homebrew is missing.
~/.claude/update.shFrom then on, /update is the skill that does this — it pulls the latest project code and ~/.claude first, then runs the script.
This installs:
- The TypeScript LSP plugin
ghandjqvia Homebrew (installed or upgraded), then runsgh auth loginif you aren't already authenticated- Vercel agent-browser and skill-creator
- Vercel React best practices and composition patterns
npm-check-updates(ncu) as a pnpm global — required by the dependency-updater skill- Linear CLI via cargo (Finesssee — the Linear skills already ship with this repo), authenticating it if needed
- launchd background daemons on macOS — the merge-queue drainer and worktree reaper
- Runs markdown linting
See mcpServers.md for some available MCP server configurations. The current approach favors skills over MCP servers for context efficiency — most MCP servers have been removed in favor of CLI tools and skills.
Primary entry point for complex, multi-step work:
/do I want to update Traefik. Search traefik documents, compare the version
we are currently on, and what we might need to change to be up to date.
Implement the changes.
/do this code was originally written for react 16. While some files have been
updated for react 19, I want you to take a look at a comprehensive review of
all react code, and implement the best practices for react 19.
No manual intervention needed — hooks run behind the scenes:
- Destructive git commands are blocked before execution (
reset,restore/checkout <file>,clean -f,--force) - Scratch writes to bare root paths or system
/tmpare denied with redirect-to-tmp/guidance - Biome and markdownlint run after every file edit
- On stop,
full-continuekeeps/fullgoing — re-dispatching/finishif the macro stalls afterREADY-FOR-FINISH
Create a directory in skills/ with a SKILL.md containing YAML frontmatter. See skills/README.md for the full guide.
Add a markdown file to standards/. It will be referenced by agents automatically. See standards/README.md.
Add a markdown file to rules/ and register the glob pattern in CLAUDE.md under "Path-Specific Rules."
Scope the paths: glob to where the rule's principle actually applies: use **/* (plus **/.* and **/.*/** to also cover dotfiles and dot-directories like .github/) when the rule is language-agnostic — e.g. comments — and reserve a curated extension list for genuinely language-specific rules. A curated list silently exempts every file type it omits, and the gap stays invisible until a violation slips through an unlisted type (this is how the comment rule once missed a Dockerfile).