architect

A Claude Code plugin that builds the harness you develop in.

Point it at any repository — greenfield, legacy, or half-configured — and it audits what is there, decides what is missing, and sets up the intent, branching, environments, database isolation, CI/CD, versioning, testing, spec loop and enforcement that make AI-assisted development reliable.

It does not write your application. It builds the environment your application gets developed in — including the skills and guards the next agent will work under.

Install

/plugin marketplace add fialhosoft/architect
/plugin install architect

Update later with /plugin marketplace update fialhosoft.

Use

Command	Does
/audit	Read-only health check against the rubric. Changes nothing.
/organize	The full engagement: audit → decide → plan → apply → verify.
/spec	Agree what a change must do, before any code.
/plan	Turn the spec into an approach, a constitution check and ordered tasks.
/implement	Execute the plan one task at a time, verifying each.
/report	Is the harness working? Drift, change size, which guards never fire.
/upgrade	Bring an already-organized repo's harness up to date — no full audit.

The skills also trigger on their own — "set up CI for this", "protect main", "this repo is a mess", "I want to add a feature", "every project should have this" — without the slash command.

The four layers

/organize installs all of them; you can strike any stage.

0 · Intent — docs/constitution.md: what the project is for, the worst outcome, and three to seven articles derived from the audit. Without a written objective an agent can only comply — there is no standard to weigh a request against. This is what makes "tell me when I'm wrong" mean something.

1 · Repository — branching model chosen with you, protection where the platform allows it and honest fallbacks where it does not, an isolated database per pull request destroyed on close, one reusable quality workflow shared by the PR and release paths, versioning and changelog, and a single verify command matching CI exactly.

2 · Work — the loop per change, sized by blast radius:

Tier	Trigger	Artifacts
0	typo, dep bump, one file	none
1	one behaviour change	ac ids in the test names
2	new capability	spec.md + tasks.md
3	schema, auth, money, contracts, workflows	full set + rollback + human approval

The tier is computed from paths and diff shape in .architect.json. An agent may raise it; it may never lower it. Tiering is the part most spec tooling gets wrong — a six-command ritual for a typo is why teams abandon the practice after a month.

3 · Enforcement — hooks that refuse rather than advise: force pushes and commits on the production branch, edits to tier-3 paths with no approved plan, a PR opened on a tier ≥ 2 spec with no spec-reviewer findings recorded, and a Stop gate that will not let the turn end on unverified work. Each one bounded, each one with a CI counterpart, each one failing open when it cannot read its own rules.

spec-reviewer used to be the one piece of this that depended on memory — a step implement-spec said to run, with nothing checking that it had been. guard-pr reads the branch name for the spec id and refuses gh pr create until notes.md has a ## Review section with no unresolved finding in it. A second script, constitution-check, closes the matching gap one layer up: it proves every article in the constitution got a row in the plan's gate table — not that the verdict was right, only that no article was silently skipped while an agent filled in a checklist about its own plan.

The drift gate

The reason spec-driven development degrades: specs and code diverge, invisibly. No linter flags it, no CI job flags it, and the repo ships describing a system that no longer exists — which agents then read as current truth.

Two scripts close it. Every acceptance criterion carries a permanent id, and the test that proves it names that id:

it('AC-003: retries twice on 5xx, then surfaces a retryable error', () => { … })

trace-check fails the PR when a criterion has no test — and when a test names an id no spec declares, which is how a criterion dropped mid-implementation gets caught. spec-freshness fails when a shipped tier-3 spec owns files the PR changes and was not updated with them.

So the spec is never the source of truth. The code is, the test is the enforcer, and these are the rope between them.

Any language

One set of templates, not one per ecosystem. What varies — install, lint, test, build, the CI setup step, where tests live — is detected once from the manifest and written into .architect.json; templates read {{commands.*}}. Node, Python, Go, Rust, JVM, .NET, Ruby, PHP, Elixir, Dart and Swift are in the detection table, and a repo with no build and no tests (docs, infra, data) is a supported answer rather than a gap to scaffold over.

Four parallel template trees would have quadrupled what an agent reads to set up one repository, and three of the four would have been stale within a year.

The gate scripts stay Node whatever the project is: their logic is already language-agnostic, and every GitHub-hosted runner ships Node regardless of what the project is written in.

What it costs to have installed

~1180 tokens resident per session — the descriptions of seven skills, two subagents and seven commands, which is what makes them findable. Everything else loads only when it fires: a reference is read at its stage, never preloaded, and the counts that would otherwise be estimated by reading files come from scripts instead.

The plugin holds target repositories to the same standard. context-budget.mjs fails CI when what loads into every session in your repo crosses its ceiling, because instruction files only grow — each incident adds a paragraph and nothing removes one. At the ceiling, adding a rule means removing one, or promoting it to a check so it can leave the text entirely.

The principles it works from

1. An executable gate beats a documented rule. Anything a machine can check becomes a check, not a paragraph asking people to be careful.
2. Prove the dangerous thing. "The preview uses the preview database" is asserted by a test that fails the PR — not stated in a doc.
3. A gate must distinguish its own breakage from a real failure. Exit 1 for "the repo is wrong", exit 2 for "the check could not run".
4. Ceremony scales with blast radius, and with nothing else.
5. Every generated file carries its own why. A rule without a reason gets deleted by the first person who finds it inconvenient.
6. Additive and reversible. Stages land independently.
7. Never touch production data or the default branch. It works on a branch and opens a PR; you merge.
8. Never invent a secret, and never report a gate as configured when the platform refused it.
9. The repo's existing conventions win.

The learning loop

record-learning turns an incident into a safeguard at the right level, using a four-rung ladder:

Rung	When	Where it goes
1. Context	happened once	a note
2. Procedure	an agent would hit it again	a skill step, with the mechanism
3. Automated check	a machine can detect it	CI — and the rung 2 prose is deleted
4. Structural	every repo of this kind has it	upstream, via evolve-architect

Rung 3 is what keeps the instruction set from growing without bound: rules that become checks leave the text.

Structure

skills/
  organize-repository/   the consultant: SKILL.md + references/ + templates/
  write-spec/            agree what a change must do
  plan-implementation/   approach, constitution gate, tasks
  implement-spec/        execute one task at a time
  record-learning/       the four-rung ladder
  evolve-architect/      contribute a structural lesson back here
  upgrade-harness/       bring an organized repo's harness up to date
agents/
  auditor.md             read-only scorecard across eleven axes
  spec-reviewer.md       fresh-context review against the spec
commands/                /audit /organize /spec /plan /implement /report /upgrade
evals/run.mjs            37 cases proving each shipped gate refuses what it claims
docs/constitution.md     this plugin's own — it follows its advice

Templates are starting points, never answers — every one is adapted to the target repository's real paths, commands and constraints before it is written.

node scripts/verify.mjs is this repository's own gate: every shipped file would be valid where it lands, and every gate refuses what it claims to. The second half exists because the rubric here scores a gate nobody has watched refuse anything as a 1, and holding other repositories to a standard this one did not meet was not defensible.

It runs in .github/workflows/ci.yml on every push and pull request against main — one job, because there is no separate release pipeline yet for a second job to drift weaker than.