diff --git a/dashboard/observablehq.config.js b/dashboard/observablehq.config.js index 2b0ff54..94ffd25 100644 --- a/dashboard/observablehq.config.js +++ b/dashboard/observablehq.config.js @@ -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" }, ], }, ], diff --git a/dashboard/src/docs/inter-repo-communication.md b/dashboard/src/docs/inter-repo-communication.md new file mode 100644 index 0000000..143d690 --- /dev/null +++ b/dashboard/src/docs/inter-repo-communication.md @@ -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:]` | +| **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/` | diff --git a/dashboard/src/docs/sbom.md b/dashboard/src/docs/sbom.md index 788614b..a60694f 100644 --- a/dashboard/src/docs/sbom.md +++ b/dashboard/src/docs/sbom.md @@ -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:]` 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:]` in the title. Visible via `get_state_summary()` at the - start of any domain session. - -2. **Workplan file** — a `workplans/-.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) --- diff --git a/scripts/project_claude_md.template b/scripts/project_claude_md.template index 8d42352..30c787d 100644 --- a/scripts/project_claude_md.template +++ b/scripts/project_claude_md.template @@ -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:]` 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. ---