streams
Skill0 starsChanged 2 months agoApache-2.0View on GitHub
The parallel-work janitor. Lists every active /contribute + /review + probe-run stream from state/active-streams.yaml, reconciles each against the LIVE working trees (never the records), flags STALE / ORPHANED streams, and offers resume / reclaim / discard — with the invariant that no resource is reclaimed until its work is captured. Run it to see what is in flight, to pick a non-colliding namespace before starting a stream, or to clean up after abandoned work.
In this repository27 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- alignSkill
- code-walkSkill
- conceptsSkill
- contributeSkill
- coverageSkill
- doc-gap-checkSkill
- enrichSkill
- enumerateSkill
- find-implicit-adrsSkill
- implementSkill
- ingest-docsSkill
- log-issueSkill
- navigateSkill
- next-batchSkill
- orientSkill
- panelSkill
- probe-defineSkill
- probe-runSkill
- probeSkill
- reflect-featureSkill
- retrieveSkill
- reviewSkill
- scanSkill
- statusSkill
- test-coverageSkill
- triageSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 19
Read state/active-streams.yaml.
- Distinctive: line 83
Capture before reclaim: No worktree is removed and no branch is deleted until its work is pushed or parked.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/streams — the parallel-contribution janitor
You maintain state/active-streams.yaml as the live coordination substrate for every parallel stream, and
you garbage-collect abandoned work. The operating model is adrs/drafts/parallel-contribution-operating-model.md;
the protocol every stream follows is playbooks/stream-coordination.md; the resource inventory is
adrs/drafts/parallel-contribution-infra.md (R1-R9 / O1-O10). This skill is the read + reconcile + GC view.
$ARGUMENTS: empty → the full dashboard. <stream-id> → focus one stream. gc → run the reclaim sweep.
1. Read + verify-live (never trust the record — O4/O8/O9)
Read state/active-streams.yaml. For every entry, re-derive the truth from the working trees and docker —
a record is a claim, the tree is the truth:
git -C ../odd-platform rev-parse HEAD+--abbrev-ref HEAD+git status --porcelain(vs the recordedhead/branch).- the same for
../documentationand every../odd-platform-<id>worktree (git worktree list). git -C ../odd-platform status lineage/+ theprobe_run_idinlineage/odd-platform/feature-flows.yaml(who actually holds the R9 lineage lock — never guess a stream; O8).docker ps(which<id>-*/probe-*stacks + ports + images are live) — a<id>-*orprobe-*stack whose<id>has no LIVE entry is an ORPHAN stack (a crashed/manual run that skipped teardown) → GC it (§3).cat state/locks/heavy-e2e.holder— the flock holder of the serialized heavy-e2e lock (the authoritative "who is running the full regression right now"; absent = the lock is free; seerun-regression.sh).
Reconcile the registry to what you observe: fix stale heads, wrong lock holders, and the unowned_dirty_state
block. Stamp each touched entry with a verified-at. Commit the reconciliation (explicit path, atomic).
2. Classify each stream
- LIVE —
updatedwithin the heartbeat window (default 4h) and a non-terminalphase; its worktree + stack match the record. Leave it; just report. - STALE —
updatedolder than the window AND a non-terminalphase(intake…pr-pending). The session likely ended mid-flight. Candidate for resume/reclaim. - ORPHANED — a worktree / contrib branch / held port / image tag with no registry entry, OR an entry
whose isolation no longer exists on disk. Also:
unowned_dirty_state(dirty paths no entry claims — e.g. a probe-run'slineage/**residue, a stray spec). Surface it; never sweep it (O10). - COMPLETE — terminal (
merged/done/blocked/review-complete). Should already be cleared; clear it.
3. Offer per STALE / ORPHANED stream (the GC) — gc mode
For each, present the options; never act destructively without the work captured or an explicit discard:
- resume — the worktree + branch + record are intact; print the exact commands to re-attach (the
cd ../odd-platform-<id>, the SUT tag, the ports) and the next pending DoD gate. Nothing is reclaimed. - reclaim — free the namespace only after the work is captured (the contrib branch is pushed to origin,
or its uncommitted diff is saved to
state/abandoned/<id>.patchwith a one-line provenance header and surfaced). Then free, in order: tear down its stack —docker compose -p <id> -f lineage/_extractor/probe-stacks/odd-minimal.docker-compose.yml down -v(containers + network + volume; the backstop for a run that crashed beforerun-regression.sh's teardown trap fired) — drop the image tag (docker image rm odd-platform:odd-team-sut-<id>), remove the worktree, release the ports, clear the registry entry. Print what was captured + where before freeing anything. - discard — maintainer-confirmed only. Even then, save the diff to
state/abandoned/<id>.patchfirst (a discard is recoverable for one release cycle), then free the namespace.
The invariant (non-negotiable): abandoned work is never silently lost and never silently blocking. Every reclaim either pushes the branch or parks the patch; every discard parks the patch and is human-confirmed.
4. The dashboard (default, no args)
Print a compact table: id · role · work-item · phase · LIVE/STALE/ORPHANED · isolation (worktree/image/ports)
· lineage-lock? · last-verified. Then:
- Next-free namespace — the lowest unused stream id pattern + the next free port pair + the next image tag,
so a starting stream can copy them (the
shared_resources.next_freevalues, re-derived live). - Serialized-resource status — who holds
lineage/**(R9); the heavy-e2e flock (cat state/locks/heavy-e2e.holder— the authoritative one-at-a-time holder thatrun-regression.shacquires, G-C2); and thewants: e2equeue order. - GC candidates — the STALE/ORPHANED list with the recommended action each.
Rules
- Verify live over record, always (O4/O8/O9). If the registry and the tree disagree, the tree wins; fix the registry.
- Never sweep what you do not own (O10). Unowned dirty state is reported for its owner to reconcile; this
skill does not
git checkout --/git add/ revert another stream's paths. The single exception is a human-confirmeddiscard, and even then the diff is parked first. - Capture before reclaim. No worktree is removed and no branch is deleted until its work is pushed or parked.
- Atomic registry commits (explicit path; never
git add -A— R5/O3). - This skill is read-mostly + reconcile; it does not run builds, suites,
/enrich, or pushes of code. It curates the coordination substrate so the other skills run safely in parallel.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

