Start Here: Six Lessons

Everything in this documentation set is real and verified — and there is a lot of it. You do not need most of it on day one. Take these six lessons in order and you are good to go. Each one builds on the last, states how long it takes, and ends with something working.

Two notes before Lesson 1: do it in a throwaway directory — the real profile decision is Lesson 2, and a scratch run is what makes deferring it legitimate. And if you are here to review rather than adopt, Lesson 6 alone is your path — it needs only an evidence file, not the toolchain.

The path

Lesson 1 — Install it and reach a green gate

Getting started: zero to first passing gate · ~30 minutes

Install the CLI, initialize a project, stage a real failure on purpose, read the finding, fix it, finish green. When you are done you have a working governed repository and you have seen the gate catch something.

Lesson 2 — Choose the right profile for your repository

Choosing profiles, presets, and frameworks · ~20 minutes

Lesson 1 used the appsec profile on faith. This lesson is the decision you actually own: which profile fits your repository, what each one installs and enforces, and which compliance frameworks it selects. Do this before initializing anything real.

Lesson 3 — Write your first spec

Your first spec · ~30 minutes

The gate exists to judge specs. Copy the template, fill it section by section, stage a defect so you see a finding fire, reach green. After this you have done the core loop the whole product is about. Lesson 5 returns here to teach what the gate cannot check about what you wrote.

Lesson 4 — Put the gate in CI

Wire the gate into CI · ~30 minutes

Extra starting state for this lesson: a git repository hosted on GitHub with push and pull-request rights — Lesson 1 deliberately did not create one. Governance that depends on people remembering to run a command is not governance. Wire the shipped workflow, watch a pull request go red on a staged failure and green on the fix — with screenshots of exactly what you should see.

Lesson 5 — Write a spec worth reviewing

Spec authoring: every governance section · ~60 minutes

The gate now has teeth, so this is the moment to learn what those teeth cannot bite. Section by section: what each governance section is for, what the rule literally checks, and the difference between analysis and gate-passing filler — including the demonstration that a spec saying "we did not do the work" passes every rule. The gate catches vocabulary; you supply substance. This lesson is where that stops being a slogan.

Lesson 6 — Review a gate you did not run

Read evidence as a reviewer · ~20 minutes

Someone must be the reader the visibility controls were built for. Handed only a stranger's gate-summary.json: which rules ran, what was disabled or narrowed and by whom, where the rules were loaded from, what was never scanned — and the six documented grounds to refuse an approval.

That's it. Six lessons, about three hours (a natural split: 1–3, then 4–6), and you can take a repository you own from nothing to a merge-blocking gate, write a spec a reviewer would accept as analysis rather than vocabulary, and read a green run's own evidence to say what it actually checked — and whether anything was weakened.

When you need it

The remaining playbooks are task-shaped: go to them when their situation is in front of you, not before. In particular, the first time the gate goes red for a reason you did not stage, open Investigate a failing gate.

When this happens	Go here
Adopting in a repo that already has a constitution or templates	Brownfield adoption
The gate is red and you do not know why	Investigate a failing gate
You need a project-specific check the shipped rules do not cover	Add a custom rule
A shipped rule is too broad (or too noisy) for your repository	Override a shipped rule
Choosing or changing compliance frameworks after setup	Select frameworks

Reference documentation (every finding code, every rule parameter, every evidence field) lives in USAGE.md and the rule engine guide — for looking things up, not for reading through.