Edison SinaniAI implementation architectBook a call

AI Team Playbook / Appendix C

Tightening the process

The twelve rules rely on every pull request being seen. That is enough for most teams of this size. A team that wants the rules to hold even against a determined developer adds four things, all on the git host or in managed settings, where a local edit changes nothing. The files are in the kit under extras/.

September 16, 2026 · About 3 minutes

Contents

The playbook

  1. Overview

Before code

  1. 1Write the constitution first
  2. 2One instruction file, under 200 lines
  3. 3Enforce the rules with settings and hooks
  4. 4Three gates before any code
  5. 5A walkable demo before any screen

Building

  1. 6One task, one worktree, one pull request
  2. 7Every contract has a file and two tests

Reviewing

  1. 8AI review first, and filtered
  2. 9Human review by risk tier
  3. 10Done means the evidence is in the pull request

Over time

  1. 11Measure five numbers, baseline first
  2. 12Protect the people who are still learning

Appendix

  1. AInstall checklist
  2. BOther tools, limits and sources
  3. CTightening the process
  4. DRun the agent with no entitlements

Get the kit

Why this is optional

Rule 3 enforces the rules with settings and hooks. That works inside an agent session. Outside it, the hooks, the settings and the instruction file are ordinary files in the repository, and a developer can change them. The playbook’s main check is the pull request: every change is read by an automated reviewer and a human before it merges.

On a small team that is usually enough, because a change to stop-gate.sh or to the allow list is visible in the diff and a reviewer asks why. The four additions below are for a team that wants those files locked. Each one runs where the developer cannot edit it.

1. Put the rule files under the lead’s ownership

A CODEOWNERS file names an owner for the playbook’s files. With “require review from code owners” switched on in the branch protection rule, no change to those files merges without the lead’s approval. A developer can still edit them locally, but the edit cannot merge without the lead.

# .github/CODEOWNERS
# The playbook files. No change to these merges without the lead.
/AGENTS.md                   @lead
/CLAUDE.md                   @lead
/.claude/                    @lead
/.github/                    @lead
/docs/constitution.md        @lead
/docs/review-policy.md       @lead
/docs/definition-of-done.md  @lead
/contracts/                  @lead

Replace @lead with the lead’s GitHub handle or a team. Owning .github/ also covers the CI workflows and this file itself.

2. Make the checks impossible to remove from a pull request

A pull request can edit the workflow that checks it. Two things stop that from mattering. First, branch protection names its required checks, and a required check that never reports blocks the merge, so deleting the gates job does not help. Second, a small guard job fails when any rule file changed in a pull request that does not carry the playbook-change label. The label alerts the reviewer. The ownership rule above is what blocks the merge, because the lead has to approve the change either way. The job goes in pr-checks.yml, which re-runs when a label is added, so adding the label clears it at once.

playbook-guard:
  if: github.event_name == 'pull_request'
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
      with: { fetch-depth: 0 }
    - name: Rule files change only with the playbook-change label
      env:
        BASE: ${{ github.event.pull_request.base.sha }}
        HEAD: ${{ github.event.pull_request.head.sha }}
        LABELS: ${{ join(github.event.pull_request.labels.*.name, ',') }}
      run: |
        set -euo pipefail
        CHANGED=$(git diff --name-only "$BASE...$HEAD" -- AGENTS.md CLAUDE.md .claude .github \
          docs/constitution.md docs/review-policy.md docs/definition-of-done.md contracts)
        if [ -n "$CHANGED" ] && ! echo ",$LABELS," | grep -q ",playbook-change,"; then
          echo "::error::Rule files changed without the playbook-change label:"
          echo "$CHANGED"
          exit 1
        fi

On an organization plan, a repository ruleset can require a workflow from a central repository instead. The pull request cannot touch that workflow at all.

3. Two lines in the policy

Add these to the review policy and the definition of done.

  • Any change to a rule file is High tier by definition. The lead and one other person review it.
  • A change to an approved spec is its own pull request. It is never in the same pull request as the code that claims to satisfy it. Without this line, a developer could edit the requirement in the same pull request, and the task would pass.

4. Managed settings for Claude Code

On a Team or Enterprise plan, settings deployed to the machine by the administrator win over the repository’s settings file. The allowManagedPermissionRulesOnly setting makes it impossible to remove a deny rule locally. Hooks can be set at the managed level too, so the stop gate does not have to live in the repository at all.

What this still does not stop

A developer can build a change entirely by hand, or with a tool that is not on the approved list, and open an ordinary pull request. That is fine. The template still asks how it was built, the same checks run, and the same reviewer reads it. The rules apply to what merges, whatever tool produced it.