Fast code is easy. A codebase that survives its next hundred changes is harder.
Build codebases that stay coherent as they grow -- without giant modules, speculative abstractions, or accidental breaking changes.
No architecture by accident. No abstraction by speculation. No compatibility by assumption.
Why · Install · Quick start · Use it correctly · Example · Workflow · Outputs
Most coding agents do not fail because they cannot write code.
They fail because they make structural decisions silently while writing it.
A request that sounds ordinary:
Add a second payment provider.
Refactor this service.
Make this feature extensible.
already forces decisions about ownership, boundaries, compatibility, failure behavior, state flow, migration, and rollback.
When those decisions stay implicit, the codebase usually drifts into one of three expensive states:
| Failure | What happens |
|---|---|
| Architecture by neglect | The feature lands in the nearest file. Ownership blurs, rules duplicate, and one or two modules absorb everything. |
| Architecture by speculation | A possible future becomes an interface, factory, registry, event, or inheritance layer before a real variation exists. |
| Compatibility by assumption | Existing behavior is preserved or broken without first making the intended boundary explicit. |
Architect exists to force those decisions into the open before the codebase pays for them.
codex plugin marketplace add vortezwohl/Architect
codex plugin install architect@architect
/plugin marketplace add vortezwohl/Architect
/plugin install architect@architect
Start a new session after installation so the agent can discover the plugin.
npx skills add vortezwohl/Architect
Or copy skills/ into your tool's supported skills directory and invoke the stage manually:
$architect-design
$architect-propose <plan-name>
$architect-build <plan-name>
Important
Read a skill before installing it. These skills encode execution rules, package contracts, and stage boundaries.
Tip
If you installed the plugin and do not see the commands immediately, start a fresh session first.
After installation, you should see three plugin commands:
designproposebuild
Use them like a wizard. Click the next one only after the previous one is done.
Tip
For most people, the fastest way to start is simple: click design, describe the change in one sentence, then follow the same name through propose and build.
Use this first.
Tell Architect what you want to change.
$architect-design Add a second payment provider without breaking checkout.
/architect:design Add a second payment provider without breaking checkout.
What you get:
- one approved design bundle;
- clear boundaries;
- no coding yet.
Use this after the design is approved.
Give the change a short plan name:
$architect-propose add-payment-provider
/architect:propose add-payment-provider
What you get:
- one sealed
.architect/add-payment-provider/package; - task files;
- verification plan;
- execution log.
Use this after the plan package exists.
Run the same plan name:
$architect-build add-payment-provider
/architect:build add-payment-provider
What happens:
- Architect executes the recorded tasks in order;
- updates state and logs;
- keeps the work inside the approved boundary.
- New change: start with
design - Design approved, no plan yet: use
propose - Plan already created: use
build
Do not jump straight to build.
The whole point of Architect is:
design -> propose -> build
Use the stages in order.
- Run
architect-designonly when you want one approved design bundle. - Run
architect-proposeonly after that bundle is approved. - Run
architect-buildonly after the generated package is sealed and validated.
Do not skip directly from a large request to architect-build. The repository is built around the separation of approved design, sealed plan, and bounded execution.
Important
Architect is intentionally manual. It is not meant to guess the next stage for you.
User:
Add a second payment provider without breaking the current checkout flow.
Stage 1: $architect-design
- Reads the repository first.
- Asks what compatibility must hold.
- Separates proven variation from stable policy.
- Produces approved D-xxx subdesigns.
Stage 2: $architect-propose add-payment-provider
- Creates .architect/add-payment-provider/
- Allocates design and task documents with repository scripts.
- Seals and validates the package.
Stage 3: $architect-build add-payment-provider
- Loads the sealed package and current execution state.
- Executes the recorded T-xxx tasks in order.
- Updates the execution log with actual results.
The difference is straightforward:
- A normal coding agent starts coding and hides architectural decisions inside diffs.
- Architect makes those decisions explicit, approved, serialized, and executable.
Architect is a strict manual three-stage flow:
architect-design -> architect-propose -> architect-build
Each stage has a separate responsibility and refuses to do the next stage's work automatically.
| Stage | Invoke when | Produces | Refuses to do |
|---|---|---|---|
architect-design |
You need one approved architectural direction for one consequential change. | One approved design bundle containing one or more D-xxx subdesigns. |
Planning, file writes, or implementation. |
architect-propose |
The design bundle is already approved and must become an executable package. | One sealed .architect/<plan-name>/ package with D-xxx, T-xxx, state, and log artifacts. |
Redesigning the solution or editing app code. |
architect-build |
The sealed package is validated and ready to execute. | Real implementation progress, task-state updates, and factual execution logs. | Reopening design or inventing new structure mid-build. |
This is the core user experience change: the agent no longer jumps from request to code. It must first separate design approval, plan sealing, and bounded execution.
architect-design produces one approved bundle for one future plan package.
Each bundle may contain multiple D-xxx subdesigns with explicit intent, boundaries, counterexamples, anti-patterns, and MUST DO / MUST NOT DO rules.
architect-propose converts that approved bundle into one deterministic package under:
.architect/<plan-name>/
The package includes:
00-plan-manifest.md
01-context-and-contract.md
02-design-catalog.md
03-designs/D-xxx-<slug>.md
04-impact-and-boundaries.md
05-task-catalog.md
06-tasks/T-xxx-<slug>.md
07-verification-plan.md
08-execution-log.md
.state/execution-state.json
This package is not notes. It is the execution contract for the build stage.
architect-build executes the sealed T-xxx tasks in order, updates task state truthfully, appends factual log entries, and keeps implementation inside the approved boundary.
What you get is not just code. You get code plus the decision trail, state trail, and execution trail that explain why the code was changed and what actually happened.
assets/
`-- architect-wordmark.svg
skills/
|-- architect-design/
| |-- SKILL.md
| |-- agents/openai.yaml
| `-- references/
| |-- decision-protocol.md
| |-- gof-patterns.md
| `-- source-article.md
|-- architect-propose/
| |-- SKILL.md
| |-- agents/openai.yaml
| |-- scripts/
| `-- templates/
`-- architect-build/
|-- SKILL.md
`-- agents/openai.yaml
The public product is Architect.
The three callable stages are architect-design, architect-propose, and architect-build.
Contributions should strengthen the workflow, not add noise.
Good contributions usually improve one of these:
- design-stage evidence gates;
- compatibility-boundary clarity;
- sealed package determinism;
- build-stage execution discipline;
- rollback, validation, or logging accuracy.
If a change adds ceremony without improving one of those properties, it is probably the wrong change.
MIT. See LICENSE.