> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mutagent.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboard your project

> Set up an existing repository or a new project for local Architech sessions.

> [!NOTE]
>
> **Early Access.** Commands and behavior can change between releases.

**1. Open your project**

Run `architech` in your project directory, then type:

```text theme={null}
/onboard
```

Onboarding sets up your project locally; it deploys nothing to Cloud. The orchestrator, agents and
skills ship inside Architech, so onboarding doesn't copy them into your project.

**2. Choose your project and board**

Architech asks whether this is a new project or existing code, which GitHub Project board to use
(or whether to skip it), and whether it may scan your repository to draft context and rules. It
never scans without your permission. Review the proposed context before you accept it.

**3. Review the proposed changes**

Onboarding writes project memory, engineering rules, a record of your intent and setup, and
ignore entries. It never overwrites context you wrote. Declared exemptions and inheritance are
respected; onboarding doesn't scaffold a file your context rules already account for.

> [tab] Configure a board
>
> Onboarding writes `.architech/factory/factory.yaml` (with `mode: local`, your board,
> repositories, label roles, issue naming and merge policy) and one pointer in `CLAUDE.md`.

> [tab] Skip the board
>
> Onboarding writes neither the factory file nor the `CLAUDE.md` pointer. It doesn't add issues
> to a board or create board labels.

Before writing the board setup, onboarding shows you a diff. Once you approve, it commits the
factory file and the pointer together, and nothing else. If there is no `CLAUDE.md`, it creates
one that holds only the pointer. It won't write through a symlinked `CLAUDE.md`; follow the
onboarding message to add the pointer yourself.

You can run onboarding again later to add a board. Without a board, Architech still works for
local software work.

**4. Review the result**

Read the onboarding report and do any manual steps it lists. If you picked a board, review
`factory.yaml`: its repository list is the scope of board work, not every repository your
organization owns. Check its `context:` block too: it records which repositories inherit, require
or don't need rules and memory. With no factory file, that configuration lives in
`.architech/context-rules.yaml`.

## What onboarding keeps

Onboarding sets up the factory, then writes down what matters in
**`.architech/onboarding/context.md`**:

* **Goals** — your intent: what the project is and who it is for.
* **Spec and ideation** — the general specification and ideas you shared.
* **Setup** — the setup choices; this section is regenerated.
* **Your own sections** — decisions and important details you add are kept.

Setup choices that onboarding reads back live in the note's frontmatter. Configuration belongs in
`factory.yaml`'s `context:` block (or `.architech/context-rules.yaml` without a factory), not in this
note. There is no `onboarding:` configuration block in `factory.yaml`.

Onboarding uses `.architech/ONBOARD-PLAN.json` only as temporary, gitignored scratch state.
Completion writes the record, reads it back and removes the plan; later choices update the record
instead of recreating a permanent plan file.

To record your intent and general specification from the shell:

```bash theme={null}
architech-onboard detect --intent "A billing API for small teams" --spec "Usage-based invoices with team approval"
```

[Memory and rules](https://docs.mutagent.io/architech/features/memory-and-rules.md) explains what belongs in each repository.
[Context management](https://docs.mutagent.io/architech/features/context-management.md) shows how to exempt generated code,
inherit standards or require files. Missing context proceeds with a warning and a recommended
action; only an explicit `required` holds the code-writing step that needs it, never a review.

> [card] [Orchestrator and agents](https://docs.mutagent.io/architech/agents.md)
>
> Who plans, builds and reviews the work.

> [card] [Factory quickstart](https://docs.mutagent.io/factory/quickstart.md)
>
> Start from your local factory file, then decide whether to move to Cloud.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.