--- 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:]` | | **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 ```python create_task( workstream_id="", title="[repo:] 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:]` 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:]` 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------.md` - `feature-requests/fr-YYYY-MM-DD------.md` - `extension-points/EP--NNN------.md` - `upstream-prs/upr-YYYY-MM-DD------.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="") ``` 3. When submitted upstream, close the loop: ```python update_contribution_status(contribution_id="", 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:]` 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:] ...")` | | 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/` |