AI cares little about architecture, but writes code faster than we read it.
Connect Archiplan to your agent and the code it writes gets a real architecture behind it — stress-tested and traceable before anything ships.
Install the archi CLI:
curl -fsSL https://raw.githubusercontent.com/archiplan-ai/Archiplan/main/release/install.sh | shWindows (PowerShell):
irm https://raw.githubusercontent.com/archiplan-ai/Archiplan/main/release/install.ps1 | iexThe installer finds the latest GitHub release
for your platform, verifies its checksum, and writes the binary into
~/.local/bin. Make sure that directory is on your PATH, then confirm
the install with archi --version. To pin a version, set
ARCHI_VERSION=x.y.z.
You can also install it by hand. Every release publishes one tarball per
platform — macos-arm64, linux-x64, linux-arm64, windows-x64 —
with a .sha256 file beside it. Download one, unpack it, and move
archi onto your PATH.
Everything after the install happens inside your agent. There are no commands to memorize.
Open your agent in the project folder, run /archi, and describe the
system in one sentence. The agent does the rest:
- intent, then requirements, then the model, then stress rounds, then a hardened and versioned spec
- every choice that matters comes back to you as a question with priced options
/archi-planwrites the implementation plan. It polls you for the stack, the tests and the infrastructure./archi-implementruns waves of parallel sub-agents until the plan is done, and runs the scenarios on a live stack
Run /archi in the repo and name the change you want:
- the model is recovered from the code — only the slice your change touches
- requirements pin the behavior that must not break, and links anchor the load-bearing code
- from there the loop is the same: stress, version,
/archi-plan,/archi-implement
The spec lives in one repository and the code lives in several. Tell the agent which repos participate:
- each member gets a worktree beside its checkout, on the same branch, started from its recorded baseline
- an ambiguous base comes back as candidate branches. The agent never guesses.
- members land by push and PR on their forges. The spec lands once, and whole.
- one unit — the spec, then the plan, then the code — stays in one worktree and lands once
- parallel efforts are parallel worktrees. Your main checkout is never mutated.
- the tools refuse work done outside this rule, and they say where to go
The install writes the workflow skills into your agent, and a slash command invokes each one. They are grouped by the job at hand.
/archi is the main entry point. It guides a full architecture
session with the archiplan methodology: from a one-line problem
statement, through intent and requirements, to a hardened and versioned
spec. It works greenfield and brownfield. It tracks the coupling live
with the NKP scoring line. It steers you toward the CRITICAL regime,
where changes propagate without cascading.
The stress rounds live here too. Each round finds stressors — failure modes, scale concerns, hostile users, regulators. It names the components that each stressor presses, applies the verdicts, and turns every break into a derived requirement or into a signed trade-off. You loop until a round survives. That version is the hardened spec.
/archi-plan turns a hardened spec into an implementation plan. It
authors the plan entirely through the archi plan commands. The plan holds
a charter, one task per node, curated requirement ownership, named
verifications and end-to-end scenarios. The charter carries a user-polled
stack and its infrastructure. The ownership is curated from the spec's
own reverse lookup. The command refuses on an unsaved model.
/archi-implement drives the build of a started plan, wave by wave,
with every task in its own sub-agent, until archi plan next reports
DONE. The plan stays the source of truth. The task briefs come from
archi plan task show. Every wave commits inside the worktree before the
merge, and code-link evidence is captured as each wave closes.
/archi-finish-worktree closes a worktree. It lands the spec, plan
and code unit in one move. It pushes the member branches for their PRs,
and it retires the worktree and its registry binding. A protected
receiving branch lands sideways, with --to plus a push and a PR, never
by a local merge.
/archi-merge joins two branches that both mutated the spec. It
triages the merge with check, resolves version-archive collisions with
remint, reads the notes the journal absorbed, and folds concurrent
stress rounds. The contract is the canonical render: a clean git merge
proves nothing until the composition compiles.
Archiplan throws traffic spikes, partial outages, hostile users and regulators at the spec, before you ship code that pretended none of them exist. Anything that breaks becomes a new requirement.
Every requirement remembers its origin: the initial problem, a specific stressor, or a stakeholder concern. Six months later, when someone asks why you split this from that, the answer is an artifact and not a lost Slack thread.
Archiplan flags when your design is heading toward a god-service or microservices-for-microservices' sake — before "we should refactor" turns into "we have to rewrite."
It gives you an evolutionary approach to system design, then continuous tracking of cause and effect:
Archi is in beta. It is rough in places, and that is the point. We harden it the way archi hardens a spec. The fastest way to make it better is to hear what breaks for you. Try it on a real design, and tell us what breaks.
Go deeper:
- skills/archi.md — the full workflow, greenfield and brownfield, and the modeling language in brief
- docs/versioning.md — what a version is, and why the archive is durable
- docs/multi-repo-workflow.md — the loop when the code lives in repositories of its own
Licensed under the MIT License.
Archiplan — plan mode on steroids.