diff --git a/plan-orchestrator/SKILL.md b/plan-orchestrator/SKILL.md new file mode 100644 index 0000000..d51be23 --- /dev/null +++ b/plan-orchestrator/SKILL.md @@ -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 (). Reply and write comments in . + +Step of : + +<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.