light-orchestrator

Orchestrator

Turn the "combined invocation chain" from a declarative description into an executable process: plan stages, invoke skills, block at checkpoints, keep a ledger, resume from breakpoints. It does not do the work itself (writing, drawing, analysis are all handed to the corresponding skills); it is only responsible forscheduling, gatekeeping, restoring context, and stage handoff。

When to start

Start pipeline(the task spans ≥3 stages, or the user explicitly wants "full workflow / from X to Y"):

• "From this dataset to a paper" / "turn this idea into a submission" / "help me run the project from scratch to submission".
• The user gave raw materials (data/idea) and wants a cross-stage final product (paper/grant application/defense).

Start breakpoint recovery(even if only a single action remains, restore state first):

• "Continue" / "it just broke" / "pick it up" / "take over Claude/Codex/Hermes" / "restore context" / "where did we get to last time".
• The user says the previous agent kept breaking, asks you to find the conversation record, and continue some long-term project.

Do not start(route directly to a single skill; do not let a heavy process drag down a light task):

• "Revise this abstract" → m07 section/abstract mode.
• "Draw a bar chart" → m11.
• "Check these citations" → m10.
• Any task in a single stage that can be closed out with one skill.

Criterion:Does this task require handing off artifacts across skills or restoring an old state? Yes→orchestrator; no→single skill.

0. Breakpoint recovery protocol (do this first when the user says "continue / it just broke")

Do not continue from impressions. First run the minimal recovery probes to assemble the "current factual state" before acting (see the full six probes in the references/checkpoints.md"Breakpoint recovery probes" section):

1. Workspace and version：git status --short、git log --oneline -5, current branch/remote; if there is a GitHub remote, also read the latest CI (gh run list）。
2. Current task list: read the Todo tool state; if none, rebuild from passport/db09/latest commit.
3. Project ledger: read .light/passport.yamlfirst; if none, read the db09 project card/decision_log/version_history.
4. Conversation/external handoff: retrieve the transcript only when ① the user gives a conversation record path, or ② the cache path/session title/project slug clearly matches the current repository or db09 project name, limited to current project keywords; if relevance cannot be proven, mark transcript: unavailable, do not guess at nonexistent records, and do not read unrelated project sessions.
5. Artifacts and dirty files: read manifest/plan/diff/uncommitted files to determine "completed but uncommitted / committed but unpushed / pushed and waiting on CI / CI failed and awaiting fix".
6. Recovery summary: before continuing, internally form five facts—当前阶段/已完成/未完成/阻塞风险/下一步最小动作; if the next step has side effects (commit/push/rewrite history/delete), confirm according to scope discipline.

If a probe (gh/CI/todo/transcript) is unavailable, mark unavailable, continue with the remaining available evidence, do not hard-block improperly.On resume, strictly prohibited: claiming "it should have reached X by now" based only on chat memory (there must be git/passport/db09/todo/CI evidence); rerunning completed stages (unless the user requests it or the artifacts are invalid); directly overwriting uncommitted changes (first read the diff to distinguish whether they are leftovers from this round or new user changes).

1. Plan the pipeline

According to the task goal, cut a chain from the stage mainline in Section 6 of CONVENTIONS (do not run everything every time). Common chains are in references/pipelines.md. Planning produces astage plan table, and each stage must clearly state: which skill is invoked, inputs, expected outputs, where artifacts are persisted, and checkpoint type.

Plan table template:

Stage	Skill	Input	Output/Artifact location	Checkpoint
Research	m01 literature-search	User question + db01/db03 background	docs/literature_review.md / literature table	✓ Sources verifiable
Plan	m05 research-plan	Idea that passed review	PROJECT_PLAN.md / experiments/experiment_matrix.md	✓ Executable

Principle: first give the plan table to the user for confirmation before starting; if the user says "continue the previous task", only resume and continue the current stage, do not replan the entire chain.

2. Stage input/output contract

Cross-skill handoff must have persistable artifacts, and cannot rely only on a chat summary.The single source of truth for artifact naming is the stage artifact contract table in CONVENTIONS §6.1, and the execution-view mirror table of stage-by-stage "upstream input → standard output/handoff artifact → downstream" is in references/pipelines.mdthe "Stage Artifact Contract" section (if inconsistent with CONVENTIONS §6.1, the latter prevails). If the project already has conventions, the project conventions prevail, but the path must be recorded in the passport.

At the end of each stage, write "artifact path + verification output summary + next-stage input" into .light/passport.yaml; if an artifact is missing, the stage cannot be claimed complete.

3. Stage-by-stage execution + checkpoints

Each stage: invoke the corresponding skill → persist output to the ledger → pass the stage checkpoint → only then proceed to the next stage. Two types of checkpoints (see details in references/checkpoints.md）：

• Decision point 🧑: requires the user to choose a branch before continuing. For example, if the m04 idea does not pass (send back to m03 or let it pass?), which venue to submit to, which output format to use.Do not decide for the user.
• Confirmation point ✓: the machine verifies first (run the a08 self-review / a07 consistency / a10 research-ethics gates), produces a report → user confirms → proceed.If the integrity gate is not met, block by default, do not silently skip; the same stage allows at most 2 rounds of overall rework (for details see references/checkpoints.md), and those still not meeting the standard are converted into "known limitations" and recorded truthfully, rather than pretending they are fixed.

The evidence for a confirmation point must be fresh: one of the current round's command output, file diff, CI run, script selftest, or manual confirmation record; it is not enough to just write "checked".

Stage switching triggers session handoff by default (T3): after each checkpoint is passed and before entering a new stage, proactively leave a handoff card according to §5 + print the startup prompt, without waiting for context to be exhausted.

4. Maintain the artifact ledger

Maintain throughout aartifact ledger(passport), recording each stage: what was produced, which gates were passed, which were marked GAP, and what the user chose at decision points. For the format and storage location, see references/passport.md(fixed storage in the project root directory .light/passport.yaml). On startup, first check whether this file exists—if it exists, resume; if not, create it. The ledger is incorporated into a02 memory-pm's project memory,so that after a task interruption it can be used to resume。

Minimum ledger update rules:

• Each time a stage is completed, append on the spot; do not save it up to fill in at the end.
• For each artifact, write the path relative to the project root directory.
• For gate, write PASS/FAIL/WARN and the evidence source.
• For user decisions, write choice and by: user。
• Record GAP / known_limitations truthfully.

Downstream consumption: the union of the artifacts: paths from each stage is theauthoritative "materials already produced" listfor a07 consistency's "change broadcast" rescan (once a definition/term changes, a07 rescans this list item by item to prevent staleness). Therefore artifact paths must be timely and accurate—products that are not registered cannot be found by a07's scan. For lightweight projects without a passport, a07 falls back to reading db09 version_history.md。

5. Stage handoff output (handoff → the two-piece session handoff protocol)

For long tasks, each time before pausing, submitting, waiting for the user/CI/experiment, or when context may be compressed, a handoff must be actively performed (T1/T2/T3 triggers in CONVENTIONS §9).The handoff format is consolidated into the two-piece set of the a02 session handoff protocol; this skill no longer carries its own summary format(to avoid divergence in conventions):

1. Handoff card persisted to disk: according to a02 light-memory-pm/templates/handoff_card.md , fill it in and store it in the project root .light/handoff/S<NN>-<slug>.md(at the same level as .light/passport.yaml ,<NN> incremented by two digits,parent_session continuing from the previous card). The card's "current stage/completed/workspace state/next step/blockers/must-read files/prohibitions" are all the fields of the original handoff summary.
2. Print the startup prompt: according to a02 light-memory-pm/templates/handoff_prompt.md , fill in the values and print it in the chat; the user copies it → opens a new conversation → pastes it to resume.

For persistence details, the four types of trigger criteria, and the self-contained/self-propagating principles, see a02 light-memory-pm/references/session_handoff.md and CONVENTIONS §9. For lightweight conversations without a project directory, only print the prompt; do not persist a card.

When the user later says "continue", first read the latest handoff card as the entry point, butdo not treat the handoff card as current fact; still refresh git status, todo, passport/db09, CI/remote, and other current evidence. Only when there is no handoff card should you fall back to §0 "Breakpoint Recovery Protocol".

Boundaries (important)

• The orchestratordoes not bypass any standing gate. self-review / consistency / research-ethics / tool-selection take effect in the background as usual at each stage.
• The orchestratordoes not make research decisions for the user. Which idea to choose, how to settle the conclusion, where to submit—these are all decision points, left to the user to decide. The design decision record for this boundary ("can borrow ARS's scheduling form, but does not take over research judgment") is in the repository docs/design/2026-06-08-ars-borrow-boundary.md(only within the repository, not distributed with the installation).
• Tiering principle: use the full pipeline for large tasks, and directly use a single skill for small tasks. Better to orchestrate less than to orchestrate for the sake of orchestration.
• Breakpoint recovery is not "doing it all over again." Stages that have been verified, committed, and entered into the passport are not redone by default; if the current diff, dependencies, remote state, or CI show that the evidence is no longer valid, only re-verify the minimal affected scope; roll back only when the evidence is invalid, the user requests it, or a downstream contradiction is found.

Self-check list

• First determine whether the task should use the pipeline, a single skill, or breakpoint recovery?
• If it is "continue/just disconnected," did you read evidence such as git/todo/passport/db09/CI?
• Did you clearly identify the current stage, what is completed, what is not completed, and the next minimal action?
• Did you write a persistence path for each cross-skill handoff artifact?
• Did you stop at decision points to let the user choose, rather than deciding for the user?
• Did you provide real verification evidence at confirmation points, rather than verbally saying it passed?
• Did you update .light/passport.yaml, and when pausing/switching stages/context is about to run out, leave a handoff card + startup prompt according to §5 to ensure it can be continued next time?