Repository Coding Agent Instructions

This repository is a public playbook of Claude Code global instructions, skills with their packaged reference documents, and custom subagent definitions. It is almost entirely Markdown, plus a standard-library Python installer with two thin launchers, a few standard-library Python helper scripts inside skill packages, and a small amount of YAML frontmatter. It is for Claude Code only.

Follow the host's instruction hierarchy first. Within the same authority level, the repository-specific guidance here applies where it is more specific than the global instructions.

What This Repository Is For

• Keep the playbook useful across many teams and codebases.
• Keep global guidance tool-agnostic and durable.
• Keep repository-specific, machine-specific, and workflow-specific detail out of global instructions.
• Prefer concise, practical guidance over theory — but do not sacrifice necessary detail for brevity. These files are read by agents that need the specifics.
• Keep the root session accountable for framing, delegation, coordination, integration, validation, and the final report.
• Keep the subagent lineup at local-orchestrator, read-only-explorer, senior-reviewer, docs-researcher, test-triager, and isolated-worker.
• Keep the branch, worktree, session, and dependency lifecycles separate. feature-branch-lifecycle owns branch topology, promotion, and temporary-branch cleanup; worktree-lifecycle owns checkouts; multi-session-coordination owns concurrent ownership; task-graph-orchestration owns dependencies between work outcomes. A branch is not a worktree, a branch is not a session, and a feature integration branch is not automatically a graph node. session-cleanup owns the end-of-work integrity pass over the work delta and routes branch deletion and worktree removal to those skills rather than doing either itself; handoff prepares a fresh continuation, starts one itself only when the user asks, and changes nothing else.
• Keep the operating model direct-first: the root session implements by default, including substantial multi-file work; subagents are used sparingly — only when a bounded assignment's concrete benefit outweighs its context, coordination, latency, and review cost, or independent assistance is required — bounded, flat by default, and never mandatory; skills and dependency-graph planning apply whether one agent or several do the work. Do not reintroduce a rule that requires a helper on every task, a direct-execution exception statement, one helper per graph node, or a required sequence of planner, implementer, reviewer, tester, and documentation passes.
• Keep each agent definition usable two ways: as a Role perspective the root applies directly (which changes nothing about the root's model, effort, permissions, or ownership, and is self-review, not independent verification) and as a bounded assignment for an actual subagent, whose Delegated use rules apply only when it runs as one. Keep the two separated in the file, with an Applying this perspective directly section between them.
• Keep the engineering standard: understand the whole affected flow before choosing a fix; improve the existing implementation by default and replace a substantial part only on evidence of a significant benefit that justifies migration, verification, and maintenance costs; treat unnecessary abstractions, speculative compatibility, and redundant tests as maintainability defects; and never invent a support commitment for hypothetical users, obsolete test accounts, fixtures, or earlier implementations. Do not introduce numerical quality thresholds or scores.
• Keep the testing standard end-to-end: behavioral tests retained by new work drive complete supported UI, API, or CLI flows and cover important business rules, realistic regressions, meaningful failures, and boundaries; every newly created unit test is temporary and is removed, with its exclusive support code, once passing E2E coverage carries its still-required assertions; existing required suites and repository gates are preserved, and existing non-E2E tests migrate only within authorized scope after replacement coverage passes; builds, lint, type checks, and static validation stay valid evidence for what they check. Do not reintroduce an endorsement of permanent unit tests or isolated integration suites as lasting coverage.
• Keep the runtime-resource rules: recover and reuse the established environment in dependency order before creating another, at most two recovery cycles unless a project runbook sets another finite limit, one browser-test worker when safe capacity is unverified or heavy jobs overlap, and teardown limited to task-owned resources. Local preflight produces local evidence only: local-ci-preflight and aws-local-preflight grant no authority to call AWS or other cloud services, start shared services, deploy, or dispatch remote CI.
• Link third-party skills and plugins to their official Claude distribution instead of vendoring copies. Each one — Impeccable, Taste, Humanizer, and the separately maintained Intuitive Software Design — is a companion that users install from its own Claude Code plugin marketplace or from the Anthropic Directory. Because the playbook ships none of them, every install path says they need to be downloaded separately: the install prompts in README.md and INSTALL.md, INSTALL.md's agent steps, and the installer's closing message. Install instructions always take a companion's latest version — the current release on a first install, and an update on every playbook install or update — so never pin or record a companion version number. INSTALL.md documents each companion and THIRD_PARTY.md credits it. State availability only as far as it was verified, with the date it was checked.
• Keep every skill self-contained: a skill's SKILL.md and every reference or template it depends on live under that skill's directory and install together, and a path written inside a skill resolves against the skill's package root. There is no top-level references/ directory. A cross-skill need is met by naming the owning skill, never by reaching into its files or keeping a second copy.

Facts About Claude Code That This Playbook Depends On

These are load-bearing. If you change guidance that touches them, verify against the current Claude Code documentation first — an earlier version of this playbook had the nesting rule backwards, and it propagated to eleven files.

• Subagent frontmatter supports name, description, tools, disallowedTools, model, permissionMode, effort, isolation, and others. All of the fields used here are documented.
• Model precedence (Claude Code v2.1.251 and later): per-invocation model > frontmatter model (including inherit) > CLAUDE_CODE_SUBAGENT_MODEL > the main conversation's model. CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 reverses this — it ignores every definition's model and blocks the per-call parameter — and an organization availableModels allowlist can substitute. Before v2.1.251 the environment variable came first; do not reintroduce that ordering.
• A helper's model is chosen for its work, within approved routes, independent of the main session's model, nesting depth, retries, and replacements: haiku for narrow lookup, extraction, file mapping, and log summaries; opus at the definition's effort: medium for implementation, diagnosis, planning, and review; the root itself, on the user's model, for the hardest architecture and cross-system reasoning. Each definition declares the default for its typical work — read-only-explorer and docs-researcher on haiku with no effort field (Haiku does not support effort), and senior-reviewer, test-triager, isolated-worker, and local-orchestrator on opus at effort: medium — and the per-call model selects the actual route. Judgment work never goes to Haiku. sonnet and fable are not helper routes; high, xhigh, and max on a helper are deliberately not used because they remove the per-turn thinking ceiling and consume usage quickly on work the root verifies anyway; fast mode is a main-session setting the user controls. The main session's model, effort, and speed are never changed from inside a task. Do not reintroduce a "child at or below the main session's tier" rule, a fixed route that ignores the work, or effort-specific copies of the roles.
• There is no per-invocation effort parameter on the Agent call. A definition's effort is the only way to set a subagent's effort; a definition that omits it inherits the session level. This is why effort belongs to the role while the model is chosen per dispatch, and why there is one definition per role rather than copies per effort level. The effortLevel settings key accepts low through xhigh but not max. medium is the documented default effort for Opus 5.5, which Anthropic reports matches or exceeds Opus 5 at high there.
• Nesting is enabled by default, up to three layers below the main conversation. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=2 tightens that to two; 1 turns nesting off. It is not a switch that enables nesting, and it must never be documented as a precondition for delegation.
• What actually prevents a spawn is omitting Agent from tools and listing it in disallowedTools. Prompt text does not.
• Subagents invoke skills only through the Skill tool. A tools allowlist that omits Skill — as every bundled role's does — means the subagent cannot invoke a skill; the caller names each applicable skill and its entrypoint path in the assignment and the helper reads it. The skills frontmatter field preloads skill content at startup and is not used here because the applicable set is chosen per task.
• effort overrides the session effort level. It is a property of the role, not a ceiling inherited from the caller. Do not reintroduce a rule that a child's effort must be at or below the caller's session effort — it would make a role's pinned effort unreachable from a session running below it, and it misreads the field.
• Plan mode gates shell commands. Commands outside the built-in read-only set are classifier-reviewed or prompt for approval, so a plan-mode subagent cannot reliably run tests, linters, type checkers, or builds. Suite execution belongs to test-triager (default mode), not senior-reviewer (plan mode).
• isolation: worktree branches from the repository default branch, not the parent session's HEAD, unless worktree.baseRef is "head". This is why isolation is root-authorized with the base ref recorded.
• Agent teams are experimental and off by default (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 enables them). While on, a named subagent spawn in an interactive session becomes a teammate that runs in the main session's working directory and inherits the lead's effort rather than the definition's; frontmatter isolation does not prevent it.
• Background subagents keep only a subset of built-in tools, so one definition can resolve to different tools in the foreground and the background.
• Session actions, which the handoff skill depends on. claude "<prompt>" starts an interactive session with that first prompt, -n names it, and /clear starts a new conversation with an empty context while the previous one stays resumable. --continue, --resume, and /resume reopen a conversation with its history; /branch, --fork-session, and /fork copy that history. claude -p runs headless and exits. claude --bg starts a background session (agent view, a research preview) that moves into its own worktree under .claude/worktrees/ before it edits — branched from the default branch unless worktree.baseRef is "head" — and commits and pushes its changes unless the task, CLAUDE.md, or memory says the user handles git. It takes the prompt as the positional argument and --name for its title, and prints the session ID that claude logs <id> (recent output) and claude attach <id> (open it in a terminal) take; claude agents --json lists active sessions. Claude Code documents no tool for the model to open a new interactive session. Checked against the Claude Code 2.1.263 documentation and claude --help.
• Skill loading. When a skill is invoked, Claude Code loads its SKILL.md and states the skill's base directory, so a skill's instructions can address its bundled references/, scripts/, and assets/ files relative to that directory. Packages that ship helper scripts or templates depend on this. Observed on 2.1.281.
• Plugin marketplaces, which the companion-plugin guidance depends on. claude plugin marketplace add <source> adds a marketplace from a URL, a path, or a GitHub repository; claude plugin install <plugin>@<marketplace> installs from it; claude plugin list shows what is installed; claude plugin marketplace update [name] refreshes a configured marketplace from its source, every marketplace when no name is given; and claude plugin update <plugin>@<marketplace> updates an installed plugin to its latest version, which applies after a restart. Checked against claude plugin --help on 2.1.281. Anthropic's claude-plugins-official marketplace and the Anthropic Directory, the plugin catalog in Claude, are separate listings: a plugin can appear in one but not the other, as Intuitive Software Design did when checked on 2026-11-03.

Content Rules

• No sensitive access material, private local paths, internal-only URLs, session transcripts, or long incident logs.
• No hardcoded project names, organization workflows, or local machine quirks in global guidance.
• No instructions tied to a specific issue tracker, review tool, package manager, shell, or hosting provider unless the file is explicitly an example or template.
• Use Claude Code terminology in Claude-specific files: CLAUDE.md, the resolved Claude Code home, Markdown agent definitions with YAML frontmatter, model aliases, effort levels, permission modes, real tool names, and real session commands.
• This repository is Claude Code only. Never add another coding-agent environment's configuration paths, file names, agent formats, model identifiers, command vocabulary, metadata files, or links to editions for other environments. scripts/validate.sh rejects the known ones, so its own deny-list is the one place those names appear. The one exception is the README banner image, assets/coding-agent-playbook-claude-code-hero.png, which is kept by maintainer decision: its panel that points to the playbook's other edition is intentional, and a replacement banner keeps that panel. Do not remove or edit the banner unless the maintainer asks.
• Prefer "safety", "access control", and "sensitive access material" over product-specific security terminology.
• Keep templates reusable and clearly marked as templates.

Writing Style for Agent-Facing Files

The agents/, skills/ (including each skill's packaged references and templates), and custom-instructions/ files are read by models, and how they are written changes how well they are followed.

• Put a rule where its actor can act on it. Routing rules belong in the caller's documentation, not duplicated into every leaf agent's system prompt — a leaf cannot choose its own model.
• Lead with the decision, then the rule, then the exception.
• Prefer concrete examples over abstract constraint lists. One worked assignment teaches more than twenty required fields.
• Explain the mechanism when it changes behavior. "Plan mode cannot run your test suite" is followed; "respect permission boundaries" is not.
• Use tables for lookups and numbered steps for procedures.
• State positive defaults, then a bounded list of what not to do.
• Avoid invented vocabulary. Say what Claude Code says: subagent, Agent tool, subagent_type, model, effort, permissionMode, tools, disallowedTools, nesting depth, plan mode.
• Do not compress away necessary detail. These files are reference material; length is fine when every paragraph earns its place.
• Write with STE-inspired clarity: one main instruction per sentence, active voice, explicit actors, consistent terms, and conditions placed before the actions they control. Keep every consequential qualifier — "only", "before", "unless", approval and verification requirements — and keep exact commands, paths, schemas, and values. This is an authoring approach, not a claim of ASD-STE100 compliance, and it imposes no restricted dictionary or sentence-length limit on technical content.

Validation

Run the full check suite locally before finalizing meaningful changes:

bash scripts/validate.sh

CI runs exactly this script (.github/workflows/validate.yml), plus a PowerShell job that parses install.ps1 and runs the launcher end to end, including a dry run.

Automated checks (CI enforces all of these):

• Every SKILL.md has YAML frontmatter with name and description, and its name matches its directory. Every directory under skills/ has a SKILL.md, and no file sits loose directly under skills/.
• Skill packages are discovered from the tree by both the installer and the validator, so adding one requires no change to either. Do not reintroduce a hardcoded skill list.
• Every agents/*.md has name, description, model, permissionMode, tools, and disallowedTools, declares an approved default route (haiku with no effort on read-only-explorer and docs-researcher; opus with effort: medium on the other four), and carries the ## Role perspective, ## Applying this perspective directly, and ## Delegated use headings. Both validators check only the six playbook-managed definitions by name, so a user's own agents are never judged against this policy.
• read-only-explorer, docs-researcher, and senior-reviewer use permissionMode: plan and list neither Edit nor Write.
• test-triager, isolated-worker, and local-orchestrator use permissionMode: default.
• Only agents/local-orchestrator.md lists Agent in tools; the other five list Agent in disallowedTools.
• No bundled agent sets isolation: worktree.
• Fenced code blocks are balanced; every repository path referenced in Markdown exists; every references/, scripts/, or assets/ path written inside a skill — bare or as <skill-base-dir>/... (or <skill-dir>/...) — resolves inside that skill's package, which is the same rule install.py enforces before it writes anything; a project's own path inside a skill is written with a leading ./ so neither check treats it as a package resource; no Markdown outside skills/ refers to a top-level references/ path; no repository text file of any type carries the names, configuration paths, model names, or commands of another coding-agent environment; no skill package ships another environment's per-skill metadata file; and no skill package ships a LICENSE or NOTICE file at any depth, because third-party skills are linked as companions rather than vendored.
• The installer's post-install check reads only the Markdown the release ships, so a user's own files in an adopted skill directory never fail an install.
• The validator reads tracked files plus new files that are not ignored, so on a clean CI checkout it sees exactly the committed tree, and locally it checks a new package before its first commit.
• install/install.py passes a real full-mode install into a temporary home (including a body containing backslashes) in which every packaged skill file is installed byte-identically, a repeat install that changes nothing and writes no backups, a dry run that creates nothing and uses "Would ..." wording, a support-only install that preserves and backs up existing CLAUDE.md content, a legacy-reference migration that retires an unchanged file and preserves a customized one, and exits non-zero when a managed file is missing.
• install.sh and install.ps1 are thin launchers for install.py and, with pwsh available, produce a byte-identical Claude Code home in both modes. The former duplicated Bash and PowerShell implementations drifted more than once — a trailing-newline difference and a case-insensitive manifest sort made each rewrite the other's files — so do not reintroduce a second implementation.
• install.sh passes bash -n, install.py compiles, and the pointer block in claude-prompts/setup-global-claude-support-system.md is identical to install/support-only-pointer.md.

Manual review:

• Guidance touching any item in Facts About Claude Code matches current documentation.
• README.md's repository-structure block matches the actual tree.
• Design-principle wording in custom-instructions/, agents/, and skills/ stays consistent with skills/reference-doc-routing/references/engineering-design.md: whole affected flow understood first, smallest complete solution, improve before replace (a substantial replacement needs evidence of a significant benefit, never a numerical score), earned abstractions rather than a blanket ban on single-use ones, root-cause fixes within scope, and material technical debt recorded with scope, rationale, and follow-up condition.
• Testing wording retains only E2E behavioral tests for new work, through complete supported UI, API, or CLI flows; treats every newly created unit test as temporary, removed with its exclusive support code only after passing E2E coverage carries its still-required assertions; preserves existing required suites, repository gates, and required assertions; keeps existing non-E2E migration within authorized scope; keeps builds, lint, type checks, and static validation as valid evidence; and never treats a mocked, partial, or relabeled check as E2E proof. Check the global instructions, the testing and repository templates, the six agents, senior-code-review, session-cleanup, feature-branch-lifecycle, multi-session-coordination, legacy-path-retirement, and the support-only pointer together.
• Runtime guidance recovers the established environment in dependency order before creating another, bounds recovery at two cycles unless a runbook sets another finite limit, starts browser tests with one worker when safe capacity is unverified or heavy jobs overlap, and tears down only task-owned resources. The local-preflight skills keep local evidence separate from remote acceptance, report unconfigured or skipped required checks as gaps rather than passes, and grant no authority to call AWS, start shared services, deploy, or dispatch remote CI.
• No third-party skill is vendored. Each companion links to its official Claude distribution, has a THIRD_PARTY.md row with source and license, states availability and install commands only as far as they were verified, with the date, and pins no version. Every install path tells users to download the companions and to install or update them to their latest versions.
• Install docs and scripts reference the current file set.
• No file reintroduces mandatory delegation, a direct-execution exception statement, one helper per graph node, graph use that requires delegation, a required role sequence, a claim that applying a role's perspective yourself satisfies an independent-verification gate, or permission to skip a matching skill for direct or familiar work.
• Design guidance asks for existing components, dialogs, hooks, validators, utilities, and interaction patterns to be reused, composed, or extended before new code is written, and justifies shared code by a current need, a real boundary or invariant, an established convention, or meaningful duplication removed — never by hypothetical reuse.
• Legacy-path guidance keeps or adds a compatibility path only for a demonstrated current dependency or an explicit retention requirement, treats a search that finds nothing as an evidence gap rather than proof of non-use, treats hypothetical users, obsolete test accounts, fixtures, and earlier implementations as no support commitment, decides data retention separately from code retirement, and carries correctness safeguards into the authoritative path.
• Handoff guidance names only session actions Claude Code supports, never offers a resume, branch, fork, or cross-session message as a fresh continuation, and gates a background continuation on the user's request and on its worktree and git behavior.
• Session-cleanup guidance derives the work delta from the repository against a verified baseline, preserves unrelated work, requires evidence for compatibility code, and never deletes branches or worktrees itself.
• Branch guidance keeps the detailed procedure in skills/feature-branch-lifecycle/references/branching-rule.md rather than the global instructions, detects real branch names instead of assuming main or staging, never invents a missing long-lived branch, never lets a development branch bypass the feature integration branch, requires complete-feature validation before promotion, gates every temporary-branch deletion on verified evidence and explicit authority, preserves and reports a branch whose gates fail, and never deletes a permanent branch.
• The installer defaults to full mode, maintains the managed-file manifest, retires only unchanged formerly managed files (including loose references/ files left by earlier releases), writes backups outside the managed trees, and preserves customized or unrelated files.
• The final diff contains no paths, schemas, model names, commands, metadata files, or edition links belonging to another coding-agent environment.

License

MIT (see LICENSE). Do not change the license without an explicit maintainer decision.