@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.
- package/README.md +23 -25
- package/THIRD_PARTY_NOTICES.md +1 -1
- package/dist/build-info.json +1 -1
- package/package.json +2 -1
- package/plugin/.claude-plugin/plugin.json +1 -1
- package/plugin/agents/dot-implementer.md +4 -17
- package/plugin/agents/dot-tester.md +5 -13
- package/plugin/hooks/check.mjs +37 -11
- package/plugin/hooks/hooks.json +30 -0
- package/plugin/hooks/rules.mjs +27 -0
- package/plugin/rules/code-style.md +1 -1
- package/plugin/rules/core.md +2 -2
- package/plugin/rules/ponytail.md +1 -1
- package/plugin/rules/ponytail.upstream.json +1 -1
- package/plugin/rules/writing.md +3 -4
- package/plugin/rules/writing.upstream.json +1 -1
- package/plugin/scaffold/AGENTS.md.tmpl +2 -2
- package/plugin/skills/dot-code-review/SKILL.md +1 -3
- package/plugin/skills/dot-commit/SKILL.md +1 -5
- package/plugin/skills/dot-correct/SKILL.md +1 -3
- package/plugin/skills/dot-debug/SKILL.md +4 -6
- package/plugin/skills/dot-debug/UPSTREAM.json +1 -1
- package/plugin/skills/dot-docs-writing/SKILL.md +1 -3
- package/plugin/skills/dot-flow/SKILL.md +27 -29
- package/plugin/skills/dot-flow/references/inline.md +5 -38
- package/plugin/skills/dot-grilling/SKILL.md +1 -3
- package/plugin/skills/dot-grilling/UPSTREAM.json +1 -1
- package/plugin/skills/dot-handoff/SKILL.md +1 -3
- package/plugin/skills/dot-handoff/UPSTREAM.json +1 -1
- package/plugin/skills/dot-implement/SKILL.md +10 -7
- package/plugin/skills/dot-plan/SKILL.md +3 -7
- package/plugin/skills/dot-plan/references/entity-schemas.md +3 -3
- package/plugin/skills/dot-roadmap/SKILL.md +4 -8
- package/plugin/skills/dot-roadmap/agents/openai.yaml +5 -0
- package/plugin/skills/dot-testing/SKILL.md +2 -5
- package/plugin/skills/dot-testing/references/after-implement.md +23 -0
- package/plugin/skills/dot-writing-for-agents/SKILL.md +1 -3
- package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +1 -1
- package/plugin/skills/dot-grill-me/SKILL.md +0 -11
- package/plugin/skills/dot-grill-me/UPSTREAM.json +0 -8
- package/plugin/skills/dot-grill-me/agents/openai.yaml +0 -5
- 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
|
|
5
|
-
steps, reviews the result, and asks for your
|
|
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
|
|
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
|
|
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-
|
|
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.
|
|
109
|
+
Main->>Agents: 1. Production code (dot-implementer)
|
|
110
110
|
Agents-->>Main: Reply
|
|
111
|
-
Main
|
|
112
|
-
|
|
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
|
|
116
|
-
|
|
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
|
|
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
|
|
135
|
-
in the main session, with the same
|
|
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
|
|
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-
|
|
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
|
|
176
|
-
| `dot-testing` | Write tests with a makeSut factory,
|
|
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
|
|
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
|
|
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -4,7 +4,7 @@ dotagents includes content from the following projects.
|
|
|
4
4
|
|
|
5
5
|
## mattpocock/skills
|
|
6
6
|
|
|
7
|
-
The `dot-debug`, `dot-
|
|
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:
|
package/dist/build-info.json
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"commit":"
|
|
1
|
+
{"commit":"6e38c12"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@igorlau/dotagents",
|
|
3
|
-
"version": "1.0.
|
|
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"
|
|
@@ -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
|
-
- **
|
|
17
|
+
- **Findings**: only on a second run, the review findings to fix. Fix these findings and nothing else.
|
|
18
18
|
|
|
19
|
-
When
|
|
19
|
+
When the task is missing, stop and report it.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
Write no tests, do not commit, and do not tick the roadmap checkbox.
|
|
22
22
|
|
|
23
23
|
## Output
|
|
24
24
|
|
|
25
|
-
End with
|
|
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,
|
|
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
|
|
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
|
-
- **
|
|
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
|
|
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.
|
package/plugin/hooks/check.mjs
CHANGED
|
@@ -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
|
|
3
|
-
//
|
|
4
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
25
|
-
|
|
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
|
-
|
|
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
|
|
84
|
-
|
|
85
|
-
|
|
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
|
-
|
|
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) {
|
package/plugin/hooks/hooks.json
CHANGED
|
@@ -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
|
|
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.
|
package/plugin/rules/core.md
CHANGED
|
@@ -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
|
|
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
|
|
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`.
|
package/plugin/rules/ponytail.md
CHANGED
|
@@ -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
|
}
|
package/plugin/rules/writing.md
CHANGED
|
@@ -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.
|
|
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
|
|
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
|
|
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,
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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-
|
|
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.
|
|
34
|
-
| 2.
|
|
35
|
-
| 3.
|
|
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.
|
|
41
|
+
Copy the replies unchanged, because the agents read their fields.
|
|
48
42
|
|
|
49
|
-
|
|
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
|
-
|
|
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
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
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
|
-
|
|
58
|
+
Done when the review reply arrived, or the flow stopped.
|
|
61
59
|
|
|
62
|
-
|
|
60
|
+
## 4. Decide after the review
|
|
63
61
|
|
|
64
|
-
|
|
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
|
-
-
|
|
67
|
-
-
|
|
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
|
|
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.
|
|
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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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-
|
|
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-
|
|
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
|
|
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
|
|
81
|
+
- <approved entity schema, as a code block, when the plan has one>
|
|
86
82
|
|
|
87
83
|
## Out of scope
|
|
88
84
|
|
|
@@ -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
|
-
|
|
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/
|
|
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
|
-
|
|
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
|
|
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,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.
|