@igorlau/dotagents 1.0.14 → 1.0.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (94) hide show
  1. package/README.md +127 -35
  2. package/THIRD_PARTY_NOTICES.md +77 -3
  3. package/dist/build-info.json +1 -1
  4. package/dist/catalog.js +3 -3
  5. package/dist/cli.js +8 -2
  6. package/dist/commands.js +60 -5
  7. package/dist/paths.js +1 -1
  8. package/dist/targets.js +3 -0
  9. package/package.json +3 -2
  10. package/plugin/.claude-plugin/plugin.json +10 -0
  11. package/plugin/agents/dot-implementer.md +25 -0
  12. package/plugin/agents/dot-reviewer.md +31 -0
  13. package/plugin/agents/dot-tester.md +25 -0
  14. package/plugin/hooks/check.mjs +118 -0
  15. package/plugin/hooks/hooks.json +54 -0
  16. package/plugin/hooks/rules.mjs +27 -0
  17. package/plugin/rules/code-style.md +6 -0
  18. package/plugin/rules/comments.md +17 -0
  19. package/plugin/rules/comments.upstream.json +8 -0
  20. package/{content → plugin}/rules/core.md +2 -2
  21. package/{content → plugin}/rules/ponytail.md +2 -2
  22. package/{content → plugin}/rules/ponytail.upstream.json +1 -1
  23. package/plugin/rules/writing.md +34 -0
  24. package/plugin/rules/writing.upstream.json +8 -0
  25. package/{content → plugin}/scaffold/AGENTS.md.tmpl +2 -1
  26. package/plugin/skills/dot-code-review/SKILL.md +69 -0
  27. package/plugin/skills/dot-code-review/UPSTREAM.json +8 -0
  28. package/plugin/skills/dot-code-review/references/maintainability.md +67 -0
  29. package/plugin/skills/dot-comments/SKILL.md +41 -0
  30. package/plugin/skills/dot-comments/UPSTREAM.json +8 -0
  31. package/{content → plugin}/skills/dot-commit/SKILL.md +7 -9
  32. package/plugin/skills/dot-correct/SKILL.md +41 -0
  33. package/plugin/skills/dot-correct/UPSTREAM.json +8 -0
  34. package/plugin/skills/dot-correct/agents/openai.yaml +5 -0
  35. package/plugin/skills/dot-debug/SKILL.md +123 -0
  36. package/plugin/skills/dot-debug/UPSTREAM.json +8 -0
  37. package/plugin/skills/dot-debug/references/loops.md +32 -0
  38. package/{content → plugin}/skills/dot-docs-writing/SKILL.md +15 -25
  39. package/{content → plugin}/skills/dot-docs-writing/references/formatting.md +26 -26
  40. package/{content → plugin}/skills/dot-docs-writing/references/global-and-accessible.md +9 -10
  41. package/{content → plugin}/skills/dot-docs-writing/references/word-list.md +4 -5
  42. package/plugin/skills/dot-flow/SKILL.md +73 -0
  43. package/plugin/skills/dot-flow/agents/openai.yaml +5 -0
  44. package/plugin/skills/dot-flow/references/inline.md +9 -0
  45. package/plugin/skills/dot-grilling/SKILL.md +32 -0
  46. package/plugin/skills/dot-grilling/UPSTREAM.json +8 -0
  47. package/plugin/skills/dot-grilling/agents/openai.yaml +3 -0
  48. package/plugin/skills/dot-handoff/SKILL.md +18 -0
  49. package/{content → plugin}/skills/dot-handoff/UPSTREAM.json +1 -1
  50. package/plugin/skills/dot-implement/SKILL.md +68 -0
  51. package/plugin/skills/dot-implement/UPSTREAM.json +8 -0
  52. package/{content → plugin}/skills/dot-implement/references/typescript.md +29 -20
  53. package/{content → plugin}/skills/dot-plan/SKILL.md +16 -13
  54. package/plugin/skills/dot-plan/UPSTREAM.json +8 -0
  55. package/plugin/skills/dot-plan/references/entity-schemas.md +66 -0
  56. package/{content → plugin}/skills/dot-roadmap/SKILL.md +19 -16
  57. package/plugin/skills/dot-roadmap/UPSTREAM.json +8 -0
  58. package/plugin/skills/dot-roadmap/agents/openai.yaml +5 -0
  59. package/plugin/skills/dot-roadmap/references/wide-refactor.md +3 -0
  60. package/plugin/skills/dot-testing/SKILL.md +45 -0
  61. package/plugin/skills/dot-testing/UPSTREAM.json +8 -0
  62. package/plugin/skills/dot-testing/references/after-implement.md +23 -0
  63. package/plugin/skills/dot-testing/references/http.md +15 -0
  64. package/plugin/skills/dot-testing/references/shared-state.md +3 -0
  65. package/{content → plugin}/skills/dot-testing/references/typescript.md +2 -2
  66. package/plugin/skills/dot-writing-for-agents/SKILL.md +52 -0
  67. package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +8 -0
  68. package/plugin/skills/dot-writing-for-agents/references/pointers.md +27 -0
  69. package/plugin/skills/dot-writing-for-agents/references/skill-mechanics.md +22 -0
  70. package/plugin/skills/dot-writing-for-agents/references/steps.md +8 -0
  71. package/content/rules/comments.md +0 -15
  72. package/content/skills/dot-code-review/SKILL.md +0 -58
  73. package/content/skills/dot-debug/SKILL.md +0 -142
  74. package/content/skills/dot-debug/UPSTREAM.json +0 -8
  75. package/content/skills/dot-grill-me/SKILL.md +0 -11
  76. package/content/skills/dot-grill-me/UPSTREAM.json +0 -8
  77. package/content/skills/dot-grill-me/agents/openai.yaml +0 -5
  78. package/content/skills/dot-grilling/SKILL.md +0 -34
  79. package/content/skills/dot-grilling/UPSTREAM.json +0 -8
  80. package/content/skills/dot-grilling/agents/openai.yaml +0 -3
  81. package/content/skills/dot-handoff/SKILL.md +0 -20
  82. package/content/skills/dot-implement/SKILL.md +0 -52
  83. package/content/skills/dot-testing/SKILL.md +0 -44
  84. package/content/skills/dot-writing-for-agents/SKILL-MECHANICS.md +0 -22
  85. package/content/skills/dot-writing-for-agents/SKILL.md +0 -85
  86. package/content/skills/dot-writing-for-agents/UPSTREAM.json +0 -8
  87. /package/{content → plugin}/scaffold/.claude/settings.json.tmpl +0 -0
  88. /package/{content → plugin}/scaffold/.editorconfig.tmpl +0 -0
  89. /package/{content → plugin}/scaffold/.gitattributes.tmpl +0 -0
  90. /package/{content → plugin}/scaffold/CLAUDE.md.tmpl +0 -0
  91. /package/{content → plugin}/skills/dot-debug/agents/openai.yaml +0 -0
  92. /package/{content → plugin}/skills/dot-debug/scripts/hitl-loop.template.sh +0 -0
  93. /package/{content → plugin}/skills/dot-handoff/agents/openai.yaml +0 -0
  94. /package/{content → plugin}/skills/dot-writing-for-agents/agents/openai.yaml +0 -0
package/README.md CHANGED
@@ -1,20 +1,45 @@
1
1
  # dotagents
2
2
 
3
- dotagents installs a curated set of skills and rules into Claude Code,
4
- OpenAI Codex, and GitHub Copilot, so every project you work on gets the same
5
- AI workflow.
3
+ dotagents gives Claude Code, OpenAI Codex, and GitHub Copilot one AI workflow
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
+
7
+ dotagents has two parts:
8
+
9
+ - A plugin with skills, agents, and hooks. Claude Code, the
10
+ Copilot CLI, and VS Code load the plugin.
11
+ - A CLI that installs the always-on rules for all three coding agents, and the
12
+ skills for Codex and Copilot.
6
13
 
7
14
  ## Install
8
15
 
9
- To install the skills and rules for all your projects, run the following
10
- command:
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:
11
28
 
12
29
  ```bash
13
30
  npx --yes @igorlau/dotagents install
14
31
  ```
15
32
 
16
- `npx` runs dotagents without installing it. To run `dotagents` as a command
17
- in any terminal, install it globally:
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:
36
+
37
+ ```bash
38
+ npx --yes @igorlau/dotagents check enable
39
+ ```
40
+
41
+ `npx` runs dotagents without an install. To run `dotagents` as a command in
42
+ any terminal, install it globally:
18
43
 
19
44
  ```bash
20
45
  npm install --global @igorlau/dotagents
@@ -25,8 +50,8 @@ To upgrade a global install, run
25
50
 
26
51
  ## Use dotagents in a repository
27
52
 
28
- The global install covers every project, including team repositories, and
29
- writes nothing to them.
53
+ The global install covers every project, team repositories too, and writes
54
+ nothing to them.
30
55
 
31
56
  To share the skills and rules with collaborators in a repository that you
32
57
  own, run the following command in the repository, and commit the new files:
@@ -44,23 +69,75 @@ command in the repository:
44
69
  npx --yes @igorlau/dotagents scaffold
45
70
  ```
46
71
 
47
- The command creates the following files, skips any that already exist, and
48
- never changes them afterward. They belong to the repository, so edit and
49
- commit them like any other file:
72
+ The command creates the following files. It skips a file that exists, and it
73
+ never changes the files after that. The files belong to the repository, so
74
+ edit and commit them like any other file:
50
75
 
51
76
  | File | Purpose |
52
77
  | ---- | ------- |
53
78
  | `AGENTS.md` | Project instructions for every agent: how to work, code and tests, security, and Git. |
54
79
  | `CLAUDE.md` | Imports `AGENTS.md`, so Claude Code reads the same instructions. |
55
- | `.claude/settings.json` | Blocks Claude Code from reading secrets, and asks before `git push`. |
56
- | `.editorconfig`, `.gitattributes` | Keep whitespace and line endings consistent across editors and operating systems. |
80
+ | `.claude/settings.json` | Blocks secret files from Claude Code, and asks before `git push`. |
81
+ | `.editorconfig`, `.gitattributes` | Keep whitespace and line endings the same in all editors and operating systems. |
57
82
 
58
83
  Run `scaffold` before `init`. `init` adds a block to `AGENTS.md`, and
59
- `scaffold` doesn't overwrite an existing `AGENTS.md`.
84
+ `scaffold` does not overwrite an `AGENTS.md` that exists.
85
+
86
+ ## The flow
87
+
88
+ The following diagram shows the full flow, from an idea to the commits of one
89
+ task. The agent stops for your decision at each "approve", "fix", or "accept":
90
+
91
+ ```mermaid
92
+ sequenceDiagram
93
+ actor User
94
+ participant Main as Main session
95
+ participant Agents as Step agents
96
+ User->>Main: dot-grilling with an idea
97
+ Main-->>User: Questions in rounds, with recommended answers
98
+ User->>Main: Answers until the plan is clear
99
+ User->>Main: dot-plan
100
+ Main-->>User: Entity schemas
101
+ User->>Main: Approve the schemas
102
+ Main-->>User: Plan as small, verifiable steps
103
+ User->>Main: Approve the plan
104
+ User->>Main: dot-roadmap
105
+ Main-->>User: Phases and task files with test cases
106
+ User->>Main: Approve the roadmap
107
+ loop Each task
108
+ User->>Main: dot-flow with the task file
109
+ Main->>Agents: 1. Production code (dot-implementer)
110
+ Agents-->>Main: Reply
111
+ Main->>Main: Run the checks of the reply
112
+ Main->>Agents: 2. Tests (dot-tester)
113
+ Agents-->>Main: Reply
114
+ Main->>Main: Run the tests of the reply
115
+ Main->>Agents: 3. Review (dot-reviewer)
116
+ Agents-->>Main: Findings
117
+ Main-->>User: Findings
118
+ break A blocker, or a check that differs from the reply
119
+ Main-->>User: Stop. The files stay as they are.
120
+ end
121
+ opt Fix
122
+ User->>Main: Fix these findings
123
+ Main->>Agents: Steps 1 to 3 again
124
+ end
125
+ User->>Main: Accept
126
+ User->>Main: dot-commit
127
+ Main-->>User: Each commit for approval
128
+ User->>Main: Approve
129
+ Main-->>User: Commits, and a tick in the roadmap
130
+ end
131
+ ```
132
+
133
+ `dot-flow` never commits. In Codex and Copilot, `dot-flow` runs the three steps
134
+ in the main session, with the same verification and stops.
135
+
136
+ To learn the workflow step by step, read the [guide](docs/guide/README.md).
60
137
 
61
138
  ## Commands
62
139
 
63
- The following table summarizes the commands. For options, run
140
+ The following table gives a summary of the commands. For the options, run
64
141
  `dotagents --help`.
65
142
 
66
143
  | Command | Description |
@@ -68,42 +145,57 @@ The following table summarizes the commands. For options, run
68
145
  | `install` | Install globally. |
69
146
  | `init` | Install into the current repository for collaborators. |
70
147
  | `scaffold` | Create starter agent instructions in the current repository. |
71
- | `update` | Apply the latest catalog to existing installs. |
148
+ | `update` | Apply the latest catalog to the installs. |
72
149
  | `uninstall` | Remove everything that dotagents installed. |
73
- | `doctor` | Check installs for missing or modified files. |
150
+ | `doctor` | Find missing or changed files in the installs. |
74
151
  | `list` | List the skills. |
75
152
  | `self-update` | Run `update` with the latest release. |
153
+ | `check enable`, `check disable` | Start or stop the plugin `check` hook in the current repository. |
76
154
 
77
- dotagents doesn't overwrite files that you changed or that it didn't write.
78
- To overwrite them, pass `--force`.
155
+ dotagents does not overwrite a file that you changed or that it did not
156
+ write. To overwrite the file, add `--force`.
79
157
 
80
- ## What's included
158
+ ## What is included
81
159
 
82
- The always-on rules in [`content/rules/`](content/rules/) cover working
160
+ The always-on rules in [`plugin/rules/`](plugin/rules/) cover working
83
161
  agreements, the smallest complete change from
84
- [ponytail](https://github.com/DietrichGebert/ponytail), and code comments.
162
+ [ponytail](https://github.com/DietrichGebert/ponytail), code comments, code
163
+ style, and writing.
85
164
 
86
- The following skills load when a task needs them:
165
+ The 14 skills in [`plugin/skills/`](plugin/skills/) load when a task needs
166
+ them:
87
167
 
88
168
  | Skill | Purpose |
89
169
  | ----- | ------- |
90
- | `dot-plan` | Plan a change as small, verifiable steps. |
91
- | `dot-implement` | Implement a change or roadmap task to the repository's and language's standards. |
92
- | `dot-testing` | Write tests around a shared makeSut factory. |
93
- | `dot-code-review` | Review a diff for correctness bugs. |
170
+ | `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. |
172
+ | `dot-roadmap` | Split a plan into phases and tasks that each stand alone. |
173
+ | `dot-flow` | Take a roadmap task through code, tests, and review, verify each step, and stop for your decision after the review. |
174
+ | `dot-testing` | Write tests with a makeSut factory, alone or after `dot-implement`. |
175
+ | `dot-implement` | Write the code of a change or roadmap task to the standards of the repository and the language. |
176
+ | `dot-code-review` | Review a diff for correctness bugs and maintainability problems. |
177
+ | `dot-comments` | Delete the comments in a diff that no exception protects. |
94
178
  | `dot-commit` | Commit changes as small, logical commits. |
95
- | `dot-docs-writing` | Write docs in the Google developer documentation style. |
96
- | `dot-debug` | Diagnose hard bugs with a feedback loop. |
97
- | `dot-grill-me` | Start an interview that sharpens a plan. |
98
- | `dot-grilling` | Run the interview method behind `dot-grill-me`. |
99
- | `dot-roadmap` | Split a grilled plan into phases and self-contained tasks. |
100
- | `dot-handoff` | Summarize a conversation for another agent. |
179
+ | `dot-debug` | Find the cause of a hard bug with a feedback loop. |
180
+ | `dot-correct` | Change a mistake that agents repeat into a check that prevents it. |
181
+ | `dot-handoff` | Give a summary of a conversation to another agent. |
182
+ | `dot-docs-writing` | Give docs the structure and format of the Google developer documentation style. |
101
183
  | `dot-writing-for-agents` | Write skills, `AGENTS.md`, and `CLAUDE.md` files. |
102
184
 
185
+ The plugin also has 3 agents in [`plugin/agents/`](plugin/agents/).
186
+ `dot-flow` starts a new agent for each step, so each step starts with a clean
187
+ context:
188
+
189
+ | Agent | Purpose |
190
+ | ----- | ------- |
191
+ | `dot-tester` | Write the tests of a task after the code exists. |
192
+ | `dot-implementer` | Write the production code of a task. |
193
+ | `dot-reviewer` | Review the changes of a task. |
194
+
103
195
  ## More information
104
196
 
105
197
  - [Design specification](SPEC.md)
106
198
  - [Contributing guide](CONTRIBUTING.md): report problems and propose changes
107
- through pull requests
199
+ with pull requests
108
200
  - [Third-party notices](THIRD_PARTY_NOTICES.md)
109
201
  - [License (MIT)](LICENSE)
@@ -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:
@@ -35,9 +35,9 @@ SOFTWARE.
35
35
 
36
36
  ## DietrichGebert/ponytail
37
37
 
38
- The `ponytail` rules in `content/rules/ponytail.md` come from the `AGENTS.md`
38
+ The `ponytail` rules in `plugin/rules/ponytail.md` come from the `AGENTS.md`
39
39
  file in [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail).
40
- `content/rules/ponytail.upstream.json` records the source commit and local
40
+ `plugin/rules/ponytail.upstream.json` records the source commit and local
41
41
  changes. The project is licensed under the MIT License:
42
42
 
43
43
  ```text
@@ -64,6 +64,80 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
64
64
  SOFTWARE.
65
65
  ```
66
66
 
67
+ ## cursor/plugins pstack
68
+
69
+ The `dot-comments` and `dot-correct` skills, the comment policy in
70
+ `plugin/rules/comments.md`, and the word and format rules in
71
+ `plugin/rules/writing.md` come from the
72
+ `pstack` plugin in [cursor/plugins](https://github.com/cursor/plugins). The
73
+ skills' `UPSTREAM.json` files, `plugin/rules/comments.upstream.json`, and
74
+ `plugin/rules/writing.upstream.json` record the source commits and local
75
+ changes. The behavior test principle in the `dot-testing` skill, the rule to put
76
+ removals first in the `dot-plan` and `dot-roadmap` skills, the domain model rules
77
+ in `dot-plan`, the reader load, domain model, and scope rules in the
78
+ maintainability pass of `dot-code-review`, the root cause and premise rules
79
+ in `dot-debug`, and parts of the TypeScript
80
+ reference in `dot-implement` come from pstack's principle skills and its
81
+ `typescript-best-practices` skill.
82
+ The `UPSTREAM.json` file of each of these skills records its sources. The project
83
+ is licensed under the MIT License:
84
+
85
+ ```text
86
+ MIT License
87
+
88
+ Copyright (c) 2026 Lauren Tan
89
+
90
+ Permission is hereby granted, free of charge, to any person obtaining a copy
91
+ of this software and associated documentation files (the "Software"), to deal
92
+ in the Software without restriction, including without limitation the rights
93
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
94
+ copies of the Software, and to permit persons to whom the Software is
95
+ furnished to do so, subject to the following conditions:
96
+
97
+ The above copyright notice and this permission notice shall be included in all
98
+ copies or substantial portions of the Software.
99
+
100
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
101
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
102
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
103
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
104
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
105
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
106
+ SOFTWARE.
107
+ ```
108
+
109
+ ## cursor/plugins cursor-team-kit
110
+
111
+ The maintainability pass of the `dot-code-review` skill is adapted from the
112
+ `thermo-nuclear-code-quality-review` skill of the `cursor-team-kit` plugin in
113
+ [cursor/plugins](https://github.com/cursor/plugins). The skill's
114
+ `UPSTREAM.json` file records the source commit and local changes. The plugin
115
+ is licensed under the MIT License:
116
+
117
+ ```text
118
+ MIT License
119
+
120
+ Copyright (c) 2026 Cursor
121
+
122
+ Permission is hereby granted, free of charge, to any person obtaining a copy
123
+ of this software and associated documentation files (the "Software"), to deal
124
+ in the Software without restriction, including without limitation the rights
125
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
126
+ copies of the Software, and to permit persons to whom the Software is
127
+ furnished to do so, subject to the following conditions:
128
+
129
+ The above copyright notice and this permission notice shall be included in all
130
+ copies or substantial portions of the Software.
131
+
132
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
133
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
134
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
135
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
136
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
137
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
138
+ SOFTWARE.
139
+ ```
140
+
67
141
  ## Google developer documentation style guide
68
142
 
69
143
  The `dot-docs-writing` skill is adapted from the
@@ -1 +1 @@
1
- {"commit":"f6ee8bc"}
1
+ {"commit":"6e38c12"}
package/dist/catalog.js CHANGED
@@ -1,10 +1,10 @@
1
1
  import fs from "node:fs";
2
2
  import path from "node:path";
3
- import { contentRoot } from "./paths.js";
3
+ import { pluginRoot } from "./paths.js";
4
4
  import { parseFrontmatter } from "./frontmatter.js";
5
5
  // Files that describe a skill's origin but aren't part of the skill itself.
6
6
  const META_FILES = new Set(["UPSTREAM.json"]);
7
- export function loadCatalog(root = contentRoot) {
7
+ export function loadCatalog(root = pluginRoot) {
8
8
  const rules = loadRules(path.join(root, "rules"));
9
9
  const skillsDir = path.join(root, "skills");
10
10
  const skills = fs
@@ -44,7 +44,7 @@ function loadSkill(dir) {
44
44
  }
45
45
  // Templates carry a .tmpl suffix, so agents and Git working in this repository
46
46
  // don't load them as its own AGENTS.md, CLAUDE.md, or .gitattributes.
47
- export function loadScaffold(root = contentRoot) {
47
+ export function loadScaffold(root = pluginRoot) {
48
48
  const dir = path.join(root, "scaffold");
49
49
  return listFiles(dir).map((rel) => ({ rel: rel.replace(/\.tmpl$/, ""), content: fs.readFileSync(path.join(dir, rel), "utf8") }));
50
50
  }
package/dist/cli.js CHANGED
@@ -1,6 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
  import { parseArgs } from "node:util";
3
- import { doctor, init, install, list, saveSource, scaffold, selfUpdate, uninstall, update, version } from "./commands.js";
3
+ import { doctor, init, install, list, saveSource, scaffold, selfUpdate, setCheckHook, uninstall, update, version } from "./commands.js";
4
4
  import { parseAgents } from "./targets.js";
5
5
  const HELP = `dotagents: install curated agent skills and rules
6
6
 
@@ -13,6 +13,7 @@ Usage:
13
13
  dotagents doctor Check installs for problems
14
14
  dotagents list List the skills in the catalog
15
15
  dotagents self-update Run \`update\` with the latest release
16
+ dotagents check enable|disable Let the plugin's check hook run in the current repository, or stop it
16
17
 
17
18
  Options:
18
19
  --agents <list> Comma-separated: claude,codex,copilot (default: all)
@@ -41,7 +42,7 @@ function main(argv) {
41
42
  console.log(version());
42
43
  return 0;
43
44
  }
44
- const [command] = positionals;
45
+ const [command, subcommand] = positionals;
45
46
  if (values.help || !command) {
46
47
  console.log(HELP);
47
48
  return command || values.help ? 0 : 1;
@@ -67,6 +68,11 @@ function main(argv) {
67
68
  case "list":
68
69
  list();
69
70
  return 0;
71
+ case "check":
72
+ if (subcommand !== "enable" && subcommand !== "disable")
73
+ throw new Error("Usage: dotagents check enable|disable");
74
+ setCheckHook(cwd, subcommand === "enable", options.dryRun);
75
+ return 0;
70
76
  case "self-update":
71
77
  return selfUpdate(argv.slice(1)) ? 0 : 1;
72
78
  default:
package/dist/commands.js CHANGED
@@ -6,9 +6,10 @@ import { readBlock } from "./blocks.js";
6
6
  import { loadCatalog, loadScaffold } from "./catalog.js";
7
7
  import { repoRoot } from "./git.js";
8
8
  import { fromStored, globalManifestPath, hash, projectManifestPath, readManifest, toStored, writeManifest, } from "./manifest.js";
9
- import { codexHome, configDir, packageRoot } from "./paths.js";
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
13
  // Release tags carry a real version. Builds from a branch carry X.Y.0-dev,
13
14
  // so the commit tells them apart.
14
15
  export function version() {
@@ -45,6 +46,8 @@ function run(scope, agents, options, uninstall = false) {
45
46
  const ops = uninstall ? [] : planInstall(catalog, scope.mode, agents, scope.root);
46
47
  const result = apply(ops, fromStored(previous?.entries ?? [], scope.root), options);
47
48
  report(result, options.dryRun);
49
+ if (!uninstall && scope.mode === "global" && agents.includes("claude") && !dotagentsPluginInstalled())
50
+ log(PLUGIN_HINT);
48
51
  if (options.dryRun)
49
52
  return result.problems.length === 0;
50
53
  if (result.entries.length === 0) {
@@ -160,15 +163,39 @@ export function doctor(cwd) {
160
163
  if (scope.mode === "global" && manifest.agents.includes("codex") && fs.existsSync(path.join(codexHome(), "AGENTS.override.md"))) {
161
164
  issues.push(`${path.join(codexHome(), "AGENTS.override.md")} exists, so Codex ignores the rules in AGENTS.md.`);
162
165
  }
166
+ if (scope.mode === "global" && manifest.agents.includes("claude")) {
167
+ issues.push(...(dotagentsPluginInstalled() ? duplicateClaudeSkills() : [PLUGIN_HINT]));
168
+ }
163
169
  if (version() !== manifest.version)
164
170
  log(` Installed version ${manifest.version} differs from this CLI (${version()}). Run \`dotagents update\`.`);
165
171
  }
172
+ const checkRepos = readConfig().checkRepos ?? [];
173
+ log(checkRepos.length > 0 ? ` The check hook runs in: ${checkRepos.join(", ")}` : " The check hook runs in no repository. Run `dotagents check enable` in one.");
166
174
  for (const issue of issues)
167
175
  log(` ! ${issue}`);
168
176
  if (issues.length === 0)
169
177
  log(" No problems found.");
170
178
  return issues.length === 0;
171
179
  }
180
+ /** Lists `dot-*` skills in Claude Code's skills directory when the dotagents plugin also provides them. */
181
+ function duplicateClaudeSkills() {
182
+ const skillsDir = path.join(claudeHome(), "skills");
183
+ if (!fs.existsSync(skillsDir))
184
+ return [];
185
+ return fs
186
+ .readdirSync(skillsDir)
187
+ .filter((name) => name.startsWith("dot-"))
188
+ .map((name) => `${path.join(skillsDir, name)}: Claude Code also loads this skill from the dotagents plugin. Delete the directory.`);
189
+ }
190
+ function dotagentsPluginInstalled() {
191
+ try {
192
+ const installed = JSON.parse(fs.readFileSync(path.join(claudeHome(), "plugins", "installed_plugins.json"), "utf8"));
193
+ return Object.keys(installed.plugins ?? {}).some((id) => id.startsWith("dotagents@"));
194
+ }
195
+ catch {
196
+ return false;
197
+ }
198
+ }
172
199
  export function list() {
173
200
  for (const skill of loadCatalog().skills)
174
201
  log(`${skill.name}\n ${skill.description}`);
@@ -176,13 +203,41 @@ export function list() {
176
203
  function configFile() {
177
204
  return path.join(configDir(), "config.json");
178
205
  }
179
- export function readSource() {
206
+ function readConfig() {
180
207
  const file = configFile();
181
- return fs.existsSync(file) ? (JSON.parse(fs.readFileSync(file, "utf8")).source ?? DEFAULT_SOURCE) : DEFAULT_SOURCE;
208
+ if (!fs.existsSync(file))
209
+ return {};
210
+ try {
211
+ return JSON.parse(fs.readFileSync(file, "utf8"));
212
+ }
213
+ catch (error) {
214
+ throw new Error(`${file} isn't valid JSON: ${error.message}. Fix or delete it.`);
215
+ }
182
216
  }
183
- export function saveSource(source) {
217
+ function writeConfig(changes) {
184
218
  fs.mkdirSync(configDir(), { recursive: true });
185
- fs.writeFileSync(configFile(), JSON.stringify({ source }, null, 2) + "\n");
219
+ fs.writeFileSync(configFile(), JSON.stringify({ ...readConfig(), ...changes }, null, 2) + "\n");
220
+ }
221
+ export function readSource() {
222
+ return readConfig().source ?? DEFAULT_SOURCE;
223
+ }
224
+ export function saveSource(source) {
225
+ writeConfig({ source });
226
+ }
227
+ /** Enables or disables the plugin's `check` hook for the repository that contains `cwd`. Throws outside a repository. */
228
+ export function setCheckHook(cwd, enabled, dryRun) {
229
+ const root = repoRoot(cwd);
230
+ if (!root)
231
+ throw new Error("Not inside a Git repository. Run this command from the repository to change.");
232
+ const repo = fs.realpathSync(root);
233
+ const others = (readConfig().checkRepos ?? []).filter((candidate) => candidate !== repo);
234
+ const state = enabled ? "enabled" : "disabled";
235
+ if (dryRun) {
236
+ log(`The check hook would be ${state} in ${repo}.`);
237
+ return;
238
+ }
239
+ writeConfig({ checkRepos: enabled ? [...others, repo].sort() : others });
240
+ log(`The check hook is ${state} in ${repo}.`);
186
241
  }
187
242
  export function selfUpdate(args) {
188
243
  const source = readSource();
package/dist/paths.js CHANGED
@@ -22,4 +22,4 @@ export function configDir() {
22
22
  }
23
23
  // Works from both src/ (tests, scripts) and dist/ (installed package).
24
24
  export const packageRoot = fileURLToPath(new URL("..", import.meta.url));
25
- export const contentRoot = path.join(packageRoot, "content");
25
+ export const pluginRoot = path.join(packageRoot, "plugin");
package/dist/targets.js CHANGED
@@ -36,6 +36,9 @@ export function planInstall(catalog, mode, agents, root = "") {
36
36
  const ops = new Map();
37
37
  const add = (op) => ops.set(op.path, op);
38
38
  for (const agent of agents) {
39
+ // Claude Code gets its skills globally from the dotagents plugin. See SPEC.md, decision 19.
40
+ if (mode === "global" && agent === "claude")
41
+ continue;
39
42
  for (const skill of catalog.skills) {
40
43
  for (const file of skill.files) {
41
44
  add({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@igorlau/dotagents",
3
- "version": "1.0.14",
3
+ "version": "1.0.16",
4
4
  "description": "Install a curated set of agent skills and rules into Claude Code, Codex, and GitHub Copilot.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -17,7 +17,7 @@
17
17
  },
18
18
  "files": [
19
19
  "dist",
20
- "content",
20
+ "plugin",
21
21
  "THIRD_PARTY_NOTICES.md"
22
22
  ],
23
23
  "engines": {
@@ -27,6 +27,7 @@
27
27
  "build": "tsc -p tsconfig.build.json && node scripts/build-info.mjs",
28
28
  "prepare": "npm run build",
29
29
  "typecheck": "tsc -p tsconfig.json --noEmit",
30
+ "check": "npm run --silent typecheck && npm run --silent lint:content",
30
31
  "test": "node --test 'test/**/*.test.ts'",
31
32
  "lint:content": "node scripts/lint-content.ts",
32
33
  "check-upstream": "node scripts/check-upstream.ts"
@@ -0,0 +1,10 @@
1
+ {
2
+ "name": "dotagents",
3
+ "description": "Skills, agents, and hooks for a planned, tested, and reviewed coding workflow.",
4
+ "author": {
5
+ "name": "igorlau"
6
+ },
7
+ "homepage": "https://github.com/igorlau/dotagents#readme",
8
+ "repository": "https://github.com/igorlau/dotagents",
9
+ "license": "MIT"
10
+ }
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: dot-implementer
3
+ description: Write the production code of one roadmap task with the dot-implement skill, and hand off the test changes it needs. Use for the implementation step of the dot-flow skill.
4
+ skills: dotagents:dot-implement
5
+ disallowedTools: Agent
6
+ ---
7
+
8
+ # Implementer
9
+
10
+ Run the implementation step of a roadmap task. Follow the `dot-implement` skill.
11
+
12
+ ## Input
13
+
14
+ The prompt gives these fields:
15
+
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.
18
+
19
+ When the task is missing, stop and report it.
20
+
21
+ Write no tests, do not commit, and do not tick the roadmap checkbox.
22
+
23
+ ## Output
24
+
25
+ End with the handoff of step 5 of `dot-implement`, and write nothing after it. The next step writes the tests.
@@ -0,0 +1,31 @@
1
+ ---
2
+ name: dot-reviewer
3
+ description: Review the uncommitted changes of one roadmap task with the dot-code-review skill. Use for the review step of the dot-flow skill.
4
+ skills: dotagents:dot-code-review
5
+ disallowedTools: Agent
6
+ ---
7
+
8
+ # Reviewer
9
+
10
+ Run the review step of a roadmap task. Follow the `dot-code-review` skill.
11
+
12
+ ## Input
13
+
14
+ The prompt gives these fields:
15
+
16
+ - **Task**: the path of the roadmap task file. Check the change against its requirements and its "Out of scope" section.
17
+ - **Handoff**: the replies of the earlier steps.
18
+
19
+ When a field is missing, stop and report it.
20
+
21
+ The target is the uncommitted change: `git diff HEAD`, plus the untracked files that `git status --short` lists. Report the findings, and keep the code as it is. Delete each test that you write to prove a finding.
22
+
23
+ Do not commit, and do not tick the roadmap checkbox.
24
+
25
+ ## Output
26
+
27
+ Start the reply with this line, then give the report of `dot-code-review`:
28
+
29
+ ```markdown
30
+ **Highest severity:** <high | medium | low | none>
31
+ ```
@@ -0,0 +1,25 @@
1
+ ---
2
+ name: dot-tester
3
+ description: Write the tests of one roadmap task with the dot-testing skill, after the code exists. Use for the test step of the dot-flow skill.
4
+ skills: dotagents:dot-testing
5
+ disallowedTools: Agent
6
+ ---
7
+
8
+ # Tester
9
+
10
+ Run the test step of a roadmap task. Follow the `dot-testing` skill and its `references/after-implement.md`.
11
+
12
+ ## Input
13
+
14
+ The prompt gives these fields:
15
+
16
+ - **Task**: the path of the roadmap task file.
17
+ - **Handoff**: the handoff of the implementation step, with the "Expected failures" and "Behaviors that need tests" fields.
18
+
19
+ When a field is missing, stop and report it.
20
+
21
+ Keep the production code as it is. Do not commit, and do not tick the roadmap checkbox.
22
+
23
+ ## Output
24
+
25
+ End with the reply that `references/after-implement.md` gives, and write nothing after it.