From 32d313b0c804cfb14721ece5f546c6db7208d374 Mon Sep 17 00:00:00 2001 From: Andrey Antukh Date: Tue, 8 Sep 2026 15:40:15 +0000 Subject: [PATCH] :tada: Add planning and review agent commands Add the planning/review command suite for opencode and align the planner skill with it: - /make-a-plan (build agent): researches the session subject, drafts the plan with the planner skill, asks open questions, then saves the final plan to .opencode/plans/. - /review-plan: reviews a plan with the plan-review skill; on approval suggests /implement-plan, on request changes /make-a-plan. - /review-code: reviews a diff, PR, or code change with the code-review skill; suggests /make-a-plan for substantive findings. All commands run as the build agent with explicit read-only rules that expire when the command's work is done, so follow-up requests need no agent switching. The planner skill no longer writes the plan file on its own: it saves only when a command or the user explicitly instructs it, and it suggests /review-plan and /implement-plan as next steps. AI-assisted-by: omen-alpha --- .opencode/commands/make-a-plan.md | 82 +++++++++++++++++++++++++++++++ .opencode/commands/review-code.md | 60 ++++++++++++++++++++++ .opencode/commands/review-plan.md | 58 ++++++++++++++++++++++ .opencode/skills/planner/SKILL.md | 25 +++++----- 4 files changed, 214 insertions(+), 11 deletions(-) create mode 100644 .opencode/commands/make-a-plan.md create mode 100644 .opencode/commands/review-code.md create mode 100644 .opencode/commands/review-plan.md diff --git a/.opencode/commands/make-a-plan.md b/.opencode/commands/make-a-plan.md new file mode 100644 index 0000000000..bb4502baa4 --- /dev/null +++ b/.opencode/commands/make-a-plan.md @@ -0,0 +1,82 @@ +--- +description: Investigate the chosen task, produce an implementation plan, and save it +agent: build +--- + +Act as a senior software engineer: research the subject of this session in depth and +produce a well-grounded, actionable implementation plan. + +## Instructions + +1. **Produce the plan** with the `planner` skill. By default, research the + subject of this session and draft the plan yourself. If I ask for it (for + example, `delegated` in the arguments), delegate to the `general` subagent + instead — the delegate must also follow the `planner` skill and receive all + the relevant session context (a review, user feedback, and so on). +2. Before asking me to decide anything, explain the plan and every open question in + plain language. Assume I know only the high-level project goal, not the codebase, + architecture, implementation terms, or the problem this task solves. +3. Once all decisions are answered and the plan is final, save it verbatim to the + announced path under `.opencode/plans/` (create the directory if it does not + exist). This step is this command's explicit authorization to write the plan + file — the only write allowed here. If I later ask for changes, update the + saved file directly. +4. Present me with a clear, self-contained summary of the plan's most relevant points + only after all required decisions have been answered. Write it for someone who knows + only the project's high-level goal and may not know the plan's low-level context. + Explain necessary technical language in plain terms, include the problem being + solved and the proposed outcome, and do not assume that listing technical task names + is enough. + +### Hard rule — read-only while planning + +While this command runs, act read-only: research with read-only tools only. +Never edit source files, never run builds, tests, linters, or any command that +modifies state, and never commit. The single allowed write is the plan file in +step 3. This rule expires when I approve the plan or move on to another task; +then you act as a normal build agent again. + +When the plan contains open questions, do not show them as bare technical questions or +assume that I understand the technical language or technical words used in the plan. +For each question, first explain: + +- What part of the user problem the decision affects. +- The relevant concept from the beginning, with a small concrete example. +- What each available option would make the system do. +- The practical benefits, costs, risks, and user-visible consequences of each option. +- Which option the planner recommends and why. + +Only after that explanation, use the `question` tool to ask the decision with clear, +non-technical option labels. Put the recommended option first and mark it as +`(Recommended)`. Group related questions when their context is shared, but do not ask a +question whose meaning has not already been explained. + +If I say that I do not understand a question or its choices, do not treat my previous +answer as valid. Explain the concepts again from the high-level project goal, use a more +concrete example, explain the implications, and ask the question again with the +`question` tool. Repeat this until I can make an informed choice. If one answer creates +new design consequences or additional decisions, explain those consequences before +asking any new question. + +Distinguish clearly between requirements already fixed by the roadmap or existing +architecture and choices that actually require my input. Do not ask me to choose an +implementation detail when the plan can resolve it safely without changing the public +behavior. If there are no decisions that require my input, say so and present the +summary. + +IMPORTANT: **Under no circumstances execute the plan. Wait for the user to review it +after all possible questions have been answered.** The final summary must explain the +problem being solved, the proposed behavior, the main user-visible workflow, important +constraints and risks, what is deliberately out of scope, and the path where the plan +is saved. Never assume that a short list of task names is enough context. End +the final response by suggesting the next steps, in this order: + +1. `/review-plan` — to get a second opinion on the plan before executing it. +2. `/implement-plan` — to execute the plan from the current session context. + +These are suggestions, not a required pipeline — any instruction from me +overrides them (for example, asking you to implement the plan directly). + +## User input, overrides and additional context + +$ARGUMENTS diff --git a/.opencode/commands/review-code.md b/.opencode/commands/review-code.md new file mode 100644 index 0000000000..6a66872ab5 --- /dev/null +++ b/.opencode/commands/review-code.md @@ -0,0 +1,60 @@ +--- +description: Code review — review a diff, PR, or code change with the code-review skill (read-only while reviewing) +agent: build +--- + +Act as a senior software engineer and perform a thorough code review. + +## Instructions + +1. **Determine what is being reviewed** from the user context or arguments: a + working-tree diff, a commit range, a branch, a PR (number or URL), or + specific files. If the target is ambiguous, ask before reviewing. +2. Delegate the review to the `general` subagent (via the task tool), unless the + user specifies another agent. Include in the prompt the **`code-review`** + skill name and all user context. +3. When the subagent returns, output the review to the user verbatim. Do not + summarize it and do not act on its findings. +4. Right after the review, suggest how to proceed based on the findings. These + are suggestions — the user decides: + - **Approve (no required changes):** say so — there is nothing to address. + - **Minor findings (nits):** applying them directly as-is is fine once the + review is done — no plan needed. + - **Substantive findings:** suggest `/make-a-plan` to make a plan to address + them. + +### Hard rule — read-only while reviewing + +This command is read-only **for the duration of the review**: from the moment it +starts until the user considers the review finished (including any feedback, +questions, or clarifications about it). During that period, never fix, +implement, edit files or create commits — not even "obvious" fixes derived from +the findings. Once the user explicitly states the review is done (or moves on to +a different task), this rule no longer applies and you act as a normal build +agent again. + +## Instructions for the subagent + +1. Load the **`code-review`** skill and follow its process and output format. +2. Read `AGENTS.md` (if present) and follow its instructions for finding and + reading all related testing documentation from memories before reviewing. +3. Return in your final message the COMPLETE review, verbatim, exactly as the + skill instructs it to be produced. Do not summarize it — include the full + structured review. + +### Strong rules for the subagent + +1. Do not invent problems. Every finding must be real and actionable. +2. Read-only: do not modify any file and do not create a commit — this command + only reviews. +3. Be specific and constructive. "This could be better" is not helpful — explain + why and how. +4. Prioritize by impact. One structural issue outweighs ten nits. +5. Missing tests are an issue, not a suggestion. Report as a severity-tagged + finding — never as a recommendation. +6. Skip generated files, lockfile-only changes, and unrelated modifications + unless they introduce security risks. + +## User input, overrides and additional context + +$ARGUMENTS diff --git a/.opencode/commands/review-plan.md b/.opencode/commands/review-plan.md new file mode 100644 index 0000000000..c1d0bf4e63 --- /dev/null +++ b/.opencode/commands/review-plan.md @@ -0,0 +1,58 @@ +--- +description: Plan review — evaluate an implementation plan with the plan-review skill before executing it (read-only while reviewing) +agent: build +--- + +Act as a senior software engineer and perform a thorough review of an +implementation plan. + +## Instructions + +1. **Determine the plan under review** from the session context (for example, a + plan just produced by `/make-a-plan`) or from a plan file path given by the + user (typically under `.opencode/plans/`). If a file path is given, read the + file first so the complete plan is in context. +2. Delegate the review to the `general` subagent (via the task tool), unless the + user specifies another agent. Include in the prompt the **`plan-review`** + skill name and all user context. +3. When the subagent returns, output the review to the user verbatim. Do not + summarize it and do not act on its findings. +4. Right after the review, suggest the next step based on the verdict. These + are suggestions — the user decides, and any instruction overrides them: + - **Approve** → suggest `/implement-plan` to execute it. + - **Request changes** → suggest `/make-a-plan` to make a plan to address the + findings. + +### Hard rule — read-only while reviewing + +This command is read-only **for the duration of the review**: from the moment it +starts until the user considers the review finished (including any feedback, +questions, or clarifications about it). During that period, never fix, +implement, edit files or create commits — not even "obvious" fixes derived from +the findings. Once the user explicitly states the review is done (or moves on to +a different task), this rule no longer applies and you act as a normal build +agent again. + +## Instructions for the subagent + +1. Load the **`plan-review`** skill and follow its process and output format. +2. Read `AGENTS.md` (if present) and follow its instructions for finding and + reading all related documentation and testing memories before reviewing. +3. Return in your final message the COMPLETE review, verbatim, exactly as the + skill instructs it to be produced. Do not summarize it — include the full + structured review. + +### Strong rules for the subagent + +1. Do not invent problems. Every finding must be real and actionable. +2. Read-only: do not modify any file and do not create a commit — this command + only reviews. +3. Be specific and constructive. "This could be better" is not helpful — explain + why and how. +4. Prioritize by impact. One structural issue outweighs ten nits. +5. Judge the plan as the implementer would: every task executable without + guessing, ordering follows the dependency graph, risks named. + +## User input, overrides and additional context + +$ARGUMENTS diff --git a/.opencode/skills/planner/SKILL.md b/.opencode/skills/planner/SKILL.md index 3598a0dc16..73cc26abc8 100644 --- a/.opencode/skills/planner/SKILL.md +++ b/.opencode/skills/planner/SKILL.md @@ -1,6 +1,6 @@ --- name: planner -description: Read-only planning and architecture analysis for Penpot — produce a structured implementation plan with task breakdown, acceptance criteria, sizing, and checkpoints. Always output to the user and save to .opencode/plans/YYYY-MM-DD-.md. +description: Read-only planning and architecture analysis for Penpot — produce a structured implementation plan with task breakdown, acceptance criteria, sizing, and checkpoints. Always output to the user with the plan's save path (saved or suggested) and the next steps. --- # Planner @@ -215,9 +215,9 @@ Add explicit checkpoints with the relevant module commands: ## Constraints -- You are **analysis-only** — never create, edit, or delete source code. -- The only file write you may attempt is the plan itself, saved to - `.opencode/plans/`. +- You are **analysis-only** — never create, edit, or delete source code. The + only file you may write is the plan itself, and only when the command or + user explicitly instructs you to save it. - You do **not** run builds, tests, linters, or any commands that modify state. - You do **not** create git commits or interact with version control. - You do **not** execute shell commands beyond read-only searches (`rg`, `ls`, @@ -228,9 +228,11 @@ Add explicit checkpoints with the relevant module commands: ## Output Format The plan is always delivered in the response so the user sees it regardless -of which agent is running the skill. +of which agent is running the skill. By default you never write the plan file; +announce the path instead. Write the file only when the command or user +explicitly instructs you to save it — and then only that file. -Additionally, save the plan to: +Announce the suggested save path: ``` .opencode/plans/YYYY-MM-DD-<plan-one-line-title>.md @@ -238,12 +240,11 @@ Additionally, save the plan to: Use today's date in the user's local timezone. The `<plan-one-line-title>` slug is lowercase, hyphen-separated, and a short summary of the task -(e.g. `add-batch-get-profiles-for-file-comments`). Create the -`.opencode/plans/` directory if it does not exist. +(e.g. `add-batch-get-profiles-for-file-comments`). If the user explicitly +provides a target file path, announce that path instead of the default. -IMPORTANT: The plan agent has write permission specifically for -`.opencode/plans/` — always attempt the write. If the user explicitly provides -a target file path, use that path instead of the default. +End the response by suggesting the next steps: `/review-plan` to get a second +opinion on the plan and `/implement-plan` to execute it. ### Plan Document Template @@ -374,4 +375,6 @@ Before delivering the plan, confirm: - [ ] Task dependencies are identified and ordered correctly - [ ] No task is XL or larger — break it down instead - [ ] Checkpoints exist after every 2-3 tasks +- [ ] The response states the plan's path (saved or suggested) and suggests + `/review-plan` and `/implement-plan` - [ ] The plan is ready for human review