Onboard Skill

The onboard skill bootstraps a project into Archgate governance. It is the first thing you run when setting up Archgate on a repository: it verifies the CLI, initializes the governance skeleton, explores the codebase, interviews you, proposes an Architecture Decision Record (ADR) backlog, authors every approved ADR, and delivers a governance summary.

Run it once

Run onboard a single time per project for the initial setup. Re-run it later to extend governance into new domains or audit existing ADRs — the skill detects existing ADRs and asks which you want.

What It Does

Onboard works through a fixed sequence of phases and does not skip ahead. It determines what it can by exploring the codebase, and only asks you what exploration cannot answer.

1. CLI pre-flight check. It detects your platform (macOS, Linux, or Windows) and verifies the archgate CLI is installed, installing it from the official source if needed.

2. Initialize the skeleton. If .archgate/adrs/ does not exist it runs archgate init. If governance already exists it counts the real ADRs and asks whether you want to extend or audit. It always removes the placeholder example ADR so the GEN-001 slot stays free.

3. Assess repo maturity. Using manifest files, source-file counts, and recent git activity it classifies the repo as Mature, Early-stage, or Greenfield. The tier governs which exploration runs and which questions are asked.

4. Discover (Mature and Early-stage only). It launches three exploration sub-agents in parallel — Stack and Config, Structure and Patterns, and Docs and Intent — each in its own context window so deep file reading never exhausts the parent. Greenfield projects skip straight to the interview.

5. Interview. It asks at most three targeted questions — typically which governance domains are highest priority and whether exploration missed anything. If you provide a URL, it fetches the content and folds it into the ADR context.

6. Prioritize and pre-assign IDs. From the evidence it builds a backlog of 6–8 ADRs, each with a pre-assigned ID, filename, domain, one-sentence rationale, and whether it warrants automated rules. Pre-assigning IDs is what makes parallel authoring safe — no two sub-agents can collide on an ID.

7. Approve the backlog. It prints the full backlog as visible text, then asks you to approve it (via plan mode where available) with auto-accept edits enabled so the parallel writes are not interrupted by per-file prompts.

8. Author in parallel. On approval it spawns one sub-agent per ADR in a single message. Each delegates to the adr-author standard, writes its assigned file (and companion .rules.ts when rules are warranted), and returns its ID and path.

9. Cross-reference fixup. Because ADRs were written in parallel, it reads each new file and adds or repairs the cross-references between topically related ADRs.

10. Report. It prints a governance summary: ADRs created, domains covered, domains not yet covered, open governance gaps, and next steps.

ADR Backlog Selection

The skill maps observed evidence to candidate ADRs, including only what the evidence supports:

Trigger	Domain	Title pattern
Always	general	Tech Stack and Runtime
Test runner detected	general	Testing Standards
Package manager detected	general	Dependency Policy
Clear src/ conventions	architecture	Code Organization
Error handling patterns	backend	Error Handling Pattern
REST/RPC/GraphQL patterns	backend	API Design
Frontend framework detected	frontend	Component Patterns
ORM/DB driver detected	data	Data Access Layer
CI workflows found	architecture	CI/CD Pipeline Standards

The first run is capped at 6–8 ADRs, favoring breadth over depth so the most critical domains are covered first.

Output Format

After authoring, onboard prints a plain-text governance summary:

## Onboarding Complete

### ADRs Created
- <ID>  <title>  (<domain>)
...

### Governance Coverage
Domains covered: <list>
Domains not yet covered: <list>

### Open Governance Gaps
- <Patterns found but not documented, with the reason>

### Next Steps
- Run `archgate check` to verify automated rules pass
- Use the lessons-learned skill after future coding sessions to extend governance
- Use the adr-author skill to document decisions not covered above
- Re-run onboard at any time to extend governance for new domains

It then offers to add a short Archgate governance section to your project’s AI instruction file (CLAUDE.md, .cursorrules/.cursor/rules, .github/copilot-instructions.md, or agents.md) so every future AI session inherits awareness of the governance.

How It Fits the Workflow

Onboard is the entry point — it produces the ADRs that the rest of the system enforces. Once the initial backlog exists, the developer agent reads those ADRs before coding, the reviewer skill validates changes against them, and the lessons-learned skill extends them over time. All ADR writing — in onboard and afterward — runs through the adr-author skill.

adr-author skill The standard every onboard sub-agent follows when writing an ADR.

Note

For the exact syntax of archgate init, archgate adr list, and archgate adr show, see the authoritative reference at cli.archgate.dev.