@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,153 @@
1
+ # Performance Checklist
2
+
3
+ Quick reference checklist for web application performance. Use alongside the `performance-optimization` skill.
4
+
5
+ ## Table of Contents
6
+
7
+ - [Core Web Vitals Targets](#core-web-vitals-targets)
8
+ - [TTFB Diagnosis](#ttfb-diagnosis)
9
+ - [Frontend Checklist](#frontend-checklist)
10
+ - [Backend Checklist](#backend-checklist)
11
+ - [Measurement Commands](#measurement-commands)
12
+ - [Common Anti-Patterns](#common-anti-patterns)
13
+
14
+ ## Core Web Vitals Targets
15
+
16
+ | Metric | Good | Needs Work | Poor |
17
+ |--------|------|------------|------|
18
+ | LCP (Largest Contentful Paint) | ≤ 2.5s | ≤ 4.0s | > 4.0s |
19
+ | INP (Interaction to Next Paint) | ≤ 200ms | ≤ 500ms | > 500ms |
20
+ | CLS (Cumulative Layout Shift) | ≤ 0.1 | ≤ 0.25 | > 0.25 |
21
+
22
+ ## TTFB Diagnosis
23
+
24
+ When TTFB is slow (> 800ms), check each component in DevTools Network waterfall:
25
+
26
+ - [ ] **DNS resolution** slow → add `<link rel="dns-prefetch">` or `<link rel="preconnect">` for known origins
27
+ - [ ] **TCP/TLS handshake** slow → enable HTTP/2, consider edge deployment, verify keep-alive
28
+ - [ ] **Server processing** slow → profile backend, check slow queries, add caching
29
+
30
+ ## Frontend Checklist
31
+
32
+ ### Images
33
+ - [ ] Images use modern formats (WebP, AVIF)
34
+ - [ ] Images are responsively sized (`srcset` and `sizes`)
35
+ - [ ] Images and `<source>` elements have explicit `width` and `height` (prevents CLS in art direction)
36
+ - [ ] Below-the-fold images use `loading="lazy"` and `decoding="async"`
37
+ - [ ] Hero/LCP images use `fetchpriority="high"` and no lazy loading
38
+
39
+ ### JavaScript
40
+ - [ ] Bundle size under 200KB gzipped (initial load)
41
+ - [ ] Code splitting with dynamic `import()` for routes and heavy features
42
+ - [ ] Tree shaking enabled (verify dependency ships ESM and marks `sideEffects: false`)
43
+ - [ ] No blocking JavaScript in `<head>` (use `defer` or `async`)
44
+ - [ ] Heavy computation offloaded to Web Workers (if applicable)
45
+ - [ ] `React.memo()` on expensive components that re-render with same props
46
+ - [ ] `useMemo()` / `useCallback()` only where profiling shows benefit
47
+ - [ ] Long tasks (> 50ms) broken up to keep the main thread available — main lever for INP
48
+ - [ ] `yieldToMain` pattern used inside long-running loops so input events can run between chunks
49
+ - [ ] Modern scheduling APIs used where available: `scheduler.yield()` (preferred), `scheduler.postTask()` with priorities, `isInputPending()` to yield only when needed
50
+ - [ ] `requestIdleCallback` for deferrable, non-urgent work (analytics flush, prefetch, warmup)
51
+ - [ ] Non-critical work deferred out of event handlers (e.g. analytics, logging) so the response to the interaction is not delayed
52
+ - [ ] Third-party scripts loaded with `async` / `defer`, audited for size, and fronted by a facade when heavy (chat widgets, embeds)
53
+
54
+ ### CSS
55
+ - [ ] Critical CSS inlined or preloaded
56
+ - [ ] No render-blocking CSS for non-critical styles
57
+ - [ ] No CSS-in-JS runtime cost in production (use extraction)
58
+
59
+ ### Fonts
60
+ - [ ] Limited to 2–3 font families, 2–3 weights each (every additional weight is another request)
61
+ - [ ] WOFF2 format only (smallest, universal support — skip WOFF/TTF/EOT)
62
+ - [ ] Self-hosted when possible (third-party font CDNs add DNS + TCP + TLS round-trips)
63
+ - [ ] LCP-critical fonts preloaded: `<link rel="preload" as="font" type="font/woff2" crossorigin>`
64
+ - [ ] `font-display: swap` (or `optional` for non-critical) to avoid FOIT blocking render
65
+ - [ ] Subsetted via `unicode-range` to ship only the glyphs each page needs
66
+ - [ ] Variable fonts considered when multiple weights/styles are required (one file replaces many)
67
+ - [ ] Fallback font metrics adjusted with `size-adjust`, `ascent-override`, `descent-override` to reduce CLS on font swap
68
+ - [ ] System font stack considered before any custom font
69
+
70
+ ### Network
71
+ - [ ] Static assets cached with long `max-age` + content hashing
72
+ - [ ] API responses cached where appropriate (`Cache-Control`)
73
+ - [ ] HTTP/2 or HTTP/3 enabled
74
+ - [ ] Resources preconnected (`<link rel="preconnect">`) for known origins
75
+ - [ ] `fetchpriority` used on critical non-image resources (e.g., key `<link rel="preload">`, above-the-fold `<script>`) — not only on `<img>`
76
+ - [ ] No unnecessary redirects
77
+
78
+ ### Rendering
79
+ - [ ] No layout thrashing (forced synchronous layouts)
80
+ - [ ] Animations use `transform` and `opacity` (GPU-accelerated)
81
+ - [ ] Long lists use virtualization (e.g., `react-window`)
82
+ - [ ] No unnecessary full-page re-renders
83
+ - [ ] Off-screen sections use `content-visibility: auto` with `contain-intrinsic-size` to skip layout/paint of non-visible areas
84
+ - [ ] No `unload` event handlers and no `Cache-Control: no-store` on HTML responses — preserves back/forward cache (bfcache) eligibility
85
+
86
+ ## Backend Checklist
87
+
88
+ ### Database
89
+ - [ ] No N+1 query patterns (use eager loading / joins)
90
+ - [ ] Queries have appropriate indexes
91
+ - [ ] List endpoints paginated (never `SELECT * FROM table`)
92
+ - [ ] Connection pooling configured
93
+ - [ ] Slow query logging enabled
94
+
95
+ ### API
96
+ - [ ] Response times < 200ms (p95)
97
+ - [ ] No synchronous heavy computation in request handlers
98
+ - [ ] Bulk operations instead of loops of individual calls
99
+ - [ ] Response compression (gzip/brotli)
100
+ - [ ] Appropriate caching (in-memory, Redis, CDN)
101
+
102
+ ### Infrastructure
103
+ - [ ] CDN for static assets
104
+ - [ ] Server located close to users (or edge deployment)
105
+ - [ ] Horizontal scaling configured (if needed)
106
+ - [ ] Health check endpoint for load balancer
107
+
108
+ ## Measurement Commands
109
+
110
+ ### INP field data and DevTools workflow
111
+
112
+ 1. **Field data first** — check [CrUX Vis](https://developer.chrome.com/docs/crux/vis) or your RUM tool for real-user INP before optimising
113
+ 2. **Identify slow interactions** — open DevTools → Performance panel → record while interacting; look for long tasks triggered by clicks/keystrokes
114
+ 3. **Test on mid-range Android** — INP issues often only surface on slower hardware; use a real device or DevTools CPU throttling (4×–6× slowdown)
115
+
116
+ ```bash
117
+ # Lighthouse CLI
118
+ npx lighthouse https://localhost:3000 --output json --output-path ./report.json
119
+
120
+ # Bundle analysis
121
+ npx webpack-bundle-analyzer stats.json
122
+ # or for Vite:
123
+ npx vite-bundle-visualizer
124
+
125
+ # Check bundle size
126
+ npx bundlesize
127
+
128
+ # Web Vitals in code
129
+ import { onLCP, onINP, onCLS } from 'web-vitals';
130
+ onLCP(console.log);
131
+ onINP(console.log);
132
+ onCLS(console.log);
133
+
134
+ # INP with interaction-level detail (attribution build)
135
+ import { onINP } from 'web-vitals/attribution';
136
+ onINP(({ value, attribution }) => {
137
+ const { interactionTarget, inputDelay, processingDuration, presentationDelay } = attribution;
138
+ console.log({ value, interactionTarget, inputDelay, processingDuration, presentationDelay });
139
+ });
140
+ ```
141
+
142
+ ## Common Anti-Patterns
143
+
144
+ | Anti-Pattern | Impact | Fix |
145
+ |---|---|---|
146
+ | N+1 queries | Linear DB load growth | Use joins, includes, or batch loading |
147
+ | Unbounded queries | Memory exhaustion, timeouts | Always paginate, add LIMIT |
148
+ | Missing indexes | Slow reads as data grows | Add indexes for filtered/sorted columns |
149
+ | Layout thrashing | Jank, dropped frames | Batch DOM reads, then batch writes |
150
+ | Unoptimized images | Slow LCP, wasted bandwidth | Use WebP, responsive sizes, lazy load |
151
+ | Large bundles | Slow Time to Interactive | Code split, tree shake, audit deps |
152
+ | Blocking main thread | Poor INP, unresponsive UI | Chunk long tasks with `scheduler.yield()` / `yieldToMain`, offload to Web Workers |
153
+ | Memory leaks | Growing memory, eventual crash | Clean up listeners, intervals, refs |
@@ -0,0 +1,380 @@
1
+ # Prompting Patterns Reference
2
+
3
+ Consolidated prompt-engineering best practices for authoring instructions that coding agents will follow. Use alongside the `designing-agents`, `context-engineering`, and `using-agent-skills` skills, and consult this file before finalizing any agent persona, slash command, skill, pi harness, or rule file.
4
+
5
+ ## How to Use This Reference
6
+
7
+ Three primary audiences:
8
+
9
+ 1. **Persona authors** writing files under `agents/` — check sections 1-3, 6, 7, 12 before writing.
10
+ 2. **Skill authors** writing files under `skills/` — check sections 1, 2, 4, 6.4, 7, 12 before writing.
11
+ 3. **Rule-file authors** writing project rules (CLAUDE.md, AGENTS.md, or supplementary rule files) — check sections 1.4, 2, 9, 11, 12.
12
+
13
+ Source attribution key: **[A]** = Anthropic, **[O]** = OpenAI, **[A+O]** = both vendors agree.
14
+
15
+ ## Table of Contents
16
+
17
+ 1. [Structural Foundations](#1-structural-foundations)
18
+ 2. [Clarity and Specificity](#2-clarity-and-specificity)
19
+ 3. [Role and Identity](#3-role-and-identity)
20
+ 4. [Examples (Few-Shot Prompting)](#4-examples-few-shot-prompting)
21
+ 5. [Tool Use and Function Calling](#5-tool-use-and-function-calling)
22
+ 6. [Agentic Behavior](#6-agentic-behavior)
23
+ 7. [Output Control](#7-output-control)
24
+ 8. [Thinking and Reasoning](#8-thinking-and-reasoning)
25
+ 9. [Layered Configuration Architecture](#9-layered-configuration-architecture)
26
+ 10. [Long-Horizon and Multi-Session Workflows](#10-long-horizon-and-multi-session-workflows)
27
+ 11. [Prompt Maintenance and Iteration](#11-prompt-maintenance-and-iteration)
28
+ 12. [Anti-Patterns to Avoid](#12-anti-patterns-to-avoid)
29
+ 13. [Sources](#sources)
30
+
31
+ ---
32
+
33
+ ## 1. Structural Foundations
34
+
35
+ ### 1.1 Use a Clear, Hierarchical Section Layout [A+O]
36
+
37
+ Structure prompts and rules with labeled sections using Markdown headers or XML tags. A recommended template:
38
+
39
+ ```
40
+ # Role and Objective
41
+ # Instructions
42
+ ## Sub-categories
43
+ # Constraints
44
+ # Output Format
45
+ # Examples
46
+ ```
47
+
48
+ - **[O]** Models trained on instruction-following (GPT-4.1+, Claude 4+) follow instructions more literally. Clear section labels help the model locate and apply the right rules at the right time.
49
+ - **[A]** Use numbered lists or bullet points when order or completeness matters.
50
+
51
+ ### 1.2 Use XML Tags for Structured Sections [A+O]
52
+
53
+ - **[A]** XML tags are the preferred delimiter for separating instructions, context, examples, and variable inputs. Use consistent, descriptive tag names (`<instructions>`, `<context>`, `<constraints>`). Nest tags when content has natural hierarchy.
54
+ - **[O]** Use XML tags for nested examples and metadata-tagged documents. Use Markdown for prose sections.
55
+ - **[A+O]** Avoid JSON for large document collections — both vendors report performance degradation.
56
+
57
+ ### 1.3 Instruction Placement Strategy [O]
58
+
59
+ For long-context prompts (20K+ tokens), place critical instructions at both the beginning **and** end of the prompt (the "sandwich" approach). This yields the best retrieval and adherence rates.
60
+
61
+ ### 1.4 Put Data Above Instructions [A]
62
+
63
+ Place longform data (documents, code, reference material) at the top of the prompt, with instructions and queries at the end. Anthropic testing showed up to 30% improved response quality.
64
+
65
+ ### 1.5 Later Instructions Take Priority [O]
66
+
67
+ In GPT-4.1+, when instructions conflict, the model prioritizes instructions appearing later. Use this to create a natural override hierarchy — put the most specific or important rules last.
68
+
69
+ ---
70
+
71
+ ## 2. Clarity and Specificity
72
+
73
+ ### 2.1 Be Explicit, Not Implicit [A+O]
74
+
75
+ Treat the model like a brilliant but new team member who lacks context on your norms. Specify everything explicitly.
76
+
77
+ - **[A]** Golden rule: show your prompt to a colleague with minimal context. If they would be confused, the model will be too.
78
+ - **[O]** Newer models do exactly what you say. A single clarifying sentence can redirect behavior, but omissions lead to undesired output.
79
+ - **[A+O]** Instead of "write clean code," specify: "Use descriptive variable names. Extract repeated logic into helpers. Add JSDoc to exported functions."
80
+
81
+ ### 2.2 Tell the Model What TO DO, Not What NOT to Do [A]
82
+
83
+ Positive instructions are more effective than prohibitions.
84
+
85
+ - Instead of: "Do not use markdown"
86
+ - Write: "Your response should be composed of smoothly flowing prose paragraphs."
87
+
88
+ ### 2.3 Explain WHY Behind Rules [A]
89
+
90
+ Providing motivation behind instructions helps the model generalize correctly and handle edge cases better.
91
+
92
+ - Instead of: "NEVER use ellipses"
93
+ - Write: "Never use ellipses because the response will be read aloud by a text-to-speech engine that cannot pronounce them."
94
+ - Instead of: "Always use absolute paths"
95
+ - Write: "Use absolute paths because the working directory resets between shell calls, so relative paths will break."
96
+
97
+ ### 2.4 Eliminate Contradictions [O]
98
+
99
+ Thoroughly review prompts for ambiguities and contradictions. Reasoning models (o1/o3, Claude extended thinking) expend tokens trying to reconcile conflicting directives rather than ignoring them.
100
+
101
+ - Example conflict: "Be concise" + "Err on the side of completeness."
102
+ - Resolution: "Default to concise responses (2-5 sentences). Provide detailed responses only when the change spans more than 3 files or the user explicitly requests detail."
103
+
104
+ ### 2.5 Remove Unnecessary Emphasis Patterns [A+O]
105
+
106
+ - **[O]** Avoid ALL-CAPS emphasis and reward/punishment language. These are unnecessary for modern models (GPT-4.1+) and can be counterproductive.
107
+ - **[A]** Replace "CRITICAL: You MUST use this tool when..." with normal language like "Use this tool when..." Claude 4+ models are significantly more responsive to the system prompt; aggressive language causes overtriggering.
108
+
109
+ ---
110
+
111
+ ## 3. Role and Identity
112
+
113
+ ### 3.1 Set a Role [A+O]
114
+
115
+ - **[A]** Set a role in the system prompt to focus behavior and tone. Even a single sentence makes a difference.
116
+ - **[O]** Frame coding agents as an autonomous senior pair-programmer who gathers context, plans, implements, tests, and refines without waiting for intermediate prompts.
117
+
118
+ ### 3.2 Scale Role Complexity to Task [A]
119
+
120
+ For simple tasks, a one-line role suffices. For complex agent systems, describe the persona's expertise, priorities, and behavioral constraints in detail.
121
+
122
+ ---
123
+
124
+ ## 4. Examples (Few-Shot Prompting)
125
+
126
+ ### 4.1 Include Relevant Examples [A+O]
127
+
128
+ - **[A]** Include 3-5 well-crafted examples to steer output format, tone, and structure. Wrap examples in `<example>` tags so the model distinguishes them from instructions.
129
+ - **[O]** Combine few-shot examples into a concise YAML-style or bulleted block. Place them in a dedicated `# Examples` section.
130
+
131
+ ### 4.2 Example Quality Requirements [A]
132
+
133
+ Good examples must be:
134
+ - **Relevant** — mirror your actual use case closely.
135
+ - **Diverse** — cover edge cases to prevent unintended pattern-matching.
136
+ - **Structured** — wrapped in tags to distinguish from instructions.
137
+
138
+ ### 4.3 Reasoning Models Need Fewer Examples [O]
139
+
140
+ For reasoning models (o1/o3), use zero-shot or at most one example. Multiple examples constrain internal reasoning rather than helping it.
141
+
142
+ ### 4.4 Show Reasoning Patterns in Examples [A]
143
+
144
+ Include `<thinking>` tags inside few-shot examples to demonstrate desired reasoning patterns. The model will generalize that reasoning style.
145
+
146
+ ---
147
+
148
+ ## 5. Tool Use and Function Calling
149
+
150
+ ### 5.1 Use Native API Tool Definitions [O]
151
+
152
+ Use the API-native `tools` field rather than manually injecting tool descriptions into prompt text. OpenAI testing showed 2% performance gain.
153
+
154
+ ### 5.2 Tool Description Best Practices [A+O]
155
+
156
+ - **[A+O]** Use clear, semantically meaningful tool names.
157
+ - **[O]** Include "when to use" and "when not to use" guidance.
158
+ - **[O]** Add a safety valve: "If insufficient information to call the tool, ask the user."
159
+ - **[A]** Use normal language instead of aggressive prompting. Replace "Default to using [tool]" with "Use [tool] when it would enhance your understanding of the problem."
160
+
161
+ ### 5.3 Enable Parallel Tool Calls [A+O]
162
+
163
+ - **[A+O]** Explicitly prompt for parallel tool execution when calls are independent.
164
+ - **[A]** Recommended phrasing: "If you intend to call multiple tools and there are no dependencies between the tool calls, make all independent calls in parallel. If some calls depend on previous results, do NOT call them in parallel."
165
+ - **[O]** "Think first before any tool call and decide all needed files upfront. Batch everything together."
166
+
167
+ ### 5.4 Prefer Dedicated Tools Over Shell [A+O]
168
+
169
+ - **[A]** Use Read instead of cat, Edit instead of sed, Grep instead of grep.
170
+ - **[O]** Use apply_patch, read_file, semantic_search as defaults. Only invoke the shell when no specialized tool exists.
171
+
172
+ ### 5.5 Add Tools Incrementally [O]
173
+
174
+ Start with 1-2 tools that eliminate current manual loops. Adding too many tools at once confuses tool selection and increases incorrect calls.
175
+
176
+ ---
177
+
178
+ ## 6. Agentic Behavior
179
+
180
+ ### 6.1 The Three Critical Agent Instructions [O]
181
+
182
+ Anchor every coding agent prompt with:
183
+
184
+ 1. **Persistence:** "Keep going until the user's query is completely resolved. Only terminate when you are sure the problem is solved."
185
+ 2. **Tool utilization:** "If you are not sure about file content or codebase structure, use your tools to read files. Do NOT guess or make up an answer."
186
+ 3. **Planning:** Require explicit reasoning steps before tool calls rather than silent tool-call chains.
187
+
188
+ OpenAI testing showed these three instructions boosted SWE-bench scores by ~20%.
189
+
190
+ ### 6.2 Provide Clear Completion Criteria [O]
191
+
192
+ Every task prompt should include a "Done When" section. Example: "Done when: all existing tests pass, the new endpoint returns the correct schema, and no TypeScript errors remain."
193
+
194
+ ### 6.3 Investigate Before Answering [A]
195
+
196
+ Never speculate about code you have not opened. If the user references a specific file, read it before answering. Give grounded, hallucination-free answers.
197
+
198
+ ### 6.4 Prevent Overengineering [A]
199
+
200
+ Explicitly instruct:
201
+ - Do not add features, refactor code, or make "improvements" beyond what was asked.
202
+ - Do not add docstrings, comments, or type annotations to code you did not change.
203
+ - Do not add error handling for scenarios that cannot happen. Only validate at system boundaries.
204
+ - Do not create helpers or utilities for one-time operations.
205
+
206
+ ### 6.5 Prevent Test-Focused Hard-Coding [A]
207
+
208
+ "Implement solutions that work correctly for all valid inputs, not just the test cases. Do not hard-code values. Tests verify correctness — they do not define the solution."
209
+
210
+ ### 6.6 Balance Autonomy and Safety [A+O]
211
+
212
+ - **[A]** Consider reversibility and blast radius. Take local, reversible actions freely. Confirm before destructive operations (deleting files, force-pushing, dropping tables).
213
+ - **[O]** Start restrictive, widen permissions based on observed needs. Do not grant full permissions before understanding workflows.
214
+
215
+ ### 6.7 Subagent Orchestration [A]
216
+
217
+ Use subagents when tasks can run in parallel, require isolated context, or involve independent workstreams. For simple tasks, single-file edits, or tasks requiring context continuity, work directly.
218
+
219
+ ### 6.8 Require Verification Loop [O]
220
+
221
+ Include a verification loop in agent workflows:
222
+ 1. Write or update tests for changes.
223
+ 2. Run relevant test suites.
224
+ 3. Execute lint, formatting, and type checks.
225
+ 4. Confirm final behavior matches requirements.
226
+ 5. Review diffs for bugs, regressions, or risky patterns.
227
+
228
+ ---
229
+
230
+ ## 7. Output Control
231
+
232
+ ### 7.1 Scale Output to Change Size [O]
233
+
234
+ - Tiny changes (10 lines or fewer): 2-5 sentences, 0-1 short snippet.
235
+ - Medium changes: 6 bullets or fewer, 1-2 snippets (8 lines max each).
236
+ - Large changes: Summarize per file with 1-2 bullets; avoid inlining code.
237
+
238
+ ### 7.2 Reference Files, Don't Reproduce Code [O]
239
+
240
+ Reference file paths instead of showing large code blocks. Show code only when necessary to clarify intent.
241
+
242
+ ### 7.3 Suppress Unnecessary Output [O]
243
+
244
+ Omit build/lint/test logs unless explicitly requested or they reveal blocking errors. Report outcomes, not processes.
245
+
246
+ ### 7.4 Control Format via Prompt Style [A]
247
+
248
+ Match your prompt formatting to desired output formatting. If your prompt is markdown-heavy, the output will be too. Remove markdown from your prompt if you want prose output.
249
+
250
+ ### 7.5 Eliminate Preambles [A]
251
+
252
+ Use direct instructions: "Respond directly without preamble. Do not start with phrases like 'Here is...', 'Based on...', etc."
253
+
254
+ ---
255
+
256
+ ## 8. Thinking and Reasoning
257
+
258
+ ### 8.1 Use Adaptive Thinking [A]
259
+
260
+ Prefer adaptive thinking (`thinking: {type: "adaptive"}`) with the `effort` parameter instead of manual `budget_tokens`. Claude dynamically decides when and how much to think.
261
+
262
+ ### 8.2 Reasoning Effort as a Tuning Knob [A+O]
263
+
264
+ - **[A]** `low` for high-volume, `medium` for most apps, `high` for complex coding, `max` for hardest problems.
265
+ - **[O]** Lower reasoning effort with better prompts can match higher reasoning effort with poor prompts.
266
+
267
+ ### 8.3 Prefer General Instructions Over Prescriptive Steps [A]
268
+
269
+ "Think thoroughly" often produces better reasoning than a hand-written step-by-step plan. Let the model organize its own thinking.
270
+
271
+ ### 8.4 Ask the Model to Self-Check [A]
272
+
273
+ "Before you finish, verify your answer against [test criteria]." This catches errors reliably, especially for coding and math.
274
+
275
+ ### 8.5 Reasoning Models Need Simpler Prompts [O]
276
+
277
+ Do NOT use chain-of-thought instructions ("think step by step") with reasoning models (o1/o3). They generate internal CoT; external prompting conflicts with it and can degrade performance.
278
+
279
+ ---
280
+
281
+ ## 9. Layered Configuration Architecture
282
+
283
+ ### 9.1 Structure Guidance in Layers [O]
284
+
285
+ Build a layered configuration system:
286
+ 1. **Task prompt** — immediate goal, context, constraints, done-when.
287
+ 2. **Rules files** (CLAUDE.md / AGENTS.md) — durable, reusable rules for the repository.
288
+ 3. **Configuration files** — model choice, reasoning effort, sandbox mode.
289
+ 4. **Tools** — external system integrations.
290
+ 5. **Skills** — packaged repeatable workflows.
291
+
292
+ ### 9.2 Keep Rules Files Concise [A+O]
293
+
294
+ - **[O]** "A short, accurate rules file is more useful than a long file full of vague rules." Add rules only after noticing repeated mistakes.
295
+ - **[A]** Keep the always-loaded core small. Load domain and task rules only when the current task needs them.
296
+
297
+ ### 9.3 Hierarchical Override Strategy [O]
298
+
299
+ Use a three-layer override hierarchy (global → repository → subdirectory). General rules are inherited; specific directories can override them.
300
+
301
+ ---
302
+
303
+ ## 10. Long-Horizon and Multi-Session Workflows
304
+
305
+ ### 10.1 Context Persistence [A]
306
+
307
+ Tell the model about context compaction: "Your context window will be automatically compacted as it approaches its limit. Do not stop tasks early due to token budget concerns. Save progress and state to memory before the context window refreshes."
308
+
309
+ ### 10.2 State Management [A]
310
+
311
+ - Use structured JSON for state data (test results, task status).
312
+ - Use freeform text for progress notes.
313
+ - Use git for state tracking across sessions.
314
+ - Create setup scripts to prevent repeated work when continuing from a fresh context.
315
+
316
+ ### 10.3 Resuming Fresh Context Windows [A]
317
+
318
+ Be prescriptive about how the model should resume: "Review progress files, test status, and git logs. Run a fundamental integration test before implementing new features."
319
+
320
+ ---
321
+
322
+ ## 11. Prompt Maintenance and Iteration
323
+
324
+ ### 11.1 Start Minimal, Add Rules for Observed Failures [A+O]
325
+
326
+ - **[O]** Start with the smallest prompt that passes evaluations. Add blocks only when they fix a measured failure mode.
327
+ - **[A]** Dial back anti-laziness prompting. Prompts designed for older models may cause overtriggering on newer ones.
328
+
329
+ ### 11.2 Use the Model as Its Own Optimizer [O]
330
+
331
+ When a prompt underperforms, ask the model to diagnose root causes and propose surgical revisions. Focus on clarifying conflicts and tightening vague rules rather than full rewrites.
332
+
333
+ ### 11.3 Build Evaluations Before Changing Prompts [O]
334
+
335
+ Build evaluation systems to measure prompt behavior before deploying changes. Pin production applications to specific model snapshots. Run evaluations every time you publish prompt changes.
336
+
337
+ ### 11.4 Audit for Model Generation Changes [A]
338
+
339
+ When upgrading to a new model generation:
340
+ - Replace blanket defaults with targeted instructions.
341
+ - Remove aggressive "If in doubt, use [tool]" prompting.
342
+ - Test for overtriggering and overengineering.
343
+ - Adjust emphasis patterns (remove ALL-CAPS, reward/punishment language).
344
+
345
+ ---
346
+
347
+ ## 12. Anti-Patterns to Avoid [A+O]
348
+
349
+ | Anti-Pattern | Source | Fix |
350
+ |---|---|---|
351
+ | Overloading prompts with durable rules | O | Move to rules files or repository docs |
352
+ | No build/test feedback to agent | O | Include verification loop |
353
+ | Skipping planning on complex tasks | O | Use plan mode or require explicit planning |
354
+ | ALL-CAPS and reward language | A+O | Use structured formatting instead |
355
+ | Contradictory instructions | O | Audit and resolve before deployment |
356
+ | Aggressive tool prompting ("MUST use") | A | Use normal language ("Use this when...") |
357
+ | Many few-shot examples for reasoning models | O | Use zero-shot or one example max |
358
+ | Not explaining WHY behind rules | A | Add motivation to help generalization |
359
+ | Telling model what NOT to do | A | Reframe as positive instructions |
360
+ | One thread per project instead of per task | O | One thread per coherent unit of work |
361
+ | Forcing tool calls without sufficient info | O | Add "ask the user" safety valve |
362
+ | Sample phrases repeated verbatim | O | Instruct variation explicitly |
363
+
364
+ ---
365
+
366
+ ## Sources
367
+
368
+ ### Anthropic
369
+ - [Claude Prompting Best Practices](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/overview) (consolidated guide)
370
+ - [Prompt Caching](https://docs.anthropic.com/en/docs/build-with-claude/prompt-caching)
371
+ - [Extended Thinking](https://docs.anthropic.com/en/docs/build-with-claude/extended-thinking)
372
+
373
+ ### OpenAI
374
+ - [GPT-4.1 Prompting Guide](https://developers.openai.com/cookbook/examples/gpt4-1_prompting_guide/)
375
+ - [GPT-5 Prompting Guide](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5_prompting_guide/)
376
+ - [GPT-5.1 Prompting Guide](https://developers.openai.com/cookbook/examples/gpt-5/gpt-5-1_prompting_guide/)
377
+ - [Codex Prompting Guide](https://developers.openai.com/cookbook/examples/gpt-5/codex_prompting_guide/)
378
+ - [Codex Best Practices](https://developers.openai.com/codex/learn/best-practices/)
379
+ - [Prompt Engineering Guide](https://developers.openai.com/api/docs/guides/prompt-engineering/)
380
+ - [Reasoning Models Guide](https://platform.openai.com/docs/guides/reasoning)