heimdall-agent 1.0.0 → 1.1.0

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 (231) hide show
  1. package/README.md +57 -26
  2. package/README.pt-BR.md +429 -0
  3. package/agents/cloud-engineer.md +77 -0
  4. package/agents/code-sentinel.md +66 -35
  5. package/agents/database-architect.md +31 -25
  6. package/agents/frontend-designer.md +30 -28
  7. package/agents/mobile-designer.md +25 -24
  8. package/agents/modernizer.md +66 -0
  9. package/agents/orchestrator.md +94 -93
  10. package/agents/reviewer.md +100 -71
  11. package/agents/security-auditor.md +27 -27
  12. package/agents/tester.md +97 -90
  13. package/commands/grill-me.md +20 -4
  14. package/commands/orchestrate.md +16 -0
  15. package/commands/orchestrator.md +16 -0
  16. package/commands/plan.md +17 -1
  17. package/config/agents.json +21 -3
  18. package/config/mcp.json +72 -0
  19. package/config/models.json +26 -16
  20. package/config/profiles.json +2 -4
  21. package/config/skills.json +210 -100
  22. package/docs/SKILLS.md +341 -245
  23. package/docs/designs/old/2026-10-31 plan-lifecycle-backlog-and-clean-code-skill.md +87 -0
  24. package/docs/designs/old/2026-11-02 skill-upstream-audit-and-update.md +105 -0
  25. package/docs/designs/old/2026-11-05 communication-doctrine-bluf-ste.md +94 -0
  26. package/docs/designs/old/2026-11-06-cloud-engineer-and-resilience-synthesis.md +67 -0
  27. package/docs/designs/old/2026-11-06-herdr-native-agent-orchestration.md +45 -0
  28. package/docs/runs/skill-audit/add_progressive_disclosure.cjs +30 -0
  29. package/docs/runs/skill-audit/check_heimdall_skills.ps1 +9 -0
  30. package/docs/runs/skill-audit/compare_classics.ps1 +26 -0
  31. package/docs/runs/skill-audit/compare_taste.ps1 +12 -0
  32. package/docs/runs/skill-audit/customization-report.json +380 -0
  33. package/docs/runs/skill-audit/diff_pending_skills.cjs +94 -0
  34. package/docs/runs/skill-audit/fetch_and_apply_skill.cjs +58 -0
  35. package/docs/runs/skill-audit/fetch_and_apply_taste_v2.cjs +65 -0
  36. package/docs/runs/skill-audit/inspect_pending_skills.cjs +71 -0
  37. package/docs/runs/skill-audit/inventory.json +308 -0
  38. package/docs/runs/skill-audit/list_local_taste.ps1 +1 -0
  39. package/docs/runs/skill-audit/phase5-update-plan.json +595 -0
  40. package/docs/runs/skill-audit/phase5-update-plan.md +138 -0
  41. package/docs/runs/skill-audit/probe.ps1 +16 -0
  42. package/docs/runs/skill-audit/probe_classics_branches.ps1 +3 -0
  43. package/docs/runs/skill-audit/probe_commits.ps1 +15 -0
  44. package/docs/runs/skill-audit/probe_repos.ps1 +17 -0
  45. package/docs/runs/skill-audit/probe_sentry_sec.ps1 +3 -0
  46. package/docs/runs/skill-audit/probe_sentry_sweep.ps1 +5 -0
  47. package/docs/runs/skill-audit/probe_snyk.ps1 +3 -0
  48. package/docs/runs/skill-audit/probe_snyk_recipes.ps1 +5 -0
  49. package/docs/runs/skill-audit/probe_taste_branches.ps1 +8 -0
  50. package/docs/runs/skill-audit/probe_taste_v19.ps1 +3 -0
  51. package/docs/runs/skill-audit/probe_user_repos.ps1 +19 -0
  52. package/docs/runs/skill-audit/prune_taste_skills.cjs +22 -0
  53. package/docs/runs/skill-audit/run_phase1_2.cjs +142 -0
  54. package/docs/runs/skill-audit/run_phase6_verification.cjs +107 -0
  55. package/docs/runs/skill-audit/show_16_details.ps1 +25 -0
  56. package/docs/runs/skill-audit/show_20_skills.ps1 +28 -0
  57. package/docs/runs/skill-audit/show_classics_diff.cjs +37 -0
  58. package/docs/runs/skill-audit/sync_agent_markdowns.cjs +30 -0
  59. package/docs/runs/skill-audit/taste-skill-upstream.md +542 -0
  60. package/docs/runs/skill-audit/update-manifest.md +88 -0
  61. package/docs/runs/skill-audit/update_config_skills.cjs +52 -0
  62. package/docs/runs/skill-audit/update_registry_phase7.cjs +83 -0
  63. package/docs/runs/skill-audit/upstream-status.json +563 -0
  64. package/docs/runs/skill-audit/verification-results.json +252 -0
  65. package/doctrine/AGENTS.md +39 -77
  66. package/hooks/git/pre-commit +11 -0
  67. package/hooks/heimdall-hook.cjs +81 -2
  68. package/hooks/herdr-agent-state.ps1 +55 -0
  69. package/hooks/hooks.json +0 -11
  70. package/lib/catalog-sync.cjs +162 -0
  71. package/lib/hermes-context.cjs +57 -0
  72. package/lib/model-context.cjs +123 -0
  73. package/lib/path-discovery.cjs +94 -0
  74. package/package.json +7 -3
  75. package/playbooks/01-interactive-grilling-gate.md +14 -1
  76. package/playbooks/02-fast-code-deep-verification.md +3 -2
  77. package/playbooks/03-adversarial-code-review.md +3 -3
  78. package/playbooks/05-canonical-plan-template.md +32 -18
  79. package/playbooks/06-model-registry-matrix.md +24 -13
  80. package/playbooks/07-legacy-code-modernization.md +74 -0
  81. package/playbooks/08-backlog-and-change-request-flow.md +122 -0
  82. package/setup.mjs +592 -172
  83. package/skills/antislop/SKILL.md +76 -56
  84. package/skills/antislop/VERSION +1 -0
  85. package/skills/antislop-copywriting/SKILL.md +372 -372
  86. package/skills/antislop-human/LICENSE-web-quality-skills +21 -0
  87. package/skills/antislop-human/SKILL.md +204 -147
  88. package/skills/antislop-human/contrast-check.py +168 -165
  89. package/skills/antislop-human/contrast-mcp.py +6 -3
  90. package/skills/antislop-human/references/A11Y-PATTERNS.md +249 -0
  91. package/skills/antislop-human/references/WCAG.md +127 -0
  92. package/skills/antislop-ui/LICENSE-web-quality-skills +21 -0
  93. package/skills/antislop-ui/SKILL.md +344 -304
  94. package/skills/antislop-ui/references/CORE-WEB-VITALS.md +181 -0
  95. package/skills/antislop-ui/references/WEB-BASELINE.md +28 -0
  96. package/skills/brainstorming/SKILL.md +274 -265
  97. package/skills/brainstorming/builder-check-prompt.md +23 -0
  98. package/skills/brainstorming/scripts/frame-template.html +213 -213
  99. package/skills/brainstorming/scripts/server.cjs +723 -723
  100. package/skills/brandkit/SKILL.md +798 -798
  101. package/skills/brutalist-skill/SKILL.md +93 -92
  102. package/skills/caveman/README.md +68 -0
  103. package/skills/caveman/SKILL.md +73 -38
  104. package/skills/claude-collaborator/SKILL.md +24 -44
  105. package/skills/clean-code/SKILL.md +152 -0
  106. package/skills/cloudflare-security-audit/AI-AND-LLM.md +83 -83
  107. package/skills/cloudflare-security-audit/ATTACK-CLASSES.md +130 -130
  108. package/skills/cloudflare-security-audit/CLIENT-SIDE.md +83 -83
  109. package/skills/cloudflare-security-audit/CLOUD-AND-DEPLOYMENT.md +86 -86
  110. package/skills/cloudflare-security-audit/DATA-ISOLATION-AND-LIFECYCLE.md +84 -84
  111. package/skills/cloudflare-security-audit/DESKTOP-MOBILE-AND-LOCAL-IPC.md +89 -89
  112. package/skills/cloudflare-security-audit/HUNTING.md +251 -251
  113. package/skills/cloudflare-security-audit/MEMORY-SAFETY-AND-BINARY.md +101 -101
  114. package/skills/cloudflare-security-audit/PROTOCOLS-RPC-AND-MESSAGING.md +81 -81
  115. package/skills/cloudflare-security-audit/RECONNAISSANCE.md +156 -156
  116. package/skills/cloudflare-security-audit/RESOURCE-EXHAUSTION-AND-AVAILABILITY.md +78 -78
  117. package/skills/cloudflare-security-audit/SKILL.md +192 -192
  118. package/skills/cloudflare-security-audit/SUPPLY-CHAIN-AND-RELEASE.md +73 -73
  119. package/skills/cloudflare-security-audit/VALIDATION-AND-REPORTING.md +186 -186
  120. package/skills/cloudflare-security-audit/WEB-PROTOCOL-AND-AUTH.md +105 -105
  121. package/skills/cloudflare-security-audit/report-schema.json +461 -461
  122. package/skills/cloudflare-security-audit/validate-coverage-ledger.cjs +872 -872
  123. package/skills/cloudflare-security-audit/validate-coverage-ledger.test.cjs +740 -740
  124. package/skills/cloudflare-security-audit/validate-findings.cjs +773 -773
  125. package/skills/cloudflare-security-audit/validate-findings.test.cjs +652 -652
  126. package/skills/codex-collaborator/SKILL.md +24 -45
  127. package/skills/communication-doctrine/SKILL.md +89 -0
  128. package/skills/diagnosing-superpowers/SKILL.md +1 -1
  129. package/skills/diagnosing-superpowers/references/github-issues.md +3 -3
  130. package/skills/diagnosing-superpowers/templates/issue.md +23 -4
  131. package/skills/executing-plans/SKILL.md +0 -52
  132. package/skills/executing-plans/scripts/task-done +52 -52
  133. package/skills/executing-plans/scripts/task-start +28 -28
  134. package/skills/gemini-collaborator/SKILL.md +24 -56
  135. package/skills/herdr/SKILL.md +243 -0
  136. package/skills/image-to-code-skill/SKILL.md +1228 -1228
  137. package/skills/imagegen-frontend-mobile/SKILL.md +1465 -1465
  138. package/skills/imagegen-frontend-web/SKILL.md +987 -987
  139. package/skills/karpathy-guidelines/SKILL.md +67 -67
  140. package/skills/mcp-engineering/SKILL.md +74 -0
  141. package/skills/minimalist-skill/SKILL.md +87 -85
  142. package/skills/output-skill/SKILL.md +49 -49
  143. package/skills/ponytail/SKILL.md +36 -52
  144. package/skills/postgres-best-practices/SKILL.md +30 -52
  145. package/skills/postgres-best-practices/references/backup-restore.md +372 -0
  146. package/skills/postgres-best-practices/references/bulk-loading.md +315 -0
  147. package/skills/postgres-best-practices/references/connection-pooling.md +310 -0
  148. package/skills/postgres-best-practices/references/hot-standby.md +221 -0
  149. package/skills/postgres-best-practices/references/indexing.md +318 -0
  150. package/skills/postgres-best-practices/references/logical-replication.md +610 -0
  151. package/skills/postgres-best-practices/references/major-version-upgrades.md +334 -0
  152. package/skills/postgres-best-practices/references/performance-diagnostics.md +553 -0
  153. package/skills/postgres-best-practices/references/query-optimization.md +294 -0
  154. package/skills/postgres-best-practices/references/query-patterns.md +566 -0
  155. package/skills/postgres-best-practices/references/schema-design.md +362 -0
  156. package/skills/postgres-best-practices/references/security-roles.md +489 -0
  157. package/skills/postgres-best-practices/references/transaction-isolation.md +344 -0
  158. package/skills/progressive-disclosure/SKILL.md +68 -0
  159. package/skills/pstack-discipline/SKILL.md +40 -0
  160. package/skills/receiving-code-review/SKILL.md +2 -23
  161. package/skills/requesting-code-review/SKILL.md +7 -36
  162. package/skills/soft-skill/SKILL.md +99 -98
  163. package/skills/stitch-skill/DESIGN.md +121 -121
  164. package/skills/stitch-skill/SKILL.md +185 -184
  165. package/skills/strix-security/SKILL.md +54 -53
  166. package/skills/subagent-driven-development/SKILL.md +28 -260
  167. package/skills/subagent-driven-development/references/batching.md +11 -0
  168. package/skills/subagent-driven-development/references/cannot-verify.md +10 -0
  169. package/skills/subagent-driven-development/references/final-review.md +47 -0
  170. package/skills/subagent-driven-development/references/fix-loop.md +77 -0
  171. package/skills/subagent-driven-development/references/handling-reports.md +15 -0
  172. package/skills/subagent-driven-development/references/preflight.md +26 -0
  173. package/skills/subagent-driven-development/references/resuming.md +12 -0
  174. package/skills/subagent-driven-development/scripts/review-package +53 -53
  175. package/skills/subagent-driven-development/scripts/sdd-workspace +87 -82
  176. package/skills/subagent-driven-development/scripts/task-brief +43 -43
  177. package/skills/systematic-debugging/SKILL.md +283 -306
  178. package/skills/taste-skill/SKILL.md +542 -1206
  179. package/skills/taste-skill/references/app-screens.md +1199 -0
  180. package/skills/taste-skill/references/colour.md +141 -0
  181. package/skills/taste-skill/references/copy.md +177 -0
  182. package/skills/taste-skill/references/critique.md +182 -0
  183. package/skills/taste-skill/references/imagery.md +791 -0
  184. package/skills/taste-skill/references/layout.md +292 -0
  185. package/skills/taste-skill/references/motion.md +980 -0
  186. package/skills/taste-skill/references/research.md +356 -0
  187. package/skills/taste-skill/references/scenes.md +174 -0
  188. package/skills/taste-skill/references/tells.md +115 -0
  189. package/skills/taste-skill/references/type.md +170 -0
  190. package/skills/test-driven-development/SKILL.md +330 -337
  191. package/skills/thermo/SKILL.md +67 -0
  192. package/skills/threat-modeling/SKILL.md +55 -0
  193. package/skills/trailofbits-audit-context/SKILL.md +72 -72
  194. package/skills/trailofbits-insecure-defaults/commands/audit.md +35 -0
  195. package/skills/trailofbits-insecure-defaults/references/debug-features.json +13 -13
  196. package/skills/trailofbits-insecure-defaults/references/debug-features.md +75 -75
  197. package/skills/trailofbits-insecure-defaults/references/default-credentials.json +12 -12
  198. package/skills/trailofbits-insecure-defaults/references/default-credentials.md +76 -76
  199. package/skills/trailofbits-insecure-defaults/references/fail-open-security.json +11 -11
  200. package/skills/trailofbits-insecure-defaults/references/fail-open-security.md +70 -70
  201. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.json +11 -11
  202. package/skills/trailofbits-insecure-defaults/references/fallback-secrets.md +70 -70
  203. package/skills/trailofbits-insecure-defaults/references/permissive-access.json +13 -13
  204. package/skills/trailofbits-insecure-defaults/references/permissive-access.md +62 -62
  205. package/skills/trailofbits-insecure-defaults/references/weak-crypto.json +13 -13
  206. package/skills/trailofbits-insecure-defaults/references/weak-crypto.md +71 -71
  207. package/skills/trailofbits-triage-brocards/SKILL.md +208 -208
  208. package/skills/verification-before-completion/SKILL.md +0 -14
  209. package/skills/writing-plans/SKILL.md +11 -15
  210. package/skills/writing-skills/SKILL.md +21 -303
  211. package/skills/writing-skills/references/CLAUDE_MD_TESTING.md +189 -0
  212. package/skills/writing-skills/references/anthropic-best-practices.md +1150 -0
  213. package/skills/writing-skills/references/bulletproofing.md +80 -0
  214. package/skills/writing-skills/references/discovery.md +201 -0
  215. package/skills/writing-skills/references/flowcharts.md +37 -0
  216. package/skills/writing-skills/references/graphviz-conventions.dot +172 -0
  217. package/skills/writing-skills/references/persuasion-principles.md +187 -0
  218. package/skills/writing-skills/references/testing-skills-with-subagents.md +384 -0
  219. package/tools/{claude-bridge.ps1 → archive/claude-bridge.ps1} +10 -7
  220. package/tools/{codex-bridge.ps1 → archive/codex-bridge.ps1} +1 -1
  221. package/tools/{gemini-bridge.ps1 → archive/gemini-bridge.ps1} +12 -19
  222. package/skills/gpt-tasteskill/SKILL.md +0 -74
  223. package/skills/taste-skill-v1/SKILL.md +0 -226
  224. /package/tools/{claude-bridge.cmd → archive/claude-bridge.cmd} +0 -0
  225. /package/tools/{claude-bridge.sh → archive/claude-bridge.sh} +0 -0
  226. /package/tools/{codex-bridge.cmd → archive/codex-bridge.cmd} +0 -0
  227. /package/tools/{codex-bridge.sh → archive/codex-bridge.sh} +0 -0
  228. /package/tools/{codexcli-bridge.cmd → archive/codexcli-bridge.cmd} +0 -0
  229. /package/tools/{codexcli-bridge.ps1 → archive/codexcli-bridge.ps1} +0 -0
  230. /package/tools/{gemini-bridge.cmd → archive/gemini-bridge.cmd} +0 -0
  231. /package/tools/{gemini-bridge.sh → archive/gemini-bridge.sh} +0 -0
@@ -1,337 +1,330 @@
1
- ---
2
- name: test-driven-development
3
- description: Use when implementing any feature or bugfix, before writing implementation code
4
- ---
5
-
6
- # Test-Driven Development (TDD)
7
-
8
- ## Overview
9
-
10
- Write the test first. Watch it fail. Write minimal code to pass.
11
-
12
- **Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
13
-
14
- **Violating the letter of the rules is violating the spirit of the rules.**
15
-
16
- ## When to Use
17
-
18
- **Always:**
19
- - New features
20
- - Bug fixes
21
- - Refactoring
22
- - Behavior changes
23
-
24
- **Exceptions (ask your human partner):**
25
- - Throwaway prototypes
26
- - Generated code
27
- - Configuration files
28
-
29
- Thinking "skip TDD just this once"? Stop. That's rationalization.
30
-
31
- ## The Iron Law
32
-
33
- ```
34
- NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
35
- ```
36
-
37
- Write code before the test? Delete it. Start over.
38
-
39
- **No exceptions:**
40
- - Don't keep it as "reference"
41
- - Don't "adapt" it while writing tests
42
- - Don't look at it
43
- - Delete means delete
44
-
45
- Implement fresh from tests. Period.
46
-
47
- ### The Google EGM Blind Bug Reproduction Principle
48
- When reproducing a bug reported by an external actor or an ongoing session:
49
- - **Blind the Diagnoser**: Isolate the test author from speculative narrative or guessed solutions.
50
- - Provide only symptoms, repro steps, and boundary data.
51
- - The test author must independently codify a test that fails with the identical symptom.
52
- - If the test passes or fails for an unrelated reason, the bug is not isolated; do not write code until the failure is authentically codified.
53
-
54
- ## Red-Green-Refactor
55
-
56
- ```dot
57
- digraph tdd_cycle {
58
- rankdir=LR;
59
- red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
60
- verify_red [label="Verify fails\ncorrectly", shape=diamond];
61
- green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
62
- verify_green [label="Verify passes\nAll green", shape=diamond];
63
- refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
64
- next [label="Next", shape=ellipse];
65
-
66
- red -> verify_red;
67
- verify_red -> green [label="yes"];
68
- verify_red -> red [label="wrong\nfailure"];
69
- green -> verify_green;
70
- verify_green -> refactor [label="yes"];
71
- verify_green -> green [label="no"];
72
- refactor -> verify_green [label="stay\ngreen"];
73
- verify_green -> next;
74
- next -> red;
75
- }
76
- ```
77
-
78
- ### RED - Write Failing Test
79
-
80
- Write one minimal test showing what should happen.
81
-
82
- <Good>
83
- ```typescript
84
- test('retries failed operations 3 times', async () => {
85
- let attempts = 0;
86
- const operation = () => {
87
- attempts++;
88
- if (attempts < 3) throw new Error('fail');
89
- return 'success';
90
- };
91
-
92
- const result = await retryOperation(operation);
93
-
94
- expect(result).toBe('success');
95
- expect(attempts).toBe(3);
96
- });
97
- ```
98
- Clear name, tests real behavior, one thing
99
- </Good>
100
-
101
- <Bad>
102
- ```typescript
103
- test('retry works', async () => {
104
- const mock = jest.fn()
105
- .mockRejectedValueOnce(new Error())
106
- .mockRejectedValueOnce(new Error())
107
- .mockResolvedValueOnce('success');
108
- await retryOperation(mock);
109
- expect(mock).toHaveBeenCalledTimes(3);
110
- });
111
- ```
112
- Vague name, tests mock not code
113
- </Bad>
114
-
115
- **Requirements:**
116
- - One behavior
117
- - Clear name
118
- - Real code (no mocks unless unavoidable)
119
-
120
- ### Verify RED - Watch It Fail
121
-
122
- **MANDATORY. Never skip.**
123
-
124
- ```bash
125
- npm test path/to/test.test.ts
126
- ```
127
-
128
- Confirm:
129
- - Test fails (not errors)
130
- - Failure message is expected
131
- - Fails because feature missing (not typos)
132
-
133
- **Test passes?** You're testing existing behavior. Fix test.
134
-
135
- **Test errors?** Fix error, re-run until it fails correctly.
136
-
137
- ### GREEN - Minimal Code
138
-
139
- Write simplest code to pass the test.
140
-
141
- <Good>
142
- ```typescript
143
- async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
144
- for (let i = 0; i < 3; i++) {
145
- try {
146
- return await fn();
147
- } catch (e) {
148
- if (i === 2) throw e;
149
- }
150
- }
151
- throw new Error('unreachable');
152
- }
153
- ```
154
- Just enough to pass
155
- </Good>
156
-
157
- <Bad>
158
- ```typescript
159
- async function retryOperation<T>(
160
- fn: () => Promise<T>,
161
- options?: {
162
- maxRetries?: number;
163
- backoff?: 'linear' | 'exponential';
164
- onRetry?: (attempt: number) => void;
165
- }
166
- ): Promise<T> {
167
- // YAGNI
168
- }
169
- ```
170
- Over-engineered
171
- </Bad>
172
-
173
- Don't add features, refactor other code, or "improve" beyond the test.
174
-
175
- ### Verify GREEN - Watch It Pass
176
-
177
- **MANDATORY.**
178
-
179
- ```bash
180
- npm test path/to/test.test.ts
181
- ```
182
-
183
- Confirm:
184
- - Test passes
185
- - Other tests still pass
186
- - Output pristine (no errors, warnings)
187
-
188
- **Test fails?** Fix code, not test.
189
-
190
- **Other tests fail?** Fix now.
191
-
192
- **"Other tests" means the project's suite, not just your file.** A
193
- green run of the test you wrote is not a green suite. Before you call
194
- the change done, run the project's test command (bare `pytest`,
195
- `npm test`, `cargo test` — whatever the repo uses) even when your task
196
- named only one test file. A scope statement in your task bounds the
197
- deliverable, not your verification. Any failure that run shows —
198
- including one you didn't cause — goes in your report by name; a red
199
- test you watched scroll past and didn't mention is a report falsified
200
- by omission.
201
-
202
- ### REFACTOR - Clean Up
203
-
204
- After green only:
205
- - Remove duplication
206
- - Improve names
207
- - Extract helpers
208
-
209
- Keep tests green. Don't add behavior.
210
-
211
- ### Repeat
212
-
213
- Next failing test for next feature.
214
-
215
- ## Good Tests
216
-
217
- | Quality | Good | Bad |
218
- |---------|------|-----|
219
- | **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
220
- | **Clear** | Name describes behavior | `test('test1')` |
221
- | **Shows intent** | Demonstrates desired API | Obscures what code should do |
222
-
223
- When writing or changing any test, read [writing-good-tests.md](writing-good-tests.md) for the rules that keep tests honest:
224
- - Name the production change that would make the test fail — before writing it
225
- - Assert on real behavior, never on mock behavior
226
- - Keep test-only code in test utilities, out of production classes
227
- - Understand a dependency's side effects before mocking it
228
-
229
- ## Common Rationalizations
230
-
231
- | Excuse | Reality |
232
- |--------|---------|
233
- | "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
234
- | "I'll test after" | Tests written after pass immediately — which proves nothing. They may test the wrong thing, test the implementation instead of the behavior, or miss the edge case you forgot. You never watched it fail, so you never proved it can catch the bug. Test-first forces that failure. |
235
- | "Tests after achieve same goals (spirit not ritual)" | Tests-after answer "what does this do?"; tests-first answer "what should this do?" Tests written after are biased by the code you already wrote — you verify the cases you remembered, not the ones you'd have discovered. Coverage without proof the tests work. |
236
- | "Already manually tested" | Manual testing is ad-hoc: no record of what you covered, no way to re-run it when the code changes, easy to forget cases under pressure. "Worked when I tried it" ≠ comprehensive. Automated tests run the same way every time. |
237
- | "Deleting X hours is wasteful" | Sunk cost fallacy — that time is already spent either way. The real choice: rewrite with TDD (high confidence) vs. keep it and bolt tests on after (low confidence, likely bugs). Keeping code you can't trust is the waste. |
238
- | "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
239
- | "Need to explore first" | Fine. Throw away exploration, start with TDD. |
240
- | "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
241
- | "TDD will slow me down" | TDD IS the pragmatic path: catches bugs before commit, prevents regressions, lets you refactor without fear. "Pragmatic" shortcuts mean debugging in production — slower, not faster. |
242
- | "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
243
- | "Existing code has no tests" | You're improving it. Add tests for existing code. |
244
-
245
- ## Red Flags - STOP and Start Over
246
-
247
- - Code before test
248
- - Test after implementation
249
- - Test passes immediately
250
- - Can't explain why test failed
251
- - Tests added "later"
252
- - Rationalizing "just this once"
253
- - "I already manually tested it"
254
- - "Tests after achieve the same purpose"
255
- - "It's about spirit not ritual"
256
- - "Keep as reference" or "adapt existing code"
257
- - "Already spent X hours, deleting is wasteful"
258
- - "TDD is dogmatic, I'm being pragmatic"
259
- - "This is different because..."
260
-
261
- **All of these mean: Delete code. Start over with TDD.**
262
-
263
- ## Example: Bug Fix
264
-
265
- **Bug:** Empty email accepted
266
-
267
- **RED**
268
- ```typescript
269
- test('rejects empty email', async () => {
270
- const result = await submitForm({ email: '' });
271
- expect(result.error).toBe('Email required');
272
- });
273
- ```
274
-
275
- **Verify RED**
276
- ```bash
277
- $ npm test
278
- FAIL: expected 'Email required', got undefined
279
- ```
280
-
281
- **GREEN**
282
- ```typescript
283
- function submitForm(data: FormData) {
284
- if (!data.email?.trim()) {
285
- return { error: 'Email required' };
286
- }
287
- // ...
288
- }
289
- ```
290
-
291
- **Verify GREEN**
292
- ```bash
293
- $ npm test
294
- PASS
295
- ```
296
-
297
- **REFACTOR**
298
- Extract validation for multiple fields if needed.
299
-
300
- ## Verification Checklist
301
-
302
- Before marking work complete:
303
-
304
- - [ ] Every new function/method has a test
305
- - [ ] Watched each test fail before implementing
306
- - [ ] Each test failed for expected reason (feature missing, not typo)
307
- - [ ] Wrote minimal code to pass each test
308
- - [ ] All tests pass
309
- - [ ] Output pristine (no errors, warnings)
310
- - [ ] Tests use real code (mocks only if unavoidable)
311
- - [ ] Edge cases and errors covered
312
-
313
- Can't check all boxes? You skipped TDD. Start over.
314
-
315
- ## When Stuck
316
-
317
- | Problem | Solution |
318
- |---------|----------|
319
- | Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. |
320
- | Test too complicated | Design too complicated. Simplify interface. |
321
- | Must mock everything | Code too coupled. Use dependency injection. |
322
- | Test setup huge | Extract helpers. Still complex? Simplify design. |
323
-
324
- ## Debugging Integration
325
-
326
- Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
327
-
328
- Never fix bugs without a test.
329
-
330
- ## Final Rule
331
-
332
- ```
333
- Production code → test exists and failed first
334
- Otherwise → not TDD
335
- ```
336
-
337
- No exceptions without your human partner's permission.
1
+ ---
2
+ name: test-driven-development
3
+ description: Use when implementing any feature or bugfix, before writing implementation code
4
+ ---
5
+
6
+ # Test-Driven Development (TDD)
7
+
8
+ ## Overview
9
+
10
+ Write the test first. Watch it fail. Write minimal code to pass.
11
+
12
+ **Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.
13
+
14
+ **Violating the letter of the rules is violating the spirit of the rules.**
15
+
16
+ ## When to Use
17
+
18
+ **Always:**
19
+ - New features
20
+ - Bug fixes
21
+ - Refactoring
22
+ - Behavior changes
23
+
24
+ **Exceptions (ask your human partner):**
25
+ - Throwaway prototypes
26
+ - Generated code
27
+ - Configuration files
28
+
29
+ Thinking "skip TDD just this once"? Stop. That's rationalization.
30
+
31
+ ## The Iron Law
32
+
33
+ ```
34
+ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
35
+ ```
36
+
37
+ Write code before the test? Delete it. Start over.
38
+
39
+ **No exceptions:**
40
+ - Don't keep it as "reference"
41
+ - Don't "adapt" it while writing tests
42
+ - Don't look at it
43
+ - Delete means delete
44
+
45
+ Implement fresh from tests. Period.
46
+
47
+ ## Red-Green-Refactor
48
+
49
+ ```dot
50
+ digraph tdd_cycle {
51
+ rankdir=LR;
52
+ red [label="RED\nWrite failing test", shape=box, style=filled, fillcolor="#ffcccc"];
53
+ verify_red [label="Verify fails\ncorrectly", shape=diamond];
54
+ green [label="GREEN\nMinimal code", shape=box, style=filled, fillcolor="#ccffcc"];
55
+ verify_green [label="Verify passes\nAll green", shape=diamond];
56
+ refactor [label="REFACTOR\nClean up", shape=box, style=filled, fillcolor="#ccccff"];
57
+ next [label="Next", shape=ellipse];
58
+
59
+ red -> verify_red;
60
+ verify_red -> green [label="yes"];
61
+ verify_red -> red [label="wrong\nfailure"];
62
+ green -> verify_green;
63
+ verify_green -> refactor [label="yes"];
64
+ verify_green -> green [label="no"];
65
+ refactor -> verify_green [label="stay\ngreen"];
66
+ verify_green -> next;
67
+ next -> red;
68
+ }
69
+ ```
70
+
71
+ ### RED - Write Failing Test
72
+
73
+ Write one minimal test showing what should happen.
74
+
75
+ <Good>
76
+ ```typescript
77
+ test('retries failed operations 3 times', async () => {
78
+ let attempts = 0;
79
+ const operation = () => {
80
+ attempts++;
81
+ if (attempts < 3) throw new Error('fail');
82
+ return 'success';
83
+ };
84
+
85
+ const result = await retryOperation(operation);
86
+
87
+ expect(result).toBe('success');
88
+ expect(attempts).toBe(3);
89
+ });
90
+ ```
91
+ Clear name, tests real behavior, one thing
92
+ </Good>
93
+
94
+ <Bad>
95
+ ```typescript
96
+ test('retry works', async () => {
97
+ const mock = jest.fn()
98
+ .mockRejectedValueOnce(new Error())
99
+ .mockRejectedValueOnce(new Error())
100
+ .mockResolvedValueOnce('success');
101
+ await retryOperation(mock);
102
+ expect(mock).toHaveBeenCalledTimes(3);
103
+ });
104
+ ```
105
+ Vague name, tests mock not code
106
+ </Bad>
107
+
108
+ **Requirements:**
109
+ - One behavior
110
+ - Clear name
111
+ - Real code (no mocks unless unavoidable)
112
+
113
+ ### Verify RED - Watch It Fail
114
+
115
+ **MANDATORY. Never skip.**
116
+
117
+ ```bash
118
+ npm test path/to/test.test.ts
119
+ ```
120
+
121
+ Confirm:
122
+ - Test fails (not errors)
123
+ - Failure message is expected
124
+ - Fails because feature missing (not typos)
125
+
126
+ **Test passes?** You're testing existing behavior. Fix test.
127
+
128
+ **Test errors?** Fix error, re-run until it fails correctly.
129
+
130
+ ### GREEN - Minimal Code
131
+
132
+ Write simplest code to pass the test.
133
+
134
+ <Good>
135
+ ```typescript
136
+ async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
137
+ for (let i = 0; i < 3; i++) {
138
+ try {
139
+ return await fn();
140
+ } catch (e) {
141
+ if (i === 2) throw e;
142
+ }
143
+ }
144
+ throw new Error('unreachable');
145
+ }
146
+ ```
147
+ Just enough to pass
148
+ </Good>
149
+
150
+ <Bad>
151
+ ```typescript
152
+ async function retryOperation<T>(
153
+ fn: () => Promise<T>,
154
+ options?: {
155
+ maxRetries?: number;
156
+ backoff?: 'linear' | 'exponential';
157
+ onRetry?: (attempt: number) => void;
158
+ }
159
+ ): Promise<T> {
160
+ // YAGNI
161
+ }
162
+ ```
163
+ Over-engineered
164
+ </Bad>
165
+
166
+ Don't add features, refactor other code, or "improve" beyond the test.
167
+
168
+ ### Verify GREEN - Watch It Pass
169
+
170
+ **MANDATORY.**
171
+
172
+ ```bash
173
+ npm test path/to/test.test.ts
174
+ ```
175
+
176
+ Confirm:
177
+ - Test passes
178
+ - Other tests still pass
179
+ - Output pristine (no errors, warnings)
180
+
181
+ **Test fails?** Fix code, not test.
182
+
183
+ **Other tests fail?** Fix now.
184
+
185
+ **"Other tests" means the project's suite, not just your file.** A
186
+ green run of the test you wrote is not a green suite. Before you call
187
+ the change done, run the project's test command (bare `pytest`,
188
+ `npm test`, `cargo test` — whatever the repo uses) even when your task
189
+ named only one test file. A scope statement in your task bounds the
190
+ deliverable, not your verification. Any failure that run shows —
191
+ including one you didn't cause — goes in your report by name; a red
192
+ test you watched scroll past and didn't mention is a report falsified
193
+ by omission.
194
+
195
+ ### REFACTOR - Clean Up
196
+
197
+ After green only:
198
+ - Remove duplication
199
+ - Improve names
200
+ - Extract helpers
201
+
202
+ Keep tests green. Don't add behavior.
203
+
204
+ ### Repeat
205
+
206
+ Next failing test for next feature.
207
+
208
+ ## Good Tests
209
+
210
+ | Quality | Good | Bad |
211
+ |---------|------|-----|
212
+ | **Minimal** | One thing. "and" in name? Split it. | `test('validates email and domain and whitespace')` |
213
+ | **Clear** | Name describes behavior | `test('test1')` |
214
+ | **Shows intent** | Demonstrates desired API | Obscures what code should do |
215
+
216
+ When writing or changing any test, read [writing-good-tests.md](writing-good-tests.md) for the rules that keep tests honest:
217
+ - Name the production change that would make the test fail — before writing it
218
+ - Assert on real behavior, never on mock behavior
219
+ - Keep test-only code in test utilities, out of production classes
220
+ - Understand a dependency's side effects before mocking it
221
+
222
+ ## Common Rationalizations
223
+
224
+ | Excuse | Reality |
225
+ |--------|---------|
226
+ | "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
227
+ | "I'll test after" | Tests written after pass immediately — which proves nothing. They may test the wrong thing, test the implementation instead of the behavior, or miss the edge case you forgot. You never watched it fail, so you never proved it can catch the bug. Test-first forces that failure. |
228
+ | "Tests after achieve same goals (spirit not ritual)" | Tests-after answer "what does this do?"; tests-first answer "what should this do?" Tests written after are biased by the code you already wrote — you verify the cases you remembered, not the ones you'd have discovered. Coverage without proof the tests work. |
229
+ | "Already manually tested" | Manual testing is ad-hoc: no record of what you covered, no way to re-run it when the code changes, easy to forget cases under pressure. "Worked when I tried it" ≠ comprehensive. Automated tests run the same way every time. |
230
+ | "Deleting X hours is wasteful" | Sunk cost fallacy — that time is already spent either way. The real choice: rewrite with TDD (high confidence) vs. keep it and bolt tests on after (low confidence, likely bugs). Keeping code you can't trust is the waste. |
231
+ | "Keep as reference, write tests first" | You'll adapt it. That's testing after. Delete means delete. |
232
+ | "Need to explore first" | Fine. Throw away exploration, start with TDD. |
233
+ | "Test hard = design unclear" | Listen to test. Hard to test = hard to use. |
234
+ | "TDD will slow me down" | TDD IS the pragmatic path: catches bugs before commit, prevents regressions, lets you refactor without fear. "Pragmatic" shortcuts mean debugging in production — slower, not faster. |
235
+ | "Manual test faster" | Manual doesn't prove edge cases. You'll re-test every change. |
236
+ | "Existing code has no tests" | You're improving it. Add tests for existing code. |
237
+
238
+ ## Red Flags - STOP and Start Over
239
+
240
+ - Code before test
241
+ - Test after implementation
242
+ - Test passes immediately
243
+ - Can't explain why test failed
244
+ - Tests added "later"
245
+ - Rationalizing "just this once"
246
+ - "I already manually tested it"
247
+ - "Tests after achieve the same purpose"
248
+ - "It's about spirit not ritual"
249
+ - "Keep as reference" or "adapt existing code"
250
+ - "Already spent X hours, deleting is wasteful"
251
+ - "TDD is dogmatic, I'm being pragmatic"
252
+ - "This is different because..."
253
+
254
+ **All of these mean: Delete code. Start over with TDD.**
255
+
256
+ ## Example: Bug Fix
257
+
258
+ **Bug:** Empty email accepted
259
+
260
+ **RED**
261
+ ```typescript
262
+ test('rejects empty email', async () => {
263
+ const result = await submitForm({ email: '' });
264
+ expect(result.error).toBe('Email required');
265
+ });
266
+ ```
267
+
268
+ **Verify RED**
269
+ ```bash
270
+ $ npm test
271
+ FAIL: expected 'Email required', got undefined
272
+ ```
273
+
274
+ **GREEN**
275
+ ```typescript
276
+ function submitForm(data: FormData) {
277
+ if (!data.email?.trim()) {
278
+ return { error: 'Email required' };
279
+ }
280
+ // ...
281
+ }
282
+ ```
283
+
284
+ **Verify GREEN**
285
+ ```bash
286
+ $ npm test
287
+ PASS
288
+ ```
289
+
290
+ **REFACTOR**
291
+ Extract validation for multiple fields if needed.
292
+
293
+ ## Verification Checklist
294
+
295
+ Before marking work complete:
296
+
297
+ - [ ] Every new function/method has a test
298
+ - [ ] Watched each test fail before implementing
299
+ - [ ] Each test failed for expected reason (feature missing, not typo)
300
+ - [ ] Wrote minimal code to pass each test
301
+ - [ ] All tests pass
302
+ - [ ] Output pristine (no errors, warnings)
303
+ - [ ] Tests use real code (mocks only if unavoidable)
304
+ - [ ] Edge cases and errors covered
305
+
306
+ Can't check all boxes? You skipped TDD. Start over.
307
+
308
+ ## When Stuck
309
+
310
+ | Problem | Solution |
311
+ |---------|----------|
312
+ | Don't know how to test | Write wished-for API. Write assertion first. Ask your human partner. |
313
+ | Test too complicated | Design too complicated. Simplify interface. |
314
+ | Must mock everything | Code too coupled. Use dependency injection. |
315
+ | Test setup huge | Extract helpers. Still complex? Simplify design. |
316
+
317
+ ## Debugging Integration
318
+
319
+ Bug found? Write failing test reproducing it. Follow TDD cycle. Test proves fix and prevents regression.
320
+
321
+ Never fix bugs without a test.
322
+
323
+ ## Final Rule
324
+
325
+ ```
326
+ Production code → test exists and failed first
327
+ Otherwise → not TDD
328
+ ```
329
+
330
+ No exceptions without your human partner's permission.