@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
|
@@ -8,9 +8,7 @@ disable-model-invocation: true
|
|
|
8
8
|
|
|
9
9
|
Change the repository so that the next agent cannot make the same mistake again. Assume every contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. A change that looks right from one file must be right for the whole repository.
|
|
10
10
|
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. Use the type checker, linter, and test framework that the repository already has.
|
|
11
|
+
Use the type checker, linter, and test framework that the repository already has.
|
|
14
12
|
|
|
15
13
|
## 1. Name the mistake class
|
|
16
14
|
|
|
@@ -1,17 +1,15 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: dot-debug
|
|
3
|
-
description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose" or "debug this", or
|
|
3
|
+
description: Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose" or "debug this", or when the error does not show the cause of a failure or a slowdown.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Diagnose bugs
|
|
7
7
|
|
|
8
|
-
Use this method for hard bugs. Skip a phase only when you can state the reason.
|
|
8
|
+
Use this method for hard bugs. When the error message already shows the cause, fix the bug directly. Skip a phase only when you can state the reason.
|
|
9
9
|
|
|
10
10
|
To learn the modules in the area, read `GLOSSARY.md` if it exists, and read the ADRs for the area that you change.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. Build the feedback loop with the test framework, scripts, and tools of the repository.
|
|
12
|
+
Build the feedback loop with the test framework, scripts, and tools of the repository.
|
|
15
13
|
|
|
16
14
|
## Redact
|
|
17
15
|
|
|
@@ -104,7 +102,7 @@ Write the regression test **before the fix**, but only if a **correct seam** exi
|
|
|
104
102
|
|
|
105
103
|
A correct seam is one where the test runs the **real bug pattern** as it occurs at the call site. Sometimes the only seam is too shallow: a test with one caller when the bug needs several callers, or a unit test that cannot repeat the chain that triggered the bug. A regression test there gives false confidence.
|
|
106
104
|
|
|
107
|
-
**If no correct seam exists, that is the finding.** Note it. The architecture of the codebase prevents a test that locks the bug down.
|
|
105
|
+
**If no correct seam exists, that is the finding.** Note it. The architecture of the codebase prevents a test that locks the bug down. Report it to the user at the end.
|
|
108
106
|
|
|
109
107
|
If a correct seam exists:
|
|
110
108
|
|
|
@@ -4,5 +4,5 @@
|
|
|
4
4
|
"commit": "49dd158d1076134a641b33efb035946536778336",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"modified": true,
|
|
7
|
-
"notes": "Renamed from diagnosing-bugs to debug (frontmatter name and display_name). Added a
|
|
7
|
+
"notes": "Renamed from diagnosing-bugs to debug (frontmatter name and display_name). Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Added the root cause and premise rules to Phase 5, condensed from pstack/skills/principle-fix-root-causes and pstack/skills/principle-attack-the-premise in https://github.com/cursor/plugins at commit a5539b15a3d56e04992565aafee2b37051329ce3 (MIT). Rewrote the text under plugin/rules/writing.md. Moved the ways to build a loop, the bugs that are not deterministic, and the case with no loop to references/loops.md."
|
|
8
8
|
}
|
|
@@ -7,9 +7,7 @@ description: Write and edit developer documentation in the Google developer docu
|
|
|
7
7
|
|
|
8
8
|
Write documentation that a developer in a hurry, who reads in their second language, can follow on the first pass. This skill covers the frame, structure, and format of a document, based on the Google developer documentation style guide. The always-on writing rule governs the prose, and it wins any conflict with this skill.
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. This includes the project's documentation style guide, prose linter configuration such as Vale, and the structure and terms of its current docs.
|
|
10
|
+
Follow the project's documentation style guide, its prose linter configuration such as Vale, and the structure and terms of its current docs. They win a conflict with this skill.
|
|
13
11
|
|
|
14
12
|
## 1. Frame the document
|
|
15
13
|
|
|
@@ -1,16 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: dot-flow
|
|
3
|
-
description: Take one roadmap task through
|
|
3
|
+
description: Take one roadmap task through implementation, tests, and review, and stop for your decision after the review.
|
|
4
4
|
disable-model-invocation: true
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Flow
|
|
8
8
|
|
|
9
|
-
Take one task from a `dot-roadmap` roadmap through
|
|
10
|
-
|
|
11
|
-
## Repository conventions first
|
|
12
|
-
|
|
13
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard.
|
|
9
|
+
Take one task from a `dot-roadmap` roadmap through three steps: implementation, tests, and review. Each step runs in a fresh agent with one skill. You coordinate the steps, and you verify each reply with the commands that it names. The agents write the code, the tests, and the review. The user decides after the review.
|
|
14
10
|
|
|
15
11
|
## 1. Pin the task
|
|
16
12
|
|
|
@@ -22,54 +18,58 @@ Done when you can name the task file and its goal.
|
|
|
22
18
|
|
|
23
19
|
## 2. Pick the runner
|
|
24
20
|
|
|
25
|
-
Use the agents of the dotagents plugin when the `Agent` tool can start them: `dotagents:dot-
|
|
21
|
+
Use the agents of the dotagents plugin when the `Agent` tool can start them: `dotagents:dot-implementer`, `dotagents:dot-tester`, and `dotagents:dot-reviewer`. Otherwise, such as in Codex or Copilot, read [`references/inline.md`](references/inline.md), and run each step inline with the same verification and stops.
|
|
26
22
|
|
|
27
|
-
## 3. Run the steps
|
|
23
|
+
## 3. Run and verify the steps
|
|
28
24
|
|
|
29
25
|
Run the steps in this order. For each step, start a new agent of the named type, not a fork, so that each step starts with a fresh context:
|
|
30
26
|
|
|
31
27
|
| Step | Agent | Prompt fields |
|
|
32
28
|
| ---- | ----- | ------------- |
|
|
33
|
-
| 1.
|
|
34
|
-
| 2.
|
|
35
|
-
| 3.
|
|
36
|
-
| 4. Review | `dotagents:dot-reviewer` | Task, Handoff: the replies of steps 1 to 3 |
|
|
29
|
+
| 1. Implement | `dotagents:dot-implementer` | Task |
|
|
30
|
+
| 2. Test | `dotagents:dot-tester` | Task, Handoff: the reply of step 1 |
|
|
31
|
+
| 3. Review | `dotagents:dot-reviewer` | Task, Handoff: the replies of steps 1 and 2, Findings: only on a fix run |
|
|
37
32
|
|
|
38
33
|
Write the prompt as labeled fields, and leave out a field that the step does not take:
|
|
39
34
|
|
|
40
35
|
```markdown
|
|
41
36
|
**Task:** <path of the task file>
|
|
42
|
-
**Mode:** <stub | fill>
|
|
43
37
|
**Handoff:**
|
|
44
38
|
<the replies of the earlier steps, unchanged>
|
|
39
|
+
**Findings:**
|
|
40
|
+
<the findings that the user named, unchanged>
|
|
45
41
|
```
|
|
46
42
|
|
|
47
|
-
Copy the replies unchanged, because the agents read their fields.
|
|
43
|
+
Copy the replies and the findings unchanged, because the agents read their fields. Add no other fields or instructions, such as a list of files to review.
|
|
48
44
|
|
|
49
|
-
|
|
45
|
+
A reply is a claim, not a result. After steps 1 and 2, run each command that the reply names in its **Checks** or **Tests** line, and read only the result line and the names of the tests that fail. Keep the main context small: do not read the changed files. The step is **verified** when all of these are true:
|
|
50
46
|
|
|
51
|
-
|
|
47
|
+
- The type checker and the linter pass.
|
|
48
|
+
- After step 1, each test that fails is in "Expected failures".
|
|
49
|
+
- After step 2, the test command passes.
|
|
50
|
+
- The reply has no blockers.
|
|
52
51
|
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
52
|
+
After a verified step, show the user one line, such as "Step 1 of 3: verified, `npm run check` passes", and start the next step. Do not wait.
|
|
53
|
+
|
|
54
|
+
Stop the flow, keep the files as they are, and ask the user how to continue in these cases:
|
|
55
|
+
|
|
56
|
+
- A reply has blockers. Show them.
|
|
57
|
+
- A step is not verified. Show the command, your result line, and the line of the reply.
|
|
58
|
+
- The `check` hook reports a failure to you. An agent left it, so the step is not verified. Show the output, and do not edit the code yourself.
|
|
59
59
|
|
|
60
|
-
|
|
60
|
+
Done when the review reply arrived, or the flow stopped.
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
## 4. Decide after the review
|
|
63
63
|
|
|
64
|
-
|
|
64
|
+
Show the user the **Highest severity** line and one line for each finding: its severity, summary, and `file:line`. Show each `high` finding with its **Fix** line. The presumed blockers of the maintainability pass are `high`. Then wait for the user to pick one:
|
|
65
65
|
|
|
66
|
-
-
|
|
67
|
-
-
|
|
66
|
+
- **Fix**: the user names the findings to fix. Run step 1 again in a new agent, with the findings as a **Findings** field, then run steps 2 and 3 again. Give step 3 the same **Findings** field. The review target stays the full uncommitted change of the task, not the files that the fix changed.
|
|
67
|
+
- **Accept**: the user accepts the findings that remain.
|
|
68
68
|
|
|
69
|
-
Done when the user
|
|
69
|
+
Done when the user accepts.
|
|
70
70
|
|
|
71
71
|
## 5. Finish
|
|
72
72
|
|
|
73
|
-
List the files that the steps changed, from the **Files** lines of the replies.
|
|
73
|
+
List the files that the steps changed, from the **Files** lines of the replies. Suggest the `dot-commit` skill, and name the task file, so that `dot-commit` can tick its checkbox.
|
|
74
74
|
|
|
75
75
|
Do not commit, and do not tick the roadmap checkbox: `dot-commit` ticks it when the commits finish the task.
|
|
@@ -1,42 +1,9 @@
|
|
|
1
1
|
# Inline mode
|
|
2
2
|
|
|
3
|
-
Inline steps for the [`dot-flow`](../SKILL.md) skill, for an agent that cannot start the dotagents agents, such as Codex or Copilot. The
|
|
3
|
+
Inline steps for the [`dot-flow`](../SKILL.md) skill, for an agent that cannot start the dotagents agents, such as Codex or Copilot. The verification, the stops, and the decision after the review stay as `SKILL.md` gives them. You run each step yourself, in this conversation, instead of in an agent.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
1. Implement: use the `dot-implement` skill for the task, and end the step with its handoff. Write no tests in this step.
|
|
6
|
+
2. Test: use the `dot-testing` skill with its `references/after-implement.md` and the handoff of step 1, and end the step with the reply that the reference gives.
|
|
7
|
+
3. Review: use the `dot-code-review` skill for the task. The target is `git diff HEAD`, plus the untracked files that `git status --short` lists. Start the report with the line `**Highest severity:** <high | medium | low | none>`. Also read the `## Requirements` section of the roadmap `README.md`, check the change against every non-negotiable (`NN`) and each business rule (`BR`) that the task names, and report a breached `NN` as a `high` finding. Review the whole target, also on a fix run. On a fix run, also check that each fixed finding is gone, and that each fix did not break other code. Report every finding at every severity, and keep the code as it is. Delete each test that you write to prove a finding.
|
|
6
8
|
|
|
7
|
-
|
|
8
|
-
2. Implement: use the `dot-implement` skill for the task, with the reply of step 1.
|
|
9
|
-
3. Fill: use the `dot-testing` skill in fill mode for the task, with the reply of step 2.
|
|
10
|
-
4. Review: use the `dot-code-review` skill for the task. The target is `git diff HEAD`, plus the untracked files that `git status --short` lists. Report the findings, and keep the code as it is. Delete each test that you write to prove a finding.
|
|
11
|
-
|
|
12
|
-
Do only the work of the current step, even when the next step looks small. The steps share one context, so read only what the current step needs.
|
|
13
|
-
|
|
14
|
-
## Replies
|
|
15
|
-
|
|
16
|
-
End each step with its reply, then show the summary of `SKILL.md` step 4. Keep each summary to 3 sentences or fewer.
|
|
17
|
-
|
|
18
|
-
Steps 1 and 3:
|
|
19
|
-
|
|
20
|
-
```markdown
|
|
21
|
-
**Summary:** <what you did>
|
|
22
|
-
**Tests:** <the test command and its result line>
|
|
23
|
-
**Files:** <the test files that you changed>
|
|
24
|
-
**Blockers:** <what stops the next step, or "none">
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
Step 2, with the handoff fields from step 5 of `dot-implement`:
|
|
28
|
-
|
|
29
|
-
```markdown
|
|
30
|
-
**Summary:** <what you did>
|
|
31
|
-
**Checks:** <the type checker, linter, and test commands, with their result lines>
|
|
32
|
-
**Files:** <the production files that you changed>
|
|
33
|
-
**Blockers:** <what stops the next step, or "none">
|
|
34
|
-
|
|
35
|
-
**Expected failures:**
|
|
36
|
-
- `<test file>`: <test name>: <the new behavior that the test must assert>
|
|
37
|
-
|
|
38
|
-
**Behaviors that need tests:**
|
|
39
|
-
- `<module>`: <a behavior that the change adds or changes, and that no test case covers>
|
|
40
|
-
```
|
|
41
|
-
|
|
42
|
-
Step 4: start with the line `**Highest severity:** <high | medium | low | none>`, then give the report of `dot-code-review`.
|
|
9
|
+
Do only the work of the current step, even when the next step looks small. After steps 1 and 2, run the commands of the reply again before you start the next step: the verification of `SKILL.md` applies to your own replies too. The steps share one context, so read only what the current step needs.
|
|
@@ -29,6 +29,4 @@ Facts are your job, never the user's. When a frontier question needs a fact from
|
|
|
29
29
|
|
|
30
30
|
The session is done when the frontier is empty: you visited every branch of the design tree, and you assumed nothing in silence. Do not act on the result until the user confirms that you reached a shared understanding.
|
|
31
31
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. Base your recommended answers on those conventions.
|
|
32
|
+
Base your recommended answers on the conventions of the repository.
|
|
@@ -4,5 +4,5 @@
|
|
|
4
4
|
"commit": "49dd158d1076134a641b33efb035946536778336",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"modified": true,
|
|
7
|
-
"notes": "Added a
|
|
7
|
+
"notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md, and replaced the emoji in the round format with text labels."
|
|
8
8
|
}
|
|
@@ -15,6 +15,4 @@ Redact all sensitive information, such as API keys, passwords, and personally id
|
|
|
15
15
|
|
|
16
16
|
If the user passed arguments, they describe the focus of the next session. Write the document for that focus.
|
|
17
17
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. List the repository conventions that the next agent must follow, by path.
|
|
18
|
+
List the repository conventions that the next agent must follow, by path.
|
|
@@ -4,5 +4,5 @@
|
|
|
4
4
|
"commit": "49dd158d1076134a641b33efb035946536778336",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"modified": true,
|
|
7
|
-
"notes": "Added a
|
|
7
|
+
"notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md."
|
|
8
8
|
}
|
|
@@ -7,15 +7,11 @@ description: Implement a feature, fix, refactor, or roadmap task to the reposito
|
|
|
7
7
|
|
|
8
8
|
Turn a request, an approved plan, or a roadmap task into a production code change that ends **green**: the type checker and the linter pass, no current test fails by accident, and you have shown the output. Write no tests: a separate test step writes them.
|
|
9
9
|
|
|
10
|
-
## Repository conventions first
|
|
11
|
-
|
|
12
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. Write code that fits those conventions.
|
|
13
|
-
|
|
14
10
|
## 1. Pin the work
|
|
15
11
|
|
|
16
12
|
Identify the source of the work:
|
|
17
13
|
|
|
18
|
-
- **Roadmap task**: a task file from `dot-roadmap`, or a roadmap directory. With only a directory, pick the lowest-id unticked task whose blockers are all ticked in its `README.md`. If a named task has an unticked blocker, stop and name it. Read the task file and the roadmap's decisions in full. The task's "Out of scope" is a hard boundary.
|
|
14
|
+
- **Roadmap task**: a task file from `dot-roadmap`, or a roadmap directory. With only a directory, pick the lowest-id unticked task whose blockers are all ticked in its `README.md`. If a named task has an unticked blocker, stop and name it. Read the task file and the roadmap's requirements and decisions in full. The task's "Out of scope" is a hard boundary.
|
|
19
15
|
- **Approved plan**: the plan in this conversation, from `dot-plan` or the user.
|
|
20
16
|
- **Request**: anything else.
|
|
21
17
|
|
|
@@ -23,7 +19,7 @@ Done when you can state the goal, the scope boundary, and the check that proves
|
|
|
23
19
|
|
|
24
20
|
## 2. Plan when needed
|
|
25
21
|
|
|
26
|
-
A roadmap task or an approved plan is already the plan. For a request that
|
|
22
|
+
A roadmap task or an approved plan is already the plan. For a request that spans several modules, or that has more than one reasonable design, use the `dot-plan` skill and wait for the user's approval before you change any file. Any other request goes straight to step 3.
|
|
27
23
|
|
|
28
24
|
## 3. Build
|
|
29
25
|
|
|
@@ -44,7 +40,7 @@ Run the type checker and the linter. They are hard checks: fix each error that t
|
|
|
44
40
|
|
|
45
41
|
Check every acceptance criterion one by one. When only an expected failure or a test that does not exist yet blocks a criterion, leave the criterion open for the test step, and list it in the handoff.
|
|
46
42
|
|
|
47
|
-
When a hard check or an unexpected failure stays red, or the task or plan turns out wrong (a fact contradicts it, or it needs work outside its scope), stop. Report the check that failed or the fact that conflicts, and propose a change to the task or plan. Keep the task file, the roadmap's decisions, and the plan as they are until the user agrees, and keep the change inside its scope.
|
|
43
|
+
When a hard check or an unexpected failure stays red, or the task or plan turns out wrong (a fact contradicts it, or it needs work outside its scope), stop. Report the check that failed or the fact that conflicts, and propose a change to the task or plan. Keep the task file, the roadmap's requirements and decisions, and the plan as they are until the user agrees, and keep the change inside its scope.
|
|
48
44
|
|
|
49
45
|
Do not tick the roadmap checkbox. The `dot-commit` skill ticks it after the review step.
|
|
50
46
|
|
|
@@ -52,9 +48,14 @@ Done when the hard checks pass and no unexpected failure remains.
|
|
|
52
48
|
|
|
53
49
|
## 5. Hand off
|
|
54
50
|
|
|
55
|
-
End with
|
|
51
|
+
End with this handoff. The `dot-testing` skill reads its last two fields:
|
|
56
52
|
|
|
57
53
|
```markdown
|
|
54
|
+
**Summary:** <what you did, in 3 sentences or fewer>
|
|
55
|
+
**Checks:** <the type checker, linter, and test commands, each with its result line>
|
|
56
|
+
**Files:** <the production files that you changed>
|
|
57
|
+
**Blockers:** <what stops the test step, and what you skipped or could not check, or "none">
|
|
58
|
+
|
|
58
59
|
**Expected failures:**
|
|
59
60
|
- `<test file>`: <test name>: <the new behavior that the test must assert>
|
|
60
61
|
|
|
@@ -62,4 +63,6 @@ End with the verification output, anything that you skipped or could not check,
|
|
|
62
63
|
- `<module>`: <a behavior that the change adds or changes, and that no test case covers>
|
|
63
64
|
```
|
|
64
65
|
|
|
65
|
-
Write "none" under a field that has no items.
|
|
66
|
+
Write "none" under a field that has no items.
|
|
67
|
+
|
|
68
|
+
When `dot-flow` or an agent prompt gave you only the implementation step, stop after the handoff. Otherwise, use the `dot-testing` skill with this handoff now, then suggest the `dot-code-review` skill and the `dot-commit` skill. Leave the commit to the user.
|
|
@@ -1,16 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: dot-plan
|
|
3
|
-
description: Plan a change as small, verifiable steps before writing code. Use when the user asks for a plan, or before a
|
|
3
|
+
description: Plan a change as small, verifiable steps before writing code. Use when the user asks for a plan, or before a change that spans several modules or has more than one reasonable design.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Plan
|
|
7
7
|
|
|
8
8
|
A plan turns a request into a sequence of **vertical slices**: each slice is a small change that leaves the system in a state that works and ends on a check you can run.
|
|
9
9
|
|
|
10
|
-
## Repository conventions first
|
|
11
|
-
|
|
12
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. Plan changes that fit those conventions.
|
|
13
|
-
|
|
14
10
|
## 1. Pin the goal
|
|
15
11
|
|
|
16
12
|
Restate the goal in one or two sentences, and name the **done criterion**: the observable result that tells the user the work is finished (a test that passes, a command's output, a behavior in the UI).
|
|
@@ -23,19 +19,32 @@ Read the code, tests, configuration, and docs that the change touches. Trace eac
|
|
|
23
19
|
|
|
24
20
|
Facts are your job: look them up. Do not ask the user. Done when you can name every file you expect to change and why.
|
|
25
21
|
|
|
26
|
-
## 3.
|
|
22
|
+
## 3. List the requirements
|
|
23
|
+
|
|
24
|
+
List the requirements in four categories, in this order. Give each requirement an ID with the category prefix and a number, such as `FR2`:
|
|
25
|
+
|
|
26
|
+
- **User needs** (`UN`): who uses the change, and what they must be able to do.
|
|
27
|
+
- **Functional requirements** (`FR`): the behavior that the system must have.
|
|
28
|
+
- **Business rules** (`BR`): the domain constraints and policies, such as "a refund cannot exceed the payment".
|
|
29
|
+
- **Non-negotiables** (`NN`): the hard limits that no trade-off can break, such as security, compatibility, a performance budget, or "no new dependency".
|
|
30
|
+
|
|
31
|
+
Take the requirements from the request, the code, and the docs. Ask the user only for the items that you cannot find there. Write "none" for an empty category. Show the lists, and wait for the user to approve them.
|
|
32
|
+
|
|
33
|
+
Done when the user approves the four lists.
|
|
34
|
+
|
|
35
|
+
## 4. Surface decisions
|
|
27
36
|
|
|
28
37
|
List the choices that the facts do not settle: behavior in edge cases, trade-offs, names that users see, anything hard to reverse. Give your recommendation for each one.
|
|
29
38
|
|
|
30
39
|
If the list is long or the decisions depend on each other, use the `dot-grilling` skill to resolve them with the user. Done when every decision has an answer or is marked as an open question in the plan.
|
|
31
40
|
|
|
32
|
-
##
|
|
41
|
+
## 5. Show entity schemas
|
|
33
42
|
|
|
34
|
-
When the change adds or changes a domain entity, read [`references/entity-schemas.md`](references/entity-schemas.md). Show
|
|
43
|
+
When the change adds or changes a domain entity, read [`references/entity-schemas.md`](references/entity-schemas.md). Show the full schema of each new entity, and a before and after diff of each changed entity. Wait for the user to approve the schemas before you slice the work.
|
|
35
44
|
|
|
36
45
|
Done when the user approves each schema, or the change touches no domain entity.
|
|
37
46
|
|
|
38
|
-
##
|
|
47
|
+
## 6. Slice the work
|
|
39
48
|
|
|
40
49
|
Write the steps. For each step, include:
|
|
41
50
|
|
|
@@ -46,20 +55,32 @@ Put the removal steps first: delete the dead code, redundant checks, and stubs t
|
|
|
46
55
|
|
|
47
56
|
Done when every step has a check that can fail, and the last check matches the done criterion.
|
|
48
57
|
|
|
49
|
-
##
|
|
58
|
+
## 7. Present and wait
|
|
50
59
|
|
|
51
60
|
Show the plan in this shape:
|
|
52
61
|
|
|
53
62
|
```markdown
|
|
54
63
|
**Goal:** <one sentence>
|
|
55
64
|
**Done when:** <done criterion>
|
|
65
|
+
|
|
66
|
+
## Requirements
|
|
67
|
+
|
|
68
|
+
- **User needs:** UN1: <need>, or none
|
|
69
|
+
- **Functional requirements:** FR1: <requirement>, or none
|
|
70
|
+
- **Business rules:** BR1: <rule>, or none
|
|
71
|
+
- **Non-negotiables:** NN1: <limit>, or none
|
|
72
|
+
|
|
56
73
|
**Schemas:** <the approved entity schemas, or none>
|
|
57
74
|
|
|
58
|
-
1. <change
|
|
75
|
+
1. <change>. Check: <command or observation>
|
|
59
76
|
2. ...
|
|
60
77
|
|
|
61
78
|
**Open questions:** <none, or the list>
|
|
62
79
|
**Risks:** <what could make the plan wrong>
|
|
63
80
|
```
|
|
64
81
|
|
|
65
|
-
|
|
82
|
+
Ask the user where to write the plan, and offer `.tmp/plans/<plan-slug>/plan.md` at the repository root as the default. Wait for the user's approval before you change any file.
|
|
83
|
+
|
|
84
|
+
After the approval, write the plan to that path in the same shape. For a path under `.tmp`, first run `git check-ignore -q .tmp`: if Git does not ignore `.tmp`, stop and tell the user. Do not edit `.gitignore`. Write any other path that the user picks.
|
|
85
|
+
|
|
86
|
+
When the plan changes during the work, update the plan file and say what changed.
|
|
@@ -4,7 +4,7 @@ Schema details for the [`dot-plan`](../SKILL.md) skill. A domain entity is a thi
|
|
|
4
4
|
|
|
5
5
|
## Format
|
|
6
6
|
|
|
7
|
-
Write each schema in JSON Schema draft 2020-12
|
|
7
|
+
Write each schema in the form that the repository already uses for its entities, such as a TypeScript type, a Zod schema, or SQL DDL, so the approved schema is the code that lands. When the repository has no such form, use JSON Schema draft 2020-12 in a `json` block, with `$schema`, `$id`, `title`, `type`, `required`, and `properties`.
|
|
8
8
|
|
|
9
9
|
- For a new entity, show the full schema.
|
|
10
10
|
- For a changed entity, show a `diff` block of the schema before and after the change.
|
|
@@ -13,13 +13,13 @@ Put the schemas in the plan. Do not commit schema files to the target repository
|
|
|
13
13
|
|
|
14
14
|
## Model the domain
|
|
15
15
|
|
|
16
|
-
Make the illegal states impossible to write in the schema:
|
|
16
|
+
Make the illegal states impossible to write in the schema. In JSON Schema:
|
|
17
17
|
|
|
18
18
|
- Model a lifecycle as one `status` field with an `enum`, not as booleans that must agree, such as `isPaid` and `isShipped`.
|
|
19
19
|
- Model variants with a `kind` field and `oneOf`, not as one object with optional fields for each variant.
|
|
20
20
|
- Use `minItems: 1` for a list that must have an item.
|
|
21
21
|
|
|
22
|
-
## Example: a new entity
|
|
22
|
+
## Example: a new entity in JSON Schema
|
|
23
23
|
|
|
24
24
|
```json
|
|
25
25
|
{
|
|
@@ -9,15 +9,15 @@ disable-model-invocation: true
|
|
|
9
9
|
|
|
10
10
|
A roadmap splits a plan into **phases**, and each phase into **tasks**. A phase ends on a **milestone**: an observable state where the system works and could ship. A task is **self-contained**: a fresh agent session can build it from its file alone, and a reviewer can judge its diff in one session.
|
|
11
11
|
|
|
12
|
-
## Repository conventions first
|
|
13
|
-
|
|
14
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. Write tasks whose changes fit those conventions.
|
|
15
|
-
|
|
16
12
|
## 1. Load the plan
|
|
17
13
|
|
|
18
|
-
|
|
14
|
+
Take the plan from the first of these sources that exists:
|
|
19
15
|
|
|
20
|
-
|
|
16
|
+
1. The path or URL that the user passed. Read it in full.
|
|
17
|
+
2. The plan in this conversation, usually from `dot-plan`.
|
|
18
|
+
3. The plan files under `.tmp/plans/`. With one file, use it. With more than one, ask the user which one.
|
|
19
|
+
|
|
20
|
+
Synthesize the plan. Do not interview the user. If the plan still has unsettled decisions, list them and suggest `dot-grilling` before you go on. Done when you can state the **destination** (what is true when the whole roadmap is done), the requirements with their IDs, and every decision the plan made.
|
|
21
21
|
|
|
22
22
|
## 2. Gather facts
|
|
23
23
|
|
|
@@ -41,12 +41,14 @@ Split each phase into tasks. Each task:
|
|
|
41
41
|
- Is a **vertical slice**: a narrow but complete path through every layer it needs, verifiable on its own.
|
|
42
42
|
- Keeps a refactor separate from a behavior change.
|
|
43
43
|
- Fits one fresh agent session and one reviewable diff, roughly a few hundred changed lines.
|
|
44
|
-
- Lists its **test cases**: the test names, each with the test file where it belongs, in the order and with the names that the `dot-testing` skill gives. For controller, integration, and end-to-end tests, use
|
|
44
|
+
- Lists its **test cases**: the test names, each with the test file where it belongs, in the order and with the names that the `dot-testing` skill gives. For controller, integration, and end-to-end tests, use `references/http.md` of `dot-testing`. `dot-testing` writes them after `dot-implement`. Write "none" when the task changes no tested behavior.
|
|
45
45
|
- Declares its **blockers**: the tasks that must be done first, by id (`2.3` is phase 2, task 3). A task without blockers can start now.
|
|
46
46
|
|
|
47
47
|
When one mechanical change breaks many call sites at once, read [`references/wide-refactor.md`](references/wide-refactor.md).
|
|
48
48
|
|
|
49
|
-
|
|
49
|
+
When a bullet of a task's requirements implements a functional requirement (`FR`) or a business rule (`BR`), start the bullet with its ID. User needs (`UN`) and non-negotiables (`NN`) apply to the whole roadmap: they stay in `README.md`, and no task claims them.
|
|
50
|
+
|
|
51
|
+
Done when every `FR` and `BR` belongs to at least one task or to the roadmap's out-of-scope list, every decision belongs to exactly one task or to that list, and every task has acceptance criteria that can fail.
|
|
50
52
|
|
|
51
53
|
## 5. Review with the user
|
|
52
54
|
|
|
@@ -72,17 +74,25 @@ Write to `.tmp/roadmaps/<roadmap-slug>/` at the repository root. First run `git
|
|
|
72
74
|
└── 01-<task-slug>.md
|
|
73
75
|
```
|
|
74
76
|
|
|
75
|
-
`README.md` is the index and the single source of truth for decisions; task files link to it and do not restate them. Put the entity schemas that the user approved in `dot-plan` in the decisions:
|
|
77
|
+
`README.md` is the index and the single source of truth for requirements and decisions; task files link to it and do not restate them. Copy the requirements with their IDs from the plan, because the plan file can be deleted. Put the entity schemas that the user approved in `dot-plan` in the decisions:
|
|
76
78
|
|
|
77
79
|
```markdown
|
|
78
80
|
# <Roadmap title>
|
|
79
81
|
|
|
80
82
|
**Destination:** <what is true when the roadmap is done>
|
|
83
|
+
**Plan:** <path of the plan file, or none>
|
|
84
|
+
|
|
85
|
+
## Requirements
|
|
86
|
+
|
|
87
|
+
- **User needs:** UN1: <need>, or none
|
|
88
|
+
- **Functional requirements:** FR1: <requirement>, or none
|
|
89
|
+
- **Business rules:** BR1: <rule>, or none
|
|
90
|
+
- **Non-negotiables:** NN1: <limit>, or none
|
|
81
91
|
|
|
82
92
|
## Decisions
|
|
83
93
|
|
|
84
94
|
- <decision from the plan, one line each, with the reason when it is not obvious>
|
|
85
|
-
- <approved entity schema, as a
|
|
95
|
+
- <approved entity schema, as a code block, when the plan has one>
|
|
86
96
|
|
|
87
97
|
## Out of scope
|
|
88
98
|
|
|
@@ -109,7 +119,7 @@ Each task file:
|
|
|
109
119
|
|
|
110
120
|
## Requirements
|
|
111
121
|
|
|
112
|
-
- <what the change must do, specific enough to build without the conversation>
|
|
122
|
+
- <FR or BR ID>: <what the change must do, specific enough to build without the conversation>
|
|
113
123
|
- <files or modules it touches, when known>
|
|
114
124
|
|
|
115
125
|
## Out of scope
|
|
@@ -7,9 +7,7 @@ description: Write and change tests with a makeSut factory per suite. Use when y
|
|
|
7
7
|
|
|
8
8
|
Write tests that build the **system under test** (`sut`) in one factory, share it across the suite, and stay isolated: reset the test doubles between tests.
|
|
9
9
|
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. When the repository already sets up tests another way, such as pytest fixtures or its own setup helper, use that and leave out `makeSut`.
|
|
10
|
+
When the repository already sets up tests another way, such as pytest fixtures or its own setup helper, use that and leave out `makeSut`.
|
|
13
11
|
|
|
14
12
|
## The makeSut factory
|
|
15
13
|
|
|
@@ -26,7 +24,6 @@ Use `makeSut` when the subject needs setup: construction, configuration, depende
|
|
|
26
24
|
2. In a test, change a dependency's behavior with a spy or a stub on the double that `makeSut` returned, for that test only.
|
|
27
25
|
3. Restore every spy and stub in the hook that runs after each test, so the next test sees the happy-path doubles again.
|
|
28
26
|
|
|
29
|
-
|
|
30
27
|
## Test principles
|
|
31
28
|
|
|
32
29
|
- Arrange, act, assert: one block each, in that order.
|
|
@@ -43,6 +40,6 @@ Read each reference that applies to the tests:
|
|
|
43
40
|
- [`references/typescript.md`](references/typescript.md): read when the tests use TypeScript with Vitest, Jest, or `node:test`.
|
|
44
41
|
- [`references/http.md`](references/http.md): read when you write controller, integration, or end-to-end tests.
|
|
45
42
|
- [`references/shared-state.md`](references/shared-state.md): read when the `sut` keeps mutable state between calls, or when the tests run concurrently.
|
|
46
|
-
- [`references/
|
|
43
|
+
- [`references/after-implement.md`](references/after-implement.md): read when you write the tests of a change that `dot-implement` made, such as a roadmap task.
|
|
47
44
|
|
|
48
45
|
Done when every test you wrote or changed passes with the repository's test command, and you have shown the output.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Tests after dot-implement
|
|
2
|
+
|
|
3
|
+
Details for the [`dot-testing`](../SKILL.md) skill when it runs after `dot-implement`, with or without a roadmap task. `dot-implement` writes no tests. Use red-green TDD, where a test fails before the code exists, only when the user asks for it.
|
|
4
|
+
|
|
5
|
+
Read the handoff of `dot-implement`, with its "Expected failures" and "Behaviors that need tests" fields, and the diff of the change. When the change is a roadmap task, read its "Test cases" section.
|
|
6
|
+
|
|
7
|
+
1. Write each test case of the task that is not a test yet, in the test file that the case names. Use the order and the names that the cases give.
|
|
8
|
+
2. Change each test in "Expected failures" so that it asserts the new behavior.
|
|
9
|
+
3. Add a test for each item in "Behaviors that need tests", in the test file of its module.
|
|
10
|
+
4. Take each assertion from the task or the request, not from the code. When a test fails because the production code is wrong, stop and report the failure. Keep the production code as it is.
|
|
11
|
+
|
|
12
|
+
Done when each test case of the task is a test, and the test command of the repository passes, with its output shown.
|
|
13
|
+
|
|
14
|
+
## Reply
|
|
15
|
+
|
|
16
|
+
End with this reply:
|
|
17
|
+
|
|
18
|
+
```markdown
|
|
19
|
+
**Summary:** <what you did, in 3 sentences or fewer>
|
|
20
|
+
**Tests:** <the test command and its result line>
|
|
21
|
+
**Files:** <the test files that you changed>
|
|
22
|
+
**Blockers:** <what stops the review, or "none">
|
|
23
|
+
```
|
|
@@ -11,9 +11,7 @@ Read each reference that applies:
|
|
|
11
11
|
- [`references/steps.md`](references/steps.md): read when the document has steps, for the completion criterion of each step.
|
|
12
12
|
- [`references/skill-mechanics.md`](references/skill-mechanics.md): read when the document is a skill, for the frontmatter, the invocation choice, and router skills.
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. When you edit the `AGENTS.md`, `CLAUDE.md`, or skills of a repository, keep their structure, format, and conventions.
|
|
14
|
+
When you edit the `AGENTS.md`, `CLAUDE.md`, or skills of a repository, keep their structure, format, and conventions.
|
|
17
15
|
|
|
18
16
|
## Information hierarchy
|
|
19
17
|
|
|
@@ -4,5 +4,5 @@
|
|
|
4
4
|
"commit": "49dd158d1076134a641b33efb035946536778336",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"modified": true,
|
|
7
|
-
"notes": "Added a
|
|
7
|
+
"notes": "Added a sentence about the conventions of the repository. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md. Moved SKILL-MECHANICS.md to references/skill-mechanics.md, and moved the context pointers, the two loads, and the splits to references/pointers.md, and the completion criteria to references/steps.md."
|
|
8
8
|
}
|
|
@@ -1,11 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: dot-grill-me
|
|
3
|
-
description: A relentless interview to sharpen a plan or design.
|
|
4
|
-
disable-model-invocation: true
|
|
5
|
-
---
|
|
6
|
-
|
|
7
|
-
Use the `dot-grilling` skill to interview the user about the plan or design that they describe.
|
|
8
|
-
|
|
9
|
-
## Repository conventions first
|
|
10
|
-
|
|
11
|
-
Before you start, read what the repository defines: agent instructions (`AGENTS.md`, `CLAUDE.md`, `.github/copilot-instructions.md`, `.github/instructions/`, `.cursor/rules/`), project skills, `CONTRIBUTING.md`, style guides, linter and formatter configuration, and the patterns in the nearby code. They take precedence over this skill: where they differ, follow the repository, and point out the difference. Do not change the repository's standard. Base the recommendations of the interview on those conventions.
|