@igorlau/dotagents 1.0.15 → 1.0.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (49) hide show
  1. package/README.md +39 -45
  2. package/THIRD_PARTY_NOTICES.md +1 -1
  3. package/dist/apply.js +6 -6
  4. package/dist/build-info.json +1 -1
  5. package/dist/cli.js +24 -4
  6. package/dist/commands.js +70 -16
  7. package/dist/git.js +1 -1
  8. package/dist/targets.js +24 -5
  9. package/dist/wizard.js +248 -0
  10. package/package.json +5 -1
  11. package/plugin/.claude-plugin/plugin.json +1 -1
  12. package/plugin/agents/dot-implementer.md +4 -17
  13. package/plugin/agents/dot-reviewer.md +4 -3
  14. package/plugin/agents/dot-tester.md +5 -13
  15. package/plugin/hooks/check.mjs +37 -11
  16. package/plugin/hooks/hooks.json +30 -0
  17. package/plugin/hooks/rules.mjs +27 -0
  18. package/plugin/rules/code-style.md +1 -1
  19. package/plugin/rules/core.md +2 -2
  20. package/plugin/rules/ponytail.md +1 -1
  21. package/plugin/rules/ponytail.upstream.json +1 -1
  22. package/plugin/rules/writing.md +3 -4
  23. package/plugin/rules/writing.upstream.json +1 -1
  24. package/plugin/scaffold/AGENTS.md.tmpl +2 -2
  25. package/plugin/skills/dot-code-review/SKILL.md +1 -3
  26. package/plugin/skills/dot-commit/SKILL.md +1 -5
  27. package/plugin/skills/dot-correct/SKILL.md +1 -3
  28. package/plugin/skills/dot-debug/SKILL.md +4 -6
  29. package/plugin/skills/dot-debug/UPSTREAM.json +1 -1
  30. package/plugin/skills/dot-docs-writing/SKILL.md +1 -3
  31. package/plugin/skills/dot-flow/SKILL.md +29 -29
  32. package/plugin/skills/dot-flow/references/inline.md +5 -38
  33. package/plugin/skills/dot-grilling/SKILL.md +1 -3
  34. package/plugin/skills/dot-grilling/UPSTREAM.json +1 -1
  35. package/plugin/skills/dot-handoff/SKILL.md +1 -3
  36. package/plugin/skills/dot-handoff/UPSTREAM.json +1 -1
  37. package/plugin/skills/dot-implement/SKILL.md +12 -9
  38. package/plugin/skills/dot-plan/SKILL.md +33 -12
  39. package/plugin/skills/dot-plan/references/entity-schemas.md +3 -3
  40. package/plugin/skills/dot-roadmap/SKILL.md +21 -11
  41. package/plugin/skills/dot-roadmap/agents/openai.yaml +5 -0
  42. package/plugin/skills/dot-testing/SKILL.md +2 -5
  43. package/plugin/skills/dot-testing/references/after-implement.md +23 -0
  44. package/plugin/skills/dot-writing-for-agents/SKILL.md +1 -3
  45. package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +1 -1
  46. package/plugin/skills/dot-grill-me/SKILL.md +0 -11
  47. package/plugin/skills/dot-grill-me/UPSTREAM.json +0 -8
  48. package/plugin/skills/dot-grill-me/agents/openai.yaml +0 -5
  49. package/plugin/skills/dot-testing/references/modes.md +0 -32
@@ -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
- ## 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. 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 reports that something is broken, throws, fails, or is slow.
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
- ## 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. 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. Flag it for the next phase.
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 'Repository conventions first' section. 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."
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
- ## 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. 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 test stubs, implementation, test fill, and review, with your approval after each step.
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 four steps: test stubs, implementation, test fill, and review. Each step runs in a fresh agent with one skill, and the user approves its result before the next step starts. You coordinate the steps. The agents write the tests, the code, and the review.
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-tester`, `dotagents:dot-implementer`, 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 approvals.
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. Stub | `dotagents:dot-tester` | Task, Mode `stub` |
34
- | 2. Implement | `dotagents:dot-implementer` | Task, Handoff: the reply of step 1 |
35
- | 3. Fill | `dotagents:dot-tester` | Task, Mode `fill`, Handoff: the reply of step 2 |
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. Keep the main context small: do not read the changed files or the full test output yourself. The replies carry what the user needs.
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
- ## 4. Approve each step
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
- After each step, show the user this summary, then wait:
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
- ```markdown
54
- **Step <n> of 4: <step name>**
55
- <the Summary line of the reply>
56
- <the Checks or Tests line of the reply>
57
- **Blockers:** <the Blockers line of the reply>
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
- For the review step, show the **Highest severity** line and one line for each finding: its severity, summary, and `file:line`.
60
+ Done when the review reply arrived, or the flow stopped.
61
61
 
62
- Start the next step only when the user says "go" or approves in other words. When the user asks for a change, run the same step again in a new agent, and add the request to the prompt.
62
+ ## 4. Decide after the review
63
63
 
64
- Stop the flow, and keep the files as they are, in these cases:
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
- - A reply has blockers. Show them, and ask the user how to continue.
67
- - The review reports a `high` finding. The presumed blockers of the maintainability pass are `high`. Show each `high` finding with its **Fix** line. When the user fixes the findings and asks for a new review, run step 4 again.
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 approved the review step, or the flow stopped.
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. The user decides about the `medium` and `low` findings. Suggest the `dot-commit` skill.
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 steps, the approvals, and the stop cases of `SKILL.md` stay the same. You run each step yourself, in this conversation, instead of in an agent.
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
- ## Steps
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
- 1. Stub: use the `dot-testing` skill in stub mode for the task.
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
- ## Repository conventions first
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 'Repository conventions first' section. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md, and replaced the emoji in the round format with text labels."
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
- ## Repository conventions first
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 'Repository conventions first' section. Renamed with the dot- prefix. Rewrote the text under plugin/rules/writing.md."
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 touches more than one file, use the `dot-plan` skill and wait for the user's approval before you change any file. A single-file change goes straight to step 3.
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 the verification output, anything that you skipped or could not check, and these fields for the fill mode of the `dot-testing` skill:
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. Suggest `dot-testing` in fill mode, then the `dot-code-review` skill, then the `dot-commit` skill. Leave the commit to the user.
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 feature, refactor, or migration that touches more than one file.
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. Surface decisions
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
- ## 4. Show entity schemas
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 a full JSON Schema for each new entity, and a before and after diff for each changed entity. Wait for the user to approve the schemas before you slice the work.
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
- ## 5. Slice the work
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
- ## 6. Present and wait
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> → check: <command or observation>
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
- Wait for the user's approval before you change any file. When the plan changes during the work, update it and say what changed.
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, in a `json` block. Give it `$schema`, `$id`, `title`, `type`, `required`, and `properties`.
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
- Work from the plan in this conversation, usually the shared understanding a `dot-grill-me` session reached. If the user passed a path or URL, read it in full.
14
+ Take the plan from the first of these sources that exists:
19
15
 
20
- Synthesize the plan. Do not interview the user. If the plan still has unsettled decisions, list them and suggest `dot-grill-me` before you go on. Done when you can state the **destination** (what is true when the whole roadmap is done) and every decision the plan made.
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 the HTTP reference of `dot-testing`. `dot-testing` writes them as pending tests before the code. Write "none" when the task changes no tested behavior.
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
- Done when every requirement and decision from the plan belongs to exactly one task or to the roadmap's out-of-scope list, and every task has acceptance criteria that can fail.
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 JSON Schema block, when the plan has one>
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
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: "Roadmap"
3
+ short_description: "Split a plan into phases and self-contained tasks"
4
+ policy:
5
+ allow_implicit_invocation: false
@@ -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
- ## 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. 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/modes.md`](references/modes.md): read when you work a roadmap task, before `dot-implement` (stub mode) or after it (fill mode).
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
- ## Repository conventions first
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 'Repository conventions first' section. 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."
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.