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

title

title
Inter-Repo Communication

Inter-Repo Task Communication

This document defines the boundary rule for Claude Code agents within this ecosystem, the terminology for classifying work items by their scope, and the workflows for routing work to the correct owner.

---

The Repo Boundary Rule

A Claude Code agent is bounded to the repository it was started in.

Permitted	Prohibited
Read, write, and commit files anywhere inside the repo root	Write files or make commits in any other repository
Create state hub tasks targeting another repo	Create workplan files in another repo on its behalf
Create contribution artifacts for third-party repos	Directly edit code that originates from another repo

Why this matters: each registered repo has its own Claude agent that owns its working directory. Cross-repo direct writes bypass that agent's awareness, context, and responsibility. The agent for the target repo is the one with the full session context for that codebase — it should create its own workplan and make its own decisions about how to carry out the work.

When you identify work that belongs to another repo, route it through the appropriate coordination channel (see below). Do not write the files yourself.

---

Terminology

Task

A task is the state hub data entity encapsulating a suggested or required piece of work. Tasks live in the state hub database, are always scoped to a workstream, and are the universal unit of cross-repo coordination. Tasks are neutral — they describe what should be done, not who does it or where.

Todo

A todo is a task viewed from the perspective of a specific repo or domain session. When you run the session protocol and review open work, you are reviewing your todos: the tasks that are relevant to the current scope.

Todos are classified by where the work belongs:

Todo
├── Internal todo   — addressable within the current repo by this agent
└── External todo   — requires action outside the current repo
    ├── Ecosystem todo   — target is a repo registered in the Custodian ecosystem
    └── Third-party todo — target is an upstream repo we don't own or control

Class	Definition	Mechanism
Internal todo	Work fully addressable within this repo	Create workplan, begin work
Ecosystem todo	Work for another registered repo	State hub task with [repo:<slug>]
Third-party todo	Work for an upstream repo we don't own	Contribution artifact (BR/FR/EP/UPR)

---

Ecosystem Todo Workflow

Use this when you identify work that belongs to another repo registered in the Custodian State Hub.

Step 1 — Create a state hub task in the target domain's workstream

create_task(
    workstream_id="<uuid of appropriate workstream in the target domain>",
    title="[repo:<target-slug>] Brief description of the required work",
    priority="medium",   # low | medium | high | critical
    description="Full context: why this work is needed and what the expected outcome is"
)

The [repo:<slug>] prefix in the title is mandatory. It is the signal that the target repo's session protocol uses to surface this task automatically.

Step 2 — The target repo's agent picks it up

When a Claude Code session opens in the target repo:

1. get_state_summary() runs at session start
2. The session protocol scans for tasks containing [repo:<slug>] in their title
3. Matching tasks appear in the orientation brief
4. The target repo's agent creates a workplan file locally (ADR-001) and begins work

Do not create the workplan file in the target repo yourself. The target repo's agent is responsible for its own workplans. Your job is to place the task where that agent will find it.

---

Third-Party Todo Workflow

Use this when you identify work for an upstream repo — a library, tool, or framework you use but do not own.

1. Create a contribution artifact in the current repo's contrib/ directory:
   • bug-reports/br-YYYY-MM-DD--<org>--<repo>--<slug>.md
   • feature-requests/fr-YYYY-MM-DD--<org>--<repo>--<slug>.md
   • extension-points/EP-<DOMAIN>-NNN--<org>--<repo>--<slug>.md
   • upstream-prs/upr-YYYY-MM-DD--<org>--<repo>--<slug>.md
2. Register it with the state hub:

   register_contribution(type="br|fr|ep|upr", title="...", target_org="...",
       target_repo="...", body_path="contrib/...", related_workstream_id="<uuid>")
   

3. When submitted upstream, close the loop:

   update_contribution_status(contribution_id="<uuid>", status="submitted")
   

Templates: ~/the-custodian/canon/standards/contrib-templates/ Convention: ~/the-custodian/canon/standards/contribution-convention_v0.1.md

---

Session Protocol: Surfacing Todos

The session orientation protocol (every repo's CLAUDE.md) surfaces todos from two sources:

Internal todos (Step 2 of orientation) — workplan files in workplans/ with status: active, tasks with status: todo or in_progress.

Ecosystem todos targeting this repo (Step 1 of orientation) — get_state_summary() returns all open tasks across all workstreams. The session protocol filters for tasks with [repo:<this-slug>] in their title and surfaces them in the orientation brief.

Both sources are combined in Step 3 (orientation output).

---

Decision Table

Situation	Classification	Action
Found a bug in this repo	Internal todo	Fix it; no cross-repo coordination needed
Found a config gap in another registered repo	Ecosystem todo	create_task(..., title="[repo:<slug>] ...")
Identified a feature needed in a library you use	Third-party todo	Create FR artifact in contrib/feature-requests/
Found a bug in an upstream tool	Third-party todo	Create BR artifact in contrib/bug-reports/
Want to propose a patch to an upstream repo	Third-party todo	Create UPR artifact in contrib/upstream-prs/
Identified an extension opportunity in an upstream repo	Third-party todo	Create EP artifact in contrib/extension-points/