@igorlau/dotagents 1.0.16 → 1.0.18
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 +16 -20
- package/dist/apply.js +6 -6
- package/dist/build-info.json +1 -1
- package/dist/cli.js +24 -4
- package/dist/commands.js +84 -17
- package/dist/git.js +1 -1
- package/dist/targets.js +24 -5
- package/dist/wizard.js +248 -0
- package/package.json +4 -1
- package/plugin/agents/dot-implementer.md +1 -1
- package/plugin/agents/dot-reviewer.md +4 -3
- package/plugin/skills/dot-flow/SKILL.md +5 -3
- package/plugin/skills/dot-flow/references/inline.md +1 -1
- package/plugin/skills/dot-implement/SKILL.md +2 -2
- package/plugin/skills/dot-plan/SKILL.md +30 -5
- package/plugin/skills/dot-roadmap/SKILL.md +19 -5
package/README.md
CHANGED
|
@@ -13,30 +13,24 @@ dotagents has two parts:
|
|
|
13
13
|
|
|
14
14
|
## Install
|
|
15
15
|
|
|
16
|
-
To install
|
|
17
|
-
|
|
18
|
-
```text
|
|
19
|
-
/plugin marketplace add igorlau/dotagents
|
|
20
|
-
/plugin install dotagents@dotagents
|
|
21
|
-
```
|
|
22
|
-
|
|
23
|
-
The plugin skills have the `dotagents:` namespace, such as
|
|
24
|
-
`/dotagents:dot-plan`.
|
|
25
|
-
|
|
26
|
-
To install the rules for all your projects, and the skills for Codex and
|
|
27
|
-
Copilot, run the following command:
|
|
16
|
+
To install dotagents, run the following command in a terminal:
|
|
28
17
|
|
|
29
18
|
```bash
|
|
30
|
-
npx --yes @igorlau/dotagents
|
|
19
|
+
npx --yes @igorlau/dotagents
|
|
31
20
|
```
|
|
32
21
|
|
|
33
|
-
The
|
|
34
|
-
|
|
35
|
-
|
|
22
|
+
The wizard asks for your coding agents and where to install. For a global
|
|
23
|
+
install with Claude Code, it offers to install the Claude Code plugin. In a
|
|
24
|
+
repository, it can enable the `check` hook. It shows a summary and writes
|
|
25
|
+
nothing before you confirm.
|
|
36
26
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
27
|
+
The plugin skills have the `dotagents:` namespace, such as
|
|
28
|
+
`/dotagents:dot-plan`. The plugin hook runs the `check` script of a
|
|
29
|
+
repository at the end of each turn that changes files, only in a repository
|
|
30
|
+
that you enable.
|
|
31
|
+
|
|
32
|
+
For scripts and CI, use the commands with flags. Without a terminal, no
|
|
33
|
+
wizard opens. See [Install dotagents](docs/guide/01-install.md).
|
|
40
34
|
|
|
41
35
|
`npx` runs dotagents without an install. To run `dotagents` as a command in
|
|
42
36
|
any terminal, install it globally:
|
|
@@ -97,6 +91,8 @@ sequenceDiagram
|
|
|
97
91
|
Main-->>User: Questions in rounds, with recommended answers
|
|
98
92
|
User->>Main: Answers until the plan is clear
|
|
99
93
|
User->>Main: dot-plan
|
|
94
|
+
Main-->>User: Requirements
|
|
95
|
+
User->>Main: Approve the requirements
|
|
100
96
|
Main-->>User: Entity schemas
|
|
101
97
|
User->>Main: Approve the schemas
|
|
102
98
|
Main-->>User: Plan as small, verifiable steps
|
|
@@ -168,7 +164,7 @@ them:
|
|
|
168
164
|
| Skill | Purpose |
|
|
169
165
|
| ----- | ------- |
|
|
170
166
|
| `dot-grilling` | Run an interview, in rounds of questions, that makes a plan clear. |
|
|
171
|
-
| `dot-plan` | Plan a change as small, verifiable steps, with entity schemas. |
|
|
167
|
+
| `dot-plan` | Plan a change as small, verifiable steps, with requirements and entity schemas. |
|
|
172
168
|
| `dot-roadmap` | Split a plan into phases and tasks that each stand alone. |
|
|
173
169
|
| `dot-flow` | Take a roadmap task through code, tests, and review, verify each step, and stop for your decision after the review. |
|
|
174
170
|
| `dot-testing` | Write tests with a makeSut factory, alone or after `dot-implement`. |
|
package/dist/apply.js
CHANGED
|
@@ -40,7 +40,7 @@ function applyFile(op, owned, options, result) {
|
|
|
40
40
|
const current = read(op.path);
|
|
41
41
|
if (current === undefined) {
|
|
42
42
|
write(op.path, op.content, options, op.executable);
|
|
43
|
-
result.changes.push(
|
|
43
|
+
result.changes.push({ action: "create", path: op.path });
|
|
44
44
|
return entry;
|
|
45
45
|
}
|
|
46
46
|
if (current === op.content)
|
|
@@ -56,7 +56,7 @@ function applyFile(op, owned, options, result) {
|
|
|
56
56
|
}
|
|
57
57
|
}
|
|
58
58
|
write(op.path, op.content, options, op.executable);
|
|
59
|
-
result.changes.push(
|
|
59
|
+
result.changes.push({ action: "update", path: op.path });
|
|
60
60
|
return entry;
|
|
61
61
|
}
|
|
62
62
|
function applyBlock(op, owned, options, result) {
|
|
@@ -72,7 +72,7 @@ function applyBlock(op, owned, options, result) {
|
|
|
72
72
|
return owned;
|
|
73
73
|
}
|
|
74
74
|
write(op.path, upsertBlock(current, body), options);
|
|
75
|
-
result.changes.push(
|
|
75
|
+
result.changes.push({ action: block === undefined ? "add block to" : "update block in", path: op.path });
|
|
76
76
|
return entry;
|
|
77
77
|
}
|
|
78
78
|
// Returns true when the entry no longer needs tracking.
|
|
@@ -89,7 +89,7 @@ function removeEntry(entry, options, result) {
|
|
|
89
89
|
fs.rmSync(entry.path);
|
|
90
90
|
prune(path.dirname(entry.path));
|
|
91
91
|
}
|
|
92
|
-
result.changes.push(
|
|
92
|
+
result.changes.push({ action: "remove", path: entry.path });
|
|
93
93
|
return true;
|
|
94
94
|
}
|
|
95
95
|
const block = readBlock(current);
|
|
@@ -103,11 +103,11 @@ function removeEntry(entry, options, result) {
|
|
|
103
103
|
if (rest === "" && entry.created) {
|
|
104
104
|
if (!options.dryRun)
|
|
105
105
|
fs.rmSync(entry.path);
|
|
106
|
-
result.changes.push(
|
|
106
|
+
result.changes.push({ action: "remove", path: entry.path });
|
|
107
107
|
}
|
|
108
108
|
else {
|
|
109
109
|
write(entry.path, rest, options);
|
|
110
|
-
result.changes.push(
|
|
110
|
+
result.changes.push({ action: "remove block from", path: entry.path });
|
|
111
111
|
}
|
|
112
112
|
return true;
|
|
113
113
|
}
|
package/dist/build-info.json
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"commit":"
|
|
1
|
+
{"commit":"85a839f"}
|
package/dist/cli.js
CHANGED
|
@@ -2,9 +2,11 @@
|
|
|
2
2
|
import { parseArgs } from "node:util";
|
|
3
3
|
import { doctor, init, install, list, saveSource, scaffold, selfUpdate, setCheckHook, uninstall, update, version } from "./commands.js";
|
|
4
4
|
import { parseAgents } from "./targets.js";
|
|
5
|
+
import { claudePlugin, clackPrompts, installWizard, opensWizard, scaffoldWizard, uninstallWizard } from "./wizard.js";
|
|
5
6
|
const HELP = `dotagents: install curated agent skills and rules
|
|
6
7
|
|
|
7
8
|
Usage:
|
|
9
|
+
dotagents In a terminal, open the install wizard
|
|
8
10
|
dotagents install Install globally (default for all projects)
|
|
9
11
|
dotagents init Install into the current repository (commit the files)
|
|
10
12
|
dotagents scaffold Create starter AGENTS.md, CLAUDE.md, and settings in the current repository
|
|
@@ -22,8 +24,11 @@ Options:
|
|
|
22
24
|
--source <spec> With install: where self-update fetches dotagents from
|
|
23
25
|
-v, --version Print the version
|
|
24
26
|
-h, --help Print this help
|
|
27
|
+
|
|
28
|
+
In a terminal, install, scaffold, and uninstall open a wizard. --dry-run and
|
|
29
|
+
--force skip the wizard, and so does --source for install.
|
|
25
30
|
`;
|
|
26
|
-
function main(argv) {
|
|
31
|
+
async function main(argv) {
|
|
27
32
|
const { values, positionals } = parseArgs({
|
|
28
33
|
args: argv,
|
|
29
34
|
allowPositionals: true,
|
|
@@ -42,10 +47,19 @@ function main(argv) {
|
|
|
42
47
|
console.log(version());
|
|
43
48
|
return 0;
|
|
44
49
|
}
|
|
50
|
+
if (values.help) {
|
|
51
|
+
console.log(HELP);
|
|
52
|
+
return 0;
|
|
53
|
+
}
|
|
45
54
|
const [command, subcommand] = positionals;
|
|
46
|
-
|
|
55
|
+
const interactive = process.stdin.isTTY === true && process.stdout.isTTY === true;
|
|
56
|
+
if (opensWizard({ command, interactive, values })) {
|
|
57
|
+
const agents = values.agents === undefined ? undefined : parseAgents(values.agents);
|
|
58
|
+
return (await installWizard(clackPrompts, claudePlugin, { agents, cwd: process.cwd() })) ? 0 : 1;
|
|
59
|
+
}
|
|
60
|
+
if (!command) {
|
|
47
61
|
console.log(HELP);
|
|
48
|
-
return
|
|
62
|
+
return 1;
|
|
49
63
|
}
|
|
50
64
|
const options = { agents: parseAgents(values.agents), dryRun: values["dry-run"], force: values.force };
|
|
51
65
|
const which = values.global ? "global" : values.project ? "project" : undefined;
|
|
@@ -58,10 +72,16 @@ function main(argv) {
|
|
|
58
72
|
case "init":
|
|
59
73
|
return init(cwd, options) ? 0 : 1;
|
|
60
74
|
case "scaffold":
|
|
75
|
+
if (interactive && !options.dryRun && !options.force) {
|
|
76
|
+
const agents = values.agents === undefined ? undefined : options.agents;
|
|
77
|
+
return (await scaffoldWizard(clackPrompts, { agents, cwd })) ? 0 : 1;
|
|
78
|
+
}
|
|
61
79
|
return scaffold(cwd, options) ? 0 : 1;
|
|
62
80
|
case "update":
|
|
63
81
|
return update(cwd, which, options) ? 0 : 1;
|
|
64
82
|
case "uninstall":
|
|
83
|
+
if (interactive && !options.dryRun && !options.force)
|
|
84
|
+
return (await uninstallWizard(clackPrompts, { cwd, which })) ? 0 : 1;
|
|
65
85
|
return uninstall(cwd, which, options) ? 0 : 1;
|
|
66
86
|
case "doctor":
|
|
67
87
|
return doctor(cwd) ? 0 : 1;
|
|
@@ -81,7 +101,7 @@ function main(argv) {
|
|
|
81
101
|
}
|
|
82
102
|
}
|
|
83
103
|
try {
|
|
84
|
-
process.exitCode = main(process.argv.slice(2));
|
|
104
|
+
process.exitCode = await main(process.argv.slice(2));
|
|
85
105
|
}
|
|
86
106
|
catch (error) {
|
|
87
107
|
console.error(`dotagents: ${error instanceof Error ? error.message : String(error)}`);
|
package/dist/commands.js
CHANGED
|
@@ -9,7 +9,9 @@ import { fromStored, globalManifestPath, hash, projectManifestPath, readManifest
|
|
|
9
9
|
import { claudeHome, codexHome, configDir, packageRoot } from "./paths.js";
|
|
10
10
|
import { planInstall, planScaffold } from "./targets.js";
|
|
11
11
|
export const DEFAULT_SOURCE = "@igorlau/dotagents@latest";
|
|
12
|
-
const
|
|
12
|
+
export const UP_TO_DATE = "Already up to date.";
|
|
13
|
+
export const NOTHING_TO_UNINSTALL = "Nothing to uninstall.";
|
|
14
|
+
export const PLUGIN_HINT = "Claude Code gets the dotagents skills from the plugin. To install it, run `/plugin marketplace add igorlau/dotagents` and `/plugin install dotagents@dotagents` in Claude Code.";
|
|
13
15
|
// Release tags carry a real version. Builds from a branch carry X.Y.0-dev,
|
|
14
16
|
// so the commit tells them apart.
|
|
15
17
|
export function version() {
|
|
@@ -39,15 +41,51 @@ function existingProjectScope(cwd) {
|
|
|
39
41
|
const manifest = readManifest(projectManifestPath(root));
|
|
40
42
|
return manifest ? { mode: manifest.mode, root, manifestPath: projectManifestPath(root) } : undefined;
|
|
41
43
|
}
|
|
42
|
-
|
|
43
|
-
function
|
|
44
|
+
const PREVIEW = { dryRun: true, force: false };
|
|
45
|
+
function plan(scope, agents, options, uninstall, pending = []) {
|
|
44
46
|
const previous = readManifest(scope.manifestPath);
|
|
45
47
|
const catalog = loadCatalog();
|
|
46
|
-
const ops = uninstall ? [] : planInstall(catalog, scope.mode, agents, scope.root);
|
|
48
|
+
const ops = uninstall ? [] : planInstall(catalog, scope.mode, agents, scope.root, pending);
|
|
47
49
|
const result = apply(ops, fromStored(previous?.entries ?? [], scope.root), options);
|
|
50
|
+
const skills = uninstall ? (previous?.skills ?? []) : catalog.skills.map((skill) => skill.name);
|
|
51
|
+
return { result, skills };
|
|
52
|
+
}
|
|
53
|
+
/** Computes the changes of a global install without writing files or logging. */
|
|
54
|
+
export function previewInstall(agents) {
|
|
55
|
+
return plan(globalScope(), agents, PREVIEW, false).result;
|
|
56
|
+
}
|
|
57
|
+
/** Computes the changes of a project install into the repository that contains `cwd`, after `scaffold` creates `scaffoldFiles`. Throws outside a repository. */
|
|
58
|
+
export function previewInit(cwd, agents, { scaffoldFiles = [] } = {}) {
|
|
59
|
+
const scope = projectScope(cwd);
|
|
60
|
+
return plan(scope, agents, PREVIEW, false, scaffoldOps(scope.root, agents, scaffoldFiles)).result;
|
|
61
|
+
}
|
|
62
|
+
/** Returns the root of the repository that contains `cwd`. Throws outside a repository. */
|
|
63
|
+
export function projectRoot(cwd) {
|
|
64
|
+
return projectScope(cwd).root;
|
|
65
|
+
}
|
|
66
|
+
/** Lists the scaffold files for `agents` in the repository that contains `cwd`, and whether each one exists. Throws outside a repository. */
|
|
67
|
+
export function listScaffoldFiles(cwd, agents) {
|
|
68
|
+
return planScaffold(loadScaffold(), agents, projectRoot(cwd)).map((op) => ({ exists: fs.existsSync(op.path), path: op.path }));
|
|
69
|
+
}
|
|
70
|
+
/** Computes the changes of `scaffold` for `files` in the repository that contains `cwd`. Throws outside a repository. */
|
|
71
|
+
export function previewScaffold(cwd, agents, files) {
|
|
72
|
+
return apply(scaffoldOps(projectRoot(cwd), agents, files), [], PREVIEW);
|
|
73
|
+
}
|
|
74
|
+
function scaffoldOps(root, agents, files) {
|
|
75
|
+
return planScaffold(loadScaffold(), agents, root).filter((op) => files.includes(op.path));
|
|
76
|
+
}
|
|
77
|
+
/** Computes the changes of an uninstall for each existing install that `which` selects. */
|
|
78
|
+
export function previewUninstall(cwd, which) {
|
|
79
|
+
return selectScopes(cwd, which).map((scope) => ({
|
|
80
|
+
mode: scope.mode,
|
|
81
|
+
result: plan(scope, readManifest(scope.manifestPath).agents, PREVIEW, true).result,
|
|
82
|
+
root: scope.root,
|
|
83
|
+
}));
|
|
84
|
+
}
|
|
85
|
+
// Install, update, and uninstall all reduce to: apply a plan, then record it.
|
|
86
|
+
function run(scope, agents, options, uninstall = false) {
|
|
87
|
+
const { result, skills } = plan(scope, agents, options, uninstall);
|
|
48
88
|
report(result, options.dryRun);
|
|
49
|
-
if (!uninstall && scope.mode === "global" && agents.includes("claude") && !dotagentsPluginInstalled())
|
|
50
|
-
log(PLUGIN_HINT);
|
|
51
89
|
if (options.dryRun)
|
|
52
90
|
return result.problems.length === 0;
|
|
53
91
|
if (result.entries.length === 0) {
|
|
@@ -59,7 +97,7 @@ function run(scope, agents, options, uninstall = false) {
|
|
|
59
97
|
version: version(),
|
|
60
98
|
mode: scope.mode,
|
|
61
99
|
agents,
|
|
62
|
-
skills
|
|
100
|
+
skills,
|
|
63
101
|
entries: toStored(result.entries, scope.root),
|
|
64
102
|
updatedAt: new Date().toISOString(),
|
|
65
103
|
});
|
|
@@ -69,15 +107,22 @@ function run(scope, agents, options, uninstall = false) {
|
|
|
69
107
|
function report(result, dryRun) {
|
|
70
108
|
const prefix = dryRun ? "would " : "";
|
|
71
109
|
for (const change of result.changes)
|
|
72
|
-
log(` ${prefix}${change}`);
|
|
110
|
+
log(` ${prefix}${change.action} ${change.path}`);
|
|
73
111
|
for (const problem of result.problems)
|
|
74
112
|
log(` ! ${problem}`);
|
|
75
113
|
if (result.changes.length === 0 && result.problems.length === 0)
|
|
76
|
-
log(
|
|
114
|
+
log(` ${UP_TO_DATE}`);
|
|
77
115
|
}
|
|
78
|
-
export function install(options) {
|
|
116
|
+
export function install(options, pluginHint = true) {
|
|
79
117
|
log(`Installing dotagents ${version()} globally for ${options.agents.join(", ")}:`);
|
|
80
|
-
|
|
118
|
+
const ok = run(globalScope(), options.agents, options);
|
|
119
|
+
if (pluginHint)
|
|
120
|
+
logPluginHint(options.agents);
|
|
121
|
+
return ok;
|
|
122
|
+
}
|
|
123
|
+
function logPluginHint(agents) {
|
|
124
|
+
if (agents.includes("claude") && !dotagentsPluginInstalled())
|
|
125
|
+
log(PLUGIN_HINT);
|
|
81
126
|
}
|
|
82
127
|
export function init(cwd, options) {
|
|
83
128
|
const scope = projectScope(cwd);
|
|
@@ -89,10 +134,11 @@ export function init(cwd, options) {
|
|
|
89
134
|
}
|
|
90
135
|
// Scaffold files belong to the repository once written, so no manifest tracks
|
|
91
136
|
// them, and update and uninstall leave them alone.
|
|
92
|
-
export function scaffold(cwd, options) {
|
|
93
|
-
const root =
|
|
137
|
+
export function scaffold(cwd, options, { files } = {}) {
|
|
138
|
+
const root = projectRoot(cwd);
|
|
94
139
|
log(`Scaffolding agent instructions into ${root}:`);
|
|
95
|
-
const
|
|
140
|
+
const planned = files ?? listScaffoldFiles(cwd, options.agents).map((file) => file.path);
|
|
141
|
+
const result = apply(scaffoldOps(root, options.agents, planned), [], options);
|
|
96
142
|
report(result, options.dryRun);
|
|
97
143
|
if (!options.dryRun)
|
|
98
144
|
log("Review the files, keep AGENTS.md current as the project takes shape, and commit them.");
|
|
@@ -120,13 +166,15 @@ export function update(cwd, which, options) {
|
|
|
120
166
|
const manifest = readManifest(scope.manifestPath);
|
|
121
167
|
log(`Updating ${describe(scope)} to dotagents ${version()}:`);
|
|
122
168
|
ok = run(scope, manifest.agents, { ...options, agents: manifest.agents }) && ok;
|
|
169
|
+
if (scope.mode === "global")
|
|
170
|
+
logPluginHint(manifest.agents);
|
|
123
171
|
}
|
|
124
172
|
return ok;
|
|
125
173
|
}
|
|
126
174
|
export function uninstall(cwd, which, options) {
|
|
127
175
|
const scopes = selectScopes(cwd, which);
|
|
128
176
|
if (scopes.length === 0) {
|
|
129
|
-
log(
|
|
177
|
+
log(NOTHING_TO_UNINSTALL);
|
|
130
178
|
return true;
|
|
131
179
|
}
|
|
132
180
|
let ok = true;
|
|
@@ -187,7 +235,8 @@ function duplicateClaudeSkills() {
|
|
|
187
235
|
.filter((name) => name.startsWith("dot-"))
|
|
188
236
|
.map((name) => `${path.join(skillsDir, name)}: Claude Code also loads this skill from the dotagents plugin. Delete the directory.`);
|
|
189
237
|
}
|
|
190
|
-
|
|
238
|
+
/** Reports whether Claude Code lists the dotagents plugin in `installed_plugins.json`. */
|
|
239
|
+
export function dotagentsPluginInstalled() {
|
|
191
240
|
try {
|
|
192
241
|
const installed = JSON.parse(fs.readFileSync(path.join(claudeHome(), "plugins", "installed_plugins.json"), "utf8"));
|
|
193
242
|
return Object.keys(installed.plugins ?? {}).some((id) => id.startsWith("dotagents@"));
|
|
@@ -224,6 +273,11 @@ export function readSource() {
|
|
|
224
273
|
export function saveSource(source) {
|
|
225
274
|
writeConfig({ source });
|
|
226
275
|
}
|
|
276
|
+
/** Reports whether the plugin's `check` hook runs in the repository that contains `cwd`. */
|
|
277
|
+
export function checkHookEnabled(cwd) {
|
|
278
|
+
const root = repoRoot(cwd);
|
|
279
|
+
return root !== undefined && (readConfig().checkRepos ?? []).includes(fs.realpathSync(root));
|
|
280
|
+
}
|
|
227
281
|
/** Enables or disables the plugin's `check` hook for the repository that contains `cwd`. Throws outside a repository. */
|
|
228
282
|
export function setCheckHook(cwd, enabled, dryRun) {
|
|
229
283
|
const root = repoRoot(cwd);
|
|
@@ -242,6 +296,19 @@ export function setCheckHook(cwd, enabled, dryRun) {
|
|
|
242
296
|
export function selfUpdate(args) {
|
|
243
297
|
const source = readSource();
|
|
244
298
|
log(`Running the latest dotagents from ${source}:`);
|
|
245
|
-
const
|
|
299
|
+
const npx = npxCommand(["--yes", "--prefer-online", source, "update", ...args]);
|
|
300
|
+
const result = spawnSync(npx.command, npx.args, { shell: npx.shell, stdio: "inherit" });
|
|
246
301
|
return result.status === 0;
|
|
247
302
|
}
|
|
303
|
+
/**
|
|
304
|
+
* Builds the command that starts `npx`. On Windows, `npx` is `npx.cmd`, which Node starts only through a shell,
|
|
305
|
+
* so the arguments go into one quoted command line. `cmd.exe` still reads `"` and `%` inside quotes, so those throw.
|
|
306
|
+
*/
|
|
307
|
+
export function npxCommand(args, platform = process.platform) {
|
|
308
|
+
if (platform !== "win32")
|
|
309
|
+
return { args, command: "npx", shell: false };
|
|
310
|
+
const unsafe = args.find((arg) => /["%]/.test(arg));
|
|
311
|
+
if (unsafe !== undefined)
|
|
312
|
+
throw new Error(`Cannot pass ${unsafe} to npx on Windows. Remove the " and % characters.`);
|
|
313
|
+
return { args: [], command: ["npx", ...args.map((arg) => `"${arg}"`)].join(" "), shell: true };
|
|
314
|
+
}
|
package/dist/git.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import { spawnSync } from "node:child_process";
|
|
2
2
|
export function repoRoot(cwd) {
|
|
3
3
|
const result = spawnSync("git", ["rev-parse", "--show-toplevel"], { cwd, encoding: "utf8" });
|
|
4
|
-
if (result.error)
|
|
4
|
+
if (result.error && result.error.code !== "ENOENT")
|
|
5
5
|
throw result.error;
|
|
6
6
|
return result.status === 0 ? result.stdout.trim() : undefined;
|
|
7
7
|
}
|
package/dist/targets.js
CHANGED
|
@@ -1,9 +1,10 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
1
2
|
import path from "node:path";
|
|
2
3
|
import { agentsHome, claudeHome, codexHome, copilotHome } from "./paths.js";
|
|
3
4
|
export const AGENTS = ["claude", "codex", "copilot"];
|
|
4
5
|
const HEADER = "<!-- Managed by dotagents. Run `dotagents update` instead of editing this file. -->";
|
|
5
6
|
const RULES_FILE = "dotagents.md";
|
|
6
|
-
function layout(mode, root) {
|
|
7
|
+
function layout(mode, root, pending) {
|
|
7
8
|
if (mode === "global") {
|
|
8
9
|
return {
|
|
9
10
|
skillDirs: {
|
|
@@ -12,6 +13,7 @@ function layout(mode, root) {
|
|
|
12
13
|
copilot: path.join(agentsHome(), "skills"),
|
|
13
14
|
},
|
|
14
15
|
claudeRules: path.join(claudeHome(), "rules", RULES_FILE),
|
|
16
|
+
claudeRulesInAgentsMd: false,
|
|
15
17
|
codexRules: path.join(codexHome(), "AGENTS.md"),
|
|
16
18
|
// Copilot loads this file in every session; files in ~/.copilot/instructions/
|
|
17
19
|
// load only when their applyTo pattern matches a file being edited.
|
|
@@ -20,19 +22,23 @@ function layout(mode, root) {
|
|
|
20
22
|
}
|
|
21
23
|
// Copilot reads AGENTS.md too, so both agents share one block.
|
|
22
24
|
const agentsMd = path.join(root, "AGENTS.md");
|
|
25
|
+
const claudeMd = path.join(root, "CLAUDE.md");
|
|
26
|
+
const claudeRulesInAgentsMd = importsAgentsMd(pending.find((op) => op.path === claudeMd)?.content ?? readIfExists(claudeMd));
|
|
23
27
|
return {
|
|
24
28
|
skillDirs: {
|
|
25
29
|
claude: path.join(root, ".claude", "skills"),
|
|
26
30
|
codex: path.join(root, ".agents", "skills"),
|
|
27
31
|
copilot: path.join(root, ".agents", "skills"),
|
|
28
32
|
},
|
|
29
|
-
claudeRules: path.join(root, ".claude", "rules", RULES_FILE),
|
|
33
|
+
claudeRules: claudeRulesInAgentsMd ? agentsMd : path.join(root, ".claude", "rules", RULES_FILE),
|
|
34
|
+
claudeRulesInAgentsMd,
|
|
30
35
|
codexRules: agentsMd,
|
|
31
36
|
copilotRules: agentsMd,
|
|
32
37
|
};
|
|
33
38
|
}
|
|
34
|
-
|
|
35
|
-
|
|
39
|
+
/** Plans an install. `pending` holds the ops of another step that runs first, such as scaffold, so the plan sees the files that it writes. */
|
|
40
|
+
export function planInstall(catalog, mode, agents, root = "", pending = []) {
|
|
41
|
+
const target = layout(mode, root, pending);
|
|
36
42
|
const ops = new Map();
|
|
37
43
|
const add = (op) => ops.set(op.path, op);
|
|
38
44
|
for (const agent of agents) {
|
|
@@ -52,7 +58,9 @@ export function planInstall(catalog, mode, agents, root = "") {
|
|
|
52
58
|
}
|
|
53
59
|
const rules = catalog.rules.trim();
|
|
54
60
|
if (agents.includes("claude")) {
|
|
55
|
-
add(
|
|
61
|
+
add(target.claudeRulesInAgentsMd
|
|
62
|
+
? { kind: "block", path: target.claudeRules, content: rules }
|
|
63
|
+
: { kind: "file", path: target.claudeRules, content: `${HEADER}\n\n${rules}\n` });
|
|
56
64
|
}
|
|
57
65
|
if (agents.includes("codex"))
|
|
58
66
|
add({ kind: "block", path: target.codexRules, content: rules });
|
|
@@ -60,6 +68,17 @@ export function planInstall(catalog, mode, agents, root = "") {
|
|
|
60
68
|
add({ kind: "block", path: target.copilotRules, content: rules });
|
|
61
69
|
return [...ops.values()];
|
|
62
70
|
}
|
|
71
|
+
/** Reports whether the repository at `root` has a CLAUDE.md that does not import AGENTS.md. */
|
|
72
|
+
export function claudeMdSkipsAgentsMd(root) {
|
|
73
|
+
const claudeMd = readIfExists(path.join(root, "CLAUDE.md"));
|
|
74
|
+
return claudeMd !== undefined && !importsAgentsMd(claudeMd);
|
|
75
|
+
}
|
|
76
|
+
function importsAgentsMd(claudeMd) {
|
|
77
|
+
return claudeMd !== undefined && /^@(\.\/)?AGENTS\.md\s*$/m.test(claudeMd);
|
|
78
|
+
}
|
|
79
|
+
function readIfExists(file) {
|
|
80
|
+
return fs.existsSync(file) ? fs.readFileSync(file, "utf8") : undefined;
|
|
81
|
+
}
|
|
63
82
|
// AGENTS.md serves every agent; CLAUDE.md and .claude/ serve only Claude Code.
|
|
64
83
|
export function planScaffold(files, agents, root) {
|
|
65
84
|
const claudeOnly = (rel) => rel === "CLAUDE.md" || rel.startsWith(".claude/");
|
package/dist/wizard.js
ADDED
|
@@ -0,0 +1,248 @@
|
|
|
1
|
+
import { spawnSync } from "node:child_process";
|
|
2
|
+
import fs from "node:fs";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
import * as clack from "@clack/prompts";
|
|
5
|
+
import { checkHookEnabled, dotagentsPluginInstalled, init, install, listScaffoldFiles, NOTHING_TO_UNINSTALL, PLUGIN_HINT, previewInit, previewInstall, previewScaffold, previewUninstall, projectRoot, scaffold, setCheckHook, uninstall, UP_TO_DATE, } from "./commands.js";
|
|
6
|
+
import { repoRoot } from "./git.js";
|
|
7
|
+
import { homeDir } from "./paths.js";
|
|
8
|
+
import { AGENTS, claudeMdSkipsAgentsMd } from "./targets.js";
|
|
9
|
+
export const CANCEL = Symbol("cancel");
|
|
10
|
+
export const clackPrompts = {
|
|
11
|
+
async confirm(options) {
|
|
12
|
+
const answer = await clack.confirm(options);
|
|
13
|
+
return clack.isCancel(answer) ? CANCEL : answer;
|
|
14
|
+
},
|
|
15
|
+
async multiselect(options) {
|
|
16
|
+
const answer = await clack.multiselect(options);
|
|
17
|
+
return clack.isCancel(answer) ? CANCEL : answer;
|
|
18
|
+
},
|
|
19
|
+
note(message, title) {
|
|
20
|
+
clack.note(message, title);
|
|
21
|
+
},
|
|
22
|
+
async select(options) {
|
|
23
|
+
const answer = await clack.select(options);
|
|
24
|
+
return clack.isCancel(answer) ? CANCEL : answer;
|
|
25
|
+
},
|
|
26
|
+
};
|
|
27
|
+
export const claudePlugin = {
|
|
28
|
+
available() {
|
|
29
|
+
return spawnSync("claude", ["--version"], { stdio: "ignore" }).error === undefined;
|
|
30
|
+
},
|
|
31
|
+
install() {
|
|
32
|
+
const result = spawnSync("claude", ["plugin", "install", "dotagents", "--marketplace", "igorlau/dotagents"], { encoding: "utf8" });
|
|
33
|
+
if (result.error?.code === "ENOENT")
|
|
34
|
+
return { kind: "missing" };
|
|
35
|
+
if (result.error)
|
|
36
|
+
return { kind: "failed", output: result.error.message };
|
|
37
|
+
return result.status === 0 ? { kind: "installed" } : { kind: "failed", output: `${result.stdout}${result.stderr}`.trim() };
|
|
38
|
+
},
|
|
39
|
+
};
|
|
40
|
+
/** Whether the CLI opens the install wizard: in a terminal, for no command or `install`, with no flag other than `--agents`. */
|
|
41
|
+
export function opensWizard({ command, interactive, values }) {
|
|
42
|
+
if (!interactive)
|
|
43
|
+
return false;
|
|
44
|
+
if (command !== undefined && command !== "install")
|
|
45
|
+
return false;
|
|
46
|
+
return !values["dry-run"] && !values.force && !values.global && !values.project && values.source === undefined;
|
|
47
|
+
}
|
|
48
|
+
const AGENT_LABELS = { claude: "Claude Code", codex: "Codex", copilot: "GitHub Copilot" };
|
|
49
|
+
async function askAgents(prompts, agents) {
|
|
50
|
+
return (agents ??
|
|
51
|
+
prompts.multiselect({
|
|
52
|
+
initialValues: [...AGENTS],
|
|
53
|
+
message: "Which agents do you use?",
|
|
54
|
+
options: AGENTS.map((agent) => ({ label: AGENT_LABELS[agent], value: agent })),
|
|
55
|
+
required: true,
|
|
56
|
+
}));
|
|
57
|
+
}
|
|
58
|
+
/** Asks for the agents, the scope, and the Claude Code plugin, shows the changes, and installs after the user confirms. */
|
|
59
|
+
export async function installWizard(prompts, plugin, options) {
|
|
60
|
+
const agents = await askAgents(prompts, options.agents);
|
|
61
|
+
if (agents === CANCEL)
|
|
62
|
+
return cancelled();
|
|
63
|
+
const root = repoRoot(options.cwd);
|
|
64
|
+
const scope = root === undefined
|
|
65
|
+
? "global"
|
|
66
|
+
: await prompts.select({
|
|
67
|
+
initialValue: "global",
|
|
68
|
+
message: "Where do you want to install dotagents?",
|
|
69
|
+
options: [
|
|
70
|
+
{ label: "Global (Recommended)", value: "global" },
|
|
71
|
+
{ label: "This repository, for collaborators", value: "project" },
|
|
72
|
+
],
|
|
73
|
+
});
|
|
74
|
+
if (scope === CANCEL)
|
|
75
|
+
return cancelled();
|
|
76
|
+
const needsPlugin = scope === "global" && agents.includes("claude") && !dotagentsPluginInstalled();
|
|
77
|
+
const claudeFound = needsPlugin && plugin.available();
|
|
78
|
+
const installPlugin = claudeFound && (await prompts.confirm({ message: "Install the dotagents plugin for Claude Code?" }));
|
|
79
|
+
if (installPlugin === CANCEL)
|
|
80
|
+
return cancelled();
|
|
81
|
+
const setup = root === undefined ? [] : await askSetup(prompts, root);
|
|
82
|
+
if (setup === CANCEL)
|
|
83
|
+
return cancelled();
|
|
84
|
+
const scaffoldFiles = setup.includes("scaffold") ? newScaffoldFiles(options.cwd, agents) : [];
|
|
85
|
+
const scaffoldLines = scaffoldFiles.length > 0 ? summaryLines(previewScaffold(options.cwd, agents, scaffoldFiles)) : [];
|
|
86
|
+
const hintLines = root === undefined ? [] : importHint(root, agents, scaffoldFiles);
|
|
87
|
+
const preview = scope === "global" ? previewInstall(agents) : previewInit(options.cwd, agents, { scaffoldFiles });
|
|
88
|
+
const pluginLines = needsPlugin && !claudeFound ? [PLUGIN_HINT] : [];
|
|
89
|
+
const checkLines = root !== undefined && setup.includes("check") ? [`Enable the check hook in ${withTilde(root)}`] : [];
|
|
90
|
+
prompts.note([...scaffoldLines, ...hintLines, ...summaryLines(preview), ...pluginLines, ...checkLines].join("\n"), "Installation summary");
|
|
91
|
+
const proceed = await prompts.confirm({ message: "Proceed with installation?" });
|
|
92
|
+
if (proceed !== true)
|
|
93
|
+
return cancelled();
|
|
94
|
+
const installOptions = { agents, dryRun: false, force: false };
|
|
95
|
+
const scaffolded = scaffoldFiles.length > 0 ? scaffold(options.cwd, installOptions, { files: scaffoldFiles }) : true;
|
|
96
|
+
const installed = scope === "global" ? install(installOptions, false) : init(options.cwd, installOptions);
|
|
97
|
+
if (installPlugin)
|
|
98
|
+
installClaudePlugin(plugin);
|
|
99
|
+
if (claudeFound && !installPlugin)
|
|
100
|
+
console.log(PLUGIN_HINT);
|
|
101
|
+
if (setup.includes("check"))
|
|
102
|
+
setCheckHook(options.cwd, true, false);
|
|
103
|
+
for (const line of hintLines)
|
|
104
|
+
console.log(line);
|
|
105
|
+
return scaffolded && installed;
|
|
106
|
+
}
|
|
107
|
+
/** Offers the repository steps that apply, all unchecked: the `check` hook, and `scaffold` when the repository has no AGENTS.md. */
|
|
108
|
+
async function askSetup(prompts, root) {
|
|
109
|
+
const options = [];
|
|
110
|
+
if (hasCheckScript(root) && !checkHookEnabled(root))
|
|
111
|
+
options.push({ label: "Enable the check hook", value: "check" });
|
|
112
|
+
if (!fs.existsSync(path.join(root, "AGENTS.md")))
|
|
113
|
+
options.push({ label: "Create AGENTS.md and the agent instruction files", value: "scaffold" });
|
|
114
|
+
if (options.length === 0)
|
|
115
|
+
return [];
|
|
116
|
+
return prompts.multiselect({ initialValues: [], message: "Set up this repository?", options, required: false });
|
|
117
|
+
}
|
|
118
|
+
function hasCheckScript(root) {
|
|
119
|
+
return hasNpmCheck(root) || hasMakeCheck(root);
|
|
120
|
+
}
|
|
121
|
+
function hasNpmCheck(root) {
|
|
122
|
+
try {
|
|
123
|
+
return Boolean(JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")).scripts?.check);
|
|
124
|
+
}
|
|
125
|
+
catch {
|
|
126
|
+
return false;
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
function hasMakeCheck(root) {
|
|
130
|
+
try {
|
|
131
|
+
return /^check:/m.test(fs.readFileSync(path.join(root, "Makefile"), "utf8"));
|
|
132
|
+
}
|
|
133
|
+
catch {
|
|
134
|
+
return false;
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
function newScaffoldFiles(cwd, agents) {
|
|
138
|
+
return listScaffoldFiles(cwd, agents)
|
|
139
|
+
.filter((file) => !file.exists)
|
|
140
|
+
.map((file) => file.path);
|
|
141
|
+
}
|
|
142
|
+
/** Asks for the agents and the files, shows the files to create, and creates the checked files after the user confirms. Throws outside a repository. */
|
|
143
|
+
export async function scaffoldWizard(prompts, options) {
|
|
144
|
+
const root = projectRoot(options.cwd);
|
|
145
|
+
const agents = await askAgents(prompts, options.agents);
|
|
146
|
+
if (agents === CANCEL)
|
|
147
|
+
return cancelled();
|
|
148
|
+
const candidates = listScaffoldFiles(options.cwd, agents);
|
|
149
|
+
if (candidates.every((file) => file.exists)) {
|
|
150
|
+
console.log("Every scaffold file exists. Nothing changed.");
|
|
151
|
+
return true;
|
|
152
|
+
}
|
|
153
|
+
const files = await prompts.multiselect({
|
|
154
|
+
initialValues: candidates.filter((file) => !file.exists).map((file) => file.path),
|
|
155
|
+
message: "Which files do you want to create?",
|
|
156
|
+
options: candidates.map((file) => ({
|
|
157
|
+
disabled: file.exists,
|
|
158
|
+
hint: file.exists ? "exists, skip" : undefined,
|
|
159
|
+
label: path.relative(root, file.path),
|
|
160
|
+
value: file.path,
|
|
161
|
+
})),
|
|
162
|
+
required: true,
|
|
163
|
+
});
|
|
164
|
+
if (files === CANCEL)
|
|
165
|
+
return cancelled();
|
|
166
|
+
const hintLines = importHint(root, agents, files);
|
|
167
|
+
prompts.note([...summaryLines(previewScaffold(options.cwd, agents, files)), ...hintLines].join("\n"), "Scaffold summary");
|
|
168
|
+
const proceed = await prompts.confirm({ message: "Create these files?" });
|
|
169
|
+
if (proceed !== true)
|
|
170
|
+
return cancelled();
|
|
171
|
+
const ok = scaffold(options.cwd, { agents, dryRun: false, force: false }, { files });
|
|
172
|
+
for (const line of hintLines)
|
|
173
|
+
console.log(line);
|
|
174
|
+
return ok;
|
|
175
|
+
}
|
|
176
|
+
/** Asks which install to remove when both exist, shows the files to remove, and uninstalls after the user confirms. */
|
|
177
|
+
export async function uninstallWizard(prompts, options) {
|
|
178
|
+
const installs = previewUninstall(options.cwd, options.which);
|
|
179
|
+
const [first] = installs;
|
|
180
|
+
if (first === undefined) {
|
|
181
|
+
console.log(NOTHING_TO_UNINSTALL);
|
|
182
|
+
return true;
|
|
183
|
+
}
|
|
184
|
+
const choice = installs.length === 1
|
|
185
|
+
? first.mode
|
|
186
|
+
: await prompts.select({
|
|
187
|
+
message: "Which install do you want to remove?",
|
|
188
|
+
options: [...installs.map((install) => ({ label: installLabel(install), value: install.mode })), { label: "Both", value: "both" }],
|
|
189
|
+
});
|
|
190
|
+
if (choice === CANCEL)
|
|
191
|
+
return cancelled();
|
|
192
|
+
const chosen = installs.filter((install) => choice === "both" || install.mode === choice);
|
|
193
|
+
prompts.note(chosen.flatMap((install) => removalLines(install)).join("\n"), "Uninstall summary");
|
|
194
|
+
const proceed = await prompts.confirm({ message: "Remove these files?" });
|
|
195
|
+
if (proceed !== true)
|
|
196
|
+
return cancelled();
|
|
197
|
+
return uninstall(options.cwd, choice === "both" ? undefined : choice, { dryRun: false, force: false });
|
|
198
|
+
}
|
|
199
|
+
function installLabel(install) {
|
|
200
|
+
return install.mode === "global" ? "The global install" : `The project install in ${install.root}`;
|
|
201
|
+
}
|
|
202
|
+
function removalLines(install) {
|
|
203
|
+
if (install.result.changes.length > 0 || install.result.problems.length > 0)
|
|
204
|
+
return summaryLines(install.result);
|
|
205
|
+
return [`${installLabel(install)}: no files to remove. Only the manifest is deleted.`];
|
|
206
|
+
}
|
|
207
|
+
const IMPORT_HINT = "CLAUDE.md does not import AGENTS.md. Add the line `@AGENTS.md` to CLAUDE.md so Claude Code reads it, then run `dotagents update`.";
|
|
208
|
+
function importHint(root, agents, files) {
|
|
209
|
+
if (!agents.includes("claude") || !files.includes(path.join(root, "AGENTS.md")))
|
|
210
|
+
return [];
|
|
211
|
+
return claudeMdSkipsAgentsMd(root) ? [IMPORT_HINT] : [];
|
|
212
|
+
}
|
|
213
|
+
function installClaudePlugin(plugin) {
|
|
214
|
+
const result = plugin.install();
|
|
215
|
+
if (result.kind === "installed") {
|
|
216
|
+
console.log("The dotagents plugin for Claude Code is installed.");
|
|
217
|
+
return;
|
|
218
|
+
}
|
|
219
|
+
if (result.kind === "failed")
|
|
220
|
+
console.log(result.output);
|
|
221
|
+
console.log(PLUGIN_HINT);
|
|
222
|
+
}
|
|
223
|
+
function cancelled() {
|
|
224
|
+
console.log("Cancelled. Nothing changed.");
|
|
225
|
+
return false;
|
|
226
|
+
}
|
|
227
|
+
const SKILL_FILE = /^(.*[\\/]skills)[\\/][^\\/]+[\\/]/;
|
|
228
|
+
/** Counts the changes of each action in each target directory, then lists each problem. */
|
|
229
|
+
export function summaryLines(result) {
|
|
230
|
+
if (result.changes.length === 0 && result.problems.length === 0)
|
|
231
|
+
return [UP_TO_DATE];
|
|
232
|
+
const groups = new Map();
|
|
233
|
+
for (const change of result.changes) {
|
|
234
|
+
const group = withTilde(SKILL_FILE.exec(change.path)?.[1] ?? change.path);
|
|
235
|
+
const counts = groups.get(group) ?? new Map();
|
|
236
|
+
counts.set(change.action, (counts.get(change.action) ?? 0) + 1);
|
|
237
|
+
groups.set(group, counts);
|
|
238
|
+
}
|
|
239
|
+
const lines = [...groups].map(([group, counts]) => {
|
|
240
|
+
const actions = [...counts].map(([action, count]) => `${action} ${count} ${count === 1 ? "file" : "files"}`);
|
|
241
|
+
return `${group}: ${actions.join(", ")}`;
|
|
242
|
+
});
|
|
243
|
+
return [...lines, ...result.problems];
|
|
244
|
+
}
|
|
245
|
+
function withTilde(file) {
|
|
246
|
+
const home = homeDir();
|
|
247
|
+
return file.startsWith(home + path.sep) ? `~${file.slice(home.length)}` : file;
|
|
248
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@igorlau/dotagents",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.18",
|
|
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": {
|
|
@@ -32,6 +32,9 @@
|
|
|
32
32
|
"lint:content": "node scripts/lint-content.ts",
|
|
33
33
|
"check-upstream": "node scripts/check-upstream.ts"
|
|
34
34
|
},
|
|
35
|
+
"dependencies": {
|
|
36
|
+
"@clack/prompts": "1.9.0"
|
|
37
|
+
},
|
|
35
38
|
"devDependencies": {
|
|
36
39
|
"@types/node": "^24.0.0",
|
|
37
40
|
"typescript": "^5.9.0"
|
|
@@ -14,7 +14,7 @@ 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
|
-
- **Findings**: only on a second run, the review findings to fix. Fix these findings and nothing else.
|
|
17
|
+
- **Findings**: only on a second run, the review findings to fix. Fix these findings and nothing else. For each finding, fix every place in the task change that has the same problem.
|
|
18
18
|
|
|
19
19
|
When the task is missing, stop and report it.
|
|
20
20
|
|
|
@@ -13,12 +13,13 @@ Run the review step of a roadmap task. Follow the `dot-code-review` skill.
|
|
|
13
13
|
|
|
14
14
|
The prompt gives these fields:
|
|
15
15
|
|
|
16
|
-
- **Task**: the path of the roadmap task file. Check the change against its requirements and its "Out of scope" section.
|
|
16
|
+
- **Task**: the path of the roadmap task file. Check the change against its requirements and its "Out of scope" section. Also read the `## Requirements` section of the roadmap `README.md`. Check the change against every non-negotiable (`NN`) and against each business rule (`BR`) that the task names. Report a breached `NN` as a `high` finding.
|
|
17
17
|
- **Handoff**: the replies of the earlier steps.
|
|
18
|
+
- **Findings**: only on a fix run, the findings of the earlier review that the implementer fixed. Check that each one is gone, and that each fix did not break other code of the task. Report a finding that is still there again.
|
|
18
19
|
|
|
19
|
-
When
|
|
20
|
+
When the task or the handoff is missing, stop and report it.
|
|
20
21
|
|
|
21
|
-
The target is the uncommitted change: `git diff HEAD`, plus the untracked files that `git status --short` lists.
|
|
22
|
+
The target is the uncommitted change: `git diff HEAD`, plus the untracked files that `git status --short` lists. Review the whole target on each run, also on a fix run. Report every finding at every severity in this review, so that no finding waits for a later round. Keep the code as it is. Delete each test that you write to prove a finding.
|
|
22
23
|
|
|
23
24
|
Do not commit, and do not tick the roadmap checkbox.
|
|
24
25
|
|
|
@@ -28,7 +28,7 @@ Run the steps in this order. For each step, start a new agent of the named type,
|
|
|
28
28
|
| ---- | ----- | ------------- |
|
|
29
29
|
| 1. Implement | `dotagents:dot-implementer` | Task |
|
|
30
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 |
|
|
31
|
+
| 3. Review | `dotagents:dot-reviewer` | Task, Handoff: the replies of steps 1 and 2, Findings: only on a fix run |
|
|
32
32
|
|
|
33
33
|
Write the prompt as labeled fields, and leave out a field that the step does not take:
|
|
34
34
|
|
|
@@ -36,9 +36,11 @@ Write the prompt as labeled fields, and leave out a field that the step does not
|
|
|
36
36
|
**Task:** <path of the task file>
|
|
37
37
|
**Handoff:**
|
|
38
38
|
<the replies of the earlier steps, unchanged>
|
|
39
|
+
**Findings:**
|
|
40
|
+
<the findings that the user named, unchanged>
|
|
39
41
|
```
|
|
40
42
|
|
|
41
|
-
Copy the replies unchanged, because the agents read their fields.
|
|
43
|
+
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.
|
|
42
44
|
|
|
43
45
|
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:
|
|
44
46
|
|
|
@@ -61,7 +63,7 @@ Done when the review reply arrived, or the flow stopped.
|
|
|
61
63
|
|
|
62
64
|
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:
|
|
63
65
|
|
|
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.
|
|
66
|
+
- **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. Give step 3 the same **Findings** field. The review target stays the full uncommitted change of the task, not the files that the fix changed.
|
|
65
67
|
- **Accept**: the user accepts the findings that remain.
|
|
66
68
|
|
|
67
69
|
Done when the user accepts.
|
|
@@ -4,6 +4,6 @@ Inline steps for the [`dot-flow`](../SKILL.md) skill, for an agent that cannot s
|
|
|
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
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>`.
|
|
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>`. 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. Review the whole target, also on a fix run. On a fix run, also check that each fixed finding is gone, and that each fix did not break other code. Report every finding at every severity, and keep the code as it is. Delete each test that you write to prove a finding.
|
|
8
8
|
|
|
9
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.
|
|
@@ -11,7 +11,7 @@ Turn a request, an approved plan, or a roadmap task into a production code chang
|
|
|
11
11
|
|
|
12
12
|
Identify the source of the work:
|
|
13
13
|
|
|
14
|
-
- **Roadmap task**: a task file from `dot-roadmap`, or a roadmap directory. With only a directory, pick the lowest-id unticked task whose blockers are all ticked in its `README.md`. If a named task has an unticked blocker, stop and name it. Read the task file and the roadmap's decisions in full. The task's "Out of scope" is a hard boundary.
|
|
14
|
+
- **Roadmap task**: a task file from `dot-roadmap`, or a roadmap directory. With only a directory, pick the lowest-id unticked task whose blockers are all ticked in its `README.md`. If a named task has an unticked blocker, stop and name it. Read the task file and the roadmap's requirements and decisions in full. The task's "Out of scope" is a hard boundary.
|
|
15
15
|
- **Approved plan**: the plan in this conversation, from `dot-plan` or the user.
|
|
16
16
|
- **Request**: anything else.
|
|
17
17
|
|
|
@@ -40,7 +40,7 @@ Run the type checker and the linter. They are hard checks: fix each error that t
|
|
|
40
40
|
|
|
41
41
|
Check every acceptance criterion one by one. When only an expected failure or a test that does not exist yet blocks a criterion, leave the criterion open for the test step, and list it in the handoff.
|
|
42
42
|
|
|
43
|
-
When a hard check or an unexpected failure stays red, or the task or plan turns out wrong (a fact contradicts it, or it needs work outside its scope), stop. Report the check that failed or the fact that conflicts, and propose a change to the task or plan. Keep the task file, the roadmap's decisions, and the plan as they are until the user agrees, and keep the change inside its scope.
|
|
43
|
+
When a hard check or an unexpected failure stays red, or the task or plan turns out wrong (a fact contradicts it, or it needs work outside its scope), stop. Report the check that failed or the fact that conflicts, and propose a change to the task or plan. Keep the task file, the roadmap's requirements and decisions, and the plan as they are until the user agrees, and keep the change inside its scope.
|
|
44
44
|
|
|
45
45
|
Do not tick the roadmap checkbox. The `dot-commit` skill ticks it after the review step.
|
|
46
46
|
|
|
@@ -19,19 +19,32 @@ Read the code, tests, configuration, and docs that the change touches. Trace eac
|
|
|
19
19
|
|
|
20
20
|
Facts are your job: look them up. Do not ask the user. Done when you can name every file you expect to change and why.
|
|
21
21
|
|
|
22
|
-
## 3.
|
|
22
|
+
## 3. List the requirements
|
|
23
|
+
|
|
24
|
+
List the requirements in four categories, in this order. Give each requirement an ID with the category prefix and a number, such as `FR2`:
|
|
25
|
+
|
|
26
|
+
- **User needs** (`UN`): who uses the change, and what they must be able to do.
|
|
27
|
+
- **Functional requirements** (`FR`): the behavior that the system must have.
|
|
28
|
+
- **Business rules** (`BR`): the domain constraints and policies, such as "a refund cannot exceed the payment".
|
|
29
|
+
- **Non-negotiables** (`NN`): the hard limits that no trade-off can break, such as security, compatibility, a performance budget, or "no new dependency".
|
|
30
|
+
|
|
31
|
+
Take the requirements from the request, the code, and the docs. Ask the user only for the items that you cannot find there. Write "none" for an empty category. Show the lists, and wait for the user to approve them.
|
|
32
|
+
|
|
33
|
+
Done when the user approves the four lists.
|
|
34
|
+
|
|
35
|
+
## 4. Surface decisions
|
|
23
36
|
|
|
24
37
|
List the choices that the facts do not settle: behavior in edge cases, trade-offs, names that users see, anything hard to reverse. Give your recommendation for each one.
|
|
25
38
|
|
|
26
39
|
If the list is long or the decisions depend on each other, use the `dot-grilling` skill to resolve them with the user. Done when every decision has an answer or is marked as an open question in the plan.
|
|
27
40
|
|
|
28
|
-
##
|
|
41
|
+
## 5. Show entity schemas
|
|
29
42
|
|
|
30
43
|
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.
|
|
31
44
|
|
|
32
45
|
Done when the user approves each schema, or the change touches no domain entity.
|
|
33
46
|
|
|
34
|
-
##
|
|
47
|
+
## 6. Slice the work
|
|
35
48
|
|
|
36
49
|
Write the steps. For each step, include:
|
|
37
50
|
|
|
@@ -42,13 +55,21 @@ Put the removal steps first: delete the dead code, redundant checks, and stubs t
|
|
|
42
55
|
|
|
43
56
|
Done when every step has a check that can fail, and the last check matches the done criterion.
|
|
44
57
|
|
|
45
|
-
##
|
|
58
|
+
## 7. Present and wait
|
|
46
59
|
|
|
47
60
|
Show the plan in this shape:
|
|
48
61
|
|
|
49
62
|
```markdown
|
|
50
63
|
**Goal:** <one sentence>
|
|
51
64
|
**Done when:** <done criterion>
|
|
65
|
+
|
|
66
|
+
## Requirements
|
|
67
|
+
|
|
68
|
+
- **User needs:** UN1: <need>, or none
|
|
69
|
+
- **Functional requirements:** FR1: <requirement>, or none
|
|
70
|
+
- **Business rules:** BR1: <rule>, or none
|
|
71
|
+
- **Non-negotiables:** NN1: <limit>, or none
|
|
72
|
+
|
|
52
73
|
**Schemas:** <the approved entity schemas, or none>
|
|
53
74
|
|
|
54
75
|
1. <change>. Check: <command or observation>
|
|
@@ -58,4 +79,8 @@ Show the plan in this shape:
|
|
|
58
79
|
**Risks:** <what could make the plan wrong>
|
|
59
80
|
```
|
|
60
81
|
|
|
61
|
-
|
|
82
|
+
Ask the user where to write the plan, and offer `.tmp/plans/<plan-slug>/plan.md` at the repository root as the default. Wait for the user's approval before you change any file.
|
|
83
|
+
|
|
84
|
+
After the approval, write the plan to that path in the same shape. For a path under `.tmp`, first run `git check-ignore -q .tmp`: if Git does not ignore `.tmp`, stop and tell the user. Do not edit `.gitignore`. Write any other path that the user picks.
|
|
85
|
+
|
|
86
|
+
When the plan changes during the work, update the plan file and say what changed.
|
|
@@ -11,9 +11,13 @@ A roadmap splits a plan into **phases**, and each phase into **tasks**. A phase
|
|
|
11
11
|
|
|
12
12
|
## 1. Load the plan
|
|
13
13
|
|
|
14
|
-
|
|
14
|
+
Take the plan from the first of these sources that exists:
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
1. The path or URL that the user passed. Read it in full.
|
|
17
|
+
2. The plan in this conversation, usually from `dot-plan`.
|
|
18
|
+
3. The plan files under `.tmp/plans/`. With one file, use it. With more than one, ask the user which one.
|
|
19
|
+
|
|
20
|
+
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), the requirements with their IDs, and every decision the plan made.
|
|
17
21
|
|
|
18
22
|
## 2. Gather facts
|
|
19
23
|
|
|
@@ -42,7 +46,9 @@ Split each phase into tasks. Each task:
|
|
|
42
46
|
|
|
43
47
|
When one mechanical change breaks many call sites at once, read [`references/wide-refactor.md`](references/wide-refactor.md).
|
|
44
48
|
|
|
45
|
-
|
|
49
|
+
When a bullet of a task's requirements implements a functional requirement (`FR`) or a business rule (`BR`), start the bullet with its ID. User needs (`UN`) and non-negotiables (`NN`) apply to the whole roadmap: they stay in `README.md`, and no task claims them.
|
|
50
|
+
|
|
51
|
+
Done when every `FR` and `BR` belongs to at least one task or to the roadmap's out-of-scope list, every decision belongs to exactly one task or to that list, and every task has acceptance criteria that can fail.
|
|
46
52
|
|
|
47
53
|
## 5. Review with the user
|
|
48
54
|
|
|
@@ -68,12 +74,20 @@ Write to `.tmp/roadmaps/<roadmap-slug>/` at the repository root. First run `git
|
|
|
68
74
|
└── 01-<task-slug>.md
|
|
69
75
|
```
|
|
70
76
|
|
|
71
|
-
`README.md` is the index and the single source of truth for decisions; task files link to it and do not restate them. Put the entity schemas that the user approved in `dot-plan` in the decisions:
|
|
77
|
+
`README.md` is the index and the single source of truth for requirements and decisions; task files link to it and do not restate them. Copy the requirements with their IDs from the plan, because the plan file can be deleted. Put the entity schemas that the user approved in `dot-plan` in the decisions:
|
|
72
78
|
|
|
73
79
|
```markdown
|
|
74
80
|
# <Roadmap title>
|
|
75
81
|
|
|
76
82
|
**Destination:** <what is true when the roadmap is done>
|
|
83
|
+
**Plan:** <path of the plan file, or none>
|
|
84
|
+
|
|
85
|
+
## Requirements
|
|
86
|
+
|
|
87
|
+
- **User needs:** UN1: <need>, or none
|
|
88
|
+
- **Functional requirements:** FR1: <requirement>, or none
|
|
89
|
+
- **Business rules:** BR1: <rule>, or none
|
|
90
|
+
- **Non-negotiables:** NN1: <limit>, or none
|
|
77
91
|
|
|
78
92
|
## Decisions
|
|
79
93
|
|
|
@@ -105,7 +119,7 @@ Each task file:
|
|
|
105
119
|
|
|
106
120
|
## Requirements
|
|
107
121
|
|
|
108
|
-
- <what the change must do, specific enough to build without the conversation>
|
|
122
|
+
- <FR or BR ID>: <what the change must do, specific enough to build without the conversation>
|
|
109
123
|
- <files or modules it touches, when known>
|
|
110
124
|
|
|
111
125
|
## Out of scope
|