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 2 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. 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 five-line CLAUDE.md. If .gitignore ignores .claude/ as a whole, narrow it to the three lines below, because the shared settings, hooks, agents and skills must be committed.

Then add three lines to .gitignore:

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

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/ai-review.yml. And git status shows them as new files on the branch task/playbook-install.

Step 2. 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 3. Fill in the instruction file

Do. Open AGENTS.md. Fill in the two sections marked TODO and delete the comments. Rule 2.

• Commands. 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. 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 4. Review the shared settings

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

• In permissions.allow, replace the example commands with the real ones from step 3, 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.
• In sandbox.network.allowedDomains, keep the package registries your stack uses and remove the ones it does not.

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.

Step 5. Make the hooks executable and set the check command

Do. Rule 3.

chmod +x .claude/hooks/*.sh

Open .claude/hooks/stop-gate.sh and replace the CHECK= line with the project’s fast check, the one you want to pass before any task can be called done. For example CHECK="dotnet test --no-restore". Keep it 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. Feed the destructive-command hook a fake command by hand:

echo '{"tool_input":{"command":"rm -rf build"}}' | .claude/hooks/block-destructive.sh; echo "exit $?"

It prints the blocked message and exit 2. 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. 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 and follow the prompts. It installs the app and creates the secret.
• Or install the Claude GitHub app for the organization from GitHub, then create an API key in the Claude console and add it as an organization secret named ANTHROPIC_API_KEY.

Open .github/workflows/ai-review.yml and compare its inputs with the action’s current documentation before the first run. The action changes over time.

Check. gh secret list shows ANTHROPIC_API_KEY, or the app appears under the organization’s installed GitHub apps. The workflow’s first real run is the pull request in step 8.

Step 7. Protect the main branch and create the labels

Do. Rules 6 and 9.

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

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. 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.

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, is the one that stops an agent fixing what is not broken. 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 pr-size, pr-template and gates checks run, the no-em-dashes check runs, and the AI review posts a comment. If gates fails, its placeholder step needs the project’s real build and test commands in .github/workflows/ci.yml. Fix that on the same 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. 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, and 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. Start the measurement file

Do. Rule 11. Create docs/measurement-log.csv with this header line and the first week’s row, before anything else changes:

week,prs_merged,median_pr_lines,median_hours_to_merge,change_failures,rework_prs
2026-09-21,12,180,9.5,1,2

Fill the row from the git host and the tracker. Put five minutes for it on the agenda of the weekly checkpoint.

Check. The file has six columns and one row. 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.