architecture

architect

Instruction-first architecture review for AI coding agents.

architect packages a read-only Architect role, portable Agent Skills, report/design/plan templates, and helper CLIs for evidence-based architecture design and review. It is built for Claude Code, Codex CLI, Pi, and other runtimes that can load Agent Skills-style capabilities.

The Architect does not rewrite systems. It designs target architecture from requirements, establishes intended architecture, maps observed structure, gathers local evidence, scores architecture quality with confidence, and returns design artifacts, a cited report, and/or an incremental architecture plan.

Install

Install from GitHub through your runtime's plugin, marketplace, or package mechanism.

Claude Code

/plugin marketplace add alexei-led/architect
/plugin install architecture@architect

Use --scope project if you want the plugin recorded in project settings.

Codex CLI

codex plugin marketplace add alexei-led/architect
codex plugin add architecture@alexei-led-architect

Or use the Codex UI:

/plugins → Add marketplace → https://github.com/alexei-led/architect → install architecture

Restart Codex after installing or updating plugins.

The Codex custom agent is generated at dist/codex/agents/architect.toml; copy or symlink it into ~/.codex/agents/ or .codex/agents/ when you want subagent spawning.

Pi

pi install git:github.com/alexei-led/architect

Use project scope when the architecture-review package should travel with a repository:

pi install -l git:github.com/alexei-led/architect

Restart Pi or run /reload after installing.

Pi package install loads skills. If you use a Pi subagent loader, symlink dist/pi/agents from the installed checkout into that loader's agent directory.

Helper CLIs

The Python CLIs can be installed directly from GitHub:

uv tool install git+https://github.com/alexei-led/architect.git

Then run:

architect-doctor --repo /path/to/repo
architect-validate-report path/to/report.md
architect-compare-reports base-report.md head-report.md

What it contains

• One architecture-review plugin named architecture.
• A read-only Architect role for assessment, design, and planning, not implementation.
• Design, review, scorecard, and planning skills for the core workflow.
• Methodology skills for Balanced Coupling and architecture fitness functions.
• Tool skills that guide evidence collection with local OSS CLIs.
• Report, design, and plan templates with machine-checkable review contracts; human reports may use Mermaid summaries, while AI-targeted reports stay plain text.
• Helper CLIs for tool coverage checks, report validation, and report comparison.

What it does

A full review follows this order:

1. Capture intended architecture and constraints from the user, docs, ADRs, manifests, and config.
2. Build a system map before judging quality.
3. Gather evidence across discovery, structural, semantic, dependency, change, operational, security, and report dimensions.
4. Score architecture dimensions with a fixed rubric and explicit confidence.
5. Write an architecture report with addressable evidence references.
6. Recommend one primary next skill: usually architecture-design for remediation target-state work, architecture-plan only when an approved design already exists, or no next skill for pure audit.

A design flow follows this order:

1. Read requirements, existing docs, and prior reports.
2. Check existing implementation for drift when code exists; design docs are intent, not proof.
3. Validate the working model with the user.
4. Produce domain, module, integration-contract, test-specification, and fitness-check sections.
5. Self-review the design for coupling imbalances and recommend architecture-plan only when implementation sequencing is requested.

Default user-facing routing:

• Existing-code remediation: architecture-review → architecture-design → architecture-plan → implementation by a mutator/engineer → architecture-review re-check.
• Greenfield or requirements-to-architecture work: architecture-design → architecture-plan when sequencing is requested.
• Pure audit: architecture-review only.
• Already-approved target design: architecture-plan.

Hard boundaries:

• No production source edits by the Architect.
• No finding without evidence.
• No score before the system map.
• No high-quality score on low-confidence evidence.
• No big-bang rewrite plans.

Tools

architect-doctor checks whether useful local analysis tools are available and records gaps as coverage limits, not fatal errors. The skills guide the agent across these tool families: