the-custodian/state-hub/dashboard/src/docs/repo-integration.md

---
title: Repo Integration — Reference
---

# Repo Integration

This page describes how a new repository is onboarded into the Custodian
ecosystem and how the custodian and the repo's own Claude agent collaborate
during and after integration.

---

## The Collaboration Model

The custodian acts as a **coach**: it registers the repo, writes an
integration suggestion, and generates a structured set of onboarding tasks.
The repo's own Claude agent acts as the **executor**: it reads those tasks,
makes all changes to the repo, and closes out the onboarding workstream.

| Role | Responsibility |
|------|---------------|
| **Custodian** | Registers the repo, generates `CLAUDE.custodian.md`, creates the onboarding workstream and tasks, monitors integration status via the dashboard |
| **Repo agent** | Integrates `CLAUDE.custodian.md` → `CLAUDE.md`, writes the first workplan, ingests the SBOM, catalogues EPs/TDs, closes the onboarding workstream |

The custodian never writes files into another repo directly. All changes to
the target repo are made from inside that repo by its own agent. This upholds
the [repo boundary rule](/docs/inter-repo-communication).

---

## The Registration Journey

### Step 1 — Clone the repo locally

```bash
git clone <remote-url> /path/to/repo
```

### Step 2 — Register from the repo root

```bash
cd /path/to/repo
custodian register-project --domain <slug>
```

The `--domain` flag is required. Run `custodian status` to list valid domain
slugs. The command takes about five seconds and produces no interactive
prompts.

What happens automatically:
1. The API is health-checked
2. The domain is validated; the domain's topic ID is resolved
3. `CLAUDE.custodian.md` is written to the repo root — the integration suggestion
4. The repo is registered in the State Hub (`POST /repos/`)
5. A **Repo Integration** workstream is created in the domain's topic with 4
   onboarding tasks
6. A progress event is logged

### Step 3 — Open the repo in Claude Code

```bash
cd /path/to/repo
claude
```

The repo agent starts, calls `get_domain_summary("<domain>")`, and sees the
Repo Integration workstream. It works through the 4 onboarding tasks
autonomously. No human interaction is needed unless the agent has a question.

### Step 4 — Monitor on the Repos page

The [Repos](/repos) page shows each repo's integration status. An **integrating**
badge appears on repos with an active Repo Integration workstream. The badge
clears when the workstream is marked completed.

---

## What the Registration Creates

### `CLAUDE.custodian.md`

A suggestion file written to the repo root. It contains the full State Hub
session protocol, First Session Protocol, workplan convention, contribution
tracking instructions, and SBOM guidance — pre-filled with the repo's domain,
topic ID, and slug.

The repo agent integrates this content into the existing `CLAUDE.md` (or
creates a new one) and deletes the suggestion file. It is not meant to persist.

### Repo Integration workstream

A workstream titled **Repo Integration: `<repo-slug>`** is created in the
target domain's topic. It is visible via `get_domain_summary()` at the repo
agent's next session start.

> **ADR-001 note:** This workstream is a DB-first bootstrapping exception.
> The file-first principle does not apply here because the repo has no
> `workplans/` directory yet. Writing the first workplan file is task T2.

### 4 Onboarding tasks

| # | Title | Priority | What it means |
|---|-------|----------|---------------|
| T1 | Integrate `CLAUDE.custodian.md` → `CLAUDE.md` | high | Merge the suggestion into the existing CLAUDE.md; delete the suggestion file; commit |
| T2 | Write first workplan and initialise `workplans/` | high | Create `workplans/` and write the first workplan file per ADR-001; register the workstream in the hub |
| T3 | Ingest SBOM | medium | Run `make ingest-sbom REPO=<slug> SCAN=1 REPO_PATH=<path>` from the state-hub dir |
| T4 | Register known EPs and TDs | low | Catalogue extension points and technical debt using the MCP tools |

---

## Repo Agent: First Session Protocol

When `get_domain_summary()` returns a **Repo Integration** workstream, the
repo agent should:

1. Read `CLAUDE.custodian.md` alongside the existing `CLAUDE.md`
2. Execute T1 first — merge and delete the suggestion file, commit
3. Execute T2 — create `workplans/<DOMAIN>-WP-0001-<slug>.md` covering the
   primary near-term work; register the workstream in the hub via MCP
4. Execute T3 — ingest the SBOM so the repo appears green on the Repos page
5. Execute T4 — a quick scan for obvious EPs/TDs; defer if nothing obvious
6. Mark each task `done` in the hub as completed
7. Mark the Repo Integration workstream `completed`
8. Log a progress event summarising the integration

The agent should resolve each task independently and in order. It does not
need human approval for any of these steps unless it encounters an ambiguous
merge conflict in CLAUDE.md.

---

## After Integration

Once the onboarding workstream is closed, the repo participates in the full
custodian ecosystem:

- **Session start:** `get_domain_summary("<domain>")` shows active workstreams,
  blocking decisions, and recent progress — the standard orientation
- **Ecosystem todos:** tasks with `[repo:<slug>]` in their title created by
  other agents appear in the domain summary and signal cross-repo work
- **Contributions:** outbound upstream work is tracked in `contrib/` and
  registered via `register_contribution()`
- **SBOM:** re-ingest after dependency updates with `make ingest-sbom`
- **Session close:** `add_progress_event()` keeps the hub's episodic memory
  current

See the [Inter-Repo Communication](/docs/inter-repo-communication) reference
for task routing conventions.

---

## Troubleshooting

**`custodian: command not found`**
The CLI is installed via `make install-cli` from the state-hub directory.
Ensure `~/.local/bin` is on your `PATH`.

**`ERROR: Cannot reach API`**
The state hub API must be running: `cd ~/the-custodian/state-hub && make api`

**`CLAUDE.custodian.md` already exists**
Re-running `custodian register-project` overwrites it with a fresh
suggestion. The repo agent should integrate and delete it.

**Repo already registered (slug conflict)**
The command is idempotent for the repo row. Onboarding tasks are re-created
only if no active Repo Integration workstream already exists.