@igorlau/dotagents 1.0.13 → 1.0.15
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 +129 -35
- package/THIRD_PARTY_NOTICES.md +76 -2
- package/dist/build-info.json +1 -1
- package/dist/catalog.js +3 -3
- package/dist/cli.js +8 -2
- package/dist/commands.js +60 -5
- package/dist/paths.js +1 -1
- package/dist/targets.js +3 -0
- package/package.json +2 -2
- package/plugin/.claude-plugin/plugin.json +10 -0
- package/plugin/agents/dot-implementer.md +38 -0
- package/plugin/agents/dot-reviewer.md +31 -0
- package/plugin/agents/dot-tester.md +33 -0
- package/plugin/hooks/check.mjs +92 -0
- package/plugin/hooks/hooks.json +24 -0
- package/plugin/rules/code-style.md +6 -0
- package/plugin/rules/comments.md +17 -0
- package/plugin/rules/comments.upstream.json +8 -0
- package/{content → plugin}/rules/ponytail.md +1 -1
- package/{content → plugin}/rules/ponytail.upstream.json +1 -1
- package/plugin/rules/writing.md +35 -0
- package/plugin/rules/writing.upstream.json +8 -0
- package/{content → plugin}/scaffold/AGENTS.md.tmpl +1 -0
- package/plugin/skills/dot-code-review/SKILL.md +71 -0
- package/plugin/skills/dot-code-review/UPSTREAM.json +8 -0
- package/plugin/skills/dot-code-review/references/maintainability.md +67 -0
- package/plugin/skills/dot-comments/SKILL.md +41 -0
- package/plugin/skills/dot-comments/UPSTREAM.json +8 -0
- package/{content → plugin}/skills/dot-commit/SKILL.md +7 -5
- package/plugin/skills/dot-correct/SKILL.md +43 -0
- package/plugin/skills/dot-correct/UPSTREAM.json +8 -0
- package/plugin/skills/dot-correct/agents/openai.yaml +5 -0
- package/plugin/skills/dot-debug/SKILL.md +125 -0
- package/plugin/skills/dot-debug/UPSTREAM.json +8 -0
- package/plugin/skills/dot-debug/references/loops.md +32 -0
- package/{content → plugin}/skills/dot-docs-writing/SKILL.md +15 -23
- package/{content → plugin}/skills/dot-docs-writing/references/formatting.md +26 -26
- package/{content → plugin}/skills/dot-docs-writing/references/global-and-accessible.md +9 -10
- package/{content → plugin}/skills/dot-docs-writing/references/word-list.md +4 -5
- package/plugin/skills/dot-flow/SKILL.md +75 -0
- package/plugin/skills/dot-flow/agents/openai.yaml +5 -0
- package/plugin/skills/dot-flow/references/inline.md +42 -0
- package/{content → plugin}/skills/dot-grill-me/SKILL.md +2 -2
- package/{content → plugin}/skills/dot-grill-me/UPSTREAM.json +1 -1
- package/plugin/skills/dot-grilling/SKILL.md +34 -0
- package/{content → plugin}/skills/dot-grilling/UPSTREAM.json +1 -1
- package/plugin/skills/dot-grilling/agents/openai.yaml +3 -0
- package/plugin/skills/dot-handoff/SKILL.md +20 -0
- package/{content → plugin}/skills/dot-handoff/UPSTREAM.json +1 -1
- package/plugin/skills/dot-implement/SKILL.md +65 -0
- package/plugin/skills/dot-implement/UPSTREAM.json +8 -0
- package/{content → plugin}/skills/dot-implement/references/typescript.md +29 -20
- package/{content → plugin}/skills/dot-plan/SKILL.md +15 -8
- package/plugin/skills/dot-plan/UPSTREAM.json +8 -0
- package/plugin/skills/dot-plan/references/entity-schemas.md +66 -0
- package/{content → plugin}/skills/dot-roadmap/SKILL.md +19 -12
- package/plugin/skills/dot-roadmap/UPSTREAM.json +8 -0
- package/plugin/skills/dot-roadmap/references/wide-refactor.md +3 -0
- package/plugin/skills/dot-testing/SKILL.md +48 -0
- package/plugin/skills/dot-testing/UPSTREAM.json +8 -0
- package/plugin/skills/dot-testing/references/http.md +15 -0
- package/plugin/skills/dot-testing/references/modes.md +32 -0
- package/plugin/skills/dot-testing/references/shared-state.md +3 -0
- package/{content → plugin}/skills/dot-testing/references/typescript.md +2 -2
- package/plugin/skills/dot-writing-for-agents/SKILL.md +54 -0
- package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +8 -0
- package/plugin/skills/dot-writing-for-agents/references/pointers.md +27 -0
- package/plugin/skills/dot-writing-for-agents/references/skill-mechanics.md +22 -0
- package/plugin/skills/dot-writing-for-agents/references/steps.md +8 -0
- package/content/rules/comments.md +0 -13
- package/content/skills/dot-code-review/SKILL.md +0 -58
- package/content/skills/dot-debug/SKILL.md +0 -142
- package/content/skills/dot-debug/UPSTREAM.json +0 -8
- package/content/skills/dot-grilling/SKILL.md +0 -34
- package/content/skills/dot-grilling/agents/openai.yaml +0 -3
- package/content/skills/dot-handoff/SKILL.md +0 -20
- package/content/skills/dot-implement/SKILL.md +0 -52
- package/content/skills/dot-testing/SKILL.md +0 -44
- package/content/skills/dot-writing-for-agents/SKILL-MECHANICS.md +0 -22
- package/content/skills/dot-writing-for-agents/SKILL.md +0 -85
- package/content/skills/dot-writing-for-agents/UPSTREAM.json +0 -8
- /package/{content → plugin}/rules/core.md +0 -0
- /package/{content → plugin}/scaffold/.claude/settings.json.tmpl +0 -0
- /package/{content → plugin}/scaffold/.editorconfig.tmpl +0 -0
- /package/{content → plugin}/scaffold/.gitattributes.tmpl +0 -0
- /package/{content → plugin}/scaffold/CLAUDE.md.tmpl +0 -0
- /package/{content → plugin}/skills/dot-debug/agents/openai.yaml +0 -0
- /package/{content → plugin}/skills/dot-debug/scripts/hitl-loop.template.sh +0 -0
- /package/{content → plugin}/skills/dot-grill-me/agents/openai.yaml +0 -0
- /package/{content → plugin}/skills/dot-handoff/agents/openai.yaml +0 -0
- /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
|
|
4
|
-
|
|
5
|
-
|
|
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.
|
|
6
|
+
|
|
7
|
+
dotagents has two parts:
|
|
8
|
+
|
|
9
|
+
- A plugin with skills, agents, and an end-of-turn hook. 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
|
|
10
|
-
|
|
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
|
-
|
|
17
|
-
in
|
|
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,
|
|
29
|
-
|
|
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,76 @@ command in the repository:
|
|
|
44
69
|
npx --yes @igorlau/dotagents scaffold
|
|
45
70
|
```
|
|
46
71
|
|
|
47
|
-
The command creates the following files
|
|
48
|
-
never changes
|
|
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
|
|
56
|
-
| `.editorconfig`, `.gitattributes` | Keep whitespace and line endings
|
|
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`
|
|
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 approval at each "approve" or "go":
|
|
90
|
+
|
|
91
|
+
```mermaid
|
|
92
|
+
sequenceDiagram
|
|
93
|
+
actor User
|
|
94
|
+
participant Main as Main session
|
|
95
|
+
participant Agents as Step agents
|
|
96
|
+
User->>Main: dot-grill-me 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. Test stubs (dot-tester)
|
|
110
|
+
Agents-->>Main: Reply
|
|
111
|
+
Main-->>User: Summary
|
|
112
|
+
User->>Main: go
|
|
113
|
+
Main->>Agents: 2. Production code (dot-implementer)
|
|
114
|
+
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)
|
|
122
|
+
Agents-->>Main: Findings
|
|
123
|
+
Main-->>User: Findings
|
|
124
|
+
break A blocker or a high finding
|
|
125
|
+
Main-->>User: Stop. The files stay as they are.
|
|
126
|
+
end
|
|
127
|
+
User->>Main: dot-commit
|
|
128
|
+
Main-->>User: Each commit for approval
|
|
129
|
+
User->>Main: Approve
|
|
130
|
+
Main-->>User: Commits, and a tick in the roadmap
|
|
131
|
+
end
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
`dot-flow` never commits. In Codex and Copilot, `dot-flow` runs the four steps
|
|
135
|
+
in the main session, with the same approvals.
|
|
136
|
+
|
|
137
|
+
To learn the workflow step by step, read the [guide](docs/guide/README.md).
|
|
60
138
|
|
|
61
139
|
## Commands
|
|
62
140
|
|
|
63
|
-
The following table
|
|
141
|
+
The following table gives a summary of the commands. For the options, run
|
|
64
142
|
`dotagents --help`.
|
|
65
143
|
|
|
66
144
|
| Command | Description |
|
|
@@ -68,42 +146,58 @@ The following table summarizes the commands. For options, run
|
|
|
68
146
|
| `install` | Install globally. |
|
|
69
147
|
| `init` | Install into the current repository for collaborators. |
|
|
70
148
|
| `scaffold` | Create starter agent instructions in the current repository. |
|
|
71
|
-
| `update` | Apply the latest catalog to
|
|
149
|
+
| `update` | Apply the latest catalog to the installs. |
|
|
72
150
|
| `uninstall` | Remove everything that dotagents installed. |
|
|
73
|
-
| `doctor` |
|
|
151
|
+
| `doctor` | Find missing or changed files in the installs. |
|
|
74
152
|
| `list` | List the skills. |
|
|
75
153
|
| `self-update` | Run `update` with the latest release. |
|
|
154
|
+
| `check enable`, `check disable` | Start or stop the plugin `check` hook in the current repository. |
|
|
76
155
|
|
|
77
|
-
dotagents
|
|
78
|
-
To overwrite
|
|
156
|
+
dotagents does not overwrite a file that you changed or that it did not
|
|
157
|
+
write. To overwrite the file, add `--force`.
|
|
79
158
|
|
|
80
|
-
## What
|
|
159
|
+
## What is included
|
|
81
160
|
|
|
82
|
-
The always-on rules in [`
|
|
161
|
+
The always-on rules in [`plugin/rules/`](plugin/rules/) cover working
|
|
83
162
|
agreements, the smallest complete change from
|
|
84
|
-
[ponytail](https://github.com/DietrichGebert/ponytail),
|
|
163
|
+
[ponytail](https://github.com/DietrichGebert/ponytail), code comments, code
|
|
164
|
+
style, and writing.
|
|
85
165
|
|
|
86
|
-
The
|
|
166
|
+
The 15 skills in [`plugin/skills/`](plugin/skills/) load when a task needs
|
|
167
|
+
them:
|
|
87
168
|
|
|
88
169
|
| Skill | Purpose |
|
|
89
170
|
| ----- | ------- |
|
|
90
|
-
| `dot-
|
|
91
|
-
| `dot-
|
|
92
|
-
| `dot-
|
|
93
|
-
| `dot-
|
|
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. |
|
|
174
|
+
| `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. |
|
|
177
|
+
| `dot-implement` | Write the code of a change or roadmap task to the standards of the repository and the language. |
|
|
178
|
+
| `dot-code-review` | Review a diff for correctness bugs and maintainability problems. |
|
|
179
|
+
| `dot-comments` | Delete the comments in a diff that no exception protects. |
|
|
94
180
|
| `dot-commit` | Commit changes as small, logical commits. |
|
|
95
|
-
| `dot-
|
|
96
|
-
| `dot-
|
|
97
|
-
| `dot-
|
|
98
|
-
| `dot-
|
|
99
|
-
| `dot-roadmap` | Split a grilled plan into phases and self-contained tasks. |
|
|
100
|
-
| `dot-handoff` | Summarize a conversation for another agent. |
|
|
181
|
+
| `dot-debug` | Find the cause of a hard bug with a feedback loop. |
|
|
182
|
+
| `dot-correct` | Change a mistake that agents repeat into a check that prevents it. |
|
|
183
|
+
| `dot-handoff` | Give a summary of a conversation to another agent. |
|
|
184
|
+
| `dot-docs-writing` | Give docs the structure and format of the Google developer documentation style. |
|
|
101
185
|
| `dot-writing-for-agents` | Write skills, `AGENTS.md`, and `CLAUDE.md` files. |
|
|
102
186
|
|
|
187
|
+
The plugin also has 3 agents in [`plugin/agents/`](plugin/agents/).
|
|
188
|
+
`dot-flow` starts a new agent for each step, so each step starts with a clean
|
|
189
|
+
context:
|
|
190
|
+
|
|
191
|
+
| Agent | Purpose |
|
|
192
|
+
| ----- | ------- |
|
|
193
|
+
| `dot-tester` | Write the test stubs, or fill them after the code exists. |
|
|
194
|
+
| `dot-implementer` | Write the production code of a task. |
|
|
195
|
+
| `dot-reviewer` | Review the changes of a task. |
|
|
196
|
+
|
|
103
197
|
## More information
|
|
104
198
|
|
|
105
199
|
- [Design specification](SPEC.md)
|
|
106
200
|
- [Contributing guide](CONTRIBUTING.md): report problems and propose changes
|
|
107
|
-
|
|
201
|
+
with pull requests
|
|
108
202
|
- [Third-party notices](THIRD_PARTY_NOTICES.md)
|
|
109
203
|
- [License (MIT)](LICENSE)
|
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -35,9 +35,9 @@ SOFTWARE.
|
|
|
35
35
|
|
|
36
36
|
## DietrichGebert/ponytail
|
|
37
37
|
|
|
38
|
-
The `ponytail` rules in `
|
|
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
|
-
`
|
|
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
|
package/dist/build-info.json
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"commit":"
|
|
1
|
+
{"commit":"0b97ba2"}
|
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 {
|
|
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 =
|
|
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 =
|
|
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
|
-
|
|
206
|
+
function readConfig() {
|
|
180
207
|
const file = configFile();
|
|
181
|
-
|
|
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
|
-
|
|
217
|
+
function writeConfig(changes) {
|
|
184
218
|
fs.mkdirSync(configDir(), { recursive: true });
|
|
185
|
-
fs.writeFileSync(configFile(), JSON.stringify({
|
|
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
|
|
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.
|
|
3
|
+
"version": "1.0.15",
|
|
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
|
-
"
|
|
20
|
+
"plugin",
|
|
21
21
|
"THIRD_PARTY_NOTICES.md"
|
|
22
22
|
],
|
|
23
23
|
"engines": {
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "dotagents",
|
|
3
|
+
"description": "Skills, agents, and hooks for a planned, test-first, 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,38 @@
|
|
|
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
|
+
- **Handoff**: the reply of the stub step, with the pending tests that it wrote.
|
|
18
|
+
|
|
19
|
+
When a field is missing, stop and report it.
|
|
20
|
+
|
|
21
|
+
Do not commit, and do not tick the roadmap checkbox.
|
|
22
|
+
|
|
23
|
+
## Output
|
|
24
|
+
|
|
25
|
+
End with this reply, and keep the summary to 3 sentences or fewer. Copy the two handoff fields from step 5 of `dot-implement`:
|
|
26
|
+
|
|
27
|
+
```markdown
|
|
28
|
+
**Summary:** <what you did>
|
|
29
|
+
**Checks:** <the type checker, linter, and test commands, with their result lines>
|
|
30
|
+
**Files:** <the production files that you changed>
|
|
31
|
+
**Blockers:** <what stops the next step, or "none">
|
|
32
|
+
|
|
33
|
+
**Expected failures:**
|
|
34
|
+
- `<test file>`: <test name>: <the new behavior that the test must assert>
|
|
35
|
+
|
|
36
|
+
**Behaviors that need tests:**
|
|
37
|
+
- `<module>`: <a behavior that the change adds or changes, and that no test case covers>
|
|
38
|
+
```
|
|
@@ -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,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: dot-tester
|
|
3
|
+
description: Write the tests of one roadmap task with the dot-testing skill, in stub mode before the code exists or in fill mode after it. Use for the test steps of the dot-flow skill.
|
|
4
|
+
skills: dotagents:dot-testing
|
|
5
|
+
disallowedTools: Agent
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Tester
|
|
9
|
+
|
|
10
|
+
Run one test step of a roadmap task. Follow the `dot-testing` skill and its `references/modes.md`.
|
|
11
|
+
|
|
12
|
+
## Input
|
|
13
|
+
|
|
14
|
+
The prompt gives these fields:
|
|
15
|
+
|
|
16
|
+
- **Task**: the path of the roadmap task file.
|
|
17
|
+
- **Mode**: `stub` or `fill`.
|
|
18
|
+
- **Handoff**: in fill mode, the handoff of the implementation step, with the "Expected failures" and "Behaviors that need tests" fields.
|
|
19
|
+
|
|
20
|
+
When a field is missing, stop and report it.
|
|
21
|
+
|
|
22
|
+
Do not commit, and do not tick the roadmap checkbox.
|
|
23
|
+
|
|
24
|
+
## Output
|
|
25
|
+
|
|
26
|
+
End with this reply, and keep the summary to 3 sentences or fewer:
|
|
27
|
+
|
|
28
|
+
```markdown
|
|
29
|
+
**Summary:** <what you did>
|
|
30
|
+
**Tests:** <the test command and its result line>
|
|
31
|
+
**Files:** <the test files that you changed>
|
|
32
|
+
**Blockers:** <what stops the next step, or "none">
|
|
33
|
+
```
|