plan-orchestrator@1.0.0

2026-10-31 00:34:08 +04:00
1 parent 22699eac9b
commit 0e753f17df
@@ -0,0 +1,203 @@
 ---
 name: plan-orchestrator
 description: 'Step-by-step execution of an agreed plan by subagents: plan phase → questions → work → independent verification by the orchestrator → commit. Use when the plan is ready and must be executed as a whole, not one task (e.g. "do the plan", "execute step by step", «делай по плану», «выполняй по пунктам»).'
 license: MIT
 metadata:
  author: Valentin Silyutin
  version: "1.0.0"
 ---
 # Plan orchestration
 How to run a multi-step plan: one step per subagent, planning and work as two phases, verification by the orchestrator, a commit after each step.
 ## When to use
 - an agreed plan of three or more steps, touching different files;
 - the user wants the whole plan executed, not a single task.
 Do not use:
 - one task or a couple of edits — a subagent plus two phases costs more than doing it directly;
 - research without edits, reviews, answering a question;
 - a plan the user wants to drive themselves — only the "user leads" mode applies (section 8).
 ## Why this shape
 - **A step must stand alone.** The subagent starts with a clean context: without the goal, files and acceptance criteria it guesses and delivers half.
 - **Plan first, code second.** The planning phase surfaces questions before any edit, when rework is cheap.
 - **The orchestrator writes no code.** It reads the diff and runs the checks, so it judges the work instead of defending its own.
 - **Questions go up.** Anything that needs a human decision (meaning, priority, scope) goes to the user, not to the subagent's taste.
 ## Prompt language
 This document is in English. Prompts to subagents follow the target project's language, not this file's:
 1. An explicit language rule in the project's instruction file (`AGENTS.md`, `CLAUDE.md`) wins, even when the user writes in another language. Look for a language section; do not re-read the whole file.
 2. Otherwise use the language of the user's messages.
 3. Otherwise English.
 Translate the templates before sending. Keep paths, commands, file and function names, API identifiers and rule IDs verbatim. Never mix languages inside one prompt: a half-translated prompt is worse than a fully foreign one, because the subagent starts answering in the wrong language and the project convention breaks silently.
 ## 0. Choose the mode
 One call to the questions tool, two questions, defaults first:
 1. **Who drives execution**: the agent (default) / the user.
 2. **Commits**: after every step (default) / one at the end / none.
 The loop never starts while planning: edits are forbidden in plan mode. The plan is agreed and the user has left plan mode first.
 No questions tool available — ask the same two questions as plain text and wait for the answer.
 ## 1. The plan
 A step is not a heading; it is a self-contained assignment. Required fields:
 | Field | What to write |
 |---|---|
 | Goal | what must change in behaviour or appearance |
 | Files | paths this step is allowed to touch |
 | Acceptance criteria | checkable statements, not "make it neat" |
 | Checks | project commands and what a human verifies by hand |
 | Do not touch | neighbouring entities, contracts, dependencies |
 | Risks | what may break and how to notice it |
 Steps follow dependency order. Parallel runs are allowed only for steps that share no files, and only by an explicit decision, never by default.
 Track progress with the todo tool when the environment has one. Otherwise print a status table after each step. Create a journal file in one case only: the context is running out and the plan would be lost.
 ## 2. Loop over a step
 ### 2.1. Record the tree state
 Before launching the subagent run `git status --short` and keep the output. It shows later what the subagent did and what was there before it.
 ### 2.2. Planning phase
 Launch the subagent waiting for its result (not in the background). Translate the template below per "Prompt language":
 ```text
 You work in the repository <path> (<stack>). Reply and write comments in <project language>.
 Step <N> of <M>: <title>
 <the whole step: goal, files, acceptance criteria, checks, what must not be touched>
 Phase 1 — plan only. Do not edit files, do not create anything, do not commit.
 Return:
 1) a work plan step by step: what changes in which file and why;
 2) what is ambiguous in the step and needs a human decision;
 3) what is missing in the step or what is superfluous;
 4) risks and how you will verify them.
 List your questions, each with answer options, no filler.
 ```
 Right after the answer compare `git status --short` with the saved output: new lines mean the subagent edited files anyway. Revert only its edits (not the user's), say so, and repeat the planning phase.
 ### 2.3. Questions
 Split the subagent's questions into two groups:
 - **answerable from the plan, project docs or conventions** — answer yourself, briefly and with the reason;
 - **needing a human** (UX meaning, priority, scope, a deviation from the rules) — ask the user in one call, with your own options and a recommendation.
 Record decisions from both groups in your reply: the user must see what you decided for them and why.
 ### 2.4. Work phase
 Continue **the same subagent session** so it does not have to restate the plan. Template:
 ```text
 The plan is agreed. Answers to your questions:
 - <question> → <answer>
 - <question> → <answer>
 Execute your plan.
 Rules: <project constraints: do not commit, add no dependencies, touch no files outside the list, do not edit generated files, comment language>.
 At the end run the project checks and return a report:
 - what changed, per file, one line each with the reason;
 - which acceptance criteria are met and what proves it;
 - checks: command → result;
 - what remains unverified and which risks exist;
 - what the user must look at by hand.
 ```
 Session not kept or lost — pass the plan back as text, but never start a new step in the same session.
 ## 3. Verification by the orchestrator
 This is the orchestrator's job, not the subagent's. Go through the checklist before moving on:
 - [ ] `git status --short` — only the step's files, no unrelated changes;
 - [ ] the diff is read in full, not by the heading;
 - [ ] every acceptance criterion is checked in the code, not by the report's word;
 - [ ] no debug output, commented-out blocks or dead code;
 - [ ] no new dependencies, generated files rebuilt by their generator rather than edited by hand;
 - [ ] project checks from `AGENTS.md` or `package.json` are run by you, not taken on trust;
 - [ ] manual checks are collected into a list for the user.
 A failure is no reason to rewrite the code yourself. Continue the subagent's session with a concrete list of findings. Two failed attempts — stop and ask the user: continue, revert the step, or replan.
 ## 4. Commit
 By default one step is one commit, after green checks.
 - The message is the step title, without "fix", "wip" or a file list.
 - `git add -A` is allowed only when the tree has no foreign changes. Otherwise stage the step's files one by one.
 - The subagent never commits: the orchestrator does, otherwise the history stops matching the plan.
 - Commits disabled by the user — do not commit at all, but keep running the checks.
 ## 5. Stop signals
 Stop the loop and ask the user when:
 - edits went beyond the step's files — that is another step;
 - the step grew twice against the plan — split it or replan;
 - a new dependency, contract or schema change is needed that the plan does not have;
 - checks fail that the step never touched;
 - the subagent fails the step a second time;
 - two steps claim the same lines — parallelism is forbidden here.
 Proceeding silently is fine only for cosmetic drift: different line order, a renamed internal variable, an extra line in the report.
 ## 6. Final verification
 After the last step:
 1. Run the full project checks.
 2. A table: step → commit → status.
 3. What remains open and why.
 4. What the user verifies by hand: screens, gestures, states, devices.
 5. Remaining risks — one line each, no plan retelling.
 ## 7. Context hygiene
 - The subagent prompt carries the step and the conventions, never the discussion history.
 - Restate the step no longer than in the plan: a long prompt is read worse than a short one.
 - The user's answers are passed on faithfully, without guesswork.
 - Run two steps in one subagent and you lose the commit and verification boundary.
 ## 8. User-led mode
 When the user drives execution, quality does not change, only the rhythm:
 - the orchestrator does not start the next step on its own; it shows the current one and waits for a command;
 - questions to the user are asked immediately, not accumulated;
 - commits happen on the user's command, not automatically;
 - after each step a short report: what is done, what is verified, what is left.
 Every other section still applies: phases, verification, stop signals.
 ## 9. Do not
 - Do not pack two steps into one subagent.
 - Do not take "checks are green" on trust.
 - Do not commit while the tree holds foreign changes.
 - Do not let the subagent commit.
 - Do not implement a step yourself when the agent drives: verification then becomes self-verification.
 - Do not retell the whole plan after every step — status and decisions only.