@igorlau/dotagents 1.0.15 → 1.0.16

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 (42) hide show
  1. package/README.md +23 -25
  2. package/THIRD_PARTY_NOTICES.md +1 -1
  3. package/dist/build-info.json +1 -1
  4. package/package.json +2 -1
  5. package/plugin/.claude-plugin/plugin.json +1 -1
  6. package/plugin/agents/dot-implementer.md +4 -17
  7. package/plugin/agents/dot-tester.md +5 -13
  8. package/plugin/hooks/check.mjs +37 -11
  9. package/plugin/hooks/hooks.json +30 -0
  10. package/plugin/hooks/rules.mjs +27 -0
  11. package/plugin/rules/code-style.md +1 -1
  12. package/plugin/rules/core.md +2 -2
  13. package/plugin/rules/ponytail.md +1 -1
  14. package/plugin/rules/ponytail.upstream.json +1 -1
  15. package/plugin/rules/writing.md +3 -4
  16. package/plugin/rules/writing.upstream.json +1 -1
  17. package/plugin/scaffold/AGENTS.md.tmpl +2 -2
  18. package/plugin/skills/dot-code-review/SKILL.md +1 -3
  19. package/plugin/skills/dot-commit/SKILL.md +1 -5
  20. package/plugin/skills/dot-correct/SKILL.md +1 -3
  21. package/plugin/skills/dot-debug/SKILL.md +4 -6
  22. package/plugin/skills/dot-debug/UPSTREAM.json +1 -1
  23. package/plugin/skills/dot-docs-writing/SKILL.md +1 -3
  24. package/plugin/skills/dot-flow/SKILL.md +27 -29
  25. package/plugin/skills/dot-flow/references/inline.md +5 -38
  26. package/plugin/skills/dot-grilling/SKILL.md +1 -3
  27. package/plugin/skills/dot-grilling/UPSTREAM.json +1 -1
  28. package/plugin/skills/dot-handoff/SKILL.md +1 -3
  29. package/plugin/skills/dot-handoff/UPSTREAM.json +1 -1
  30. package/plugin/skills/dot-implement/SKILL.md +10 -7
  31. package/plugin/skills/dot-plan/SKILL.md +3 -7
  32. package/plugin/skills/dot-plan/references/entity-schemas.md +3 -3
  33. package/plugin/skills/dot-roadmap/SKILL.md +4 -8
  34. package/plugin/skills/dot-roadmap/agents/openai.yaml +5 -0
  35. package/plugin/skills/dot-testing/SKILL.md +2 -5
  36. package/plugin/skills/dot-testing/references/after-implement.md +23 -0
  37. package/plugin/skills/dot-writing-for-agents/SKILL.md +1 -3
  38. package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +1 -1
  39. package/plugin/skills/dot-grill-me/SKILL.md +0 -11
  40. package/plugin/skills/dot-grill-me/UPSTREAM.json +0 -8
  41. package/plugin/skills/dot-grill-me/agents/openai.yaml +0 -5
  42. package/plugin/skills/dot-testing/references/modes.md +0 -32
package/README.md CHANGED
@@ -1,12 +1,12 @@
1
1
  # dotagents
2
2
 
3
3
  dotagents gives Claude Code, OpenAI Codex, and GitHub Copilot one AI workflow
4
- for every project. The workflow plans a change, writes tests and code in small
5
- steps, reviews the result, and asks for your approval between the steps.
4
+ for every project. The workflow plans a change, writes code and tests in small
5
+ steps, verifies each step, reviews the result, and asks for your decision.
6
6
 
7
7
  dotagents has two parts:
8
8
 
9
- - A plugin with skills, agents, and an end-of-turn hook. Claude Code, the
9
+ - A plugin with skills, agents, and hooks. Claude Code, the
10
10
  Copilot CLI, and VS Code load the plugin.
11
11
  - A CLI that installs the always-on rules for all three coding agents, and the
12
12
  skills for Codex and Copilot.
@@ -86,14 +86,14 @@ Run `scaffold` before `init`. `init` adds a block to `AGENTS.md`, and
86
86
  ## The flow
87
87
 
88
88
  The following diagram shows the full flow, from an idea to the commits of one
89
- task. The agent stops for your approval at each "approve" or "go":
89
+ task. The agent stops for your decision at each "approve", "fix", or "accept":
90
90
 
91
91
  ```mermaid
92
92
  sequenceDiagram
93
93
  actor User
94
94
  participant Main as Main session
95
95
  participant Agents as Step agents
96
- User->>Main: dot-grill-me with an idea
96
+ User->>Main: dot-grilling with an idea
97
97
  Main-->>User: Questions in rounds, with recommended answers
98
98
  User->>Main: Answers until the plan is clear
99
99
  User->>Main: dot-plan
@@ -106,24 +106,23 @@ sequenceDiagram
106
106
  User->>Main: Approve the roadmap
107
107
  loop Each task
108
108
  User->>Main: dot-flow with the task file
109
- Main->>Agents: 1. Test stubs (dot-tester)
109
+ Main->>Agents: 1. Production code (dot-implementer)
110
110
  Agents-->>Main: Reply
111
- Main-->>User: Summary
112
- User->>Main: go
113
- Main->>Agents: 2. Production code (dot-implementer)
111
+ Main->>Main: Run the checks of the reply
112
+ Main->>Agents: 2. Tests (dot-tester)
114
113
  Agents-->>Main: Reply
115
- Main-->>User: Summary
116
- User->>Main: go
117
- Main->>Agents: 3. Test fill (dot-tester)
118
- Agents-->>Main: Reply
119
- Main-->>User: Summary
120
- User->>Main: go
121
- Main->>Agents: 4. Review (dot-reviewer)
114
+ Main->>Main: Run the tests of the reply
115
+ Main->>Agents: 3. Review (dot-reviewer)
122
116
  Agents-->>Main: Findings
123
117
  Main-->>User: Findings
124
- break A blocker or a high finding
118
+ break A blocker, or a check that differs from the reply
125
119
  Main-->>User: Stop. The files stay as they are.
126
120
  end
121
+ opt Fix
122
+ User->>Main: Fix these findings
123
+ Main->>Agents: Steps 1 to 3 again
124
+ end
125
+ User->>Main: Accept
127
126
  User->>Main: dot-commit
128
127
  Main-->>User: Each commit for approval
129
128
  User->>Main: Approve
@@ -131,8 +130,8 @@ sequenceDiagram
131
130
  end
132
131
  ```
133
132
 
134
- `dot-flow` never commits. In Codex and Copilot, `dot-flow` runs the four steps
135
- in the main session, with the same approvals.
133
+ `dot-flow` never commits. In Codex and Copilot, `dot-flow` runs the three steps
134
+ in the main session, with the same verification and stops.
136
135
 
137
136
  To learn the workflow step by step, read the [guide](docs/guide/README.md).
138
137
 
@@ -163,17 +162,16 @@ agreements, the smallest complete change from
163
162
  [ponytail](https://github.com/DietrichGebert/ponytail), code comments, code
164
163
  style, and writing.
165
164
 
166
- The 15 skills in [`plugin/skills/`](plugin/skills/) load when a task needs
165
+ The 14 skills in [`plugin/skills/`](plugin/skills/) load when a task needs
167
166
  them:
168
167
 
169
168
  | Skill | Purpose |
170
169
  | ----- | ------- |
171
- | `dot-grill-me` | Start an interview that makes a plan clear. |
172
- | `dot-grilling` | Run the interview method of `dot-grill-me`. |
170
+ | `dot-grilling` | Run an interview, in rounds of questions, that makes a plan clear. |
173
171
  | `dot-plan` | Plan a change as small, verifiable steps, with entity schemas. |
174
172
  | `dot-roadmap` | Split a plan into phases and tasks that each stand alone. |
175
- | `dot-flow` | Take a roadmap task through test stubs, code, test fill, and review, with an approval after each step. |
176
- | `dot-testing` | Write tests with a makeSut factory, as stubs before the code or in full after it. |
173
+ | `dot-flow` | Take a roadmap task through code, tests, and review, verify each step, and stop for your decision after the review. |
174
+ | `dot-testing` | Write tests with a makeSut factory, alone or after `dot-implement`. |
177
175
  | `dot-implement` | Write the code of a change or roadmap task to the standards of the repository and the language. |
178
176
  | `dot-code-review` | Review a diff for correctness bugs and maintainability problems. |
179
177
  | `dot-comments` | Delete the comments in a diff that no exception protects. |
@@ -190,7 +188,7 @@ context:
190
188
 
191
189
  | Agent | Purpose |
192
190
  | ----- | ------- |
193
- | `dot-tester` | Write the test stubs, or fill them after the code exists. |
191
+ | `dot-tester` | Write the tests of a task after the code exists. |
194
192
  | `dot-implementer` | Write the production code of a task. |
195
193
  | `dot-reviewer` | Review the changes of a task. |
196
194
 
@@ -4,7 +4,7 @@ dotagents includes content from the following projects.
4
4
 
5
5
  ## mattpocock/skills
6
6
 
7
- The `dot-debug`, `dot-grill-me`, `dot-grilling`, `dot-handoff`, and `dot-writing-for-agents`
7
+ The `dot-debug`, `dot-grilling`, `dot-handoff`, and `dot-writing-for-agents`
8
8
  skills come from [mattpocock/skills](https://github.com/mattpocock/skills).
9
9
  Each skill's `UPSTREAM.json` file records the source commit and any local
10
10
  changes. The project is licensed under the MIT License:
@@ -1 +1 @@
1
- {"commit":"0b97ba2"}
1
+ {"commit":"6e38c12"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@igorlau/dotagents",
3
- "version": "1.0.15",
3
+ "version": "1.0.16",
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,6 +27,7 @@
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"
@@ -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.
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.
@@ -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>
@@ -8,9 +8,7 @@ disable-model-invocation: true
8
8
 
9
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
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.
11
+ Use the type checker, linter, and test framework that the repository already has.
14
12
 
15
13
  ## 1. Name the mistake class
16
14
 
@@ -1,17 +1,15 @@
1
1
  ---
2
2
  name: dot-debug
3
- description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose" or "debug this", or reports that something is broken, throws, fails, or is slow.
3
+ description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose" or "debug this", or when the error does not show the cause of a failure or a slowdown.
4
4
  ---
5
5
 
6
6
  # Diagnose bugs
7
7
 
8
- Use this method for hard bugs. Skip a phase only when you can state the reason.
8
+ Use this method for hard bugs. When the error message already shows the cause, fix the bug directly. Skip a phase only when you can state the reason.
9
9
 
10
10
  To learn the modules in the area, read `GLOSSARY.md` if it exists, and read the ADRs for the area that you change.
11
11
 
12
- ## Repository conventions first
13
-
14
- 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. Build the feedback loop with the test framework, scripts, and tools of the repository.
12
+ Build the feedback loop with the test framework, scripts, and tools of the repository.
15
13
 
16
14
  ## Redact
17
15
 
@@ -104,7 +102,7 @@ Write the regression test **before the fix**, but only if a **correct seam** exi
104
102
 
105
103
  A correct seam is one where the test runs the **real bug pattern** as it occurs at the call site. Sometimes the only seam is too shallow: a test with one caller when the bug needs several callers, or a unit test that cannot repeat the chain that triggered the bug. A regression test there gives false confidence.
106
104
 
107
- **If no correct seam exists, that is the finding.** Note it. The architecture of the codebase prevents a test that locks the bug down. Flag it for the next phase.
105
+ **If no correct seam exists, that is the finding.** Note it. The architecture of the codebase prevents a test that locks the bug down. Report it to the user at the end.
108
106
 
109
107
  If a correct seam exists:
110
108
 
@@ -4,5 +4,5 @@
4
4
  "commit": "49dd158d1076134a641b33efb035946536778336",
5
5
  "license": "MIT",
6
6
  "modified": true,
7
- "notes": "Renamed from diagnosing-bugs to debug (frontmatter name and display_name). Added a 'Repository conventions first' section. Renamed with the dot- prefix. Added the root cause and premise rules to Phase 5, condensed from pstack/skills/principle-fix-root-causes and pstack/skills/principle-attack-the-premise in https://github.com/cursor/plugins at commit a5539b15a3d56e04992565aafee2b37051329ce3 (MIT). Rewrote the text under plugin/rules/writing.md. Moved the ways to build a loop, the bugs that are not deterministic, and the case with no loop to references/loops.md."
7
+ "notes": "Renamed from diagnosing-bugs to debug (frontmatter name and display_name). Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Added the root cause and premise rules to Phase 5, condensed from pstack/skills/principle-fix-root-causes and pstack/skills/principle-attack-the-premise in https://github.com/cursor/plugins at commit a5539b15a3d56e04992565aafee2b37051329ce3 (MIT). Rewrote the text under plugin/rules/writing.md. Moved the ways to build a loop, the bugs that are not deterministic, and the case with no loop to references/loops.md."
8
8
  }
@@ -7,9 +7,7 @@ description: Write and edit developer documentation in the Google developer docu
7
7
 
8
8
  Write documentation that a developer in a hurry, who reads in their second language, can follow on the first pass. This skill covers the frame, structure, and format of a document, based on the Google developer documentation style guide. The always-on writing rule governs the prose, and it wins any conflict with this skill.
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. This includes the project's documentation style guide, prose linter configuration such as Vale, and the structure and terms of its current docs.
10
+ Follow the project's documentation style guide, its prose linter configuration such as Vale, and the structure and terms of its current docs. They win a conflict with this skill.
13
11
 
14
12
  ## 1. Frame the document
15
13
 
@@ -1,16 +1,12 @@
1
1
  ---
2
2
  name: dot-flow
3
- description: Take one roadmap task through test stubs, implementation, test fill, and review, with your approval after each step.
3
+ description: Take one roadmap task through implementation, tests, and review, and stop for your decision after the review.
4
4
  disable-model-invocation: true
5
5
  ---
6
6
 
7
7
  # Flow
8
8
 
9
- Take one task from a `dot-roadmap` roadmap through four steps: test stubs, implementation, test fill, and review. Each step runs in a fresh agent with one skill, and the user approves its result before the next step starts. You coordinate the steps. The agents write the tests, the code, and the review.
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.
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 after the review.
14
10
 
15
11
  ## 1. Pin the task
16
12
 
@@ -22,54 +18,56 @@ Done when you can name the task file and its goal.
22
18
 
23
19
  ## 2. Pick the runner
24
20
 
25
- Use the agents of the dotagents plugin when the `Agent` tool can start them: `dotagents:dot-tester`, `dotagents:dot-implementer`, 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 approvals.
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.
26
22
 
27
- ## 3. Run the steps
23
+ ## 3. Run and verify the steps
28
24
 
29
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:
30
26
 
31
27
  | Step | Agent | Prompt fields |
32
28
  | ---- | ----- | ------------- |
33
- | 1. Stub | `dotagents:dot-tester` | Task, Mode `stub` |
34
- | 2. Implement | `dotagents:dot-implementer` | Task, Handoff: the reply of step 1 |
35
- | 3. Fill | `dotagents:dot-tester` | Task, Mode `fill`, Handoff: the reply of step 2 |
36
- | 4. Review | `dotagents:dot-reviewer` | Task, Handoff: the replies of steps 1 to 3 |
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 |
37
32
 
38
33
  Write the prompt as labeled fields, and leave out a field that the step does not take:
39
34
 
40
35
  ```markdown
41
36
  **Task:** <path of the task file>
42
- **Mode:** <stub | fill>
43
37
  **Handoff:**
44
38
  <the replies of the earlier steps, unchanged>
45
39
  ```
46
40
 
47
- Copy the replies unchanged, because the agents read their fields. Keep the main context small: do not read the changed files or the full test output yourself. The replies carry what the user needs.
41
+ Copy the replies unchanged, because the agents read their fields.
48
42
 
49
- ## 4. Approve each step
43
+ 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:
50
44
 
51
- After each step, show the user this summary, then wait:
45
+ - The type checker and the linter pass.
46
+ - After step 1, each test that fails is in "Expected failures".
47
+ - After step 2, the test command passes.
48
+ - The reply has no blockers.
52
49
 
53
- ```markdown
54
- **Step <n> of 4: <step name>**
55
- <the Summary line of the reply>
56
- <the Checks or Tests line of the reply>
57
- **Blockers:** <the Blockers line of the reply>
58
- ```
50
+ 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.
51
+
52
+ Stop the flow, keep the files as they are, and ask the user how to continue in these cases:
53
+
54
+ - A reply has blockers. Show them.
55
+ - A step is not verified. Show the command, your result line, and the line of the reply.
56
+ - 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.
59
57
 
60
- For the review step, show the **Highest severity** line and one line for each finding: its severity, summary, and `file:line`.
58
+ Done when the review reply arrived, or the flow stopped.
61
59
 
62
- Start the next step only when the user says "go" or approves in other words. When the user asks for a change, run the same step again in a new agent, and add the request to the prompt.
60
+ ## 4. Decide after the review
63
61
 
64
- Stop the flow, and keep the files as they are, in these cases:
62
+ Show the user the **Highest severity** line and one line for each finding: its severity, summary, and `file:line`. 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:
65
63
 
66
- - A reply has blockers. Show them, and ask the user how to continue.
67
- - The review reports a `high` finding. The presumed blockers of the maintainability pass are `high`. Show each `high` finding with its **Fix** line. When the user fixes the findings and asks for a new review, run step 4 again.
64
+ - **Fix**: the user names the findings to fix. Run step 1 again in a new agent, with the findings as a **Findings** field, then run steps 2 and 3 again.
65
+ - **Accept**: the user accepts the findings that remain.
68
66
 
69
- Done when the user approved the review step, or the flow stopped.
67
+ Done when the user accepts.
70
68
 
71
69
  ## 5. Finish
72
70
 
73
- List the files that the steps changed, from the **Files** lines of the replies. The user decides about the `medium` and `low` findings. Suggest the `dot-commit` skill.
71
+ 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.
74
72
 
75
73
  Do not commit, and do not tick the roadmap checkbox: `dot-commit` ticks it when the commits finish the task.
@@ -1,42 +1,9 @@
1
1
  # Inline mode
2
2
 
3
- Inline steps for the [`dot-flow`](../SKILL.md) skill, for an agent that cannot start the dotagents agents, such as Codex or Copilot. The steps, the approvals, and the stop cases of `SKILL.md` stay the same. You run each step yourself, in this conversation, instead of in an agent.
3
+ Inline steps for the [`dot-flow`](../SKILL.md) skill, for an agent that cannot start the dotagents agents, such as Codex or Copilot. The verification, the stops, and the decision after the review stay as `SKILL.md` gives them. You run each step yourself, in this conversation, instead of in an agent.
4
4
 
5
- ## Steps
5
+ 1. Implement: use the `dot-implement` skill for the task, and end the step with its handoff. Write no tests in this step.
6
+ 2. Test: use the `dot-testing` skill with its `references/after-implement.md` and the handoff of step 1, and end the step with the reply that the reference gives.
7
+ 3. Review: use the `dot-code-review` skill for the task. The target is `git diff HEAD`, plus the untracked files that `git status --short` lists. Start the report with the line `**Highest severity:** <high | medium | low | none>`. Report the findings, and keep the code as it is. Delete each test that you write to prove a finding.
6
8
 
7
- 1. Stub: use the `dot-testing` skill in stub mode for the task.
8
- 2. Implement: use the `dot-implement` skill for the task, with the reply of step 1.
9
- 3. Fill: use the `dot-testing` skill in fill mode for the task, with the reply of step 2.
10
- 4. Review: use the `dot-code-review` skill for the task. The target is `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.
11
-
12
- Do only the work of the current step, even when the next step looks small. The steps share one context, so read only what the current step needs.
13
-
14
- ## Replies
15
-
16
- End each step with its reply, then show the summary of `SKILL.md` step 4. Keep each summary to 3 sentences or fewer.
17
-
18
- Steps 1 and 3:
19
-
20
- ```markdown
21
- **Summary:** <what you did>
22
- **Tests:** <the test command and its result line>
23
- **Files:** <the test files that you changed>
24
- **Blockers:** <what stops the next step, or "none">
25
- ```
26
-
27
- Step 2, with the handoff fields from step 5 of `dot-implement`:
28
-
29
- ```markdown
30
- **Summary:** <what you did>
31
- **Checks:** <the type checker, linter, and test commands, with their result lines>
32
- **Files:** <the production files that you changed>
33
- **Blockers:** <what stops the next step, or "none">
34
-
35
- **Expected failures:**
36
- - `<test file>`: <test name>: <the new behavior that the test must assert>
37
-
38
- **Behaviors that need tests:**
39
- - `<module>`: <a behavior that the change adds or changes, and that no test case covers>
40
- ```
41
-
42
- Step 4: start with the line `**Highest severity:** <high | medium | low | none>`, then give the report of `dot-code-review`.
9
+ Do only the work of the current step, even when the next step looks small. After steps 1 and 2, run the commands of the reply again before you start the next step: the verification of `SKILL.md` applies to your own replies too. The steps share one context, so read only what the current step needs.
@@ -29,6 +29,4 @@ Facts are your job, never the user's. When a frontier question needs a fact from
29
29
 
30
30
  The session is done when the frontier is empty: you visited every branch of the design tree, and you assumed nothing in silence. Do not act on the result until the user confirms that you reached a shared understanding.
31
31
 
32
- ## Repository conventions first
33
-
34
- 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. Base your recommended answers on those conventions.
32
+ Base your recommended answers on the conventions of the repository.
@@ -4,5 +4,5 @@
4
4
  "commit": "49dd158d1076134a641b33efb035946536778336",
5
5
  "license": "MIT",
6
6
  "modified": true,
7
- "notes": "Added a 'Repository conventions first' section. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md, and replaced the emoji in the round format with text labels."
7
+ "notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md, and replaced the emoji in the round format with text labels."
8
8
  }
@@ -15,6 +15,4 @@ Redact all sensitive information, such as API keys, passwords, and personally id
15
15
 
16
16
  If the user passed arguments, they describe the focus of the next session. Write the document for that focus.
17
17
 
18
- ## Repository conventions first
19
-
20
- 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. List the repository conventions that the next agent must follow, by path.
18
+ List the repository conventions that the next agent must follow, by path.
@@ -4,5 +4,5 @@
4
4
  "commit": "49dd158d1076134a641b33efb035946536778336",
5
5
  "license": "MIT",
6
6
  "modified": true,
7
- "notes": "Added a 'Repository conventions first' section. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md."
7
+ "notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md."
8
8
  }
@@ -7,10 +7,6 @@ description: Implement a feature, fix, refactor, or roadmap task to the reposito
7
7
 
8
8
  Turn a request, an approved plan, or a roadmap task into a production code change that ends **green**: the type checker and the linter pass, no current test fails by accident, and you have shown the output. Write no tests: a separate test step writes them.
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. Write code that fits those conventions.
13
-
14
10
  ## 1. Pin the work
15
11
 
16
12
  Identify the source of the work:
@@ -23,7 +19,7 @@ Done when you can state the goal, the scope boundary, and the check that proves
23
19
 
24
20
  ## 2. Plan when needed
25
21
 
26
- A roadmap task or an approved plan is already the plan. For a request that touches more than one file, use the `dot-plan` skill and wait for the user's approval before you change any file. A single-file change goes straight to step 3.
22
+ A roadmap task or an approved plan is already the plan. For a request that spans several modules, or that has more than one reasonable design, use the `dot-plan` skill and wait for the user's approval before you change any file. Any other request goes straight to step 3.
27
23
 
28
24
  ## 3. Build
29
25
 
@@ -52,9 +48,14 @@ Done when the hard checks pass and no unexpected failure remains.
52
48
 
53
49
  ## 5. Hand off
54
50
 
55
- End with the verification output, anything that you skipped or could not check, and these fields for the fill mode of the `dot-testing` skill:
51
+ End with this handoff. The `dot-testing` skill reads its last two fields:
56
52
 
57
53
  ```markdown
54
+ **Summary:** <what you did, in 3 sentences or fewer>
55
+ **Checks:** <the type checker, linter, and test commands, each with its result line>
56
+ **Files:** <the production files that you changed>
57
+ **Blockers:** <what stops the test step, and what you skipped or could not check, or "none">
58
+
58
59
  **Expected failures:**
59
60
  - `<test file>`: <test name>: <the new behavior that the test must assert>
60
61
 
@@ -62,4 +63,6 @@ End with the verification output, anything that you skipped or could not check,
62
63
  - `<module>`: <a behavior that the change adds or changes, and that no test case covers>
63
64
  ```
64
65
 
65
- Write "none" under a field that has no items. Suggest `dot-testing` in fill mode, then the `dot-code-review` skill, then the `dot-commit` skill. Leave the commit to the user.
66
+ Write "none" under a field that has no items.
67
+
68
+ When `dot-flow` or an agent prompt gave you only the implementation step, stop after the handoff. Otherwise, use the `dot-testing` skill with this handoff now, then suggest the `dot-code-review` skill and the `dot-commit` skill. Leave the commit to the user.
@@ -1,16 +1,12 @@
1
1
  ---
2
2
  name: dot-plan
3
- description: Plan a change as small, verifiable steps before writing code. Use when the user asks for a plan, or before a feature, refactor, or migration that touches more than one file.
3
+ description: Plan a change as small, verifiable steps before writing code. Use when the user asks for a plan, or before a change that spans several modules or has more than one reasonable design.
4
4
  ---
5
5
 
6
6
  # Plan
7
7
 
8
8
  A plan turns a request into a sequence of **vertical slices**: each slice is a small change that leaves the system in a state that works and ends on a check you can run.
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. Plan changes that fit those conventions.
13
-
14
10
  ## 1. Pin the goal
15
11
 
16
12
  Restate the goal in one or two sentences, and name the **done criterion**: the observable result that tells the user the work is finished (a test that passes, a command's output, a behavior in the UI).
@@ -31,7 +27,7 @@ If the list is long or the decisions depend on each other, use the `dot-grilling
31
27
 
32
28
  ## 4. Show entity schemas
33
29
 
34
- When the change adds or changes a domain entity, read [`references/entity-schemas.md`](references/entity-schemas.md). Show a full JSON Schema for each new entity, and a before and after diff for each changed entity. Wait for the user to approve the schemas before you slice the work.
30
+ When the change adds or changes a domain entity, read [`references/entity-schemas.md`](references/entity-schemas.md). Show the full schema of each new entity, and a before and after diff of each changed entity. Wait for the user to approve the schemas before you slice the work.
35
31
 
36
32
  Done when the user approves each schema, or the change touches no domain entity.
37
33
 
@@ -55,7 +51,7 @@ Show the plan in this shape:
55
51
  **Done when:** <done criterion>
56
52
  **Schemas:** <the approved entity schemas, or none>
57
53
 
58
- 1. <change> → check: <command or observation>
54
+ 1. <change>. Check: <command or observation>
59
55
  2. ...
60
56
 
61
57
  **Open questions:** <none, or the list>
@@ -4,7 +4,7 @@ Schema details for the [`dot-plan`](../SKILL.md) skill. A domain entity is a thi
4
4
 
5
5
  ## Format
6
6
 
7
- Write each schema in JSON Schema draft 2020-12, in a `json` block. Give it `$schema`, `$id`, `title`, `type`, `required`, and `properties`.
7
+ Write each schema in the form that the repository already uses for its entities, such as a TypeScript type, a Zod schema, or SQL DDL, so the approved schema is the code that lands. When the repository has no such form, use JSON Schema draft 2020-12 in a `json` block, with `$schema`, `$id`, `title`, `type`, `required`, and `properties`.
8
8
 
9
9
  - For a new entity, show the full schema.
10
10
  - For a changed entity, show a `diff` block of the schema before and after the change.
@@ -13,13 +13,13 @@ Put the schemas in the plan. Do not commit schema files to the target repository
13
13
 
14
14
  ## Model the domain
15
15
 
16
- Make the illegal states impossible to write in the schema:
16
+ Make the illegal states impossible to write in the schema. In JSON Schema:
17
17
 
18
18
  - Model a lifecycle as one `status` field with an `enum`, not as booleans that must agree, such as `isPaid` and `isShipped`.
19
19
  - Model variants with a `kind` field and `oneOf`, not as one object with optional fields for each variant.
20
20
  - Use `minItems: 1` for a list that must have an item.
21
21
 
22
- ## Example: a new entity
22
+ ## Example: a new entity in JSON Schema
23
23
 
24
24
  ```json
25
25
  {
@@ -9,15 +9,11 @@ disable-model-invocation: true
9
9
 
10
10
  A roadmap splits a plan into **phases**, and each phase into **tasks**. A phase ends on a **milestone**: an observable state where the system works and could ship. A task is **self-contained**: a fresh agent session can build it from its file alone, and a reviewer can judge its diff in one session.
11
11
 
12
- ## Repository conventions first
13
-
14
- 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. Write tasks whose changes fit those conventions.
15
-
16
12
  ## 1. Load the plan
17
13
 
18
- Work from the plan in this conversation, usually the shared understanding a `dot-grill-me` session reached. If the user passed a path or URL, read it in full.
14
+ Work from the plan in this conversation, usually the shared understanding a `dot-grilling` session reached. If the user passed a path or URL, read it in full.
19
15
 
20
- Synthesize the plan. Do not interview the user. If the plan still has unsettled decisions, list them and suggest `dot-grill-me` before you go on. Done when you can state the **destination** (what is true when the whole roadmap is done) and every decision the plan made.
16
+ Synthesize the plan. Do not interview the user. If the plan still has unsettled decisions, list them and suggest `dot-grilling` before you go on. Done when you can state the **destination** (what is true when the whole roadmap is done) and every decision the plan made.
21
17
 
22
18
  ## 2. Gather facts
23
19
 
@@ -41,7 +37,7 @@ Split each phase into tasks. Each task:
41
37
  - Is a **vertical slice**: a narrow but complete path through every layer it needs, verifiable on its own.
42
38
  - Keeps a refactor separate from a behavior change.
43
39
  - Fits one fresh agent session and one reviewable diff, roughly a few hundred changed lines.
44
- - Lists its **test cases**: the test names, each with the test file where it belongs, in the order and with the names that the `dot-testing` skill gives. For controller, integration, and end-to-end tests, use the HTTP reference of `dot-testing`. `dot-testing` writes them as pending tests before the code. Write "none" when the task changes no tested behavior.
40
+ - Lists its **test cases**: the test names, each with the test file where it belongs, in the order and with the names that the `dot-testing` skill gives. For controller, integration, and end-to-end tests, use `references/http.md` of `dot-testing`. `dot-testing` writes them after `dot-implement`. Write "none" when the task changes no tested behavior.
45
41
  - Declares its **blockers**: the tasks that must be done first, by id (`2.3` is phase 2, task 3). A task without blockers can start now.
46
42
 
47
43
  When one mechanical change breaks many call sites at once, read [`references/wide-refactor.md`](references/wide-refactor.md).
@@ -82,7 +78,7 @@ Write to `.tmp/roadmaps/<roadmap-slug>/` at the repository root. First run `git
82
78
  ## Decisions
83
79
 
84
80
  - <decision from the plan, one line each, with the reason when it is not obvious>
85
- - <approved entity schema, as a JSON Schema block, when the plan has one>
81
+ - <approved entity schema, as a code block, when the plan has one>
86
82
 
87
83
  ## Out of scope
88
84
 
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: "Roadmap"
3
+ short_description: "Split a plan into phases and self-contained tasks"
4
+ policy:
5
+ allow_implicit_invocation: false
@@ -7,9 +7,7 @@ description: Write and change tests with a makeSut factory per suite. Use when y
7
7
 
8
8
  Write tests that build the **system under test** (`sut`) in one factory, share it across the suite, and stay isolated: reset the test doubles between tests.
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. When the repository already sets up tests another way, such as pytest fixtures or its own setup helper, use that and leave out `makeSut`.
10
+ When the repository already sets up tests another way, such as pytest fixtures or its own setup helper, use that and leave out `makeSut`.
13
11
 
14
12
  ## The makeSut factory
15
13
 
@@ -26,7 +24,6 @@ Use `makeSut` when the subject needs setup: construction, configuration, depende
26
24
  2. In a test, change a dependency's behavior with a spy or a stub on the double that `makeSut` returned, for that test only.
27
25
  3. Restore every spy and stub in the hook that runs after each test, so the next test sees the happy-path doubles again.
28
26
 
29
-
30
27
  ## Test principles
31
28
 
32
29
  - Arrange, act, assert: one block each, in that order.
@@ -43,6 +40,6 @@ Read each reference that applies to the tests:
43
40
  - [`references/typescript.md`](references/typescript.md): read when the tests use TypeScript with Vitest, Jest, or `node:test`.
44
41
  - [`references/http.md`](references/http.md): read when you write controller, integration, or end-to-end tests.
45
42
  - [`references/shared-state.md`](references/shared-state.md): read when the `sut` keeps mutable state between calls, or when the tests run concurrently.
46
- - [`references/modes.md`](references/modes.md): read when you work a roadmap task, before `dot-implement` (stub mode) or after it (fill mode).
43
+ - [`references/after-implement.md`](references/after-implement.md): read when you write the tests of a change that `dot-implement` made, such as a roadmap task.
47
44
 
48
45
  Done when every test you wrote or changed passes with the repository's test command, and you have shown the output.
@@ -0,0 +1,23 @@
1
+ # Tests after dot-implement
2
+
3
+ Details for the [`dot-testing`](../SKILL.md) skill when it runs after `dot-implement`, with or without a roadmap task. `dot-implement` writes no tests. Use red-green TDD, where a test fails before the code exists, only when the user asks for it.
4
+
5
+ Read the handoff of `dot-implement`, with its "Expected failures" and "Behaviors that need tests" fields, and the diff of the change. When the change is a roadmap task, read its "Test cases" section.
6
+
7
+ 1. Write each test case of the task that is not a test yet, in the test file that the case names. Use the order and the names that the cases give.
8
+ 2. Change each test in "Expected failures" so that it asserts the new behavior.
9
+ 3. Add a test for each item in "Behaviors that need tests", in the test file of its module.
10
+ 4. Take each assertion from the task or the request, not from the code. When a test fails because the production code is wrong, stop and report the failure. Keep the production code as it is.
11
+
12
+ Done when each test case of the task is a test, and the test command of the repository passes, with its output shown.
13
+
14
+ ## Reply
15
+
16
+ End with this reply:
17
+
18
+ ```markdown
19
+ **Summary:** <what you did, in 3 sentences or fewer>
20
+ **Tests:** <the test command and its result line>
21
+ **Files:** <the test files that you changed>
22
+ **Blockers:** <what stops the review, or "none">
23
+ ```
@@ -11,9 +11,7 @@ Read each reference that applies:
11
11
  - [`references/steps.md`](references/steps.md): read when the document has steps, for the completion criterion of each step.
12
12
  - [`references/skill-mechanics.md`](references/skill-mechanics.md): read when the document is a skill, for the frontmatter, the invocation choice, and router skills.
13
13
 
14
- ## Repository conventions first
15
-
16
- 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. When you edit the `AGENTS.md`, `CLAUDE.md`, or skills of a repository, keep their structure, format, and conventions.
14
+ When you edit the `AGENTS.md`, `CLAUDE.md`, or skills of a repository, keep their structure, format, and conventions.
17
15
 
18
16
  ## Information hierarchy
19
17
 
@@ -4,5 +4,5 @@
4
4
  "commit": "49dd158d1076134a641b33efb035946536778336",
5
5
  "license": "MIT",
6
6
  "modified": true,
7
- "notes": "Added a 'Repository conventions first' section. Renamed with the dot- prefix. Rewrote the text under plugin/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."
7
+ "notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under plugin/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
8
  }
@@ -1,11 +0,0 @@
1
- ---
2
- name: dot-grill-me
3
- description: A relentless interview to sharpen a plan or design.
4
- disable-model-invocation: true
5
- ---
6
-
7
- Use the `dot-grilling` skill to interview the user about the plan or design that they describe.
8
-
9
- ## Repository conventions first
10
-
11
- 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. Base the recommendations of the interview on those conventions.
@@ -1,8 +0,0 @@
1
- {
2
- "repository": "https://github.com/mattpocock/skills",
3
- "path": "skills/productivity/grill-me",
4
- "commit": "49dd158d1076134a641b33efb035946536778336",
5
- "license": "MIT",
6
- "modified": true,
7
- "notes": "Replaced the Claude-specific 'Call the Skill tool' instruction with an agent-neutral one. Added a 'Repository conventions first' section. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md."
8
- }
@@ -1,5 +0,0 @@
1
- interface:
2
- display_name: "Grill Me"
3
- short_description: "Sharpen a plan through interview"
4
- policy:
5
- allow_implicit_invocation: false
@@ -1,32 +0,0 @@
1
- # Modes
2
-
3
- Mode details for the [`dot-testing`](../SKILL.md) skill. A roadmap task runs `dot-testing` twice: in stub mode before `dot-implement`, and in fill mode after it. Use red-green TDD, where a test fails before the code exists, only when the user asks for it.
4
-
5
- ## Stub mode
6
-
7
- Run stub mode before the code exists.
8
-
9
- 1. Read the "Test cases" section of the roadmap task.
10
- 2. Write each case as a pending test (`it.todo`, `test.todo`, or the equivalent of the runner) in the test file of the module that the case covers. Use the order and the names that the cases give.
11
- 3. Write no other test code: no `makeSut`, no doubles, and no assertions.
12
-
13
- Done when each case is a pending test, and the test command reports them as pending.
14
-
15
- ## Fill mode
16
-
17
- Run fill mode after `dot-implement`. Read the "Test cases" section of the roadmap task, the diff of the task, and the handoff of `dot-implement`. The handoff has these fields:
18
-
19
- ```markdown
20
- **Expected failures:**
21
- - `<test file>`: <test name>: <the new behavior that the test must assert>
22
-
23
- **Behaviors that need tests:**
24
- - `<module>`: <a behavior that the change adds or changes, and that no test case covers>
25
- ```
26
-
27
- 1. Turn each pending test of the task into a real test, by the rules in `SKILL.md`.
28
- 2. Change each test in "Expected failures" so that it asserts the new behavior.
29
- 3. Add a test for each item in "Behaviors that need tests", in the test file of its module.
30
- 4. When a test fails because the production code is wrong, stop and report the failure. Do not change the production code.
31
-
32
- Done when no pending test of the task remains, and the test command of the repository passes, with its output shown.