@igorlau/dotagents 1.0.15 → 1.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +39 -45
  2. package/THIRD_PARTY_NOTICES.md +1 -1
  3. package/dist/apply.js +6 -6
  4. package/dist/build-info.json +1 -1
  5. package/dist/cli.js +24 -4
  6. package/dist/commands.js +70 -16
  7. package/dist/git.js +1 -1
  8. package/dist/targets.js +24 -5
  9. package/dist/wizard.js +248 -0
  10. package/package.json +5 -1
  11. package/plugin/.claude-plugin/plugin.json +1 -1
  12. package/plugin/agents/dot-implementer.md +4 -17
  13. package/plugin/agents/dot-reviewer.md +4 -3
  14. package/plugin/agents/dot-tester.md +5 -13
  15. package/plugin/hooks/check.mjs +37 -11
  16. package/plugin/hooks/hooks.json +30 -0
  17. package/plugin/hooks/rules.mjs +27 -0
  18. package/plugin/rules/code-style.md +1 -1
  19. package/plugin/rules/core.md +2 -2
  20. package/plugin/rules/ponytail.md +1 -1
  21. package/plugin/rules/ponytail.upstream.json +1 -1
  22. package/plugin/rules/writing.md +3 -4
  23. package/plugin/rules/writing.upstream.json +1 -1
  24. package/plugin/scaffold/AGENTS.md.tmpl +2 -2
  25. package/plugin/skills/dot-code-review/SKILL.md +1 -3
  26. package/plugin/skills/dot-commit/SKILL.md +1 -5
  27. package/plugin/skills/dot-correct/SKILL.md +1 -3
  28. package/plugin/skills/dot-debug/SKILL.md +4 -6
  29. package/plugin/skills/dot-debug/UPSTREAM.json +1 -1
  30. package/plugin/skills/dot-docs-writing/SKILL.md +1 -3
  31. package/plugin/skills/dot-flow/SKILL.md +29 -29
  32. package/plugin/skills/dot-flow/references/inline.md +5 -38
  33. package/plugin/skills/dot-grilling/SKILL.md +1 -3
  34. package/plugin/skills/dot-grilling/UPSTREAM.json +1 -1
  35. package/plugin/skills/dot-handoff/SKILL.md +1 -3
  36. package/plugin/skills/dot-handoff/UPSTREAM.json +1 -1
  37. package/plugin/skills/dot-implement/SKILL.md +12 -9
  38. package/plugin/skills/dot-plan/SKILL.md +33 -12
  39. package/plugin/skills/dot-plan/references/entity-schemas.md +3 -3
  40. package/plugin/skills/dot-roadmap/SKILL.md +21 -11
  41. package/plugin/skills/dot-roadmap/agents/openai.yaml +5 -0
  42. package/plugin/skills/dot-testing/SKILL.md +2 -5
  43. package/plugin/skills/dot-testing/references/after-implement.md +23 -0
  44. package/plugin/skills/dot-writing-for-agents/SKILL.md +1 -3
  45. package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +1 -1
  46. package/plugin/skills/dot-grill-me/SKILL.md +0 -11
  47. package/plugin/skills/dot-grill-me/UPSTREAM.json +0 -8
  48. package/plugin/skills/dot-grill-me/agents/openai.yaml +0 -5
  49. package/plugin/skills/dot-testing/references/modes.md +0 -32
package/README.md CHANGED
@@ -1,42 +1,36 @@
1
1
  # dotagents
2
2
 
3
3
  dotagents gives Claude Code, OpenAI Codex, and GitHub Copilot one AI workflow
4
- for every project. The workflow plans a change, writes tests and code in small
5
- steps, reviews the result, and asks for your approval between the steps.
4
+ for every project. The workflow plans a change, writes code and tests in small
5
+ steps, verifies each step, reviews the result, and asks for your decision.
6
6
 
7
7
  dotagents has two parts:
8
8
 
9
- - A plugin with skills, agents, and an end-of-turn hook. Claude Code, the
9
+ - A plugin with skills, agents, and hooks. Claude Code, the
10
10
  Copilot CLI, and VS Code load the plugin.
11
11
  - A CLI that installs the always-on rules for all three coding agents, and the
12
12
  skills for Codex and Copilot.
13
13
 
14
14
  ## Install
15
15
 
16
- To install the plugin, run the following commands in Claude Code:
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 install
19
+ npx --yes @igorlau/dotagents
31
20
  ```
32
21
 
33
- The plugin hook runs the `check` script of a repository at the end of each
34
- turn that changes files. The hook runs only in a repository that you enable.
35
- To enable it, run the following command in the repository:
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
- ```bash
38
- npx --yes @igorlau/dotagents check enable
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:
@@ -86,17 +80,19 @@ Run `scaffold` before `init`. `init` adds a block to `AGENTS.md`, and
86
80
  ## The flow
87
81
 
88
82
  The following diagram shows the full flow, from an idea to the commits of one
89
- task. The agent stops for your approval at each "approve" or "go":
83
+ task. The agent stops for your decision at each "approve", "fix", or "accept":
90
84
 
91
85
  ```mermaid
92
86
  sequenceDiagram
93
87
  actor User
94
88
  participant Main as Main session
95
89
  participant Agents as Step agents
96
- User->>Main: dot-grill-me with an idea
90
+ User->>Main: dot-grilling with an idea
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
@@ -106,24 +102,23 @@ sequenceDiagram
106
102
  User->>Main: Approve the roadmap
107
103
  loop Each task
108
104
  User->>Main: dot-flow with the task file
109
- Main->>Agents: 1. Test stubs (dot-tester)
105
+ Main->>Agents: 1. Production code (dot-implementer)
110
106
  Agents-->>Main: Reply
111
- Main-->>User: Summary
112
- User->>Main: go
113
- Main->>Agents: 2. Production code (dot-implementer)
107
+ Main->>Main: Run the checks of the reply
108
+ Main->>Agents: 2. Tests (dot-tester)
114
109
  Agents-->>Main: Reply
115
- Main-->>User: Summary
116
- User->>Main: go
117
- Main->>Agents: 3. Test fill (dot-tester)
118
- Agents-->>Main: Reply
119
- Main-->>User: Summary
120
- User->>Main: go
121
- Main->>Agents: 4. Review (dot-reviewer)
110
+ Main->>Main: Run the tests of the reply
111
+ Main->>Agents: 3. Review (dot-reviewer)
122
112
  Agents-->>Main: Findings
123
113
  Main-->>User: Findings
124
- break A blocker or a high finding
114
+ break A blocker, or a check that differs from the reply
125
115
  Main-->>User: Stop. The files stay as they are.
126
116
  end
117
+ opt Fix
118
+ User->>Main: Fix these findings
119
+ Main->>Agents: Steps 1 to 3 again
120
+ end
121
+ User->>Main: Accept
127
122
  User->>Main: dot-commit
128
123
  Main-->>User: Each commit for approval
129
124
  User->>Main: Approve
@@ -131,8 +126,8 @@ sequenceDiagram
131
126
  end
132
127
  ```
133
128
 
134
- `dot-flow` never commits. In Codex and Copilot, `dot-flow` runs the four steps
135
- in the main session, with the same approvals.
129
+ `dot-flow` never commits. In Codex and Copilot, `dot-flow` runs the three steps
130
+ in the main session, with the same verification and stops.
136
131
 
137
132
  To learn the workflow step by step, read the [guide](docs/guide/README.md).
138
133
 
@@ -163,17 +158,16 @@ agreements, the smallest complete change from
163
158
  [ponytail](https://github.com/DietrichGebert/ponytail), code comments, code
164
159
  style, and writing.
165
160
 
166
- The 15 skills in [`plugin/skills/`](plugin/skills/) load when a task needs
161
+ The 14 skills in [`plugin/skills/`](plugin/skills/) load when a task needs
167
162
  them:
168
163
 
169
164
  | Skill | Purpose |
170
165
  | ----- | ------- |
171
- | `dot-grill-me` | Start an interview that makes a plan clear. |
172
- | `dot-grilling` | Run the interview method of `dot-grill-me`. |
173
- | `dot-plan` | Plan a change as small, verifiable steps, with entity schemas. |
166
+ | `dot-grilling` | Run an interview, in rounds of questions, that makes a plan clear. |
167
+ | `dot-plan` | Plan a change as small, verifiable steps, with requirements and entity schemas. |
174
168
  | `dot-roadmap` | Split a plan into phases and tasks that each stand alone. |
175
- | `dot-flow` | Take a roadmap task through test stubs, code, test fill, and review, with an approval after each step. |
176
- | `dot-testing` | Write tests with a makeSut factory, as stubs before the code or in full after it. |
169
+ | `dot-flow` | Take a roadmap task through code, tests, and review, verify each step, and stop for your decision after the review. |
170
+ | `dot-testing` | Write tests with a makeSut factory, alone or after `dot-implement`. |
177
171
  | `dot-implement` | Write the code of a change or roadmap task to the standards of the repository and the language. |
178
172
  | `dot-code-review` | Review a diff for correctness bugs and maintainability problems. |
179
173
  | `dot-comments` | Delete the comments in a diff that no exception protects. |
@@ -190,7 +184,7 @@ context:
190
184
 
191
185
  | Agent | Purpose |
192
186
  | ----- | ------- |
193
- | `dot-tester` | Write the test stubs, or fill them after the code exists. |
187
+ | `dot-tester` | Write the tests of a task after the code exists. |
194
188
  | `dot-implementer` | Write the production code of a task. |
195
189
  | `dot-reviewer` | Review the changes of a task. |
196
190
 
@@ -4,7 +4,7 @@ dotagents includes content from the following projects.
4
4
 
5
5
  ## mattpocock/skills
6
6
 
7
- The `dot-debug`, `dot-grill-me`, `dot-grilling`, `dot-handoff`, and `dot-writing-for-agents`
7
+ The `dot-debug`, `dot-grilling`, `dot-handoff`, and `dot-writing-for-agents`
8
8
  skills come from [mattpocock/skills](https://github.com/mattpocock/skills).
9
9
  Each skill's `UPSTREAM.json` file records the source commit and any local
10
10
  changes. The project is licensed under the MIT License:
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(`create ${op.path}`);
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(`update ${op.path}`);
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(`${block === undefined ? "add block to" : "update block in"} ${op.path}`);
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(`remove ${entry.path}`);
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(`remove ${entry.path}`);
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(`remove block from ${entry.path}`);
110
+ result.changes.push({ action: "remove block from", path: entry.path });
111
111
  }
112
112
  return true;
113
113
  }
@@ -1 +1 @@
1
- {"commit":"0b97ba2"}
1
+ {"commit":"386b124"}
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
- if (values.help || !command) {
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 command || values.help ? 0 : 1;
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 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.";
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
- // Install, update, and uninstall all reduce to: apply a plan, then record it.
43
- function run(scope, agents, options, uninstall = false) {
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: uninstall ? (previous?.skills ?? []) : catalog.skills.map((skill) => skill.name),
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(" Already up to date.");
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
- return run(globalScope(), options.agents, options);
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 = projectScope(cwd).root;
137
+ export function scaffold(cwd, options, { files } = {}) {
138
+ const root = projectRoot(cwd);
94
139
  log(`Scaffolding agent instructions into ${root}:`);
95
- const result = apply(planScaffold(loadScaffold(), options.agents, root), [], options);
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("Nothing to uninstall.");
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
- function dotagentsPluginInstalled() {
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);
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
- export function planInstall(catalog, mode, agents, root = "") {
35
- const target = layout(mode, root);
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({ kind: "file", path: target.claudeRules, content: `${HEADER}\n\n${rules}\n` });
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/");