---
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
workplan, 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 workplan

```python
create_task(
    workstream_id="<uuid of appropriate workplan 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:
   ```python
   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:
   ```python
   advance_workstation(entity_type="contribution", entity_id="<uuid>", target_workstation="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/`
whose stored workstation/status label is `active`, with tasks in `wait`,
`todo`, or `progress`.

**Ecosystem todos targeting this repo** (Step 1 of orientation) —
`get_state_summary()` returns all open tasks across all workplans. 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/` |
