@igorlau/dotagents 1.0.21 → 2.0.0

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 (108) hide show
  1. package/README.md +65 -65
  2. package/THIRD_PARTY_NOTICES.md +101 -6
  3. package/dist/build-info.json +1 -1
  4. package/dist/catalog.js +3 -3
  5. package/dist/cli.js +1 -1
  6. package/dist/commands.js +9 -8
  7. package/dist/manifest.js +8 -1
  8. package/dist/paths.js +0 -4
  9. package/dist/targets.js +3 -9
  10. package/dist/wizard.js +1 -1
  11. package/package.json +5 -3
  12. package/{plugin/rules → rules}/comments.upstream.json +1 -1
  13. package/{plugin/rules → rules}/ponytail.md +1 -1
  14. package/{plugin/rules → rules}/ponytail.upstream.json +1 -1
  15. package/{plugin/rules → rules}/writing.md +1 -2
  16. package/{plugin/rules → rules}/writing.upstream.json +1 -1
  17. package/{plugin/scaffold → scaffold}/AGENTS.md.tmpl +1 -1
  18. package/{plugin/skills → skills}/dot-code-review/SKILL.md +2 -0
  19. package/{plugin/skills → skills}/dot-code-review/UPSTREAM.json +1 -1
  20. package/skills/dot-code-review/references/finding-classes.md +33 -0
  21. package/{plugin/skills → skills}/dot-comments/UPSTREAM.json +1 -1
  22. package/{plugin/skills → skills}/dot-commit/SKILL.md +0 -2
  23. package/skills/dot-correct/UPSTREAM.json +8 -0
  24. package/{plugin/skills → skills}/dot-debug/UPSTREAM.json +1 -1
  25. package/{plugin/skills → skills}/dot-grilling/UPSTREAM.json +2 -2
  26. package/{plugin/skills → skills}/dot-handoff/UPSTREAM.json +1 -1
  27. package/{plugin/skills → skills}/dot-implement/SKILL.md +2 -2
  28. package/{plugin/skills → skills}/dot-plan/SKILL.md +3 -1
  29. package/{plugin/skills → skills}/dot-roadmap/SKILL.md +7 -4
  30. package/skills/dot-security-audit/SKILL.md +87 -0
  31. package/skills/dot-security-audit/UPSTREAM.json +8 -0
  32. package/skills/dot-security-audit/references/AI-AND-LLM.md +83 -0
  33. package/skills/dot-security-audit/references/ATTACK-CLASSES.md +130 -0
  34. package/skills/dot-security-audit/references/CLIENT-SIDE.md +83 -0
  35. package/skills/dot-security-audit/references/CLOUD-AND-DEPLOYMENT.md +86 -0
  36. package/skills/dot-security-audit/references/DATA-ISOLATION-AND-LIFECYCLE.md +84 -0
  37. package/skills/dot-security-audit/references/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -0
  38. package/skills/dot-security-audit/references/MEMORY-SAFETY-AND-BINARY.md +101 -0
  39. package/skills/dot-security-audit/references/PROTOCOLS-RPC-AND-MESSAGING.md +81 -0
  40. package/skills/dot-security-audit/references/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -0
  41. package/skills/dot-security-audit/references/SUPPLY-CHAIN-AND-RELEASE.md +73 -0
  42. package/skills/dot-security-audit/references/WEB-PROTOCOL-AND-AUTH.md +105 -0
  43. package/skills/dot-security-changes/SKILL.md +68 -0
  44. package/{plugin/skills → skills}/dot-testing/UPSTREAM.json +1 -1
  45. package/skills/dot-ui-review/SKILL.md +79 -0
  46. package/skills/dot-ui-review/UPSTREAM.json +8 -0
  47. package/skills/dot-ux-review/SKILL.md +50 -0
  48. package/skills/dot-ux-review/UPSTREAM.json +8 -0
  49. package/skills/dot-ux-review/references/web-interface-guidelines.md +191 -0
  50. package/{plugin/skills/dot-stack-review → skills/dot-walkthrough-branch}/SKILL.md +9 -30
  51. package/skills/dot-walkthrough-branch/references/layers.md +38 -0
  52. package/{plugin/skills/dot-stack-review → skills/dot-walkthrough-branch}/scripts/page.mjs +39 -10
  53. package/skills/dot-walkthrough-changes/SKILL.md +62 -0
  54. package/skills/dot-writing-for-agents/UPSTREAM.json +8 -0
  55. package/plugin/.claude-plugin/plugin.json +0 -10
  56. package/plugin/agents/dot-implementer.md +0 -27
  57. package/plugin/agents/dot-reviewer.md +0 -44
  58. package/plugin/agents/dot-tester.md +0 -25
  59. package/plugin/hooks/check.mjs +0 -118
  60. package/plugin/hooks/hooks.json +0 -54
  61. package/plugin/hooks/rules.mjs +0 -27
  62. package/plugin/skills/dot-correct/UPSTREAM.json +0 -8
  63. package/plugin/skills/dot-correct/agents/openai.yaml +0 -5
  64. package/plugin/skills/dot-debug/agents/openai.yaml +0 -3
  65. package/plugin/skills/dot-flow/SKILL.md +0 -105
  66. package/plugin/skills/dot-flow/agents/openai.yaml +0 -5
  67. package/plugin/skills/dot-flow/references/fix-round.md +0 -64
  68. package/plugin/skills/dot-flow/references/inline.md +0 -9
  69. package/plugin/skills/dot-grilling/agents/openai.yaml +0 -3
  70. package/plugin/skills/dot-handoff/agents/openai.yaml +0 -5
  71. package/plugin/skills/dot-roadmap/agents/openai.yaml +0 -5
  72. package/plugin/skills/dot-stack-review/agents/openai.yaml +0 -5
  73. package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +0 -8
  74. package/plugin/skills/dot-writing-for-agents/agents/openai.yaml +0 -3
  75. /package/{plugin/rules → rules}/code-style.md +0 -0
  76. /package/{plugin/rules → rules}/comments.md +0 -0
  77. /package/{plugin/rules → rules}/core.md +0 -0
  78. /package/{plugin/scaffold → scaffold}/.claude/settings.json.tmpl +0 -0
  79. /package/{plugin/scaffold → scaffold}/.editorconfig.tmpl +0 -0
  80. /package/{plugin/scaffold → scaffold}/.gitattributes.tmpl +0 -0
  81. /package/{plugin/scaffold → scaffold}/CLAUDE.md.tmpl +0 -0
  82. /package/{plugin/skills → skills}/dot-code-review/references/maintainability.md +0 -0
  83. /package/{plugin/skills → skills}/dot-comments/SKILL.md +0 -0
  84. /package/{plugin/skills → skills}/dot-correct/SKILL.md +0 -0
  85. /package/{plugin/skills → skills}/dot-debug/SKILL.md +0 -0
  86. /package/{plugin/skills → skills}/dot-debug/references/loops.md +0 -0
  87. /package/{plugin/skills → skills}/dot-debug/scripts/hitl-loop.template.sh +0 -0
  88. /package/{plugin/skills → skills}/dot-docs-writing/SKILL.md +0 -0
  89. /package/{plugin/skills → skills}/dot-docs-writing/references/formatting.md +0 -0
  90. /package/{plugin/skills → skills}/dot-docs-writing/references/global-and-accessible.md +0 -0
  91. /package/{plugin/skills → skills}/dot-docs-writing/references/word-list.md +0 -0
  92. /package/{plugin/skills → skills}/dot-grilling/SKILL.md +0 -0
  93. /package/{plugin/skills → skills}/dot-handoff/SKILL.md +0 -0
  94. /package/{plugin/skills → skills}/dot-implement/UPSTREAM.json +0 -0
  95. /package/{plugin/skills → skills}/dot-implement/references/typescript.md +0 -0
  96. /package/{plugin/skills → skills}/dot-plan/UPSTREAM.json +0 -0
  97. /package/{plugin/skills → skills}/dot-plan/references/entity-schemas.md +0 -0
  98. /package/{plugin/skills → skills}/dot-roadmap/UPSTREAM.json +0 -0
  99. /package/{plugin/skills → skills}/dot-roadmap/references/wide-refactor.md +0 -0
  100. /package/{plugin/skills → skills}/dot-testing/SKILL.md +0 -0
  101. /package/{plugin/skills → skills}/dot-testing/references/after-implement.md +0 -0
  102. /package/{plugin/skills → skills}/dot-testing/references/http.md +0 -0
  103. /package/{plugin/skills → skills}/dot-testing/references/shared-state.md +0 -0
  104. /package/{plugin/skills → skills}/dot-testing/references/typescript.md +0 -0
  105. /package/{plugin/skills → skills}/dot-writing-for-agents/SKILL.md +0 -0
  106. /package/{plugin/skills → skills}/dot-writing-for-agents/references/pointers.md +0 -0
  107. /package/{plugin/skills → skills}/dot-writing-for-agents/references/skill-mechanics.md +0 -0
  108. /package/{plugin/skills → skills}/dot-writing-for-agents/references/steps.md +0 -0
@@ -1,7 +1,10 @@
1
1
  // Usage: node page.mjs <layers.json>, from inside the repository. Writes
2
- // .tmp/stack-review/<branch-slug>.html at the repository root, and prints its path.
2
+ // .tmp/walkthrough/<slug>.html at the repository root, and prints its path.
3
+ // The layers file names the target with "base" and "head" (a branch), with "oldTree" and
4
+ // "newTree" (a tree range), or with none of them (the working tree against HEAD).
3
5
  import { spawnSync } from "node:child_process";
4
6
  import fs from "node:fs";
7
+ import os from "node:os";
5
8
  import path from "node:path";
6
9
 
7
10
  const SEVERITIES = ["high", "medium", "low"];
@@ -14,18 +17,19 @@ const stack = readStack(layersFile);
14
17
  validate(stack);
15
18
 
16
19
  const root = git(["rev-parse", "--show-toplevel"]);
17
- const mergeBase = git(["merge-base", stack.base, stack.head]);
20
+ const target = resolveTarget();
18
21
  // shortcut: a file that is split between 2 layers shows its full diff in both layers, split the diff by hunk when readers need only the hunks of each layer.
19
22
  const diffs = new Map();
20
23
  stack.layers.forEach((layer, i) => {
21
24
  layer.files.forEach((file, j) => {
22
- if (!diffs.has(file)) diffs.set(file, git(["--literal-pathspecs", "diff", "--no-color", "--no-ext-diff", mergeBase, stack.head, "--", file], root));
23
- if (!diffs.get(file)) invalid(`layers[${i}].files[${j}]`, "has no changes between the merge base and head");
25
+ if (!diffs.has(file)) diffs.set(file, git(["--literal-pathspecs", "diff", "--no-color", "--no-ext-diff", target.from, target.to, "--", file], root));
26
+ if (!diffs.get(file)) invalid(`layers[${i}].files[${j}]`, "has no changes in the target");
24
27
  });
25
28
  });
26
29
 
27
- const page = path.join(root, ".tmp", "stack-review", `${stack.head.replace(/[^\w.-]/g, "-")}.html`);
30
+ const page = path.join(root, ".tmp", "walkthrough", `${target.slug.replace(/[^\w.-]/g, "-")}.html`);
28
31
  fs.mkdirSync(path.dirname(page), { recursive: true });
32
+ fs.rmSync(page, { force: true });
29
33
  fs.writeFileSync(page, renderPage());
30
34
  console.log(page);
31
35
 
@@ -56,8 +60,14 @@ function isText(value) {
56
60
  function validate(stack) {
57
61
  if (!isObject(stack)) invalid("the root", "must be an object");
58
62
  for (const key of ["base", "head"]) {
59
- if (typeof stack[key] !== "string" || !/^[^-\s]\S*$/.test(stack[key])) invalid(key, "must be a branch or commit name without spaces that does not start with -");
63
+ if (key in stack && (typeof stack[key] !== "string" || !/^[^-\s]\S*$/.test(stack[key]))) invalid(key, "must be a branch or commit name without spaces that does not start with -");
60
64
  }
65
+ if ("base" in stack !== "head" in stack) invalid("base and head", "must both be present or both be absent");
66
+ for (const key of ["oldTree", "newTree"]) {
67
+ if (key in stack && (typeof stack[key] !== "string" || !/^[0-9a-f]{4,64}$/.test(stack[key]))) invalid(key, "must be a tree id in lowercase hexadecimal");
68
+ }
69
+ if ("oldTree" in stack !== "newTree" in stack) invalid("oldTree and newTree", "must both be present or both be absent");
70
+ if ("base" in stack && "oldTree" in stack) invalid("base", "cannot go with oldTree: name a branch or a tree range, not both");
61
71
  if (!Array.isArray(stack.layers) || stack.layers.length === 0) invalid("layers", "must be a non-empty array");
62
72
  stack.layers.forEach((layer, index) => {
63
73
  const at = `layers[${index}]`;
@@ -84,8 +94,27 @@ function validate(stack) {
84
94
  });
85
95
  }
86
96
 
87
- function git(args, cwd) {
88
- const result = spawnSync("git", args, { cwd, encoding: "utf8", maxBuffer: MAX_DIFF });
97
+ function resolveTarget() {
98
+ if ("head" in stack) {
99
+ const mergeBase = git(["merge-base", stack.base, stack.head]);
100
+ return { from: mergeBase, slug: stack.head, subtitle: `Merge base <code>${mergeBase.slice(0, 7)}</code>`, title: `${stack.head} vs ${stack.base}`, to: stack.head };
101
+ }
102
+ if ("oldTree" in stack) {
103
+ const [from, to] = [stack.oldTree, stack.newTree].map((id) => git(["rev-parse", "--verify", "--end-of-options", `${id}^{tree}`], root));
104
+ const range = `${from.slice(0, 12)}..${to.slice(0, 12)}`;
105
+ return { from, slug: `tree-${range}`, subtitle: "Tree range", title: range, to };
106
+ }
107
+ const indexDir = fs.mkdtempSync(path.join(os.tmpdir(), "walkthrough-"));
108
+ process.once("exit", () => fs.rmSync(indexDir, { recursive: true, force: true }));
109
+ const env = { ...process.env, GIT_INDEX_FILE: path.join(indexDir, "index") };
110
+ git(["read-tree", "HEAD"], root, env);
111
+ // shortcut: git add writes every changed and untracked file as a loose object into the real object database, point GIT_OBJECT_DIRECTORY at a temporary directory with the real one as an alternate when that growth matters.
112
+ git(["add", "--all", "--", "."], root, env);
113
+ return { from: "HEAD", slug: "working-tree", subtitle: "Working tree against <code>HEAD</code>", title: "working tree", to: git(["write-tree"], root, env) };
114
+ }
115
+
116
+ function git(args, cwd, env = process.env) {
117
+ const result = spawnSync("git", args, { cwd, env, encoding: "utf8", maxBuffer: MAX_DIFF });
89
118
  if (result.status !== 0) fail(`git ${args.join(" ")} failed: ${(result.stderr || result.error?.message || "").trim()}`);
90
119
  return result.stdout.trimEnd();
91
120
  }
@@ -209,7 +238,7 @@ function renderOverviewRow(layer, index) {
209
238
  }
210
239
 
211
240
  function renderPage() {
212
- const title = `${stack.head} vs ${stack.base}`;
241
+ const { subtitle, title } = target;
213
242
  return `<!doctype html>
214
243
  <html lang="en">
215
244
  <head>
@@ -336,7 +365,7 @@ table.diff tr:target td { background: color-mix(in srgb, var(--blue) 18%, transp
336
365
  <main>
337
366
  <div class="hero">
338
367
  <h1>${escapeHtml(title)}</h1>
339
- <p>Merge base <code>${mergeBase.slice(0, 7)}</code></p>
368
+ <p>${subtitle}</p>
340
369
  </div>
341
370
  <h2 class="section-title">Layers</h2>
342
371
  <ol class="stack">
@@ -0,0 +1,62 @@
1
+ ---
2
+ name: dot-walkthrough-changes
3
+ description: Walk through the uncommitted changes of the working tree, or the changes between two trees, as an ordered stack of dependency layers, with an optional review and an HTML page. Use when the user or an agent asks to walk through or group the current changes before a commit. Do not use it for a review that needs no layers: use `dot-code-review`.
4
+ ---
5
+
6
+ # Changes walkthrough
7
+
8
+ Walk through the changes of the working tree as a **stack**: layers of files in dependency order. This skill follows [`dot-walkthrough-branch`](../dot-walkthrough-branch/SKILL.md). It differs in the target, the optional review, and the output path.
9
+
10
+ ## 1. Pick the target
11
+
12
+ - **Working tree** (default): the working tree against `HEAD`. The diff is `git diff HEAD`, and each untracked file that `git status --porcelain` lists is a new file. Git ignores the files that `.gitignore` names, so they stay out.
13
+ - **Tree range**: `<old-tree> <new-tree>`, when the caller gives the two tree ids. The diff is `git diff <old-tree> <new-tree>`.
14
+ - **Output path**: a file path from the caller, for the layers JSON.
15
+ - **Layers only**: when the caller says "layers only", skip step 3.
16
+ - **Page**: when the arguments include `page`, run step 5 after the report, without the offer.
17
+
18
+ Read each changed file from the working tree, or with `git show <tree>:<path>` for a tree range. For a deleted file, read it from `HEAD` or from the old tree.
19
+
20
+ State the target in one line: `working tree vs HEAD (<short sha>)`, or `<old-tree> .. <new-tree>`.
21
+
22
+ Done when you have the list of changed files. When there are none, stop and tell the user.
23
+
24
+ ## 2. Group the layers
25
+
26
+ Group the changed files into layers with the rules of [`layers.md`](../dot-walkthrough-branch/references/layers.md).
27
+
28
+ Done when each changed hunk is in exactly one layer, and no layer depends on a layer below it.
29
+
30
+ ## 3. Review
31
+
32
+ Skip this step when the caller said "layers only". Each layer then has an empty `findings` array.
33
+
34
+ Otherwise, follow step 3 of [`dot-walkthrough-branch`](../dot-walkthrough-branch/SKILL.md#3-review) on the diff of step 1.
35
+
36
+ Done when each layer has its findings, is clean, or was skipped.
37
+
38
+ ## 4. Report
39
+
40
+ Run this step only when the caller gave no output path. Fill the template of step 4 of [`dot-walkthrough-branch`](../dot-walkthrough-branch/SKILL.md#4-report), with the target line of step 1 in place of the branch line. When step 3 ran, add the "Make it impossible" section. Then offer the page of step 5.
41
+
42
+ With an output path, skip the report. Go to step 5.
43
+
44
+ Done when the report has every layer of step 2, and every finding of step 3 when it ran.
45
+
46
+ ## 5. Page
47
+
48
+ 1. Run `git check-ignore -q .tmp/` at the repository root. When it exits with a non-zero code, stop, and tell the caller that Git does not ignore `.tmp`, so the page could reach a commit.
49
+ 2. Write the layers to the output path of the caller, or to `.tmp/walkthrough/working-tree.json`. Sort the keys. Leave out `base` and `head`. For a tree range, add `oldTree` and `newTree` as full tree ids.
50
+
51
+ ```json
52
+ {
53
+ "layers": []
54
+ }
55
+ ```
56
+
57
+ `layers` has the layer objects of the layers JSON in [`layers.md`](../dot-walkthrough-branch/references/layers.md).
58
+
59
+ 3. Run the script of `dot-walkthrough-branch` from the repository root: `node <skills directory>/dot-walkthrough-branch/scripts/page.mjs <layers file>`. The page title is `working tree`, or the tree range.
60
+ 4. When the script exits with a non-zero code, fix the field that its message names, and run it again.
61
+
62
+ Done when the caller has the path of the page. With an output path, return the page path as the last line of the answer.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/mattpocock/skills",
3
+ "path": "skills/productivity/writing-for-agents",
4
+ "commit": "49dd158d1076134a641b33efb035946536778336",
5
+ "license": "MIT",
6
+ "modified": true,
7
+ "notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under rules/writing.md. Moved SKILL-MECHANICS.md to references/skill-mechanics.md, and moved the context pointers, the two loads, and the splits to references/pointers.md, and the completion criteria to references/steps.md."
8
+ }
@@ -1,10 +0,0 @@
1
- {
2
- "name": "dotagents",
3
- "description": "Skills, agents, and hooks for a planned, tested, and reviewed coding workflow.",
4
- "author": {
5
- "name": "igorlau"
6
- },
7
- "homepage": "https://github.com/igorlau/dotagents#readme",
8
- "repository": "https://github.com/igorlau/dotagents",
9
- "license": "MIT"
10
- }
@@ -1,27 +0,0 @@
1
- ---
2
- name: dot-implementer
3
- description: Write the production code of one roadmap task with the dot-implement skill, and hand off the test changes it needs. Use for the implementation step of the dot-flow skill.
4
- skills: dotagents:dot-implement
5
- disallowedTools: Agent
6
- ---
7
-
8
- # Implementer
9
-
10
- Run the implementation step of a roadmap task. Follow the `dot-implement` skill.
11
-
12
- ## Input
13
-
14
- The prompt gives these fields:
15
-
16
- - **Task**: the path of the roadmap task file.
17
- - **Findings**: only on a second run, the review findings to fix. Fix these findings and nothing else. For each finding, fix every place in the task change that has the same problem.
18
-
19
- When the task is missing, stop and report it.
20
-
21
- Write no tests, do not commit, and do not tick the roadmap checkbox.
22
-
23
- ## Output
24
-
25
- End with the handoff of step 5 of `dot-implement`, and write nothing after it. The next step writes the tests.
26
-
27
- On a run with **Findings**, end the handoff with the line `**Behavior change:** <yes | no>`. A behavior change is a change to what the code does for any input.
@@ -1,44 +0,0 @@
1
- ---
2
- name: dot-reviewer
3
- description: Review the uncommitted changes of one roadmap task with the dot-code-review skill. Use for the review step of the dot-flow skill.
4
- skills: dotagents:dot-code-review
5
- disallowedTools: Agent
6
- ---
7
-
8
- # Reviewer
9
-
10
- Run the review step of a roadmap task. Follow the `dot-code-review` skill.
11
-
12
- ## Input
13
-
14
- The prompt gives these fields:
15
-
16
- - **Task**: the path of the roadmap task file. Check the change against its requirements and its "Out of scope" section. Also read the `## Requirements` section of the roadmap `README.md`. Check the change against every non-negotiable (`NN`) and against each business rule (`BR`) that the task names. Report a breached `NN` as a `high` finding.
17
- - **Handoff**: the replies of the earlier steps.
18
- - **Since**: only on a delta review of a fix run, `<old-tree> <new-tree>`. Run `git diff <old-tree> <new-tree>`, and review only that diff. Still check the diff against every `NN` and each `BR` that the task names.
19
- - **Earlier findings**: only on a fix run, the findings of the earlier review that the implementer fixed. Give each one a status:
20
- - `fixed`: the problem is gone.
21
- - `open`: the problem is still there.
22
- - `regressed`: the fix made the problem worse, or moved it to other code.
23
-
24
- Do not report an earlier finding again as a new finding.
25
-
26
- When the task or the handoff is missing, stop and report it.
27
-
28
- Without **Since**, the target is the uncommitted change: `git diff HEAD`, plus the untracked files that `git status --short` lists. Review the whole target.
29
-
30
- Without **Earlier findings**, report every finding at every severity, so that no finding waits for a later round. With **Earlier findings**, on a full or a delta review, report only new `high` and `medium` findings.
31
-
32
- Keep the code as it is. Delete each test that you write to prove a finding. Do not commit, and do not tick the roadmap checkbox.
33
-
34
- ## Output
35
-
36
- Start the reply with this line. On a fix run, add the status of each earlier finding after it. Then give the report of `dot-code-review` with the new findings:
37
-
38
- ```markdown
39
- **Highest severity:** <high | medium | low | none>
40
- **Earlier findings:**
41
- - <fixed | open | regressed>: <the summary of the finding>
42
- ```
43
-
44
- The highest severity covers the new findings and the earlier findings that are `open` or `regressed`.
@@ -1,25 +0,0 @@
1
- ---
2
- name: dot-tester
3
- description: Write the tests of one roadmap task with the dot-testing skill, after the code exists. Use for the test step of the dot-flow skill.
4
- skills: dotagents:dot-testing
5
- disallowedTools: Agent
6
- ---
7
-
8
- # Tester
9
-
10
- Run the test step of a roadmap task. Follow the `dot-testing` skill and its `references/after-implement.md`.
11
-
12
- ## Input
13
-
14
- The prompt gives these fields:
15
-
16
- - **Task**: the path of the roadmap task file.
17
- - **Handoff**: the handoff of the implementation step, with the "Expected failures" and "Behaviors that need tests" fields.
18
-
19
- When a field is missing, stop and report it.
20
-
21
- Keep the production code as it is. Do not commit, and do not tick the roadmap checkbox.
22
-
23
- ## Output
24
-
25
- End with the reply that `references/after-implement.md` gives, and write nothing after it.
@@ -1,118 +0,0 @@
1
- // Hook for Claude Code, Copilot, and Codex. With `snapshot`, it runs when a
2
- // prompt arrives or a subagent starts, and records the working tree. Without
3
- // it, it runs when the agent or the subagent stops: when that agent changed
4
- // the tree, it runs the repository's `check` script and, when that fails,
5
- // asks the agent to continue with the output. A check that still fails on
6
- // the retry becomes a warning for the user, so the hook can't loop.
7
- // It acts only in repositories that `dotagents check enable` added to the
8
- // user's config, because the `check` script is the repository's own code.
9
- import { spawnSync } from "node:child_process";
10
- import crypto from "node:crypto";
11
- import fs from "node:fs";
12
- import os from "node:os";
13
- import path from "node:path";
14
-
15
- const MAX_OUTPUT = 4000;
16
-
17
- const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
18
- const cwd = input.cwd ?? process.cwd();
19
- // A subagent has its own snapshot, so each agent answers only for the changes that it made.
20
- const snapshotFile = path.join(os.tmpdir(), "dotagents-check", `${hash(input.agent_id ?? input.session_id ?? cwd)}.txt`);
21
-
22
- // Codex needs JSON on stdout when the hook exits 0.
23
- let decision = {};
24
- if (checkEnabled()) {
25
- if (process.argv[2] === "snapshot") saveSnapshot();
26
- else {
27
- const command = turnChangedTree() && checkCommand();
28
- if (command) decision = runCheck(command);
29
- // A blocked agent stops again, and that retry needs the snapshot.
30
- if (decision.decision !== "block") fs.rmSync(snapshotFile, { force: true });
31
- }
32
- }
33
- console.log(JSON.stringify(decision));
34
-
35
- function checkEnabled() {
36
- const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
37
- if (top.status !== 0) return false;
38
- // Same path as configDir() in the CLI's src/paths.ts.
39
- const configDir = process.env.XDG_CONFIG_HOME ? path.join(process.env.XDG_CONFIG_HOME, "dotagents") : path.join(os.homedir(), ".config", "dotagents");
40
- try {
41
- const { checkRepos = [] } = JSON.parse(fs.readFileSync(path.join(configDir, "config.json"), "utf8"));
42
- return Array.isArray(checkRepos) && checkRepos.includes(fs.realpathSync(top.stdout.trim()));
43
- } catch {
44
- return false;
45
- }
46
- }
47
-
48
- function saveSnapshot() {
49
- const tree = treeHash();
50
- if (!tree) return;
51
- fs.mkdirSync(path.dirname(snapshotFile), { recursive: true });
52
- fs.writeFileSync(snapshotFile, tree);
53
- }
54
-
55
- // Without a snapshot or Git, a change can't be proven, so the check doesn't run:
56
- // a failing check on untouched code would make the agent edit what nobody asked for.
57
- function turnChangedTree() {
58
- const tree = treeHash();
59
- if (!tree || !fs.existsSync(snapshotFile)) return false;
60
- return fs.readFileSync(snapshotFile, "utf8") !== tree;
61
- }
62
-
63
- /** Hashes the working tree, untracked files included and ignored files excluded, without touching the repository's index. */
64
- function treeHash() {
65
- const index = path.join(os.tmpdir(), `dotagents-index-${process.pid}`);
66
- const env = { ...process.env, GIT_INDEX_FILE: index };
67
- try {
68
- // Starting from a copy of the real index reuses its file stat cache, so unchanged files aren't rehashed.
69
- const realIndex = spawnSync("git", ["rev-parse", "--path-format=absolute", "--git-path", "index"], { cwd, encoding: "utf8" });
70
- if (realIndex.status === 0 && fs.existsSync(realIndex.stdout.trim())) fs.copyFileSync(realIndex.stdout.trim(), index);
71
- const add = spawnSync("git", ["add", "--all", "."], { cwd, env, encoding: "utf8" });
72
- if (add.status !== 0) return undefined;
73
- const tree = spawnSync("git", ["write-tree"], { cwd, env, encoding: "utf8" });
74
- return tree.status === 0 ? tree.stdout.trim() : undefined;
75
- } finally {
76
- fs.rmSync(index, { force: true });
77
- }
78
- }
79
-
80
- /** Returns the command and arguments that run the repository's `check`: an npm script, else a Makefile target. */
81
- function checkCommand() {
82
- if (hasNpmCheck()) return ["npm", "run", "--silent", "check"];
83
- if (hasMakeCheck()) return ["make", "--silent", "check"];
84
- return undefined;
85
- }
86
-
87
- function hasNpmCheck() {
88
- try {
89
- return Boolean(JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")).scripts?.check);
90
- } catch {
91
- return false;
92
- }
93
- }
94
-
95
- function hasMakeCheck() {
96
- try {
97
- return /^check:/m.test(fs.readFileSync(path.join(cwd, "Makefile"), "utf8"));
98
- } catch {
99
- return false;
100
- }
101
- }
102
-
103
- function runCheck([command, ...args]) {
104
- const result = spawnSync(command, args, { cwd, encoding: "utf8", shell: process.platform === "win32" });
105
- // A runner that isn't installed can't prove a failure.
106
- if (result.status === 0 || result.error) return {};
107
- const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim().slice(-MAX_OUTPUT) || "It printed nothing.";
108
- const failure = `\`${[command, ...args.filter((arg) => arg !== "--silent")].join(" ")}\` failed with exit code ${result.status}.`;
109
- if (input.stop_hook_active) return { systemMessage: `${failure} The agent already tried to fix it, so the check still fails:\n${output}` };
110
- return {
111
- decision: "block",
112
- reason: `${failure} Fix the problems that your changes caused, then finish. If a problem was there before your changes, leave it and tell the user:\n${output}`,
113
- };
114
- }
115
-
116
- function hash(text) {
117
- return crypto.createHash("sha256").update(text).digest("hex").slice(0, 16);
118
- }
@@ -1,54 +0,0 @@
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
- "SessionStart": [
14
- {
15
- "hooks": [
16
- {
17
- "type": "command",
18
- "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/rules.mjs\""
19
- }
20
- ]
21
- }
22
- ],
23
- "SubagentStart": [
24
- {
25
- "hooks": [
26
- {
27
- "type": "command",
28
- "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check.mjs\" snapshot"
29
- }
30
- ]
31
- }
32
- ],
33
- "SubagentStop": [
34
- {
35
- "hooks": [
36
- {
37
- "type": "command",
38
- "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check.mjs\""
39
- }
40
- ]
41
- }
42
- ],
43
- "Stop": [
44
- {
45
- "hooks": [
46
- {
47
- "type": "command",
48
- "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check.mjs\""
49
- }
50
- ]
51
- }
52
- ]
53
- }
54
- }
@@ -1,27 +0,0 @@
1
- // Hook for the start of a session. The plugin updates on every commit, but the
2
- // rules reach Claude Code only when the user runs `dotagents update`. This
3
- // hook warns the user when the installed rules differ from the plugin's rules.
4
- // shortcut: checks only Claude Code's rules file, add the Codex and Copilot blocks when their plugins update apart from the CLI.
5
- import fs from "node:fs";
6
- import os from "node:os";
7
- import path from "node:path";
8
- import { fileURLToPath } from "node:url";
9
-
10
- const rulesDir = fileURLToPath(new URL("../rules", import.meta.url));
11
- const claudeHome = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
12
- const installedFile = path.join(claudeHome, "rules", "dotagents.md");
13
-
14
- let message;
15
- try {
16
- const installed = fs.readFileSync(installedFile, "utf8");
17
- // Same heading shift as loadRules() in the CLI's src/catalog.ts.
18
- const stale = fs
19
- .readdirSync(rulesDir)
20
- .filter((name) => name.endsWith(".md"))
21
- .some((name) => !installed.includes(fs.readFileSync(path.join(rulesDir, name), "utf8").trim().replace(/^#/gm, "##")));
22
- if (stale) message = "The installed dotagents rules differ from the rules of the dotagents plugin. Run `dotagents update` with a release that has the same rules, and add `--force` if you changed the rules file.";
23
- } catch {
24
- // Without Claude Code's directory, another coding agent runs the plugin, and its rules are in another file.
25
- if (fs.existsSync(claudeHome)) message = "The dotagents plugin needs the dotagents rules. Run `npx @igorlau/dotagents install`.";
26
- }
27
- console.log(JSON.stringify(message ? { systemMessage: message } : {}));
@@ -1,8 +0,0 @@
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
- }
@@ -1,5 +0,0 @@
1
- interface:
2
- display_name: "Correct"
3
- short_description: "Turn a repeated agent mistake into a check"
4
- policy:
5
- allow_implicit_invocation: false
@@ -1,3 +0,0 @@
1
- interface:
2
- display_name: "Debug"
3
- short_description: "Diagnose hard bugs and regressions"
@@ -1,105 +0,0 @@
1
- ---
2
- name: dot-flow
3
- description: Take one roadmap task through implementation, tests, and review, fix the high and medium findings in automatic rounds, and stop for your decision.
4
- disable-model-invocation: true
5
- ---
6
-
7
- # Flow
8
-
9
- Take one task from a `dot-roadmap` roadmap through three steps: implementation, tests, and review. Each step runs in a fresh agent with one skill. You coordinate the steps, and you verify each reply with the commands that it names. The agents write the code, the tests, and the review. The user decides at a stop.
10
-
11
- ## 1. Pin the task
12
-
13
- The input is a roadmap task file or a roadmap directory. With a directory, pick the lowest-id unticked task whose blockers are all ticked in its `README.md`. If the task has an unticked blocker, stop and name it.
14
-
15
- Run `git status --short`. The review step reads every uncommitted change, so when the working tree has other changes, ask the user to commit them first or to include them in the review.
16
-
17
- Done when you can name the task file and its goal.
18
-
19
- ## 2. Pick the runner
20
-
21
- Use the agents of the dotagents plugin when the `Agent` tool can start them: `dotagents:dot-implementer`, `dotagents:dot-tester`, and `dotagents:dot-reviewer`. Otherwise, such as in Codex or Copilot, read [`references/inline.md`](references/inline.md), and run each step inline with the same verification and stops.
22
-
23
- ## 3. Run and verify the steps
24
-
25
- Run the steps in this order. For each step, start a new agent of the named type, not a fork, so that each step starts with a fresh context:
26
-
27
- | Step | Agent | Prompt fields |
28
- | ---- | ----- | ------------- |
29
- | 1. Implement | `dotagents:dot-implementer` | Task |
30
- | 2. Test | `dotagents:dot-tester` | Task, Handoff: the reply of step 1 |
31
- | 3. Review | `dotagents:dot-reviewer` | Task, Handoff: the replies of steps 1 and 2, Since and Earlier findings: only on a fix run |
32
-
33
- Write the prompt as labeled fields, and leave out a field that the step does not take:
34
-
35
- ```markdown
36
- **Task:** <path of the task file>
37
- **Handoff:**
38
- <the replies of the earlier steps, unchanged>
39
- **Findings:**
40
- <the findings to fix, unchanged>
41
- **Since:** <old-tree> <new-tree>
42
- **Earlier findings:**
43
- <the findings that the round sent to fix and the light-fixed findings, unchanged>
44
- ```
45
-
46
- Copy the replies and the findings unchanged, because the agents read their fields. Add no other fields or instructions, such as a list of files to review.
47
-
48
- A reply is a claim, not a result. After steps 1 and 2, run each command that the reply names in its **Checks** or **Tests** line, and read only the result line and the names of the tests that fail. Keep the main context small: do not read the changed files. The step is **verified** when all of these are true:
49
-
50
- - The type checker and the linter pass.
51
- - After step 1, each test that fails is in "Expected failures".
52
- - After step 2, the test command passes.
53
- - The reply has no blockers.
54
-
55
- After a verified step, show the user one line, such as "Step 1 of 3: verified, `npm run check` passes", and start the next step. Do not wait.
56
-
57
- Stop the flow, keep the files as they are, and ask the user how to continue in these cases:
58
-
59
- - A reply has blockers. Show them.
60
- - A step is not verified. Show the command, your result line, and the line of the reply.
61
- - The `check` hook reports a failure to you. An agent left it, so the step is not verified. Show the output, and do not edit the code yourself.
62
-
63
- Done when the review reply arrived, or the flow stopped.
64
-
65
- ## 4. Decide after each review
66
-
67
- When the first review reply of the task arrives, write the old tree, as the "Snapshots" section of [`references/fix-round.md`](references/fix-round.md#snapshots) gives it.
68
-
69
- A **fix round** runs step 1 again in a new agent, with the findings to fix as a **Findings** field, then takes the light path or runs steps 2 and 3 again. Before the first fix round, read [`references/fix-round.md`](references/fix-round.md), for the snapshots, the light path, the review fields, and the findings to carry.
70
-
71
- After each review, check the stop rules. When no stop rule is true, run an **automatic round**: a fix round of every `high` and `medium` finding, with no question to the user. Show one line, such as "Round 2: automatic fix of 1 `medium` finding". The task has a limit of 2 automatic rounds. Rounds that the user picks do not count, and do not reset the count. The automatic rounds also follow a review after a round that the user picked.
72
-
73
- ### Stop rules
74
-
75
- Stop the loop and ask the user when any of these is true:
76
-
77
- 1. The highest severity is `low`, or no findings remain.
78
- 2. 2 automatic rounds have run.
79
- 3. A finding that the round sent to fix has the status `open` or `regressed`.
80
- 4. After a fix round, the count did not go down since the review before. The count is the `high` and `medium` findings that remain after the review, carried findings included.
81
- 5. A stop of step 3 fires.
82
-
83
- At the stop, show the round history, with one row for each round:
84
-
85
- ```markdown
86
- | Round | Kind | Review | Fixed | Open | Regressed | New | Highest |
87
- | ----- | ---- | ------ | ----- | ---- | --------- | --- | ------- |
88
- | 1 | first | full | - | - | - | 4 | medium |
89
- | 2 | auto | delta | 2 | 0 | 0 | 0 | low |
90
- ```
91
-
92
- Kind is `first`, `auto`, `user`, or `light`. A `light` round has `none` in the Review column. Highest is the highest severity of the findings that remain after the round.
93
-
94
- Then show the **Highest severity** line and one line for each finding: its severity, summary, and `file:line`, and its status when it has one. Show each `high` finding with its **Fix** line. The presumed blockers of the maintainability pass are `high`. Then wait for the user to pick one:
95
-
96
- - **Fix**: the user names the findings to fix. Run a fix round with them.
97
- - **Accept**: the user accepts the findings that remain.
98
-
99
- Done when the user accepts.
100
-
101
- ## 5. Finish
102
-
103
- List the files that the steps changed, from the **Files** lines of the replies. Suggest the `dot-commit` skill, and name the task file, so that `dot-commit` can tick its checkbox.
104
-
105
- Do not commit, and do not tick the roadmap checkbox: `dot-commit` ticks it when the commits finish the task.
@@ -1,5 +0,0 @@
1
- interface:
2
- display_name: "Flow"
3
- short_description: "Run a roadmap task through tests, code, and review"
4
- policy:
5
- allow_implicit_invocation: false