diff --git a/.agents/README.md b/.agents/README.md index 371444a89d..98937323af 100644 --- a/.agents/README.md +++ b/.agents/README.md @@ -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. diff --git a/.agents/skills/code-review-criteria/SKILL.md b/.agents/skills/code-review-criteria/SKILL.md index b95c563a57..af926a26e2 100644 --- a/.agents/skills/code-review-criteria/SKILL.md +++ b/.agents/skills/code-review-criteria/SKILL.md @@ -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. diff --git a/.agents/skills/create-commit/SKILL.md b/.agents/skills/create-commit/SKILL.md index 264f870e03..2a49b29dc8 100644 --- a/.agents/skills/create-commit/SKILL.md +++ b/.agents/skills/create-commit/SKILL.md @@ -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. diff --git a/.agents/skills/create-pr/SKILL.md b/.agents/skills/create-pr/SKILL.md index 3ab1ccf5d5..00d8fd7dc6 100644 --- a/.agents/skills/create-pr/SKILL.md +++ b/.agents/skills/create-pr/SKILL.md @@ -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/` is missing, or `git rev-parse origin/` 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 diff --git a/.agents/skills/implement-plan/SKILL.md b/.agents/skills/implement-plan/SKILL.md index ec81467343..20dbce4d75 100644 --- a/.agents/skills/implement-plan/SKILL.md +++ b/.agents/skills/implement-plan/SKILL.md @@ -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 diff --git a/.agents/skills/local-ci/SKILL.md b/.agents/skills/local-ci/SKILL.md index d04f581dc1..c6ab6d30b7 100644 --- a/.agents/skills/local-ci/SKILL.md +++ b/.agents/skills/local-ci/SKILL.md @@ -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 diff --git a/.agents/skills/make-a-plan/SKILL.md b/.agents/skills/make-a-plan/SKILL.md index 2314b559a8..7a46cd9261 100644 --- a/.agents/skills/make-a-plan/SKILL.md +++ b/.agents/skills/make-a-plan/SKILL.md @@ -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). diff --git a/.agents/skills/plan-review-criteria/SKILL.md b/.agents/skills/plan-review-criteria/SKILL.md index 649bd1118f..86352f6b77 100644 --- a/.agents/skills/plan-review-criteria/SKILL.md +++ b/.agents/skills/plan-review-criteria/SKILL.md @@ -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. diff --git a/.agents/skills/planner/SKILL.md b/.agents/skills/planner/SKILL.md index a242cf83bd..7874bbccfd 100644 --- a/.agents/skills/planner/SKILL.md +++ b/.agents/skills/planner/SKILL.md @@ -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 `` (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 diff --git a/.agents/skills/review-code/SKILL.md b/.agents/skills/review-code/SKILL.md index 65c811e71d..564db4faa8 100644 --- a/.agents/skills/review-code/SKILL.md +++ b/.agents/skills/review-code/SKILL.md @@ -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. diff --git a/.agents/skills/review-plan/SKILL.md b/.agents/skills/review-plan/SKILL.md index 431610db5e..b4beb20641 100644 --- a/.agents/skills/review-plan/SKILL.md +++ b/.agents/skills/review-plan/SKILL.md @@ -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. diff --git a/.agents/skills/rewrite-commit-message/SKILL.md b/.agents/skills/rewrite-commit-message/SKILL.md index 3281d0fa75..7284f0721b 100644 --- a/.agents/skills/rewrite-commit-message/SKILL.md +++ b/.agents/skills/rewrite-commit-message/SKILL.md @@ -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 `. diff --git a/.agents/skills/ripgrep/SKILL.md b/.agents/skills/ripgrep/SKILL.md index 1b028d8c58..e7690ed9e8 100644 --- a/.agents/skills/ripgrep/SKILL.md +++ b/.agents/skills/ripgrep/SKILL.md @@ -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]+" diff --git a/.agents/skills/ste/SKILL.md b/.agents/skills/ste/SKILL.md index 67e474ef6b..049c75c069 100644 --- a/.agents/skills/ste/SKILL.md +++ b/.agents/skills/ste/SKILL.md @@ -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. diff --git a/.agents/skills/taiga/SKILL.md b/.agents/skills/taiga/SKILL.md deleted file mode 100644 index a5f32565a1..0000000000 --- a/.agents/skills/taiga/SKILL.md +++ /dev/null @@ -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 " " 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/` | -| User Story | `https://tree.taiga.io/project/penpot/us/` | -| Task | `https://tree.taiga.io/project/penpot/task/` | - -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 -python3 scripts/taiga.py -python3 scripts/taiga.py [--json] -python3 scripts/taiga.py [--json] -``` - -### 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 -================================ - -``` - -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` diff --git a/.opencode/commands/create-pr.md b/.opencode/commands/create-pr.md deleted file mode 100644 index a6c21f7bb2..0000000000 --- a/.opencode/commands/create-pr.md +++ /dev/null @@ -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 diff --git a/.opencode/commands/implement-plan.md b/.opencode/commands/implement-plan.md deleted file mode 100644 index eaf9d29fc3..0000000000 --- a/.opencode/commands/implement-plan.md +++ /dev/null @@ -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 diff --git a/.opencode/commands/make-a-plan.md b/.opencode/commands/make-a-plan.md deleted file mode 100644 index 27a2be5559..0000000000 --- a/.opencode/commands/make-a-plan.md +++ /dev/null @@ -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 diff --git a/.opencode/commands/resolve-git-conflicts.md b/.opencode/commands/resolve-git-conflicts.md deleted file mode 100644 index 05b13d3a4b..0000000000 --- a/.opencode/commands/resolve-git-conflicts.md +++ /dev/null @@ -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. diff --git a/.opencode/commands/review-code.md b/.opencode/commands/review-code.md deleted file mode 100644 index 4bea9ab7ff..0000000000 --- a/.opencode/commands/review-code.md +++ /dev/null @@ -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 diff --git a/.opencode/commands/review-plan.md b/.opencode/commands/review-plan.md deleted file mode 100644 index 90bc6161a9..0000000000 --- a/.opencode/commands/review-plan.md +++ /dev/null @@ -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 diff --git a/.serena/memories/backend/core.md b/.serena/memories/backend/core.md index 77ba723328..9be0eb103f 100644 --- a/.serena/memories/backend/core.md +++ b/.serena/memories/backend/core.md @@ -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/`. +- `app.rpc.commands.*`: RPC command implementations exposed under `/api/main/methods/`; `/api/rpc/command/` 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. diff --git a/.serena/memories/clojure/design-rules.md b/.serena/memories/clojure/core.md similarity index 94% rename from .serena/memories/clojure/design-rules.md rename to .serena/memories/clojure/core.md index e39facedc3..876b003a49 100644 --- a/.serena/memories/clojure/design-rules.md +++ b/.serena/memories/clojure/core.md @@ -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). diff --git a/.serena/memories/clojure/idioms.md b/.serena/memories/clojure/idioms.md index e8c7bc299e..51726e9c76 100644 --- a/.serena/memories/clojure/idioms.md +++ b/.serena/memories/clojure/idioms.md @@ -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`). diff --git a/.serena/memories/critical-info.md b/.serena/memories/critical-info.md index 2e9c0c6f5a..19c74e4d98 100644 --- a/.serena/memories/critical-info.md +++ b/.serena/memories/critical-info.md @@ -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. diff --git a/.serena/memories/testing.md b/.serena/memories/testing.md index 75b775d0ec..81a1361674 100644 --- a/.serena/memories/testing.md +++ b/.serena/memories/testing.md @@ -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: diff --git a/AGENTS.md b/AGENTS.md index 261d099e68..b492067467 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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 `/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 `/core`. +Memories are grouped into folders for modules or topics. Project modules have +a `/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`. -