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
@@ -0,0 +1,80 @@
1
+ # Bulletproofing Skills Against Rationalization
2
+
3
+ Part of superpowers:writing-skills. Use it when the baseline failure is a
4
+ discipline failure: the agent knows the rule and skips it under pressure.
5
+
6
+ ## Bulletproofing Skills Against Rationalization
7
+
8
+ Skills that enforce discipline (like TDD) need to resist rationalization. Agents are smart and will find loopholes when under pressure.
9
+
10
+ **Scope:** this toolkit is for discipline failures — an agent that knows the rule and skips it under pressure. For wrong-shaped output or omitted elements, prohibition-based bulletproofing backfires; use the forms in Match the Form to the Failure instead.
11
+
12
+ **Psychology note:** Understanding WHY persuasion techniques work helps you apply them systematically. See persuasion-principles.md in this directory for research foundation (Cialdini, 2021; Meincke et al., 2025) on authority, commitment, scarcity, social proof, and unity principles.
13
+
14
+ ### Close Every Loophole Explicitly
15
+
16
+ Don't just state the rule - forbid specific workarounds:
17
+
18
+ <Bad>
19
+ ```markdown
20
+ Write code before test? Delete it.
21
+ ```
22
+ </Bad>
23
+
24
+ <Good>
25
+ ```markdown
26
+ Write code before test? Delete it. Start over.
27
+
28
+ **No exceptions:**
29
+ - Don't keep it as "reference"
30
+ - Don't "adapt" it while writing tests
31
+ - Don't look at it
32
+ - Delete means delete
33
+ ```
34
+ </Good>
35
+
36
+ ### Address "Spirit vs Letter" Arguments
37
+
38
+ Add foundational principle early:
39
+
40
+ ```markdown
41
+ **Violating the letter of the rules is violating the spirit of the rules.**
42
+ ```
43
+
44
+ This cuts off entire class of "I'm following the spirit" rationalizations.
45
+
46
+ ### Build Rationalization Table
47
+
48
+ Capture rationalizations from baseline testing (see Testing section below). Every excuse agents make goes in the table:
49
+
50
+ ```markdown
51
+ | Excuse | Reality |
52
+ |--------|---------|
53
+ | "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
54
+ | "I'll test after" | Tests passing immediately prove nothing. |
55
+ | "Tests after achieve same goals" | Tests-after = "what does this do?" Tests-first = "what should this do?" |
56
+ ```
57
+
58
+ ### Create Red Flags List
59
+
60
+ Make it easy for agents to self-check when rationalizing:
61
+
62
+ ```markdown
63
+ ## Red Flags - STOP and Start Over
64
+
65
+ - Code before test
66
+ - "I already manually tested it"
67
+ - "Tests after achieve the same purpose"
68
+ - "It's about spirit not ritual"
69
+ - "This is different because..."
70
+
71
+ **All of these mean: Delete code. Start over with TDD.**
72
+ ```
73
+
74
+ ### Update SDO for Violation Symptoms
75
+
76
+ Add to description: symptoms of when you're ABOUT to violate the rule:
77
+
78
+ ```yaml
79
+ description: use when implementing any feature or bugfix, before writing implementation code
80
+ ```
@@ -0,0 +1,201 @@
1
+ # Writing SKILL.md for Discovery
2
+
3
+ Part of superpowers:writing-skills: the SKILL.md template and how to name,
4
+ describe and size a skill so agents find it and read it.
5
+
6
+ ## SKILL.md Structure
7
+
8
+ **Frontmatter (YAML):**
9
+ - Two required fields: `name` and `description` (see [agentskills.io/specification](https://agentskills.io/specification) for all supported fields)
10
+ - Max 1024 characters total
11
+ - `name`: Use letters, numbers, and hyphens only (no parentheses, special chars)
12
+ - `description`: Third-person, describes ONLY when to use (NOT what it does)
13
+ - Start with "Use when..." to focus on triggering conditions
14
+ - Include specific symptoms, situations, and contexts
15
+ - **NEVER summarize the skill's process or workflow** (see Skill Discovery Optimization below for why)
16
+ - Keep under 500 characters if possible
17
+
18
+ ```markdown
19
+ ---
20
+ name: Skill-Name-With-Hyphens
21
+ description: Use when [specific triggering conditions and symptoms]
22
+ ---
23
+
24
+ # Skill Name
25
+
26
+ ## Overview
27
+ What is this? Core principle in 1-2 sentences.
28
+
29
+ ## When to Use
30
+ [Small inline flowchart IF decision non-obvious]
31
+
32
+ Bullet list with SYMPTOMS and use cases
33
+ When NOT to use
34
+
35
+ ## Core Pattern (for techniques/patterns)
36
+ Before/after code comparison
37
+
38
+ ## Quick Reference
39
+ Table or bullets for scanning common operations
40
+
41
+ ## Implementation
42
+ Inline code for simple patterns
43
+ Link to file for heavy reference or reusable tools
44
+
45
+ ## Common Mistakes
46
+ What goes wrong + fixes
47
+
48
+ ## Real-World Impact (optional)
49
+ Concrete results
50
+ ```
51
+
52
+
53
+ ## Skill Discovery Optimization (SDO)
54
+
55
+ **Critical for discovery:** Future agents need to FIND your skill
56
+
57
+ ### 1. Rich Description Field
58
+
59
+ **Purpose:** Your agent reads the description to decide which skills to load for a given task. Make it answer: "Should I read this skill right now?"
60
+
61
+ **Format:** Start with "Use when..." to focus on triggering conditions
62
+
63
+ **CRITICAL: Description = When to Use, NOT What the Skill Does**
64
+
65
+ The description should ONLY describe triggering conditions. Do NOT summarize the skill's process or workflow in the description.
66
+
67
+ **Why this matters:** Testing revealed that when a description summarizes the skill's workflow, an agent may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused an agent to do ONE review, even though the skill's flowchart clearly showed TWO reviews (spec compliance then code quality).
68
+
69
+ When the description was changed to just "Use when executing implementation plans with independent tasks" (no workflow summary), the agent correctly read the flowchart and followed the two-stage review process.
70
+
71
+ **The trap:** Descriptions that summarize workflow create a shortcut agents will take. The skill body becomes documentation agents skip.
72
+
73
+ ```yaml
74
+ # ❌ BAD: Summarizes workflow - agents may follow this instead of reading skill
75
+ description: Use when executing plans - dispatches subagent per task with code review between tasks
76
+
77
+ # ❌ BAD: Too much process detail
78
+ description: Use for TDD - write test first, watch it fail, write minimal code, refactor
79
+
80
+ # ✅ GOOD: Just triggering conditions, no workflow summary
81
+ description: Use when executing implementation plans with independent tasks in the current session
82
+
83
+ # ✅ GOOD: Triggering conditions only
84
+ description: Use when implementing any feature or bugfix, before writing implementation code
85
+ ```
86
+
87
+ **Content:**
88
+ - Use concrete triggers, symptoms, and situations that signal this skill applies
89
+ - Describe the *problem* (race conditions, inconsistent behavior) not *language-specific symptoms* (setTimeout, sleep)
90
+ - Keep triggers technology-agnostic unless the skill itself is technology-specific
91
+ - If skill is technology-specific, make that explicit in the trigger
92
+ - Write in third person (injected into system prompt)
93
+ - **NEVER summarize the skill's process or workflow**
94
+
95
+ ```yaml
96
+ # ❌ BAD: Too abstract, vague, doesn't include when to use
97
+ description: For async testing
98
+
99
+ # ❌ BAD: First person
100
+ description: I can help you with async tests when they're flaky
101
+
102
+ # ❌ BAD: Mentions technology but skill isn't specific to it
103
+ description: Use when tests use setTimeout/sleep and are flaky
104
+
105
+ # ✅ GOOD: Starts with "Use when", describes problem, no workflow
106
+ description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
107
+
108
+ # ✅ GOOD: Technology-specific skill with explicit trigger
109
+ description: Use when using React Router and handling authentication redirects
110
+ ```
111
+
112
+ ### 2. Keyword Coverage
113
+
114
+ Use words an agent would search for:
115
+ - Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
116
+ - Symptoms: "flaky", "hanging", "zombie", "pollution"
117
+ - Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
118
+ - Tools: Actual commands, library names, file types
119
+
120
+ ### 3. Descriptive Naming
121
+
122
+ **Use active voice, verb-first:**
123
+ - ✅ `creating-skills` not `skill-creation`
124
+ - ✅ `condition-based-waiting` not `async-test-helpers`
125
+
126
+ ### 4. Token Efficiency (Critical)
127
+
128
+ **Problem:** getting-started and frequently-referenced skills load into EVERY conversation. Every token counts.
129
+
130
+ **Target word counts:**
131
+ - getting-started workflows: <150 words each
132
+ - Frequently-loaded skills: <200 words total
133
+ - Other skills: <500 words (still be concise)
134
+
135
+ **Techniques:**
136
+
137
+ **Move details to tool help:**
138
+ ```bash
139
+ # ❌ BAD: Document all flags in SKILL.md
140
+ search-conversations supports --text, --both, --after DATE, --before DATE, --limit N
141
+
142
+ # ✅ GOOD: Reference --help
143
+ search-conversations supports multiple modes and filters. Run --help for details.
144
+ ```
145
+
146
+ **Use cross-references:**
147
+ ```markdown
148
+ # ❌ BAD: Repeat workflow details
149
+ When searching, dispatch subagent with template...
150
+ [20 lines of repeated instructions]
151
+
152
+ # ✅ GOOD: Reference other skill
153
+ Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
154
+ ```
155
+
156
+ **Compress examples:**
157
+ ```markdown
158
+ # ❌ BAD: Verbose example (42 words)
159
+ your human partner: "How did we handle authentication errors in React Router before?"
160
+ You: I'll search past conversations for React Router authentication patterns.
161
+ [Dispatch subagent with search query: "React Router authentication error handling 401"]
162
+
163
+ # ✅ GOOD: Minimal example (20 words)
164
+ Partner: "How did we handle auth errors in React Router?"
165
+ You: Searching...
166
+ [Dispatch subagent → synthesis]
167
+ ```
168
+
169
+ **Eliminate redundancy:**
170
+ - Don't repeat what's in cross-referenced skills
171
+ - Don't explain what's obvious from command
172
+ - Don't include multiple examples of same pattern
173
+
174
+ **Verification:**
175
+ ```bash
176
+ wc -w skills/path/SKILL.md
177
+ # getting-started workflows: aim for <150 each
178
+ # Other frequently-loaded: aim for <200 total
179
+ ```
180
+
181
+ **Name by what you DO or core insight:**
182
+ - ✅ `condition-based-waiting` > `async-test-helpers`
183
+ - ✅ `using-skills` not `skill-usage`
184
+ - ✅ `flatten-with-flags` > `data-structure-refactoring`
185
+ - ✅ `root-cause-tracing` > `debugging-techniques`
186
+
187
+ **Gerunds (-ing) work well for processes:**
188
+ - `creating-skills`, `testing-skills`, `debugging-with-logs`
189
+ - Active, describes the action you're taking
190
+
191
+ ### 5. Cross-Referencing Other Skills
192
+
193
+ **When writing documentation that references other skills:**
194
+
195
+ Use skill name only, with explicit requirement markers:
196
+ - ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development`
197
+ - ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging`
198
+ - ❌ Bad: `See skills/testing/test-driven-development` (unclear if required)
199
+ - ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context)
200
+
201
+ **Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them.
@@ -0,0 +1,37 @@
1
+ # Flowcharts in Skills
2
+
3
+ Part of superpowers:writing-skills.
4
+
5
+ ## Flowchart Usage
6
+
7
+ ```dot
8
+ digraph when_flowchart {
9
+ "Need to show information?" [shape=diamond];
10
+ "Decision where I might go wrong?" [shape=diamond];
11
+ "Use markdown" [shape=box];
12
+ "Small inline flowchart" [shape=box];
13
+
14
+ "Need to show information?" -> "Decision where I might go wrong?" [label="yes"];
15
+ "Decision where I might go wrong?" -> "Small inline flowchart" [label="yes"];
16
+ "Decision where I might go wrong?" -> "Use markdown" [label="no"];
17
+ }
18
+ ```
19
+
20
+ **Use flowcharts ONLY for:**
21
+ - Non-obvious decision points
22
+ - Process loops where you might stop too early
23
+ - "When to use A vs B" decisions
24
+
25
+ **Never use flowcharts for:**
26
+ - Reference material → Tables, lists
27
+ - Code examples → Markdown blocks
28
+ - Linear instructions → Numbered lists
29
+ - Labels without semantic meaning (step1, helper2)
30
+
31
+ See `graphviz-conventions.dot` in this directory for graphviz style rules.
32
+
33
+ **Visualizing for your human partner:** Use `render-graphs.js` in the writing-skills directory to render a skill's flowcharts to SVG, run from there:
34
+ ```bash
35
+ node ./render-graphs.js ../some-skill # Each diagram separately
36
+ node ./render-graphs.js ../some-skill --combine # All diagrams in one SVG
37
+ ```
@@ -0,0 +1,172 @@
1
+ digraph STYLE_GUIDE {
2
+ // The style guide for our process DSL, written in the DSL itself
3
+
4
+ // Node type examples with their shapes
5
+ subgraph cluster_node_types {
6
+ label="NODE TYPES AND SHAPES";
7
+
8
+ // Questions are diamonds
9
+ "Is this a question?" [shape=diamond];
10
+
11
+ // Actions are boxes (default)
12
+ "Take an action" [shape=box];
13
+
14
+ // Commands are plaintext
15
+ "git commit -m 'msg'" [shape=plaintext];
16
+
17
+ // States are ellipses
18
+ "Current state" [shape=ellipse];
19
+
20
+ // Warnings are octagons
21
+ "STOP: Critical warning" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
22
+
23
+ // Entry/exit are double circles
24
+ "Process starts" [shape=doublecircle];
25
+ "Process complete" [shape=doublecircle];
26
+
27
+ // Examples of each
28
+ "Is test passing?" [shape=diamond];
29
+ "Write test first" [shape=box];
30
+ "npm test" [shape=plaintext];
31
+ "I am stuck" [shape=ellipse];
32
+ "NEVER use git add -A" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
33
+ }
34
+
35
+ // Edge naming conventions
36
+ subgraph cluster_edge_types {
37
+ label="EDGE LABELS";
38
+
39
+ "Binary decision?" [shape=diamond];
40
+ "Yes path" [shape=box];
41
+ "No path" [shape=box];
42
+
43
+ "Binary decision?" -> "Yes path" [label="yes"];
44
+ "Binary decision?" -> "No path" [label="no"];
45
+
46
+ "Multiple choice?" [shape=diamond];
47
+ "Option A" [shape=box];
48
+ "Option B" [shape=box];
49
+ "Option C" [shape=box];
50
+
51
+ "Multiple choice?" -> "Option A" [label="condition A"];
52
+ "Multiple choice?" -> "Option B" [label="condition B"];
53
+ "Multiple choice?" -> "Option C" [label="otherwise"];
54
+
55
+ "Process A done" [shape=doublecircle];
56
+ "Process B starts" [shape=doublecircle];
57
+
58
+ "Process A done" -> "Process B starts" [label="triggers", style=dotted];
59
+ }
60
+
61
+ // Naming patterns
62
+ subgraph cluster_naming_patterns {
63
+ label="NAMING PATTERNS";
64
+
65
+ // Questions end with ?
66
+ "Should I do X?";
67
+ "Can this be Y?";
68
+ "Is Z true?";
69
+ "Have I done W?";
70
+
71
+ // Actions start with verb
72
+ "Write the test";
73
+ "Search for patterns";
74
+ "Commit changes";
75
+ "Ask for help";
76
+
77
+ // Commands are literal
78
+ "grep -r 'pattern' .";
79
+ "git status";
80
+ "npm run build";
81
+
82
+ // States describe situation
83
+ "Test is failing";
84
+ "Build complete";
85
+ "Stuck on error";
86
+ }
87
+
88
+ // Process structure template
89
+ subgraph cluster_structure {
90
+ label="PROCESS STRUCTURE TEMPLATE";
91
+
92
+ "Trigger: Something happens" [shape=ellipse];
93
+ "Initial check?" [shape=diamond];
94
+ "Main action" [shape=box];
95
+ "git status" [shape=plaintext];
96
+ "Another check?" [shape=diamond];
97
+ "Alternative action" [shape=box];
98
+ "STOP: Don't do this" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
99
+ "Process complete" [shape=doublecircle];
100
+
101
+ "Trigger: Something happens" -> "Initial check?";
102
+ "Initial check?" -> "Main action" [label="yes"];
103
+ "Initial check?" -> "Alternative action" [label="no"];
104
+ "Main action" -> "git status";
105
+ "git status" -> "Another check?";
106
+ "Another check?" -> "Process complete" [label="ok"];
107
+ "Another check?" -> "STOP: Don't do this" [label="problem"];
108
+ "Alternative action" -> "Process complete";
109
+ }
110
+
111
+ // When to use which shape
112
+ subgraph cluster_shape_rules {
113
+ label="WHEN TO USE EACH SHAPE";
114
+
115
+ "Choosing a shape" [shape=ellipse];
116
+
117
+ "Is it a decision?" [shape=diamond];
118
+ "Use diamond" [shape=diamond, style=filled, fillcolor=lightblue];
119
+
120
+ "Is it a command?" [shape=diamond];
121
+ "Use plaintext" [shape=plaintext, style=filled, fillcolor=lightgray];
122
+
123
+ "Is it a warning?" [shape=diamond];
124
+ "Use octagon" [shape=octagon, style=filled, fillcolor=pink];
125
+
126
+ "Is it entry/exit?" [shape=diamond];
127
+ "Use doublecircle" [shape=doublecircle, style=filled, fillcolor=lightgreen];
128
+
129
+ "Is it a state?" [shape=diamond];
130
+ "Use ellipse" [shape=ellipse, style=filled, fillcolor=lightyellow];
131
+
132
+ "Default: use box" [shape=box, style=filled, fillcolor=lightcyan];
133
+
134
+ "Choosing a shape" -> "Is it a decision?";
135
+ "Is it a decision?" -> "Use diamond" [label="yes"];
136
+ "Is it a decision?" -> "Is it a command?" [label="no"];
137
+ "Is it a command?" -> "Use plaintext" [label="yes"];
138
+ "Is it a command?" -> "Is it a warning?" [label="no"];
139
+ "Is it a warning?" -> "Use octagon" [label="yes"];
140
+ "Is it a warning?" -> "Is it entry/exit?" [label="no"];
141
+ "Is it entry/exit?" -> "Use doublecircle" [label="yes"];
142
+ "Is it entry/exit?" -> "Is it a state?" [label="no"];
143
+ "Is it a state?" -> "Use ellipse" [label="yes"];
144
+ "Is it a state?" -> "Default: use box" [label="no"];
145
+ }
146
+
147
+ // Good vs bad examples
148
+ subgraph cluster_examples {
149
+ label="GOOD VS BAD EXAMPLES";
150
+
151
+ // Good: specific and shaped correctly
152
+ "Test failed" [shape=ellipse];
153
+ "Read error message" [shape=box];
154
+ "Can reproduce?" [shape=diamond];
155
+ "git diff HEAD~1" [shape=plaintext];
156
+ "NEVER ignore errors" [shape=octagon, style=filled, fillcolor=red, fontcolor=white];
157
+
158
+ "Test failed" -> "Read error message";
159
+ "Read error message" -> "Can reproduce?";
160
+ "Can reproduce?" -> "git diff HEAD~1" [label="yes"];
161
+
162
+ // Bad: vague and wrong shapes
163
+ bad_1 [label="Something wrong", shape=box]; // Should be ellipse (state)
164
+ bad_2 [label="Fix it", shape=box]; // Too vague
165
+ bad_3 [label="Check", shape=box]; // Should be diamond
166
+ bad_4 [label="Run command", shape=box]; // Should be plaintext with actual command
167
+
168
+ bad_1 -> bad_2;
169
+ bad_2 -> bad_3;
170
+ bad_3 -> bad_4;
171
+ }
172
+ }
@@ -0,0 +1,187 @@
1
+ # Persuasion Principles for Skill Design
2
+
3
+ ## Overview
4
+
5
+ LLMs respond to the same persuasion principles as humans. Understanding this psychology helps you design more effective skills - not to manipulate, but to ensure critical practices are followed even under pressure.
6
+
7
+ **Research foundation:** Meincke et al. (2025) tested 7 persuasion principles with N=28,000 AI conversations. Persuasion techniques more than doubled compliance rates (33% → 72%, p < .001).
8
+
9
+ ## The Seven Principles
10
+
11
+ ### 1. Authority
12
+ **What it is:** Deference to expertise, credentials, or official sources.
13
+
14
+ **How it works in skills:**
15
+ - Imperative language: "YOU MUST", "Never", "Always"
16
+ - Non-negotiable framing: "No exceptions"
17
+ - Eliminates decision fatigue and rationalization
18
+
19
+ **When to use:**
20
+ - Discipline-enforcing skills (TDD, verification requirements)
21
+ - Safety-critical practices
22
+ - Established best practices
23
+
24
+ **Example:**
25
+ ```markdown
26
+ ✅ Write code before test? Delete it. Start over. No exceptions.
27
+ ❌ Consider writing tests first when feasible.
28
+ ```
29
+
30
+ ### 2. Commitment
31
+ **What it is:** Consistency with prior actions, statements, or public declarations.
32
+
33
+ **How it works in skills:**
34
+ - Require announcements: "Announce skill usage"
35
+ - Force explicit choices: "Choose A, B, or C"
36
+ - Use tracking: todos for checklists
37
+
38
+ **When to use:**
39
+ - Ensuring skills are actually followed
40
+ - Multi-step processes
41
+ - Accountability mechanisms
42
+
43
+ **Example:**
44
+ ```markdown
45
+ ✅ When you find a skill, you MUST announce: "I'm using [Skill Name]"
46
+ ❌ Consider letting your partner know which skill you're using.
47
+ ```
48
+
49
+ ### 3. Scarcity
50
+ **What it is:** Urgency from time limits or limited availability.
51
+
52
+ **How it works in skills:**
53
+ - Time-bound requirements: "Before proceeding"
54
+ - Sequential dependencies: "Immediately after X"
55
+ - Prevents procrastination
56
+
57
+ **When to use:**
58
+ - Immediate verification requirements
59
+ - Time-sensitive workflows
60
+ - Preventing "I'll do it later"
61
+
62
+ **Example:**
63
+ ```markdown
64
+ ✅ After completing a task, IMMEDIATELY request code review before proceeding.
65
+ ❌ You can review code when convenient.
66
+ ```
67
+
68
+ ### 4. Social Proof
69
+ **What it is:** Conformity to what others do or what's considered normal.
70
+
71
+ **How it works in skills:**
72
+ - Universal patterns: "Every time", "Always"
73
+ - Failure modes: "X without Y = failure"
74
+ - Establishes norms
75
+
76
+ **When to use:**
77
+ - Documenting universal practices
78
+ - Warning about common failures
79
+ - Reinforcing standards
80
+
81
+ **Example:**
82
+ ```markdown
83
+ ✅ Checklists without todo tracking = steps get skipped. Every time.
84
+ ❌ Some people find a todo list helpful for checklists.
85
+ ```
86
+
87
+ ### 5. Unity
88
+ **What it is:** Shared identity, "we-ness", in-group belonging.
89
+
90
+ **How it works in skills:**
91
+ - Collaborative language: "our codebase", "we're colleagues"
92
+ - Shared goals: "we both want quality"
93
+
94
+ **When to use:**
95
+ - Collaborative workflows
96
+ - Establishing team culture
97
+ - Non-hierarchical practices
98
+
99
+ **Example:**
100
+ ```markdown
101
+ ✅ We're colleagues working together. I need your honest technical judgment.
102
+ ❌ You should probably tell me if I'm wrong.
103
+ ```
104
+
105
+ ### 6. Reciprocity
106
+ **What it is:** Obligation to return benefits received.
107
+
108
+ **How it works:**
109
+ - Use sparingly - can feel manipulative
110
+ - Rarely needed in skills
111
+
112
+ **When to avoid:**
113
+ - Almost always (other principles more effective)
114
+
115
+ ### 7. Liking
116
+ **What it is:** Preference for cooperating with those we like.
117
+
118
+ **How it works:**
119
+ - **DON'T USE for compliance**
120
+ - Conflicts with honest feedback culture
121
+ - Creates sycophancy
122
+
123
+ **When to avoid:**
124
+ - Always for discipline enforcement
125
+
126
+ ## Principle Combinations by Skill Type
127
+
128
+ | Skill Type | Use | Avoid |
129
+ |------------|-----|-------|
130
+ | Discipline-enforcing | Authority + Commitment + Social Proof | Liking, Reciprocity |
131
+ | Guidance/technique | Moderate Authority + Unity | Heavy authority |
132
+ | Collaborative | Unity + Commitment | Authority, Liking |
133
+ | Reference | Clarity only | All persuasion |
134
+
135
+ ## Why This Works: The Psychology
136
+
137
+ **Bright-line rules reduce rationalization:**
138
+ - "YOU MUST" removes decision fatigue
139
+ - Absolute language eliminates "is this an exception?" questions
140
+ - Explicit anti-rationalization counters close specific loopholes
141
+
142
+ **Implementation intentions create automatic behavior:**
143
+ - Clear triggers + required actions = automatic execution
144
+ - "When X, do Y" more effective than "generally do Y"
145
+ - Reduces cognitive load on compliance
146
+
147
+ **LLMs are parahuman:**
148
+ - Trained on human text containing these patterns
149
+ - Authority language precedes compliance in training data
150
+ - Commitment sequences (statement → action) frequently modeled
151
+ - Social proof patterns (everyone does X) establish norms
152
+
153
+ ## Ethical Use
154
+
155
+ **Legitimate:**
156
+ - Ensuring critical practices are followed
157
+ - Creating effective documentation
158
+ - Preventing predictable failures
159
+
160
+ **Illegitimate:**
161
+ - Manipulating for personal gain
162
+ - Creating false urgency
163
+ - Guilt-based compliance
164
+
165
+ **The test:** Would this technique serve the user's genuine interests if they fully understood it?
166
+
167
+ ## Research Citations
168
+
169
+ **Cialdini, R. B. (2021).** *Influence: The Psychology of Persuasion (New and Expanded).* Harper Business.
170
+ - Seven principles of persuasion
171
+ - Empirical foundation for influence research
172
+
173
+ **Meincke, L., Shapiro, D., Duckworth, A. L., Mollick, E., Mollick, L., & Cialdini, R. (2025).** Call Me A Jerk: Persuading AI to Comply with Objectionable Requests. University of Pennsylvania.
174
+ - Tested 7 principles with N=28,000 LLM conversations
175
+ - Compliance increased 33% → 72% with persuasion techniques
176
+ - Authority, commitment, scarcity most effective
177
+ - Validates parahuman model of LLM behavior
178
+
179
+ ## Quick Reference
180
+
181
+ When designing a skill, ask:
182
+
183
+ 1. **What type is it?** (Discipline vs. guidance vs. reference)
184
+ 2. **What behavior am I trying to change?**
185
+ 3. **Which principle(s) apply?** (Usually authority + commitment for discipline)
186
+ 4. **Am I combining too many?** (Don't use all seven)
187
+ 5. **Is this ethical?** (Serves user's genuine interests?)