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

title

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.

---

The Registration Journey

Step 1 — Clone the repo locally

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

Step 2 — Register from the repo root

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 and run /init

cd /path/to/repo
claude

Once Claude starts, run /init to trigger the integration. The repo agent reads CLAUDE.custodian.md, calls get_domain_summary("<domain>"), sees the Repo Integration workstream, and 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 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 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.