@dtt_siye/atool 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 (463) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +235 -0
  3. package/VERSION +1 -0
  4. package/agents/code-reviewer.md +29 -0
  5. package/bin/atool.js +235 -0
  6. package/bin/postinstall.js +23 -0
  7. package/hooks/doc-sync-reminder +155 -0
  8. package/hooks/hooks-cursor.json +37 -0
  9. package/hooks/hooks.json +37 -0
  10. package/hooks/prompt-guard +135 -0
  11. package/hooks/session-start +286 -0
  12. package/install.sh +603 -0
  13. package/lib/analyze-source.sh +1265 -0
  14. package/lib/common.sh +1041 -0
  15. package/lib/compute-importance.sh +598 -0
  16. package/lib/detect-stack.sh +354 -0
  17. package/lib/generate-visualization.sh +266 -0
  18. package/lib/install-claude.sh +43 -0
  19. package/lib/install-cursor.sh +281 -0
  20. package/lib/install-hooks.sh +285 -0
  21. package/lib/install-kiro.sh +543 -0
  22. package/lib/install-mcp.sh +99 -0
  23. package/lib/install-skills.sh +129 -0
  24. package/lib/knowledge-graph.sh +1014 -0
  25. package/lib/multi-dimensional-analysis.sh +413 -0
  26. package/lib/pre-scan.sh +1045 -0
  27. package/lib/project-init.sh +552 -0
  28. package/lib/visualization-template.html +545 -0
  29. package/mcp/recommended.json +24 -0
  30. package/package.json +39 -0
  31. package/skills/_superpowers/.claude-plugin/marketplace.json +20 -0
  32. package/skills/_superpowers/.claude-plugin/plugin.json +20 -0
  33. package/skills/_superpowers/.codex/INSTALL.md +67 -0
  34. package/skills/_superpowers/.cursor-plugin/plugin.json +25 -0
  35. package/skills/_superpowers/.gitattributes +18 -0
  36. package/skills/_superpowers/.github/FUNDING.yml +3 -0
  37. package/skills/_superpowers/.github/ISSUE_TEMPLATE/bug_report.md +52 -0
  38. package/skills/_superpowers/.github/ISSUE_TEMPLATE/config.yml +5 -0
  39. package/skills/_superpowers/.github/ISSUE_TEMPLATE/feature_request.md +34 -0
  40. package/skills/_superpowers/.github/ISSUE_TEMPLATE/platform_support.md +23 -0
  41. package/skills/_superpowers/.github/PULL_REQUEST_TEMPLATE.md +87 -0
  42. package/skills/_superpowers/.opencode/INSTALL.md +83 -0
  43. package/skills/_superpowers/.opencode/plugins/superpowers.js +107 -0
  44. package/skills/_superpowers/CHANGELOG.md +13 -0
  45. package/skills/_superpowers/CODE_OF_CONDUCT.md +128 -0
  46. package/skills/_superpowers/GEMINI.md +2 -0
  47. package/skills/_superpowers/LICENSE +21 -0
  48. package/skills/_superpowers/README.md +187 -0
  49. package/skills/_superpowers/RELEASE-NOTES.md +1083 -0
  50. package/skills/_superpowers/agents/code-reviewer.md +48 -0
  51. package/skills/_superpowers/commands/brainstorm.md +5 -0
  52. package/skills/_superpowers/commands/execute-plan.md +5 -0
  53. package/skills/_superpowers/commands/write-plan.md +5 -0
  54. package/skills/_superpowers/docs/README.codex.md +126 -0
  55. package/skills/_superpowers/docs/README.opencode.md +130 -0
  56. package/skills/_superpowers/docs/plans/2025-11-22-opencode-support-design.md +294 -0
  57. package/skills/_superpowers/docs/plans/2025-11-22-opencode-support-implementation.md +1095 -0
  58. package/skills/_superpowers/docs/plans/2025-11-28-skills-improvements-from-user-feedback.md +711 -0
  59. package/skills/_superpowers/docs/plans/2026-01-17-visual-brainstorming.md +571 -0
  60. package/skills/_superpowers/docs/superpowers/plans/2026-01-22-document-review-system.md +301 -0
  61. package/skills/_superpowers/docs/superpowers/plans/2026-02-19-visual-brainstorming-refactor.md +523 -0
  62. package/skills/_superpowers/docs/superpowers/plans/2026-03-11-zero-dep-brainstorm-server.md +479 -0
  63. package/skills/_superpowers/docs/superpowers/plans/2026-03-23-codex-app-compatibility.md +564 -0
  64. package/skills/_superpowers/docs/superpowers/specs/2026-01-22-document-review-system-design.md +136 -0
  65. package/skills/_superpowers/docs/superpowers/specs/2026-02-19-visual-brainstorming-refactor-design.md +162 -0
  66. package/skills/_superpowers/docs/superpowers/specs/2026-03-11-zero-dep-brainstorm-server-design.md +118 -0
  67. package/skills/_superpowers/docs/superpowers/specs/2026-03-23-codex-app-compatibility-design.md +244 -0
  68. package/skills/_superpowers/docs/testing.md +303 -0
  69. package/skills/_superpowers/docs/windows/polyglot-hooks.md +212 -0
  70. package/skills/_superpowers/gemini-extension.json +6 -0
  71. package/skills/_superpowers/hooks/hooks-cursor.json +10 -0
  72. package/skills/_superpowers/hooks/hooks.json +16 -0
  73. package/skills/_superpowers/hooks/run-hook.cmd +46 -0
  74. package/skills/_superpowers/hooks/session-start +57 -0
  75. package/skills/_superpowers/package.json +6 -0
  76. package/skills/_superpowers/skills/brainstorming/SKILL.md +164 -0
  77. package/skills/_superpowers/skills/brainstorming/scripts/frame-template.html +214 -0
  78. package/skills/_superpowers/skills/brainstorming/scripts/helper.js +88 -0
  79. package/skills/_superpowers/skills/brainstorming/scripts/server.cjs +354 -0
  80. package/skills/_superpowers/skills/brainstorming/scripts/start-server.sh +148 -0
  81. package/skills/_superpowers/skills/brainstorming/scripts/stop-server.sh +56 -0
  82. package/skills/_superpowers/skills/brainstorming/spec-document-reviewer-prompt.md +49 -0
  83. package/skills/_superpowers/skills/brainstorming/visual-companion.md +287 -0
  84. package/skills/_superpowers/skills/dispatching-parallel-agents/SKILL.md +182 -0
  85. package/skills/_superpowers/skills/executing-plans/SKILL.md +70 -0
  86. package/skills/_superpowers/skills/finishing-a-development-branch/SKILL.md +200 -0
  87. package/skills/_superpowers/skills/receiving-code-review/SKILL.md +213 -0
  88. package/skills/_superpowers/skills/requesting-code-review/SKILL.md +105 -0
  89. package/skills/_superpowers/skills/requesting-code-review/code-reviewer.md +146 -0
  90. package/skills/_superpowers/skills/subagent-driven-development/SKILL.md +277 -0
  91. package/skills/_superpowers/skills/subagent-driven-development/code-quality-reviewer-prompt.md +26 -0
  92. package/skills/_superpowers/skills/subagent-driven-development/implementer-prompt.md +113 -0
  93. package/skills/_superpowers/skills/subagent-driven-development/spec-reviewer-prompt.md +61 -0
  94. package/skills/_superpowers/skills/systematic-debugging/CREATION-LOG.md +119 -0
  95. package/skills/_superpowers/skills/systematic-debugging/SKILL.md +296 -0
  96. package/skills/_superpowers/skills/systematic-debugging/condition-based-waiting-example.ts +158 -0
  97. package/skills/_superpowers/skills/systematic-debugging/condition-based-waiting.md +115 -0
  98. package/skills/_superpowers/skills/systematic-debugging/defense-in-depth.md +122 -0
  99. package/skills/_superpowers/skills/systematic-debugging/find-polluter.sh +63 -0
  100. package/skills/_superpowers/skills/systematic-debugging/root-cause-tracing.md +169 -0
  101. package/skills/_superpowers/skills/systematic-debugging/test-academic.md +14 -0
  102. package/skills/_superpowers/skills/systematic-debugging/test-pressure-1.md +58 -0
  103. package/skills/_superpowers/skills/systematic-debugging/test-pressure-2.md +68 -0
  104. package/skills/_superpowers/skills/systematic-debugging/test-pressure-3.md +69 -0
  105. package/skills/_superpowers/skills/test-driven-development/SKILL.md +371 -0
  106. package/skills/_superpowers/skills/test-driven-development/testing-anti-patterns.md +299 -0
  107. package/skills/_superpowers/skills/using-git-worktrees/SKILL.md +218 -0
  108. package/skills/_superpowers/skills/using-superpowers/SKILL.md +115 -0
  109. package/skills/_superpowers/skills/using-superpowers/references/codex-tools.md +100 -0
  110. package/skills/_superpowers/skills/using-superpowers/references/gemini-tools.md +33 -0
  111. package/skills/_superpowers/skills/verification-before-completion/SKILL.md +139 -0
  112. package/skills/_superpowers/skills/writing-plans/SKILL.md +152 -0
  113. package/skills/_superpowers/skills/writing-plans/plan-document-reviewer-prompt.md +49 -0
  114. package/skills/_superpowers/skills/writing-skills/SKILL.md +655 -0
  115. package/skills/_superpowers/skills/writing-skills/anthropic-best-practices.md +1150 -0
  116. package/skills/_superpowers/skills/writing-skills/examples/CLAUDE_MD_TESTING.md +189 -0
  117. package/skills/_superpowers/skills/writing-skills/graphviz-conventions.dot +172 -0
  118. package/skills/_superpowers/skills/writing-skills/persuasion-principles.md +187 -0
  119. package/skills/_superpowers/skills/writing-skills/render-graphs.js +168 -0
  120. package/skills/_superpowers/skills/writing-skills/testing-skills-with-subagents.md +384 -0
  121. package/skills/_superpowers/tests/brainstorm-server/package-lock.json +36 -0
  122. package/skills/_superpowers/tests/brainstorm-server/package.json +10 -0
  123. package/skills/_superpowers/tests/brainstorm-server/server.test.js +427 -0
  124. package/skills/_superpowers/tests/brainstorm-server/windows-lifecycle.test.sh +351 -0
  125. package/skills/_superpowers/tests/brainstorm-server/ws-protocol.test.js +392 -0
  126. package/skills/_superpowers/tests/claude-code/README.md +158 -0
  127. package/skills/_superpowers/tests/claude-code/analyze-token-usage.py +168 -0
  128. package/skills/_superpowers/tests/claude-code/run-skill-tests.sh +187 -0
  129. package/skills/_superpowers/tests/claude-code/test-document-review-system.sh +177 -0
  130. package/skills/_superpowers/tests/claude-code/test-helpers.sh +202 -0
  131. package/skills/_superpowers/tests/claude-code/test-subagent-driven-development-integration.sh +314 -0
  132. package/skills/_superpowers/tests/claude-code/test-subagent-driven-development.sh +165 -0
  133. package/skills/_superpowers/tests/explicit-skill-requests/prompts/action-oriented.txt +3 -0
  134. package/skills/_superpowers/tests/explicit-skill-requests/prompts/after-planning-flow.txt +17 -0
  135. package/skills/_superpowers/tests/explicit-skill-requests/prompts/claude-suggested-it.txt +11 -0
  136. package/skills/_superpowers/tests/explicit-skill-requests/prompts/i-know-what-sdd-means.txt +8 -0
  137. package/skills/_superpowers/tests/explicit-skill-requests/prompts/mid-conversation-execute-plan.txt +3 -0
  138. package/skills/_superpowers/tests/explicit-skill-requests/prompts/please-use-brainstorming.txt +1 -0
  139. package/skills/_superpowers/tests/explicit-skill-requests/prompts/skip-formalities.txt +3 -0
  140. package/skills/_superpowers/tests/explicit-skill-requests/prompts/subagent-driven-development-please.txt +1 -0
  141. package/skills/_superpowers/tests/explicit-skill-requests/prompts/use-systematic-debugging.txt +1 -0
  142. package/skills/_superpowers/tests/explicit-skill-requests/run-all.sh +70 -0
  143. package/skills/_superpowers/tests/explicit-skill-requests/run-claude-describes-sdd.sh +100 -0
  144. package/skills/_superpowers/tests/explicit-skill-requests/run-extended-multiturn-test.sh +113 -0
  145. package/skills/_superpowers/tests/explicit-skill-requests/run-haiku-test.sh +144 -0
  146. package/skills/_superpowers/tests/explicit-skill-requests/run-multiturn-test.sh +143 -0
  147. package/skills/_superpowers/tests/explicit-skill-requests/run-test.sh +136 -0
  148. package/skills/_superpowers/tests/opencode/run-tests.sh +163 -0
  149. package/skills/_superpowers/tests/opencode/setup.sh +73 -0
  150. package/skills/_superpowers/tests/opencode/test-plugin-loading.sh +72 -0
  151. package/skills/_superpowers/tests/opencode/test-priority.sh +198 -0
  152. package/skills/_superpowers/tests/opencode/test-tools.sh +104 -0
  153. package/skills/_superpowers/tests/skill-triggering/prompts/dispatching-parallel-agents.txt +8 -0
  154. package/skills/_superpowers/tests/skill-triggering/prompts/executing-plans.txt +1 -0
  155. package/skills/_superpowers/tests/skill-triggering/prompts/requesting-code-review.txt +3 -0
  156. package/skills/_superpowers/tests/skill-triggering/prompts/systematic-debugging.txt +11 -0
  157. package/skills/_superpowers/tests/skill-triggering/prompts/test-driven-development.txt +7 -0
  158. package/skills/_superpowers/tests/skill-triggering/prompts/writing-plans.txt +10 -0
  159. package/skills/_superpowers/tests/skill-triggering/run-all.sh +60 -0
  160. package/skills/_superpowers/tests/skill-triggering/run-test.sh +88 -0
  161. package/skills/_superpowers/tests/subagent-driven-dev/go-fractals/design.md +81 -0
  162. package/skills/_superpowers/tests/subagent-driven-dev/go-fractals/plan.md +172 -0
  163. package/skills/_superpowers/tests/subagent-driven-dev/go-fractals/scaffold.sh +45 -0
  164. package/skills/_superpowers/tests/subagent-driven-dev/run-test.sh +106 -0
  165. package/skills/_superpowers/tests/subagent-driven-dev/svelte-todo/design.md +70 -0
  166. package/skills/_superpowers/tests/subagent-driven-dev/svelte-todo/plan.md +222 -0
  167. package/skills/_superpowers/tests/subagent-driven-dev/svelte-todo/scaffold.sh +46 -0
  168. package/skills/ai-project-architecture/SKILL.md +632 -0
  169. package/skills/ai-project-architecture/reference/structure-rules.md +406 -0
  170. package/skills/ai-project-architecture/templates/compliance-report.md +300 -0
  171. package/skills/ai-project-architecture/templates/migration-plan.md +433 -0
  172. package/skills/ai-project-architecture/templates/verification-checklist.md +408 -0
  173. package/skills/android-conventions/SKILL.md +125 -0
  174. package/skills/atool-init/SKILL.md +141 -0
  175. package/skills/clarify-before-build/SKILL.md +107 -0
  176. package/skills/code-review/SKILL.md +406 -0
  177. package/skills/code-review/rules/architecture.md +285 -0
  178. package/skills/code-review/rules/coupling-cohesion.md +309 -0
  179. package/skills/code-review/rules/dead-code.md +115 -0
  180. package/skills/code-review/rules/deprecation-debt.md +279 -0
  181. package/skills/code-review/rules/duplication.md +104 -0
  182. package/skills/code-review/rules/error-security.md +143 -0
  183. package/skills/code-review/rules/maintainability.md +203 -0
  184. package/skills/code-review/rules/quality.md +158 -0
  185. package/skills/devops-conventions/SKILL.md +205 -0
  186. package/skills/doc-coauthoring/SKILL.md +392 -0
  187. package/skills/doc-standards-enforcer/SKILL.md +290 -0
  188. package/skills/doc-standards-enforcer/examples/valid-document-example.md +67 -0
  189. package/skills/doc-standards-enforcer/references/101-standards-summary.md +318 -0
  190. package/skills/doc-standards-enforcer/scripts/check_references.py +175 -0
  191. package/skills/doc-standards-enforcer/scripts/fix_common_issues.py +303 -0
  192. package/skills/doc-standards-enforcer/scripts/validate_doc_standards.py +332 -0
  193. package/skills/docx/LICENSE.txt +30 -0
  194. package/skills/docx/SKILL.md +200 -0
  195. package/skills/docx/docx-js.md +350 -0
  196. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-chart.xsd +1499 -0
  197. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd +146 -0
  198. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd +1085 -0
  199. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd +11 -0
  200. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-main.xsd +3081 -0
  201. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-picture.xsd +23 -0
  202. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd +185 -0
  203. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd +287 -0
  204. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/pml.xsd +1676 -0
  205. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd +28 -0
  206. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd +144 -0
  207. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd +174 -0
  208. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd +25 -0
  209. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd +18 -0
  210. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd +59 -0
  211. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd +56 -0
  212. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd +195 -0
  213. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-math.xsd +582 -0
  214. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd +25 -0
  215. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/sml.xsd +4439 -0
  216. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/vml-main.xsd +570 -0
  217. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd +509 -0
  218. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd +12 -0
  219. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd +108 -0
  220. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd +96 -0
  221. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/wml.xsd +3646 -0
  222. package/skills/docx/ooxml/schemas/ISO-IEC29500-4_2016/xml.xsd +116 -0
  223. package/skills/docx/ooxml/schemas/ecma/fouth-edition/opc-contentTypes.xsd +42 -0
  224. package/skills/docx/ooxml/schemas/ecma/fouth-edition/opc-coreProperties.xsd +50 -0
  225. package/skills/docx/ooxml/schemas/ecma/fouth-edition/opc-digSig.xsd +49 -0
  226. package/skills/docx/ooxml/schemas/ecma/fouth-edition/opc-relationships.xsd +33 -0
  227. package/skills/docx/ooxml/schemas/mce/mc.xsd +75 -0
  228. package/skills/docx/ooxml/schemas/microsoft/wml-2010.xsd +560 -0
  229. package/skills/docx/ooxml/schemas/microsoft/wml-2012.xsd +67 -0
  230. package/skills/docx/ooxml/schemas/microsoft/wml-2018.xsd +14 -0
  231. package/skills/docx/ooxml/schemas/microsoft/wml-cex-2018.xsd +20 -0
  232. package/skills/docx/ooxml/schemas/microsoft/wml-cid-2016.xsd +13 -0
  233. package/skills/docx/ooxml/schemas/microsoft/wml-sdtdatahash-2020.xsd +4 -0
  234. package/skills/docx/ooxml/schemas/microsoft/wml-symex-2015.xsd +8 -0
  235. package/skills/docx/ooxml/scripts/pack.py +159 -0
  236. package/skills/docx/ooxml/scripts/unpack.py +29 -0
  237. package/skills/docx/ooxml/scripts/validate.py +69 -0
  238. package/skills/docx/ooxml/scripts/validation/__init__.py +15 -0
  239. package/skills/docx/ooxml/scripts/validation/base.py +951 -0
  240. package/skills/docx/ooxml/scripts/validation/docx.py +274 -0
  241. package/skills/docx/ooxml/scripts/validation/pptx.py +315 -0
  242. package/skills/docx/ooxml/scripts/validation/redlining.py +279 -0
  243. package/skills/docx/ooxml.md +610 -0
  244. package/skills/docx/scripts/__init__.py +1 -0
  245. package/skills/docx/scripts/document.py +1276 -0
  246. package/skills/docx/scripts/templates/comments.xml +3 -0
  247. package/skills/docx/scripts/templates/commentsExtended.xml +3 -0
  248. package/skills/docx/scripts/templates/commentsExtensible.xml +3 -0
  249. package/skills/docx/scripts/templates/commentsIds.xml +3 -0
  250. package/skills/docx/scripts/templates/people.xml +3 -0
  251. package/skills/docx/scripts/utilities.py +374 -0
  252. package/skills/flutter-conventions/SKILL.md +70 -0
  253. package/skills/go-conventions/SKILL.md +230 -0
  254. package/skills/harmony-conventions/SKILL.md +156 -0
  255. package/skills/java-conventions/SKILL.md +277 -0
  256. package/skills/pdf/LICENSE.txt +30 -0
  257. package/skills/pdf/SKILL.md +297 -0
  258. package/skills/pdf/forms.md +205 -0
  259. package/skills/pdf/reference.md +612 -0
  260. package/skills/pdf/scripts/check_bounding_boxes.py +70 -0
  261. package/skills/pdf/scripts/check_bounding_boxes_test.py +226 -0
  262. package/skills/pdf/scripts/check_fillable_fields.py +12 -0
  263. package/skills/pdf/scripts/convert_pdf_to_images.py +35 -0
  264. package/skills/pdf/scripts/create_validation_image.py +41 -0
  265. package/skills/pdf/scripts/extract_form_field_info.py +152 -0
  266. package/skills/pdf/scripts/fill_fillable_fields.py +114 -0
  267. package/skills/pdf/scripts/fill_pdf_form_with_annotations.py +108 -0
  268. package/skills/pptx/LICENSE.txt +30 -0
  269. package/skills/pptx/SKILL.md +487 -0
  270. package/skills/pptx/html2pptx.md +625 -0
  271. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/dml-chart.xsd +1499 -0
  272. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/dml-chartDrawing.xsd +146 -0
  273. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/dml-diagram.xsd +1085 -0
  274. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/dml-lockedCanvas.xsd +11 -0
  275. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/dml-main.xsd +3081 -0
  276. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/dml-picture.xsd +23 -0
  277. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/dml-spreadsheetDrawing.xsd +185 -0
  278. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/dml-wordprocessingDrawing.xsd +287 -0
  279. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/pml.xsd +1676 -0
  280. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/shared-additionalCharacteristics.xsd +28 -0
  281. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/shared-bibliography.xsd +144 -0
  282. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/shared-commonSimpleTypes.xsd +174 -0
  283. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/shared-customXmlDataProperties.xsd +25 -0
  284. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/shared-customXmlSchemaProperties.xsd +18 -0
  285. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesCustom.xsd +59 -0
  286. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesExtended.xsd +56 -0
  287. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/shared-documentPropertiesVariantTypes.xsd +195 -0
  288. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/shared-math.xsd +582 -0
  289. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/shared-relationshipReference.xsd +25 -0
  290. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/sml.xsd +4439 -0
  291. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/vml-main.xsd +570 -0
  292. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/vml-officeDrawing.xsd +509 -0
  293. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/vml-presentationDrawing.xsd +12 -0
  294. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/vml-spreadsheetDrawing.xsd +108 -0
  295. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/vml-wordprocessingDrawing.xsd +96 -0
  296. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/wml.xsd +3646 -0
  297. package/skills/pptx/ooxml/schemas/ISO-IEC29500-4_2016/xml.xsd +116 -0
  298. package/skills/pptx/ooxml/schemas/ecma/fouth-edition/opc-contentTypes.xsd +42 -0
  299. package/skills/pptx/ooxml/schemas/ecma/fouth-edition/opc-coreProperties.xsd +50 -0
  300. package/skills/pptx/ooxml/schemas/ecma/fouth-edition/opc-digSig.xsd +49 -0
  301. package/skills/pptx/ooxml/schemas/ecma/fouth-edition/opc-relationships.xsd +33 -0
  302. package/skills/pptx/ooxml/schemas/mce/mc.xsd +75 -0
  303. package/skills/pptx/ooxml/schemas/microsoft/wml-2010.xsd +560 -0
  304. package/skills/pptx/ooxml/schemas/microsoft/wml-2012.xsd +67 -0
  305. package/skills/pptx/ooxml/schemas/microsoft/wml-2018.xsd +14 -0
  306. package/skills/pptx/ooxml/schemas/microsoft/wml-cex-2018.xsd +20 -0
  307. package/skills/pptx/ooxml/schemas/microsoft/wml-cid-2016.xsd +13 -0
  308. package/skills/pptx/ooxml/schemas/microsoft/wml-sdtdatahash-2020.xsd +4 -0
  309. package/skills/pptx/ooxml/schemas/microsoft/wml-symex-2015.xsd +8 -0
  310. package/skills/pptx/ooxml/scripts/pack.py +159 -0
  311. package/skills/pptx/ooxml/scripts/unpack.py +29 -0
  312. package/skills/pptx/ooxml/scripts/validate.py +69 -0
  313. package/skills/pptx/ooxml/scripts/validation/__init__.py +15 -0
  314. package/skills/pptx/ooxml/scripts/validation/base.py +951 -0
  315. package/skills/pptx/ooxml/scripts/validation/docx.py +274 -0
  316. package/skills/pptx/ooxml/scripts/validation/pptx.py +315 -0
  317. package/skills/pptx/ooxml/scripts/validation/redlining.py +279 -0
  318. package/skills/pptx/ooxml.md +427 -0
  319. package/skills/pptx/scripts/html2pptx.js +979 -0
  320. package/skills/pptx/scripts/inventory.py +1020 -0
  321. package/skills/pptx/scripts/rearrange.py +231 -0
  322. package/skills/pptx/scripts/replace.py +385 -0
  323. package/skills/pptx/scripts/thumbnail.py +450 -0
  324. package/skills/project-analyze/SKILL.md +270 -0
  325. package/skills/project-analyze/phases/phase0-discovery.md +278 -0
  326. package/skills/project-analyze/phases/phase0.5-prescan.md +139 -0
  327. package/skills/project-analyze/phases/phase1-inventory.md +94 -0
  328. package/skills/project-analyze/phases/phase2-deep-analysis.md +249 -0
  329. package/skills/project-analyze/phases/phase2a-l4-analysis.md +94 -0
  330. package/skills/project-analyze/phases/phase2b-l5-analysis.md +97 -0
  331. package/skills/project-analyze/phases/phase3-knowledge-graph.md +120 -0
  332. package/skills/project-analyze/phases/phase3a-multi-dimensional.md +61 -0
  333. package/skills/project-analyze/phases/phase4-code-quality.md +81 -0
  334. package/skills/project-analyze/phases/phase5-synthesis.md +284 -0
  335. package/skills/project-analyze/phases/phase6-validation.md +179 -0
  336. package/skills/project-analyze/prompts/code-review-agent.md +122 -0
  337. package/skills/project-analyze/prompts/deep-analysis-agent.md +107 -0
  338. package/skills/project-analyze/prompts/inventory-agent.md +67 -0
  339. package/skills/project-analyze/prompts/l4-analysis-agent.md +98 -0
  340. package/skills/project-analyze/rules/android.md +282 -0
  341. package/skills/project-analyze/rules/devops.md +443 -0
  342. package/skills/project-analyze/rules/generic.md +243 -0
  343. package/skills/project-analyze/rules/go.md +289 -0
  344. package/skills/project-analyze/rules/harmony.md +257 -0
  345. package/skills/project-analyze/rules/java.md +507 -0
  346. package/skills/project-analyze/rules/mobile-flutter.md +315 -0
  347. package/skills/project-analyze/rules/mobile-react-native.md +283 -0
  348. package/skills/project-analyze/rules/mobile-swift.md +323 -0
  349. package/skills/project-analyze/rules/python.md +317 -0
  350. package/skills/project-analyze/rules/rust-tauri.md +243 -0
  351. package/skills/project-analyze/rules/rust.md +296 -0
  352. package/skills/project-analyze/rules/web-nextjs.md +364 -0
  353. package/skills/project-analyze/rules/web-react.md +298 -0
  354. package/skills/project-analyze/rules/web-vue.md +378 -0
  355. package/skills/project-analyze/rules/web.md +390 -0
  356. package/skills/project-query/SKILL.md +224 -0
  357. package/skills/project-query/rules/query-templates.md +212 -0
  358. package/skills/python-conventions/SKILL.md +169 -0
  359. package/skills/react-native-conventions/SKILL.md +73 -0
  360. package/skills/requirements-writer/README.md +153 -0
  361. package/skills/requirements-writer/SKILL.md +341 -0
  362. package/skills/requirements-writer/examples/prd-outline-example.md +217 -0
  363. package/skills/requirements-writer/templates/module-prd-template.md +362 -0
  364. package/skills/requirements-writer/templates/prd-outline-template.md +185 -0
  365. package/skills/requirements-writer/templates/user-story-template.md +1125 -0
  366. package/skills/rust-conventions/SKILL.md +361 -0
  367. package/skills/smart-dispatch/SKILL.md +296 -0
  368. package/skills/smart-dispatch/implementer-prompt.md +146 -0
  369. package/skills/smart-dispatch/reviewer-prompt.md +199 -0
  370. package/skills/software-architecture/SKILL.md +278 -0
  371. package/skills/swift-conventions/SKILL.md +72 -0
  372. package/skills/ui-ux-pro/SKILL.md +140 -0
  373. package/skills/verification-before-completion/SKILL.md +119 -0
  374. package/skills/web-conventions/SKILL.md +259 -0
  375. package/skills/webapp-testing/LICENSE.txt +202 -0
  376. package/skills/webapp-testing/SKILL.md +97 -0
  377. package/skills/webapp-testing/examples/console_logging.py +35 -0
  378. package/skills/webapp-testing/examples/element_discovery.py +40 -0
  379. package/skills/webapp-testing/examples/static_html_automation.py +33 -0
  380. package/skills/webapp-testing/scripts/with_server.py +106 -0
  381. package/skills/writing-plans/SKILL.md +144 -0
  382. package/skills/xlsx/LICENSE.txt +30 -0
  383. package/skills/xlsx/SKILL.md +292 -0
  384. package/skills/xlsx/recalc.py +178 -0
  385. package/templates/CLAUDE.md.android +57 -0
  386. package/templates/CLAUDE.md.devops +50 -0
  387. package/templates/CLAUDE.md.generic +34 -0
  388. package/templates/CLAUDE.md.go +67 -0
  389. package/templates/CLAUDE.md.harmony +54 -0
  390. package/templates/CLAUDE.md.java +56 -0
  391. package/templates/CLAUDE.md.mobile-flutter +38 -0
  392. package/templates/CLAUDE.md.mobile-react-native +37 -0
  393. package/templates/CLAUDE.md.mobile-swift +40 -0
  394. package/templates/CLAUDE.md.python +65 -0
  395. package/templates/CLAUDE.md.rust +68 -0
  396. package/templates/CLAUDE.md.rust-tauri +120 -0
  397. package/templates/CLAUDE.md.web +63 -0
  398. package/templates/COMPONENT.md.android +58 -0
  399. package/templates/COMPONENT.md.devops +54 -0
  400. package/templates/COMPONENT.md.generic +35 -0
  401. package/templates/COMPONENT.md.go +59 -0
  402. package/templates/COMPONENT.md.harmony +63 -0
  403. package/templates/COMPONENT.md.java +69 -0
  404. package/templates/COMPONENT.md.mobile-flutter +56 -0
  405. package/templates/COMPONENT.md.mobile-react-native +55 -0
  406. package/templates/COMPONENT.md.mobile-swift +56 -0
  407. package/templates/COMPONENT.md.python +67 -0
  408. package/templates/COMPONENT.md.rust +57 -0
  409. package/templates/COMPONENT.md.rust-tauri +66 -0
  410. package/templates/COMPONENT.md.web +39 -0
  411. package/templates/README.md.android +71 -0
  412. package/templates/README.md.devops +68 -0
  413. package/templates/README.md.generic +39 -0
  414. package/templates/README.md.go +70 -0
  415. package/templates/README.md.harmony +72 -0
  416. package/templates/README.md.java +73 -0
  417. package/templates/README.md.mobile-flutter +69 -0
  418. package/templates/README.md.mobile-react-native +65 -0
  419. package/templates/README.md.mobile-swift +69 -0
  420. package/templates/README.md.monorepo +59 -0
  421. package/templates/README.md.python +66 -0
  422. package/templates/README.md.rust +69 -0
  423. package/templates/README.md.rust-tauri +149 -0
  424. package/templates/README.md.web +94 -0
  425. package/templates/UI_STYLE.md.android +74 -0
  426. package/templates/UI_STYLE.md.devops +50 -0
  427. package/templates/UI_STYLE.md.generic +31 -0
  428. package/templates/UI_STYLE.md.go +49 -0
  429. package/templates/UI_STYLE.md.harmony +71 -0
  430. package/templates/UI_STYLE.md.java +61 -0
  431. package/templates/UI_STYLE.md.mobile-flutter +70 -0
  432. package/templates/UI_STYLE.md.mobile-react-native +71 -0
  433. package/templates/UI_STYLE.md.mobile-swift +71 -0
  434. package/templates/UI_STYLE.md.python +58 -0
  435. package/templates/UI_STYLE.md.rust +52 -0
  436. package/templates/UI_STYLE.md.rust-tauri +102 -0
  437. package/templates/UI_STYLE.md.web +92 -0
  438. package/templates/cursor-rules.android.mdc +33 -0
  439. package/templates/cursor-rules.devops.mdc +32 -0
  440. package/templates/cursor-rules.generic.mdc +25 -0
  441. package/templates/cursor-rules.go.mdc +34 -0
  442. package/templates/cursor-rules.harmony.mdc +30 -0
  443. package/templates/cursor-rules.java.mdc +30 -0
  444. package/templates/cursor-rules.mobile-flutter.mdc +42 -0
  445. package/templates/cursor-rules.mobile-react-native.mdc +43 -0
  446. package/templates/cursor-rules.mobile-swift.mdc +42 -0
  447. package/templates/cursor-rules.python.mdc +33 -0
  448. package/templates/cursor-rules.rust-tauri.mdc +67 -0
  449. package/templates/cursor-rules.rust.mdc +30 -0
  450. package/templates/cursor-rules.web.mdc +30 -0
  451. package/templates/kiro-steering.android.md +39 -0
  452. package/templates/kiro-steering.devops.md +32 -0
  453. package/templates/kiro-steering.generic.md +28 -0
  454. package/templates/kiro-steering.go.md +41 -0
  455. package/templates/kiro-steering.harmony.md +36 -0
  456. package/templates/kiro-steering.java.md +37 -0
  457. package/templates/kiro-steering.mobile-flutter.md +73 -0
  458. package/templates/kiro-steering.mobile-react-native.md +71 -0
  459. package/templates/kiro-steering.mobile-swift.md +62 -0
  460. package/templates/kiro-steering.python.md +34 -0
  461. package/templates/kiro-steering.rust-tauri.md +50 -0
  462. package/templates/kiro-steering.rust.md +36 -0
  463. package/templates/kiro-steering.web.md +41 -0
@@ -0,0 +1,303 @@
1
+ # Testing Superpowers Skills
2
+
3
+ This document describes how to test Superpowers skills, particularly the integration tests for complex skills like `subagent-driven-development`.
4
+
5
+ ## Overview
6
+
7
+ Testing skills that involve subagents, workflows, and complex interactions requires running actual Claude Code sessions in headless mode and verifying their behavior through session transcripts.
8
+
9
+ ## Test Structure
10
+
11
+ ```
12
+ tests/
13
+ ├── claude-code/
14
+ │ ├── test-helpers.sh # Shared test utilities
15
+ │ ├── test-subagent-driven-development-integration.sh
16
+ │ ├── analyze-token-usage.py # Token analysis tool
17
+ │ └── run-skill-tests.sh # Test runner (if exists)
18
+ ```
19
+
20
+ ## Running Tests
21
+
22
+ ### Integration Tests
23
+
24
+ Integration tests execute real Claude Code sessions with actual skills:
25
+
26
+ ```bash
27
+ # Run the subagent-driven-development integration test
28
+ cd tests/claude-code
29
+ ./test-subagent-driven-development-integration.sh
30
+ ```
31
+
32
+ **Note:** Integration tests can take 10-30 minutes as they execute real implementation plans with multiple subagents.
33
+
34
+ ### Requirements
35
+
36
+ - Must run from the **superpowers plugin directory** (not from temp directories)
37
+ - Claude Code must be installed and available as `claude` command
38
+ - Local dev marketplace must be enabled: `"superpowers@superpowers-dev": true` in `~/.claude/settings.json`
39
+
40
+ ## Integration Test: subagent-driven-development
41
+
42
+ ### What It Tests
43
+
44
+ The integration test verifies the `subagent-driven-development` skill correctly:
45
+
46
+ 1. **Plan Loading**: Reads the plan once at the beginning
47
+ 2. **Full Task Text**: Provides complete task descriptions to subagents (doesn't make them read files)
48
+ 3. **Self-Review**: Ensures subagents perform self-review before reporting
49
+ 4. **Review Order**: Runs spec compliance review before code quality review
50
+ 5. **Review Loops**: Uses review loops when issues are found
51
+ 6. **Independent Verification**: Spec reviewer reads code independently, doesn't trust implementer reports
52
+
53
+ ### How It Works
54
+
55
+ 1. **Setup**: Creates a temporary Node.js project with a minimal implementation plan
56
+ 2. **Execution**: Runs Claude Code in headless mode with the skill
57
+ 3. **Verification**: Parses the session transcript (`.jsonl` file) to verify:
58
+ - Skill tool was invoked
59
+ - Subagents were dispatched (Task tool)
60
+ - TodoWrite was used for tracking
61
+ - Implementation files were created
62
+ - Tests pass
63
+ - Git commits show proper workflow
64
+ 4. **Token Analysis**: Shows token usage breakdown by subagent
65
+
66
+ ### Test Output
67
+
68
+ ```
69
+ ========================================
70
+ Integration Test: subagent-driven-development
71
+ ========================================
72
+
73
+ Test project: /tmp/tmp.xyz123
74
+
75
+ === Verification Tests ===
76
+
77
+ Test 1: Skill tool invoked...
78
+ [PASS] subagent-driven-development skill was invoked
79
+
80
+ Test 2: Subagents dispatched...
81
+ [PASS] 7 subagents dispatched
82
+
83
+ Test 3: Task tracking...
84
+ [PASS] TodoWrite used 5 time(s)
85
+
86
+ Test 6: Implementation verification...
87
+ [PASS] src/math.js created
88
+ [PASS] add function exists
89
+ [PASS] multiply function exists
90
+ [PASS] test/math.test.js created
91
+ [PASS] Tests pass
92
+
93
+ Test 7: Git commit history...
94
+ [PASS] Multiple commits created (3 total)
95
+
96
+ Test 8: No extra features added...
97
+ [PASS] No extra features added
98
+
99
+ =========================================
100
+ Token Usage Analysis
101
+ =========================================
102
+
103
+ Usage Breakdown:
104
+ ----------------------------------------------------------------------------------------------------
105
+ Agent Description Msgs Input Output Cache Cost
106
+ ----------------------------------------------------------------------------------------------------
107
+ main Main session (coordinator) 34 27 3,996 1,213,703 $ 4.09
108
+ 3380c209 implementing Task 1: Create Add Function 1 2 787 24,989 $ 0.09
109
+ 34b00fde implementing Task 2: Create Multiply Function 1 4 644 25,114 $ 0.09
110
+ 3801a732 reviewing whether an implementation matches... 1 5 703 25,742 $ 0.09
111
+ 4c142934 doing a final code review... 1 6 854 25,319 $ 0.09
112
+ 5f017a42 a code reviewer. Review Task 2... 1 6 504 22,949 $ 0.08
113
+ a6b7fbe4 a code reviewer. Review Task 1... 1 6 515 22,534 $ 0.08
114
+ f15837c0 reviewing whether an implementation matches... 1 6 416 22,485 $ 0.07
115
+ ----------------------------------------------------------------------------------------------------
116
+
117
+ TOTALS:
118
+ Total messages: 41
119
+ Input tokens: 62
120
+ Output tokens: 8,419
121
+ Cache creation tokens: 132,742
122
+ Cache read tokens: 1,382,835
123
+
124
+ Total input (incl cache): 1,515,639
125
+ Total tokens: 1,524,058
126
+
127
+ Estimated cost: $4.67
128
+ (at $3/$15 per M tokens for input/output)
129
+
130
+ ========================================
131
+ Test Summary
132
+ ========================================
133
+
134
+ STATUS: PASSED
135
+ ```
136
+
137
+ ## Token Analysis Tool
138
+
139
+ ### Usage
140
+
141
+ Analyze token usage from any Claude Code session:
142
+
143
+ ```bash
144
+ python3 tests/claude-code/analyze-token-usage.py ~/.claude/projects/<project-dir>/<session-id>.jsonl
145
+ ```
146
+
147
+ ### Finding Session Files
148
+
149
+ Session transcripts are stored in `~/.claude/projects/` with the working directory path encoded:
150
+
151
+ ```bash
152
+ # Example for /Users/jesse/Documents/GitHub/superpowers/superpowers
153
+ SESSION_DIR="$HOME/.claude/projects/-Users-jesse-Documents-GitHub-superpowers-superpowers"
154
+
155
+ # Find recent sessions
156
+ ls -lt "$SESSION_DIR"/*.jsonl | head -5
157
+ ```
158
+
159
+ ### What It Shows
160
+
161
+ - **Main session usage**: Token usage by the coordinator (you or main Claude instance)
162
+ - **Per-subagent breakdown**: Each Task invocation with:
163
+ - Agent ID
164
+ - Description (extracted from prompt)
165
+ - Message count
166
+ - Input/output tokens
167
+ - Cache usage
168
+ - Estimated cost
169
+ - **Totals**: Overall token usage and cost estimate
170
+
171
+ ### Understanding the Output
172
+
173
+ - **High cache reads**: Good - means prompt caching is working
174
+ - **High input tokens on main**: Expected - coordinator has full context
175
+ - **Similar costs per subagent**: Expected - each gets similar task complexity
176
+ - **Cost per task**: Typical range is $0.05-$0.15 per subagent depending on task
177
+
178
+ ## Troubleshooting
179
+
180
+ ### Skills Not Loading
181
+
182
+ **Problem**: Skill not found when running headless tests
183
+
184
+ **Solutions**:
185
+ 1. Ensure you're running FROM the superpowers directory: `cd /path/to/superpowers && tests/...`
186
+ 2. Check `~/.claude/settings.json` has `"superpowers@superpowers-dev": true` in `enabledPlugins`
187
+ 3. Verify skill exists in `skills/` directory
188
+
189
+ ### Permission Errors
190
+
191
+ **Problem**: Claude blocked from writing files or accessing directories
192
+
193
+ **Solutions**:
194
+ 1. Use `--permission-mode bypassPermissions` flag
195
+ 2. Use `--add-dir /path/to/temp/dir` to grant access to test directories
196
+ 3. Check file permissions on test directories
197
+
198
+ ### Test Timeouts
199
+
200
+ **Problem**: Test takes too long and times out
201
+
202
+ **Solutions**:
203
+ 1. Increase timeout: `timeout 1800 claude ...` (30 minutes)
204
+ 2. Check for infinite loops in skill logic
205
+ 3. Review subagent task complexity
206
+
207
+ ### Session File Not Found
208
+
209
+ **Problem**: Can't find session transcript after test run
210
+
211
+ **Solutions**:
212
+ 1. Check the correct project directory in `~/.claude/projects/`
213
+ 2. Use `find ~/.claude/projects -name "*.jsonl" -mmin -60` to find recent sessions
214
+ 3. Verify test actually ran (check for errors in test output)
215
+
216
+ ## Writing New Integration Tests
217
+
218
+ ### Template
219
+
220
+ ```bash
221
+ #!/usr/bin/env bash
222
+ set -euo pipefail
223
+
224
+ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
225
+ source "$SCRIPT_DIR/test-helpers.sh"
226
+
227
+ # Create test project
228
+ TEST_PROJECT=$(create_test_project)
229
+ trap "cleanup_test_project $TEST_PROJECT" EXIT
230
+
231
+ # Set up test files...
232
+ cd "$TEST_PROJECT"
233
+
234
+ # Run Claude with skill
235
+ PROMPT="Your test prompt here"
236
+ cd "$SCRIPT_DIR/../.." && timeout 1800 claude -p "$PROMPT" \
237
+ --allowed-tools=all \
238
+ --add-dir "$TEST_PROJECT" \
239
+ --permission-mode bypassPermissions \
240
+ 2>&1 | tee output.txt
241
+
242
+ # Find and analyze session
243
+ WORKING_DIR_ESCAPED=$(echo "$SCRIPT_DIR/../.." | sed 's/\\//-/g' | sed 's/^-//')
244
+ SESSION_DIR="$HOME/.claude/projects/$WORKING_DIR_ESCAPED"
245
+ SESSION_FILE=$(find "$SESSION_DIR" -name "*.jsonl" -type f -mmin -60 | sort -r | head -1)
246
+
247
+ # Verify behavior by parsing session transcript
248
+ if grep -q '"name":"Skill".*"skill":"your-skill-name"' "$SESSION_FILE"; then
249
+ echo "[PASS] Skill was invoked"
250
+ fi
251
+
252
+ # Show token analysis
253
+ python3 "$SCRIPT_DIR/analyze-token-usage.py" "$SESSION_FILE"
254
+ ```
255
+
256
+ ### Best Practices
257
+
258
+ 1. **Always cleanup**: Use trap to cleanup temp directories
259
+ 2. **Parse transcripts**: Don't grep user-facing output - parse the `.jsonl` session file
260
+ 3. **Grant permissions**: Use `--permission-mode bypassPermissions` and `--add-dir`
261
+ 4. **Run from plugin dir**: Skills only load when running from the superpowers directory
262
+ 5. **Show token usage**: Always include token analysis for cost visibility
263
+ 6. **Test real behavior**: Verify actual files created, tests passing, commits made
264
+
265
+ ## Session Transcript Format
266
+
267
+ Session transcripts are JSONL (JSON Lines) files where each line is a JSON object representing a message or tool result.
268
+
269
+ ### Key Fields
270
+
271
+ ```json
272
+ {
273
+ "type": "assistant",
274
+ "message": {
275
+ "content": [...],
276
+ "usage": {
277
+ "input_tokens": 27,
278
+ "output_tokens": 3996,
279
+ "cache_read_input_tokens": 1213703
280
+ }
281
+ }
282
+ }
283
+ ```
284
+
285
+ ### Tool Results
286
+
287
+ ```json
288
+ {
289
+ "type": "user",
290
+ "toolUseResult": {
291
+ "agentId": "3380c209",
292
+ "usage": {
293
+ "input_tokens": 2,
294
+ "output_tokens": 787,
295
+ "cache_read_input_tokens": 24989
296
+ },
297
+ "prompt": "You are implementing Task 1...",
298
+ "content": [{"type": "text", "text": "..."}]
299
+ }
300
+ }
301
+ ```
302
+
303
+ The `agentId` field links to subagent sessions, and the `usage` field contains token usage for that specific subagent invocation.
@@ -0,0 +1,212 @@
1
+ # Cross-Platform Polyglot Hooks for Claude Code
2
+
3
+ Claude Code plugins need hooks that work on Windows, macOS, and Linux. This document explains the polyglot wrapper technique that makes this possible.
4
+
5
+ ## The Problem
6
+
7
+ Claude Code runs hook commands through the system's default shell:
8
+ - **Windows**: CMD.exe
9
+ - **macOS/Linux**: bash or sh
10
+
11
+ This creates several challenges:
12
+
13
+ 1. **Script execution**: Windows CMD can't execute `.sh` files directly - it tries to open them in a text editor
14
+ 2. **Path format**: Windows uses backslashes (`C:\path`), Unix uses forward slashes (`/path`)
15
+ 3. **Environment variables**: `$VAR` syntax doesn't work in CMD
16
+ 4. **No `bash` in PATH**: Even with Git Bash installed, `bash` isn't in the PATH when CMD runs
17
+
18
+ ## The Solution: Polyglot `.cmd` Wrapper
19
+
20
+ A polyglot script is valid syntax in multiple languages simultaneously. Our wrapper is valid in both CMD and bash:
21
+
22
+ ```cmd
23
+ : << 'CMDBLOCK'
24
+ @echo off
25
+ "C:\Program Files\Git\bin\bash.exe" -l -c "\"$(cygpath -u \"$CLAUDE_PLUGIN_ROOT\")/hooks/session-start.sh\""
26
+ exit /b
27
+ CMDBLOCK
28
+
29
+ # Unix shell runs from here
30
+ "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
31
+ ```
32
+
33
+ ### How It Works
34
+
35
+ #### On Windows (CMD.exe)
36
+
37
+ 1. `: << 'CMDBLOCK'` - CMD sees `:` as a label (like `:label`) and ignores `<< 'CMDBLOCK'`
38
+ 2. `@echo off` - Suppresses command echoing
39
+ 3. The bash.exe command runs with:
40
+ - `-l` (login shell) to get proper PATH with Unix utilities
41
+ - `cygpath -u` converts Windows path to Unix format (`C:\foo` → `/c/foo`)
42
+ 4. `exit /b` - Exits the batch script, stopping CMD here
43
+ 5. Everything after `CMDBLOCK` is never reached by CMD
44
+
45
+ #### On Unix (bash/sh)
46
+
47
+ 1. `: << 'CMDBLOCK'` - `:` is a no-op, `<< 'CMDBLOCK'` starts a heredoc
48
+ 2. Everything until `CMDBLOCK` is consumed by the heredoc (ignored)
49
+ 3. `# Unix shell runs from here` - Comment
50
+ 4. The script runs directly with the Unix path
51
+
52
+ ## File Structure
53
+
54
+ ```
55
+ hooks/
56
+ ├── hooks.json # Points to the .cmd wrapper
57
+ ├── session-start.cmd # Polyglot wrapper (cross-platform entry point)
58
+ └── session-start.sh # Actual hook logic (bash script)
59
+ ```
60
+
61
+ ### hooks.json
62
+
63
+ ```json
64
+ {
65
+ "hooks": {
66
+ "SessionStart": [
67
+ {
68
+ "matcher": "startup|resume|clear|compact",
69
+ "hooks": [
70
+ {
71
+ "type": "command",
72
+ "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.cmd\""
73
+ }
74
+ ]
75
+ }
76
+ ]
77
+ }
78
+ }
79
+ ```
80
+
81
+ Note: The path must be quoted because `${CLAUDE_PLUGIN_ROOT}` may contain spaces on Windows (e.g., `C:\Program Files\...`).
82
+
83
+ ## Requirements
84
+
85
+ ### Windows
86
+ - **Git for Windows** must be installed (provides `bash.exe` and `cygpath`)
87
+ - Default installation path: `C:\Program Files\Git\bin\bash.exe`
88
+ - If Git is installed elsewhere, the wrapper needs modification
89
+
90
+ ### Unix (macOS/Linux)
91
+ - Standard bash or sh shell
92
+ - The `.cmd` file must have execute permission (`chmod +x`)
93
+
94
+ ## Writing Cross-Platform Hook Scripts
95
+
96
+ Your actual hook logic goes in the `.sh` file. To ensure it works on Windows (via Git Bash):
97
+
98
+ ### Do:
99
+ - Use pure bash builtins when possible
100
+ - Use `$(command)` instead of backticks
101
+ - Quote all variable expansions: `"$VAR"`
102
+ - Use `printf` or here-docs for output
103
+
104
+ ### Avoid:
105
+ - External commands that may not be in PATH (sed, awk, grep)
106
+ - If you must use them, they're available in Git Bash but ensure PATH is set up (use `bash -l`)
107
+
108
+ ### Example: JSON Escaping Without sed/awk
109
+
110
+ Instead of:
111
+ ```bash
112
+ escaped=$(echo "$content" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
113
+ ```
114
+
115
+ Use pure bash:
116
+ ```bash
117
+ escape_for_json() {
118
+ local input="$1"
119
+ local output=""
120
+ local i char
121
+ for (( i=0; i<${#input}; i++ )); do
122
+ char="${input:$i:1}"
123
+ case "$char" in
124
+ $'\\') output+='\\' ;;
125
+ '"') output+='\"' ;;
126
+ $'\n') output+='\n' ;;
127
+ $'\r') output+='\r' ;;
128
+ $'\t') output+='\t' ;;
129
+ *) output+="$char" ;;
130
+ esac
131
+ done
132
+ printf '%s' "$output"
133
+ }
134
+ ```
135
+
136
+ ## Reusable Wrapper Pattern
137
+
138
+ For plugins with multiple hooks, you can create a generic wrapper that takes the script name as an argument:
139
+
140
+ ### run-hook.cmd
141
+ ```cmd
142
+ : << 'CMDBLOCK'
143
+ @echo off
144
+ set "SCRIPT_DIR=%~dp0"
145
+ set "SCRIPT_NAME=%~1"
146
+ "C:\Program Files\Git\bin\bash.exe" -l -c "cd \"$(cygpath -u \"%SCRIPT_DIR%\")\" && \"./%SCRIPT_NAME%\""
147
+ exit /b
148
+ CMDBLOCK
149
+
150
+ # Unix shell runs from here
151
+ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
152
+ SCRIPT_NAME="$1"
153
+ shift
154
+ "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
155
+ ```
156
+
157
+ ### hooks.json using the reusable wrapper
158
+ ```json
159
+ {
160
+ "hooks": {
161
+ "SessionStart": [
162
+ {
163
+ "matcher": "startup",
164
+ "hooks": [
165
+ {
166
+ "type": "command",
167
+ "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start.sh"
168
+ }
169
+ ]
170
+ }
171
+ ],
172
+ "PreToolUse": [
173
+ {
174
+ "matcher": "Bash",
175
+ "hooks": [
176
+ {
177
+ "type": "command",
178
+ "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" validate-bash.sh"
179
+ }
180
+ ]
181
+ }
182
+ ]
183
+ }
184
+ }
185
+ ```
186
+
187
+ ## Troubleshooting
188
+
189
+ ### "bash is not recognized"
190
+ CMD can't find bash. The wrapper uses the full path `C:\Program Files\Git\bin\bash.exe`. If Git is installed elsewhere, update the path.
191
+
192
+ ### "cygpath: command not found" or "dirname: command not found"
193
+ Bash isn't running as a login shell. Ensure `-l` flag is used.
194
+
195
+ ### Path has weird `\/` in it
196
+ `${CLAUDE_PLUGIN_ROOT}` expanded to a Windows path ending with backslash, then `/hooks/...` was appended. Use `cygpath` to convert the entire path.
197
+
198
+ ### Script opens in text editor instead of running
199
+ The hooks.json is pointing directly to the `.sh` file. Point to the `.cmd` wrapper instead.
200
+
201
+ ### Works in terminal but not as hook
202
+ Claude Code may run hooks differently. Test by simulating the hook environment:
203
+ ```powershell
204
+ $env:CLAUDE_PLUGIN_ROOT = "C:\path\to\plugin"
205
+ cmd /c "C:\path\to\plugin\hooks\session-start.cmd"
206
+ ```
207
+
208
+ ## Related Issues
209
+
210
+ - [anthropics/claude-code#9758](https://github.com/anthropics/claude-code/issues/9758) - .sh scripts open in editor on Windows
211
+ - [anthropics/claude-code#3417](https://github.com/anthropics/claude-code/issues/3417) - Hooks don't work on Windows
212
+ - [anthropics/claude-code#6023](https://github.com/anthropics/claude-code/issues/6023) - CLAUDE_PROJECT_DIR not found
@@ -0,0 +1,6 @@
1
+ {
2
+ "name": "superpowers",
3
+ "description": "Core skills library: TDD, debugging, collaboration patterns, and proven techniques",
4
+ "version": "5.0.6",
5
+ "contextFileName": "GEMINI.md"
6
+ }
@@ -0,0 +1,10 @@
1
+ {
2
+ "version": 1,
3
+ "hooks": {
4
+ "sessionStart": [
5
+ {
6
+ "command": "./hooks/session-start"
7
+ }
8
+ ]
9
+ }
10
+ }
@@ -0,0 +1,16 @@
1
+ {
2
+ "hooks": {
3
+ "SessionStart": [
4
+ {
5
+ "matcher": "startup|clear|compact",
6
+ "hooks": [
7
+ {
8
+ "type": "command",
9
+ "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
10
+ "async": false
11
+ }
12
+ ]
13
+ }
14
+ ]
15
+ }
16
+ }
@@ -0,0 +1,46 @@
1
+ : << 'CMDBLOCK'
2
+ @echo off
3
+ REM Cross-platform polyglot wrapper for hook scripts.
4
+ REM On Windows: cmd.exe runs the batch portion, which finds and calls bash.
5
+ REM On Unix: the shell interprets this as a script (: is a no-op in bash).
6
+ REM
7
+ REM Hook scripts use extensionless filenames (e.g. "session-start" not
8
+ REM "session-start.sh") so Claude Code's Windows auto-detection -- which
9
+ REM prepends "bash" to any command containing .sh -- doesn't interfere.
10
+ REM
11
+ REM Usage: run-hook.cmd <script-name> [args...]
12
+
13
+ if "%~1"=="" (
14
+ echo run-hook.cmd: missing script name >&2
15
+ exit /b 1
16
+ )
17
+
18
+ set "HOOK_DIR=%~dp0"
19
+
20
+ REM Try Git for Windows bash in standard locations
21
+ if exist "C:\Program Files\Git\bin\bash.exe" (
22
+ "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
23
+ exit /b %ERRORLEVEL%
24
+ )
25
+ if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
26
+ "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
27
+ exit /b %ERRORLEVEL%
28
+ )
29
+
30
+ REM Try bash on PATH (e.g. user-installed Git Bash, MSYS2, Cygwin)
31
+ where bash >nul 2>nul
32
+ if %ERRORLEVEL% equ 0 (
33
+ bash "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
34
+ exit /b %ERRORLEVEL%
35
+ )
36
+
37
+ REM No bash found - exit silently rather than error
38
+ REM (plugin still works, just without SessionStart context injection)
39
+ exit /b 0
40
+ CMDBLOCK
41
+
42
+ # Unix: run the named script directly
43
+ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
44
+ SCRIPT_NAME="$1"
45
+ shift
46
+ exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
@@ -0,0 +1,57 @@
1
+ #!/usr/bin/env bash
2
+ # SessionStart hook for superpowers plugin
3
+
4
+ set -euo pipefail
5
+
6
+ # Determine plugin root directory
7
+ SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
8
+ PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
9
+
10
+ # Check if legacy skills directory exists and build warning
11
+ warning_message=""
12
+ legacy_skills_dir="${HOME}/.config/superpowers/skills"
13
+ if [ -d "$legacy_skills_dir" ]; then
14
+ warning_message="\n\n<important-reminder>IN YOUR FIRST REPLY AFTER SEEING THIS MESSAGE YOU MUST TELL THE USER:⚠️ **WARNING:** Superpowers now uses Claude Code's skills system. Custom skills in ~/.config/superpowers/skills will not be read. Move custom skills to ~/.claude/skills instead. To make this message go away, remove ~/.config/superpowers/skills</important-reminder>"
15
+ fi
16
+
17
+ # Read using-superpowers content
18
+ using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
19
+
20
+ # Escape string for JSON embedding using bash parameter substitution.
21
+ # Each ${s//old/new} is a single C-level pass - orders of magnitude
22
+ # faster than the character-by-character loop this replaces.
23
+ escape_for_json() {
24
+ local s="$1"
25
+ s="${s//\\/\\\\}"
26
+ s="${s//\"/\\\"}"
27
+ s="${s//$'\n'/\\n}"
28
+ s="${s//$'\r'/\\r}"
29
+ s="${s//$'\t'/\\t}"
30
+ printf '%s' "$s"
31
+ }
32
+
33
+ using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")
34
+ warning_escaped=$(escape_for_json "$warning_message")
35
+ session_context="<EXTREMELY_IMPORTANT>\nYou have superpowers.\n\n**Below is the full content of your 'superpowers:using-superpowers' skill - your introduction to using skills. For all other skills, use the 'Skill' tool:**\n\n${using_superpowers_escaped}\n\n${warning_escaped}\n</EXTREMELY_IMPORTANT>"
36
+
37
+ # Output context injection as JSON.
38
+ # Cursor hooks expect additional_context.
39
+ # Claude Code hooks expect hookSpecificOutput.additionalContext.
40
+ # Claude Code reads BOTH fields without deduplication, so we must only
41
+ # emit the field consumed by the current platform to avoid double injection.
42
+ #
43
+ # Uses printf instead of heredoc (cat <<EOF) to work around a bash 5.3+
44
+ # bug where heredoc variable expansion hangs when content exceeds ~512 bytes.
45
+ # See: https://github.com/obra/superpowers/issues/571
46
+ if [ -n "${CURSOR_PLUGIN_ROOT:-}" ]; then
47
+ # Cursor sets CURSOR_PLUGIN_ROOT (may also set CLAUDE_PLUGIN_ROOT) — emit additional_context
48
+ printf '{\n "additional_context": "%s"\n}\n' "$session_context"
49
+ elif [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
50
+ # Claude Code sets CLAUDE_PLUGIN_ROOT — emit only hookSpecificOutput
51
+ printf '{\n "hookSpecificOutput": {\n "hookEventName": "SessionStart",\n "additionalContext": "%s"\n }\n}\n' "$session_context"
52
+ else
53
+ # Other platforms — emit additional_context as fallback
54
+ printf '{\n "additional_context": "%s"\n}\n' "$session_context"
55
+ fi
56
+
57
+ exit 0
@@ -0,0 +1,6 @@
1
+ {
2
+ "name": "superpowers",
3
+ "version": "5.0.6",
4
+ "type": "module",
5
+ "main": ".opencode/plugins/superpowers.js"
6
+ }