standards/guides/roundup.md

# Cross-project roundup — orchestration guide

*Substance file per the portability protocol. Vendor wrappers (e.g.
`adapters/claude/commands/roundup.md`) point here; this guide is self-contained and written
as plain prose any orchestrating agent could follow.*

You produce one **portfolio-wide status report** across all of the user's projects: what
each is, where it stands, and every open to-do gathered into a single priority-grouped list
— including items still sitting un-triaged in the inbox, not yet pushed down to any repo.

**Your job is to read and report, not to decide.** Gather faithfully and group by the
priority signals you find; do **not** rank the projects against each other or tell the user
what to work on. Choosing the best use of time is a conversation the user has on top of this
report — your output is the evidence-backed inventory that makes that conversation possible.
You run in the main thread, so after presenting you can help the user reason about ordering
if they ask — but only then, and only with their input.

## Phase 1 — Discover (no deep reading)

- List the candidate projects: the immediate subdirectories of `~/Projects` that are git
  repos (e.g. `ls -d ~/Projects/*/.git`). Skip non-repo folders; note any you skip.
- Include the standards repo — its ROADMAP holds the cross-cutting tooling work — but label
  its items as the meta/tooling layer so they're easy to tell apart from product work.
- Honor any focus the user gave (a subset of repos, or "only P0/P1").

## Phase 2 — Fan out (one read-only reader per repo)

Delegate to a read-only reader subagent per repo (e.g. the `Explore` agent), in parallel
where your tooling allows. Give each the repo path and this exact ask:

> Read only this repo's `AGENTS.md` (especially its `## Current state` section) and
> `ROADMAP.md` if present. Return, compactly: a one-line description; the current state
> (what's done, what's in progress and where it stands); the concrete next steps listed; and
> the ROADMAP backlog items with any priority markers. Quote priorities/labels verbatim; do
> not invent or re-rank. If a file is missing, say so. Read nothing else; do not review code.

Separately, read the inbox yourself: `~/Projects/standards/INBOX.md`. Collect the unchecked
items — these are captured-but-not-yet-triaged, the work that hasn't reached a repo's ROADMAP
yet. Keep `(new)` / `(new:…)` items apart: they're proposed *new* projects, not tasks in an
existing one.

Wait for all readers before synthesizing. If a reader fails or a repo has neither file, note
it honestly rather than dropping the repo.

## Phase 3 — Synthesize (one report → STATUS.md + inline)

Produce ONE report. **Write it to `~/Projects/standards/STATUS.md`**, overwriting the
previous snapshot, **and** show the same report inline in the chat — the file is the durable,
diffable record; the inline copy is for reading right now. Title it with today's date (run
`date +%F`).

Structure (used identically for the file and the inline copy):

```
# Roundup — <date>
Repos scanned: <list>  (skipped/failed: <list with reason>)

## Per-project snapshot
<repo> — <one-line state>; in progress: <…>; next: <…>
... one block per repo, 1–3 lines each ...

## Priority queue (all projects + untriaged inbox)
P0 → P3, every actionable item once, each one line:
[Px] item — source: <repo> | inbox(untriaged) — evidence pointer
Items with no priority signal go under "Unprioritized — needs triage", never dropped.

## Not yet pushed down (inbox)
The untriaged inbox items, grouped by target project — these exist nowhere but the inbox.

## Proposed new projects
The (new)/(new:name) inbox items — ideas awaiting the new-repo bootstrap.

## Gaps
Repos missing AGENTS.md or a Current state; stale-looking states; anything that blocked a reader.
```

## Phase 4 — Persist the snapshot

`STATUS.md` is only a *tracked* snapshot if it's committed — that's the whole point of the
file (a dated history you can diff over time). So after writing it, commit and push **only
that file** to the standards repo, without asking (the same durability reflex as `/capture`):

- `git -C ~/Projects/standards add STATUS.md`
- `git -C ~/Projects/standards commit -m "Roundup snapshot — <date>" -- STATUS.md`
  (the `-- STATUS.md` pathspec commits only the snapshot — never sweep unrelated standards
  changes into a roundup commit)
- `git -C ~/Projects/standards push` (only if a remote is configured; if the push fails,
  report it but don't treat the snapshot as lost — it's committed locally)

This write-and-commit of `STATUS.md` is the *only* thing `/roundup` changes on disk;
everything else — every project repo, every other file — stays strictly read-only.

## Rules

- The only file you may write or commit is `~/Projects/standards/STATUS.md` (the snapshot).
  Every project repo and every other file stays strictly read-only — never edit or commit them.
- Quote priorities and states as found; never re-rank projects or recommend what to do next
  unprompted — that's the user's call.
- Preserve every item; if you can't place one, list it under "needs triage" rather than
  dropping it.
- If a reader fails or a repo can't be read, report it honestly rather than papering over it.
- If blocked, report exactly what blocked you — never guess or fabricate a project's state.