@igorlau/dotagents 1.0.20 → 1.0.22
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 +66 -66
- package/THIRD_PARTY_NOTICES.md +101 -6
- package/dist/build-info.json +1 -1
- package/dist/catalog.js +3 -3
- package/dist/cli.js +1 -1
- package/dist/commands.js +52 -15
- package/dist/manifest.js +8 -1
- package/dist/paths.js +0 -4
- package/dist/targets.js +3 -9
- package/dist/wizard.js +1 -1
- package/package.json +5 -3
- package/{plugin/rules → rules}/comments.upstream.json +1 -1
- package/{plugin/rules → rules}/ponytail.md +1 -1
- package/{plugin/rules → rules}/ponytail.upstream.json +1 -1
- package/{plugin/rules → rules}/writing.md +5 -2
- package/{plugin/rules → rules}/writing.upstream.json +1 -1
- package/{plugin/scaffold → scaffold}/AGENTS.md.tmpl +1 -1
- package/{plugin/skills → skills}/dot-code-review/SKILL.md +2 -0
- package/{plugin/skills → skills}/dot-code-review/UPSTREAM.json +1 -1
- package/skills/dot-code-review/references/finding-classes.md +33 -0
- package/{plugin/skills → skills}/dot-code-review/references/maintainability.md +1 -0
- package/{plugin/skills → skills}/dot-comments/UPSTREAM.json +1 -1
- package/{plugin/skills → skills}/dot-commit/SKILL.md +0 -2
- package/skills/dot-correct/UPSTREAM.json +8 -0
- package/{plugin/skills → skills}/dot-debug/UPSTREAM.json +1 -1
- package/{plugin/skills → skills}/dot-grilling/UPSTREAM.json +2 -2
- package/{plugin/skills → skills}/dot-handoff/UPSTREAM.json +1 -1
- package/{plugin/skills → skills}/dot-implement/SKILL.md +2 -2
- package/{plugin/skills → skills}/dot-implement/references/typescript.md +2 -1
- package/{plugin/skills → skills}/dot-plan/SKILL.md +3 -1
- package/{plugin/skills → skills}/dot-roadmap/SKILL.md +7 -4
- package/skills/dot-security-audit/SKILL.md +87 -0
- package/skills/dot-security-audit/UPSTREAM.json +8 -0
- package/skills/dot-security-audit/references/AI-AND-LLM.md +83 -0
- package/skills/dot-security-audit/references/ATTACK-CLASSES.md +130 -0
- package/skills/dot-security-audit/references/CLIENT-SIDE.md +83 -0
- package/skills/dot-security-audit/references/CLOUD-AND-DEPLOYMENT.md +86 -0
- package/skills/dot-security-audit/references/DATA-ISOLATION-AND-LIFECYCLE.md +84 -0
- package/skills/dot-security-audit/references/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -0
- package/skills/dot-security-audit/references/MEMORY-SAFETY-AND-BINARY.md +101 -0
- package/skills/dot-security-audit/references/PROTOCOLS-RPC-AND-MESSAGING.md +81 -0
- package/skills/dot-security-audit/references/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -0
- package/skills/dot-security-audit/references/SUPPLY-CHAIN-AND-RELEASE.md +73 -0
- package/skills/dot-security-audit/references/WEB-PROTOCOL-AND-AUTH.md +105 -0
- package/skills/dot-security-changes/SKILL.md +68 -0
- package/{plugin/skills → skills}/dot-testing/UPSTREAM.json +1 -1
- package/skills/dot-ui-review/SKILL.md +79 -0
- package/skills/dot-ui-review/UPSTREAM.json +8 -0
- package/skills/dot-ux-review/SKILL.md +50 -0
- package/skills/dot-ux-review/UPSTREAM.json +8 -0
- package/skills/dot-ux-review/references/web-interface-guidelines.md +191 -0
- package/{plugin/skills/dot-stack-review → skills/dot-walkthrough-branch}/SKILL.md +9 -30
- package/skills/dot-walkthrough-branch/references/layers.md +38 -0
- package/{plugin/skills/dot-stack-review → skills/dot-walkthrough-branch}/scripts/page.mjs +39 -10
- package/skills/dot-walkthrough-changes/SKILL.md +62 -0
- package/skills/dot-writing-for-agents/UPSTREAM.json +8 -0
- package/plugin/.claude-plugin/plugin.json +0 -10
- package/plugin/agents/dot-implementer.md +0 -27
- package/plugin/agents/dot-reviewer.md +0 -44
- package/plugin/agents/dot-tester.md +0 -25
- package/plugin/hooks/check.mjs +0 -118
- package/plugin/hooks/hooks.json +0 -54
- package/plugin/hooks/rules.mjs +0 -27
- package/plugin/skills/dot-correct/UPSTREAM.json +0 -8
- package/plugin/skills/dot-correct/agents/openai.yaml +0 -5
- package/plugin/skills/dot-debug/agents/openai.yaml +0 -3
- package/plugin/skills/dot-flow/SKILL.md +0 -105
- package/plugin/skills/dot-flow/agents/openai.yaml +0 -5
- package/plugin/skills/dot-flow/references/fix-round.md +0 -64
- package/plugin/skills/dot-flow/references/inline.md +0 -9
- package/plugin/skills/dot-grilling/agents/openai.yaml +0 -3
- package/plugin/skills/dot-handoff/agents/openai.yaml +0 -5
- package/plugin/skills/dot-roadmap/agents/openai.yaml +0 -5
- package/plugin/skills/dot-stack-review/agents/openai.yaml +0 -5
- package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +0 -8
- package/plugin/skills/dot-writing-for-agents/agents/openai.yaml +0 -3
- /package/{plugin/rules → rules}/code-style.md +0 -0
- /package/{plugin/rules → rules}/comments.md +0 -0
- /package/{plugin/rules → rules}/core.md +0 -0
- /package/{plugin/scaffold → scaffold}/.claude/settings.json.tmpl +0 -0
- /package/{plugin/scaffold → scaffold}/.editorconfig.tmpl +0 -0
- /package/{plugin/scaffold → scaffold}/.gitattributes.tmpl +0 -0
- /package/{plugin/scaffold → scaffold}/CLAUDE.md.tmpl +0 -0
- /package/{plugin/skills → skills}/dot-comments/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-correct/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-debug/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-debug/references/loops.md +0 -0
- /package/{plugin/skills → skills}/dot-debug/scripts/hitl-loop.template.sh +0 -0
- /package/{plugin/skills → skills}/dot-docs-writing/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-docs-writing/references/formatting.md +0 -0
- /package/{plugin/skills → skills}/dot-docs-writing/references/global-and-accessible.md +0 -0
- /package/{plugin/skills → skills}/dot-docs-writing/references/word-list.md +0 -0
- /package/{plugin/skills → skills}/dot-grilling/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-handoff/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-implement/UPSTREAM.json +0 -0
- /package/{plugin/skills → skills}/dot-plan/UPSTREAM.json +0 -0
- /package/{plugin/skills → skills}/dot-plan/references/entity-schemas.md +0 -0
- /package/{plugin/skills → skills}/dot-roadmap/UPSTREAM.json +0 -0
- /package/{plugin/skills → skills}/dot-roadmap/references/wide-refactor.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/references/after-implement.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/references/http.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/references/shared-state.md +0 -0
- /package/{plugin/skills → skills}/dot-testing/references/typescript.md +0 -0
- /package/{plugin/skills → skills}/dot-writing-for-agents/SKILL.md +0 -0
- /package/{plugin/skills → skills}/dot-writing-for-agents/references/pointers.md +0 -0
- /package/{plugin/skills → skills}/dot-writing-for-agents/references/skill-mechanics.md +0 -0
- /package/{plugin/skills → skills}/dot-writing-for-agents/references/steps.md +0 -0
package/plugin/hooks/check.mjs
DELETED
|
@@ -1,118 +0,0 @@
|
|
|
1
|
-
// Hook for Claude Code, Copilot, and Codex. With `snapshot`, it runs when a
|
|
2
|
-
// prompt arrives or a subagent starts, and records the working tree. Without
|
|
3
|
-
// it, it runs when the agent or the subagent stops: when that agent changed
|
|
4
|
-
// the tree, it runs the repository's `check` script and, when that fails,
|
|
5
|
-
// asks the agent to continue with the output. A check that still fails on
|
|
6
|
-
// the retry becomes a warning for the user, so the hook can't loop.
|
|
7
|
-
// It acts only in repositories that `dotagents check enable` added to the
|
|
8
|
-
// user's config, because the `check` script is the repository's own code.
|
|
9
|
-
import { spawnSync } from "node:child_process";
|
|
10
|
-
import crypto from "node:crypto";
|
|
11
|
-
import fs from "node:fs";
|
|
12
|
-
import os from "node:os";
|
|
13
|
-
import path from "node:path";
|
|
14
|
-
|
|
15
|
-
const MAX_OUTPUT = 4000;
|
|
16
|
-
|
|
17
|
-
const input = JSON.parse(fs.readFileSync(0, "utf8") || "{}");
|
|
18
|
-
const cwd = input.cwd ?? process.cwd();
|
|
19
|
-
// A subagent has its own snapshot, so each agent answers only for the changes that it made.
|
|
20
|
-
const snapshotFile = path.join(os.tmpdir(), "dotagents-check", `${hash(input.agent_id ?? input.session_id ?? cwd)}.txt`);
|
|
21
|
-
|
|
22
|
-
// Codex needs JSON on stdout when the hook exits 0.
|
|
23
|
-
let decision = {};
|
|
24
|
-
if (checkEnabled()) {
|
|
25
|
-
if (process.argv[2] === "snapshot") saveSnapshot();
|
|
26
|
-
else {
|
|
27
|
-
const command = turnChangedTree() && checkCommand();
|
|
28
|
-
if (command) decision = runCheck(command);
|
|
29
|
-
// A blocked agent stops again, and that retry needs the snapshot.
|
|
30
|
-
if (decision.decision !== "block") fs.rmSync(snapshotFile, { force: true });
|
|
31
|
-
}
|
|
32
|
-
}
|
|
33
|
-
console.log(JSON.stringify(decision));
|
|
34
|
-
|
|
35
|
-
function checkEnabled() {
|
|
36
|
-
const top = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
|
|
37
|
-
if (top.status !== 0) return false;
|
|
38
|
-
// Same path as configDir() in the CLI's src/paths.ts.
|
|
39
|
-
const configDir = process.env.XDG_CONFIG_HOME ? path.join(process.env.XDG_CONFIG_HOME, "dotagents") : path.join(os.homedir(), ".config", "dotagents");
|
|
40
|
-
try {
|
|
41
|
-
const { checkRepos = [] } = JSON.parse(fs.readFileSync(path.join(configDir, "config.json"), "utf8"));
|
|
42
|
-
return Array.isArray(checkRepos) && checkRepos.includes(fs.realpathSync(top.stdout.trim()));
|
|
43
|
-
} catch {
|
|
44
|
-
return false;
|
|
45
|
-
}
|
|
46
|
-
}
|
|
47
|
-
|
|
48
|
-
function saveSnapshot() {
|
|
49
|
-
const tree = treeHash();
|
|
50
|
-
if (!tree) return;
|
|
51
|
-
fs.mkdirSync(path.dirname(snapshotFile), { recursive: true });
|
|
52
|
-
fs.writeFileSync(snapshotFile, tree);
|
|
53
|
-
}
|
|
54
|
-
|
|
55
|
-
// Without a snapshot or Git, a change can't be proven, so the check doesn't run:
|
|
56
|
-
// a failing check on untouched code would make the agent edit what nobody asked for.
|
|
57
|
-
function turnChangedTree() {
|
|
58
|
-
const tree = treeHash();
|
|
59
|
-
if (!tree || !fs.existsSync(snapshotFile)) return false;
|
|
60
|
-
return fs.readFileSync(snapshotFile, "utf8") !== tree;
|
|
61
|
-
}
|
|
62
|
-
|
|
63
|
-
/** Hashes the working tree, untracked files included and ignored files excluded, without touching the repository's index. */
|
|
64
|
-
function treeHash() {
|
|
65
|
-
const index = path.join(os.tmpdir(), `dotagents-index-${process.pid}`);
|
|
66
|
-
const env = { ...process.env, GIT_INDEX_FILE: index };
|
|
67
|
-
try {
|
|
68
|
-
// Starting from a copy of the real index reuses its file stat cache, so unchanged files aren't rehashed.
|
|
69
|
-
const realIndex = spawnSync("git", ["rev-parse", "--path-format=absolute", "--git-path", "index"], { cwd, encoding: "utf8" });
|
|
70
|
-
if (realIndex.status === 0 && fs.existsSync(realIndex.stdout.trim())) fs.copyFileSync(realIndex.stdout.trim(), index);
|
|
71
|
-
const add = spawnSync("git", ["add", "--all", "."], { cwd, env, encoding: "utf8" });
|
|
72
|
-
if (add.status !== 0) return undefined;
|
|
73
|
-
const tree = spawnSync("git", ["write-tree"], { cwd, env, encoding: "utf8" });
|
|
74
|
-
return tree.status === 0 ? tree.stdout.trim() : undefined;
|
|
75
|
-
} finally {
|
|
76
|
-
fs.rmSync(index, { force: true });
|
|
77
|
-
}
|
|
78
|
-
}
|
|
79
|
-
|
|
80
|
-
/** Returns the command and arguments that run the repository's `check`: an npm script, else a Makefile target. */
|
|
81
|
-
function checkCommand() {
|
|
82
|
-
if (hasNpmCheck()) return ["npm", "run", "--silent", "check"];
|
|
83
|
-
if (hasMakeCheck()) return ["make", "--silent", "check"];
|
|
84
|
-
return undefined;
|
|
85
|
-
}
|
|
86
|
-
|
|
87
|
-
function hasNpmCheck() {
|
|
88
|
-
try {
|
|
89
|
-
return Boolean(JSON.parse(fs.readFileSync(path.join(cwd, "package.json"), "utf8")).scripts?.check);
|
|
90
|
-
} catch {
|
|
91
|
-
return false;
|
|
92
|
-
}
|
|
93
|
-
}
|
|
94
|
-
|
|
95
|
-
function hasMakeCheck() {
|
|
96
|
-
try {
|
|
97
|
-
return /^check:/m.test(fs.readFileSync(path.join(cwd, "Makefile"), "utf8"));
|
|
98
|
-
} catch {
|
|
99
|
-
return false;
|
|
100
|
-
}
|
|
101
|
-
}
|
|
102
|
-
|
|
103
|
-
function runCheck([command, ...args]) {
|
|
104
|
-
const result = spawnSync(command, args, { cwd, encoding: "utf8", shell: process.platform === "win32" });
|
|
105
|
-
// A runner that isn't installed can't prove a failure.
|
|
106
|
-
if (result.status === 0 || result.error) return {};
|
|
107
|
-
const output = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim().slice(-MAX_OUTPUT) || "It printed nothing.";
|
|
108
|
-
const failure = `\`${[command, ...args.filter((arg) => arg !== "--silent")].join(" ")}\` failed with exit code ${result.status}.`;
|
|
109
|
-
if (input.stop_hook_active) return { systemMessage: `${failure} The agent already tried to fix it, so the check still fails:\n${output}` };
|
|
110
|
-
return {
|
|
111
|
-
decision: "block",
|
|
112
|
-
reason: `${failure} Fix the problems that your changes caused, then finish. If a problem was there before your changes, leave it and tell the user:\n${output}`,
|
|
113
|
-
};
|
|
114
|
-
}
|
|
115
|
-
|
|
116
|
-
function hash(text) {
|
|
117
|
-
return crypto.createHash("sha256").update(text).digest("hex").slice(0, 16);
|
|
118
|
-
}
|
package/plugin/hooks/hooks.json
DELETED
|
@@ -1,54 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"hooks": {
|
|
3
|
-
"UserPromptSubmit": [
|
|
4
|
-
{
|
|
5
|
-
"hooks": [
|
|
6
|
-
{
|
|
7
|
-
"type": "command",
|
|
8
|
-
"command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check.mjs\" snapshot"
|
|
9
|
-
}
|
|
10
|
-
]
|
|
11
|
-
}
|
|
12
|
-
],
|
|
13
|
-
"SessionStart": [
|
|
14
|
-
{
|
|
15
|
-
"hooks": [
|
|
16
|
-
{
|
|
17
|
-
"type": "command",
|
|
18
|
-
"command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/rules.mjs\""
|
|
19
|
-
}
|
|
20
|
-
]
|
|
21
|
-
}
|
|
22
|
-
],
|
|
23
|
-
"SubagentStart": [
|
|
24
|
-
{
|
|
25
|
-
"hooks": [
|
|
26
|
-
{
|
|
27
|
-
"type": "command",
|
|
28
|
-
"command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check.mjs\" snapshot"
|
|
29
|
-
}
|
|
30
|
-
]
|
|
31
|
-
}
|
|
32
|
-
],
|
|
33
|
-
"SubagentStop": [
|
|
34
|
-
{
|
|
35
|
-
"hooks": [
|
|
36
|
-
{
|
|
37
|
-
"type": "command",
|
|
38
|
-
"command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check.mjs\""
|
|
39
|
-
}
|
|
40
|
-
]
|
|
41
|
-
}
|
|
42
|
-
],
|
|
43
|
-
"Stop": [
|
|
44
|
-
{
|
|
45
|
-
"hooks": [
|
|
46
|
-
{
|
|
47
|
-
"type": "command",
|
|
48
|
-
"command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/check.mjs\""
|
|
49
|
-
}
|
|
50
|
-
]
|
|
51
|
-
}
|
|
52
|
-
]
|
|
53
|
-
}
|
|
54
|
-
}
|
package/plugin/hooks/rules.mjs
DELETED
|
@@ -1,27 +0,0 @@
|
|
|
1
|
-
// Hook for the start of a session. The plugin updates on every commit, but the
|
|
2
|
-
// rules reach Claude Code only when the user runs `dotagents update`. This
|
|
3
|
-
// hook warns the user when the installed rules differ from the plugin's rules.
|
|
4
|
-
// shortcut: checks only Claude Code's rules file, add the Codex and Copilot blocks when their plugins update apart from the CLI.
|
|
5
|
-
import fs from "node:fs";
|
|
6
|
-
import os from "node:os";
|
|
7
|
-
import path from "node:path";
|
|
8
|
-
import { fileURLToPath } from "node:url";
|
|
9
|
-
|
|
10
|
-
const rulesDir = fileURLToPath(new URL("../rules", import.meta.url));
|
|
11
|
-
const claudeHome = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
|
|
12
|
-
const installedFile = path.join(claudeHome, "rules", "dotagents.md");
|
|
13
|
-
|
|
14
|
-
let message;
|
|
15
|
-
try {
|
|
16
|
-
const installed = fs.readFileSync(installedFile, "utf8");
|
|
17
|
-
// Same heading shift as loadRules() in the CLI's src/catalog.ts.
|
|
18
|
-
const stale = fs
|
|
19
|
-
.readdirSync(rulesDir)
|
|
20
|
-
.filter((name) => name.endsWith(".md"))
|
|
21
|
-
.some((name) => !installed.includes(fs.readFileSync(path.join(rulesDir, name), "utf8").trim().replace(/^#/gm, "##")));
|
|
22
|
-
if (stale) message = "The installed dotagents rules differ from the rules of the dotagents plugin. Run `dotagents update` with a release that has the same rules, and add `--force` if you changed the rules file.";
|
|
23
|
-
} catch {
|
|
24
|
-
// Without Claude Code's directory, another coding agent runs the plugin, and its rules are in another file.
|
|
25
|
-
if (fs.existsSync(claudeHome)) message = "The dotagents plugin needs the dotagents rules. Run `npx @igorlau/dotagents install`.";
|
|
26
|
-
}
|
|
27
|
-
console.log(JSON.stringify(message ? { systemMessage: message } : {}));
|
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"repository": "https://github.com/cursor/plugins",
|
|
3
|
-
"path": "pstack/skills/correct/SKILL.md",
|
|
4
|
-
"commit": "a5539b15a3d56e04992565aafee2b37051329ce3",
|
|
5
|
-
"license": "MIT",
|
|
6
|
-
"modified": true,
|
|
7
|
-
"notes": "Rewrote the text under plugin/rules/writing.md and renamed it with the dot- prefix. Split the levels into architecture, types, a lint rule or check, a test, and docs, and added the approval before a new dependency or a lint configuration change. Left out the rule table in the agent instruction file and the expiry date on exceptions. Merged pstack/skills/principle-encode-lessons-in-structure at the same commit: use only the structural fix when one works, and add an example of the mistake to a docs rule. The commit goes through dot-commit."
|
|
8
|
-
}
|
|
@@ -1,105 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: dot-flow
|
|
3
|
-
description: Take one roadmap task through implementation, tests, and review, fix the high and medium findings in automatic rounds, and stop for your decision.
|
|
4
|
-
disable-model-invocation: true
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
# Flow
|
|
8
|
-
|
|
9
|
-
Take one task from a `dot-roadmap` roadmap through three steps: implementation, tests, and review. Each step runs in a fresh agent with one skill. You coordinate the steps, and you verify each reply with the commands that it names. The agents write the code, the tests, and the review. The user decides at a stop.
|
|
10
|
-
|
|
11
|
-
## 1. Pin the task
|
|
12
|
-
|
|
13
|
-
The input is a roadmap task file or a roadmap directory. With a directory, pick the lowest-id unticked task whose blockers are all ticked in its `README.md`. If the task has an unticked blocker, stop and name it.
|
|
14
|
-
|
|
15
|
-
Run `git status --short`. The review step reads every uncommitted change, so when the working tree has other changes, ask the user to commit them first or to include them in the review.
|
|
16
|
-
|
|
17
|
-
Done when you can name the task file and its goal.
|
|
18
|
-
|
|
19
|
-
## 2. Pick the runner
|
|
20
|
-
|
|
21
|
-
Use the agents of the dotagents plugin when the `Agent` tool can start them: `dotagents:dot-implementer`, `dotagents:dot-tester`, and `dotagents:dot-reviewer`. Otherwise, such as in Codex or Copilot, read [`references/inline.md`](references/inline.md), and run each step inline with the same verification and stops.
|
|
22
|
-
|
|
23
|
-
## 3. Run and verify the steps
|
|
24
|
-
|
|
25
|
-
Run the steps in this order. For each step, start a new agent of the named type, not a fork, so that each step starts with a fresh context:
|
|
26
|
-
|
|
27
|
-
| Step | Agent | Prompt fields |
|
|
28
|
-
| ---- | ----- | ------------- |
|
|
29
|
-
| 1. Implement | `dotagents:dot-implementer` | Task |
|
|
30
|
-
| 2. Test | `dotagents:dot-tester` | Task, Handoff: the reply of step 1 |
|
|
31
|
-
| 3. Review | `dotagents:dot-reviewer` | Task, Handoff: the replies of steps 1 and 2, Since and Earlier findings: only on a fix run |
|
|
32
|
-
|
|
33
|
-
Write the prompt as labeled fields, and leave out a field that the step does not take:
|
|
34
|
-
|
|
35
|
-
```markdown
|
|
36
|
-
**Task:** <path of the task file>
|
|
37
|
-
**Handoff:**
|
|
38
|
-
<the replies of the earlier steps, unchanged>
|
|
39
|
-
**Findings:**
|
|
40
|
-
<the findings to fix, unchanged>
|
|
41
|
-
**Since:** <old-tree> <new-tree>
|
|
42
|
-
**Earlier findings:**
|
|
43
|
-
<the findings that the round sent to fix and the light-fixed findings, unchanged>
|
|
44
|
-
```
|
|
45
|
-
|
|
46
|
-
Copy the replies and the findings unchanged, because the agents read their fields. Add no other fields or instructions, such as a list of files to review.
|
|
47
|
-
|
|
48
|
-
A reply is a claim, not a result. After steps 1 and 2, run each command that the reply names in its **Checks** or **Tests** line, and read only the result line and the names of the tests that fail. Keep the main context small: do not read the changed files. The step is **verified** when all of these are true:
|
|
49
|
-
|
|
50
|
-
- The type checker and the linter pass.
|
|
51
|
-
- After step 1, each test that fails is in "Expected failures".
|
|
52
|
-
- After step 2, the test command passes.
|
|
53
|
-
- The reply has no blockers.
|
|
54
|
-
|
|
55
|
-
After a verified step, show the user one line, such as "Step 1 of 3: verified, `npm run check` passes", and start the next step. Do not wait.
|
|
56
|
-
|
|
57
|
-
Stop the flow, keep the files as they are, and ask the user how to continue in these cases:
|
|
58
|
-
|
|
59
|
-
- A reply has blockers. Show them.
|
|
60
|
-
- A step is not verified. Show the command, your result line, and the line of the reply.
|
|
61
|
-
- The `check` hook reports a failure to you. An agent left it, so the step is not verified. Show the output, and do not edit the code yourself.
|
|
62
|
-
|
|
63
|
-
Done when the review reply arrived, or the flow stopped.
|
|
64
|
-
|
|
65
|
-
## 4. Decide after each review
|
|
66
|
-
|
|
67
|
-
When the first review reply of the task arrives, write the old tree, as the "Snapshots" section of [`references/fix-round.md`](references/fix-round.md#snapshots) gives it.
|
|
68
|
-
|
|
69
|
-
A **fix round** runs step 1 again in a new agent, with the findings to fix as a **Findings** field, then takes the light path or runs steps 2 and 3 again. Before the first fix round, read [`references/fix-round.md`](references/fix-round.md), for the snapshots, the light path, the review fields, and the findings to carry.
|
|
70
|
-
|
|
71
|
-
After each review, check the stop rules. When no stop rule is true, run an **automatic round**: a fix round of every `high` and `medium` finding, with no question to the user. Show one line, such as "Round 2: automatic fix of 1 `medium` finding". The task has a limit of 2 automatic rounds. Rounds that the user picks do not count, and do not reset the count. The automatic rounds also follow a review after a round that the user picked.
|
|
72
|
-
|
|
73
|
-
### Stop rules
|
|
74
|
-
|
|
75
|
-
Stop the loop and ask the user when any of these is true:
|
|
76
|
-
|
|
77
|
-
1. The highest severity is `low`, or no findings remain.
|
|
78
|
-
2. 2 automatic rounds have run.
|
|
79
|
-
3. A finding that the round sent to fix has the status `open` or `regressed`.
|
|
80
|
-
4. After a fix round, the count did not go down since the review before. The count is the `high` and `medium` findings that remain after the review, carried findings included.
|
|
81
|
-
5. A stop of step 3 fires.
|
|
82
|
-
|
|
83
|
-
At the stop, show the round history, with one row for each round:
|
|
84
|
-
|
|
85
|
-
```markdown
|
|
86
|
-
| Round | Kind | Review | Fixed | Open | Regressed | New | Highest |
|
|
87
|
-
| ----- | ---- | ------ | ----- | ---- | --------- | --- | ------- |
|
|
88
|
-
| 1 | first | full | - | - | - | 4 | medium |
|
|
89
|
-
| 2 | auto | delta | 2 | 0 | 0 | 0 | low |
|
|
90
|
-
```
|
|
91
|
-
|
|
92
|
-
Kind is `first`, `auto`, `user`, or `light`. A `light` round has `none` in the Review column. Highest is the highest severity of the findings that remain after the round.
|
|
93
|
-
|
|
94
|
-
Then show the **Highest severity** line and one line for each finding: its severity, summary, and `file:line`, and its status when it has one. Show each `high` finding with its **Fix** line. The presumed blockers of the maintainability pass are `high`. Then wait for the user to pick one:
|
|
95
|
-
|
|
96
|
-
- **Fix**: the user names the findings to fix. Run a fix round with them.
|
|
97
|
-
- **Accept**: the user accepts the findings that remain.
|
|
98
|
-
|
|
99
|
-
Done when the user accepts.
|
|
100
|
-
|
|
101
|
-
## 5. Finish
|
|
102
|
-
|
|
103
|
-
List the files that the steps changed, from the **Files** lines of the replies. Suggest the `dot-commit` skill, and name the task file, so that `dot-commit` can tick its checkbox.
|
|
104
|
-
|
|
105
|
-
Do not commit, and do not tick the roadmap checkbox: `dot-commit` ticks it when the commits finish the task.
|
|
@@ -1,64 +0,0 @@
|
|
|
1
|
-
# Fix round
|
|
2
|
-
|
|
3
|
-
Read this file in the [`dot-flow`](../SKILL.md) skill before the first fix round, automatic or picked by the user. Read its "Snapshots" section earlier, when the first review of the task ends. The file gives the snapshots, the light path, the choice between a full review and a delta review, and the fields of step 3 on a fix run. Both runners use it.
|
|
4
|
-
|
|
5
|
-
## Snapshots
|
|
6
|
-
|
|
7
|
-
A snapshot is a Git tree of the working tree, with the untracked files and without the ignored files. Write it with a temporary index, so that the working tree and the index stay as they are. Run these commands at the repository root:
|
|
8
|
-
|
|
9
|
-
```bash
|
|
10
|
-
tmp="$(mktemp)"
|
|
11
|
-
cp "$(git rev-parse --git-path index)" "$tmp"
|
|
12
|
-
GIT_INDEX_FILE="$tmp" git add -A && GIT_INDEX_FILE="$tmp" git write-tree
|
|
13
|
-
rm -f "$tmp"
|
|
14
|
-
```
|
|
15
|
-
|
|
16
|
-
`git write-tree` prints the hash of the tree. When the commands print no hash, stop the flow and show the error to the user. Each fix round uses 2 trees:
|
|
17
|
-
|
|
18
|
-
- **Old tree**: the state that the last review read. Before the first fix round, write it when the first review reply arrives, before you show the review to the user. On a later fix round, it is the new tree of the round before.
|
|
19
|
-
- **New tree**: write it after step 2 of the fix round is verified, before step 3 starts.
|
|
20
|
-
|
|
21
|
-
Compare the 2 trees, not a tree and the working tree. `git diff <tree>` misses the new untracked files, and shows the files that were untracked at the snapshot as deleted.
|
|
22
|
-
|
|
23
|
-
Compare the paths from the repository root, as `git diff --name-only` prints them. Before a comparison, remove the repository root from each absolute path in a finding or on a **Files** line.
|
|
24
|
-
|
|
25
|
-
## Light path
|
|
26
|
-
|
|
27
|
-
The light path applies when the user picks Fix and every finding to fix is `low`. A light-fixed finding is a finding that the light path fixed since the last review. On this path, the reply of step 1 ends with the line `**Behavior change:** <yes | no>`. After step 1, write a tree as the "Snapshots" section gives it, and check these 3 conditions:
|
|
28
|
-
|
|
29
|
-
- The **Behavior change** line says `no`.
|
|
30
|
-
- `git diff --name-only <old-tree> <tree>` lists only files that the findings to fix or the light-fixed findings name.
|
|
31
|
-
- The checks of the reply and the full test command pass, with no failed test.
|
|
32
|
-
|
|
33
|
-
When all 3 are true, skip steps 2 and 3. Add a `light` row to the round history, and show the stop of `SKILL.md` step 4 again, with each fixed finding as "fixed, not reviewed". Keep the old tree, so that the next review also reads the light fix. Add the light-fixed findings to the **Earlier findings** of the next review, so that it grades them.
|
|
34
|
-
|
|
35
|
-
When a condition is false, run steps 2 and 3 as a normal fix round.
|
|
36
|
-
|
|
37
|
-
## Full or delta
|
|
38
|
-
|
|
39
|
-
Run `git diff --name-only <old-tree> <new-tree>`, and read only the file names, never the changed files. Remove from the list the files on the **Files** line of the step 2 reply of the round. The delta diff still has these test changes, so a delta review reviews them.
|
|
40
|
-
|
|
41
|
-
- When the list that remains has a file that no earlier finding names, run a full review: leave out **Since**.
|
|
42
|
-
- Otherwise, run a delta review: give step 3 the **Since** field.
|
|
43
|
-
|
|
44
|
-
## Fields of step 3
|
|
45
|
-
|
|
46
|
-
On a fix run, add these fields after **Handoff**:
|
|
47
|
-
|
|
48
|
-
```markdown
|
|
49
|
-
**Since:** <old-tree> <new-tree>
|
|
50
|
-
**Earlier findings:**
|
|
51
|
-
<the findings that the round sent to fix and the light-fixed findings, unchanged>
|
|
52
|
-
```
|
|
53
|
-
|
|
54
|
-
- **Since**: only on a delta review. The reviewer runs `git diff <old-tree> <new-tree>`, and reviews only that diff. It still checks the diff against every `NN` and each `BR` that the task names. A delta review does not find an old defect that an earlier review missed. This trade-off is accepted.
|
|
55
|
-
- **Earlier findings**: on each fix run, full or delta. The reviewer does not report an earlier finding again as a new finding. It gives each earlier finding one status, and reports the statuses before the new findings:
|
|
56
|
-
- `fixed`: the problem is gone.
|
|
57
|
-
- `open`: the problem is still there.
|
|
58
|
-
- `regressed`: the fix made the problem worse, or moved it to other code.
|
|
59
|
-
|
|
60
|
-
Only the round 1 review reports `low` findings. A review with **Earlier findings**, full or delta, reports only new `high` and `medium` findings, plus the status of each earlier finding.
|
|
61
|
-
|
|
62
|
-
**Earlier findings** lists only the findings that the round sent to fix and the light-fixed findings. Keep each earlier finding that the review grades `open` or `regressed` as the last review that reported it gave it, with its `file:line` and **Fix** line. Show it again at the next decision with its status. This applies after a full review and after a delta review.
|
|
63
|
-
|
|
64
|
-
Also keep each finding that remained before the round and that is not in **Earlier findings**, unchanged, and show it again at the next decision. No reviewer grades it again. After a full review, keep only the `low` ones. The report replaces the carried `high` and `medium` findings, and a later review does not report a `low` finding again. The highest severity that you show also covers the carried findings.
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
# Inline mode
|
|
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 verification, the stops of step 3, and step 4 stay as `SKILL.md` gives them: the automatic rounds, their limit, and the stop rules. You run each step yourself, in this conversation, instead of in an agent.
|
|
4
|
-
|
|
5
|
-
1. Implement: use the `dot-implement` skill for the task, and end the step with its handoff. Write no tests in this step. On a fix run, end the handoff with the line `**Behavior change:** <yes | no>`. A behavior change is a change to what the code does for any input. Then take the light path or run steps 2 and 3, as [`fix-round.md`](fix-round.md#light-path) gives it.
|
|
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. Start the report with the line `**Highest severity:** <high | medium | low | none>`. Also read the `## Requirements` section of the roadmap `README.md`, check the change against every non-negotiable (`NN`) and each business rule (`BR`) that the task names, and report a breached `NN` as a `high` finding. On a fix run, write the new tree, pick a full or a delta review, and grade the earlier findings, as [`fix-round.md`](fix-round.md) gives it. On a delta review, the target is `git diff <old-tree> <new-tree>`. A full review has the target `git diff HEAD`, plus the untracked files that `git status --short` lists. The round 1 review reports every finding at every severity. A later review reports only new `high` and `medium` findings, plus the status of each earlier finding. Keep the code as it is. Delete each test that you write to prove a finding.
|
|
8
|
-
|
|
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.
|
|
@@ -1,8 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"repository": "https://github.com/mattpocock/skills",
|
|
3
|
-
"path": "skills/productivity/writing-for-agents",
|
|
4
|
-
"commit": "49dd158d1076134a641b33efb035946536778336",
|
|
5
|
-
"license": "MIT",
|
|
6
|
-
"modified": true,
|
|
7
|
-
"notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under 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
|
-
}
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|