generated from coulomb/repo-seed
feat(canon): add inter-repo communication standard with todo taxonomy
Establishes the repo boundary rule and a formal vocabulary for classifying work items by scope: - Task: neutral state hub data entity - Todo: a task scoped to the current session's repo/domain - Internal todo: addressed within this repo by this agent - Ecosystem todo: work for another registered repo → state hub task [repo:<slug>] - Third-party todo: work for an upstream repo → contribution artifact (BR/FR/EP/UPR) New dashboard doc: /docs/inter-repo-communication — defines the boundary rule, the full terminology, ecosystem and third-party todo workflows, and a decision table for classifying any piece of work found during a session. Also: - sbom.md: replace verbose inter-repo section with a 3-line summary + link - observablehq.config.js: add "Inter-Repo Communication" to Reference nav - project_claude_md.template: add "### Repo Boundary Rule" section; fix Workplan Convention section (removing incorrect claim that the custodian writes workplan files in other repos — that is the target repo's job) Cross-repo: created state hub task [repo:railiance-bootstrap] for that repo's agent to apply the boundary rule and workplan convention fix to its own CLAUDE.md (task 78d43cb0, workstream 59155efb). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -23,6 +23,7 @@ export default {
|
||||
{ name: "Decision Health", path: "/docs/decisions-kpi" },
|
||||
{ name: "Progress Log", path: "/docs/progress-log" },
|
||||
{ name: "SBOM", path: "/docs/sbom" },
|
||||
{ name: "Inter-Repo Communication", path: "/docs/inter-repo-communication" },
|
||||
],
|
||||
},
|
||||
],
|
||||
|
||||
152
dashboard/src/docs/inter-repo-communication.md
Normal file
152
dashboard/src/docs/inter-repo-communication.md
Normal file
@@ -0,0 +1,152 @@
|
||||
---
|
||||
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
|
||||
|
||||
```python
|
||||
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:
|
||||
```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
|
||||
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/` |
|
||||
@@ -157,19 +157,12 @@ hand-rolled parsers for comprehensive coverage.
|
||||
|
||||
## Inter-repo task communication
|
||||
|
||||
When the State Hub or custodian identifies a compliance gap in a registered repo,
|
||||
the task is communicated through two channels:
|
||||
When a compliance gap is identified in a registered repo, the finding is routed
|
||||
as an **ecosystem todo**: a state hub task with `[repo:<slug>]` in the title,
|
||||
created in the target domain's workstream. The target repo's session protocol
|
||||
surfaces it automatically at next session start.
|
||||
|
||||
1. **State Hub task** — created in the relevant domain workstream with
|
||||
`[repo:<slug>]` in the title. Visible via `get_state_summary()` at the
|
||||
start of any domain session.
|
||||
|
||||
2. **Workplan file** — a `workplans/<ID>-<slug>.md` file is created in the
|
||||
target repo itself (ADR-001 convention). When you open that repo in Claude
|
||||
Code, the session protocol surfaces it.
|
||||
|
||||
When working in a registered repo, always run `get_state_summary()` at session
|
||||
start — the state hub surfaces pending tasks for your domain automatically.
|
||||
See the full standard: [`/docs/inter-repo-communication`](/docs/inter-repo-communication)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -59,6 +59,22 @@ If there are no workstreams at all: follow the First Session Protocol below.
|
||||
|
||||
---
|
||||
|
||||
### Repo Boundary Rule
|
||||
|
||||
This agent is responsible for files **in this repo only**.
|
||||
|
||||
- **Do not** write files or make commits in any other repository
|
||||
- **Do not** create workplan files in other repos on their behalf
|
||||
- When you identify work for another registered repo (**ecosystem todo**):
|
||||
create a state hub task with `[repo:<slug>]` in the title — the other repo's
|
||||
agent will see it at session start and create its own workplan
|
||||
- When you identify work for an upstream repo (**third-party todo**):
|
||||
create a contribution artifact in `contrib/` and register it
|
||||
|
||||
Terminology and workflows: `http://localhost:3000/docs/inter-repo-communication`
|
||||
|
||||
---
|
||||
|
||||
### First Session Protocol
|
||||
|
||||
Triggered when `get_state_summary()` shows **no workstreams** for the `{DOMAIN}`
|
||||
@@ -108,10 +124,10 @@ Work items MUST originate as files in this repo before being registered in the h
|
||||
**Frontmatter required:** `id`, `type: workplan`, `domain`, `repo`, `status`,
|
||||
`state_hub_workstream_id`, `state_hub_task_id` (per task)
|
||||
|
||||
When the custodian creates a task targeting this repo from another session, it:
|
||||
1. Creates a state hub task with `[repo:{REPO_SLUG}]` in the title
|
||||
2. Creates a workplan file in this repo's `workplans/`
|
||||
3. You will see both at session start via the orientation sequence above
|
||||
When another domain's agent identifies work for this repo, it creates a state hub
|
||||
task with `[repo:{REPO_SLUG}]` in the title (an **ecosystem todo**). You will
|
||||
see it at session start via `get_state_summary()`. When you pick it up, create
|
||||
the corresponding workplan file in `workplans/` (ADR-001) and begin work.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user