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. 3Prose is advice, hooks are enforcement
  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 from day one
  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 says that prose is advice and hooks are enforcement. That is true 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 real enforcement 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, not just watched. 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. The edit cannot land.

# .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 is a flag for the reviewer. The lock is the ownership rule above, because the lead has to approve the change either way.

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. This is the quiet bypass nobody thinks of: edit the requirement, and the task now passes.

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 a local removal of a deny rule impossible rather than forbidden. 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 were never about controlling the tool. They are about what gets to merge.