@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,151 @@
1
+ # Fleet Coordination Patterns
2
+
3
+ Runtime coordination protocols for a *fleet* of long-lived agents — peers in herdr panes,
4
+ coms peers, bridged non-pi agents — talking to each other while work is in flight. This is
5
+ the **runtime layer**: message-level protocols between already-running agents.
6
+ [orchestration-patterns.md](orchestration-patterns.md) covers the **composition layer**
7
+ (which personas to invoke and how to wire them: direct invocation, slash-command fan-out,
8
+ Claude Code Agent Teams) — read that one when deciding *who runs*; read this one when
9
+ deciding *how running agents coordinate*.
10
+
11
+ Adapted from the coordination protocols in disler's cmux experiments
12
+ (`PATTERNS-read-and-notify.md`), generalized away from cmux and grounded in this repo's
13
+ mechanisms: coms envelopes (`coms_send`/`coms_await`), the agent-hub Verification
14
+ Contract, and the herdr fleet layer (`team-up`, events, pane control).
15
+
16
+ Each pattern: when to use → protocol → how this repo instantiates it → failure modes.
17
+ Patterns name live mechanisms or say "not implemented here" — nothing aspirational is
18
+ presented as current.
19
+
20
+ ---
21
+
22
+ ## 1. Read-to-decide with sentinels
23
+
24
+ **When:** an orchestrator must branch on another agent's outcome. Prose is not a branch
25
+ condition — an LLM paraphrasing "it mostly works" hides a RED.
26
+
27
+ **Protocol:** the producing agent ends its output with a machine-greppable verdict line
28
+ (`VERDICT=GREEN|RED`, `STATUS: blocked`, …). The consumer greps for the sentinel and
29
+ branches on it — never on its interpretation of the surrounding prose. If the sentinel is
30
+ missing, that is itself a verdict (treat as failure/unknown, never as success).
31
+
32
+ **In this repo (live):**
33
+ - `NEEDS_RESEARCH: <question>` — a specialist pauses for information; the hub runs the
34
+ research and resumes it (agent-hub auto-research pipe).
35
+ - `ASK_USER: <question>` — same protocol toward the human.
36
+ - The structured-return contract — agent-hub specialists return a typed
37
+ `{status, evidence, …}` block that `crossCheck` verifies against the dispatcher's
38
+ acceptance assertions; the *absence* of required evidence fails the gate.
39
+ - The `DIGEST:` contract — delegate children must end with a `DIGEST:` section; a missing
40
+ digest is flagged to the parent instead of silently passing.
41
+ - Phase 4 of the herdr integration adds `<<COMS_DONE:msg_id>>` as the bridge's completion
42
+ sentinel for driving non-pi CLIs.
43
+
44
+ **Failure modes:** sentinel collisions with legitimate output (pick unlikely strings);
45
+ agents *mentioning* the sentinel instead of *emitting* it (grep the last lines only);
46
+ treating a missing sentinel as success.
47
+
48
+ ---
49
+
50
+ ## 2. Push events over polling
51
+
52
+ **When:** an agent waits on another agent's state (done, blocked, alive) and the naive
53
+ implementation is a read-screen/ping loop.
54
+
55
+ **Protocol:** subscribe to a push channel and act on delivery. When polling is truly
56
+ unavoidable, bound it: explicit timeout, capped interval, and a terminal condition that
57
+ cannot be missed.
58
+
59
+ **In this repo (live):**
60
+ - `coms_await` — blocks on the response envelope for a `msg_id` (push) instead of
61
+ polling `coms_get`.
62
+ - The coms presence backend under herdr — the pool widget populates from
63
+ `events.subscribe` (`pane.agent_status_changed`, `pane.created/closed/exited`) instead
64
+ of the 10s ping cycle; the ping loop survives only in the files backend where no push
65
+ channel exists.
66
+ - herdr's blocking waiters — `herdr wait agent-status <pane> --status done` and
67
+ `pane.wait_for_output --match <text>` are server-side waits, not client loops.
68
+
69
+ **Failure modes:** waiting for a state the pane is already in (herdr status waits fire on
70
+ *changes* — read current state first); missed events during a reconnect (resync a
71
+ snapshot on every reconnect, as `HerdrAgentWatch` does); unbounded waits (always pass a
72
+ timeout).
73
+
74
+ ---
75
+
76
+ ## 3. Rendezvous / barriers
77
+
78
+ **When:** work must not proceed past a point until N agents have arrived at it — a
79
+ request needs its response, parallel builders must finish before the verifier runs.
80
+
81
+ **Protocol:** a named wait point. One side blocks on the barrier; the other side's
82
+ arrival (response, completion event) releases it. The barrier has a timeout and a
83
+ defined behavior on partial arrival.
84
+
85
+ **In this repo (live):**
86
+ - `coms_send` + `coms_await` — the request/response barrier between peers: the sender
87
+ blocks on the `msg_id`, the receiver's `agent_end` response capture releases it.
88
+ - The agent-hub dispatcher awaiting parallel dispatches before the Verification
89
+ Contract's gate — no verdict until every specialist's structured return is in.
90
+ - `/handoff` — a full-session barrier: the dispatcher composes a brief, sends it, and
91
+ awaits the peer's acknowledgment before ceding.
92
+
93
+ **Failure modes:** deadlock by mutual await (A awaits B while B awaits A — the coms hop
94
+ limit caps how deep synchronous chains can nest); barriers with no timeout; releasing on
95
+ ack instead of on completion (an ack means "received", not "done" — await the response
96
+ envelope, not the ack).
97
+
98
+ ---
99
+
100
+ ## 4. Fan-out / fan-in with digest discipline
101
+
102
+ **When:** a task shards into parallel independent slices whose results one agent must
103
+ merge — multi-angle reviews, per-module audits, racing hypotheses in debugging.
104
+
105
+ **Protocol:** shard → run in parallel → each worker writes its full output to an on-disk
106
+ artifact and returns only a bounded digest → the merger reads digests, pulls full
107
+ artifacts only where the digest warrants it. Raw dumps never travel upward.
108
+
109
+ **In this repo (live):**
110
+ - `spawn_research` findings files — research helpers write findings to disk; the hub
111
+ reads the file paths, not transcript dumps.
112
+ - The artifact bus — specialists exchange `kind`-tagged artifact files; inputs are
113
+ previews + paths, never inlined full content.
114
+ - The delegate `DIGEST:` contract — children return ≤30 digest lines with `path:line`
115
+ citations plus the result-file path; over-long returns are truncated with a warning.
116
+ - `just team-up <team>` is the fleet-level shard step: one pane per peer, each an
117
+ addressable worker.
118
+
119
+ **Failure modes:** digest inflation (cap lines, require citations); merger re-reading
120
+ every full artifact (defeats the point — pull selectively); shards that were not
121
+ actually independent (merge conflicts surface late; shard along module/file boundaries).
122
+
123
+ ---
124
+
125
+ ## 5. Racing with cancellation
126
+
127
+ **When:** several approaches to the same goal run in parallel and the first valid result
128
+ should win — competing fixes, multiple models on one question.
129
+
130
+ **Protocol:** N agents start; the orchestrator awaits the first result that passes
131
+ validation; every other runner is torn down immediately. Requires real kill semantics
132
+ and a validation step *before* declaring a winner (first ≠ correct).
133
+
134
+ **In this repo:** **not implemented as a first-class mechanism.** The pieces exist —
135
+ herdr `pane.close` / `workspace.close` (and the agent-hub `/agents-kill` command) can
136
+ tear down runners, and `coms_get` can poll multiple pending `msg_id`s — but **coms has no
137
+ cancel envelope**: a losing peer keeps working (and burning tokens) until its turn ends;
138
+ its late response is dropped as an orphan. Racing today means paying for every lane.
139
+ What it would take: a `cancel` envelope type honored mid-turn by peers, or racing only
140
+ runners whose lifecycle the orchestrator owns (herdr panes it may close — see the
141
+ damage-control rules before giving any LLM that verb).
142
+
143
+ **Failure modes:** declaring the fastest answer the best answer (validate first);
144
+ zombie runners after the race (tear down explicitly); racing where lanes share state
145
+ (two builders editing one worktree is a conflict, not a race — isolate worktrees).
146
+
147
+ ---
148
+
149
+ *Composition-layer patterns (which personas, which commands, Agent Teams):*
150
+ [orchestration-patterns.md](orchestration-patterns.md). *The contract the dispatcher
151
+ enforces over all of these:* [skills/orchestration-verification](../skills/orchestration-verification/SKILL.md).
@@ -0,0 +1,91 @@
1
+ # Observability Checklist
2
+
3
+ Quick reference for instrumenting production code. Use alongside the `observability-and-instrumentation` skill.
4
+
5
+ ## Table of Contents
6
+
7
+ - [On-Call Questions (Start Here)](#on-call-questions-start-here)
8
+ - [Structured Logging](#structured-logging)
9
+ - [Metrics](#metrics)
10
+ - [Distributed Tracing](#distributed-tracing)
11
+ - [Alerting](#alerting)
12
+ - [Dashboards](#dashboards)
13
+ - [Verify the Telemetry](#verify-the-telemetry)
14
+ - [Pre-Launch Gate](#pre-launch-gate)
15
+
16
+ ## On-Call Questions (Start Here)
17
+
18
+ Telemetry without a question is noise. Before instrumenting anything:
19
+
20
+ - [ ] 2–4 questions an on-call engineer will ask about this feature are written down
21
+ - [ ] Every signal below maps to one of those questions
22
+ - [ ] Each question is matched to the right signal type: metrics say **that** something is wrong, traces say **where**, logs say **why**
23
+
24
+ ## Structured Logging
25
+
26
+ - [ ] Logs are structured (JSON) with stable event names — not free-form strings
27
+ - [ ] Every log line carries a correlation/request ID, generated or accepted at the system boundary
28
+ - [ ] Correlation ID is propagated on every outbound call and async boundary (HTTP headers, queue metadata)
29
+ - [ ] Log levels are consistent: `error` = invariant broken, someone may act; `warn` = degraded but handled; `info` = significant business event; `debug` = off in production
30
+ - [ ] No secrets, tokens, passwords, or unredacted PII in any log line (hard rule from `security-and-hardening`)
31
+ - [ ] Fields are allowlisted — no whole request/response bodies, no auth headers
32
+ - [ ] External service calls logged with metadata only: endpoint, status, latency, attempt count, sanitized identifiers
33
+ - [ ] Actual log output spot-checked: structured fields, not `[object Object]`
34
+
35
+ ## Metrics
36
+
37
+ - [ ] **RED** instrumented for every endpoint and every external dependency: Rate, Errors, Duration
38
+ - [ ] **USE** instrumented for every resource (queues, pools, hosts): Utilization, Saturation, Errors
39
+ - [ ] Latency is a histogram; p50/p95/p99 queryable — never an average
40
+ - [ ] All labels come from small, fixed sets (route template, status class, provider name)
41
+ - [ ] No unbounded label values: no user IDs, tenant IDs, emails, raw URLs, request IDs, or error message text
42
+ - [ ] Status codes grouped by class (`5xx`, not `503`)
43
+ - [ ] Queue depth and processing duration tracked for every worker/queue
44
+
45
+ ## Distributed Tracing
46
+
47
+ - [ ] OpenTelemetry (or equivalent) initialized at service startup, before other imports
48
+ - [ ] Auto-instrumentation enabled for HTTP, gRPC, and DB clients
49
+ - [ ] Trace context propagated on every outbound call (W3C `traceparent`/`tracestate`) and extracted from every inbound request
50
+ - [ ] Context survives async boundaries — queue messages carry trace metadata
51
+ - [ ] Manual spans only around meaningful internal units of work, with the attributes on-call will filter by
52
+ - [ ] No secrets or PII as span attributes
53
+ - [ ] Head-based sampling at a low default rate; 100% of errors kept if tail sampling is available
54
+
55
+ ## Alerting
56
+
57
+ - [ ] Every alert is symptom-based (error rate, p99 latency, queue age) — causes (CPU, disk, restarts) go to dashboards, not pagers
58
+ - [ ] Every alert is actionable; "ignore it, it self-heals" alerts are deleted
59
+ - [ ] Every alert links to a runbook — minimum three lines: what it means, first query to run, escalation path
60
+ - [ ] Thresholds and durations justified by an SLO or historical data, not guesses
61
+ - [ ] Two severities only: **page** (user-facing, act now) and **ticket** (degradation, act this week)
62
+ - [ ] Each new alert test-fired once: it reached the right channel and the runbook link works
63
+ - [ ] No alerts that fire daily and get acknowledged without action
64
+
65
+ ## Dashboards
66
+
67
+ - [ ] Service health dashboard exists: error rate, latency p99, traffic, saturation
68
+ - [ ] Dependency health panel shows per-service error rates and latency
69
+ - [ ] Dashboard answers the on-call questions from the top of this checklist — not "everything except the answer"
70
+ - [ ] Default time range is sensible (1h–6h, not 30d)
71
+
72
+ ## Verify the Telemetry
73
+
74
+ Instrumentation is code; it can be wrong:
75
+
76
+ - [ ] Forced an error in staging → found it in the logs by correlation ID
77
+ - [ ] Sent test traffic → metric series appear with expected labels and sane values
78
+ - [ ] Followed one request end-to-end in the tracing UI → no broken spans
79
+ - [ ] An induced failure was diagnosed from telemetry alone, without reading the source
80
+
81
+ ## Pre-Launch Gate
82
+
83
+ Before a feature ships to production, all of the following are true:
84
+
85
+ - [ ] Structured logs flowing to the log aggregator
86
+ - [ ] RED metrics visible in dashboards for every new endpoint and dependency
87
+ - [ ] At least one symptom-based alert configured, with runbook, test-fired
88
+ - [ ] A request can be traced across every service it touches
89
+ - [ ] On-call knows where the runbooks are
90
+
91
+ For launch-day monitoring sequence and rollback triggers, see the `shipping-and-launch` skill.
@@ -0,0 +1,370 @@
1
+ # Orchestration Patterns
2
+
3
+ Reference catalog of agent orchestration patterns this repo endorses, plus anti-patterns to avoid. Read this before adding a new slash command that coordinates multiple personas, or before introducing a new persona that "wraps" existing ones. This is the **composition layer** (which personas run and how they're wired); the runtime coordination protocols between already-running agents — sentinels, push events, barriers, fan-in digests, racing — are catalogued in [fleet-coordination-patterns.md](fleet-coordination-patterns.md).
4
+
5
+ The governing rule: **the user (or a slash command) is the orchestrator. Personas do not invoke other personas.** Skills are mandatory hops inside a persona's workflow.
6
+
7
+ ---
8
+
9
+ ## Endorsed patterns
10
+
11
+ ### 1. Direct invocation (no orchestration)
12
+
13
+ Single persona, single perspective, single artifact. The default and the cheapest option.
14
+
15
+ ```
16
+ user → code-reviewer → report → user
17
+ ```
18
+
19
+ **Use when:** the work is one perspective on one artifact and you can describe it in one sentence.
20
+
21
+ **Examples:**
22
+ - "Review this PR" → `code-reviewer`
23
+ - "Find security issues in `auth.ts`" → `security-auditor`
24
+ - "What tests are missing for the checkout flow?" → `test-engineer`
25
+
26
+ **Cost:** one round trip. The baseline you should always compare orchestrated patterns against.
27
+
28
+ ---
29
+
30
+ ### 2. Single-persona slash command
31
+
32
+ A slash command that wraps one persona with the project's skills. Saves the user from re-explaining the workflow every time.
33
+
34
+ ```
35
+ /review → code-reviewer (with code-review-and-quality skill) → report
36
+ ```
37
+
38
+ **Use when:** the same single-persona invocation happens repeatedly with the same setup.
39
+
40
+ **Examples in this repo:** `/review`, `/test`, `/code-simplify`.
41
+
42
+ **Cost:** same as direct invocation. The slash command is just a saved prompt.
43
+
44
+ **Anti-signal:** if the slash command's body is mostly "decide which persona to call," delete it and let the user call the persona directly.
45
+
46
+ ---
47
+
48
+ ### 3. Parallel fan-out with merge
49
+
50
+ Multiple personas operate on the same input concurrently, each producing an independent report. A merge step (in the main agent's context) synthesizes them into a single decision.
51
+
52
+ ```
53
+ ┌─→ code-reviewer ─┐
54
+ /ship → fan out ───┼─→ security-auditor ─┤→ merge → go/no-go + rollback
55
+ └─→ test-engineer ─┘
56
+ ```
57
+
58
+ **Use when:**
59
+ - The sub-tasks are genuinely independent (no shared mutable state, no ordering dependency)
60
+ - Each sub-agent benefits from its own context window
61
+ - The merge step is small enough to stay in the main context
62
+ - Wall-clock latency matters
63
+
64
+ **Examples in this repo:** `/ship`.
65
+
66
+ **Cost:** N parallel sub-agent contexts + one merge turn. Higher than direct invocation, but faster wall-clock and produces better reports because each sub-agent stays focused on its single perspective.
67
+
68
+ **Validation checklist before adopting this pattern:**
69
+ - [ ] Can I run all sub-agents at the same time without ordering issues?
70
+ - [ ] Does each persona produce a different *kind* of finding, not just the same finding from a different angle?
71
+ - [ ] Will the merge step fit in the main agent's remaining context?
72
+ - [ ] Is the user's wait time long enough that parallelism is actually noticeable?
73
+
74
+ If any answer is "no," fall back to direct invocation or a single-persona command.
75
+
76
+ ---
77
+
78
+ ### 4. Sequential pipeline as user-driven slash commands
79
+
80
+ The user runs slash commands in a defined order, carrying context (or commit history) between them. There is no orchestrator agent — the user IS the orchestrator.
81
+
82
+ ```
83
+ user runs: /spec → /plan → /build → /test → /review → /ship
84
+ ```
85
+
86
+ **Use when:** the workflow has dependencies (each step needs the previous step's output) and human judgment between steps adds value.
87
+
88
+ **Examples in this repo:** the entire DEFINE → PLAN → BUILD → VERIFY → REVIEW → SHIP lifecycle.
89
+
90
+ **Cost:** one sub-agent context per step. Free for the orchestration layer because there is no orchestrator agent.
91
+
92
+ **Why not automate it:** an LLM "lifecycle orchestrator" would (a) lose nuance between steps because it has to summarize for hand-off, (b) skip the human checkpoints that catch wrong-direction work early, and (c) double the token cost via paraphrasing turns.
93
+
94
+ ---
95
+
96
+ ### 5. Research isolation (context preservation)
97
+
98
+ When a task requires reading large amounts of material that shouldn't pollute the main context, spawn a research sub-agent that returns only a digest.
99
+
100
+ ```
101
+ main agent → research sub-agent (reads 50 files) → digest → main agent continues
102
+ ```
103
+
104
+ **Use when:**
105
+ - The main session needs to stay focused on a downstream task
106
+ - The investigation result is much smaller than the input it consumes
107
+ - The decision quality benefits from the main agent having room to think after
108
+
109
+ **Examples:** "Find every call site of this deprecated API across the monorepo," "Summarize what these 30 ADRs say about caching."
110
+
111
+ **Cost:** one isolated sub-agent context. Worth it any time the alternative is loading hundreds of files into the main context.
112
+
113
+ **On Claude Code, use the built-in `Explore` subagent** rather than defining a custom research persona. `Explore` runs on Haiku, is denied write/edit tools, and is purpose-built for this pattern. Define a custom research subagent only when `Explore` doesn't fit (e.g. you need a domain-specific system prompt the model wouldn't infer).
114
+
115
+ ---
116
+
117
+ ## Claude Code compatibility
118
+
119
+ This catalog is harness-agnostic, but most readers will run it on Claude Code. Here's how each pattern maps onto Claude Code's primitives — and where the platform enforces our rules for us.
120
+
121
+ ### Where personas live
122
+
123
+ Plugin subagents go in `agents/` at the plugin root. This repo is a plugin (`.claude-plugin/plugin.json`), so `agents/code-reviewer.md`, `agents/security-auditor.md`, and `agents/test-engineer.md` are auto-discovered when the plugin is enabled. No path configuration needed.
124
+
125
+ ### Subagents vs. Agent Teams
126
+
127
+ Claude Code has two parallelism primitives. Pattern 3 (parallel fan-out with merge) maps to **subagents**. If you need teammates that talk to each other, use **Agent Teams** instead.
128
+
129
+ | | Subagents | Agent Teams |
130
+ |--|-----------|-------------|
131
+ | Coordination | Main agent fans out, sub-agents only report back | Teammates message each other, share a task list |
132
+ | Context | Own context window per subagent | Own context window per teammate |
133
+ | When to use | Independent tasks producing reports | Collaborative work needing discussion |
134
+ | Status | Stable | Experimental — requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` |
135
+ | Cost | Lower | Higher — each teammate is a separate Claude instance |
136
+
137
+ **The personas in this repo work in both modes.** When spawned as subagents (e.g. by `/ship`), they report findings to the main session. When spawned as teammates (`Spawn a teammate using the security-auditor agent type…`), they can challenge each other's findings directly. The persona definition is the same; only the spawning context changes.
138
+
139
+ One subtlety: the `skills` and `mcpServers` frontmatter fields in a persona are honored when it runs as a subagent but **ignored when it runs as a teammate** — teammates load skills and MCP servers from your project and user settings, the same as a regular session. If a persona depends on a specific skill or MCP server being loaded, configure it at the session level so it's available in both modes.
140
+
141
+ ### Platform-enforced rules
142
+
143
+ Two rules in this catalog aren't just convention — Claude Code enforces them:
144
+
145
+ - **"Subagents cannot spawn other subagents"** (verbatim from the docs). Anti-pattern B (persona-calls-persona) and Anti-pattern D (deep persona trees) cannot exist on Claude Code by construction.
146
+ - **"No nested teams"** — teammates cannot spawn their own teams. Same anti-patterns blocked at the team level.
147
+
148
+ This means you can adopt the patterns in this catalog without worrying about contributors accidentally building the anti-patterns. They'll just fail to load.
149
+
150
+ ### Built-in subagents to know about
151
+
152
+ Before defining a custom subagent, check whether one of these covers the role:
153
+
154
+ | Built-in | Purpose |
155
+ |----------|---------|
156
+ | `Explore` | Read-only codebase search and analysis. Use this for Pattern 5 (research isolation). |
157
+ | `Plan` | Read-only research during plan mode. |
158
+ | `general-purpose` | Multi-step tasks needing both exploration and modification. |
159
+
160
+ Don't redefine these. Layer your specialist personas (code-reviewer, security-auditor, test-engineer) on top of them.
161
+
162
+ ### Frontmatter restrictions for plugin agents
163
+
164
+ Plugin subagents do **not** support the `hooks`, `mcpServers`, or `permissionMode` frontmatter fields — these are silently ignored. If a future persona needs any of those, the user must copy the file into `.claude/agents/` or `~/.claude/agents/` instead.
165
+
166
+ The fields that DO work in plugin agents are: `name`, `description`, `tools`, `disallowedTools`, `model`, `maxTurns`, `skills`, `memory`, `background`, `effort`, `isolation`, `color`, `initialPrompt`. Use `model` per-persona if you want to optimize cost (e.g. Haiku for `test-engineer` coverage scans, Sonnet for `code-reviewer`, Opus for `security-auditor`).
167
+
168
+ ### Spawning multiple subagents in parallel
169
+
170
+ In Claude Code, parallel fan-out (Pattern 3) requires issuing **multiple Agent tool calls in a single assistant turn**. Sequential turns serialize execution. `/ship` calls this out explicitly. Any new orchestrator command should do the same.
171
+
172
+ ---
173
+
174
+ ## Worked example: Agent Teams for competing-hypothesis debugging
175
+
176
+ This example shows when to reach for **Agent Teams** instead of `/ship`'s subagent fan-out. The two patterns look similar from a distance — both spawn the same three personas — but the value comes from a different place.
177
+
178
+ ### The scenario
179
+
180
+ > *Checkout occasionally hangs for ~30 seconds before completing. It happens roughly once every 50 sessions. No errors in logs. Started after last week's release.*
181
+
182
+ Plausible root causes (mutually exclusive, all fit the symptoms):
183
+
184
+ 1. A race condition in the new payment-confirmation flow
185
+ 2. An auth check that occasionally falls through to a slow synchronous network call
186
+ 3. A missing index on a query that scales with cart size
187
+ 4. A flaky third-party API where the SDK retries silently before timing out
188
+
189
+ A single agent will pick the first plausible theory and stop investigating. A `/ship`-style subagent fan-out would have each persona report independently — but their reports never meet, so nothing rules out the wrong theories.
190
+
191
+ This is exactly the case the Agent Teams docs describe: *"With multiple independent investigators actively trying to disprove each other, the theory that survives is much more likely to be the actual root cause."*
192
+
193
+ ### Why this is *not* a `/ship` job
194
+
195
+ | | `/ship` (subagents) | Agent Teams |
196
+ |--|--------------------|-------------|
197
+ | Sub-agents see | The same diff, different lenses | A shared task list, each other's messages |
198
+ | Output | Three independent reports → one merge | Adversarial debate → consensus root cause |
199
+ | Right when | You want a verdict on a known artifact | You want to *find* the artifact among hypotheses |
200
+
201
+ `/ship` is a verdict; Agent Teams is an investigation.
202
+
203
+ ### Setup (one-time, per-environment)
204
+
205
+ Agent Teams is experimental. In `~/.claude/settings.json`:
206
+
207
+ ```json
208
+ {
209
+ "env": {
210
+ "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
211
+ }
212
+ }
213
+ ```
214
+
215
+ Requires Claude Code v2.1.32 or later. The personas in this repo are picked up automatically — no team-config files to author by hand.
216
+
217
+ ### The trigger prompt
218
+
219
+ Type into the lead session, in natural language:
220
+
221
+ ```
222
+ Users report checkout hangs for ~30 seconds intermittently after last
223
+ week's release. No errors in logs.
224
+
225
+ Create an agent team to debug this with competing hypotheses. Spawn
226
+ three teammates using the existing agent types:
227
+
228
+ - code-reviewer — investigate race conditions and blocking calls
229
+ in the checkout code path
230
+ - security-auditor — investigate auth checks, session handling,
231
+ and any synchronous network calls added recently
232
+ - test-engineer — propose tests that would distinguish between the
233
+ hypotheses and check coverage gaps in checkout
234
+
235
+ Have them message each other directly to challenge each other's
236
+ theories. Update findings as consensus emerges. Only converge when
237
+ two teammates agree they can disprove the others'.
238
+ ```
239
+
240
+ The lead spawns three teammates referencing the existing persona names. The persona body is **appended** to each teammate's system prompt as additional instructions (on top of the team-coordination instructions the lead installs); the trigger prompt above becomes their task.
241
+
242
+ ### What happens
243
+
244
+ 1. Each teammate runs in its own context window, exploring the codebase from its own lens.
245
+ 2. Teammates use `message` to send findings to each other directly. The lead doesn't have to relay.
246
+ 3. The shared task list shows who's investigating what — visible at any time with `Ctrl+T` (in-process mode) or in a tmux pane (split mode; tmux here is Claude Code Agent Teams' own split-mode mechanism, not this repo's fleet tooling — our fleet layer runs on herdr).
247
+ 4. When `code-reviewer` finds a `Promise.all` that should be sequential, it messages `security-auditor` to confirm the auth call isn't part of the race. `security-auditor` checks and replies — either confirming the race is the real issue or producing counter-evidence.
248
+ 5. `test-engineer` proposes a focused integration test for whichever theory is winning, which the team uses to verify before declaring consensus.
249
+ 6. The lead synthesizes the converged finding and presents it to you.
250
+
251
+ You can interrupt at any teammate by cycling with `Shift+Down` and typing — useful for redirecting an investigator who's gone down a wrong path.
252
+
253
+ ### When to clean up
254
+
255
+ When the investigation lands on a root cause, tell the lead:
256
+
257
+ ```
258
+ Clean up the team
259
+ ```
260
+
261
+ Always cleanup through the lead, not a teammate (per the docs: teammates lack full team context for cleanup).
262
+
263
+ ### Cost expectation
264
+
265
+ Three Sonnet teammates running for ~10–15 minutes of investigation costs noticeably more than the same three personas spawned as subagents by `/ship`. The justification is *quality of conclusion* — for production debugging where the wrong fix is expensive, the extra tokens are a bargain. For a routine PR review, stick with `/ship`.
266
+
267
+ ### Anti-pattern in this scenario
268
+
269
+ Do **not** rebuild this as a `/debug` slash command that fans out subagents. Subagents can't message each other — you'd lose the adversarial debate that makes the pattern work. If a workflow keeps coming up, document the trigger prompt above as a snippet rather than wrapping it in a slash command that misuses subagents.
270
+
271
+ ### When *not* to use Agent Teams
272
+
273
+ - Production-bound verdict on a known diff → use `/ship` (subagents).
274
+ - One specialist perspective on one artifact → direct persona invocation.
275
+ - Sequential lifecycle (spec → plan → build) → user-driven slash commands (Pattern 4).
276
+ - Read-heavy research with a small digest → built-in `Explore` subagent.
277
+
278
+ Reach for Agent Teams only when teammates **need** to challenge each other to produce the right answer.
279
+
280
+ ---
281
+
282
+ ## Anti-patterns
283
+
284
+ ### A. Router persona ("meta-orchestrator")
285
+
286
+ A persona whose job is to decide which other persona to call.
287
+
288
+ ```
289
+ /work → router-persona → "this needs a review" → code-reviewer → router (paraphrases) → user
290
+ ```
291
+
292
+ **Why it fails:**
293
+ - Pure routing layer with no domain value
294
+ - Adds two paraphrasing hops → information loss + roughly 2× token cost
295
+ - The user already knew they wanted a review; they could have called `/review` directly
296
+ - Replicates the work that slash commands and intent mapping in `AGENTS.md` already do
297
+
298
+ **What to do instead:** add or refine slash commands. Document intent → command mapping in `AGENTS.md`.
299
+
300
+ ---
301
+
302
+ ### B. Persona that calls another persona
303
+
304
+ A `code-reviewer` that internally invokes `security-auditor` when it sees auth code.
305
+
306
+ **Why it fails:**
307
+ - Personas were designed to produce a single perspective; chaining them defeats that
308
+ - The summary the calling persona passes loses context the called persona needs
309
+ - Failure modes multiply (which persona's output format wins? whose rules apply?)
310
+ - Hides cost from the user
311
+
312
+ **What to do instead:** have the calling persona *recommend* a follow-up audit in its report. The user or a slash command runs the second pass.
313
+
314
+ ---
315
+
316
+ ### C. Sequential orchestrator that paraphrases
317
+
318
+ An agent that calls `/spec`, then `/plan`, then `/build`, etc. on the user's behalf.
319
+
320
+ **Why it fails:**
321
+ - Loses the human checkpoints that catch wrong-direction work
322
+ - Each hand-off summarizes context — accumulated drift over a long pipeline
323
+ - Doubles token cost: orchestrator turn + sub-agent turn for every step
324
+ - Removes user agency at exactly the points where judgment matters most
325
+
326
+ **What to do instead:** keep the user as the orchestrator. Document the recommended sequence in `README.md` and let users invoke it.
327
+
328
+ ---
329
+
330
+ ### D. Deep persona trees
331
+
332
+ `/ship` calls a `pre-ship-coordinator` that calls a `quality-coordinator` that calls `code-reviewer`.
333
+
334
+ **Why it fails:**
335
+ - Each layer adds latency and tokens with no decision value
336
+ - Debugging becomes a multi-level investigation
337
+ - The leaf personas lose context to multiple summarization steps
338
+
339
+ **What to do instead:** keep the orchestration depth at most 1 (slash command → personas). The merge happens in the main agent.
340
+
341
+ ---
342
+
343
+ ## Decision flow
344
+
345
+ When considering a new orchestrated workflow, walk this flow:
346
+
347
+ ```
348
+ Is the work one perspective on one artifact?
349
+ ├── Yes → Direct invocation. Stop.
350
+ └── No → Will the same composition repeat?
351
+ ├── No → Direct invocation, ad hoc. Stop.
352
+ └── Yes → Are sub-tasks independent?
353
+ ├── No → Sequential slash commands run by user (Pattern 4).
354
+ └── Yes → Parallel fan-out with merge (Pattern 3).
355
+ Validate against the checklist above.
356
+ If any check fails → fall back to single-persona command (Pattern 2).
357
+ ```
358
+
359
+ ---
360
+
361
+ ## When to add a new pattern to this catalog
362
+
363
+ Add a new entry only after:
364
+
365
+ 1. You've used the pattern at least twice in real work
366
+ 2. You can name a concrete artifact in this repo that demonstrates it
367
+ 3. You can explain why an existing pattern wouldn't have worked
368
+ 4. You can describe its anti-pattern shadow (what people will mistakenly build instead)
369
+
370
+ Premature catalog entries become aspirational documentation that no one follows.