Imported from lbliii/orrery (AGENTS.md). Install upstream with npx skills add lbliii/orrery. Copyright stays with the author.

AGENTS.md

How to work on this repo with agents.

Default: you talk to the orchestrator (this chat). It reads the board, plans, and delegates planner/worker work to subagents. You should not have to say claim #N unless you want a single-leaf escape hatch.

Invariant: Workers claim only GitHub issues labeled leaf and ready. Planners own saga / epic / design. Do not re-decide ADRs in a leaf.

Simple invokes

If you give a goal in plain language (“push tree-handling”, “clear wave:1 ready queue”), treat it as swarm with that scope — not a request that you micro-claim leaves.

Orchestrator mode (default contract)

The parent agent in this chat is the orchestrator. It does not implement every leaf itself when parallel work is possible.

Responsibilities (parent)

1. Board — gh summary: ready / blocked / open designs; pick the active saga/epic (default bias: #237 tree-handling, then #124, #160, #1).
2. Plan gate — If ready queue is empty or leaves lack owned paths, run or delegate planner work first (burndown / plan #N / triage).
3. Delegate workers — For each leaf+ready in scope (respect caps), launch a Task subagent with the worker contract below. Prefer parallel subagents when owned paths do not overlap.
4. Integrate — Track PRs, merge when asked (or when you said “drive to merge”), close issues, drop ready on close, refresh the board, report status in plain language. Prefer fixing worker CI (often ruff) in-branch over re-delegating the whole leaf.
5. Stop conditions — Hit the turn/leaf cap, empty ready queue, path conflict, or user interrupt. Caps are intentional pauses — stop and report the next ready leaf; do not fake-unblock to keep the swarm busy.

Caps (per orchestrator turn unless user overrides)

Plan gate bias: A closed design/ADR that unblocks many leaves beats shipping one more half-specified worker. Prefer planner freeze when the ready queue is empty or leaves lack owned paths / acceptance.

Status lines

Before each major step, emit one short line, e.g.:

• Orchestrator: board — 3 ready, 41 blocked
• Orchestrator: planner — unblock #244 deps
• Orchestrator: worker ×2 — #244, #159
• Orchestrator: integrate — PR …

Subagent briefs (copy into Task prompts)

Planner subagent — read-only product code; may edit issues/ADRs/docs:

You are an Orrery planner. Read AGENTS.md + docs/plan/issue-lifecycle.md.
No star/runtime implementation. Goal: <GOAL>.
Follow the burndown/plan/triage contract. Return: ready now / newly unblocked /
still blocked (why) / ADR paths touched.

Worker subagent — one leaf only:

You are an Orrery worker. Read AGENTS.md + field-guide/index.md.
Claim ONLY GitHub issue #<N> if labels include leaf AND ready.
Restate outcome, owned paths, frozen decisions, acceptance.
Implement only owned paths; one PR with PR template; run acceptance.
Before push: `uv run ruff check .` (and `--fix` when safe) — CI lint is the
usual fail, not pytest.
If paths/acceptance missing, stop and report triage needed — do not invent design.
Do NOT merge; leave PR open for the orchestrator.
Return: PR URL, acceptance command + result, ruff clean, files touched.

Path disjointness

Before parallel claims, compare Owned paths. If two leaves both touch app.py, discovery.py, dogfood.py, the same stars/<name>/, or the same shared package (e.g. both under stars/_core/), run them serially (or triage a split). Fixture-only vs star-package leaves are usually safe in parallel.

Mode contracts (leaf-level — for subagents / escape hatches)

board / status

1. gh issue list (open) and summarize counts by kind/gate.
2. Print leaf+ready titles (claimable now).
3. Do not edit issues or code unless asked.

burndown / unblock (planner)

1. Read this file + docs/plan/issue-lifecycle.md + field-guide/index.md.
2. No product implementation (no star/runtime code). Issue/ADR/docs edits OK.
3. Prefer active sagas: #1, #237 (tree-handling), #160 (migration), #124 (execution).
4. For each candidate: missing design / ADR / owned paths / acceptance / parent gate → fix, file design, or leave blocked with one-line reason.
5. Never fake-unblock. Cap: ≤5 leaves → ready, or ≤2 designs closed per pass.
6. End with: ready now / newly unblocked / still blocked (why).

plan #N (planner)

1. Fetch issue #N. If it is a leaf, stop and suggest claim or triage.
2. Freeze the decision; link or write ADR when it outlives the epic.
3. File or update child leaves with owned paths + machine acceptance.
4. Set ready only when deps are actually clear; otherwise blocked.

claim #N / work #N / ship #N (worker)

1. Fetch #N. Abort unless labels include leaf and ready.
2. Restate: outcome, owned paths, frozen decisions, acceptance command.
3. If owned paths or machine acceptance are missing → stop; suggest triage #N.
4. Touch only owned paths (megafile carve-outs must be explicit on the issue).
5. Do not invent schema/policy; open a design issue or comment instead.
6. One PR using the PR template; run the acceptance command; report results.
7. Before push: uv run ruff check . must be clean (fix import order / line length locally — do not leave that to the orchestrator).
8. Optional: one field-guide line for a true surprise (respect line budget).
9. Do not merge unless the user pinned ship #N with merge intent; default is open PR for orchestrator integrate.

Integrate hygiene (orchestrator / ship)

When a leaf PR merges and the issue closes:

1. Remove ready (and blocked if somehow still present) from the closed issue.
2. Confirm the board’s leaf+ready list no longer includes it.
3. If the merge unblocks dependents, either flip them to ready or leave a one-line comment on why they stay blocked.

triage #N (planner)

Rewrite or comment so #N matches the leaf/design template. Add leaf / ready / blocked correctly. No feature code in this mode.

Process vs product (stars / constellations)

Rule of thumb: If only Orrery maintainers need it to ship this repo, keep it in AGENTS.md / GitHub. If any external agent would pay for a bounded sealed result mid-tree, it belongs on the tree-handling rim.

Session hygiene

• Stay in one orchestrator chat for swarm / drive — subagents get fresh context via Task; you should not open a new chat per leaf.
• New chat is still fine for a clean board glance or a pinned claim #N escape hatch.
• Prefer inexpensive models for worker subagents when the leaf is explicit; frontier for orchestrator judgment and planner freezes.