Install checklist

Before you start

You need all of these. Check each one before step 1.

• A clone of the kit repository, next to your own repository. The commands below assume it is at ~/Workspace/AiTeamPlaybook. Adjust the path if yours differs.
• A repository on GitHub with a main branch, and admin rights on it. Branch protection in step 7 needs admin.
• Claude Code installed and signed in. In a terminal, claude --version prints a version, and claude opens a session without asking you to log in. Every command in this checklist runs in a terminal from the repository root, except the ones that start with a slash, which are typed inside a running claude session.
• The repository trusted once. Run claude from the repository root, accept the dialog that asks whether to trust the folder, then type /exit. Until this is done, the shared permission rules and hooks are ignored, and a non-interactive claude -p run prints a warning saying so.
• The GitHub CLI installed and signed in: gh auth status says you are logged in.
• A clean working copy on main, up to date: git status says nothing to commit, and git pull says already up to date.
• The technology stack decided. Step 3 opens with it.

The whole install lands as one pull request. It will be well over 400 lines, so it is the one time the size override is routine. Step 7 creates the label and step 8 opens the pull request.

Step 1. Backfill the baseline

Do. Rule 11. Before anything from the kit goes in, create docs/measurement-log.csv with this header line and one row for each of the last 8 to 12 weeks:

week,prs_merged,median_pr_lines,median_hours_to_merge,change_failures,rework_prs
2026-07-06,11,210,8.0,1,2
2026-07-13,9,165,11.5,0,1

Four of the five numbers are already in the git host’s history. This lists the merged pull requests since a date, with their size, their open and merge times and their reviews. Use the Monday twelve weeks back:

gh pr list --state merged --limit 500 --search "merged:>=2026-07-06" \
  --json number,additions,deletions,createdAt,mergedAt,reviews

Change failures come from the tracker’s hotfix and revert labels, where the team has them. Leave that column empty for weeks where it does not. The file is committed with the install pull request in step 8.

Check. The file has six columns and a row for each of at least eight past weeks. Nothing from the kit is in the repository yet.

Step 2. Copy the kit in, on a branch

Do. From the repository root:

git switch -c task/playbook-install
mkdir -p docs .claude .github/workflows
cp -R ~/Workspace/AiTeamPlaybook/docs/. ./docs/
cp -R ~/Workspace/AiTeamPlaybook/.claude/. ./.claude/
cp -R ~/Workspace/AiTeamPlaybook/.github/. ./.github/
cp -R ~/Workspace/AiTeamPlaybook/alternatives ./alternatives
cp -R ~/Workspace/AiTeamPlaybook/extras ./extras
cp ~/Workspace/AiTeamPlaybook/AGENTS.md ~/Workspace/AiTeamPlaybook/CLAUDE.md .
cp ~/Workspace/AiTeamPlaybook/README.md docs/playbook-README.md

The /. form merges into a folder that already exists instead of nesting a copy inside it, so existing workflows under .github/workflows/ and existing files under .claude/ are kept. Do not copy the kit’s README.md over your own. It goes under docs/ as the playbook’s own readme. If the repository already has a CLAUDE.md or an AGENTS.md, move their contents into the kit’s AGENTS.md and keep the kit’s short CLAUDE.md.

Do not copy the kit’s .gitignore over yours either. Merge its lines into yours. The three that matter are:

.claude/worktrees/
.claude/settings.local.json
CLAUDE.local.md

If your .gitignore ignores .claude/ as a whole, narrow it to these lines, because the shared settings, hooks, agents and skills must be committed.

Check. These all exist: ls AGENTS.md CLAUDE.md .claude/settings.json .claude/hooks docs/constitution.md docs/specs/_template .github/PULL_REQUEST_TEMPLATE.md .github/workflows/ci.yml .github/workflows/pr-checks.yml .github/workflows/ai-review.yml. And git status shows them as new files on the branch task/playbook-install.

Step 3. Write the constitution

Do. Open docs/constitution.md. Fill in every section marked TODO and delete the TODO comments as you go. Rule 1.

• Purpose. One paragraph.
• Stack. One row per layer with the choice, the version and one sentence of rationale. For a repository with a .NET API, a Python worker and a Vue frontend that is six rows: backend, data, frontend, services, infrastructure, CI.
• Non-negotiables. Keep the seven that ship. Add yours below them, numbered.
• Conventions. Only what differs from the language defaults.
• Deliberate limits. At least one line. What the system does not do, so an agent does not add it.

Check. grep -n "TODO" docs/constitution.md prints nothing. The stack table has no empty cells.

Step 4. Fill in the instruction file

Do. Open AGENTS.md. Fill in the sections marked TODO and delete the comments, starting with the commands. Rule 2.

• Commands. The block ships with examples from a three-service repository. They do not exist in yours, so replace the whole block with every build, test, lint and regenerate command the agent cannot guess, one per line, with a short comment. For example:

# API (.NET)
dotnet build
dotnet test                          # unit + integration
# Worker service (Python)
cd worker && pytest
# Frontend
cd frontend && npm run type-check && npm run test && npm run build
# Local stack
docker compose up -d

• Where things are. Five to ten lines. Shared UI components, business rules, contracts and their tests, prototypes.

Leave the “How to work” and “Code Review Rules” sections as they are. Keep that second heading’s exact casing, because Codex looks for it. Open CLAUDE.md and confirm its first line is @AGENTS.md.

Check. grep -n "TODO" AGENTS.md prints nothing. wc -l AGENTS.md is under 200. Then ask the agent a question only the file can answer, from the repository root:

claude -p "Which command runs the API tests? Answer with the command only."

It answers with the command you wrote.

Step 5. Review the settings and set up the hooks

Do. Open .claude/settings.json. Rule 3.

• In permissions.allow, replace the example commands with the real ones from step 4, using the same Bash(command:*) form.
• In permissions.ask, keep commit, push, opening a pull request and applying a migration. Add any command that changes shared state.
• Leave permissions.deny as it is. If you must remove a line, write the reason in docs/governance.md first. Add the project’s own deploy commands.
• If you add a secret path to the Read(...) deny rules, add it to sandbox.filesystem.denyRead too. The Read rules stop the agent’s file tool. denyRead stops shell commands such as cat.
• In sandbox.network.allowedDomains, keep the package registries your stack uses and remove the ones it does not.

Then make the hooks executable:

chmod +x .claude/hooks/*.sh

Open .claude/hooks/stop-gate.sh and set CHECK to the project’s fast check, the one you want to pass before any task can be called done. Keep the override in place, so the line reads for example CHECK="${PLAYBOOK_CHECK:-dotnet test --no-restore}". The PLAYBOOK_CHECK environment variable is only an override for a developer who needs a different check locally. Until CHECK is set, the gate blocks the agent from finishing with a message that it is not configured. Keep the check short to run. The full suite belongs in CI.

Open .claude/hooks/lint-on-edit.sh and adjust the formatter commands to the tools the repository has.

Check. python3 -m json.tool .claude/settings.json > /dev/null prints nothing, so the file is valid. Start claude in the repository and run /permissions. The allow and deny lists you edited are shown.

Feed the destructive-command hook two fake commands by hand:

echo '{"tool_input":{"command":"rm -rf build"}}' | .claude/hooks/block-destructive.sh; echo "exit $?"
echo '{"tool_input":{"command":"git push -u origin task/142-fix-login"}}' | .claude/hooks/block-destructive.sh; echo "exit $?"

The first prints the blocked message and exit 2. The second prints only exit 0, because flags are matched as whole words. Then, inside a claude session, ask it to run rm -rf build. The session reports the command was blocked by the hook. Finally, make any test fail on purpose, ask the agent to finish a small edit, and confirm it keeps working on the failure instead of stopping. If it cannot fix the failure, the gate lets it stop after three attempts with a message that the task is not done. Undo the broken test.

Step 6. Set up the automated first-pass review

Do. Rule 8. Either of these:

• Inside claude, run /install-github-app. Let it install the Claude GitHub App on the repository, then choose “Skip for now” when it offers to add workflow files, so the kit’s ai-review.yml stays the only review workflow. Add the secret yourself: gh secret set ANTHROPIC_API_KEY --repo <owner>/<repo>.
• Or install the Claude GitHub App from GitHub, create an API key in the Claude Console, and add it as a repository or organization secret named ANTHROPIC_API_KEY.

Use an API key rather than a subscription token for a shared secret. A token from claude setup-token is tied to one person’s subscription. Create the key in a Console workspace of its own with a monthly spend limit, which is also appendix D’s step 5.

Open .github/workflows/ai-review.yml and check two things. The claude_args line must pass --allowedTools with git diff, git log, the inline comment tool and gh pr comment, because in automation mode the action grants no tools until the workflow does. Without them the reviewer cannot read the diff or post, and its findings only reach the run log. And the permissions block must have pull-requests: write and id-token: write. Compare the rest with the action’s current documentation before the first run. The action changes over time.

Check. gh secret list shows ANTHROPIC_API_KEY, and the app appears under the repository’s or organization’s installed GitHub Apps. The workflow’s first real run is the pull request in step 8. If that run succeeds but posts nothing, the --allowedTools line is missing.

Step 7. Give CI real steps, protect the main branch and create the labels

Do. Rules 6, 9 and 10.

Open .github/workflows/ci.yml and replace the steps of the gates job with the project’s real build and test commands, the full versions of the ones from step 4. Delete the Not configured step. Until you do, gates fails on every pull request, on purpose. A required check that passes without testing anything looks like evidence when there is none.

Create the two labels:

gh label create size/xl-override --description "Over 400 lines, reason in the PR body" --color d73a4a
gh label create claude-code-assisted --description "Built with Claude Code" --color 0e8a16

The second is applied by the provenance-label job in .github/workflows/pr-checks.yml whenever the pull request template says Tool: Claude Code. It is not added by hand.

Then on GitHub, open the repository settings, choose Branches, and add a protection rule for main with these settings on: require a pull request before merging, require one approval, require status checks to pass, and select the checks named gates, pr-size and pr-template. gates is in ci.yml. The other two are in pr-checks.yml, which re-runs when the pull request body is edited or a label changes. Checks appear in the list only after they have run once, so if they are missing, come back after step 8’s pull request has run and add them.

Check. grep -n "Not configured" .github/workflows/ci.yml prints nothing. Then:

gh api repos/{owner}/{repo}/branches/main/protection --jq '.required_status_checks.contexts, .required_pull_request_reviews.required_approving_review_count'

It prints the three check names and the number 1.

Step 8. Write the system design and open the install pull request

Do. Rules 4 and 7. Open docs/design.md and write it for the system as it is today, in its nine sections. Section 7, deliberate deviations, lists the unusual choices that are intentional, so an agent does not try to fix them. The automated review reads it too. Then replace docs/adr/0001-example-hosted-extraction-engine-as-a-bridge.md with your own first decision, using docs/adr/0000-template.md, and list it in section 9 of the design.

Then commit everything from steps 1 to 8 and open the install pull request:

git add -A
git commit -m "chore: install the AI team playbook"
git push -u origin task/playbook-install
gh pr create --title "Install the AI team playbook" --label size/xl-override --body-file .github/PULL_REQUEST_TEMPLATE.md

Edit the pull request body on GitHub: fill every line of the template, set the risk tier to High because it changes the agent configuration, and write “playbook install” as the override reason.

Check. On the pull request, the gates, no-em-dashes, pr-size and pr-template checks run, and the AI review posts a comment. pr-template fails until every line of the template is filled in, and its message names the line. It re-runs by itself when you edit the body. If gates fails with “not configured”, step 7’s change to ci.yml is not on the branch. When the checks are green and the pull request is merged, go back to step 7 if any check was missing from the protection rule.

Step 9. Run one small feature through the whole process

Do. With one developer, the lead reviewing each gate. Pick something small that has no contract change. Rules 4, 5, 6, 8, 9 and 10, in this order:

1. claude then /spec <feature-slug>. The developer answers the interview. The lead approves the requirements.
2. The same command continues into the design. If there is a screen, the walkable demo comes first. The lead approves the design.
3. /tasks <feature-slug>. The lead approves the task list. The developer creates the tracker entries.
4. claude --worktree task-<id>-<slug> for the first task. Rename the branch it creates with git branch -m task/<id>-<slug> before the first commit. The developer pastes the tracker entry. The agent builds it and the Stop hook runs the check.
5. /review. The reviewer agent runs. The developer fixes or answers every Important finding, then commits and pushes, with the commands the skill prints or by asking the agent, which waits for confirmation on each one. Then opens the pull request from the template.
6. CI runs, the AI review posts, the lead reviews by the tier, the pull request merges. The developer deletes the worktree.

Fix any template or hook that got in the way, in the same week, as its own small pull request.

Check. One merged pull request with the template filled in, an AI review comment on it, and a human approval. docs/specs/<feature-slug>/ holds three approved documents, and design.md in it says Implemented.

Step 10. Add a row every Friday

Do. Rule 11. Every Friday from here on, add the week’s row to docs/measurement-log.csv, from the git host and the tracker, the same way as step 1. Put five minutes for it on the agenda of the weekly checkpoint.

Check. The file gains one row a week after the backfilled ones. The weekly checkpoint invite exists and names the file.

The rest of the team comes on over the following three weeks, as rule 12 describes.