@igorlau/dotagents 1.0.14 → 1.0.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. package/README.md +129 -35
  2. package/THIRD_PARTY_NOTICES.md +76 -2
  3. package/dist/build-info.json +1 -1
  4. package/dist/catalog.js +3 -3
  5. package/dist/cli.js +8 -2
  6. package/dist/commands.js +60 -5
  7. package/dist/paths.js +1 -1
  8. package/dist/targets.js +3 -0
  9. package/package.json +2 -2
  10. package/plugin/.claude-plugin/plugin.json +10 -0
  11. package/plugin/agents/dot-implementer.md +38 -0
  12. package/plugin/agents/dot-reviewer.md +31 -0
  13. package/plugin/agents/dot-tester.md +33 -0
  14. package/plugin/hooks/check.mjs +92 -0
  15. package/plugin/hooks/hooks.json +24 -0
  16. package/plugin/rules/code-style.md +6 -0
  17. package/plugin/rules/comments.md +17 -0
  18. package/plugin/rules/comments.upstream.json +8 -0
  19. package/{content → plugin}/rules/ponytail.md +1 -1
  20. package/{content → plugin}/rules/ponytail.upstream.json +1 -1
  21. package/plugin/rules/writing.md +35 -0
  22. package/plugin/rules/writing.upstream.json +8 -0
  23. package/{content → plugin}/scaffold/AGENTS.md.tmpl +1 -0
  24. package/plugin/skills/dot-code-review/SKILL.md +71 -0
  25. package/plugin/skills/dot-code-review/UPSTREAM.json +8 -0
  26. package/plugin/skills/dot-code-review/references/maintainability.md +67 -0
  27. package/plugin/skills/dot-comments/SKILL.md +41 -0
  28. package/plugin/skills/dot-comments/UPSTREAM.json +8 -0
  29. package/{content → plugin}/skills/dot-commit/SKILL.md +7 -5
  30. package/plugin/skills/dot-correct/SKILL.md +43 -0
  31. package/plugin/skills/dot-correct/UPSTREAM.json +8 -0
  32. package/plugin/skills/dot-correct/agents/openai.yaml +5 -0
  33. package/plugin/skills/dot-debug/SKILL.md +125 -0
  34. package/plugin/skills/dot-debug/UPSTREAM.json +8 -0
  35. package/plugin/skills/dot-debug/references/loops.md +32 -0
  36. package/{content → plugin}/skills/dot-docs-writing/SKILL.md +15 -23
  37. package/{content → plugin}/skills/dot-docs-writing/references/formatting.md +26 -26
  38. package/{content → plugin}/skills/dot-docs-writing/references/global-and-accessible.md +9 -10
  39. package/{content → plugin}/skills/dot-docs-writing/references/word-list.md +4 -5
  40. package/plugin/skills/dot-flow/SKILL.md +75 -0
  41. package/plugin/skills/dot-flow/agents/openai.yaml +5 -0
  42. package/plugin/skills/dot-flow/references/inline.md +42 -0
  43. package/{content → plugin}/skills/dot-grill-me/SKILL.md +2 -2
  44. package/{content → plugin}/skills/dot-grill-me/UPSTREAM.json +1 -1
  45. package/plugin/skills/dot-grilling/SKILL.md +34 -0
  46. package/{content → plugin}/skills/dot-grilling/UPSTREAM.json +1 -1
  47. package/plugin/skills/dot-grilling/agents/openai.yaml +3 -0
  48. package/plugin/skills/dot-handoff/SKILL.md +20 -0
  49. package/{content → plugin}/skills/dot-handoff/UPSTREAM.json +1 -1
  50. package/plugin/skills/dot-implement/SKILL.md +65 -0
  51. package/plugin/skills/dot-implement/UPSTREAM.json +8 -0
  52. package/{content → plugin}/skills/dot-implement/references/typescript.md +29 -20
  53. package/{content → plugin}/skills/dot-plan/SKILL.md +15 -8
  54. package/plugin/skills/dot-plan/UPSTREAM.json +8 -0
  55. package/plugin/skills/dot-plan/references/entity-schemas.md +66 -0
  56. package/{content → plugin}/skills/dot-roadmap/SKILL.md +19 -12
  57. package/plugin/skills/dot-roadmap/UPSTREAM.json +8 -0
  58. package/plugin/skills/dot-roadmap/references/wide-refactor.md +3 -0
  59. package/plugin/skills/dot-testing/SKILL.md +48 -0
  60. package/plugin/skills/dot-testing/UPSTREAM.json +8 -0
  61. package/plugin/skills/dot-testing/references/http.md +15 -0
  62. package/plugin/skills/dot-testing/references/modes.md +32 -0
  63. package/plugin/skills/dot-testing/references/shared-state.md +3 -0
  64. package/{content → plugin}/skills/dot-testing/references/typescript.md +2 -2
  65. package/plugin/skills/dot-writing-for-agents/SKILL.md +54 -0
  66. package/plugin/skills/dot-writing-for-agents/UPSTREAM.json +8 -0
  67. package/plugin/skills/dot-writing-for-agents/references/pointers.md +27 -0
  68. package/plugin/skills/dot-writing-for-agents/references/skill-mechanics.md +22 -0
  69. package/plugin/skills/dot-writing-for-agents/references/steps.md +8 -0
  70. package/content/rules/comments.md +0 -15
  71. package/content/skills/dot-code-review/SKILL.md +0 -58
  72. package/content/skills/dot-debug/SKILL.md +0 -142
  73. package/content/skills/dot-debug/UPSTREAM.json +0 -8
  74. package/content/skills/dot-grilling/SKILL.md +0 -34
  75. package/content/skills/dot-grilling/agents/openai.yaml +0 -3
  76. package/content/skills/dot-handoff/SKILL.md +0 -20
  77. package/content/skills/dot-implement/SKILL.md +0 -52
  78. package/content/skills/dot-testing/SKILL.md +0 -44
  79. package/content/skills/dot-writing-for-agents/SKILL-MECHANICS.md +0 -22
  80. package/content/skills/dot-writing-for-agents/SKILL.md +0 -85
  81. package/content/skills/dot-writing-for-agents/UPSTREAM.json +0 -8
  82. /package/{content → plugin}/rules/core.md +0 -0
  83. /package/{content → plugin}/scaffold/.claude/settings.json.tmpl +0 -0
  84. /package/{content → plugin}/scaffold/.editorconfig.tmpl +0 -0
  85. /package/{content → plugin}/scaffold/.gitattributes.tmpl +0 -0
  86. /package/{content → plugin}/scaffold/CLAUDE.md.tmpl +0 -0
  87. /package/{content → plugin}/skills/dot-debug/agents/openai.yaml +0 -0
  88. /package/{content → plugin}/skills/dot-debug/scripts/hitl-loop.template.sh +0 -0
  89. /package/{content → plugin}/skills/dot-grill-me/agents/openai.yaml +0 -0
  90. /package/{content → plugin}/skills/dot-handoff/agents/openai.yaml +0 -0
  91. /package/{content → plugin}/skills/dot-writing-for-agents/agents/openai.yaml +0 -0
@@ -0,0 +1,125 @@
1
+ ---
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.
4
+ ---
5
+
6
+ # Diagnose bugs
7
+
8
+ Use this method for hard bugs. Skip a phase only when you can state the reason.
9
+
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
+
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.
15
+
16
+ ## Redact
17
+
18
+ This skill shows commands, outputs, and captured artifacts. Redact every secret first: write `<REDACTED>` in its place. Build loops against environment variables, so the credential stays in the environment and out of what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.
19
+
20
+ If the redacted output is not enough to diagnose the bug, say so and ask the user.
21
+
22
+ ## Phase 1: Build a feedback loop
23
+
24
+ This phase is the skill. The other phases are mechanical. With a **tight** pass or fail signal for the bug, one that goes **red** on _this_ bug, you will find the cause. Bisection, hypothesis tests, and instrumentation all use that signal. Without one, the code alone will not show you the bug.
25
+
26
+ Spend most of your effort here. Be aggressive and creative, and do not give up.
27
+
28
+ Start with a test that fails at the seam that reaches the bug. When no test can reach the bug, when the bug is not deterministic, or when you cannot build a loop, read [`references/loops.md`](references/loops.md).
29
+
30
+ ### Tighten the loop
31
+
32
+ Treat the loop as a product. When you have _a_ loop, make it **tight**:
33
+
34
+ - Make it faster: cache the setup, skip unrelated startup work, and narrow the test scope.
35
+ - Make the signal sharper: assert on the specific symptom, not on "did not crash".
36
+ - Make it more deterministic: pin the time, seed the random number generator, isolate the filesystem, and freeze the network.
37
+
38
+ A flaky loop of 30 seconds is little better than no loop. A deterministic loop of 2 seconds is tight, and it makes the bug easy to find.
39
+
40
+ ### Completion criterion: a tight loop that goes red
41
+
42
+ Phase 1 is done when the loop is **tight** and can go **red**. Name **one command**, such as a script path, a test command, or a curl call. You must have run it at least one time: show the command and its redacted output. The command must be:
43
+
44
+ - [ ] Red-capable: it drives the real bug code path and asserts the user's exact symptom, so it goes red on this bug and green after the fix. A command that only runs without an error is not enough: it must catch this specific bug.
45
+ - [ ] Deterministic: it gives the same verdict on every run. For a flaky bug, it has a pinned, high reproduction rate.
46
+ - [ ] Fast: it takes seconds, not minutes.
47
+ - [ ] Agent-runnable: you can run it without a person. A person can take part only through `scripts/hitl-loop.template.sh`.
48
+
49
+ Do not read code to build a theory before this command exists. A jump to a hypothesis is the exact failure that this skill prevents. Without a red-capable command, do not start Phase 2.
50
+
51
+ ## Phase 2: Reproduce and minimize
52
+
53
+ Run the loop. Watch it go red when the bug appears.
54
+
55
+ Confirm:
56
+
57
+ - [ ] The loop produces the failure that the user described, not a different failure nearby. The wrong bug leads to the wrong fix.
58
+ - [ ] The failure occurs on every run, or for a flaky bug, at a rate high enough to debug against.
59
+ - [ ] You captured the exact symptom (the error message, the wrong output, the slow time), so later phases can verify that the fix addresses it.
60
+
61
+ ### Minimize
62
+
63
+ When the loop is red, shrink the repro to the **smallest scenario that still goes red**. Cut inputs, callers, configuration, data, and steps **one at a time**, and run the loop again after each cut. Keep only what the failure needs.
64
+
65
+ A minimal repro shrinks the set of hypotheses in Phase 3, because fewer parts remain to suspect. It also becomes the clean regression test in Phase 5.
66
+
67
+ Done when **every element that remains is necessary**: when you remove any one of them, the loop goes green.
68
+
69
+ Do not continue until you have reproduced **and** minimized the bug.
70
+
71
+ ## Phase 3: Hypothesize
72
+
73
+ Write **3 to 5 ranked hypotheses** before you test any of them. A single hypothesis anchors on the first plausible idea.
74
+
75
+ Each hypothesis must be **falsifiable**: state the prediction that it makes.
76
+
77
+ > Format: "If <X> is the cause, then a change to <Y> makes the bug disappear, and a change to <Z> makes it worse."
78
+
79
+ If you cannot state the prediction, the hypothesis is a guess: drop it or make it sharper.
80
+
81
+ **Show the ranked list to the user before you test it.** The user often has domain knowledge that changes the rank ("we deployed a change to #3"), or knows hypotheses that are already ruled out. If the user does not answer, continue with your rank.
82
+
83
+ ## Phase 4: Instrument
84
+
85
+ Map each probe to a specific prediction from Phase 3. **Change one variable at a time.**
86
+
87
+ Use these tools, in this order of preference:
88
+
89
+ 1. A debugger or REPL, if the environment supports it. One breakpoint is better than ten logs.
90
+ 2. Targeted logs at the boundaries that tell the hypotheses apart.
91
+ 3. Never log everything and grep the output.
92
+
93
+ **Tag every debug log** with a unique prefix, such as `[DEBUG-a4f2]`. At the end, one grep finds them all for cleanup.
94
+
95
+ For a performance regression, logs are usually the wrong tool. First, measure a baseline with a harness that measures time, `performance.now()`, a profiler, or a query plan. Then bisect. Measure first, and fix second.
96
+
97
+ ## Phase 5: Fix and regression test
98
+
99
+ Fix the root cause, not the symptom. Ask "why" until the answer is the first wrong decision in the code, not a result of an earlier one. Fix every place that has the same pattern. Add a guard only for a state that is legitimate: a guard for a state that must never exist hides the bug.
100
+
101
+ When two fixes fail the same check, write down the premise that both fixes assumed. Test the premise before you write a third fix.
102
+
103
+ Write the regression test **before the fix**, but only if a **correct seam** exists for it.
104
+
105
+ 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
+
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.
108
+
109
+ If a correct seam exists:
110
+
111
+ 1. Turn the minimized repro into a test that fails at that seam.
112
+ 2. Watch it fail. If you forced the red with a change to code or a fixture, `diff` against a clean copy to prove that the change landed before you trust it.
113
+ 3. Apply the fix.
114
+ 4. Watch the test pass.
115
+ 5. Run the Phase 1 feedback loop again against the original scenario, before minimization.
116
+
117
+ ## Phase 6: Clean up
118
+
119
+ Do these before you declare the work done:
120
+
121
+ - [ ] The original repro no longer reproduces: run the Phase 1 loop again.
122
+ - [ ] The regression test passes, or you documented that no correct seam exists.
123
+ - [ ] All `[DEBUG-...]` instrumentation is removed: grep the prefix.
124
+ - [ ] Throwaway prototypes are deleted, or moved to a clearly marked debug location.
125
+ - [ ] The commit or pull request message states the hypothesis that was correct, so the next person who debugs the code learns from it.
@@ -0,0 +1,8 @@
1
+ {
2
+ "repository": "https://github.com/mattpocock/skills",
3
+ "path": "skills/engineering/diagnosing-bugs",
4
+ "commit": "49dd158d1076134a641b33efb035946536778336",
5
+ "license": "MIT",
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."
8
+ }
@@ -0,0 +1,32 @@
1
+ # Feedback loops
2
+
3
+ ## Ways to build a loop
4
+
5
+ Try these in about this order:
6
+
7
+ 1. A test that fails at the seam that reaches the bug: unit, integration, or end-to-end.
8
+ 2. A curl or HTTP script against a dev server that runs locally.
9
+ 3. A CLI call with a fixture input, with a diff of stdout against a known good snapshot.
10
+ 4. A headless browser script (Playwright or Puppeteer) that drives the UI and asserts on the DOM, the console, or the network.
11
+ 5. A replay of a captured trace. Save a real network request, payload, or event log to disk, and replay it through the code path alone.
12
+ 6. A throwaway harness. Start a minimal subset of the system, such as one service with stubbed dependencies, that runs the bug code path with one function call.
13
+ 7. A property or fuzz loop. If the bug is "sometimes wrong output", run 1,000 random inputs and look for the failure.
14
+ 8. A bisection harness. If the bug appeared between two known states (a commit, a dataset, a version), automate "start at state X, check, repeat", so you can use `git bisect run`.
15
+ 9. A differential loop. Run the same input through the old and the new version, or through two configurations, and diff the outputs.
16
+ 10. A human-in-the-loop bash script, as the last resort. If a person must click, drive the person with [`scripts/hitl-loop.template.sh`](../scripts/hitl-loop.template.sh), so the loop keeps its structure. The captured output comes back to you.
17
+
18
+ With the right feedback loop, the bug is 90% fixed.
19
+
20
+ ## Bugs that are not deterministic
21
+
22
+ The goal is not a clean repro. The goal is a **higher reproduction rate**. Run the trigger 100 times, run copies in parallel, add stress, narrow the time windows, and add sleeps. A bug that fails 50% of the time is easy to debug, and a bug that fails 1% of the time is not. Raise the rate until you can debug the bug.
23
+
24
+ ## When you cannot build a loop
25
+
26
+ Stop and say so. List what you tried. Ask the user for one of these:
27
+
28
+ - Access to the environment that reproduces the bug.
29
+ - A redacted captured artifact: a HAR file, a log dump, a core dump, or a video of the screen with timestamps.
30
+ - Permission to add temporary instrumentation in production.
31
+
32
+ Do **not** start to form hypotheses without a loop.
@@ -1,47 +1,40 @@
1
1
  ---
2
2
  name: dot-docs-writing
3
- description: Write and edit developer documentation in the Google developer documentation style. Use when creating or revising a README, guide, tutorial, reference page, changelog, or code comments meant for readers.
3
+ description: Write and edit developer documentation in the Google developer documentation style. Use when you create or revise a README, guide, tutorial, reference page, changelog, or code comments meant for readers.
4
4
  ---
5
5
 
6
6
  # Docs writing
7
7
 
8
- Write documentation that a developer in a hurry, reading in their second language, can follow on the first pass. The rules come from the Google developer documentation style guide.
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
10
  ## Repository conventions first
11
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 surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing 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 existing docs.
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.
13
13
 
14
14
  ## 1. Frame the document
15
15
 
16
- Before drafting, answer these questions:
16
+ Before you draft, answer these questions:
17
17
 
18
18
  - **Reader**: who is "you" in this document (an app developer, an operator, a contributor), and what do they already know?
19
- - **Goal**: what can the reader do after reading?
19
+ - **Goal**: what can the reader do after they read the document?
20
20
  - **Type**: a task (how to do something), a concept (how something works), or reference (facts to look up). Use a task title with a bare verb, such as "Deploy the service", and a concept title with a noun phrase, such as "Deployment model".
21
21
 
22
- ## 2. Draft with the core rules
22
+ ## 2. Draft
23
23
 
24
- **Voice and tone**
25
-
26
- - Write like a knowledgeable colleague: conversational and direct, without slang, jokes, or hype.
27
- - Address the reader as "you". Use the imperative for instructions. Use "we" only for a named organization.
28
- - Use active voice and name the actor: "The server sends a response", not "A response is sent".
29
- - Use present tense. Use "will" only for events that happen later.
30
- - Use common contractions, such as "don't" and "isn't".
31
- - Write "click **Save**", not "please click" or "simply click". Words such as "simply", "easy", "just", and "quickly" judge difficulty for the reader, so leave them out.
24
+ Write the prose by the writing rule. Then apply these rules for documents:
32
25
 
33
26
  **Sentences**
34
27
 
35
- - Keep sentences under 26 words, with the subject and verb near the start.
28
+ - Address the reader as "you". Use "we" only for a named organization.
36
29
  - Put the condition before the instruction: "If the build fails, run `make clean`."
37
30
  - Put the goal before the action: "To create a folder, click **New**."
38
- - Use the same term for the same concept throughout. Spell out an abbreviation at its first use.
39
- - Replace ambiguous pronouns ("it", "this") with the noun.
40
- - Use "can" for ability, "might" for possibility, and "must" for requirements. Avoid "should" and "may".
31
+ - Spell out an abbreviation at its first use.
32
+ - Replace an unclear pronoun, such as "it" or "this", with the noun.
33
+ - Write "click **Save**", not "please click" or "simply click". Words such as "simply", "easy", and "quickly" judge difficulty for the reader.
41
34
 
42
35
  **Structure**
43
36
 
44
- - Use sentence case for titles and headings. Don't skip heading levels, and use one level-1 heading per page.
37
+ - Keep heading levels in order, and use one level-1 heading per page.
45
38
  - Introduce every list, table, code sample, and procedure with a complete sentence that ends in a colon.
46
39
  - Use numbered lists for sequences and bulleted lists for everything else. Keep list items parallel.
47
40
  - Write each procedure step as one imperative action. State where the action happens before the action.
@@ -50,7 +43,7 @@ Before drafting, answer these questions:
50
43
  **Formatting**
51
44
 
52
45
  - Put code-related text in code font: commands, filenames, paths, variables, values, and field input.
53
- - Put UI element names in bold, matching the label's capitalization: click **Create project**.
46
+ - Put UI element names in bold, with the label's capitalization: click **Create project**.
54
47
  - Write placeholders in uppercase with underscores, such as `PROJECT_ID`, and explain each one after the sample.
55
48
  - Use descriptive link text, such as the page title. Never use "click here" or a bare URL.
56
49
  - Write dates as "January 19, 2026", or as ISO 8601 (`2026-01-19`) when space is tight.
@@ -61,8 +54,7 @@ Before drafting, answer these questions:
61
54
  Read the draft once per checklist item, and fix every instance:
62
55
 
63
56
  - [ ] Each heading matches its section type (task, concept, or reference).
64
- - [ ] No passive voice hides who acts.
65
- - [ ] No sentence exceeds 26 words.
57
+ - [ ] Every sentence follows the writing rule: its word limit, the active voice, and no contractions.
66
58
  - [ ] Every list, table, and code block has an introductory sentence.
67
59
  - [ ] Every placeholder is explained.
68
60
  - [ ] Every command and code sample runs as written, apart from its placeholders.
@@ -71,7 +63,7 @@ Read the draft once per checklist item, and fix every instance:
71
63
 
72
64
  ## References
73
65
 
74
- Load the reference that matches what you're writing:
66
+ Load the reference that matches the document:
75
67
 
76
68
  - [`references/formatting.md`](references/formatting.md): headings, lists, tables, procedures, code samples, commands, placeholders, notices, links, UI elements, and dates in detail.
77
69
  - [`references/word-list.md`](references/word-list.md): words and phrases to avoid, with replacements. Read it during the revision pass.
@@ -1,26 +1,26 @@
1
1
  # Formatting reference
2
2
 
3
- Detailed formatting rules for the [`dot-docs-writing`](../SKILL.md) skill.
3
+ Detailed format rules for the [`dot-docs-writing`](../SKILL.md) skill.
4
4
 
5
5
  ## Headings and titles
6
6
 
7
7
  - Use sentence case: "Transfer data sets", not "Transfer Data Sets".
8
8
  - Start task headings with a bare verb: "Create an instance", not "Creating an instance".
9
- - Write concept headings as noun phrases that don't start with an -ing verb: "Migration to the cloud".
9
+ - Write concept headings as noun phrases that do not start with an -ing verb: "Migration to the cloud".
10
10
  - Gerunds are acceptable only when no better option exists, such as "Billing".
11
11
  - Prefix optional sections with "Optional:", as in "Optional: Customize your alias".
12
- - Use exactly one level-1 heading per page, and make it unique in the doc set. Don't repeat the page title as a section heading.
13
- - Don't skip levels: a level-3 heading belongs under a level-2 heading.
12
+ - Use exactly one level-1 heading per page, and make it unique in the doc set. Do not repeat the page title as a section heading.
13
+ - Do not skip levels: a level-3 heading belongs under a level-2 heading.
14
14
  - Follow every heading with content.
15
- - Don't number headings to show sequence, and don't put links in headings.
15
+ - Do not number headings to show sequence, and do not put links in headings.
16
16
  - Avoid code in headings. If you must, add a descriptive noun, such as "The `init` command".
17
- - Keep heading punctuation minimal. Heavy punctuation means the heading needs rewriting.
17
+ - Keep heading punctuation minimal. Heavy punctuation means the heading needs a rewrite.
18
18
  - Introduce a group of subsections with "the following sections", not "this section" or "these sections".
19
19
 
20
20
  ## Lists
21
21
 
22
- - Use a numbered list when order matters, a bulleted list when it doesn't, and a description list for term-definition pairs.
23
- - Don't make a list of one item.
22
+ - Use a numbered list when order matters, a bulleted list when it does not, and a description list for term-definition pairs.
23
+ - Do not make a list of one item.
24
24
  - Introduce a list with a complete sentence. End the sentence with a colon if the list follows immediately, or with a period if other material comes between them.
25
25
  - Recommended: "Use the **Submit** button for any of the following purposes:"
26
26
  - Not recommended: "Use the **Submit** button to:"
@@ -28,15 +28,15 @@ Detailed formatting rules for the [`dot-docs-writing`](../SKILL.md) skill.
28
28
  - Start each item with a capital letter.
29
29
  - End items with a period unless the item is a single word, has no verb, is entirely code, or is entirely link text. When items are mixed, make them parallel or punctuate all of them.
30
30
  - In run-in lists, separate the bold term from its description with a colon or a period, and use the same punctuation for every item.
31
- - In prose lists, don't end with "etc." or "and so on". Introduce the list so that it's clearly not exhaustive, for example with "including".
31
+ - In prose lists, do not end with "etc." or "and so on". Introduce the list so that it is clearly not exhaustive, for example with "including".
32
32
  - Nest sequential sub-items with lowercase letters, and their sub-items with lowercase Roman numerals.
33
33
 
34
34
  ## Tables
35
35
 
36
36
  - Use a table when each item has three or more related pieces of data. A one-column table should be a list.
37
37
  - Introduce each table with a complete sentence that states its purpose.
38
- - Use sentence case for column headings, without ending punctuation.
39
- - Don't merge cells, and don't put a table in the middle of a numbered procedure.
38
+ - Use sentence case for column headings, without punctuation at the end.
39
+ - Do not merge cells, and do not put a table in the middle of a numbered procedure.
40
40
  - Sort rows logically, or alphabetically when no logical order exists.
41
41
  - Refer to a table by its position, such as "the following table", not "the table below".
42
42
 
@@ -52,7 +52,7 @@ Detailed formatting rules for the [`dot-docs-writing`](../SKILL.md) skill.
52
52
  - State the action, then its reason: "Store the token safely. You need it to sign in later."
53
53
  - Order a complex step as follows: action, command, placeholder explanations, further explanation, output, result.
54
54
  - List prerequisites (hardware, software, permissions, information) before the first step.
55
- - When two procedures share steps, link to the earlier one instead of repeating it.
55
+ - When two procedures share steps, link to the earlier one, and do not repeat it.
56
56
  - Document one method, the shortest one that works for every reader. Separate alternatives with headings or tabs only when necessary.
57
57
 
58
58
  ## Code in text
@@ -68,30 +68,30 @@ Use code font for the following items:
68
68
  - Text that the reader types and command output.
69
69
  - Placeholders.
70
70
 
71
- Don't use code font for product names, domain names in prose, or URLs that the reader visits in a browser.
71
+ Do not use code font for product names, domain names in prose, or URLs that the reader visits in a browser.
72
72
 
73
- Use code names grammatically as proper nouns. Don't pluralize them, make them possessive, or turn them into verbs. Add a plain noun instead:
73
+ Use code names grammatically as proper nouns. Do not pluralize them, make them possessive, or turn them into verbs. Add a plain noun instead:
74
74
 
75
75
  - Recommended: "The `ADDRESS` constant's value", "send a `POST` request".
76
76
  - Not recommended: "`ADDRESS`'s value", "`POST` the data".
77
77
 
78
- Don't wrap code in quotation marks unless the quotation marks are part of the code.
78
+ Do not wrap code in quotation marks unless the quotation marks are part of the code.
79
79
 
80
80
  ## Code samples
81
81
 
82
82
  - Introduce each sample with a sentence that ends in a colon.
83
83
  - Use fenced code blocks with a language tag.
84
84
  - Wrap lines at 80 characters.
85
- - Mark omitted code with a comment in the sample's language. Don't use an ellipsis.
85
+ - Mark omitted code with a comment in the sample's language. Do not use an ellipsis.
86
86
  - Follow the language's own style guide, or the project's.
87
87
 
88
88
  ## Commands
89
89
 
90
90
  - Make copyable commands runnable as written, apart from placeholders.
91
- - Link each command to its reference documentation where it's introduced.
91
+ - Link each command to its reference documentation where it is introduced.
92
92
  - Show as few optional flags as possible. Point to the reference for the rest.
93
93
  - Break long commands before a flag, end each continued line with ` \` (or ` ^` on Windows), and indent continuation lines four spaces.
94
- - In multi-line examples, start each input line with `$`. If a document mixes one-line and multi-line commands, use the prompt for all of them. Don't show the current directory.
94
+ - In multi-line examples, start each input line with `$`. If a document mixes one-line and multi-line commands, use the prompt for all of them. Do not show the current directory.
95
95
  - Put input and output in separate code blocks.
96
96
  - Show output only when the reader needs to verify or copy a value. Introduce it with "The output is similar to the following:". Mark omitted lines with `...` on a line of its own.
97
97
  - In syntax descriptions, wrap optional arguments in `[]`, mutually exclusive choices in `{a|b}`, and mark repeatable arguments with `...`. Keep these symbols out of copyable commands.
@@ -111,7 +111,7 @@ Don't wrap code in quotation marks unless the quotation marks are part of the co
111
111
  - **Note:** relevant but optional information that the reader can skip.
112
112
  - **Caution:** proceed carefully.
113
113
  - **Warning:** an action might cause irreversible harm, such as data loss, cost, or a security exposure.
114
- - Don't use a notice for prerequisites, required steps, results, or cross-references. Put that information in the main text.
114
+ - Do not use a notice for prerequisites, required steps, results, or cross-references. Put that information in the main text.
115
115
  - Start each notice with its bold label and a colon: "**Note:**".
116
116
 
117
117
  ## Links
@@ -119,17 +119,17 @@ Don't wrap code in quotation marks unless the quotation marks are part of the co
119
119
  - Use the destination's page title, or a short descriptive phrase with the key words first, as link text.
120
120
  - Never use "click here", "this page", "this document", or a bare URL as link text.
121
121
  - Introduce cross-references with "For more information, see LINK." or "For more information about TOPIC, see LINK."
122
- - Link only what's relevant, and don't repeat a link to the same destination on one page.
123
- - Say when a link downloads a file or leaves the doc set. Don't force new tabs.
124
- - Keep punctuation outside the link text, and don't put link text in quotation marks.
122
+ - Link only what is relevant, and do not repeat a link to the same destination on one page.
123
+ - Say when a link downloads a file or leaves the doc set. Do not force new tabs.
124
+ - Keep punctuation outside the link text, and do not put link text in quotation marks.
125
125
 
126
126
  ## UI elements
127
127
 
128
- - Put UI element names in bold, matching their capitalization on screen. Use sentence case if the label is all caps.
128
+ - Put UI element names in bold, with their capitalization on screen. Use sentence case if the label is all caps.
129
129
  - Name the element and its type: "the **Name** field", "the **File** menu", "the **Advanced** tab".
130
- - Use "click" for buttons and links, "select" and "clear" for checkboxes and options, "enter" for text, and "press" for keys. Don't write "click on", "hit", "check", or "uncheck".
130
+ - Use "click" for buttons and links, "select" and "clear" for checkboxes and options, "enter" for text, and "press" for keys. Do not write "click on", "hit", "check", or "uncheck".
131
131
  - Use "in" with dialogs, fields, lists, menus, panes, and windows, and "on" with pages, tabs, and toolbars.
132
- - Don't use a UI label as a verb: "To save the file, click **Save**", not "**Save** the file".
132
+ - Do not use a UI label as a verb: "To save the file, click **Save**", not "**Save** the file".
133
133
  - Write key combinations with spelled-out modifier names: Control+S. For several operating systems, give Windows and Linux first and macOS in parentheses.
134
134
 
135
135
  ## Dates and times
@@ -137,7 +137,7 @@ Don't wrap code in quotation marks unless the quotation marks are part of the co
137
137
  - Write dates with the full month and a four-digit year: "January 19, 2026". Abbreviate only in tables or headings: "Jan 19, 2026".
138
138
  - When a numeric date is unavoidable, use ISO 8601: `2026-01-19`.
139
139
  - Use the 12-hour clock with AM or PM: "3:45 PM", "3 PM". Use 24-hour time only when the product uses it.
140
- - Avoid time zones unless they're necessary. Spell out the region and add the UTC offset: "Pacific Standard Time (UTC-8)".
140
+ - Avoid time zones unless they are necessary. Spell out the region and add the UTC offset: "Pacific Standard Time (UTC-8)".
141
141
  - Avoid seasons, because they differ between hemispheres. Use months or quarters.
142
142
 
143
143
  ## Numbers
@@ -6,38 +6,37 @@ Rules for the [`dot-docs-writing`](../SKILL.md) skill that help readers who use
6
6
 
7
7
  - Use simple words: "start", not "commence"; "so", not "consequently"; "some" or "many", not "a number of".
8
8
  - Prefer one-word verbs to phrasal verbs, except standard terms such as "set up" and "sign in".
9
- - Use each word in its primary sense, and don't use the same word as a noun and a verb close together.
9
+ - Use each word in its primary sense, and do not use the same word as a noun and a verb close together.
10
10
  - Use subject-verb-object order, and keep the subject and verb near the start of the sentence.
11
11
  - Keep helper words that make structure explicit: "that", "then", "of". Write "Update the rules that you defined", not "Update the rules you defined".
12
12
  - Write "if X, then Y" in technical conditions.
13
13
  - Place "only" directly before the word it modifies.
14
- - Use no more than two nouns to modify another noun.
15
- - Replace "using" with "by using" or "that uses" when the meaning is unclear.
14
+ - Replace "using" with "with", "through", or "that uses".
16
15
  - Avoid idioms, metaphors, humor, slang, pop culture, sports references, and holidays.
17
16
  - Use a diverse set of names in examples, and use example domains such as `example.com`.
18
17
  - Address the reader as "you". Use "users" only for the people who use the software that the reader builds.
19
- - State what the reader can do instead of what they can't.
18
+ - State what the reader can do instead of what they cannot.
20
19
 
21
20
  ## Accessibility
22
21
 
23
22
  - Break text into short paragraphs, headings, and lists. Put the key information in the first sentence of each paragraph.
24
- - Keep sentences under 26 words. Avoid double negatives and exceptions to exceptions.
23
+ - Avoid double negatives and exceptions to exceptions.
25
24
  - Define acronyms at first use, and again if they appear rarely.
26
25
  - Write link text that makes sense out of context, because screen reader users often navigate by links alone.
27
26
  - Give every image alt text that conveys its purpose. Use empty alt text for decorative images.
28
27
  - Never put information only in an image, and never use images of text, code, or terminal output.
29
- - Don't rely on color, size, position, or shape alone. Pair each with a text label.
28
+ - Do not rely on color, size, position, or shape alone. Pair each with a text label.
30
29
  - Refer to UI elements by their labels, not by appearance ("the bell icon") or position ("on the right").
31
30
  - Use "and", not "&", except in UI labels and code.
32
- - Don't rely on punctuation alone to carry meaning, because some screen readers skip it.
33
- - Don't insert hard line breaks inside sentences.
31
+ - Do not rely on punctuation alone to carry meaning, because some screen readers skip it.
32
+ - Do not insert hard line breaks inside sentences.
34
33
  - Introduce every table, and use header cells for the first row or column only.
35
- - Provide captions or transcripts for audio and video, and avoid flashing content.
34
+ - Provide captions or transcripts for audio and video, and avoid content that flashes.
36
35
 
37
36
  ## Inclusive language
38
37
 
39
38
  - Use gender-neutral language. Use "they" for a person of unknown gender.
40
- - Use people-first or identity-first language as each community prefers. Don't describe people without disabilities as "normal" or "healthy".
39
+ - Use people-first or identity-first language as each community prefers. Do not describe people without disabilities as "normal" or "healthy".
41
40
  - Replace terms with violent, ableist, or oppressive connotations. See the inclusive language table in [`word-list.md`](word-list.md).
42
41
  - When code requires a non-inclusive term, use it only in code font, and use the inclusive term in prose.
43
42
 
@@ -16,9 +16,8 @@ These words add nothing, or judge difficulty for the reader:
16
16
  | latest, new, soon, eventually, in the future | A version number or date. |
17
17
  | performant | A precise measure, such as "responds in under 100 ms". |
18
18
  | functionality | features, capabilities |
19
- | leverage, utilize | use |
20
19
  | desire, wish | want, need |
21
- | via | through, by using, with |
20
+ | via | through, with |
22
21
  | learnings | lessons, things you learned |
23
22
  | allows you to | lets you |
24
23
 
@@ -29,7 +28,7 @@ These words have more than one meaning:
29
28
  | Avoid | Write instead |
30
29
  |-------|---------------|
31
30
  | should | must (required), can (optional), or a recommendation: "We recommend…" |
32
- | may | can (permission or ability), might (possibility) |
31
+ | may, might | can |
33
32
  | could, would | can |
34
33
  | will | Present tense, unless the event happens later. |
35
34
  | once (meaning "after") | after |
@@ -49,7 +48,7 @@ These words have more than one meaning:
49
48
  | Avoid | Write instead |
50
49
  |-------|---------------|
51
50
  | abort, kill, terminate (generic) | stop, exit, cancel, end |
52
- | hang, hung | stops responding, isn't responding |
51
+ | hang, hung | stops responding, is not responding |
53
52
  | hit (a key or button) | press, click |
54
53
  | hover over | hold the pointer over, point to |
55
54
  | click on | click |
@@ -85,7 +84,7 @@ These words have more than one meaning:
85
84
  | whitelist, blacklist | allowlist, denylist or blocklist |
86
85
  | master, slave | primary, main, leader, controller; replica, secondary, worker |
87
86
  | sanity check | quick check, confidence check |
88
- | crazy, insane, sane | unexpected, baffling, valid, sensible |
87
+ | crazy, insane, sane | unexpected, strange, valid, sensible |
89
88
  | cripple | slow down, break |
90
89
  | blind to, turn a blind eye | unaware of, ignore |
91
90
  | dumb down | simplify |
@@ -0,0 +1,75 @@
1
+ ---
2
+ name: dot-flow
3
+ description: Take one roadmap task through test stubs, implementation, test fill, and review, with your approval after each step.
4
+ disable-model-invocation: true
5
+ ---
6
+
7
+ # Flow
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.
14
+
15
+ ## 1. Pin the task
16
+
17
+ The input is a roadmap task file or a roadmap directory. With a directory, pick the lowest-id unticked task whose blockers are all ticked in its `README.md`. If the task has an unticked blocker, stop and name it.
18
+
19
+ Run `git status --short`. The review step reads every uncommitted change, so when the working tree has other changes, ask the user to commit them first or to include them in the review.
20
+
21
+ Done when you can name the task file and its goal.
22
+
23
+ ## 2. Pick the runner
24
+
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.
26
+
27
+ ## 3. Run the steps
28
+
29
+ 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
+
31
+ | Step | Agent | Prompt fields |
32
+ | ---- | ----- | ------------- |
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 |
37
+
38
+ Write the prompt as labeled fields, and leave out a field that the step does not take:
39
+
40
+ ```markdown
41
+ **Task:** <path of the task file>
42
+ **Mode:** <stub | fill>
43
+ **Handoff:**
44
+ <the replies of the earlier steps, unchanged>
45
+ ```
46
+
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.
48
+
49
+ ## 4. Approve each step
50
+
51
+ After each step, show the user this summary, then wait:
52
+
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
+ ```
59
+
60
+ For the review step, show the **Highest severity** line and one line for each finding: its severity, summary, and `file:line`.
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.
63
+
64
+ Stop the flow, and keep the files as they are, in these cases:
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.
68
+
69
+ Done when the user approved the review step, or the flow stopped.
70
+
71
+ ## 5. Finish
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.
74
+
75
+ Do not commit, and do not tick the roadmap checkbox: `dot-commit` ticks it when the commits finish the task.
@@ -0,0 +1,5 @@
1
+ interface:
2
+ display_name: "Flow"
3
+ short_description: "Run a roadmap task through tests, code, and review"
4
+ policy:
5
+ allow_implicit_invocation: false
@@ -0,0 +1,42 @@
1
+ # Inline mode
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.
4
+
5
+ ## Steps
6
+
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`.
@@ -4,8 +4,8 @@ description: A relentless interview to sharpen a plan or design.
4
4
  disable-model-invocation: true
5
5
  ---
6
6
 
7
- Use the `dot-grilling` skill to interview the user about the plan or design they describe.
7
+ Use the `dot-grilling` skill to interview the user about the plan or design that they describe.
8
8
 
9
9
  ## Repository conventions first
10
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 surrounding code. They take precedence over this skill: where they differ, follow the repository, and point out the difference instead of changing the repository's standard. The interview grounds its recommendations in those conventions.
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.