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-