Adopting Archgate in an Existing Repo

Adopting Archgate in an existing project does not mean rewriting it. Governance is additive: you commit a .archgate/ directory of Architecture Decision Records (ADRs), and from then on every check, CI run, and AI session reads those ADRs as the source of truth. This guide walks the adoption path from a clean repo to enforced governance.

The CLI syntax referenced here is documented authoritatively at cli.archgate.dev — this page focuses on the adoption journey and where each tool fits.

The adoption path

1. Initialize the governance skeleton with archgate init.

2. Author your first ADRs — codify the conventions your codebase already follows. The onboard skill automates this by exploring the repo for you.

3. Verify the ADRs and rules pass against your current code with archgate check.

4. Enforce continuously — wire checks into CI and pre-commit hooks.

5. Evolve — extend governance over time with the lessons-learned and adr-author skills.

Step 1 — Initialize

Run archgate init in the repository root. It creates the .archgate/ directory containing adrs/ (your ADRs and companion .rules.ts rule files) and lint/, and detects your editors so it can offer to wire up the matching plugin.

archgate init

The init flow seeds a placeholder example ADR (GEN-001-example.md) so you can see the format. You will replace it with real ADRs in the next step. See the CLI getting-started guide for every init flag and the exact directory layout.

Note

Commit the .archgate/ directory to version control. It is the shared, reviewable contract for your team — ADRs are human-readable docs and machine-checkable rules in one place.

Step 2 — Author your first ADRs

You have two paths to your initial ADR set. Most teams adopting Archgate into a mature codebase use the guided onboard skill, which discovers conventions automatically rather than asking you to write everything by hand.

Guided (onboard skill)

The onboard skill is the recommended path for an existing repo. Available inside Archgate’s editor plugins (Claude Code, Cursor, VS Code, and others), it onboards a project into governance end to end:

1. Pre-flight — verifies the Archgate CLI is installed.

2. Initialize — runs archgate init if .archgate/adrs/ does not exist yet, and removes the placeholder example ADR.

3. Assess maturity — classifies the repo as greenfield, early-stage, or mature from manifest files, source file counts, and recent git history.

4. Discover — for mature and early-stage repos, parallel explore sub-agents read your toolchain config, source patterns (error handling, imports, naming), and docs to extract the conventions you already follow — without you describing them.

5. Interview — asks at most three targeted questions to fill gaps exploration could not (priority governance domains, any legacy areas or external specs).

6. Propose a backlog — presents a prioritized list of 6–8 ADRs across the relevant domains (architecture, backend, frontend, data, general) for your approval before anything is written.

7. Author — writes every approved ADR (and companion rule files where a decision is objectively checkable), then fixes cross-references between them.

8. Report — prints a governance summary: ADRs created, domains covered, remaining gaps, and next steps.

Run it once, when setting up Archgate for the first time. After the initial set exists, re-running it extends or audits your governance.

Manual (adr-author skill)

If you prefer to write ADRs yourself, or want to capture one specific decision, use the adr-author skill (or the CLI’s ADR commands directly). It follows the same ADR structure the onboard skill produces — Context, Decision, Do’s and Don’ts, Consequences, Compliance, and References — and can create a companion .rules.ts for decisions that are verifiable in code.

This path suits greenfield projects with few existing conventions, or incremental adoption where you document one architectural area at a time.

Document what you already do

The goal of the first ADR set is to ratify the conventions your code already follows, not to impose new ones. Codifying existing patterns means archgate check passes on day one, and the rules start catching regressions immediately — not flagging your whole codebase as non-compliant.

Step 3 — Verify against current code

Once your ADRs exist, confirm their automated rules pass against the repository as it stands today:

archgate check

A clean run means your ADRs accurately describe your codebase. If a rule fails on existing code, you have a decision to make: fix the code, relax the rule, or scope the ADR to apply only to new files. The full flag set (--verbose, --json, --adr, --base, --staged) is documented in the CLI reference.

Step 4 — Enforce continuously

Governance only holds if it is enforced. Layer enforcement so violations are caught as early as possible:

Pre-commit hooks Block violating commits on the developer's machine, before they ever reach the remote.

CI integration Gate pull requests with archgate/check-action — the backstop that blocks merges.

For AI-assisted work, the editor plugins close the loop earlier still: the developer agent reads relevant ADRs before writing code and validates compliance before you commit, so the CI gate rarely fires.

Step 5 — Evolve governance over time

Adoption is the start, not the end. As your architecture changes:

• Use the lessons-learned skill after a development session to capture new learnings and codify them into ADRs or project memory — the final step in the development workflow.
• Use the adr-author skill to document a new decision the onboarding pass did not cover.
• Re-run the onboard skill to extend governance to a new domain (for example, adding data-layer ADRs after introducing a database).

You can also bootstrap with proven conventions from the Archgate ADR registry instead of starting from a blank page — import a curated pack and remap its IDs into your project.

Related

Skills overview The onboard, lessons-learned, and adr-author skills in depth.

Plugins overview Which editors ship the onboarding workflow.

Importing ADRs Start from curated packs in the registry.