@igorlau/dotagents 1.0.14 → 1.0.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/README.md +129 -35
  2. package/THIRD_PARTY_NOTICES.md +76 -2
  3. package/dist/build-info.json +1 -1
  4. package/dist/catalog.js +3 -3
  5. package/dist/cli.js +8 -2
  6. package/dist/commands.js +60 -5
  7. package/dist/paths.js +1 -1
  8. package/dist/targets.js +3 -0
  9. package/package.json +2 -2
  10. package/plugin/.claude-plugin/plugin.json +10 -0
  11. package/plugin/agents/dot-implementer.md +38 -0
  12. package/plugin/agents/dot-reviewer.md +31 -0
  13. package/plugin/agents/dot-tester.md +33 -0
  14. package/plugin/hooks/check.mjs +92 -0
  15. package/plugin/hooks/hooks.json +24 -0
  16. package/plugin/rules/code-style.md +6 -0
  17. package/plugin/rules/comments.md +17 -0
  18. package/plugin/rules/comments.upstream.json +8 -0
  19. package/{content → plugin}/rules/ponytail.md +1 -1
  20. package/{content → plugin}/rules/ponytail.upstream.json +1 -1
  21. package/plugin/rules/writing.md +35 -0
  22. package/plugin/rules/writing.upstream.json +8 -0
  23. package/{content → plugin}/scaffold/AGENTS.md.tmpl +1 -0
  24. package/plugin/skills/dot-code-review/SKILL.md +71 -0
  25. package/plugin/skills/dot-code-review/UPSTREAM.json +8 -0
  26. package/plugin/skills/dot-code-review/references/maintainability.md +67 -0
  27. package/plugin/skills/dot-comments/SKILL.md +41 -0
  28. package/plugin/skills/dot-comments/UPSTREAM.json +8 -0
  29. package/{content → plugin}/skills/dot-commit/SKILL.md +7 -5
  30. package/plugin/skills/dot-correct/SKILL.md +43 -0
  31. package/plugin/skills/dot-correct/UPSTREAM.json +8 -0
  32. package/plugin/skills/dot-correct/agents/openai.yaml +5 -0
  33. package/plugin/skills/dot-debug/SKILL.md +125 -0
  34. package/plugin/skills/dot-debug/UPSTREAM.json +8 -0
  35. package/plugin/skills/dot-debug/references/loops.md +32 -0
  36. package/{content → plugin}/skills/dot-docs-writing/SKILL.md +15 -23
  37. package/{content → plugin}/skills/dot-docs-writing/references/formatting.md +26 -26
  38. package/{content → plugin}/skills/dot-docs-writing/references/global-and-accessible.md +9 -10
  39. package/{content → plugin}/skills/dot-docs-writing/references/word-list.md +4 -5
  40. package/plugin/skills/dot-flow/SKILL.md +75 -0
  41. package/plugin/skills/dot-flow/agents/openai.yaml +5 -0
  42. package/plugin/skills/dot-flow/references/inline.md +42 -0
  43. package/{content → plugin}/skills/dot-grill-me/SKILL.md +2 -2
  44. package/{content → plugin}/skills/dot-grill-me/UPSTREAM.json +1 -1
  45. package/plugin/skills/dot-grilling/SKILL.md +34 -0
  46. package/{content → plugin}/skills/dot-grilling/UPSTREAM.json +1 -1
  47. package/plugin/skills/dot-grilling/agents/openai.yaml +3 -0
  48. package/plugin/skills/dot-handoff/SKILL.md +20 -0
  49. package/{content → plugin}/skills/dot-handoff/UPSTREAM.json +1 -1
  50. package/plugin/skills/dot-implement/SKILL.md +65 -0
  51. package/plugin/skills/dot-implement/UPSTREAM.json +8 -0
  52. package/{content → plugin}/skills/dot-implement/references/typescript.md +29 -20
  53. package/{content → plugin}/skills/dot-plan/SKILL.md +15 -8
  54. package/plugin/skills/dot-plan/UPSTREAM.json +8 -0
  55. package/plugin/skills/dot-plan/references/entity-schemas.md +66 -0
  56. package/{content → plugin}/skills/dot-roadmap/SKILL.md +19 -12
  57. package/plugin/skills/dot-roadmap/UPSTREAM.json +8 -0
  58. package/plugin/skills/dot-roadmap/references/wide-refactor.md +3 -0
  59. package/plugin/skills/dot-testing/SKILL.md +48 -0
  60. package/plugin/skills/dot-testing/UPSTREAM.json +8 -0
  61. package/plugin/skills/dot-testing/references/http.md +15 -0
  62. package/plugin/skills/dot-testing/references/modes.md +32 -0
  63. package/plugin/skills/dot-testing/references/shared-state.md +3 -0
  64. package/{content → plugin}/skills/dot-testing/references/typescript.md +2 -2
  65. package/plugin/skills/dot-writing-for-agents/SKILL.md +54 -0
  66. package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +8 -0
  67. package/plugin/skills/dot-writing-for-agents/references/pointers.md +27 -0
  68. package/plugin/skills/dot-writing-for-agents/references/skill-mechanics.md +22 -0
  69. package/plugin/skills/dot-writing-for-agents/references/steps.md +8 -0
  70. package/content/rules/comments.md +0 -15
  71. package/content/skills/dot-code-review/SKILL.md +0 -58
  72. package/content/skills/dot-debug/SKILL.md +0 -142
  73. package/content/skills/dot-debug/UPSTREAM.json +0 -8
  74. package/content/skills/dot-grilling/SKILL.md +0 -34
  75. package/content/skills/dot-grilling/agents/openai.yaml +0 -3
  76. package/content/skills/dot-handoff/SKILL.md +0 -20
  77. package/content/skills/dot-implement/SKILL.md +0 -52
  78. package/content/skills/dot-testing/SKILL.md +0 -44
  79. package/content/skills/dot-writing-for-agents/SKILL-MECHANICS.md +0 -22
  80. package/content/skills/dot-writing-for-agents/SKILL.md +0 -85
  81. package/content/skills/dot-writing-for-agents/UPSTREAM.json +0 -8
  82. /package/{content → plugin}/rules/core.md +0 -0
  83. /package/{content → plugin}/scaffold/.claude/settings.json.tmpl +0 -0
  84. /package/{content → plugin}/scaffold/.editorconfig.tmpl +0 -0
  85. /package/{content → plugin}/scaffold/.gitattributes.tmpl +0 -0
  86. /package/{content → plugin}/scaffold/CLAUDE.md.tmpl +0 -0
  87. /package/{content → plugin}/skills/dot-debug/agents/openai.yaml +0 -0
  88. /package/{content → plugin}/skills/dot-debug/scripts/hitl-loop.template.sh +0 -0
  89. /package/{content → plugin}/skills/dot-grill-me/agents/openai.yaml +0 -0
  90. /package/{content → plugin}/skills/dot-handoff/agents/openai.yaml +0 -0
  91. /package/{content → plugin}/skills/dot-writing-for-agents/agents/openai.yaml +0 -0
@@ -0,0 +1,92 @@
1
+ // Hook for Claude Code, Copilot, and Codex. With `snapshot`, it runs when a
2
+ // prompt arrives and records the working tree. Without it, it runs at the end
3
+ // of a turn: when the turn changed the tree, it runs the repository's `check`
4
+ // script and, when that fails, asks the agent to continue with the output.
5
+ // It acts only in repositories that `dotagents check enable` added to the
6
+ // user's config, because the `check` script is the repository's own code.
7
+ import { spawnSync } from "node:child_process";
8
+ import crypto from "node:crypto";
9
+ import fs from "node:fs";
10
+ import os from "node:os";
11
+ import path from "node:path";
12
+
13
+ const MAX_OUTPUT = 4000;
14
+
15
+ const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
16
+ const cwd = input.cwd ?? process.cwd();
17
+ const snapshotFile = path.join(os.tmpdir(), "dotagents-check", `${hash(input.session_id ?? cwd)}.txt`);
18
+
19
+ // Codex needs JSON on stdout when the hook exits 0.
20
+ let decision = {};
21
+ if (checkEnabled()) {
22
+ if (process.argv[2] === "snapshot") saveSnapshot();
23
+ else {
24
+ if (!input.stop_hook_active && turnChangedTree() && hasCheckScript()) decision = runCheck();
25
+ fs.rmSync(snapshotFile, { force: true });
26
+ }
27
+ }
28
+ console.log(JSON.stringify(decision));
29
+
30
+ function checkEnabled() {
31
+ const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
32
+ if (top.status !== 0) return false;
33
+ // Same path as configDir() in the CLI's src/paths.ts.
34
+ const configDir = process.env.XDG_CONFIG_HOME ? path.join(process.env.XDG_CONFIG_HOME, "dotagents") : path.join(os.homedir(), ".config", "dotagents");
35
+ try {
36
+ const { checkRepos = [] } = JSON.parse(fs.readFileSync(path.join(configDir, "config.json"), "utf8"));
37
+ return Array.isArray(checkRepos) && checkRepos.includes(fs.realpathSync(top.stdout.trim()));
38
+ } catch {
39
+ return false;
40
+ }
41
+ }
42
+
43
+ function saveSnapshot() {
44
+ const tree = treeHash();
45
+ if (!tree) return;
46
+ fs.mkdirSync(path.dirname(snapshotFile), { recursive: true });
47
+ fs.writeFileSync(snapshotFile, tree);
48
+ }
49
+
50
+ // Without a snapshot or Git, a change can't be proven, so the check doesn't run:
51
+ // a failing check on untouched code would make the agent edit what nobody asked for.
52
+ function turnChangedTree() {
53
+ const tree = treeHash();
54
+ if (!tree || !fs.existsSync(snapshotFile)) return false;
55
+ return fs.readFileSync(snapshotFile, "utf8") !== tree;
56
+ }
57
+
58
+ /** Hashes the working tree, untracked files included and ignored files excluded, without touching the repository's index. */
59
+ function treeHash() {
60
+ const index = path.join(os.tmpdir(), `dotagents-index-${process.pid}`);
61
+ const env = { ...process.env, GIT_INDEX_FILE: index };
62
+ try {
63
+ // Starting from a copy of the real index reuses its file stat cache, so unchanged files aren't rehashed.
64
+ const realIndex = spawnSync("git", ["rev-parse", "--path-format=absolute", "--git-path", "index"], { cwd, encoding: "utf8" });
65
+ if (realIndex.status === 0 && fs.existsSync(realIndex.stdout.trim())) fs.copyFileSync(realIndex.stdout.trim(), index);
66
+ const add = spawnSync("git", ["add", "--all", "."], { cwd, env, encoding: "utf8" });
67
+ if (add.status !== 0) return undefined;
68
+ const tree = spawnSync("git", ["write-tree"], { cwd, env, encoding: "utf8" });
69
+ return tree.status === 0 ? tree.stdout.trim() : undefined;
70
+ } finally {
71
+ fs.rmSync(index, { force: true });
72
+ }
73
+ }
74
+
75
+ function hasCheckScript() {
76
+ try {
77
+ return Boolean(JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")).scripts?.check);
78
+ } catch {
79
+ return false;
80
+ }
81
+ }
82
+
83
+ function runCheck() {
84
+ const result = spawnSync("npm", ["run", "--silent", "check"], { cwd, encoding: "utf8", shell: process.platform === "win32" });
85
+ if (result.status === 0) return {};
86
+ const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim().slice(-MAX_OUTPUT) || "It printed nothing.";
87
+ return { decision: "block", reason: `\`npm run check\` failed with exit code ${result.status}. Fix the problems your changes caused, then finish:\n${output}` };
88
+ }
89
+
90
+ function hash(text) {
91
+ return crypto.createHash("sha256").update(text).digest("hex").slice(0, 16);
92
+ }
@@ -0,0 +1,24 @@
1
+ {
2
+ "hooks": {
3
+ "UserPromptSubmit": [
4
+ {
5
+ "hooks": [
6
+ {
7
+ "type": "command",
8
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check.mjs\" snapshot"
9
+ }
10
+ ]
11
+ }
12
+ ],
13
+ "Stop": [
14
+ {
15
+ "hooks": [
16
+ {
17
+ "type": "command",
18
+ "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check.mjs\""
19
+ }
20
+ ]
21
+ }
22
+ ]
23
+ }
24
+ }
@@ -0,0 +1,6 @@
1
+ # Code style
2
+
3
+ Apply these rules when you write or refactor code:
4
+
5
+ - Branch with `if` and an early return. Reach for `else`, `else if`, or `switch` only where early returns can't express the logic.
6
+ - Sort keys alphabetically in JSON files, such as translations, unless the order changes behavior.
@@ -0,0 +1,17 @@
1
+ # Code comments
2
+
3
+ Apply these rules when you write, refactor, or review code:
4
+
5
+ - Delete comments by default. Keep only these kinds:
6
+ - Legal and license headers.
7
+ - A gotcha forced by an external dependency, platform, or protocol that you cannot change.
8
+ - Formatter-ignore markers, such as `// prettier-ignore`.
9
+ - Doc comments on a public API, in the language's convention, such as `/** */` in TypeScript.
10
+ - An issue or RFC link for a constraint that the code cannot express.
11
+ - The ponytail `shortcut:` comment.
12
+ - When your own code would surprise a reader, rename, extract, or retype it until it needs no comment.
13
+ - Turn a constraint into a type, a runtime check, a test, or a lint rule where that is cheap, then delete its comment.
14
+ - If you are not sure that an exception applies, delete the comment.
15
+ - Delete code instead of commenting it out. Git keeps the history.
16
+ - When you change code, update or delete every comment that the change makes wrong.
17
+ - To review the comments in a diff, use the `dot-comments` skill.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/cursor/plugins",
3
+ "path": "pstack/agents/comment-sicko.md",
4
+ "commit": "a5539b15a3d56e04992565aafee2b37051329ce3",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Rewrote the agent's exception list as an always-on rule in neutral wording. Added the ponytail shortcut: exception, the rules to reshape surprises and encode constraints, and a pointer to the dot-comments skill. Dropped the suppression and report instructions, which live in dot-comments."
8
+ }
@@ -23,7 +23,7 @@ Take the first option that fully works:
23
23
  - Bug fix: before you edit, grep every caller of the function you touch, then fix the root cause once in the shared code.
24
24
  - Code you move or merge keeps its error handling and validation.
25
25
  - Between options of equal size, take the one that is correct on edge cases.
26
- - Lazy code without its check is unfinished: new non-trivial logic (a branch, a loop, a parser, money or security, or a whole new script or app) leaves one small test or an assert-based self-check. Trivial changes need none.
26
+ - Lazy code without its check is unfinished: new non-trivial logic (a branch, a loop, a parser, money or security, or a whole new script or app) leaves one small test or an assert-based self-check. When a separate test step follows, that step can write the test. Trivial changes need none.
27
27
  - A shortcut with a known limit gets a code comment in this form: `shortcut: <the limit>, <when to upgrade>`.
28
28
 
29
29
  Never cut: validation at trust boundaries, error handling that prevents data loss, security, accessibility, the calibration real hardware needs, anything the user asked for.
@@ -4,5 +4,5 @@
4
4
  "commit": "2961b52fc1fe6a5a87c7a959a79512e5c2f3ffe5",
5
5
  "license": "MIT",
6
6
  "modified": true,
7
- "notes": "Removed the comment bullet (rules/comments.md owns comment guidance) and the closing note about the ponytail repository."
7
+ "notes": "Removed the comment bullet (rules/comments.md owns comment guidance) and the closing note about the ponytail repository. Let a separate test step write the test that the check bullet asks for."
8
8
  }
@@ -0,0 +1,35 @@
1
+ # Writing
2
+
3
+ Apply these rules to all text that you write for a person to read: chat replies, CLI output, plans, roadmaps, handoffs, review reports, commit messages, pull requests, and docs. The rules are based on ASD-STE100 (Simplified Technical English), and they take precedence over other style guides.
4
+
5
+ ## Sentences
6
+
7
+ - Write procedure sentences of 20 words or fewer, and descriptive sentences of 25 words or fewer.
8
+ - Write one instruction in each sentence. Use the imperative for steps.
9
+ - Use the active voice, and name the actor.
10
+ - Use the simple present, past, and future tenses. Do not use verbs in the -ing form.
11
+ - Keep noun clusters to 3 words or fewer. Keep the articles "a", "an", and "the".
12
+ - Use one word for one meaning, and use the same word each time.
13
+ - Use "must" for a requirement, and "can" for an ability or a possibility.
14
+ - Write paragraphs of 6 sentences or fewer.
15
+ - Start a warning with a command, such as "Stop the server before you delete the file."
16
+ - Write the full words, not contractions: "do not", not "don't".
17
+
18
+ ## Words
19
+
20
+ - Use plain words. Write "use", not "leverage" or "utilize". Do not write "delve", "pivotal", "crucial", "underscore", or "showcase".
21
+ - Write "is" or "has", not "serves as", "stands as", or "boasts".
22
+ - State the point directly, not as "not just X, but Y".
23
+ - Use the real number of items, not a forced group of three.
24
+ - Name the mechanism or the number, such as "a column rename fails the build", not the feeling.
25
+ - Use the concrete word, not a metaphor noun such as "surface", "north star", or "substrate".
26
+ - Remove filler, such as "in order to" and "it is important to note". Use one hedge at most.
27
+ - Write whole sentences with their articles and verbs. Write words instead of arrows and abbreviations.
28
+
29
+ ## Format
30
+
31
+ - Use periods and commas, not em dashes.
32
+ - Use a colon only before a list or an example.
33
+ - Use bold only for a UI label or a label that a template asks for. Do not use emoji.
34
+ - Use sentence case for headings.
35
+ - Answer directly. Do not write chatbot phrases, such as "I hope this helps", or flattery.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/cursor/plugins",
3
+ "path": "pstack/skills/unslop/SKILL.md",
4
+ "commit": "a5539b15a3d56e04992565aafee2b37051329ce3",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Condensed the unslop patterns into the Words and Format sections and rewrote them as rules. The Sentences section is original, based on ASD-STE100, and is not from unslop."
8
+ }
@@ -24,6 +24,7 @@ Commands and versions live in their source of truth, such as `package.json` scri
24
24
 
25
25
  ## Code and tests
26
26
 
27
+ - Keep a `check` script, such as in `package.json`, that runs the type checker and the linter but not the tests. After `dotagents check enable`, agent hooks run it at the end of each turn that changes files.
27
28
  - Prefer the standard library and the dependencies the project already has. Ask before you add a dependency, and commit the lockfile with it.
28
29
  - Validate input at trust boundaries: requests, command-line arguments, files, and environment variables.
29
30
  - Change generated files through their generator, then regenerate them.
@@ -0,0 +1,71 @@
1
+ ---
2
+ name: dot-code-review
3
+ description: Review a diff for correctness bugs and maintainability problems. Use when the user asks to review code, a commit, a branch, or a pull request, or before you commit a non-trivial change.
4
+ ---
5
+
6
+ # Code review
7
+
8
+ Review the change in two passes, and give one report. The correctness pass finds the defects that make the change behave wrongly in production. The maintainability pass finds the structure that makes the next change harder.
9
+
10
+ ## Repository conventions first
11
+
12
+ Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. Review against those standards. Code that follows a repository convention is not a finding, even when general practice differs. Code that breaks one is a finding.
13
+
14
+ ## 1. Pick the target
15
+
16
+ Use the target the user named. Otherwise pick the first one that applies:
17
+
18
+ 1. A pull request number or URL: `gh pr diff <number>`.
19
+ 2. Staged and unstaged changes: `git diff HEAD`.
20
+ 3. The current branch against its base: `git diff $(git merge-base HEAD origin/main)`. Use the repository's default branch name.
21
+
22
+ State the target in one line before you start.
23
+
24
+ ## 2. Read for context
25
+
26
+ For each changed hunk, read the whole function, its callers, and the tests that cover it. Read the description of the pull request, the linked issue, or the roadmap task if there is one, so you can check the change against its intent and its scope.
27
+
28
+ ## 3. Pass 1: correctness
29
+
30
+ Each correctness finding is a **failure scenario**: concrete inputs or state that lead to a wrong result, a crash, or data loss. Use a neutral tone in this pass.
31
+
32
+ Check every hunk against each of these classes:
33
+
34
+ - Logic: inverted conditions, off-by-one errors, wrong operator, wrong variable, unreachable branches.
35
+ - Edge cases: empty, null, zero, negative, very large, Unicode, duplicate, and concurrent inputs.
36
+ - Errors: swallowed exceptions, no cleanup, partial writes, retries that are not idempotent.
37
+ - Contracts: changed signatures, return shapes, defaults, or API responses that current callers depend on.
38
+ - Data: migrations that lose or lock data, no transaction, inconsistent writes.
39
+ - Security: injection, no authorization check, secrets in code or logs, unsafe deserialization, path traversal.
40
+ - Concurrency: races, deadlocks, shared mutable state, assumptions about order.
41
+ - Tests: changed behavior without a test that fails when the change is wrong.
42
+
43
+ Prove each candidate: trace the code path with the input that fails, or write and run a test that fails. Drop a candidate that has no concrete scenario, or report it as a question. In this pass, report style problems only when they hide a bug or break a documented convention.
44
+
45
+ ## 4. Pass 2: maintainability
46
+
47
+ Read [`references/maintainability.md`](references/maintainability.md), and apply every rule in it to the diff.
48
+
49
+ Done when you checked the diff against each rule in the reference.
50
+
51
+ ## 5. Report
52
+
53
+ Give one report for both passes, from most to least severe. Give a correctness finding its **Scenario**, and a maintainability finding its **Cost**:
54
+
55
+ ```markdown
56
+ ### <high | medium | low> <one-line summary>
57
+ `path/to/file.ts:42` (<correctness | maintainability>)
58
+ **Scenario:** <inputs or state>, then <wrong result>
59
+ **Cost:** <what a reader or the next change pays>
60
+ **Fix:** <smallest change that removes the problem>
61
+ ```
62
+
63
+ End the report with this section. Write one line for each class of finding in the report. Prefer a tool that the repository already runs:
64
+
65
+ ```markdown
66
+ ## Make it impossible
67
+
68
+ - <finding class>: <the type, lint rule, or check that prevents it, or "none">
69
+ ```
70
+
71
+ If you find nothing, say that the review found no defects, and list what you checked. Change code only when the user asks for fixes.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/cursor/plugins",
3
+ "path": "cursor-team-kit/skills/thermo-nuclear-code-quality-review/SKILL.md",
4
+ "commit": "a5539b15a3d56e04992565aafee2b37051329ce3",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Adapted into references/maintainability.md as the maintainability pass: kept code judo, the 1,000-line blocker, the smells, the presumed blockers, and the direct tone, rewrote the text under plugin/rules/writing.md, and gave each rule a severity. The Reader load, Domain model, and Scope sections condense pstack/skills/principle-minimize-reader-load, pstack/skills/principle-model-the-domain, and pstack/skills/principle-subtract-before-you-add at the same commit. SKILL.md and the correctness pass are original and are not from cursor/plugins."
8
+ }
@@ -0,0 +1,67 @@
1
+ # Maintainability pass
2
+
3
+ Judge the structure of the change, not only its behavior. Do not approve code because it works. Code that works and makes the codebase messier is a finding.
4
+
5
+ Be direct and strict. Do not soften a structural problem into a mild suggestion. If the change makes the code messier, say so. If it missed a much simpler design, say that too. Give a few findings that you are sure of, not a long list of cosmetic notes.
6
+
7
+ ## Code judo
8
+
9
+ First, look for a restructure that keeps the behavior and deletes whole branches, modes, helpers, or layers. Assume that one often exists: a new arrangement that uses the current architecture better and makes the change much smaller. A refactor that moves complexity around and deletes none of it is not enough. When you see a path to delete complexity, push for it.
10
+
11
+ ## Presumed blockers
12
+
13
+ Report each of these as `high`, unless the author gives a clear reason:
14
+
15
+ - The diff keeps a lot of incidental complexity, and a code judo move would delete it.
16
+ - The diff pushes a file from under 1,000 lines to over 1,000 lines. Ask to split the file first.
17
+ - The diff adds ad hoc branches to a flow, or scatters feature checks across shared code.
18
+ - The diff adds an abstraction, a wrapper, or a cast that makes the design more indirect.
19
+ - The diff duplicates a helper that the codebase already has, or puts logic in the wrong layer.
20
+
21
+ ## Smells
22
+
23
+ Report each of these as `medium`:
24
+
25
+ - Spaghetti growth: new conditionals, special cases, or one-off branches in unrelated flows. One-off booleans, nullable modes, and "temporary" branches that will stay.
26
+ - Thin wrappers and pass-through helpers: a wrapper with one caller, an adapter with no second implementation, a layer that repeats the methods and arguments of the layer below it. Inline them.
27
+ - Casts, `any`, `unknown`, and extra optional parameters that hide the real contract. Ask for an explicit type at the boundary.
28
+ - Silent fallbacks that hide an unclear invariant. Make the boundary explicit, so the invalid state fails.
29
+ - Layer leaks: feature logic in a shared module, or implementation details that leak through an API. Move the logic to the module that owns the concept.
30
+ - Duplicated helpers: copied logic, or a new helper next to a canonical one that does the same job.
31
+ - Needless sequential work: independent steps that run one after the other for no reason.
32
+ - Half-applied state: related updates that can stop part of the way through. Ask for an atomic structure.
33
+
34
+ ## Reader load
35
+
36
+ Count two costs for the reader: the layers to trace from the question to the answer, and the state to hold in mind. A new reader must answer "where does X come from?" and "what can change X?" in 30 seconds. If not, cut layers or cut state.
37
+
38
+ - A layer must hide a real decision. Collapse a layer that costs more than it saves.
39
+ - Shrink the scope of state: return values over mutation, locals over fields, fields over module state, module state over globals. Derive a value instead of two copies that you keep in sync.
40
+ - State an invariant once, at the boundary, not in each consumer.
41
+
42
+ ## Domain model
43
+
44
+ Flag these signs that the change skipped the domain model: an if/else chain that grows by one branch, a second boolean that must stay in sync with the first, a shape assumption repeated across files, or modules named after steps (load, validate, save) that repeat the same domain rules. Propose the structure that fits: a state machine, a typed model, a lookup table, a discriminated union, or a reducer. Do not force an abstraction when the current shape is clear, local, and unlikely to grow.
45
+
46
+ ## Scope
47
+
48
+ Check the diff against the request or the task. The smallest complete change wins:
49
+
50
+ - Flag features, options, configuration, and "for later" code that nobody asked for.
51
+ - Flag guards, validators, and parsers that the spec does not require. Validation at a trust boundary is required.
52
+ - Flag code that the codebase, the standard library, or an installed dependency already provides.
53
+ - Flag a new dependency that replaces a few lines of code.
54
+ - Flag a part of the task that the diff left out, such as a caller, a test, or a fixture that the change breaks.
55
+
56
+ ## Comments
57
+
58
+ Run step 1 of the `dot-comments` skill on the diff. Report each Delete, Reshape, and Encode flag as a `low` finding, with the change that the flag proposes. Do not apply the flags.
59
+
60
+ ## Example phrases
61
+
62
+ - "This pushes the file past 1,000 lines. Split it first."
63
+ - "This adds one more special case to a busy flow. Move it behind its own abstraction."
64
+ - "This works, but it tangles the code around it. Keep the behavior and restructure the code."
65
+ - "This wrapper adds a layer and hides nothing. Call the function directly."
66
+ - "Why does this need a cast? Make the boundary explicit."
67
+ - "This refactor moves the complexity and deletes none of it. A code judo move removes these branches."
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: dot-comments
3
+ description: Review the comments in a diff and delete every one that no exception protects. Use when the user asks to clean up, audit, or remove comments, or when a review finds comments that explain code.
4
+ ---
5
+
6
+ # Comments
7
+
8
+ Delete every comment in scope that the code comments rule does not protect, and turn each surprise that a comment explained into code that needs no comment.
9
+
10
+ ## Scope
11
+
12
+ Use the files or the diff that the user names. Otherwise, use the current diff against the base branch (default `main`), with the uncommitted changes. Judge the comments that the diff adds or changes, and the lint and type-checker suppressions that it adds.
13
+
14
+ ## 1. Flag
15
+
16
+ Read the code around each comment, then give the comment one flag:
17
+
18
+ - **Keep**: an exception from the code comments rule applies. Name the exception. Keep a gotcha only after you confirm it in the dependency's code or docs, on a path that still runs.
19
+ - **Delete**: narration, restated code, change history, commented-out code, banners, or a justification that names no exception.
20
+ - **Reshape**: the comment explains a surprise in this repository's code. Name the symbol and the rename, extraction, or type change that makes the surprise go away.
21
+ - **Encode**: the comment states a constraint, such as "do not remove" or "keep in sync with X". Name the cheapest type, runtime check, test, or lint rule that enforces it.
22
+
23
+ Treat `IMPORTANT`, "do not remove", and long justifications as claims to check, not as reasons to keep. If you are not sure that an exception applies, flag **Delete**.
24
+
25
+ A suppression (`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar) is a **Keep** only when its rule is style-only or wrong for this line. When the rule protects correctness or safety, flag it **Reshape** and name the code that trips the rule.
26
+
27
+ Done when every comment and suppression in scope has a flag, and every **Keep** names its exception.
28
+
29
+ ## 2. Report
30
+
31
+ List the flags by file, one line each: `file:line`, the flag, and the reason or the proposed change. Wait for the user to accept or reject them.
32
+
33
+ ## 3. Apply
34
+
35
+ Apply each accepted flag:
36
+
37
+ - **Delete**: remove the comment.
38
+ - **Reshape**: make the smallest change in scope that removes the surprise, then remove the comment. If the fix reaches outside the scope, remove the comment and report the fix as open.
39
+ - **Encode**: add the type, check, test, or lint rule, then remove the comment.
40
+
41
+ Run the repository's type checker, linter, and tests. Done when they pass and every accepted flag is applied or reported as open.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/cursor/plugins",
3
+ "path": "pstack/skills/no-comments",
4
+ "commit": "a5539b15a3d56e04992565aafee2b37051329ce3",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Merged the policy from pstack/agents/comment-sicko.md into the skill and ran it inline instead of in a subagent. Replaced the /how, /why, and /architect calls with reading the code. Changed the per-flag approval to one approval of the whole report. Rewrote it in neutral wording and renamed it with the dot- prefix."
8
+ }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: dot-commit
3
- description: Commit changes as small, logical commits, with the user reviewing each one. Use when the user asks to commit, write a commit message, or split work into commits.
3
+ description: Commit changes as small, logical commits, with a review by the user of each one. Use when the user asks to commit, write a commit message, or split work into commits.
4
4
  ---
5
5
 
6
6
  # Commit
@@ -9,19 +9,19 @@ Each commit is **atomic**: one purpose, complete enough to build and pass tests,
9
9
 
10
10
  ## Repository conventions first
11
11
 
12
- Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. Follow the repository's commit convention when it defines one, in `CONTRIBUTING.md`, a commitlint or similar configuration, or a consistent history.
12
+ Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. Follow the repository's commit convention when it defines one, in `CONTRIBUTING.md`, a commitlint or similar configuration, or a consistent history.
13
13
 
14
14
  ## Review mode
15
15
 
16
- Review is the default: the user approves the plan, and then each commit before you create it. When the user asks you to commit without review, for example "commit without asking", skip both approval stops for that request, and still show the summary in step 4.
16
+ Review is the default: the user approves the plan, and then each commit before you create it. When the user asks you to commit without review, for example "commit, do not ask", skip both approval stops for that request, and still show the summary in step 4.
17
17
 
18
18
  ## 1. Inspect
19
19
 
20
- Run `git status` and `git diff HEAD` to see every change, including untracked files. Note any changes that the user already staged, and ask whether they belong together. Run `git log -n 15 --oneline` to learn the convention and scopes that the repository uses.
20
+ Run `git status` and `git diff HEAD` to see every change. Include the untracked files. Note any changes that the user already staged, and ask whether they belong together. Run `git log -n 15 --oneline` to learn the convention and scopes that the repository uses.
21
21
 
22
22
  ## 2. Propose the plan
23
23
 
24
- Group the changes into commits by purpose: a refactor, a behavior change, a dependency update, and a formatting pass are separate commits. Keep a test in the same commit as the behavior it covers. Order the commits so that each one builds on the previous ones.
24
+ Group the changes into commits by purpose: a refactor, a behavior change, a dependency update, and a format pass are separate commits. Keep a test in the same commit as the behavior it covers. Order the commits so that each one builds on the previous ones.
25
25
 
26
26
  Check each file for secrets, credentials, local configuration, build output, and large binaries. Leave those out of the plan and tell the user.
27
27
 
@@ -56,6 +56,8 @@ Let pre-commit hooks run. When a hook fails, fix the cause, stage the fix, and s
56
56
 
57
57
  Show `git log --oneline` for the commits you created, and list the changes that remain uncommitted. Push only when the user asks.
58
58
 
59
+ When the commits finish a task from a `dot-roadmap` roadmap, tick the checkbox of that task in the roadmap's `README.md`, and tell the user.
60
+
59
61
  Done when every group in the plan is committed or skipped, and the user has seen the summary.
60
62
 
61
63
  ## Message format
@@ -0,0 +1,43 @@
1
+ ---
2
+ name: dot-correct
3
+ description: Turn a mistake that agents repeat into architecture, a type, a lint rule, or a test that prevents it.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # Correct
8
+
9
+ Change the repository so that the next agent cannot make the same mistake again. Assume every contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. A change that looks right from one file must be right for the whole repository.
10
+
11
+ ## Repository conventions first
12
+
13
+ Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. Use the type checker, linter, and test framework that the repository already has.
14
+
15
+ ## 1. Name the mistake class
16
+
17
+ Use the mistake that the user names. Otherwise, read the recent commits, reverts, review comments, agent instruction files, and comments that explain workarounds, and group the mistakes into classes. A class counts when it occurred two times.
18
+
19
+ Done when each class has two examples as evidence: commits, lines, or corrections from the user.
20
+
21
+ ## 2. Pick the highest level
22
+
23
+ Try each level in this order, and take the first one that prevents the class:
24
+
25
+ 1. Architecture: make the mistake impossible. Give each piece of state one owner and each task one supported way. Hide internals so that the wrong import fails. Replace lists that people keep in sync by hand with one source of truth. Delete the old ways and the dead code that an agent would copy.
26
+ 2. Types: make the bad state impossible to write.
27
+ 3. Lint rule or CI check: when the bad code still compiles, add a check whose error names the file, type, or function to use instead. If the pattern is already common, fail only when a change adds more of it.
28
+ 4. Test: test the behavior. Fix or delete a test that passes when its behavior breaks, or that fails when only the internals change.
29
+ 5. Docs or agent rules: use this level only for a judgment call that no check can enforce. Nothing fails when an agent skips a doc, so add an example of the mistake.
30
+
31
+ When a structural fix works, use only the structural fix. Do not also add an instruction.
32
+
33
+ Ask the user before you add a dependency or change the lint configuration.
34
+
35
+ ## 3. Fix and prove
36
+
37
+ Fix one class at a time, in the repository where the mistake occurred. Prove that each new check fails on a real past mistake: apply the mistake, run the check, show the error, then remove the mistake. Run the same command that CI runs. Put each exception on the line that needs it, with a reason and the user's approval.
38
+
39
+ Run the repository's type checker, linter, and tests. Done when each new check failed on a past mistake and all checks pass.
40
+
41
+ ## 4. Report
42
+
43
+ For each class, report the evidence, the level that you picked, why a higher level did not work, and the output that proves the check. Suggest the `dot-commit` skill, with one commit for each class.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/cursor/plugins",
3
+ "path": "pstack/skills/correct/SKILL.md",
4
+ "commit": "a5539b15a3d56e04992565aafee2b37051329ce3",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Rewrote the text under plugin/rules/writing.md and renamed it with the dot- prefix. Split the levels into architecture, types, a lint rule or check, a test, and docs, and added the approval before a new dependency or a lint configuration change. Left out the rule table in the agent instruction file and the expiry date on exceptions. Merged pstack/skills/principle-encode-lessons-in-structure at the same commit: use only the structural fix when one works, and add an example of the mistake to a docs rule. The commit goes through dot-commit."
8
+ }
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: "Correct"
3
+ short_description: "Turn a repeated agent mistake into a check"
4
+ policy:
5
+ allow_implicit_invocation: false