#+TITLE: Cross-Project Broadcast Workflow
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2026-05-29

* Overview

Fan out a single message to every AI project's inbox in one operation. Discovers projects by fingerprint (any directory with =.ai/protocols.org=) and delivers via the existing =inbox-send.py= per-target. The point is announcing a new capability or shared change once, instead of hand-walking 20+ projects.

* When to Use This Workflow

User triggers:

- "broadcast this to every project"
- "notify every project about <thing>"
- "fan out this announcement"
- "let every project know X is available"

Automatic invocation:

- *New machine-global capability landed.* A new script in =~/.local/bin/=, a new MCP server registered, a new tool installed (e.g. =signal-cli=, =page-signal=). Projects need to know it's available so their agents can use it.
- *Shared rule or protocol change.* When a change to =claude-rules/= or =claude-templates/.ai/= materially affects how every project's agent should behave, broadcast a heads-up so the next session of each project picks it up explicitly rather than discovering it on rsync.
- *Deprecation notice.* When a script, workflow, or rule is going away, give every project a chance to migrate before the removal lands.

* When NOT to Use This Workflow

- *Project-specific work.* A handoff intended for one project goes through =inbox-send= directly, not broadcast.
- *Routine status updates.* The session log and todo.org cover routine work. Broadcast is for capability- or rule-level changes.
- *Bulk noise.* Every broadcast adds N inbox files. Use sparingly; ask whether projects actually need to know.

* The Workflow

** Phase A — Discover targets

Run the discovery helper:

#+begin_src bash
python3 .ai/scripts/cross-project-broadcast.py --list
#+end_src

The helper scans =~/code/=, =~/projects/=, =~/.emacs.d= for any directory containing =.ai/protocols.org=. Prints the basename and full path of each, in sender-excluded order (the current project never receives its own broadcast).

** Phase B — Compose the message

Write the broadcast body to =/tmp/broadcast-<topic>.org=. Required structure:

#+begin_example
,#+TITLE: <one-line summary>
,#+DATE: YYYY-MM-DD
,#+SOURCE: <sender project name>

,* What's new

<two to five sentences: the capability, rule, or change being announced.>

,* How to use it

<two to five lines: the concrete invocation, command, or path. Code examples in =#+begin_src= blocks. No prose walls.>

,* Why this matters / when to use

<two to four sentences: the user-facing rationale and the discrimination rule for when the new thing applies vs. when existing alternatives suffice.>

,* Action required

<one of:>
- =FYI=, no action required (most broadcasts)
- =Update workflow X= to reference the new capability
- =Deprecate workflow Y= by date Z
#+end_example

The structure is rigid on purpose. Every project's next session has to read 20+ broadcasts as efficiently as possible. The standard headings let the agent scan in seconds.

** Phase C — Confirm scope with the user

Surface the discovered project list and the message inline. Ask:

#+begin_example
Broadcast scope:
- Target projects: <N> (list)
- Message: <2-line summary>
- Action required: <FYI / update workflow / deprecation>

1. Send to all <N> targets (recommended)
2. Exclude specific projects (name them)
3. Cancel — message stays at /tmp/broadcast-<topic>.org
#+end_example

** Phase D — Fan out

Run the broadcast helper with the composed message:

#+begin_src bash
python3 .ai/scripts/cross-project-broadcast.py \
    --file /tmp/broadcast-<topic>.org \
    [--exclude project1 --exclude project2 ...]
#+end_src

The helper iterates over targets, runs =inbox-send.py <target> --file <broadcast>= per target, captures success/failure per project. The =from-<sender>= prefix in the resulting filename traces provenance.

** Phase E — Report

Summarize the fan-out:

- Total targets discovered
- Sent successfully (count)
- Failed (list with reason)
- Excluded (list with reason)

If any failures, surface them — silent failure on a broadcast means some projects never learn about the change.

** Phase F — Cleanup

Delete =/tmp/broadcast-<topic>.org=. The content lives in each target's inbox now.

* Common Mistakes

1. *Broadcasting project-specific work.* Each broadcast costs N inbox files across the fleet. Routine handoffs go through =inbox-send= directly.
2. *Skipping Phase B's structure.* Free-form broadcasts force every recipient to parse them differently. Use the rigid headings.
3. *Sender-includes-itself.* The discovery helper excludes the sender automatically. Don't override it — broadcasting to your own inbox creates a self-reply loop.
4. *Forgetting Phase E.* A broadcast that partially succeeded is the failure mode you'll never notice. Always check the per-target results.
5. *Broadcasting without an "Action required" line.* Recipients need to know whether this is FYI or whether their project has to do something. The line is non-optional.
6. *Using broadcast as a substitute for documentation.* Capability announcements should be paired with a rule or workflow update so the next-next session can rediscover the capability from canonical docs, not from a stale inbox file.

* Living Document

If the discovery roots change (a new top-level directory for AI projects), update =cross-project-broadcast.py='s =SEARCH_ROOTS=. If the per-broadcast structure proves too rigid or too loose, tune Phase B. If the recipient projects start complaining about broadcast noise, the rule is "broadcast less," not "structure broadcasts harder."