Files

tegwick d7c4bd5802 feat(onboarding): redesign repo integration journey

custodian_cli.py:
- register-project now writes CLAUDE.custodian.md (suggestion) instead
  of overwriting CLAUDE.md; includes preamble with integration instructions
- registers repo via POST /repos/
- creates a "Repo Integration: {slug}" workstream in the domain's topic
  with 4 onboarding tasks (integrate CLAUDE.md, first workplan, SBOM,
  EPs/TDs); checks for existing workstream to be idempotent
- fixes {REPO_SLUG} template substitution (previously missing)

dashboard:
- repos.md: fetches workstreams; detects active repo-integration-* slugs;
  adds "Integrating" KPI card; shows ⚙ integrating badge per repo in
  coverage map and table; replaces "How to Ingest a Repo" with
  "Onboard a New Repo" 4-step panel with doc help button
- docs/repo-integration.md (new): full collaboration model doc — custodian
  as coach, repo agent as executor; journey, generated tasks, first session
  protocol, ongoing relationship
- docs/repos.md: links to new repo-integration doc; updates "What is a
  managed repo?" section; adds onboarding quick reference
- docs/reference.md: fix latent build error — code examples were in ```js
  fences (executed by OF); changed to ```javascript (display only)
- observablehq.config.js: adds "Repo Integration" to Reference nav

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

2026-03-02 08:42:30 +01:00

2.8 KiB

Raw Blame History

title

title
Repos — Reference

Repos — Reference

The Repos page shows every repository registered in the Custodian ecosystem, their SBOM ingestion status, and a domain-grouped coverage map.

What is a managed repo?

A managed repo is a git repository that has been registered with the state hub via custodian register-project or register_repo(). Registration records the repo's slug, domain, local path, and optional remote URL. Once registered, the repo receives a CLAUDE.custodian.md integration suggestion, an onboarding workstream with 4 tasks for the repo agent, and is eligible for SBOM ingestion and the ADR-001 workplan validator.

For the full onboarding journey see Repo Integration.

KPI row

Card	Meaning
Registered Repos	Active repos only (status = active)
Domains	Count of distinct domain slugs across registered repos
SBOM Ingested	Repos with at least one SBOM snapshot
SBOM Gaps	Repos with no ingested SBOM — red border when > 0

Coverage Map

Groups repos by domain. Each domain block shows:

Domain name with SBOM, EP, and TD chip indicators
SBOM chip — green ✓ if all repos in the domain are ingested, amber ⚠ if any gap exists
EPs chip — count of open/in-progress extension points for this domain
TDs chip — count of open/in-progress technical debt items for this domain
Repo table — one row per repo with SBOM status, package count, and local path

Rows with no SBOM are highlighted in amber.

Filters

Filter	Effect
Domain	Show repos for a single domain only
Gaps only	Toggle to show only repos without an ingested SBOM

Onboarding a new repo

See Repo Integration for the full journey.

Quick reference:

# From the repo root — registers, writes CLAUDE.custodian.md, creates onboarding tasks
custodian register-project --domain <slug>

Ingesting a repo's SBOM

# Auto-detects lockfile at repo root
cd ~/the-custodian/state-hub
make ingest-sbom REPO=<slug> REPO_PATH=/absolute/path

# Multi-ecosystem repo — scan all lockfiles recursively
make ingest-sbom REPO=<slug> SCAN=1 REPO_PATH=/absolute/path

Supported lockfile formats: uv.lock, requirements.txt, package-lock.json, yarn.lock, Cargo.lock, .terraform.lock.hcl.

Infra-only repos

Repos with no lockfile (Ansible, shell scripts) can be registered for inventory purposes. The SBOM gap is expected and can be left as-is. Terraform providers are auto-detected via .terraform.lock.hcl when using --scan.

SBOM snapshots are replaced on each ingest — not appended. The last ingestion timestamp is recorded on the managed_repo row.

2.8 KiB Raw Blame History