Archkeel

View saved version →

---
name: archkeel
description: Use when setting up or changing architecture rules, or checking architecture before submitting code, in a repository that uses Archkeel.
---

# Archkeel

Archkeel is a deterministic architecture checker. It observes Python, TypeScript and Dart imports, evaluates a
declared contract of components and rules against that observation, and distinguishes
PASS, FAIL and UNKNOWN. Rules live in `architecture-contract.json` and its explicit nested
contracts; nothing is enforced by convention alone.

## Onboarding (first time in this repository): a target, not a description

`architecture-contract.json` is the target architecture — where the system should be, not
where the code already is. `archkeel report` measures declared constraints, not the quality
of the whole architecture. The architect owns the target and review scope; within that scope,
inspect the physical structure at every depth, not just the top level. Support them with evidence
from the repository and the architect's quality goals for this codebase (which components
must scale, stay easy to change, or are performance-critical). Read those goals from ADRs
and architecture documents first; ask the architect only when a goal is unknown and would
change your recommendation. Every
recommendation and every rationale cites the goal it rests on. There is no contract field
for a quality goal: record it next to the rule it justifies, following the chosen decision
mode below.

For requested first-time onboarding, inspect existing files, then run
`archkeel init [--root DIR] [--source DIR] [--namespace NAME] [--force] [--json]` once.
A read-only assessment uses existing contracts, reports and source; it does not authorize
initialization, contract edits, file moves or commits.
Preserve existing contracts and their `inside` references. If onboarding files already exist,
continue from them; do not use `--force` without explicit approval to replace those files.
`init` detects the Python package (the only top-level one, or the one `pyproject.toml`'s
`[project] name` names when a test package sits beside it; otherwise it exits 2 and asks for
`--source` and `--namespace`), requires an existing Git repository with at least one
commit, and writes three files: `archkeel.toml`, `architecture-contract.json` (one component
per top-level subpackage/module, plus `complete_assignment` and — only when no component
cycle exists — `no_component_cycles`, and `interface_boundary` when it drafts public
interfaces; no dependency rule), and
`docs/architecture/architecture.md` (component table, each component's modules and inner
edges, and a Mermaid graph of observed edges).
Every rule `init` drafts carries `decided_by: "agent"` as a placeholder you must resolve, not
an answer, and so does every component whose `public` list it drafted. It refuses to overwrite existing files without `--force`.

`init` does not infer a foundation or decide where classes belong. Ask who owns a shared type
first; foundation is not the default owner for domain enums or models. Record the architect's
choice with the existing `symbol_placement` rule: set `source` to the package, `class_kinds` to
the types it owns, and `exact_sources` to the chosen module (or `allowed_sources` to a package
subtree). Follow the ownership example in the target-first guide. Run `archkeel validate` after
adding it; a misplaced matching class is a `rule.violated`.

For TypeScript, use `archkeel init --language typescript --source src --namespace app
--tsconfig tsconfig.json`; for Dart, use `archkeel init --language dart --source lib
--namespace app`. Repeat `--source` for multiple roots. A non-empty namespace initializer
requires explicit ownership via `exact_modules`; inspect it before recording the owner.
`init` shows DRAFT while its completed scan remains PASS. Review measured
`measurements.scalars.cycle_edges`: a cyclic component graph receives no drafted
`no_component_cycles` rule. Cycles are an advisory, not an error d

Preview of the first 4,000 characters. Read full instructions →