Merge branch 'staging-2.19.x' into staging

This commit is contained in:
Andrey Antukh 2026-11-18 20:17:37 +01:00
commit db1e2f7c9b
27 changed files with 376 additions and 778 deletions

View File

@ -337,28 +337,32 @@ small. To delegate without switching models, delegate to `general`.
report with your intent: "investigate this and find the possible cause",
"investigate and tell me where this points", or "does this still apply?".
Explore until you and the agent roughly agree on the problem.
2. **Write the plan.** Run `/make-a-plan` — it executes in Build mode.
If you need to step in and answer something yourself, press TAB to
leave Build mode. Use Plan mode only when you want a hard guarantee
that the agent modifies no file under any circumstance. If you
2. **Write the plan.** Invoke `@make-a-plan`. Skills use the current agent;
select Build mode first when the skill needs to write files. Use Plan mode
only when you want a hard guarantee that the agent modifies no file under
any circumstance. If you
explored with a weaker model but want a stronger one to write the
plan, switch models first or delegate:
`/make-a-plan delegate to @engineer-glm`.
`@make-a-plan delegate to @engineer-glm`.
3. **Iterate on the plan.** The plan is saved to `.agents/plans/`, so you
never depend on LLM memory: read the file directly, or run `/review-plan`
for a second opinion (delegation works here too). Complex plans deserve a
review; simple ones can skip it.
4. **Execute.** Run `/implement-plan`. It first prints the full picture —
never depend on LLM memory: read the file directly, or invoke `@review-plan`
for a second opinion (delegation works here too). It applies clear plan
improvements and discusses consequential decisions one by one before
applying them. Complex plans deserve a review; simple ones can skip it.
4. **Execute.** Invoke `@implement-plan`. It first prints the full picture —
whether it will create an issue and a branch, the execution style, and a
task checklist — and waits for your go-ahead. Say "step by step" to stop
after each task (one commit per task) so you can verify as it goes;
the default runs all tasks with one final commit.
5. **Land the work.** When it finishes, either push yourself and run
`/create-pr`, or loop `/review-code` → `/make-a-plan` →
`/implement-plan` until the findings are addressed, then push and
`/create-pr`. Nothing pushes for you — you always push from your shell.
the default runs all tasks with one final commit. For a plan based on a
code review, it then asks whether to have the original reviewer verify the
corrections. If that session is unavailable, it tells you and uses a new
reviewer with the review and implementation context.
5. **Land the work.** When it finishes, either push yourself and invoke
`@create-pr`, or loop `@review-code` → `@make-a-plan` →
`@implement-plan` until the findings are addressed, then push and invoke
`@create-pr`. Nothing pushes for you — you always push from your shell.
> Note: `/implement-plan` checks the current branch. On a base branch
> Note: `@implement-plan` checks the current branch. On a base branch
> (`main`, `develop`, `staging`) it creates a GitHub issue and a branch
> `issue-NNNN`; on an existing feature branch it continues there and
> creates nothing. The pre-run summary tells you which applies. Read the
@ -367,14 +371,14 @@ small. To delegate without switching models, delegate to `general`.
### Big feature with multiple plans
When the work is too large for a single plan, tell `/make-a-plan`
When the work is too large for a single plan, tell `@make-a-plan`
up front: produce a high-level roadmap where each task will get its
own execution plan, and the roadmap doubles as the progress tracker.
From there the flow mirrors the issue flow above, one level down:
take each roadmap task in turn, write its own plan (`/make-a-plan`,
take each roadmap task in turn, write its own plan (`@make-a-plan`,
delegating when it helps), review it when the task is complex
(`/review-plan`), implement it (`/implement-plan`), and mark progress
(`@review-plan`), implement it (`@implement-plan`), and mark progress
on the roadmap as you land each piece.
### Plan file naming (base + derivatives)
@ -392,7 +396,7 @@ keeps everything adjacent in `ls`:
`2026-09-20-upload-pipeline-roadmap--task-01-chunk-upload.md`
- Chained: `...--task-02-gc--review-01.md`
While a plan is still unimplemented, `/make-a-plan` revises it in
While a plan is still unimplemented, `@make-a-plan` revises it in
place. Once implemented and reviewed, it writes a new followup file.
Full rules live in the `planner` skill.
@ -401,11 +405,10 @@ Full rules live in the `planner` skill.
Every plan carries `Status: draft | reviewed | done` plus an
append-only `Review Log` (UTC ISO 8601, one line per entry):
- `draft` — fresh from `/make-a-plan`.
- `reviewed` — review feedback incorporated. `/review-plan` stays
read-only; only your explicit "apply" makes `/make-a-plan` apply
the changes, flip the status, and log one line.
- `done` — `/implement-plan` closes it on completion, logging the
- `draft` — fresh from `@make-a-plan`.
- `reviewed` — review feedback incorporated. `@review-plan` applies clear
improvements and agreed decisions, then updates the status and log.
- `done` — `@implement-plan` closes it on completion, logging the
issue URL when one exists (never commit hashes).
A plan approved with no changes goes `draft` → `done` directly.
@ -505,7 +508,6 @@ JSON, REPL access, and so on.
| [`ripgrep`](skills/ripgrep/SKILL.md) | Fast content search with regular expressions. |
| [`jq-json-processor`](skills/jq-json-processor/SKILL.md) | Slice, filter, and reshape JSON output. |
| [`nrepl-eval`](skills/nrepl-eval/SKILL.md) | Run Clojure or ClojureScript code in the live REPL sessions (backend and frontend). |
| [`taiga`](skills/taiga/SKILL.md) | Look up Penpot issues, user stories, and tasks in Taiga. |
| [`testing`](skills/testing/SKILL.md) | The repo's testing rules and TDD workflow, loaded before writing tests. |
| [`local-ci`](skills/local-ci/SKILL.md) | Run CI-style lint, test, and format checks for the modules you touched with `scripts/ci`, and read the logs when they fail. |
| [`security-and-hardening`](skills/security-and-hardening/SKILL.md) | Security checks for code that handles user input, auth, or external services. |
@ -516,11 +518,11 @@ JSON, REPL access, and so on.
### A typical round
1. `/make-a-plan` — you get a plan and a saved file in `.agents/plans/`.
2. `/review-plan` — a second opinion; approve or request changes.
3. `/implement-plan` — the code gets written and committed. Starting from a base branch, it also opens the GitHub issue and the `issue-NNNN` branch; the plans that follow continue on that same branch.
4. `/review-code` — a reviewer checks the commit.
5. `/create-pr` — the branch goes up as a pull request.
1. `@make-a-plan` — you get a plan and a saved file in `.agents/plans/`.
2. `@review-plan` — a second opinion; approve or request changes.
3. `@implement-plan` — the code gets written and committed. Starting from a base branch, it also opens the GitHub issue and the `issue-NNNN` branch; the plans that follow continue on that same branch.
4. `@review-code` — a reviewer checks the commit.
5. `@create-pr` — the branch goes up as a pull request.
Every step also works on its own, and you can always say what you want
in plain words — the agents pick the right skill from what you say.

View File

@ -1,172 +1,95 @@
---
name: code-review-criteria
description: Code review criteria — the five review axes, core principles, severity format, and verdict for reviewing code changes. Loaded by the reviewer subagent of the review-code flow. Not a user-facing flow — to review code, use the review-code flow.
description: Code review criteria for correctness, clarity, architecture, security and performance. Loaded by the review-code subagent.
---
# Code Review Criteria and Quality
# Code Review Criteria
## Overview
Assess whether the change improves the codebase and is safe to merge. Review
the diff in context, its intent and relevant tests. Follow project conventions
and module memories. Do not block on personal preferences or invent problems.
Apply each axis in proportion to the change and its risks.
Multi-dimensional code review with quality gates. Every change gets reviewed before merge — no exceptions. Review covers five axes: correctness, readability, architecture, security, and performance.
Follow `review-code` for delegation and its read-only contract. Never run tests,
builds, linters or other state-changing checks during a review or follow-up.
Inspect prior test results or CI evidence when available. Identify their source
and scope; if evidence is missing, stale or inaccessible, say what is
unverified. Never claim a suite passed without evidence.
**The approval standard:** Approve a change when it definitely improves overall code health, even if it isn't perfect. Perfect code doesn't exist — the goal is continuous improvement. Don't block a change because it isn't exactly how you would have written it. If it improves the codebase and follows the project's conventions, approve it.
## Review axes
## When to Use
### Correctness and tests
- The reviewer subagent of the `review-code` flow loads this skill to perform the review of a code change.
- To review code, always go through the `review-code` flow — never load this skill directly for that. This is the criteria reference, not the flow.
Check requirements, relevant boundaries, error paths, concurrency and state.
Use the module's contracts to decide where validation belongs; do not demand
redundant guards inside functions with established preconditions. Check that
new functionality has tests covering its behavior and important failure
cases, using the appropriate layer and project testing guidance. Missing
required tests are findings; documentation-only changes need not add tests.
Do not infer that a test failed before a fix without evidence.
## Core Principles
### Readability and simplicity
These principles underpin every axis. When in doubt, default to them.
Check names, control flow and maintainability against existing conventions.
Flag duplication when it creates a concrete risk of drift or maintenance
cost, not merely because code appears more than once. In tests, prefer
self-contained, readable cases even when they repeat setup. Suggest the
simplest remedy that preserves behavior.
- **DRY (Don't Repeat Yourself):** Every piece of knowledge has one authoritative representation. Flag duplicated logic as a required change — it is not "just similar", it is drift that will diverge.
- **KISS (Keep It Simple, Stupid):** The simplest solution that works is the best solution. Complexity must earn its place: if it needs more than a sentence to explain, push for simplification before merge.
- **YAGNI (You Aren't Gonna Need It):** No abstractions, hooks or generalizations for hypothetical future use cases. Generalize on the third occurrence, not the first.
- **Don't invent problems:** Every finding must be a real risk, a real readability barrier, or a real architectural concern — not a hypothetical or a stylistic preference disguised as a problem.
### Architecture and compatibility
## The Five-Axis Review
Check module boundaries, existing abstractions, contracts and unnecessary
complexity. Review surrounding code when needed to understand the change.
Do not label a compatibility shim dead code without checking its purpose.
For file formats or data model changes, consult the relevant compatibility,
migration and feature memories; for Clojure, logging and translations, read
the corresponding guidance when relevant.
Every review evaluates code across these dimensions.
### Security
### 1. Correctness
Evaluate relevant input boundaries, authorization, secrets, data handling and
external integrations. Consult project security guidance for the affected
technology; do not assume a generic framework or tool applies to this module.
Does the code do what it claims to do?
### Performance
- Does it match the spec or task requirements?
- Are edge cases handled (null, empty, boundary values)?
- Are error paths handled (not just the happy path)?
- Do the tests cover the changed behavior, including its edge cases?
- Are there off-by-one errors, race conditions, or state inconsistencies?
Assess relevant hot paths, resource bounds, data access and scaling. Explain
the workload or conditions in which a problem matters; do not flag speculative
optimizations without a concrete risk.
### 2. Readability & Simplicity
## Scope and dependencies
Can another engineer (or agent) understand this code without the author explaining it?
Review relevant generated files or lockfile changes when they affect the
contract, dependencies or security; do not skip a lockfile-only dependency
change. Check dependency changes against available changelogs, project tools
and relevant lockfile diffs. Treat size as a signal to assess reviewability,
not an automatic finding. Identify unrelated work in the target diff when it
materially impedes review; do not review unrelated working-tree changes.
- Are names descriptive and consistent with project conventions? (No `temp`, `data`, `result` without context)
- Is the control flow straightforward (avoid nested ternaries, deep callbacks)?
- Are there "clever" tricks that should be simplified? Could this be done in fewer lines? (1000 lines where 100 suffice is a failure)
- Is a new conditional bolted onto an unrelated flow? Push the logic into its own helper, state, or policy.
- Do repeated conditionals on the same shape appear? They signal a missing model or dispatcher.
- Are there dead code artifacts: no-op variables, backwards-compat shims, or `// removed` comments?
## Findings and verdict
### 3. Architecture
Assign each finding a stable ID (`F1`, `F2`, …), independent of severity.
Never renumber it within the review or follow-up; severity may change as
evidence changes. New findings receive unused IDs.
Does the change fit the system's design?
For each finding state severity, file and location, concrete circumstances,
impact, remedy and the tests needed to verify it; explain when no new test is
needed. If a consequential decision requires user input, give the real options,
consequences and recommendation within that finding, without pausing to ask.
- Does it follow existing patterns or introduce a new one? If new, is it justified?
- Does it keep clean module boundaries, with dependencies flowing the right way (no cycles)?
- Is the abstraction level appropriate (not over-engineered, not too coupled)?
- Is there existing code that already does this? Reuse the canonical helper instead of a near-duplicate, and collapse branches that do nearly the same thing.
- Is feature-specific logic leaking into a shared or general-purpose module?
- Are type boundaries explicit? Question gratuitous `any`/`unknown`/optional/casts and silent fallbacks.
- Does the change reduce complexity or relocate it? Count the concepts a reader must hold: prefer the restructuring that makes whole branches disappear, and deleting an abstraction over polishing it.
- **Give the remedy, not only the problem:** replace conditionals with dispatchers, separate orchestration from business logic, extract helpers, split large files. Prefer the remedy that removes moving pieces over one that spreads the same complexity around.
- **Critical:** security incident, data loss or comparably severe breakage;
blocks merge.
- **High:** a significant defect or missing required test; must be addressed.
- **Medium:** a substantive issue worth fixing but not a merge blocker.
- **Low / Suggestion:** an optional improvement with a concrete benefit.
### 4. Security
Base severity on impact and project requirements. Missing tests required for
new functionality must be addressed; do not invent a test requirement for
changes where none applies.
For detailed security guidance, see `security-and-hardening`.
- Is user input validated and sanitized?
- Are secrets kept out of code, logs, and version control?
- Is authentication/authorization checked where needed?
- Are SQL queries parameterized (no string concatenation)?
- Are outputs encoded to prevent XSS?
- Are dependencies from trusted sources with no known vulnerabilities?
- Is data from external sources (APIs, logs, user content, config files) treated as untrusted?
### 5. Performance
- Any N+1 query patterns?
- Any unbounded loops or unconstrained data fetching?
- Any synchronous operations that should be async?
- Any unnecessary re-renders in UI components?
- Any missing pagination on list endpoints?
- Any large objects created in hot paths?
## Review Process
1. **Understand the intent** — What is this change trying to accomplish? What spec or task does it implement?
2. **Review tests first** — Tests reveal intent and coverage. Do they test behavior, not implementation details? Are edge cases covered?
3. **Review the implementation** — Walk through each file with the five axes in mind.
4. **Categorize findings** — Label every comment with its severity:
| Prefix | Meaning | Author Action |
|--------|---------|---------------|
| **Critical:** | Blocks merge | Security vulnerability, data loss, broken functionality |
| **High:** | Required change | Must address before merge |
| **Medium:** | Should fix | Strongly recommended, not a blocker |
| **Low:** | Minor, optional | Author may ignore — formatting, style preferences |
| **Suggestion:** | Worth considering | Not required, but improves the code |
**Finding IDs.** Assign every finding a stable identifier by severity class: `R1`, `R2`, … for required findings (Critical, High), `M1`, `M2`, … for minor findings (Medium, Low), and `S1`, `S2`, … for suggestions. Number within each class in review order. Use the ID everywhere the finding is mentioned — in section headers, in the verdict, in follow-up discussion. Never renumber within a review. Example: `**R2** — `app/validate.cljs:42` — duplicate branch logic…`.
For each finding, describe the circumstances under which it could fail: specific inputs, load conditions, timing, or user actions that trigger the problem. "This crashes when input is null" is actionable; "this might crash" is not.
Lead with what matters: correctness and security first, then structural issues, then everything else. A few high-conviction comments beat a long list.
5. **Check the evidence, do not re-run it** — Which tests cover the change? What did the author run, and what did CI report? Never re-run the full suite or a build yourself: the author's run and CI already cover that, and repeating it only lengthens the review. Run at most the single test file that settles a specific doubt. When no checks have been run at all (a change you did not see tested), run the module's checks before the verdict.
## Change Sizing
Small, focused changes are easier to review, faster to merge, and safer to deploy. Flag the size when a diff exceeds ~300 lines, or when it grows a file past ~1000 total lines, and name the remedy: split it, and separate refactoring from feature work. This is a finding about the change, not work to do inside the review.
## Dependencies
Before accepting a new dependency: does the existing stack already solve it, how large is the bundle impact, is it maintained, does `npm audit` report anything, is the license compatible. Prefer the standard library and existing utilities — every dependency is a liability.
For upgrades: read the changelog, not just the version number; one dependency per change; a green suite before and after; review the lockfile diff and never hand-edit it. Supply-chain triage follows `security-and-hardening`.
## Review Output
Structure every review using this format:
### Summary
Briefly explain what the code does and give an overall assessment.
### Critical and High-Priority Issues
List problems that could cause security incidents, data loss, crashes, incorrect behavior, or major performance degradation. Each finding gets its unique ID (`R1`, `R2`, …). For each: state the severity, identify the file/function/code section, explain why it's a problem, describe failure circumstances, and provide a concrete improvement with corrected code when useful.
### Other Findings
List medium- and low-priority issues, including maintainability and design concerns. Use `M1`, `M2`, … for Medium/Low and `S1`, `S2`, … for Suggestions.
### Suggested Refactoring
Provide focused code changes or revised snippets. Preserve existing behavior unless a behavior change is explicitly justified.
### Testing Recommendations
Identify missing tests and describe specific test cases, including edge cases and failure scenarios.
### Positive Observations
Mention implementation choices that are clear, safe, efficient, or well designed. This is not fluff — it reinforces good patterns and tells the author what to keep doing.
### Final Verdict
Choose one:
- **Approve** — Ready to merge
- **Approve with minor changes** — Good to merge after addressing low/medium issues
- **Request changes** — Critical or high issues must be resolved before merge
List the finding IDs the verdict depends on (e.g. "Request changes: R1, R2").
## Red Flags
- A change merged without any review.
- A review that only checks whether the tests pass.
- Security-sensitive changes without a security-focused review.
- A change too large to review properly: split it.
## Verification
Before emitting the verdict, confirm the evidence the review rests on. This covers the state of the code at review time, not the later fixing of findings:
- [ ] The suite is green, and the evidence is the author's run or CI — not your own re-run. Say which one you relied on.
- [ ] New behavior has tests that cover the edge cases in the diff.
- [ ] The verification story is stated: what changed and how it was verified.
- [ ] Dependency changes were reviewed against the changelog and the lockfile diff.
Return a short summary, findings ordered by impact and a verdict with the
relevant IDs: **Approve**, **Approve with minor changes**, or **Request
changes**. State verification evidence and limitations. Do not duplicate
remedies or tests in separate sections. If no findings exist, say so. In
follow-up, retain original IDs and
report resolved, pending and not-addressed findings as `review-code` requires.

View File

@ -7,7 +7,7 @@ slash: true
# Skill: create-commit
Produce a git commit that follows Penpot's commit message conventions. This
skill owns the commit format, staging review, and safety checks — it does not
skill handles staging review and safety checks — it does not
implement features or push.
## When to Use
@ -23,15 +23,9 @@ subject/body limits, and the `AI-assisted-by` trailer. Follow it exactly.
## Iron Rules (non-negotiable)
1. **Wrap every body line at 80 characters or fewer.** Count characters, do
not eyeball. Exceptions: `Signed-off-by:` / `AI-assisted-by:` trailers and
lines carrying a URL. This is the rule agents skip most often.
2. **Subject ≤80 chars**, imperative, capitalized, no trailing period.
`Merge`/`Revert`/`Reapply` commits skip the length check.
3. **Blank line between subject and body.**
4. **Run `./scripts/check-commit` and require exit code 0.** It mechanically
checks rules 1–3. A non-zero exit is a hard blocker: fix the message and
re-commit. Never report the commit as done with a failing checker.
Follow the message rules and exceptions in `mem:workflow/creating-commits`.
**Run `./scripts/check-commit` and require exit code 0.** A non-zero exit is a
hard blocker: fix the message and re-check it before reporting success.
## Workflow
@ -67,4 +61,4 @@ subject/body limits, and the `AI-assisted-by` trailer. Follow it exactly.
bots are rejected by `./scripts/check-commit`; for AI participation use the
`AI-assisted-by:` trailer.
- Do not add untracked files that were not created in this session.
- Do not skip the `scripts/check-commit` verification step (Iron Rule 4).
- Do not skip the `scripts/check-commit` verification step.

View File

@ -18,7 +18,7 @@ push — the user pushes from their own shell.
- The user asks to open or create a NEW PR for the current task branch, in
any phrasing ("open a PR", "create the pull request", "put this up for
review") — or runs `/create-pr`. → **Open mode**.
review") — or invokes `@create-pr`. → **Open mode**.
- The user asks to fix or update an EXISTING PR's title or description to
match conventions. → **Update mode**.
@ -59,7 +59,7 @@ Run all checks before reporting, then report every failure together:
5. **Branch not pushed.** The remote-tracking ref `origin/<branch>` is
missing, or `git rev-parse origin/<branch>` differs from HEAD — the
branch was never pushed, or has commits the remote does not have. Never
push yourself; ask the user to push and to run `/create-pr` again
push yourself; ask the user to push and to invoke `@create-pr` again
afterwards, then stop.
### 3. Already-open PR

View File

@ -26,12 +26,17 @@ in the local working tree.
- The user asks to implement or execute a plan, in any phrasing:
"implement the plan", "execute it", "go build it" — or runs
`/implement-plan`.
`@implement-plan`.
- A ready, reviewed plan is in the session context or a plan file path
was given (typically after `/make-a-plan` or `/review-plan`).
was given (typically after `@make-a-plan` or `@review-plan`).
Do not use it to produce plans — that is the `make-a-plan` flow.
For a plan derived from a code review, retain its review target, reviewer
session ID, original findings and decisions. Record the starting revision and
the exact commits or diff produced by this implementation, plus test evidence,
in session context for follow-up. Do not put commit hashes in the plan file.
## 1. Read the plan first
Identify the plan to execute — from the file path the user gave, the
@ -111,19 +116,20 @@ Implement every task in one go. Work methodically, keeping changes
focused on what the issue requires. Respect the plan's proposed
parallelization when it applies.
When the implementation is complete, close the plan file first: flip its
`Status` to `done` and append one UTC ISO 8601 line to its `Review Log`
with the issue URL when one exists (standalone mode, e.g.
`https://github.com/penpot/penpot/issues/NNNN`); in continue/direct
mode with no issue, just `done` with no invented identifier. Never
record commit hashes. Leave the closed plan file local and uncommitted.
Then load the **`create-commit`** skill and follow its workflow to commit
When the implementation is complete, load the **`create-commit`** skill and
follow its workflow to commit
only the implementation, tests, memory, and documentation changes. Before
committing, verify that the staged file list does not contain the plan
file. Provide a brief summary of what was implemented and why, the issue
reference (`issue-NNNN`) when there is one, and the model name you are
running as so the `AI-assisted-by` trailer is set correctly.
Only after the commit exists and passes its checks, close the plan: flip
`Status` to `done` and append one UTC ISO 8601 line to `Review Log` with the
issue URL when one exists; otherwise record `done` without inventing an
identifier. Never record commit hashes. Leave the plan local and uncommitted.
If the commit or its checks fail, do not close the plan.
### Step-by-step mode (on request)
When the user asks for it — "step by step", "task by task", "one commit
@ -146,12 +152,23 @@ stop and ask the user before splitting it.
## When you are done
After the entire plan is implemented and verified, including the final task in
step-by-step mode, if it addresses code review findings, ask whether the user
wants the original reviewer to verify the corrections. Use the `question` tool
if available; otherwise ask in chat. Wait for the answer. Do not start the
follow-up without consent, and do not ask after each intermediate task.
If the user accepts, follow `@review-code`'s follow-up procedure with the
review context, decisions, exact correction range or diff and test evidence.
If the original reviewer cannot be resumed, say so and use a new reviewer with
the same context. If the user declines, stop without starting a review. The
follow-up is read-only; further fixes require the user's direction.
End by suggesting the next steps (suggestions, not a required pipeline — any
instruction from me overrides them):
- `/review-code` — to review the changes just committed; it routes to
`/make-a-plan` by itself if the findings need one.
- `/create-pr` — when the task is done and the branch is ready to merge.
- `@review-code` — for a new independent review of the changes.
- `@create-pr` — when the task is done and the branch is ready to merge.
## User input, overrides and additional context

View File

@ -86,7 +86,7 @@ log path.
./scripts/ci --lint frontend
# Changed common/ — validate its consumers too
./scripts/ci frontend backend exporter
./scripts/ci common frontend backend exporter
# Preview what would run, without running it
./scripts/ci --dry-run --all

View File

@ -16,19 +16,18 @@ stop — this skill needs the build agent to save the plan.
- The user asks to plan, design, or break down a task, in any phrasing:
"make a plan", "how would we build X", "design an approach for Y" —
or runs `/make-a-plan`.
or invokes `@make-a-plan`.
- The user asks to rework or extend an existing plan. While the plan is
still unimplemented (pre-`implement-plan` iteration, e.g. after
`/review-plan` findings or user feedback), revise the saved plan file
`@review-plan` findings or user feedback), revise the saved plan file
in place. Once the plan has been implemented and reviewed (post
`/review-code` findings on committed work), write a new derived plan
`@review-code` findings on committed work), write a new derived plan
file instead — never rewrite the executed plan. The `planner` skill
defines the derived naming (`--review-NN`, `--task-NN`).
- The user says to apply `review-plan` findings to a still-unimplemented
plan: apply the agreed changes, flip `Status` to `reviewed`, and
append one UTC ISO 8601 line to `Review Log` describing what changed.
This apply step is the only pre-implementation write to those fields —
`review-plan` itself stays read-only and never writes.
- The user says to apply additional review feedback to a still-unimplemented
plan: apply the agreed changes, flip `Status` to `reviewed`, and append one
UTC ISO 8601 line to `Review Log`. `review-plan` can also update the plan
and its metadata as part of its own review flow.
Do not use it to execute a plan — that is the `implement-plan` flow.
@ -39,6 +38,11 @@ Do not use it to execute a plan — that is the `implement-plan` flow.
example, `delegated` in the user context), 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).
When the plan addresses a code review, preserve the review target, reviewer
session ID if available, original findings and IDs, and decisions including
deferred or rejected findings and their reasons in the local plan. Map
accepted findings to tasks. If context is unavailable, mark it unknown; do
not invent it. Pass this context to a delegated planner too.
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.
@ -101,8 +105,8 @@ constraints and risks, what is deliberately out of scope, and the path where the
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.
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).

View File

@ -1,315 +1,105 @@
---
name: plan-review-criteria
description: Plan review criteria — the six review axes, severity rubric, approval standard, and output format for reviewing implementation plans. Loaded by the reviewer subagent of the review-plan flow. Not a user-facing flow — to review a plan, use the review-plan flow.
description: Criteria for reviewing implementation plans, including evidence, severity and verdicts. Loaded by the review-plan subagent.
---
# Plan Review Criteria
## Overview
Evaluate whether the plan can deliver its stated goal safely and whether a
skilled implementer can execute and verify it without guessing. Perfect plans
do not exist: do not block on personal preferences or missing sections that
add no useful information. Apply each criterion in proportion to the plan's
scope and risks; explain when a criterion is not applicable.
Multi-dimensional plan review with quality gates. Every plan gets reviewed before implementation starts — no exceptions. Review covers six axes: completeness, task quality, architecture & sequencing, risk coverage, actionability, and proposed code quality.
Follow `review-plan` for delegation, permitted edits, decisions and handover.
Do not run tests, builds or other state-changing checks during the review.
**The approval standard:** Approve a plan when it is specific enough that a skilled implementer could execute it without guessing, the task ordering is sound, and risks are acknowledged. Perfect plans don't exist — the goal is confidence that implementation won't derail. Don't block a plan because it isn't exactly how you would have structured it. If it's executable and well-organized, approve it.
## Evidence and scope
## When to Use
- Read the plan, relevant code, project guidance and module memories. Check
that cited paths, symbols and proposed commands exist and are appropriate;
distinguish verified facts from assumptions and unknowns. Do not invent
findings or claim checks were run when they were not.
- Check that tasks serve the stated goal and respect existing requirements and
decisions. Identify scope creep, contradictions and dependencies on external
work. A consequential change in scope, behavior or tradeoffs needs the user's
decision.
- Evaluate the proposed approach even without code snippets: does it solve the
problem, fit existing conventions and avoid unnecessary complexity? If the
plan includes code, also check its types, signatures and examples.
- The reviewer subagent of the `review-plan` flow loads this skill to perform
the review of a plan.
- To review a plan, always go through the `review-plan` flow — never load this
skill directly for that. This is the criteria reference, not the flow.
**Do NOT use for:** Single-file changes with obvious scope, or when the task is trivial enough to just do.
## The Six-Axis Review
Every plan gets evaluated across these dimensions:
## Six review axes
### 1. Completeness
Does the plan cover everything needed to implement successfully?
- Is the **context** clear? (What problem, why now, what's the goal?)
- Are **affected modules** identified with paths?
- Are **architecture decisions** documented with rationale?
- Is there a **testing strategy**?
- Are **verification commands** explicit (not "run the tests")?
- Are **open questions** listed (not buried in someone's head)?
- Is there a **parallelization** assessment for multi-task plans?
**Missing any of these is a gap, not a nit.**
### 2. Task Quality
Are the tasks well-defined and independently executable?
- Does every task have **acceptance criteria**? (Testable, not vague)
- Does every task have **verification steps**?
- Are tasks **sized appropriately**? (XS–M is ideal, L is acceptable, XL must be split)
- Are **dependencies** between tasks explicitly stated?
- Are **files likely touched** listed?
- Is each task a **single, self-contained change**? (Not "implement the whole feature")
- Could a skilled implementer pick up any task and execute it without asking clarifying questions?
### 3. Architecture & Sequencing
Is the plan structured so implementation flows correctly?
- Does implementation order follow the **dependency graph** (foundations first)?
- Are tasks **vertically sliced** (feature paths) rather than horizontally layered?
- Does each task leave the system in a **working state**?
- Are there **checkpoints** between major phases?
- Are **high-risk tasks early** (fail fast)?
- Is the total plan a reasonable number of tasks? (More than ~15 tasks suggests the scope should be split into multiple plans)
### 4. Risk Coverage
Are the hard parts acknowledged and mitigated?
- Are **edge cases** identified?
- Are **breaking changes** or **migration concerns** noted?
- Are **security implications** considered?
- Are **performance implications** considered?
- Are **external dependencies** or integration risks flagged?
- Is there a plan for **rollback** if something goes wrong?
- Are **data integrity** risks addressed (what happens if a migration fails mid-way)?
### 5. Actionability
Can an implementer actually execute this?
- Are **file paths** specific (not "update the relevant files")?
- Are **function/method names** mentioned where applicable?
- Are **verification commands** copy-pasteable (not "run the linter")?
- Are **test commands** project-specific (not generic)?
- Is the **code shape** described where the implementation isn't obvious?
- Are **conventions** referenced (naming, patterns, existing utilities to reuse)?
- Does the plan reference **existing code** the implementer should read first?
### 6. Proposed Code Quality *(when the plan includes implementation details)*
If the plan proposes code shapes, function signatures, data structures, or API designs, evaluate those proposals against `code-review-criteria`:
- **Correctness:** Do the proposed types/signatures handle edge cases (null, empty, boundaries)?
- **Readability:** Are proposed names descriptive and consistent with project conventions?
- **Architecture:** Do proposed abstractions follow existing patterns? Are they justified (not over-engineered)?
- **Security:** Do proposed APIs validate input at boundaries? Any injection/XSS vectors in the design?
- **Performance:** Do proposed data structures avoid N+1 patterns? Any unbounded operations in the design?
**When to apply:** Only when the plan includes specific code snippets, type definitions, API contracts, or function signatures. Plans that only describe "what" without showing "how" skip this axis.
## Structural Remedies
When you flag a structural problem in a plan, propose the fix — not just the problem:
- **A task is too large (XL):** Split it into vertical slices. Each slice should be independently testable.
- **Missing acceptance criteria:** Draft 2–3 specific, testable conditions for the task.
- **Wrong sequencing:** Identify the dependency and propose the correct order.
- **No checkpoints:** Suggest where checkpoints should go (typically after every 2–3 tasks).
- **Vague verification:** Replace "run tests" with the actual project command.
- **Horizontal slicing:** Restructure into vertical feature paths.
- **Missing risk section:** Draft the risks you can identify from the plan content.
Prefer the remedy that makes the plan immediately actionable over one that just flags the gap.
## Plan Sizing
Plans should be scoped to a single deliverable:
```
1–5 tasks → Good. A focused feature or bug fix.
6–10 tasks → Acceptable for a moderate feature.
11–15 tasks → Large. Consider splitting into phases.
15+ tasks → Too large. Split into multiple plans.
```
**What counts as "one plan":** A self-contained set of changes that delivers a single coherent capability. If you can describe the goal in one sentence, it's one plan.
## Categorize Findings
Label every comment with its severity so the author knows what's required vs optional:
| Prefix | Meaning | Author Action |
|--------|---------|---------------|
| *(no prefix)* | Required change | Must address before implementation starts |
| **Critical:** | Blocks implementation | Missing security consideration, data integrity risk, fundamentally wrong approach |
| **Nit:** | Minor, optional | Author may ignore — wording, formatting |
| **Optional:** / **Consider:** | Suggestion | Worth considering but not required |
| **FYI** | Informational only | No action needed — context for future reference |
**Lead with what matters.** Order findings by leverage: missing risks and wrong sequencing first, then task quality gaps, then completeness, then nits. If you have one critical sequencing problem and ten nits, the sequencing problem *is* the review.
## Review Process
### Step 1: Understand the Goal
Before evaluating structure, understand intent:
```
- What is this plan trying to accomplish?
- What problem does it solve?
- What does "done" look like?
```
### Step 2: Check Completeness First
Scan for missing sections before diving into content:
```
- Context present?
- Affected modules listed?
- Architecture decisions documented?
- Risks acknowledged?
- Testing strategy defined?
- Verification commands explicit?
```
### Step 3: Review Task Quality
Walk through each task:
```
For each task:
1. Can I tell exactly what to build?
2. Are acceptance criteria specific and testable?
3. Is the size reasonable (not XL)?
4. Are dependencies clear?
5. Would I know which files to touch?
```
### Step 4: Validate Sequencing
Check the dependency graph:
```
- Are foundations built first?
- Does each task leave the system working?
- Are checkpoints placed correctly?
- Are high-risk items early?
- Is it vertically sliced?
```
### Step 5: Assess Actionability
Put yourself in the implementer's shoes:
```
- Could I pick up task 1 and start coding without asking any questions?
- Are the verification commands copy-pasteable?
- Are file paths and function names specific?
- Is existing code referenced where I'd need to read it?
```
### Step 6: Verify the Verification Story
Check that the plan can actually confirm it worked:
```
- What tests should pass after implementation?
- What build/compile commands are relevant?
- What manual checks are needed?
- How do we know the feature works end-to-end?
```
### Step 7: Evaluate Proposed Code Quality *(if applicable)*
If the plan includes code snippets, types, or API designs:
```
- Load code-review-criteria skill for criteria
- Check proposed signatures for edge cases
- Verify naming follows project conventions
- Confirm abstractions follow existing patterns
- Scan for security vectors in proposed APIs
- Check for performance issues in proposed data structures
```
## Review Checklist
```markdown
## Review: [Plan title]
### Completeness
- [ ] Context explains the problem and goal
- [ ] Affected modules are listed with paths
- [ ] Architecture decisions have rationale
- [ ] Testing strategy is defined
- [ ] Verification commands are explicit and project-specific
- [ ] Open questions are listed
### Task Quality
- [ ] Every task has acceptance criteria
- [ ] Every task has verification steps
- [ ] Tasks are sized XS–M (L acceptable, XL must be split)
- [ ] Task dependencies are stated
- [ ] Files likely touched are listed
### Architecture & Sequencing
- [ ] Order follows dependency graph (foundations first)
- [ ] Vertically sliced (not horizontal layers)
- [ ] Each task leaves system working
- [ ] Checkpoints exist between phases
- [ ] High-risk tasks are early
### Risk Coverage
- [ ] Edge cases identified
- [ ] Breaking changes / migrations noted
- [ ] Security implications considered
- [ ] Performance implications considered
- [ ] Rollback strategy exists (if applicable)
### Actionability
- [ ] File paths are specific
- [ ] Verification commands are copy-pasteable
- [ ] Existing code to read is referenced
- [ ] Conventions and patterns are noted
### Proposed Code Quality *(if plan includes implementation details)*
- [ ] Proposed types/signatures handle edge cases
- [ ] Proposed names follow project conventions
- [ ] Proposed abstractions follow existing patterns
- [ ] No security vectors in proposed APIs
- [ ] No performance issues in proposed structures
### Verdict
- [ ] **Approve** — Ready to implement
- [ ] **Request changes** — Gaps must be addressed
```
## Common Rationalizations
| Rationalization | Reality |
|---|---|
| "I'll figure out the details during implementation" | That's how you discover blocking dependencies mid-task. Surface them now. |
| "The tasks are obvious, no need for criteria" | Write them anyway. Explicit criteria surface hidden assumptions. |
| "It's just a small feature, it doesn't need a plan" | Small features have edge cases too. 3 tasks with criteria takes 5 minutes. |
| "The plan is good enough" | "Good enough" without acceptance criteria means the implementer defines "done" — and they might define it differently. |
| "I'll add verification steps later" | Later never comes. The plan is the contract — define verification now. |
| "Risks are minimal" | Every change has risks. If you can't name them, you haven't thought about them. |
| "The file paths are obvious" | They're obvious to the author. The implementer might not know the codebase. |
| "The code in the plan is fine, it'll get reviewed later" | Plan-level code review catches design problems before implementation — fixing them after coding is more expensive. |
## Red Flags
- No acceptance criteria on any task
- Tasks that say "implement the feature" without specifics
- No verification steps anywhere in the plan
- All tasks are XL-sized
- No checkpoints between phases
- Dependency order isn't considered (e.g., API handler before domain model)
- No testing strategy
- Verification commands are generic ("run tests") instead of project-specific
- Plan has 20+ tasks (scope too large for one plan)
- No risk section on a plan with migrations, breaking changes, or security implications
- Horizontal slicing (all domain, then all services, then all API)
- File paths are vague ("update the relevant files")
- Missing open questions section despite stated unknowns
- Proposed code ignores project conventions or existing patterns
- Proposed types use gratuitous `any`/`unknown`/optional without justification
- Proposed APIs don't validate input at boundaries
## See Also
- For producing plans, use the `planner` skill
- For reviewing implemented code, use `code-review-criteria` — also the criteria source for axis 6
- For security-specific concerns, see `security-and-hardening`
- For testing strategy guidance, see `testing`
Are the problem, intended outcome, affected areas and relevant constraints
clear? Does the plan explain important decisions and include an appropriate
testing strategy? Identify missing information that would change the outcome
or force an implementer to guess. Require risk, rollback, migration or
parallelization details only when relevant.
### 2. Task quality
Are tasks scoped, ordered and specific enough to execute? Check likely files,
dependencies, rationale, acceptance criteria and verification where relevant.
Acceptance criteria should describe observable behavior, including important
failure cases. Split work when it is too large to understand or verify safely,
not merely because it crosses an arbitrary task count.
### 3. Architecture and sequencing
Does the approach fit the existing architecture and reuse appropriate
facilities? Do dependencies precede their consumers, and can the work be
verified as it progresses? Prefer independently testable slices where useful;
use checkpoints where risk or coordination warrants them, not at a fixed
interval. Flag unrelated work or abstractions that add complexity without
helping the goal.
### 4. Risk coverage
Consider relevant edge cases, security, performance, compatibility, data
integrity, migrations and external dependencies. Where failure has meaningful
consequences, check detection, mitigation and rollback or recovery. Do not
invent risks or demand a rollback section for changes that do not need one.
### 5. Actionability and verification
Can the implementer identify the affected code, follow project conventions and
run the stated project-specific checks? Are commands and prerequisites correct?
Do tests and other checks demonstrate the intended behavior and important
failure cases? Surface unknowns honestly rather than presenting an unverified
command or assumption as fact.
### 6. Proposed solution quality
Assess correctness, clarity, architecture, security and performance of the
proposed solution, even when the plan contains no code. For any code sketches,
also check boundary cases, names, types and contracts. Preserve intended
behavior unless a change is explicitly agreed; prefer the simplest solution
that meets the requirements.
## Findings and verdict
Give each reported item a stable ID (`P1`, `P2`, …); retain it throughout the
review and any decision walkthrough. For each item state the evidence, impact,
concrete remedy and verification needed. For a consequential user decision,
include real options, consequences and a recommendation.
- **Blocking:** implementation cannot proceed safely or an essential user
decision remains open. Explain what blocks it.
- **Improvement:** a clear correction that preserves the agreed goal, scope
and behavior. Apply it under `review-plan`'s permitted-edit rules.
- **Optional:** a suggestion that does not prevent implementation. Do not
silently expand scope or override the user's decisions.
Report applied improvements and any outstanding items with their IDs. Give a
provisional verdict before any walkthrough and a final verdict after applying
the decisions:
- **Ready:** no blocking issue or essential decision remains.
- **Awaiting decisions:** user decisions are needed before the plan is ready.
- **Blocked:** required work or evidence is missing and cannot be resolved by
applying clear improvements or obtaining the current decisions alone.
Do not approve an unresolved blocker. A plan may be ready with optional
suggestions; identify them without treating them as required.

View File

@ -42,9 +42,10 @@ Skipping this step is the #1 cause of incorrect or incomplete plans.
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`,
`find`, `cat`, `bat`).
- You do **not** create commits or run commands that modify version control.
Read-only inspection such as `git status`, `git log`, `git show` and
`git diff` is allowed.
- Shell commands must be read-only.
- Your output is a structured plan or analysis, ready for handoff to an
engineer agent or developer.
@ -192,8 +193,8 @@ Source: review-code over `<commit>` (branch `<branch>`) | task `NN` of roadmap `
Created: YYYY-MM-DD
```
End the response by suggesting the next steps: `/review-plan` to get a second
opinion on the plan and `/implement-plan` to execute it.
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 Structure
@ -223,16 +224,16 @@ Review Log:
log. `reviewed` never means "a review was emitted" — it means
"review feedback was incorporated". A plan approved with no changes
goes `draft` → `done` without passing through `reviewed`.
- Only a user-triggered apply step writes them before implementation:
when the user says to apply `review-plan` findings, `make-a-plan`
applies the changes, flips to `reviewed`, and appends one UTC
ISO 8601 line describing what changed.
- Before implementation, `review-plan` applies clear review feedback and
agreed decisions, flips to `reviewed` and appends one UTC ISO 8601 entry
when the plan changed. `make-a-plan` can also do this for additional
feedback when the user asks.
- `implement-plan` flips to `done` on completion and appends one line
with the issue URL when one exists (standalone mode); otherwise
just `done`. Never record commit hashes — they rot on amend/rebase
and git already links the commit.
- The log is append-only: never rewrite or delete lines.
- `review-plan` and `review-code` never write these fields.
- `review-code` never writes these fields.
Omit empty sections only when they do not apply. Every implementation task
still requires acceptance criteria, verification, dependencies, likely files,
@ -261,5 +262,5 @@ Before delivering the plan, confirm:
- [ ] 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`
`@review-plan` and `@implement-plan`
- [ ] The plan is ready for human review

View File

@ -12,7 +12,7 @@ Act as a senior software engineer and perform a thorough code review.
- The user asks to review code, in any phrasing: "review this diff",
"review the PR", "check my changes", "code review" — or runs
`/review-code`.
`@review-code`.
- A commit, branch, PR, or diff is ready and the user wants it assessed
before merge.
@ -29,22 +29,54 @@ Act as a senior software engineer and perform a thorough code review.
code being reviewed.
- Return the COMPLETE review, verbatim, exactly as the skill instructs it to
be produced. Never summarize it.
- Read-only: modify no file and create no commit. Reviewing never writes.
- Read-only: modify no file, create no commit, and run no tests, builds,
linters or other state-changing checks. Use prior results or CI evidence;
state explicitly when evidence is unavailable.
- Do not invent problems: every finding must be real and actionable.
- Missing tests are an issue, not a suggestion — a severity-tagged finding.
- For each finding, give a concrete remedy and the tests needed to verify it.
If a user decision is needed, include the real options and a recommendation
in that finding. Do not pause to ask during the review.
- Prioritize by impact: one structural issue outweighs ten nits, and "this
could be better" is not a finding — say why and how.
- Skip generated files, lockfile-only changes and unrelated modifications
unless they introduce security risks.
- Inspect generated files and lockfiles when relevant to the change, its
dependencies or security; exclude unrelated working-tree modifications.
3. When the subagent returns, output the review to the user verbatim. Do not
summarize it and do not act on its findings.
summarize it and do not act on its findings. Retain the subagent session ID,
review target and complete findings in the session context for follow-up;
do not invent an ID if the tool does not provide one.
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
- **Minor findings:** suggest direct fixes after the user ends the review if
appropriate; no plan is required.
- **Substantive findings:** suggest `@make-a-plan` to make a plan to address
them.
- If the user wants to discuss findings one by one, use `@issue-walkthrough`
on request; do not start it automatically. The walkthrough returns its
decisions to `@make-a-plan`, not to automatic code editing.
### Follow-up after implementation
When the user agrees to verify corrections, resume the original reviewer using
its session ID if the tool supports it. Give it the original review target and
findings, the decisions and plan, the exact correction commit range or diff,
and the test evidence. Require it to inspect the actual corrections and
evidence, not rely on its earlier context alone. If the original session is
unavailable or cannot be resumed, tell the user and delegate to a new reviewer
with the same context; never claim it is the original reviewer. If the review,
decisions or correction range cannot be established, ask for the missing
information rather than inventing it.
The reviewer follows `code-review-criteria` and remains read-only. It reports
each original finding with its unchanged ID as **resolved**, **pending**, or
**not addressed** (including the agreed reason); report any new problems with
new, non-conflicting IDs. For pending and new problems, give evidence, a remedy,
tests and any user decision as in the original review. Summarize separately
whether all agreed corrections are resolved and whether any findings remain,
including deferred findings. Do not equate deferred with resolved. Present the
result without implementing fixes; the user chooses whether to iterate, request
an independent review, or stop.
### Hard rule — read-only while reviewing
@ -52,9 +84,10 @@ This flow 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.
the findings. Never run tests, builds, linters or state-changing checks during
the review; inspect existing evidence instead. 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.
## Posting as a GitHub comment
@ -70,7 +103,7 @@ session. PR comments go in English, with this minimal structure:
problem, concrete remedy.
4. **Closing** — optional and short. Cut it when it adds nothing.
Reference every finding by its ID (`R1`, `M1`, `S1`, … from
Reference every finding by its ID (`F1`, `F2`, … from
`code-review-criteria`) so follow-up replies can point to findings
unambiguously.

View File

@ -1,46 +1,60 @@
---
name: review-plan
description: Plan review flow — evaluate an implementation plan before it is executed, delegating the review to a subagent that follows the plan-review-criteria skill. Use it when the user asks to review a plan, in any phrasing.
description: Review an implementation plan with a subagent, apply clear improvements and resolve consequential decisions with the user.
slash: true
---
# Review Plan
Act as a senior software engineer and perform a thorough review of an implementation plan.
Review an unimplemented plan with a subagent and improve the plan without
implementing it. Use this flow when the user asks for a plan review or invokes
`@review-plan`.
## When to use
## Flow
- The user asks to review a plan, in any phrasing: "review this plan", "does this plan look right?", "second opinion on the plan" — or runs `/review-plan`.
- A plan was just produced (typically by `/make-a-plan`) and the user wants it evaluated before executing it.
1. Identify and read the complete plan and its file. If the target or path is
ambiguous, ask. If no saved file exists, ask for a path or have the user save
it first. Do not edit a completed plan: propose a derived plan instead.
2. Delegate to `general`, unless the user specifies a different subagent or
model. Supply the plan path, relevant session context and these instructions:
- Load `plan-review-criteria`, read `AGENTS.md` and the relevant module and
testing memories, and review the plan against the criteria.
- Apply clear, evidence-based improvements directly to that plan file only.
Preserve the goal, scope, agreed decisions and intended behavior. Examples:
clarify tasks, add missing tests, correct dependencies and specify actual
verification commands. Do not guess commands or invent findings.
- A change that affects the goal, user-visible behavior, scope, tradeoffs or
an existing decision needs the user's decision. Leave it unresolved; report
concrete options, consequences and a recommendation. Do not ask questions
from the subagent.
- Return a concise summary of applied changes, remaining decisions with
stable IDs, evidence and recommendations, and an honest provisional
verdict. Retain the subagent session ID for follow-up if available.
- Do not change source files, other plans or documents, run state-changing
checks, commit, or implement the plan. If the plan is not writable, report
this and return the proposed edits instead.
3. Show the summary. If decisions remain, start `@issue-walkthrough` immediately
in the parent session with those questions and their IDs. Follow its one
question per turn and read-only rules. Do not ask questions that the code or
existing decisions settle. Wait for every answer.
4. Resume the same subagent with the decision table and plan path. It applies
the decisions to the plan, rechecks consistency and reports changes and any
newly discovered consequential decisions. Repeat the walkthrough for new
decisions, then apply those answers. If the original session cannot be
resumed, tell the user and apply the changes in the parent or delegate a new
subagent with the full context. If the reviewer cannot write, apply its
proposed edits in the parent only if the plan file is writable; otherwise
explain the blocker and stop.
5. Once all decisions are resolved and the plan is coherent, update its
metadata: when review feedback changed the plan, set `Status: reviewed` and
append one UTC ISO 8601 `Review Log` entry for this review, summarizing the
changes. Preserve prior log entries. If no feedback changed the plan, leave
status and log unchanged. Never record commit hashes. If decisions or
required changes remain unresolved, do not claim the plan is ready or mark
it reviewed.
6. Show the final summary, plan path and verdict. Suggest `@implement-plan` only
when the plan is ready. Never execute the plan automatically.
## 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 `.agents/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-criteria`** 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 flow 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-criteria`** 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. Cada hallazgo debe tener un identificador único y estable, con el formato `F1`, `F2`, etc. El identificador debe aparecer en el título del hallazgo y no debe reutilizarse dentro de la misma revisión. Esto permite que el usuario pueda responder sobre un hallazgo concreto.
4. 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 — reviewing never writes.
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
The only permitted write in this flow is the specified local plan file,
including its status and log. Do not stage or commit it. If a user instruction
overrides automatic editing, respect it and report findings without editing.

View File

@ -6,9 +6,8 @@ slash: true
# Skill: rewrite-commit-message
HEAD's message is a concatenation of older messages (typical after a
squash): several subjects, bodies and repeated trailers stacked in a
single message. Replace it with one proper message and amend HEAD.
Rewrite HEAD's title and description from its own diff. This also handles a
squash message with several subjects, bodies and repeated trailers.
## When to Use
@ -17,9 +16,11 @@ single message. Replace it with one proper message and amend HEAD.
## Steps
1. Read the full current message (`git log -1 --format=%B HEAD`) and
the branch diff (`git diff develop..HEAD --stat`, plus the code
when the summary needs grounding).
1. Check `git diff --cached` first. If any changes are staged, stop and ask
the user to handle them; an amend must never include those changes. Read
the full current message (`git log -1 --format=%B HEAD`) and HEAD's own
diff (`git show --format= --stat HEAD` and the patch). Respect the project
rule on amending pushed commits.
2. Collect every DISTINCT `AI-assisted-by:` value in the current
message. All of them survive into the new message, one line each:
attributions are never dropped in a rewrite, even when most of
@ -27,7 +28,7 @@ single message. Replace it with one proper message and amend HEAD.
3. Draft one message per `mem:workflow/creating-commits` (read it
end-to-end first): single subject (imperative, capitalized, no
trailing period, ≤80 chars), blank line, body wrapped at ≤80
chars covering the whole diff (not the old per-commit slices),
chars covering HEAD's diff (not the old per-commit slices),
then the preserved trailers.
4. Write it to a file (a heredoc keeps real newlines; inline `-m`
with `\n` does not) and `git commit --amend -F <file>`.

View File

@ -67,7 +67,7 @@ rg "user_\d+"
rg -F "function()"
# Multiline search
rg -U "start.*end"
rg -U '(?s)start.*end'
# Only show matches, not lines
rg -o "https?://[^\s]+"

View File

@ -1,6 +1,6 @@
---
name: ste
description: Write or rewrite text in ASD-STE100 Simplified Technical English. ONLY use this skill when the user explicitly invokes it by name — i.e. they type "/ste" or literally write "use the ste skill" / "apply ASD-STE100". Do NOT trigger it on paraphrased intent such as "simplify this", "make it clearer", "write technical documentation", or "shorter sentences please" — the user has deliberately scoped this skill to explicit invocation only. For those requests, respond normally without loading this skill unless they name it.
description: Write or rewrite text in ASD-STE100 Simplified Technical English. ONLY use this skill when the user explicitly invokes it by name — i.e. they type "@ste" or literally write "use the ste skill" / "apply ASD-STE100". Do NOT trigger it on paraphrased intent such as "simplify this", "make it clearer", "write technical documentation", or "shorter sentences please" — the user has deliberately scoped this skill to explicit invocation only. For those requests, respond normally without loading this skill unless they name it.
---
# ASD-STE100 Simplified Technical English
@ -11,7 +11,7 @@ Compliance note (for you, not for output): the official specification and its di
## When to use
Only when the user explicitly invokes it: they type `/ste`, or say "use
Only when the user explicitly invokes it: they type `@ste`, or say "use
the ste skill" / "apply ASD-STE100". Requests like "simplify this",
"make it clearer", or "shorter sentences" do NOT invoke it — respond
normally unless it is named.

View File

@ -1,116 +0,0 @@
---
name: taiga
description: Fetch information from Taiga public API for the Penpot project (id 345963) — issues, user stories, and tasks, without authentication.
metadata: {"clawdbot":{"requires":{"bins":["python3"]}}}
---
# Taiga API Skill
Fetch information from Taiga public API for the **Penpot** project
(project id: `345963`, slug: `penpot`).
**No authentication required** — only public project data is accessed.
## When to use
- The user asks about Penpot issues, user stories, or tasks tracked in
Taiga — fetch them via the public API (project id 345963), no
authentication needed.
## Prerequisites
- `python3` — the `scripts/taiga.py` CLI script is self-contained (stdlib only)
## Quick Start
The easiest way is to use the bundled Python script:
```bash
# Pass a Taiga URL directly
python3 scripts/taiga.py https://tree.taiga.io/project/penpot/issue/13714
# Or use "<type> <ref>" syntax
python3 scripts/taiga.py us 14128
python3 scripts/taiga.py task 13648
# Add --json for raw output
python3 scripts/taiga.py --json issue 13714
# See full usage
python3 scripts/taiga.py --help
```
## URL Pattern Reference
Taiga web URLs follow these patterns:
| Type | Web URL Pattern |
|------|----------------|
| Issue | `https://tree.taiga.io/project/penpot/issue/<REF>` |
| User Story | `https://tree.taiga.io/project/penpot/us/<REF>` |
| Task | `https://tree.taiga.io/project/penpot/task/<REF>` |
To extract the **type** and **ref** from a URL:
- `issue/13714` → type=`issue`, ref=`13714`
- `us/14128` → type=`us`, ref=`14128`
- `task/13648` → type=`task`, ref=`13648`
## Python Script Reference
The `scripts/taiga.py` script wraps the Taiga API into a single convenient CLI
with sensible defaults.
### Usage
```
python3 scripts/taiga.py <taiga-url>
python3 scripts/taiga.py <type> <ref>
python3 scripts/taiga.py [--json] <taiga-url>
python3 scripts/taiga.py [--json] <type> <ref>
```
### Examples
```bash
# By URL (recommended — no need to think about type/ref)
python3 scripts/taiga.py https://tree.taiga.io/project/penpot/issue/13714
# By type and ref
python3 scripts/taiga.py us 14128
python3 scripts/taiga.py task 13648
# Raw JSON output
python3 scripts/taiga.py --json issue 13714
```
### Output
The script prints a clean, structured summary:
```text
User Story #11964 — 🔴 [DESIGN TOKENS] Typography Composite Input
================================
Status: Defining
Milestone: design-systems-sprint-26
Points: 3 role(s)
Assignee: Natacha Menjibar
Author: Natacha Menjibar
Created: 2025-09-01
Tags: iop-design-tokens
URL: https://tree.taiga.io/project/penpot/us/11964
================================
<full description text, unmodified>
```
The fields section includes type-specific information:
- **Issues:** Status, Type ID, Severity ID, Priority ID
- **User Stories:** Status, Milestone, Points
- **Tasks:** Status, Milestone, Parent US
## Reference
- API docs: https://docs.taiga.io/api.html
- Taiga instance: https://tree.taiga.io
- API base: https://api.taiga.io/api/v1
- Penpot project id: `345963`
- Penpot project slug: `penpot`

View File

@ -1,10 +0,0 @@
---
description: Create a PR for the current task branch or update an existing one — loads and follows the create-pr skill
agent: build
---
Load the **`create-pr`** skill and follow it as your only instruction.
## User input, overrides and additional context
$ARGUMENTS

View File

@ -1,10 +0,0 @@
---
description: Execute a ready plan — task checklist, your confirmation, then all tasks with one commit (default) or step by step with a commit and a pause per task; creates issue + branch when on a base branch, or commits on the current branch with "direct" — loads and follows the implement-plan skill
agent: build
---
Load the **`implement-plan`** skill and follow it as your only instruction.
## User input, overrides and additional context
$ARGUMENTS

View File

@ -1,10 +0,0 @@
---
description: Investigate the chosen task, produce an implementation plan, and save it — loads and follows the make-a-plan skill
agent: build
---
Load the **`make-a-plan`** skill and follow it as your only instruction.
## User input, overrides and additional context
$ARGUMENTS

View File

@ -1,6 +0,0 @@
---
description: Resolve local git conflicts and stage the resolved files; never continues the rebase — loads and follows the resolve-git-conflicts skill
agent: build
---
Load the **`resolve-git-conflicts`** skill and follow it as your only instruction.

View File

@ -1,10 +0,0 @@
---
description: Code review — review a diff, PR, or code change — loads and follows the review-code skill
agent: build
---
Load the **`review-code`** skill and follow it as your only instruction.
## User input, overrides and additional context
$ARGUMENTS

View File

@ -1,10 +0,0 @@
---
description: Plan review — evaluate an implementation plan before executing it — loads and follows the review-plan skill
agent: build
---
Load the **`review-plan`** skill and follow it as your only instruction.
## User input, overrides and additional context
$ARGUMENTS

View File

@ -14,7 +14,7 @@ Backend: JVM Clojure; Integrant; PostgreSQL; Redis/Valkey; RPC; HTTP; storage; m
## Stable namespace map
- `app.rpc.commands.*`: RPC command implementations exposed under `/api/rpc/command/<cmd-name>`.
- `app.rpc.commands.*`: RPC command implementations exposed under `/api/main/methods/<method-name>`; `/api/rpc/command/<method-name>` remains as a backward-compatible route.
- `app.rpc.permissions`: permission predicate/check helper factories.
- `app.http.*`: HTTP routes and middleware.
- `app.auth.*`: provider-specific authentication helpers such as LDAP/OIDC.

View File

@ -1,4 +1,4 @@
# Clojure Design Rules
# Clojure Core
How to shape a function in this codebase. Each rule came from a review round; do not re-derive from taste.
@ -12,4 +12,4 @@ How to shape a function in this codebase. Each rule came from a review round; do
Reference implementation: the http metrics samplers in `app.http` (`sample-worker-metrics` / `sample-connector-metrics` are guard-free; `sample-http-metrics` guards at the boundary).
See also: `mem:clojure/idioms` (language behaviors), `mem:testing` (TDD and test conventions).
See also: `mem:clojure/idioms` (language behaviors and naming exceptions), `mem:clojure/logging` (structured logging), `mem:testing` (TDD and test conventions).

View File

@ -9,7 +9,7 @@ Behaviors confirmed against the language/stdlib — do not re-derive from assump
- Valid: `(defn ^:async f)`, `(defn- ^:async f)`, `(^:async fn [] …)` (the latter is what stock `t/async` generates itself).
- `^:async` fns never throw synchronously (rejected promises instead); `try/catch/finally` supported; continuations are microtasks, timers and RxJS schedulers are macrotasks (FIFO).
- Inside an `^:async` fn, a nested call that needs a temp binding (e.g. calling a local fn `(g (f x))`, whose arg gets a `G__` binding) compiles to `(await (async function(){…})())`: `await` unwraps a returned promise, so `(settled (upload (make-ctx)))` blocks until the upload promise settles instead of passing the promise on (a test that pushes the answer later hangs, idle). Bind each step in its own `let` binding.
- `!` suffix allowed cases (only exceptions to the no-new-`!` rule in `mem:clojure/design-rules`): mutating public `app.db` API (`insert!`, `update!`, `delete!`, `run!`, `tx-run!`, `exec!`, ...) and fns whose contract is to work over transients (stdlib `conj!`, `assoc!`, `dissoc!`, `disj!`, `persistent!` and custom helpers over them); any further case must be registered here with justification before use.
- `!` suffix allowed cases (only exceptions to the no-new-`!` rule in `mem:clojure/core`): mutating public `app.db` API (`insert!`, `update!`, `delete!`, `run!`, `tx-run!`, `exec!`, ...) and fns whose contract is to work over transients (stdlib `conj!`, `assoc!`, `dissoc!`, `disj!`, `persistent!` and custom helpers over them); any further case must be registered here with justification before use.
- Penpot extends `clojure.core/Inst` in `app.common.time` ( JVM-only section), so `inst-ms` also accepts `Duration` (returns `.toMillis`, NOT epoch millis), `FileTime` and `OffsetDateTime`. It only works where that namespace is loaded; on a bare `Duration`, prefer explicit `.toMillis`, which reads as what it is (an amount, not an instant).
- The threading macros insert the threaded value at DIFFERENT positions: `->` and `some->` put it FIRST (`(-> x (f a))` → `(f x a)`), `->>` and `some->>` put it LAST (`(->> x (f a))` → `(f a x)`). `some->`/`some->>` also short-circuit on nil. With unary calls both nest the same way (`(-> x (f) (g))` and `(->> x (f) (g))` are both `(g (f x))`): what changes between them is the position inside each call, not the order of the steps. A pipeline that calls a fn whose first argument is a config/context (`app.features.fdata/resolve-file-data` is `(cfg, file)`) must use `->>`/`some->>`; with `->`/`some->` the arguments are swapped and the call silently returns the wrong value (it cost a broken `get-snapshot` in `app.features.file-snapshots`).
- `cuerdas.core/index-of` returns `nil` (not `-1`) when the substring is absent, like `clojure.string/index-of`. `(pos? nil)` **throws on the JVM** but evaluates to `false` in CLJS (JS coercion), so `(if (pos? (str/index-of s "\n")) …)` works in the browser and crashes the backend. Guard with `some?` before `pos?` (this was `app.common.exceptions/first-line`).

View File

@ -8,7 +8,7 @@ You are working on the GitHub project `penpot/penpot`, a monorepo.
- Cross-cutting testing principles, TDD workflow, and anti-patterns: `mem:testing`.
- Structured logging conventions (`:hint` casing and fields, log levels): `mem:clojure/logging` — read before adding or changing any log call.
- Verified Clojure language behaviors that contradict common assumptions (e.g. `int?` covers `Long`; `integer?` is the general predicate): `mem:clojure/idioms` — read before assuming stdlib predicate semantics.
- Read `mem:clojure/design-rules` (function shape, boundary checks, naming) before writing or modifying Clojure/ClojureScript code — not only when designing a solution or an API.
- Read `mem:clojure/core` (function shape, boundary checks, naming) before writing or modifying Clojure/ClojureScript code — not only when designing a solution or an API.
- Promises: which call style to use where (`fmap`/`mcat`/`merr` vs `then`/`catch`) and how they bridge to rx: `mem:clojure/promesa` — read before chaining promises or mixing them with observables.
# Development workflow
@ -24,7 +24,6 @@ You are working on the GitHub project `penpot/penpot`, a monorepo.
- **Never `git push`, force-push, or modify `git origin`** (or any other remote). The user pushes from their own shell; if a push is required, say so and wait. Never amend a commit that the user has already pushed unless explicitly asked.
- **Never edit `CHANGES.md` by hand.** The changelog is generated from GitHub milestones during the release process; update it only via `mem:workflow/updating-changelog` (the `update-changelog` skill flow) or on explicit user request.
- You have access to the GitHub CLI `gh` or corresponding MCP tools.
- Issues are also managed on Taiga. Read issues using the `read_taiga_issue` tool.
- Before writing code, analyze the task in depth and describe your plan. If the task is complex, break it down into atomic steps. After making changes, run the applicable lint and format checks for the affected module before considering the work done (per example `mem:backend/core` or `mem:frontend/core`).
- Align `let` binding values: when a `let` form has multiple bindings spanning several lines, align the value forms to the same column with spaces.
- If you introduce delimiter errors (mismatched parens/brackets) in Clojure/CLJS files, fix them with `scripts/paren-repair` BEFORE running lint/format checks. See `mem:scripts/paren-repair` for usage.

View File

@ -144,10 +144,10 @@ E2E tests should not be added unless explicitly requested.
When running ANY test command (CLJS/JS or JVM):
1. **NEVER pipe test output directly to `| head`, `| tail`, `| grep`, or similar filters** — this can hide failures and cause you to miss critical errors.
2. **ALWAYS pipe to a file first, then read the file:**
2. **ALWAYS redirect to a file first, then read the file:**
```bash
# CORRECT:
pnpm run test 2>&1 > /tmp/test-output.txt
pnpm run test > /tmp/test-output.txt 2>&1
grep -A 5 "failures" /tmp/test-output.txt
# WRONG:

View File

@ -45,6 +45,8 @@ Do this **before planning, before coding, before touching any file**:
3. Read each affected module's **core memory** — the name is `<module>/core`
(e.g. `frontend/core`, `backend/core`, `common/core`).
4. If the core memory references deeper `mem:` memories relevant to your task, read those too.
5. Before writing or modifying Clojure or ClojureScript, read `mem:clojure/core`
and the relevant focused Clojure memories it references.
**STOP: Do not proceed until you have read the core memory of every affected module.**
Skipping this step is the #1 cause of incorrect or incomplete work.
@ -86,11 +88,6 @@ Review every prose output against these rules before delivering.
Memories are the **primary project guidance** — not docs or readme files.
They are dense, agent-oriented notes: terse bullets, invariants, no prose.
## Entry point
Start at `critical-info` (the graph root). It describes the project structure,
module dependency graph, and references section-level core memories.
## Progressive discovery model
Memories form a **reference graph**, not a flat list:
@ -102,11 +99,8 @@ critical-info ← read first (graph root)
└─ ... ← deeper memories as needed
```
When working on a task:
1. Read `critical-info` to identify which sections are affected.
2. Read the affected section's `core` memory for an overview.
3. Follow `mem:` references in the core memory to focused memories relevant to your task.
4. Continue following references deeper as needed.
Follow the mandatory reading sequence above. Cross-cutting topics can also be
referenced directly from `critical-info` or other memories.
## Accessing memories
@ -126,9 +120,8 @@ When you encounter a `mem:` reference relevant to your task, read that memory ne
## Topic/folder organization
Memories are grouped into folders that mirror project modules or topics:
`backend/`, `common/`, `frontend/`, `render-wasm/`, `exporter/`, `workflow/`, etc.
Each folder's top-level memory is `<folder>/core`.
Memories are grouped into folders for modules or topics. Project modules have
a `<module>/core` memory; other topic folders may contain focused memories only.
---
@ -164,4 +157,3 @@ precision while maintaining a strong focus on maintainability and performance.
- `scripts/check-fmt-clj` — Check Clojure formatting without modifying files.
- `scripts/ci` — CI orchestration script for running lint, tests, format checks and, on request (`--build`), production builds across modules. See `mem:scripts/ci`.
- `scripts/gh.py` — Multi-purpose GitHub CLI helper. Subcommands: `issues` (list issues in a milestone), `prs` (fetch PR details), `advisories` (list/inspect security advisories). See `python3 scripts/gh.py --help`.