@chankov/agent-fleet 0.0.1

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 (419) hide show
  1. package/.claude/commands/build.md +44 -0
  2. package/.claude/commands/code-simplify.md +22 -0
  3. package/.claude/commands/design-agent.md +14 -0
  4. package/.claude/commands/doctor-agent-fleet.md +17 -0
  5. package/.claude/commands/orchestrate.md +112 -0
  6. package/.claude/commands/plan.md +16 -0
  7. package/.claude/commands/prime.md +22 -0
  8. package/.claude/commands/review.md +16 -0
  9. package/.claude/commands/setup-agent-fleet.md +25 -0
  10. package/.claude/commands/ship.md +72 -0
  11. package/.claude/commands/spec.md +15 -0
  12. package/.claude/commands/test.md +19 -0
  13. package/.claude/commands/webperf.md +32 -0
  14. package/.claude/orchestrate-teams.yaml +24 -0
  15. package/.opencode/commands/af-build.md +17 -0
  16. package/.opencode/commands/af-code-simplify.md +16 -0
  17. package/.opencode/commands/af-compound.md +16 -0
  18. package/.opencode/commands/af-design-agent.md +15 -0
  19. package/.opencode/commands/af-doctor-agent-fleet.md +15 -0
  20. package/.opencode/commands/af-orchestrate.md +112 -0
  21. package/.opencode/commands/af-plan.md +16 -0
  22. package/.opencode/commands/af-prime.md +22 -0
  23. package/.opencode/commands/af-review.md +15 -0
  24. package/.opencode/commands/af-setup-agent-fleet.md +15 -0
  25. package/.opencode/commands/af-ship.md +16 -0
  26. package/.opencode/commands/af-spec.md +16 -0
  27. package/.opencode/commands/af-test.md +21 -0
  28. package/.opencode/commands/af-webperf.md +32 -0
  29. package/.opencode/orchestrate-teams.yaml +24 -0
  30. package/.pi/agents/dispatch-policy.yaml +32 -0
  31. package/.pi/agents/model-profiles.yaml +20 -0
  32. package/.pi/agents/peers.yaml +142 -0
  33. package/.pi/agents/teams.yaml +39 -0
  34. package/.pi/damage-control-rules.yaml +297 -0
  35. package/.pi/extensions/agent-fleet-update-check/README.md +58 -0
  36. package/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  37. package/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  38. package/.pi/extensions/btw/README.md +118 -0
  39. package/.pi/extensions/btw/index.ts +917 -0
  40. package/.pi/extensions/btw/package.json +6 -0
  41. package/.pi/extensions/btw/state.js +179 -0
  42. package/.pi/extensions/chrome-devtools-mcp/README.md +58 -0
  43. package/.pi/extensions/chrome-devtools-mcp/index.ts +92 -0
  44. package/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  45. package/.pi/extensions/compact-and-continue/README.md +42 -0
  46. package/.pi/extensions/compact-and-continue/index.ts +120 -0
  47. package/.pi/extensions/compact-and-continue/package.json +6 -0
  48. package/.pi/extensions/mcp-bridge/README.md +46 -0
  49. package/.pi/extensions/mcp-bridge/index.ts +206 -0
  50. package/.pi/extensions/mcp-bridge/package.json +6 -0
  51. package/.pi/extensions/package-lock.json +1143 -0
  52. package/.pi/extensions/package.json +9 -0
  53. package/.pi/extensions/pi-voice-stt/README.md +201 -0
  54. package/.pi/extensions/pi-voice-stt/config.ts +198 -0
  55. package/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  56. package/.pi/extensions/pi-voice-stt/index.ts +248 -0
  57. package/.pi/extensions/pi-voice-stt/package.json +6 -0
  58. package/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  59. package/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  60. package/.pi/harnesses/agent-hub/README.md +562 -0
  61. package/.pi/harnesses/agent-hub/artifacts.js +92 -0
  62. package/.pi/harnesses/agent-hub/backend-policy.js +153 -0
  63. package/.pi/harnesses/agent-hub/delegate.ts +363 -0
  64. package/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  65. package/.pi/harnesses/agent-hub/helpers.ts +165 -0
  66. package/.pi/harnesses/agent-hub/index.ts +7098 -0
  67. package/.pi/harnesses/agent-hub/package.json +6 -0
  68. package/.pi/harnesses/agent-hub/return-contract.js +215 -0
  69. package/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  70. package/.pi/harnesses/agent-hub/spawn.ts +179 -0
  71. package/.pi/harnesses/ask-user-remote/README.md +10 -0
  72. package/.pi/harnesses/ask-user-remote/index.ts +253 -0
  73. package/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  74. package/.pi/harnesses/coms/README.md +71 -0
  75. package/.pi/harnesses/coms/index.ts +1743 -0
  76. package/.pi/harnesses/coms/package.json +6 -0
  77. package/.pi/harnesses/damage-control/README.md +65 -0
  78. package/.pi/harnesses/damage-control/index.ts +250 -0
  79. package/.pi/harnesses/damage-control/package.json +6 -0
  80. package/.pi/harnesses/damage-control/shared.ts +183 -0
  81. package/.pi/harnesses/damage-control-continue/README.md +116 -0
  82. package/.pi/harnesses/damage-control-continue/index.ts +522 -0
  83. package/.pi/harnesses/damage-control-continue/package.json +6 -0
  84. package/.pi/harnesses/lib/herdr-client.ts +458 -0
  85. package/.pi/harnesses/lib/herdr-presence.ts +288 -0
  86. package/.pi/harnesses/package-lock.json +35 -0
  87. package/.pi/harnesses/package.json +9 -0
  88. package/.pi/prompts/build.md +24 -0
  89. package/.pi/prompts/code-simplify.md +22 -0
  90. package/.pi/prompts/doctor-agent-fleet.md +15 -0
  91. package/.pi/prompts/plan.md +16 -0
  92. package/.pi/prompts/review.md +16 -0
  93. package/.pi/prompts/setup-agent-fleet.md +27 -0
  94. package/.pi/prompts/ship.md +17 -0
  95. package/.pi/prompts/spec.md +15 -0
  96. package/.pi/prompts/test.md +19 -0
  97. package/.pi/skills/bowser/SKILL.md +145 -0
  98. package/.versions/0.0.1/.claude/commands/build.md +44 -0
  99. package/.versions/0.0.1/.claude/commands/code-simplify.md +22 -0
  100. package/.versions/0.0.1/.claude/commands/design-agent.md +14 -0
  101. package/.versions/0.0.1/.claude/commands/doctor-agent-fleet.md +17 -0
  102. package/.versions/0.0.1/.claude/commands/orchestrate.md +112 -0
  103. package/.versions/0.0.1/.claude/commands/plan.md +16 -0
  104. package/.versions/0.0.1/.claude/commands/prime.md +22 -0
  105. package/.versions/0.0.1/.claude/commands/review.md +16 -0
  106. package/.versions/0.0.1/.claude/commands/setup-agent-fleet.md +25 -0
  107. package/.versions/0.0.1/.claude/commands/ship.md +72 -0
  108. package/.versions/0.0.1/.claude/commands/spec.md +15 -0
  109. package/.versions/0.0.1/.claude/commands/test.md +19 -0
  110. package/.versions/0.0.1/.claude/commands/webperf.md +32 -0
  111. package/.versions/0.0.1/.claude/orchestrate-teams.yaml +24 -0
  112. package/.versions/0.0.1/.opencode/commands/af-build.md +17 -0
  113. package/.versions/0.0.1/.opencode/commands/af-code-simplify.md +16 -0
  114. package/.versions/0.0.1/.opencode/commands/af-compound.md +16 -0
  115. package/.versions/0.0.1/.opencode/commands/af-design-agent.md +15 -0
  116. package/.versions/0.0.1/.opencode/commands/af-doctor-agent-fleet.md +15 -0
  117. package/.versions/0.0.1/.opencode/commands/af-orchestrate.md +112 -0
  118. package/.versions/0.0.1/.opencode/commands/af-plan.md +16 -0
  119. package/.versions/0.0.1/.opencode/commands/af-prime.md +22 -0
  120. package/.versions/0.0.1/.opencode/commands/af-review.md +15 -0
  121. package/.versions/0.0.1/.opencode/commands/af-setup-agent-fleet.md +15 -0
  122. package/.versions/0.0.1/.opencode/commands/af-ship.md +16 -0
  123. package/.versions/0.0.1/.opencode/commands/af-spec.md +16 -0
  124. package/.versions/0.0.1/.opencode/commands/af-test.md +21 -0
  125. package/.versions/0.0.1/.opencode/commands/af-webperf.md +32 -0
  126. package/.versions/0.0.1/.opencode/orchestrate-teams.yaml +24 -0
  127. package/.versions/0.0.1/.pi/agents/dispatch-policy.yaml +32 -0
  128. package/.versions/0.0.1/.pi/agents/model-profiles.yaml +20 -0
  129. package/.versions/0.0.1/.pi/agents/peers.yaml +142 -0
  130. package/.versions/0.0.1/.pi/agents/teams.yaml +39 -0
  131. package/.versions/0.0.1/.pi/damage-control-rules.yaml +297 -0
  132. package/.versions/0.0.1/.pi/extensions/agent-fleet-update-check/README.md +58 -0
  133. package/.versions/0.0.1/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  134. package/.versions/0.0.1/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  135. package/.versions/0.0.1/.pi/extensions/btw/README.md +118 -0
  136. package/.versions/0.0.1/.pi/extensions/btw/index.ts +917 -0
  137. package/.versions/0.0.1/.pi/extensions/btw/package.json +6 -0
  138. package/.versions/0.0.1/.pi/extensions/btw/state.js +179 -0
  139. package/.versions/0.0.1/.pi/extensions/chrome-devtools-mcp/README.md +58 -0
  140. package/.versions/0.0.1/.pi/extensions/chrome-devtools-mcp/index.ts +92 -0
  141. package/.versions/0.0.1/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  142. package/.versions/0.0.1/.pi/extensions/compact-and-continue/README.md +42 -0
  143. package/.versions/0.0.1/.pi/extensions/compact-and-continue/index.ts +120 -0
  144. package/.versions/0.0.1/.pi/extensions/compact-and-continue/package.json +6 -0
  145. package/.versions/0.0.1/.pi/extensions/mcp-bridge/README.md +46 -0
  146. package/.versions/0.0.1/.pi/extensions/mcp-bridge/index.ts +206 -0
  147. package/.versions/0.0.1/.pi/extensions/mcp-bridge/package.json +6 -0
  148. package/.versions/0.0.1/.pi/extensions/package-lock.json +1143 -0
  149. package/.versions/0.0.1/.pi/extensions/package.json +9 -0
  150. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/README.md +201 -0
  151. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/config.ts +198 -0
  152. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  153. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/index.ts +248 -0
  154. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/package.json +6 -0
  155. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  156. package/.versions/0.0.1/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  157. package/.versions/0.0.1/.pi/harnesses/agent-hub/README.md +562 -0
  158. package/.versions/0.0.1/.pi/harnesses/agent-hub/artifacts.js +92 -0
  159. package/.versions/0.0.1/.pi/harnesses/agent-hub/backend-policy.js +153 -0
  160. package/.versions/0.0.1/.pi/harnesses/agent-hub/delegate.ts +363 -0
  161. package/.versions/0.0.1/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  162. package/.versions/0.0.1/.pi/harnesses/agent-hub/helpers.ts +165 -0
  163. package/.versions/0.0.1/.pi/harnesses/agent-hub/index.ts +7098 -0
  164. package/.versions/0.0.1/.pi/harnesses/agent-hub/package.json +6 -0
  165. package/.versions/0.0.1/.pi/harnesses/agent-hub/return-contract.js +215 -0
  166. package/.versions/0.0.1/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  167. package/.versions/0.0.1/.pi/harnesses/agent-hub/spawn.ts +179 -0
  168. package/.versions/0.0.1/.pi/harnesses/ask-user-remote/README.md +10 -0
  169. package/.versions/0.0.1/.pi/harnesses/ask-user-remote/index.ts +253 -0
  170. package/.versions/0.0.1/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  171. package/.versions/0.0.1/.pi/harnesses/coms/README.md +71 -0
  172. package/.versions/0.0.1/.pi/harnesses/coms/index.ts +1743 -0
  173. package/.versions/0.0.1/.pi/harnesses/coms/package.json +6 -0
  174. package/.versions/0.0.1/.pi/harnesses/damage-control/README.md +65 -0
  175. package/.versions/0.0.1/.pi/harnesses/damage-control/index.ts +250 -0
  176. package/.versions/0.0.1/.pi/harnesses/damage-control/package.json +6 -0
  177. package/.versions/0.0.1/.pi/harnesses/damage-control/shared.ts +183 -0
  178. package/.versions/0.0.1/.pi/harnesses/damage-control-continue/README.md +116 -0
  179. package/.versions/0.0.1/.pi/harnesses/damage-control-continue/index.ts +522 -0
  180. package/.versions/0.0.1/.pi/harnesses/damage-control-continue/package.json +6 -0
  181. package/.versions/0.0.1/.pi/harnesses/lib/herdr-client.ts +458 -0
  182. package/.versions/0.0.1/.pi/harnesses/lib/herdr-presence.ts +288 -0
  183. package/.versions/0.0.1/.pi/harnesses/package-lock.json +35 -0
  184. package/.versions/0.0.1/.pi/harnesses/package.json +9 -0
  185. package/.versions/0.0.1/.pi/prompts/build.md +24 -0
  186. package/.versions/0.0.1/.pi/prompts/code-simplify.md +22 -0
  187. package/.versions/0.0.1/.pi/prompts/doctor-agent-fleet.md +15 -0
  188. package/.versions/0.0.1/.pi/prompts/plan.md +16 -0
  189. package/.versions/0.0.1/.pi/prompts/review.md +16 -0
  190. package/.versions/0.0.1/.pi/prompts/setup-agent-fleet.md +27 -0
  191. package/.versions/0.0.1/.pi/prompts/ship.md +17 -0
  192. package/.versions/0.0.1/.pi/prompts/spec.md +15 -0
  193. package/.versions/0.0.1/.pi/prompts/test.md +19 -0
  194. package/.versions/0.0.1/.pi/skills/bowser/SKILL.md +145 -0
  195. package/.versions/0.0.1/.version +1 -0
  196. package/.versions/0.0.1/agents/architect.md +21 -0
  197. package/.versions/0.0.1/agents/bowser.md +25 -0
  198. package/.versions/0.0.1/agents/builder.md +52 -0
  199. package/.versions/0.0.1/agents/code-reviewer.md +205 -0
  200. package/.versions/0.0.1/agents/deep-researcher.md +31 -0
  201. package/.versions/0.0.1/agents/documenter.md +16 -0
  202. package/.versions/0.0.1/agents/orchestrator.md +43 -0
  203. package/.versions/0.0.1/agents/plan-reviewer.md +60 -0
  204. package/.versions/0.0.1/agents/planner.md +69 -0
  205. package/.versions/0.0.1/agents/releaser.md +22 -0
  206. package/.versions/0.0.1/agents/researcher.md +28 -0
  207. package/.versions/0.0.1/agents/security-auditor.md +166 -0
  208. package/.versions/0.0.1/agents/test-engineer.md +144 -0
  209. package/.versions/0.0.1/agents/web-debugger.md +42 -0
  210. package/.versions/0.0.1/agents/web-performance-auditor.md +192 -0
  211. package/.versions/0.0.1/hooks/SIMPLIFY-IGNORE.md +90 -0
  212. package/.versions/0.0.1/hooks/coms-stop-hook.mjs +73 -0
  213. package/.versions/0.0.1/hooks/hooks.json +14 -0
  214. package/.versions/0.0.1/hooks/session-start.sh +74 -0
  215. package/.versions/0.0.1/hooks/simplify-ignore.sh +302 -0
  216. package/.versions/0.0.1/justfile +143 -0
  217. package/.versions/0.0.1/references/accessibility-checklist.md +160 -0
  218. package/.versions/0.0.1/references/definition-of-done.md +67 -0
  219. package/.versions/0.0.1/references/fleet-coordination-patterns.md +151 -0
  220. package/.versions/0.0.1/references/observability-checklist.md +91 -0
  221. package/.versions/0.0.1/references/orchestration-patterns.md +370 -0
  222. package/.versions/0.0.1/references/performance-checklist.md +153 -0
  223. package/.versions/0.0.1/references/prompting-patterns.md +380 -0
  224. package/.versions/0.0.1/references/security-checklist.md +179 -0
  225. package/.versions/0.0.1/references/testing-patterns.md +236 -0
  226. package/.versions/0.0.1/scripts/coms-claude-bridge.ts +286 -0
  227. package/.versions/0.0.1/scripts/coms-cli.ts +372 -0
  228. package/.versions/0.0.1/scripts/coms-hermes-bridge.ts +399 -0
  229. package/.versions/0.0.1/scripts/lib/claude-bridge-core.ts +100 -0
  230. package/.versions/0.0.1/scripts/lib/coms-envelope.ts +494 -0
  231. package/.versions/0.0.1/scripts/lib/herdr-layout.ts +235 -0
  232. package/.versions/0.0.1/scripts/lib/hermes-bridge-core.ts +238 -0
  233. package/.versions/0.0.1/scripts/lib/persona-banner.ts +62 -0
  234. package/.versions/0.0.1/scripts/lib/team-project.ts +75 -0
  235. package/.versions/0.0.1/scripts/lib/team-snapshot.ts +146 -0
  236. package/.versions/0.0.1/scripts/peer-banner.ts +40 -0
  237. package/.versions/0.0.1/scripts/team-snapshot.ts +221 -0
  238. package/.versions/0.0.1/scripts/team-up.ts +245 -0
  239. package/.versions/0.0.1/skills/_internal/grilling.md +11 -0
  240. package/.versions/0.0.1/skills/browser-testing-with-devtools/SKILL.md +352 -0
  241. package/.versions/0.0.1/skills/code-review-and-quality/SKILL.md +381 -0
  242. package/.versions/0.0.1/skills/compound-learning/SKILL.md +137 -0
  243. package/.versions/0.0.1/skills/context-engineering/SKILL.md +291 -0
  244. package/.versions/0.0.1/skills/deprecation-and-migration/SKILL.md +206 -0
  245. package/.versions/0.0.1/skills/designing-agents/SKILL.md +394 -0
  246. package/.versions/0.0.1/skills/designing-agents/pi-harness-authoring.md +209 -0
  247. package/.versions/0.0.1/skills/frontend-ui-engineering/SKILL.md +328 -0
  248. package/.versions/0.0.1/skills/git-workflow-and-versioning/SKILL.md +316 -0
  249. package/.versions/0.0.1/skills/guided-workspace-setup/SKILL.md +506 -0
  250. package/.versions/0.0.1/skills/idea-refine/SKILL.md +182 -0
  251. package/.versions/0.0.1/skills/idea-refine/examples.md +238 -0
  252. package/.versions/0.0.1/skills/idea-refine/frameworks.md +99 -0
  253. package/.versions/0.0.1/skills/idea-refine/refinement-criteria.md +113 -0
  254. package/.versions/0.0.1/skills/idea-refine/scripts/idea-refine.sh +15 -0
  255. package/.versions/0.0.1/skills/incremental-implementation/SKILL.md +287 -0
  256. package/.versions/0.0.1/skills/interview-me/SKILL.md +226 -0
  257. package/.versions/0.0.1/skills/orchestration-verification/SKILL.md +181 -0
  258. package/.versions/0.0.1/skills/peer-coms/SKILL.md +81 -0
  259. package/.versions/0.0.1/skills/performance-optimization/SKILL.md +350 -0
  260. package/.versions/0.0.1/skills/planning-and-task-breakdown/SKILL.md +236 -0
  261. package/.versions/0.0.1/skills/security-and-hardening/SKILL.md +461 -0
  262. package/.versions/0.0.1/skills/spec-driven-development/SKILL.md +245 -0
  263. package/.versions/0.0.1/skills/using-agent-skills/SKILL.md +199 -0
  264. package/.versions/0.0.1/vendor/agent-skills-upstream/LICENSE +21 -0
  265. package/.versions/0.0.1/vendor/agent-skills-upstream/README.md +11 -0
  266. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  267. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  268. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  269. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  270. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  271. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  272. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  273. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  274. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  275. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  276. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  277. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  278. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  279. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  280. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  281. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  282. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  283. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  284. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  285. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  286. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  287. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  288. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  289. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  290. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  291. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  292. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  293. package/.versions/0.0.1/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  294. package/CHANGELOG.md +65 -0
  295. package/LICENSE +21 -0
  296. package/README.md +458 -0
  297. package/agents/architect.md +21 -0
  298. package/agents/bowser.md +25 -0
  299. package/agents/builder.md +52 -0
  300. package/agents/code-reviewer.md +205 -0
  301. package/agents/deep-researcher.md +31 -0
  302. package/agents/documenter.md +16 -0
  303. package/agents/orchestrator.md +43 -0
  304. package/agents/plan-reviewer.md +60 -0
  305. package/agents/planner.md +69 -0
  306. package/agents/releaser.md +22 -0
  307. package/agents/researcher.md +28 -0
  308. package/agents/security-auditor.md +166 -0
  309. package/agents/test-engineer.md +144 -0
  310. package/agents/web-debugger.md +42 -0
  311. package/agents/web-performance-auditor.md +192 -0
  312. package/bin/cli.js +633 -0
  313. package/bin/force-patch-changesets.js +44 -0
  314. package/bin/lib/bootstrap.js +323 -0
  315. package/bin/lib/detect-agent.js +49 -0
  316. package/bin/lib/doctor.js +302 -0
  317. package/bin/lib/transform-persona.js +180 -0
  318. package/bin/lib/update-notifier.js +195 -0
  319. package/bin/lib/validate-overrides.js +229 -0
  320. package/bin/snapshot-version.js +91 -0
  321. package/docs/agent-fleet-setup.md +355 -0
  322. package/docs/claude-code-coms-bridge.md +93 -0
  323. package/docs/getting-started.md +169 -0
  324. package/docs/npm-install.md +335 -0
  325. package/docs/opencode-setup.md +248 -0
  326. package/docs/pi-extensions.md +237 -0
  327. package/docs/pi-setup.md +455 -0
  328. package/docs/skill-anatomy.md +150 -0
  329. package/hooks/SIMPLIFY-IGNORE.md +90 -0
  330. package/hooks/coms-stop-hook.mjs +73 -0
  331. package/hooks/hooks.json +14 -0
  332. package/hooks/session-start.sh +74 -0
  333. package/hooks/simplify-ignore.sh +302 -0
  334. package/justfile +143 -0
  335. package/node_modules/pi-ask-user/LICENSE +21 -0
  336. package/node_modules/pi-ask-user/README.md +156 -0
  337. package/node_modules/pi-ask-user/index.ts +1795 -0
  338. package/node_modules/pi-ask-user/package.json +51 -0
  339. package/node_modules/pi-ask-user/single-select-layout.ts +203 -0
  340. package/node_modules/pi-ask-user/skills/ask-user/SKILL.md +162 -0
  341. package/node_modules/pi-ask-user/skills/ask-user/references/ask-user-skill-extension-spec.md +96 -0
  342. package/package.json +121 -0
  343. package/references/accessibility-checklist.md +160 -0
  344. package/references/definition-of-done.md +67 -0
  345. package/references/fleet-coordination-patterns.md +151 -0
  346. package/references/observability-checklist.md +91 -0
  347. package/references/orchestration-patterns.md +370 -0
  348. package/references/performance-checklist.md +153 -0
  349. package/references/prompting-patterns.md +380 -0
  350. package/references/security-checklist.md +179 -0
  351. package/references/testing-patterns.md +236 -0
  352. package/scripts/coms-claude-bridge.ts +286 -0
  353. package/scripts/coms-cli.ts +372 -0
  354. package/scripts/coms-hermes-bridge.ts +399 -0
  355. package/scripts/lib/claude-bridge-core.ts +100 -0
  356. package/scripts/lib/coms-envelope.ts +494 -0
  357. package/scripts/lib/herdr-layout.ts +235 -0
  358. package/scripts/lib/hermes-bridge-core.ts +238 -0
  359. package/scripts/lib/persona-banner.ts +62 -0
  360. package/scripts/lib/team-project.ts +75 -0
  361. package/scripts/lib/team-snapshot.ts +146 -0
  362. package/scripts/peer-banner.ts +40 -0
  363. package/scripts/team-snapshot.ts +221 -0
  364. package/scripts/team-up.ts +245 -0
  365. package/skills/_internal/grilling.md +11 -0
  366. package/skills/browser-testing-with-devtools/SKILL.md +352 -0
  367. package/skills/code-review-and-quality/SKILL.md +381 -0
  368. package/skills/compound-learning/SKILL.md +137 -0
  369. package/skills/context-engineering/SKILL.md +291 -0
  370. package/skills/deprecation-and-migration/SKILL.md +206 -0
  371. package/skills/designing-agents/SKILL.md +394 -0
  372. package/skills/designing-agents/pi-harness-authoring.md +209 -0
  373. package/skills/frontend-ui-engineering/SKILL.md +328 -0
  374. package/skills/git-workflow-and-versioning/SKILL.md +316 -0
  375. package/skills/guided-workspace-setup/SKILL.md +506 -0
  376. package/skills/idea-refine/SKILL.md +182 -0
  377. package/skills/idea-refine/examples.md +238 -0
  378. package/skills/idea-refine/frameworks.md +99 -0
  379. package/skills/idea-refine/refinement-criteria.md +113 -0
  380. package/skills/idea-refine/scripts/idea-refine.sh +15 -0
  381. package/skills/incremental-implementation/SKILL.md +287 -0
  382. package/skills/interview-me/SKILL.md +226 -0
  383. package/skills/orchestration-verification/SKILL.md +181 -0
  384. package/skills/peer-coms/SKILL.md +81 -0
  385. package/skills/performance-optimization/SKILL.md +350 -0
  386. package/skills/planning-and-task-breakdown/SKILL.md +236 -0
  387. package/skills/security-and-hardening/SKILL.md +461 -0
  388. package/skills/spec-driven-development/SKILL.md +245 -0
  389. package/skills/using-agent-skills/SKILL.md +199 -0
  390. package/vendor/agent-skills-upstream/LICENSE +21 -0
  391. package/vendor/agent-skills-upstream/README.md +11 -0
  392. package/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  393. package/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  394. package/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  395. package/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  396. package/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  397. package/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  398. package/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  399. package/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  400. package/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  401. package/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  402. package/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  403. package/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  404. package/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  405. package/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  406. package/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  407. package/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  408. package/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  409. package/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  410. package/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  411. package/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  412. package/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  413. package/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  414. package/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  415. package/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  416. package/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  417. package/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  418. package/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  419. package/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
@@ -0,0 +1,179 @@
1
+ # Security Checklist
2
+
3
+ Quick reference for web application security. Use alongside the `security-and-hardening` skill.
4
+
5
+ ## Table of Contents
6
+
7
+ - [Threat Modeling (Start Here)](#threat-modeling-start-here)
8
+ - [Pre-Commit Checks](#pre-commit-checks)
9
+ - [Authentication](#authentication)
10
+ - [Authorization](#authorization)
11
+ - [Input Validation](#input-validation)
12
+ - [Security Headers](#security-headers)
13
+ - [CORS Configuration](#cors-configuration)
14
+ - [Data Protection](#data-protection)
15
+ - [Dependency Security](#dependency-security)
16
+ - [AI / LLM Security](#ai--llm-security)
17
+ - [Error Handling](#error-handling)
18
+ - [OWASP Top 10 Quick Reference](#owasp-top-10-quick-reference)
19
+ - [OWASP Top 10 for LLMs Quick Reference](#owasp-top-10-for-llms-quick-reference)
20
+
21
+ ## Threat Modeling (Start Here)
22
+
23
+ Before reaching for controls, spend five minutes thinking like an attacker:
24
+
25
+ - [ ] Trust boundaries mapped (requests, uploads, webhooks, third-party APIs, LLM output)
26
+ - [ ] Assets named (credentials, PII, payment data, admin actions, money movement)
27
+ - [ ] STRIDE run per boundary (Spoofing, Tampering, Repudiation, Info disclosure, DoS, Elevation)
28
+ - [ ] Abuse cases written next to use cases ("how would I misuse this?")
29
+
30
+ ## Pre-Commit Checks
31
+
32
+ - [ ] No secrets in code (`git diff --cached | grep -i "password\|secret\|api_key\|token"`)
33
+ - [ ] `.gitignore` covers: `.env`, `.env.local`, `*.pem`, `*.key`
34
+ - [ ] `.env.example` uses placeholder values (not real secrets)
35
+
36
+ ## Authentication
37
+
38
+ - [ ] Passwords hashed with bcrypt (≥12 rounds), scrypt, or argon2
39
+ - [ ] Session cookies: `httpOnly`, `secure`, `sameSite: 'lax'`
40
+ - [ ] Session expiration configured (reasonable max-age)
41
+ - [ ] Rate limiting on login endpoint (≤10 attempts per 15 minutes)
42
+ - [ ] Password reset tokens: time-limited (≤1 hour), single-use
43
+ - [ ] Account lockout after repeated failures (optional, with notification)
44
+ - [ ] MFA supported for sensitive operations (optional but recommended)
45
+
46
+ ## Authorization
47
+
48
+ - [ ] Every protected endpoint checks authentication
49
+ - [ ] Every resource access checks ownership/role (prevents IDOR)
50
+ - [ ] Admin endpoints require admin role verification
51
+ - [ ] API keys scoped to minimum necessary permissions
52
+ - [ ] JWT tokens validated (signature, expiration, issuer)
53
+
54
+ ## Input Validation
55
+
56
+ - [ ] All user input validated at system boundaries (API routes, form handlers)
57
+ - [ ] Validation uses allowlists (not denylists)
58
+ - [ ] String lengths constrained (min/max)
59
+ - [ ] Numeric ranges validated
60
+ - [ ] Email, URL, and date formats validated with proper libraries
61
+ - [ ] File uploads: type restricted, size limited, content verified
62
+ - [ ] SQL queries parameterized (no string concatenation)
63
+ - [ ] HTML output encoded (use framework auto-escaping)
64
+ - [ ] URLs validated before redirect (prevent open redirect)
65
+ - [ ] Server-side URL fetches allowlisted; private/reserved IPs blocked (prevent SSRF)
66
+
67
+ ## Security Headers
68
+
69
+ ```
70
+ Content-Security-Policy: default-src 'self'; script-src 'self'
71
+ Strict-Transport-Security: max-age=31536000; includeSubDomains
72
+ X-Content-Type-Options: nosniff
73
+ X-Frame-Options: DENY
74
+ X-XSS-Protection: 0 (disabled, rely on CSP)
75
+ Referrer-Policy: strict-origin-when-cross-origin
76
+ Permissions-Policy: camera=(), microphone=(), geolocation=()
77
+ ```
78
+
79
+ ## CORS Configuration
80
+
81
+ ```typescript
82
+ // Restrictive (recommended)
83
+ cors({
84
+ origin: ['https://yourdomain.com', 'https://app.yourdomain.com'],
85
+ credentials: true,
86
+ methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'],
87
+ allowedHeaders: ['Content-Type', 'Authorization'],
88
+ })
89
+
90
+ // NEVER use in production:
91
+ cors({ origin: '*' }) // Allows any origin
92
+ ```
93
+
94
+ ## Data Protection
95
+
96
+ - [ ] Sensitive fields excluded from API responses (`passwordHash`, `resetToken`, etc.)
97
+ - [ ] Sensitive data not logged (passwords, tokens, full CC numbers)
98
+ - [ ] PII encrypted at rest (if required by regulation)
99
+ - [ ] HTTPS for all external communication
100
+ - [ ] Database backups encrypted
101
+
102
+ ## Dependency Security
103
+
104
+ ```bash
105
+ # Audit dependencies
106
+ npm audit
107
+
108
+ # Fix automatically where possible
109
+ npm audit fix
110
+
111
+ # Check for critical vulnerabilities
112
+ npm audit --audit-level=critical
113
+
114
+ # Keep dependencies updated
115
+ npx npm-check-updates
116
+ ```
117
+
118
+ **Supply-chain hygiene** (`npm audit` won't catch malicious packages):
119
+ - [ ] Lockfile committed; CI installs with `npm ci` (not `npm install`)
120
+ - [ ] New dependencies reviewed (maintenance, downloads, `postinstall` scripts)
121
+ - [ ] No typosquats (`cross-env` vs `crossenv`, `react-dom` vs `reactdom`)
122
+
123
+ ## AI / LLM Security
124
+
125
+ For any feature that calls an LLM (chatbots, summarizers, agents, RAG):
126
+
127
+ - [ ] Model output treated as untrusted — never into `eval`/SQL/shell/`innerHTML`/file paths
128
+ - [ ] Prompt injection assumed; permissions enforced in code, not in the system prompt
129
+ - [ ] Secrets, cross-tenant data, and full system prompts kept out of the context window
130
+ - [ ] Tool/agent permissions scoped; destructive or irreversible actions require confirmation
131
+ - [ ] Token, rate, and recursion/loop limits set (bound consumption)
132
+
133
+ ## Error Handling
134
+
135
+ ```typescript
136
+ // Production: generic error, no internals
137
+ res.status(500).json({
138
+ error: { code: 'INTERNAL_ERROR', message: 'Something went wrong' }
139
+ });
140
+
141
+ // NEVER in production:
142
+ res.status(500).json({
143
+ error: err.message,
144
+ stack: err.stack, // Exposes internals
145
+ query: err.sql, // Exposes database details
146
+ });
147
+ ```
148
+
149
+ ## OWASP Top 10 Quick Reference
150
+
151
+ | # | Vulnerability | Prevention |
152
+ |---|---|---|
153
+ | 1 | Broken Access Control | Auth checks on every endpoint, ownership verification |
154
+ | 2 | Cryptographic Failures | HTTPS, strong hashing, no secrets in code |
155
+ | 3 | Injection | Parameterized queries, input validation |
156
+ | 4 | Insecure Design | Threat modeling, spec-driven development |
157
+ | 5 | Security Misconfiguration | Security headers, minimal permissions, audit deps |
158
+ | 6 | Vulnerable Components | `npm audit`, keep deps updated, minimal deps |
159
+ | 7 | Auth Failures | Strong passwords, rate limiting, session management |
160
+ | 8 | Data Integrity Failures | Verify updates/dependencies, signed artifacts |
161
+ | 9 | Logging Failures | Log security events, don't log secrets |
162
+ | 10 | SSRF | Validate/allowlist URLs, restrict outbound requests |
163
+
164
+ ## OWASP Top 10 for LLMs Quick Reference
165
+
166
+ For apps with LLM features. See the [OWASP GenAI Security Project](https://genai.owasp.org/llm-top-10/).
167
+
168
+ | ID | Risk | Prevention |
169
+ |---|---|---|
170
+ | LLM01 | Prompt Injection | Don't trust the system prompt as a boundary; enforce permissions in code |
171
+ | LLM02 | Sensitive Information Disclosure | Keep secrets/PII out of prompts; filter outputs |
172
+ | LLM03 | Supply Chain | Vet models, datasets, and plugins like any dependency |
173
+ | LLM04 | Data and Model Poisoning | Use trusted model sources, verify integrity; vet fine-tuning and RAG data |
174
+ | LLM05 | Improper Output Handling | Treat model output as untrusted; validate, parameterize, encode |
175
+ | LLM06 | Excessive Agency | Scope tool permissions; confirm destructive actions |
176
+ | LLM07 | System Prompt Leakage | Assume the system prompt can leak; put no secrets in it |
177
+ | LLM08 | Vector and Embedding Weaknesses | Partition RAG embeddings per tenant; validate documents before indexing |
178
+ | LLM09 | Misinformation | Ground answers with citations; validate critical claims; keep a human in the loop |
179
+ | LLM10 | Unbounded Consumption | Cap tokens, request rate, and loop/recursion depth |
@@ -0,0 +1,236 @@
1
+ # Testing Patterns Reference
2
+
3
+ Quick reference for common testing patterns across the stack. Use alongside the `test-driven-development` skill.
4
+
5
+ ## Table of Contents
6
+
7
+ - [Test Structure (Arrange-Act-Assert)](#test-structure-arrange-act-assert)
8
+ - [Test Naming Conventions](#test-naming-conventions)
9
+ - [Common Assertions](#common-assertions)
10
+ - [Mocking Patterns](#mocking-patterns)
11
+ - [React/Component Testing](#reactcomponent-testing)
12
+ - [API / Integration Testing](#api--integration-testing)
13
+ - [E2E Testing (Playwright)](#e2e-testing-playwright)
14
+ - [Test Anti-Patterns](#test-anti-patterns)
15
+
16
+ ## Test Structure (Arrange-Act-Assert)
17
+
18
+ ```typescript
19
+ it('describes expected behavior', () => {
20
+ // Arrange: Set up test data and preconditions
21
+ const input = { title: 'Test Task', priority: 'high' };
22
+
23
+ // Act: Perform the action being tested
24
+ const result = createTask(input);
25
+
26
+ // Assert: Verify the outcome
27
+ expect(result.title).toBe('Test Task');
28
+ expect(result.priority).toBe('high');
29
+ expect(result.status).toBe('pending');
30
+ });
31
+ ```
32
+
33
+ ## Test Naming Conventions
34
+
35
+ ```typescript
36
+ // Pattern: [unit] [expected behavior] [condition]
37
+ describe('TaskService.createTask', () => {
38
+ it('creates a task with default pending status', () => {});
39
+ it('throws ValidationError when title is empty', () => {});
40
+ it('trims whitespace from title', () => {});
41
+ it('generates a unique ID for each task', () => {});
42
+ });
43
+ ```
44
+
45
+ ## Common Assertions
46
+
47
+ ```typescript
48
+ // Equality
49
+ expect(result).toBe(expected); // Strict equality (===)
50
+ expect(result).toEqual(expected); // Deep equality (objects/arrays)
51
+ expect(result).toStrictEqual(expected); // Deep equality + type matching
52
+
53
+ // Truthiness
54
+ expect(result).toBeTruthy();
55
+ expect(result).toBeFalsy();
56
+ expect(result).toBeNull();
57
+ expect(result).toBeDefined();
58
+ expect(result).toBeUndefined();
59
+
60
+ // Numbers
61
+ expect(result).toBeGreaterThan(5);
62
+ expect(result).toBeLessThanOrEqual(10);
63
+ expect(result).toBeCloseTo(0.3, 5); // Floating point
64
+
65
+ // Strings
66
+ expect(result).toMatch(/pattern/);
67
+ expect(result).toContain('substring');
68
+
69
+ // Arrays / Objects
70
+ expect(array).toContain(item);
71
+ expect(array).toHaveLength(3);
72
+ expect(object).toHaveProperty('key', 'value');
73
+
74
+ // Errors
75
+ expect(() => fn()).toThrow();
76
+ expect(() => fn()).toThrow(ValidationError);
77
+ expect(() => fn()).toThrow('specific message');
78
+
79
+ // Async
80
+ await expect(asyncFn()).resolves.toBe(value);
81
+ await expect(asyncFn()).rejects.toThrow(Error);
82
+ ```
83
+
84
+ ## Mocking Patterns
85
+
86
+ ### Mock Functions
87
+
88
+ ```typescript
89
+ const mockFn = jest.fn();
90
+ mockFn.mockReturnValue(42);
91
+ mockFn.mockResolvedValue({ data: 'test' });
92
+ mockFn.mockImplementation((x) => x * 2);
93
+
94
+ expect(mockFn).toHaveBeenCalled();
95
+ expect(mockFn).toHaveBeenCalledWith('arg1', 'arg2');
96
+ expect(mockFn).toHaveBeenCalledTimes(3);
97
+ ```
98
+
99
+ ### Mock Modules
100
+
101
+ ```typescript
102
+ // Mock an entire module
103
+ jest.mock('./database', () => ({
104
+ query: jest.fn().mockResolvedValue([{ id: 1, title: 'Test' }]),
105
+ }));
106
+
107
+ // Mock specific exports
108
+ jest.mock('./utils', () => ({
109
+ ...jest.requireActual('./utils'),
110
+ generateId: jest.fn().mockReturnValue('test-id'),
111
+ }));
112
+ ```
113
+
114
+ ### Mock at Boundaries Only
115
+
116
+ ```
117
+ Mock these: Don't mock these:
118
+ ├── Database calls ├── Internal utility functions
119
+ ├── HTTP requests ├── Business logic
120
+ ├── File system operations ├── Data transformations
121
+ ├── External API calls ├── Validation functions
122
+ └── Time/Date (when needed) └── Pure functions
123
+ ```
124
+
125
+ ## React/Component Testing
126
+
127
+ ```tsx
128
+ import { render, screen, fireEvent, waitFor } from '@testing-library/react';
129
+
130
+ describe('TaskForm', () => {
131
+ it('submits the form with entered data', async () => {
132
+ const onSubmit = jest.fn();
133
+ render(<TaskForm onSubmit={onSubmit} />);
134
+
135
+ // Find elements by accessible role/label (not test IDs)
136
+ await screen.findByRole('textbox', { name: /title/i });
137
+ fireEvent.change(screen.getByRole('textbox', { name: /title/i }), {
138
+ target: { value: 'New Task' },
139
+ });
140
+ fireEvent.click(screen.getByRole('button', { name: /create/i }));
141
+
142
+ await waitFor(() => {
143
+ expect(onSubmit).toHaveBeenCalledWith({ title: 'New Task' });
144
+ });
145
+ });
146
+
147
+ it('shows validation error for empty title', async () => {
148
+ render(<TaskForm onSubmit={jest.fn()} />);
149
+
150
+ fireEvent.click(screen.getByRole('button', { name: /create/i }));
151
+
152
+ expect(await screen.findByText(/title is required/i)).toBeInTheDocument();
153
+ });
154
+ });
155
+ ```
156
+
157
+ ## API / Integration Testing
158
+
159
+ ```typescript
160
+ import request from 'supertest';
161
+ import { app } from '../src/app';
162
+
163
+ describe('POST /api/tasks', () => {
164
+ it('creates a task and returns 201', async () => {
165
+ const response = await request(app)
166
+ .post('/api/tasks')
167
+ .send({ title: 'Test Task' })
168
+ .set('Authorization', `Bearer ${testToken}`)
169
+ .expect(201);
170
+
171
+ expect(response.body).toMatchObject({
172
+ id: expect.any(String),
173
+ title: 'Test Task',
174
+ status: 'pending',
175
+ });
176
+ });
177
+
178
+ it('returns 422 for invalid input', async () => {
179
+ const response = await request(app)
180
+ .post('/api/tasks')
181
+ .send({ title: '' })
182
+ .set('Authorization', `Bearer ${testToken}`)
183
+ .expect(422);
184
+
185
+ expect(response.body.error.code).toBe('VALIDATION_ERROR');
186
+ });
187
+
188
+ it('returns 401 without authentication', async () => {
189
+ await request(app)
190
+ .post('/api/tasks')
191
+ .send({ title: 'Test' })
192
+ .expect(401);
193
+ });
194
+ });
195
+ ```
196
+
197
+ ## E2E Testing (Playwright)
198
+
199
+ ```typescript
200
+ import { test, expect } from '@playwright/test';
201
+
202
+ test('user can create and complete a task', async ({ page }) => {
203
+ // Navigate and authenticate
204
+ await page.goto('/');
205
+ await page.fill('[name="email"]', 'test@example.com');
206
+ await page.fill('[name="password"]', 'testpass123');
207
+ await page.click('button:has-text("Log in")');
208
+
209
+ // Create a task
210
+ await page.click('button:has-text("New Task")');
211
+ await page.fill('[name="title"]', 'Buy groceries');
212
+ await page.click('button:has-text("Create")');
213
+
214
+ // Verify task appears
215
+ await expect(page.locator('text=Buy groceries')).toBeVisible();
216
+
217
+ // Complete the task
218
+ await page.click('[aria-label="Complete Buy groceries"]');
219
+ await expect(page.locator('text=Buy groceries')).toHaveCSS(
220
+ 'text-decoration-line', 'line-through'
221
+ );
222
+ });
223
+ ```
224
+
225
+ ## Test Anti-Patterns
226
+
227
+ | Anti-Pattern | Problem | Better Approach |
228
+ |---|---|---|
229
+ | Testing implementation details | Breaks on refactor | Test inputs/outputs |
230
+ | Snapshot everything | No one reviews snapshot diffs | Assert specific values |
231
+ | Shared mutable state | Tests pollute each other | Setup/teardown per test |
232
+ | Testing third-party code | Wastes time, not your bug | Mock the boundary |
233
+ | Skipping tests to pass CI | Hides real bugs | Fix or delete the test |
234
+ | Using `test.skip` permanently | Dead code | Remove or fix it |
235
+ | Overly broad assertions | Doesn't catch regressions | Be specific |
236
+ | No async error handling | Swallowed errors, false passes | Always `await` async tests |
@@ -0,0 +1,286 @@
1
+ // scripts/coms-claude-bridge.ts
2
+ //
3
+ // The Claude Code ↔ coms bridge: one bridge per Claude Code pane, launched
4
+ // next to it (the `_claude-peer` recipe backgrounds the bridge in the same
5
+ // herdr pane). It makes an interactive Claude Code a first-class coms peer:
6
+ //
7
+ // (a) binds a coms endpoint + registry entry under --name, so the Claude
8
+ // pane appears in every pool widget and is addressable via coms_send;
9
+ // (b) inbound prompt envelope → pane.send_text into the Claude pane
10
+ // (+ Enter as a separate send — spike quirk);
11
+ // (c) completion, primary path: the Claude Code Stop hook
12
+ // (hooks/coms-stop-hook.mjs) writes the turn's last message to
13
+ // ~/.pi/coms/claude-bridge/<pane>/last-message.json; fallback when no
14
+ // hook has ever fired for this pane: a <<COMS_DONE:msg_id>> sentinel is
15
+ // requested in the prompt and scraped via pane.read after herdr reports
16
+ // the agent done;
17
+ // (d) sends the response envelope back to the sender;
18
+ // (e) a `blocked` agent status returns a readable error envelope instead of
19
+ // hanging until timeout;
20
+ // (f) prompts are strictly serialized per pane; queue depth is reported in
21
+ // the agent card + herdr custom_status.
22
+ //
23
+ // usage: coms-claude-bridge.ts --name <peer-name> [--pane <pane_id>]
24
+ // [--project <p>] [--reply-timeout <ms>]
25
+ // --pane defaults to HERDR_PANE_ID (set inside every herdr pane).
26
+
27
+ import * as fs from "node:fs";
28
+ import * as os from "node:os";
29
+ import * as path from "node:path";
30
+ import { fileURLToPath } from "node:url";
31
+
32
+ import {
33
+ bindEndpoint,
34
+ ensureComsDirs,
35
+ isPromptEnvelope,
36
+ makeConnHandler,
37
+ makeEndpoint,
38
+ makeResponseEnvelope,
39
+ nowIso,
40
+ removeRegistryEntry,
41
+ resolveUniqueName,
42
+ sendEnvelope,
43
+ ulid,
44
+ writeAck,
45
+ writeNack,
46
+ writeRegistryAtomic,
47
+ type AgentCard,
48
+ type PromptEnvelope,
49
+ type RegistryEntry,
50
+ type SenderIdentity,
51
+ } from "./lib/coms-envelope.ts";
52
+ import {
53
+ extractSentinelReply,
54
+ formatPanePrompt,
55
+ parseHookRecord,
56
+ PromptQueue,
57
+ } from "./lib/claude-bridge-core.ts";
58
+ import { herdr, requireHerdr, HerdrUnavailableError } from "../.pi/harnesses/lib/herdr-client.ts";
59
+
60
+ const KEEPALIVE_MS = 30_000;
61
+ const ENTER_DELAY_MS = 1_500;
62
+ const POLL_MS = 1_000;
63
+ const DEFAULT_REPLY_TIMEOUT_MS = 600_000;
64
+ const COLOR = "#FF8B39";
65
+
66
+ function flagValue(argv: string[], flag: string): string | null {
67
+ const i = argv.indexOf(flag);
68
+ return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
69
+ }
70
+
71
+ function die(msg: string): never {
72
+ console.error(`coms-claude-bridge: ${msg}`);
73
+ process.exit(1);
74
+ }
75
+
76
+ export function hookWatchDir(paneId: string): string {
77
+ return path.join(os.homedir(), ".pi", "coms", "claude-bridge", paneId.replace(/[^A-Za-z0-9_-]/g, "_"));
78
+ }
79
+
80
+ async function main(): Promise<void> {
81
+ const argv = process.argv.slice(2);
82
+ const name = flagValue(argv, "--name") ?? die("--name <peer-name> is required");
83
+ const project = flagValue(argv, "--project") ?? "default";
84
+ const paneId = flagValue(argv, "--pane") ?? process.env.HERDR_PANE_ID ?? die("--pane <pane_id> required (or run inside a herdr pane)");
85
+ const replyTimeoutMs = Number(flagValue(argv, "--reply-timeout") ?? DEFAULT_REPLY_TIMEOUT_MS);
86
+
87
+ try {
88
+ await requireHerdr();
89
+ } catch (err) {
90
+ if (err instanceof HerdrUnavailableError) die(err.message);
91
+ throw err;
92
+ }
93
+
94
+ // ── identity ──
95
+ ensureComsDirs(project);
96
+ const sessionId = ulid();
97
+ const uniqueName = resolveUniqueName(project, name);
98
+ const id: SenderIdentity = {
99
+ session_id: sessionId,
100
+ name: uniqueName,
101
+ endpoint: makeEndpoint(sessionId),
102
+ cwd: process.cwd(),
103
+ };
104
+ const queue = new PromptQueue<PromptEnvelope>();
105
+ const purpose = "Claude Code (bridged pane)";
106
+
107
+ function registryEntry(): RegistryEntry {
108
+ return {
109
+ session_id: sessionId,
110
+ name: uniqueName,
111
+ purpose,
112
+ model: "claude-code",
113
+ color: COLOR,
114
+ pid: process.pid,
115
+ endpoint: id.endpoint,
116
+ cwd: id.cwd,
117
+ started_at: nowIso(),
118
+ explicit: false,
119
+ version: 1,
120
+ context_used_pct: 0,
121
+ queue_depth: queue.depth,
122
+ heartbeat_at: nowIso(),
123
+ };
124
+ }
125
+
126
+ const hookDir = hookWatchDir(paneId);
127
+ fs.mkdirSync(hookDir, { recursive: true });
128
+ const hookFile = path.join(hookDir, "last-message.json");
129
+ // Hook mode flips on permanently the first time the Stop hook writes for
130
+ // this pane; until then prompts carry the sentinel instruction.
131
+ let hookSeen = fs.existsSync(hookFile);
132
+
133
+ // ── envelope server ──
134
+ const server = await bindEndpoint(
135
+ id.endpoint,
136
+ makeConnHandler((env, socket) => {
137
+ if (isPromptEnvelope(env)) {
138
+ if (env.hops >= 5) {
139
+ writeNack(socket, env.msg_id, "hops exceeded");
140
+ return;
141
+ }
142
+ queue.push(env);
143
+ writeAck(socket, env.msg_id);
144
+ void pump();
145
+ } else if ((env as { type?: string }).type === "ping") {
146
+ const card: AgentCard = {
147
+ name: uniqueName,
148
+ purpose,
149
+ model: "claude-code",
150
+ color: COLOR,
151
+ context_used_pct: 0,
152
+ queue_depth: queue.depth,
153
+ };
154
+ try {
155
+ socket.write(JSON.stringify({ type: "pong", msg_id: (env as { msg_id?: string }).msg_id ?? "", agent_card: card }) + "\n");
156
+ } catch { /* ignore */ }
157
+ try { socket.end(); } catch { /* ignore */ }
158
+ } else {
159
+ writeNack(socket, (env as { msg_id?: string }).msg_id ?? "", "bridge accepts prompts and pings");
160
+ }
161
+ }),
162
+ );
163
+ writeRegistryAtomic(registryEntry(), project);
164
+ console.error(`coms-claude-bridge: ${uniqueName}@${project} bridging pane ${paneId}`);
165
+
166
+ // ── presence ──
167
+ async function reportPresence(): Promise<void> {
168
+ try {
169
+ await herdr.paneReportMetadata({
170
+ pane_id: paneId,
171
+ source: `coms-bridge:${sessionId}`,
172
+ agent: "claude",
173
+ custom_status: `${uniqueName} q${queue.depth}`.slice(0, 32),
174
+ ttl_ms: 90_000,
175
+ });
176
+ } catch { /* best-effort */ }
177
+ }
178
+ const keepalive = setInterval(() => {
179
+ try {
180
+ writeRegistryAtomic(registryEntry(), project);
181
+ } catch { /* best-effort */ }
182
+ void reportPresence();
183
+ }, KEEPALIVE_MS);
184
+ keepalive.unref?.();
185
+ void reportPresence();
186
+
187
+ // ── prompt processing (strictly serial) ──
188
+ async function pump(): Promise<void> {
189
+ const item = queue.take();
190
+ if (!item) return;
191
+ const env = item.envelope;
192
+ try {
193
+ const reply = await driveClaude(env);
194
+ await sendEnvelope(env.sender_endpoint, makeResponseEnvelope(id, env.msg_id, reply));
195
+ } catch (err) {
196
+ const message = err instanceof Error ? err.message : String(err);
197
+ try {
198
+ await sendEnvelope(env.sender_endpoint, makeResponseEnvelope(id, env.msg_id, null, message));
199
+ } catch {
200
+ console.error(`coms-claude-bridge: could not deliver error for ${env.msg_id}: ${message}`);
201
+ }
202
+ } finally {
203
+ queue.done();
204
+ void reportPresence();
205
+ void pump(); // next in line
206
+ }
207
+ }
208
+
209
+ async function paneStatus(): Promise<string> {
210
+ try {
211
+ const { pane } = await herdr.paneGet(paneId);
212
+ return (pane.agent_status as string) ?? "unknown";
213
+ } catch {
214
+ return "unknown";
215
+ }
216
+ }
217
+
218
+ async function driveClaude(env: PromptEnvelope): Promise<string> {
219
+ const sentinelMode = !hookSeen;
220
+ const hookMtimeBefore = fs.existsSync(hookFile) ? fs.statSync(hookFile).mtimeMs : 0;
221
+
222
+ // Claude Code must be idle-ish before we type into its input box.
223
+ const before = await paneStatus();
224
+ if (before === "working") {
225
+ throw new Error(`Claude Code in pane ${paneId} is mid-turn (working) — try again shortly`);
226
+ }
227
+
228
+ await herdr.paneSendText(paneId, formatPanePrompt(env, sentinelMode));
229
+ await new Promise((r) => setTimeout(r, ENTER_DELAY_MS));
230
+ await herdr.paneSendKeys(paneId, ["enter"]);
231
+
232
+ const deadline = Date.now() + replyTimeoutMs;
233
+ let sawWorking = false;
234
+ while (Date.now() < deadline) {
235
+ await new Promise((r) => setTimeout(r, POLL_MS));
236
+
237
+ // primary: Stop hook wrote a new record
238
+ if (fs.existsSync(hookFile)) {
239
+ const mtime = fs.statSync(hookFile).mtimeMs;
240
+ if (mtime > hookMtimeBefore) {
241
+ const rec = parseHookRecord(fs.readFileSync(hookFile, "utf-8"));
242
+ if (rec) {
243
+ hookSeen = true;
244
+ return rec.text;
245
+ }
246
+ }
247
+ }
248
+
249
+ const status = await paneStatus();
250
+ if (status === "working") sawWorking = true;
251
+ if (status === "blocked") {
252
+ throw new Error(
253
+ `Claude Code in pane ${paneId} is blocked on a permission prompt — a human must approve it in the pane`,
254
+ );
255
+ }
256
+ // fallback: turn ended without a hook record → scrape the sentinel
257
+ if (sentinelMode && sawWorking && (status === "done" || status === "idle")) {
258
+ const read = await herdr.paneRead({ pane_id: paneId, source: "recent", lines: 200 });
259
+ const reply = extractSentinelReply(read.read.text, env.msg_id);
260
+ if (reply) return reply;
261
+ // sentinel not visible yet — keep polling until deadline
262
+ }
263
+ }
264
+ throw new Error(
265
+ `no reply from Claude Code within ${replyTimeoutMs}ms` +
266
+ (sentinelMode ? " (Stop hook not installed? see hooks/coms-stop-hook.mjs)" : ""),
267
+ );
268
+ }
269
+
270
+ // ── shutdown ──
271
+ let shuttingDown = false;
272
+ function shutdown(): void {
273
+ if (shuttingDown) return;
274
+ shuttingDown = true;
275
+ clearInterval(keepalive);
276
+ try { server.close(); } catch { /* ignore */ }
277
+ try { fs.unlinkSync(id.endpoint); } catch { /* ignore */ }
278
+ removeRegistryEntry(project, uniqueName);
279
+ process.exit(0);
280
+ }
281
+ process.on("SIGTERM", shutdown);
282
+ process.on("SIGINT", shutdown);
283
+ }
284
+
285
+ const isEntry = process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
286
+ if (isEntry) void main();