Architecture
Agent harness
Every project from archipelago create ships scripts/agent-harness/. It blocks the conventions a team has already agreed on, at the moment an AI agent or a person breaks them. A rule cannot be forgotten, and a reviewer no longer has to repeat the same comment.
Why
Agents repeat the same mistakes: a plain Navigator.push where the router is meant to be used, Theme.of(context) where the kit has typed extensions, a hand-edited generated file. A rule written in CLAUDE.md is advice. The harness turns it into a check at three points, with the same rules each time:
| Where | How | What it covers |
|---|---|---|
| Claude Code | PreToolUse hook in .claude/settings.json | The lines a Write, Edit or MultiEdit adds, and Bash commands, including the lines a git commit would add |
| Git | .githooks/pre-commit and commit-msg | The staged diff (so git commit -a and git commit -- <path> are covered) and the message |
| CI | harness.py --range <base>...HEAD | Every line a pull request adds, so --no-verify does not get past it |
Only added lines are checked. Existing code never trips a rule.
Rules
A rule marked "warns at commit" blocks while an agent edits a file. At commit time and in CI it prints a warning and does not fail, because code that a brick generates later can break these rules and the commit that adds it is not the user's own work.
| Rule | Blocks |
|---|---|
nav (warns at commit) | Navigator.push* and MaterialPageRoute in features/*/lib and apps/*/lib. Push through the auto_route router. |
theme (warns at commit) | Theme.of(context) in feature code. Use context.colors, context.typography, context.spacing. |
widget (warns at commit) | A private method that returns a Widget. Use a class-based widget. |
getit | GetIt.asNewInstance() in feature code. Use the feature's FeatureContainer. |
noop | A public class named *Noop* in a *_noop package. A noop package keeps the impl's names. |
state | Only for bloc and cubit. A state class with no value equality in a bloc/ or cubit/ directory. |
generated | Edits to *.g.dart, *.gr.dart, *.config.dart, *.module.dart, *.freezed.dart, .archipelago/base and .archipelago/generated. |
conventional | A commit subject that is not a Conventional Commit. |
attribution | An AI attribution line in a commit message. |
Rule names are stable. Code references them in exception comments, so a rename would be a breaking change and is noted in the brick changelog.
Exceptions
A line opts out of a rule with <rule>-ok: <reason> on the line or the line above, in any comment syntax:
// nav-ok: native dialog route, not a page
Navigator.of(context).push(dialogRoute);The reason is required. In a Bash command, put # <rule>-ok: <reason> anywhere in the command.
Project rules: rules_local.py
scripts/agent-harness/rules_local.py belongs to the project. Generation creates an empty one when it is missing and never overwrites it, and no brick ships it. The engine loads it after rules.py.
import re
FILE_RULES = [
{
"name": "print",
"pattern": re.compile(r"\bprint\("),
"scope": lambda rel: rel.endswith(".dart") and "/lib/" in rel,
"message": "log through the app logger, not print().",
},
]The four lists are FILE_RULES (added lines), PATH_RULES (the file a Write or Edit targets), COMMAND_RULES (Bash commands) and MESSAGE_RULES (commit messages). The comment at the top of the generated file shows the shape of each. A rule gets the same <name>-ok: exception for free. A rules_local.py that fails to load is reported and skipped, so a typo never blocks every commit.
A project test is a test/test-<name>.sh script that sources lib.sh, like the shipped ones; run-tests.sh runs every test-*.sh. A brick run replaces only the files it ships, so your own test files stay.
Who owns what
| Path | Owner | On upgrade |
|---|---|---|
scripts/agent-harness/harness.py, rules.py, run-tests.sh, test/ | Generator | Replaced |
.githooks/ | Generator | Replaced |
scripts/agent-harness/rules_local.py | Project | Never touched |
.claude/settings.json | Shared | The harness hook is added once; every other key and hook stays |
Do not edit the generator-owned files. Fork behaviour through rules_local.py.
Setup in a clone
Generation sets core.hooksPath to .githooks when the project is a git repository of its own and no path is set. After a clone, run once:
git config core.hooksPath .githooksThe hooks run the clone's own .git/hooks/<name> afterwards, so tools that install a hook there keep working. The hooks need python3 (standard library only) and do nothing without it.
Tests
bash scripts/agent-harness/run-tests.shEach rule has one script in scripts/agent-harness/test/. They build a throwaway git repository inside the project and clean it up.