@igorlau/dotagents 1.0.15 → 1.0.17

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 (49) hide show
  1. package/README.md +39 -45
  2. package/THIRD_PARTY_NOTICES.md +1 -1
  3. package/dist/apply.js +6 -6
  4. package/dist/build-info.json +1 -1
  5. package/dist/cli.js +24 -4
  6. package/dist/commands.js +70 -16
  7. package/dist/git.js +1 -1
  8. package/dist/targets.js +24 -5
  9. package/dist/wizard.js +248 -0
  10. package/package.json +5 -1
  11. package/plugin/.claude-plugin/plugin.json +1 -1
  12. package/plugin/agents/dot-implementer.md +4 -17
  13. package/plugin/agents/dot-reviewer.md +4 -3
  14. package/plugin/agents/dot-tester.md +5 -13
  15. package/plugin/hooks/check.mjs +37 -11
  16. package/plugin/hooks/hooks.json +30 -0
  17. package/plugin/hooks/rules.mjs +27 -0
  18. package/plugin/rules/code-style.md +1 -1
  19. package/plugin/rules/core.md +2 -2
  20. package/plugin/rules/ponytail.md +1 -1
  21. package/plugin/rules/ponytail.upstream.json +1 -1
  22. package/plugin/rules/writing.md +3 -4
  23. package/plugin/rules/writing.upstream.json +1 -1
  24. package/plugin/scaffold/AGENTS.md.tmpl +2 -2
  25. package/plugin/skills/dot-code-review/SKILL.md +1 -3
  26. package/plugin/skills/dot-commit/SKILL.md +1 -5
  27. package/plugin/skills/dot-correct/SKILL.md +1 -3
  28. package/plugin/skills/dot-debug/SKILL.md +4 -6
  29. package/plugin/skills/dot-debug/UPSTREAM.json +1 -1
  30. package/plugin/skills/dot-docs-writing/SKILL.md +1 -3
  31. package/plugin/skills/dot-flow/SKILL.md +29 -29
  32. package/plugin/skills/dot-flow/references/inline.md +5 -38
  33. package/plugin/skills/dot-grilling/SKILL.md +1 -3
  34. package/plugin/skills/dot-grilling/UPSTREAM.json +1 -1
  35. package/plugin/skills/dot-handoff/SKILL.md +1 -3
  36. package/plugin/skills/dot-handoff/UPSTREAM.json +1 -1
  37. package/plugin/skills/dot-implement/SKILL.md +12 -9
  38. package/plugin/skills/dot-plan/SKILL.md +33 -12
  39. package/plugin/skills/dot-plan/references/entity-schemas.md +3 -3
  40. package/plugin/skills/dot-roadmap/SKILL.md +21 -11
  41. package/plugin/skills/dot-roadmap/agents/openai.yaml +5 -0
  42. package/plugin/skills/dot-testing/SKILL.md +2 -5
  43. package/plugin/skills/dot-testing/references/after-implement.md +23 -0
  44. package/plugin/skills/dot-writing-for-agents/SKILL.md +1 -3
  45. package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +1 -1
  46. package/plugin/skills/dot-grill-me/SKILL.md +0 -11
  47. package/plugin/skills/dot-grill-me/UPSTREAM.json +0 -8
  48. package/plugin/skills/dot-grill-me/agents/openai.yaml +0 -5
  49. package/plugin/skills/dot-testing/references/modes.md +0 -32
package/dist/wizard.js ADDED
@@ -0,0 +1,248 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import fs from "node:fs";
3
+ import path from "node:path";
4
+ import * as clack from "@clack/prompts";
5
+ import { checkHookEnabled, dotagentsPluginInstalled, init, install, listScaffoldFiles, NOTHING_TO_UNINSTALL, PLUGIN_HINT, previewInit, previewInstall, previewScaffold, previewUninstall, projectRoot, scaffold, setCheckHook, uninstall, UP_TO_DATE, } from "./commands.js";
6
+ import { repoRoot } from "./git.js";
7
+ import { homeDir } from "./paths.js";
8
+ import { AGENTS, claudeMdSkipsAgentsMd } from "./targets.js";
9
+ export const CANCEL = Symbol("cancel");
10
+ export const clackPrompts = {
11
+ async confirm(options) {
12
+ const answer = await clack.confirm(options);
13
+ return clack.isCancel(answer) ? CANCEL : answer;
14
+ },
15
+ async multiselect(options) {
16
+ const answer = await clack.multiselect(options);
17
+ return clack.isCancel(answer) ? CANCEL : answer;
18
+ },
19
+ note(message, title) {
20
+ clack.note(message, title);
21
+ },
22
+ async select(options) {
23
+ const answer = await clack.select(options);
24
+ return clack.isCancel(answer) ? CANCEL : answer;
25
+ },
26
+ };
27
+ export const claudePlugin = {
28
+ available() {
29
+ return spawnSync("claude", ["--version"], { stdio: "ignore" }).error === undefined;
30
+ },
31
+ install() {
32
+ const result = spawnSync("claude", ["plugin", "install", "dotagents", "--marketplace", "igorlau/dotagents"], { encoding: "utf8" });
33
+ if (result.error?.code === "ENOENT")
34
+ return { kind: "missing" };
35
+ if (result.error)
36
+ return { kind: "failed", output: result.error.message };
37
+ return result.status === 0 ? { kind: "installed" } : { kind: "failed", output: `${result.stdout}${result.stderr}`.trim() };
38
+ },
39
+ };
40
+ /** Whether the CLI opens the install wizard: in a terminal, for no command or `install`, with no flag other than `--agents`. */
41
+ export function opensWizard({ command, interactive, values }) {
42
+ if (!interactive)
43
+ return false;
44
+ if (command !== undefined && command !== "install")
45
+ return false;
46
+ return !values["dry-run"] && !values.force && !values.global && !values.project && values.source === undefined;
47
+ }
48
+ const AGENT_LABELS = { claude: "Claude Code", codex: "Codex", copilot: "GitHub Copilot" };
49
+ async function askAgents(prompts, agents) {
50
+ return (agents ??
51
+ prompts.multiselect({
52
+ initialValues: [...AGENTS],
53
+ message: "Which agents do you use?",
54
+ options: AGENTS.map((agent) => ({ label: AGENT_LABELS[agent], value: agent })),
55
+ required: true,
56
+ }));
57
+ }
58
+ /** Asks for the agents, the scope, and the Claude Code plugin, shows the changes, and installs after the user confirms. */
59
+ export async function installWizard(prompts, plugin, options) {
60
+ const agents = await askAgents(prompts, options.agents);
61
+ if (agents === CANCEL)
62
+ return cancelled();
63
+ const root = repoRoot(options.cwd);
64
+ const scope = root === undefined
65
+ ? "global"
66
+ : await prompts.select({
67
+ initialValue: "global",
68
+ message: "Where do you want to install dotagents?",
69
+ options: [
70
+ { label: "Global (Recommended)", value: "global" },
71
+ { label: "This repository, for collaborators", value: "project" },
72
+ ],
73
+ });
74
+ if (scope === CANCEL)
75
+ return cancelled();
76
+ const needsPlugin = scope === "global" && agents.includes("claude") && !dotagentsPluginInstalled();
77
+ const claudeFound = needsPlugin && plugin.available();
78
+ const installPlugin = claudeFound && (await prompts.confirm({ message: "Install the dotagents plugin for Claude Code?" }));
79
+ if (installPlugin === CANCEL)
80
+ return cancelled();
81
+ const setup = root === undefined ? [] : await askSetup(prompts, root);
82
+ if (setup === CANCEL)
83
+ return cancelled();
84
+ const scaffoldFiles = setup.includes("scaffold") ? newScaffoldFiles(options.cwd, agents) : [];
85
+ const scaffoldLines = scaffoldFiles.length > 0 ? summaryLines(previewScaffold(options.cwd, agents, scaffoldFiles)) : [];
86
+ const hintLines = root === undefined ? [] : importHint(root, agents, scaffoldFiles);
87
+ const preview = scope === "global" ? previewInstall(agents) : previewInit(options.cwd, agents, { scaffoldFiles });
88
+ const pluginLines = needsPlugin && !claudeFound ? [PLUGIN_HINT] : [];
89
+ const checkLines = root !== undefined && setup.includes("check") ? [`Enable the check hook in ${withTilde(root)}`] : [];
90
+ prompts.note([...scaffoldLines, ...hintLines, ...summaryLines(preview), ...pluginLines, ...checkLines].join("\n"), "Installation summary");
91
+ const proceed = await prompts.confirm({ message: "Proceed with installation?" });
92
+ if (proceed !== true)
93
+ return cancelled();
94
+ const installOptions = { agents, dryRun: false, force: false };
95
+ const scaffolded = scaffoldFiles.length > 0 ? scaffold(options.cwd, installOptions, { files: scaffoldFiles }) : true;
96
+ const installed = scope === "global" ? install(installOptions, false) : init(options.cwd, installOptions);
97
+ if (installPlugin)
98
+ installClaudePlugin(plugin);
99
+ if (claudeFound && !installPlugin)
100
+ console.log(PLUGIN_HINT);
101
+ if (setup.includes("check"))
102
+ setCheckHook(options.cwd, true, false);
103
+ for (const line of hintLines)
104
+ console.log(line);
105
+ return scaffolded && installed;
106
+ }
107
+ /** Offers the repository steps that apply, all unchecked: the `check` hook, and `scaffold` when the repository has no AGENTS.md. */
108
+ async function askSetup(prompts, root) {
109
+ const options = [];
110
+ if (hasCheckScript(root) && !checkHookEnabled(root))
111
+ options.push({ label: "Enable the check hook", value: "check" });
112
+ if (!fs.existsSync(path.join(root, "AGENTS.md")))
113
+ options.push({ label: "Create AGENTS.md and the agent instruction files", value: "scaffold" });
114
+ if (options.length === 0)
115
+ return [];
116
+ return prompts.multiselect({ initialValues: [], message: "Set up this repository?", options, required: false });
117
+ }
118
+ function hasCheckScript(root) {
119
+ return hasNpmCheck(root) || hasMakeCheck(root);
120
+ }
121
+ function hasNpmCheck(root) {
122
+ try {
123
+ return Boolean(JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).scripts?.check);
124
+ }
125
+ catch {
126
+ return false;
127
+ }
128
+ }
129
+ function hasMakeCheck(root) {
130
+ try {
131
+ return /^check:/m.test(fs.readFileSync(path.join(root, "Makefile"), "utf8"));
132
+ }
133
+ catch {
134
+ return false;
135
+ }
136
+ }
137
+ function newScaffoldFiles(cwd, agents) {
138
+ return listScaffoldFiles(cwd, agents)
139
+ .filter((file) => !file.exists)
140
+ .map((file) => file.path);
141
+ }
142
+ /** Asks for the agents and the files, shows the files to create, and creates the checked files after the user confirms. Throws outside a repository. */
143
+ export async function scaffoldWizard(prompts, options) {
144
+ const root = projectRoot(options.cwd);
145
+ const agents = await askAgents(prompts, options.agents);
146
+ if (agents === CANCEL)
147
+ return cancelled();
148
+ const candidates = listScaffoldFiles(options.cwd, agents);
149
+ if (candidates.every((file) => file.exists)) {
150
+ console.log("Every scaffold file exists. Nothing changed.");
151
+ return true;
152
+ }
153
+ const files = await prompts.multiselect({
154
+ initialValues: candidates.filter((file) => !file.exists).map((file) => file.path),
155
+ message: "Which files do you want to create?",
156
+ options: candidates.map((file) => ({
157
+ disabled: file.exists,
158
+ hint: file.exists ? "exists, skip" : undefined,
159
+ label: path.relative(root, file.path),
160
+ value: file.path,
161
+ })),
162
+ required: true,
163
+ });
164
+ if (files === CANCEL)
165
+ return cancelled();
166
+ const hintLines = importHint(root, agents, files);
167
+ prompts.note([...summaryLines(previewScaffold(options.cwd, agents, files)), ...hintLines].join("\n"), "Scaffold summary");
168
+ const proceed = await prompts.confirm({ message: "Create these files?" });
169
+ if (proceed !== true)
170
+ return cancelled();
171
+ const ok = scaffold(options.cwd, { agents, dryRun: false, force: false }, { files });
172
+ for (const line of hintLines)
173
+ console.log(line);
174
+ return ok;
175
+ }
176
+ /** Asks which install to remove when both exist, shows the files to remove, and uninstalls after the user confirms. */
177
+ export async function uninstallWizard(prompts, options) {
178
+ const installs = previewUninstall(options.cwd, options.which);
179
+ const [first] = installs;
180
+ if (first === undefined) {
181
+ console.log(NOTHING_TO_UNINSTALL);
182
+ return true;
183
+ }
184
+ const choice = installs.length === 1
185
+ ? first.mode
186
+ : await prompts.select({
187
+ message: "Which install do you want to remove?",
188
+ options: [...installs.map((install) => ({ label: installLabel(install), value: install.mode })), { label: "Both", value: "both" }],
189
+ });
190
+ if (choice === CANCEL)
191
+ return cancelled();
192
+ const chosen = installs.filter((install) => choice === "both" || install.mode === choice);
193
+ prompts.note(chosen.flatMap((install) => removalLines(install)).join("\n"), "Uninstall summary");
194
+ const proceed = await prompts.confirm({ message: "Remove these files?" });
195
+ if (proceed !== true)
196
+ return cancelled();
197
+ return uninstall(options.cwd, choice === "both" ? undefined : choice, { dryRun: false, force: false });
198
+ }
199
+ function installLabel(install) {
200
+ return install.mode === "global" ? "The global install" : `The project install in ${install.root}`;
201
+ }
202
+ function removalLines(install) {
203
+ if (install.result.changes.length > 0 || install.result.problems.length > 0)
204
+ return summaryLines(install.result);
205
+ return [`${installLabel(install)}: no files to remove. Only the manifest is deleted.`];
206
+ }
207
+ const IMPORT_HINT = "CLAUDE.md does not import AGENTS.md. Add the line `@AGENTS.md` to CLAUDE.md so Claude Code reads it, then run `dotagents update`.";
208
+ function importHint(root, agents, files) {
209
+ if (!agents.includes("claude") || !files.includes(path.join(root, "AGENTS.md")))
210
+ return [];
211
+ return claudeMdSkipsAgentsMd(root) ? [IMPORT_HINT] : [];
212
+ }
213
+ function installClaudePlugin(plugin) {
214
+ const result = plugin.install();
215
+ if (result.kind === "installed") {
216
+ console.log("The dotagents plugin for Claude Code is installed.");
217
+ return;
218
+ }
219
+ if (result.kind === "failed")
220
+ console.log(result.output);
221
+ console.log(PLUGIN_HINT);
222
+ }
223
+ function cancelled() {
224
+ console.log("Cancelled. Nothing changed.");
225
+ return false;
226
+ }
227
+ const SKILL_FILE = /^(.*[\\/]skills)[\\/][^\\/]+[\\/]/;
228
+ /** Counts the changes of each action in each target directory, then lists each problem. */
229
+ export function summaryLines(result) {
230
+ if (result.changes.length === 0 && result.problems.length === 0)
231
+ return [UP_TO_DATE];
232
+ const groups = new Map();
233
+ for (const change of result.changes) {
234
+ const group = withTilde(SKILL_FILE.exec(change.path)?.[1] ?? change.path);
235
+ const counts = groups.get(group) ?? new Map();
236
+ counts.set(change.action, (counts.get(change.action) ?? 0) + 1);
237
+ groups.set(group, counts);
238
+ }
239
+ const lines = [...groups].map(([group, counts]) => {
240
+ const actions = [...counts].map(([action, count]) => `${action} ${count} ${count === 1 ? "file" : "files"}`);
241
+ return `${group}: ${actions.join(", ")}`;
242
+ });
243
+ return [...lines, ...result.problems];
244
+ }
245
+ function withTilde(file) {
246
+ const home = homeDir();
247
+ return file.startsWith(home + path.sep) ? `~${file.slice(home.length)}` : file;
248
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@igorlau/dotagents",
3
- "version": "1.0.15",
3
+ "version": "1.0.17",
4
4
  "description": "Install a curated set of agent skills and rules into Claude Code, Codex, and GitHub Copilot.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -27,10 +27,14 @@
27
27
  "build": "tsc -p tsconfig.build.json && node scripts/build-info.mjs",
28
28
  "prepare": "npm run build",
29
29
  "typecheck": "tsc -p tsconfig.json --noEmit",
30
+ "check": "npm run --silent typecheck && npm run --silent lint:content",
30
31
  "test": "node --test 'test/**/*.test.ts'",
31
32
  "lint:content": "node scripts/lint-content.ts",
32
33
  "check-upstream": "node scripts/check-upstream.ts"
33
34
  },
35
+ "dependencies": {
36
+ "@clack/prompts": "1.9.0"
37
+ },
34
38
  "devDependencies": {
35
39
  "@types/node": "^24.0.0",
36
40
  "typescript": "^5.9.0"
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dotagents",
3
- "description": "Skills, agents, and hooks for a planned, test-first, reviewed coding workflow.",
3
+ "description": "Skills, agents, and hooks for a planned, tested, and reviewed coding workflow.",
4
4
  "author": {
5
5
  "name": "igorlau"
6
6
  },
@@ -14,25 +14,12 @@ Run the implementation step of a roadmap task. Follow the `dot-implement` skill.
14
14
  The prompt gives these fields:
15
15
 
16
16
  - **Task**: the path of the roadmap task file.
17
- - **Handoff**: the reply of the stub step, with the pending tests that it wrote.
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
18
 
19
- When a field is missing, stop and report it.
19
+ When the task is missing, stop and report it.
20
20
 
21
- Do not commit, and do not tick the roadmap checkbox.
21
+ Write no tests, do not commit, and do not tick the roadmap checkbox.
22
22
 
23
23
  ## Output
24
24
 
25
- End with this reply, and keep the summary to 3 sentences or fewer. Copy the two handoff fields from step 5 of `dot-implement`:
26
-
27
- ```markdown
28
- **Summary:** <what you did>
29
- **Checks:** <the type checker, linter, and test commands, with their result lines>
30
- **Files:** <the production files that you changed>
31
- **Blockers:** <what stops the next step, or "none">
32
-
33
- **Expected failures:**
34
- - `<test file>`: <test name>: <the new behavior that the test must assert>
35
-
36
- **Behaviors that need tests:**
37
- - `<module>`: <a behavior that the change adds or changes, and that no test case covers>
38
- ```
25
+ End with the handoff of step 5 of `dot-implement`, and write nothing after it. The next step writes the tests.
@@ -13,12 +13,13 @@ Run the review step of a roadmap task. Follow the `dot-code-review` skill.
13
13
 
14
14
  The prompt gives these fields:
15
15
 
16
- - **Task**: the path of the roadmap task file. Check the change against its requirements and its "Out of scope" section.
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
17
  - **Handoff**: the replies of the earlier steps.
18
+ - **Findings**: only on a fix run, the findings of the earlier review that the implementer fixed. Check that each one is gone, and that each fix did not break other code of the task. Report a finding that is still there again.
18
19
 
19
- When a field is missing, stop and report it.
20
+ When the task or the handoff is missing, stop and report it.
20
21
 
21
- The target is the uncommitted change: `git diff HEAD`, plus the untracked files that `git status --short` lists. Report the findings, and keep the code as it is. Delete each test that you write to prove a finding.
22
+ The target is the uncommitted change: `git diff HEAD`, plus the untracked files that `git status --short` lists. Review the whole target on each run, also on a fix run. Report every finding at every severity in this review, so that no finding waits for a later round. Keep the code as it is. Delete each test that you write to prove a finding.
22
23
 
23
24
  Do not commit, and do not tick the roadmap checkbox.
24
25
 
@@ -1,33 +1,25 @@
1
1
  ---
2
2
  name: dot-tester
3
- description: Write the tests of one roadmap task with the dot-testing skill, in stub mode before the code exists or in fill mode after it. Use for the test steps of the dot-flow skill.
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
4
  skills: dotagents:dot-testing
5
5
  disallowedTools: Agent
6
6
  ---
7
7
 
8
8
  # Tester
9
9
 
10
- Run one test step of a roadmap task. Follow the `dot-testing` skill and its `references/modes.md`.
10
+ Run the test step of a roadmap task. Follow the `dot-testing` skill and its `references/after-implement.md`.
11
11
 
12
12
  ## Input
13
13
 
14
14
  The prompt gives these fields:
15
15
 
16
16
  - **Task**: the path of the roadmap task file.
17
- - **Mode**: `stub` or `fill`.
18
- - **Handoff**: in fill mode, the handoff of the implementation step, with the "Expected failures" and "Behaviors that need tests" fields.
17
+ - **Handoff**: the handoff of the implementation step, with the "Expected failures" and "Behaviors that need tests" fields.
19
18
 
20
19
  When a field is missing, stop and report it.
21
20
 
22
- Do not commit, and do not tick the roadmap checkbox.
21
+ Keep the production code as it is. Do not commit, and do not tick the roadmap checkbox.
23
22
 
24
23
  ## Output
25
24
 
26
- End with this reply, and keep the summary to 3 sentences or fewer:
27
-
28
- ```markdown
29
- **Summary:** <what you did>
30
- **Tests:** <the test command and its result line>
31
- **Files:** <the test files that you changed>
32
- **Blockers:** <what stops the next step, or "none">
33
- ```
25
+ End with the reply that `references/after-implement.md` gives, and write nothing after it.
@@ -1,7 +1,9 @@
1
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.
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.
5
7
  // It acts only in repositories that `dotagents check enable` added to the
6
8
  // user's config, because the `check` script is the repository's own code.
7
9
  import { spawnSync } from "node:child_process";
@@ -14,15 +16,18 @@ const MAX_OUTPUT = 4000;
14
16
 
15
17
  const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
16
18
  const cwd = input.cwd ?? process.cwd();
17
- const snapshotFile = path.join(os.tmpdir(), "dotagents-check", `${hash(input.session_id ?? cwd)}.txt`);
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`);
18
21
 
19
22
  // Codex needs JSON on stdout when the hook exits 0.
20
23
  let decision = {};
21
24
  if (checkEnabled()) {
22
25
  if (process.argv[2] === "snapshot") saveSnapshot();
23
26
  else {
24
- if (!input.stop_hook_active && turnChangedTree() && hasCheckScript()) decision = runCheck();
25
- fs.rmSync(snapshotFile, { force: true });
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 });
26
31
  }
27
32
  }
28
33
  console.log(JSON.stringify(decision));
@@ -72,7 +77,14 @@ function treeHash() {
72
77
  }
73
78
  }
74
79
 
75
- function hasCheckScript() {
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() {
76
88
  try {
77
89
  return Boolean(JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")).scripts?.check);
78
90
  } catch {
@@ -80,11 +92,25 @@ function hasCheckScript() {
80
92
  }
81
93
  }
82
94
 
83
- function runCheck() {
84
- const result = spawnSync("npm", ["run", "--silent", "check"], { cwd, encoding: "utf8", shell: process.platform === "win32" });
85
- if (result.status === 0) return {};
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 {};
86
107
  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}` };
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
+ };
88
114
  }
89
115
 
90
116
  function hash(text) {
@@ -10,6 +10,36 @@
10
10
  ]
11
11
  }
12
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
+ ],
13
43
  "Stop": [
14
44
  {
15
45
  "hooks": [
@@ -0,0 +1,27 @@
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 } : {}));
@@ -2,5 +2,5 @@
2
2
 
3
3
  Apply these rules when you write or refactor code:
4
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.
5
+ - Branch with `if` and an early return. Reach for `else`, `else if`, or `switch` only where early returns cannot express the logic.
6
6
  - Sort keys alphabetically in JSON files, such as translations, unless the order changes behavior.
@@ -1,8 +1,8 @@
1
1
  # Working agreements
2
2
 
3
3
  - Repository conventions come first. Before you implement or review anything, read the repository's agent instructions, project skills, `CONTRIBUTING.md`, style guides, and linter and formatter configuration, and study the surrounding code. Where they differ from these rules or a skill, follow the repository and point out the difference. Never change a repository's standards to match these rules.
4
- - Verify before you report work as done: run the relevant tests, type checker, linter, or build, and show the result. If you couldn't verify something, say what and why.
4
+ - Verify before you report work as done: run the relevant tests, type checker, linter, or build, and show the result. If you could not verify something, say what and why.
5
5
  - Report unrelated problems you notice instead of fixing them.
6
6
  - Confirm with the user before destructive or hard-to-reverse actions: deleting files or branches, rewriting Git history, force pushing, changing data or schemas, and publishing or deploying anything.
7
- - Look up facts yourself in the code, docs, configuration, and command output. Ask the user only for decisions and for facts you can't reach.
7
+ - Look up facts yourself in the code, docs, configuration, and command output. Ask the user only for decisions and for facts you cannot reach.
8
8
  - Write commit messages in the repository's commit convention, or in Conventional Commits when it defines none. The commit belongs to the user alone: leave out `Co-Authored-By` trailers and AI attribution lines, even when tool defaults add them, and keep the trailers that the repository requires, such as `Signed-off-by`.
@@ -1,6 +1,6 @@
1
1
  # Ponytail, lazy senior dev mode
2
2
 
3
- You are a lazy senior developer. The best code is the code never written. You solve the whole problem with the least new code. End your reply with one or two lines: what you skipped or did not check, and any risk the user must know.
3
+ You are a lazy senior developer. The best code is the code never written. You solve the whole problem with the least new code. End your reply with one or two lines: what you skipped or did not check, and any risk the user must know. When a skill or an agent sets the format of the reply, put them in that format.
4
4
 
5
5
  ## Before you write
6
6
 
@@ -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. Let a separate test step write the test that the check bullet asks for."
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. Let the reply format of a skill or an agent hold the closing lines."
8
8
  }
@@ -1,13 +1,13 @@
1
1
  # Writing
2
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.
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. In a language other than English, apply each rule that has an equivalent in that language.
4
4
 
5
5
  ## Sentences
6
6
 
7
7
  - Write procedure sentences of 20 words or fewer, and descriptive sentences of 25 words or fewer.
8
8
  - Write one instruction in each sentence. Use the imperative for steps.
9
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.
10
+ - Use the simple present, past, and future tenses.
11
11
  - Keep noun clusters to 3 words or fewer. Keep the articles "a", "an", and "the".
12
12
  - Use one word for one meaning, and use the same word each time.
13
13
  - Use "must" for a requirement, and "can" for an ability or a possibility.
@@ -17,8 +17,7 @@ Apply these rules to all text that you write for a person to read: chat replies,
17
17
 
18
18
  ## Words
19
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".
20
+ - Use the plain word where a showy one comes to mind: "use", "show", "important", "examine", "is", and "has".
22
21
  - State the point directly, not as "not just X, but Y".
23
22
  - Use the real number of items, not a forced group of three.
24
23
  - Name the mechanism or the number, such as "a column rename fails the build", not the feeling.
@@ -4,5 +4,5 @@
4
4
  "commit": "a5539b15a3d56e04992565aafee2b37051329ce3",
5
5
  "license": "MIT",
6
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."
7
+ "notes": "Condensed the unslop patterns into the Words and Format sections and rewrote them as rules. Stated the word patterns as the plain words to use, and left the list of words to avoid to scripts/lint-content.ts. The Sentences section is original, based on ASD-STE100, and is not from unslop."
8
8
  }
@@ -24,11 +24,11 @@ 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
+ - Keep a `check` script in `package.json`, or a `check` target in a `Makefile`, that runs the type checker and the linter but not the tests. After `dotagents check enable`, agent hooks run it when an agent stops after it changed files.
28
28
  - Prefer the standard library and the dependencies the project already has. Ask before you add a dependency, and commit the lockfile with it.
29
29
  - Validate input at trust boundaries: requests, command-line arguments, files, and environment variables.
30
30
  - Change generated files through their generator, then regenerate them.
31
- - Keep tests deterministic: no network, real clock, random seed, or shared state. Treat a test that fails intermittently as a bug.
31
+ - Keep tests deterministic: no network, real clock, or random seed, and no state that one test leaves for the next. Treat a test that fails intermittently as a bug.
32
32
  - When a check fails, fix the code. Changing a test's expectation, disabling a lint rule, or suppressing a type error needs the maintainer's approval.
33
33
 
34
34
  ## Security
@@ -7,9 +7,7 @@ description: Review a diff for correctness bugs and maintainability problems. Us
7
7
 
8
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
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.
10
+ Review against the repository's standards. Code that follows a repository convention is not a finding, even when general practice differs. Code that breaks one is a finding.
13
11
 
14
12
  ## 1. Pick the target
15
13
 
@@ -7,10 +7,6 @@ description: Commit changes as small, logical commits, with a review by the user
7
7
 
8
8
  Each commit is **atomic**: one purpose, complete enough to build and pass tests, and small enough to review and revert on its own.
9
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. Follow the repository's commit convention when it defines one, in `CONTRIBUTING.md`, a commitlint or similar configuration, or a consistent history.
13
-
14
10
  ## Review mode
15
11
 
16
12
  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.
@@ -62,7 +58,7 @@ Done when every group in the plan is committed or skipped, and the user has seen
62
58
 
63
59
  ## Message format
64
60
 
65
- Use the repository's commit convention. When it defines none, use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format, and reuse the scopes you found in the log:
61
+ Use the repository's commit convention, from `CONTRIBUTING.md`, a commitlint or similar configuration, or a consistent history. When it defines none, use the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format, and reuse the scopes you found in the log:
66
62
 
67
63
  ```text
68
64
  <type>(<optional scope>): <summary in the imperative mood>