@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.
- package/README.md +39 -45
- package/THIRD_PARTY_NOTICES.md +1 -1
- package/dist/apply.js +6 -6
- package/dist/build-info.json +1 -1
- package/dist/cli.js +24 -4
- package/dist/commands.js +70 -16
- package/dist/git.js +1 -1
- package/dist/targets.js +24 -5
- package/dist/wizard.js +248 -0
- package/package.json +5 -1
- package/plugin/.claude-plugin/plugin.json +1 -1
- package/plugin/agents/dot-implementer.md +4 -17
- package/plugin/agents/dot-reviewer.md +4 -3
- package/plugin/agents/dot-tester.md +5 -13
- package/plugin/hooks/check.mjs +37 -11
- package/plugin/hooks/hooks.json +30 -0
- package/plugin/hooks/rules.mjs +27 -0
- package/plugin/rules/code-style.md +1 -1
- package/plugin/rules/core.md +2 -2
- package/plugin/rules/ponytail.md +1 -1
- package/plugin/rules/ponytail.upstream.json +1 -1
- package/plugin/rules/writing.md +3 -4
- package/plugin/rules/writing.upstream.json +1 -1
- package/plugin/scaffold/AGENTS.md.tmpl +2 -2
- package/plugin/skills/dot-code-review/SKILL.md +1 -3
- package/plugin/skills/dot-commit/SKILL.md +1 -5
- package/plugin/skills/dot-correct/SKILL.md +1 -3
- package/plugin/skills/dot-debug/SKILL.md +4 -6
- package/plugin/skills/dot-debug/UPSTREAM.json +1 -1
- package/plugin/skills/dot-docs-writing/SKILL.md +1 -3
- package/plugin/skills/dot-flow/SKILL.md +29 -29
- package/plugin/skills/dot-flow/references/inline.md +5 -38
- package/plugin/skills/dot-grilling/SKILL.md +1 -3
- package/plugin/skills/dot-grilling/UPSTREAM.json +1 -1
- package/plugin/skills/dot-handoff/SKILL.md +1 -3
- package/plugin/skills/dot-handoff/UPSTREAM.json +1 -1
- package/plugin/skills/dot-implement/SKILL.md +12 -9
- package/plugin/skills/dot-plan/SKILL.md +33 -12
- package/plugin/skills/dot-plan/references/entity-schemas.md +3 -3
- package/plugin/skills/dot-roadmap/SKILL.md +21 -11
- package/plugin/skills/dot-roadmap/agents/openai.yaml +5 -0
- package/plugin/skills/dot-testing/SKILL.md +2 -5
- package/plugin/skills/dot-testing/references/after-implement.md +23 -0
- package/plugin/skills/dot-writing-for-agents/SKILL.md +1 -3
- package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +1 -1
- package/plugin/skills/dot-grill-me/SKILL.md +0 -11
- package/plugin/skills/dot-grill-me/UPSTREAM.json +0 -8
- package/plugin/skills/dot-grill-me/agents/openai.yaml +0 -5
- package/plugin/skills/dot-testing/references/modes.md +0 -32
package/README.md
CHANGED
|
@@ -1,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
|
|
5
|
-
steps, reviews the result, and asks for your
|
|
4
|
+
for every project. The workflow plans a change, writes code and tests in small
|
|
5
|
+
steps, verifies each step, reviews the result, and asks for your decision.
|
|
6
6
|
|
|
7
7
|
dotagents has two parts:
|
|
8
8
|
|
|
9
|
-
- A plugin with skills, agents, and
|
|
9
|
+
- A plugin with skills, agents, and hooks. Claude Code, the
|
|
10
10
|
Copilot CLI, and VS Code load the plugin.
|
|
11
11
|
- A CLI that installs the always-on rules for all three coding agents, and the
|
|
12
12
|
skills for Codex and Copilot.
|
|
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:
|
|
@@ -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
|
|
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-
|
|
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.
|
|
105
|
+
Main->>Agents: 1. Production code (dot-implementer)
|
|
110
106
|
Agents-->>Main: Reply
|
|
111
|
-
Main
|
|
112
|
-
|
|
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
|
|
116
|
-
|
|
117
|
-
Main->>Agents: 3. Test fill (dot-tester)
|
|
118
|
-
Agents-->>Main: Reply
|
|
119
|
-
Main-->>User: Summary
|
|
120
|
-
User->>Main: go
|
|
121
|
-
Main->>Agents: 4. Review (dot-reviewer)
|
|
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
|
|
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
|
|
135
|
-
in the main session, with the same
|
|
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
|
|
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-
|
|
172
|
-
| `dot-
|
|
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
|
|
176
|
-
| `dot-testing` | Write tests with a makeSut factory,
|
|
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
|
|
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
|
|
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -4,7 +4,7 @@ dotagents includes content from the following projects.
|
|
|
4
4
|
|
|
5
5
|
## mattpocock/skills
|
|
6
6
|
|
|
7
|
-
The `dot-debug`, `dot-
|
|
7
|
+
The `dot-debug`, `dot-grilling`, `dot-handoff`, and `dot-writing-for-agents`
|
|
8
8
|
skills come from [mattpocock/skills](https://github.com/mattpocock/skills).
|
|
9
9
|
Each skill's `UPSTREAM.json` file records the source commit and any local
|
|
10
10
|
changes. The project is licensed under the MIT License:
|
package/dist/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":"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
|
-
|
|
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);
|
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/");
|