Configuration and security

Which agent does what, what an agent is allowed to do, how the workflow flags risky changes, and what you have to set up in GitHub yourself.

The short version: the scripts decide what an agent may do on your machine and point out changes that need your attention. They do not control who can merge on GitHub. For that you configure branch rules and permissions in the repository.

This page summarizes. The exact behavior of the version your project has is in its own files: the scripts, docs/workflow.md, and docs/development.md.

Agent roles and models

A role is a job in the workflow, not a person or an account. Each role has an agent and a model, set in .agents/agents.conf, one role per line:

implementer: codex <model>
reviewer: claude <model>

Role	What it does
`project-grill`	Asks you questions about a new project and writes the requirements
`project-planner`	Writes the architecture, the roadmap, and the decision records
`planning-reviewer`	Reviews the plan, read-only
`implementer`	Implements a feature and writes its tests
`reviewer`	Reviews a feature, read-only
`triage`	Proposes what to do with each review finding
`triage-implementer`	Fixes the findings that were selected
`analyst`	Compares the runs of several features and proposes improvements, read-only (learning from your runs)

The supported agents are Claude Code (claude) and Codex (codex). You can override the agent and the model for one run with --agent and --model on a workflow script. The model you name is passed to the agent as it is: the workflow never replaces it with another one, and an unknown agent is an error.

A different agent for writing and for reviewing gives you a more independent review.

What an agent is allowed to do

A script starts an agent with one of three permission profiles:

Profile	Used for	What the agent can do
write	A step you follow in the terminal, such as implementing a feature	Change files in its worktree and use the network. For anything beyond that it asks you: Claude before it runs a shell command, Codex before a command leaves its sandbox
unattended	A step that runs without you, such as in `run-feature.sh`	The same reach as write, and it asks nothing. What it would have asked you is decided without you, in a different way per agent: Codex stays inside its sandbox and is refused what leaves it; Claude runs in its automatic permission mode, whose own check allows or denies each action, and anything that would still need a question is denied. It gets none of your personal integrations, such as MCP servers or apps
read-only	Reviews, triage proposals, and the analysis of runs	Read files. It cannot change them, and it gets none of your personal integrations

If an agent cannot enforce a profile, the script stops. It never starts the agent with broader permissions instead.

What this is not: a profile uses the permission and sandbox settings of the agent's own command-line tool. It is not a container or a virtual machine. All agents share your machine, your network, and whatever databases and services run there, and a worktree separates working files only. Full isolation per agent is one of the possible improvements.

Changes that need the owner

Before a feature is committed, check-guardrails.sh looks at which files it changes. The rules come from the base branch, so a feature cannot loosen the rules it is checked against.

Kind of change	Examples	What happens
Protected	Decision records in `docs/decisions/`, CI workflows, `CODEOWNERS`, the agent configuration, and the scripts and prompts that carry out the review	The pull request is opened and marked as needing the owner's approval. No script merges it
Sensitive	`docs/architecture.md`, a new check in `scripts/verify.conf`, and paths you add yourself	Allowed; the reviewer is told to look at it closely
Everything else	Ordinary feature work	No extra step

You add the paths that matter in your project, such as the deployment or the dependency manifest, to .agents/policies/guardrails.conf. Changing or removing an existing check in scripts/verify.conf counts as protected; adding one counts as sensitive.

The reviewer also says how much a change affects the architecture. A "major" or "breaking" assessment marks the change as needing the owner, whatever the files are. The reviewer can make the outcome stricter, never looser.

What GitHub has to enforce

The gate above is a check and a label. It tells you which pull requests need your attention, and the workflow's own scripts will not merge them. It does not stop someone, or an agent with your credentials, from merging on GitHub. To enforce the rules, configure the repository:

A ruleset for main that requires a pull request and the CI check before a merge. ./scripts/doctor.sh warns you when the check is not required. The repository setup guide lists the settings.
.github/CODEOWNERS ships with the placeholder @YOUR_GITHUB_USERNAME. Replace it with your own account before you require code owner reviews; until then the file has no effect.
Bypass rights: a repository administrator can usually bypass a ruleset. Decide whether that should apply to you.

The complete list of settings is the repository setup checklist. What to keep out of a repository, and how to report a security problem, is in SECURITY.md.

One identity: an agent runs with the GitHub permissions of the account that started it. If that account may merge, so may the agent, and no script can prevent it. A separate GitHub identity with limited permissions for agents is not built yet (Issue 99).

Project checks and workflow checks

./scripts/verify.sh runs two sets of checks:

Your project's checks, listed in scripts/verify.conf, one command per line: tests, linters, builds. They always run. The file ships with the checks of the template itself; you replace them with your own.
Tests of the workflow scripts, listed in scripts/verify-workflow.conf. They protect the workflow, not your application, and run locally only when a workflow file changed. ./scripts/verify.sh --all always runs them, and CI uses that.

Checks can have a group, such as code or build. ./scripts/verify.sh --only code runs one group, for example while you work on a part, or in a CI job of its own. A partial run is never a verification: nothing is recorded as passed, and the review and the commit still run every check.

The template's own project checks include docs-references, which runs ./scripts/check-docs.sh: in the tracked Markdown files, every relative link and every path in backticks that names a file of the repository must exist, so that the documentation does not point at a file that was renamed or removed. External links, anchors, paths with a placeholder, and files that Git ignores are not checked; the details are under "References in the documentation" in docs/development.md. A project keeps the check in its scripts/verify.conf or removes it.

A successful run is recorded for the exact content of the working tree that was checked, together with which checks ran. With --reuse, a later step skips the run only when that content is unchanged and the recorded run covered every check that is required now: a run that skipped the workflow tests does not count where they are required. Any change to the content means the checks run again.

A review belongs to the content that was reviewed: a change to that content requires another review. New commits on the base branch alone do not make a review outdated.

Separately, if the point where the feature branched off its base branch has changed, for example after you merged the base branch into the feature, any later review has to cover the complete feature and cannot be limited to the recent changes.

The guidance on what makes a check worth having is in docs/evaluation.md: checks that protect behavior matter more than the number of tests.

What is recorded on your machine

The workflow keeps a record of every run, so that you can see what a feature cost and learn from it (learning from your runs). The records stay on your machine:

What	Where
One file per run: how long each step took, the tokens each agent call used, the verifications, and what you did that a script saw	`.agents/run/records/` in your main checkout, also for a feature in a worktree
The runs of a feature or a planning together, copied when the pull request is opened and before its worktree is removed	`.agents/records/` in your main checkout
The notes of the implementer on a run, optional	`.agents/experience/` in the feature worktree, kept in the record of the run once they are valid
The input, the result, and the report of an analysis	`.agents/analysis/` in your main checkout

Git ignores all of these: they are never committed, and a new clone or git clean -fdx does not keep them. Copy the directories when you want to keep them.
No prompt, no answer of an agent, and no transcript is recorded. Text that looks like a key or a token is replaced by [redacted] before it is written.
Nothing goes to GitHub, with one exception that you turn on yourself: publish-feature.sh --summary posts the totals of a feature on its Issue, as numbers only (time, runs, review rounds, tokens per role and model). It is off by default, because a repository is often public.
A record that cannot be written is reported, and the work goes on with its own outcome: a record never stops a feature.

Keeping a project up to date

A repository created from the template does not receive the template's later improvements. ./scripts/sync-template.sh brings them over:

It touches only the files listed under paths: in .agents/template.conf: the workflow scripts, prompts, policies, schemas, the CI and guardrails workflows, and the workflow documentation. Your code, your requirements, your roadmap, and your scripts/verify.conf stay yours.
A file you did not change is replaced. A file both sides changed is merged, and a conflict is left in the file and reported. A file the template removed is reported, never deleted.
To keep a listed file as your own, add :(exclude)<path> to the list.
The script never commits or pushes: you review the result and open a pull request.

What each file in the repository is for is in the project map.