@chankov/agent-fleet 0.0.10 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (690) hide show
  1. package/.pi/extensions/agent-fleet-update-check/README.md +4 -4
  2. package/.pi/extensions/btw/README.md +29 -27
  3. package/.pi/extensions/btw/index.ts +80 -83
  4. package/.pi/extensions/pi-voice-stt/README.md +7 -3
  5. package/.pi/extensions/pi-voice-stt/config.ts +1 -1
  6. package/.pi/harnesses/agent-hub/README.md +109 -54
  7. package/.pi/harnesses/agent-hub/backend-policy.js +25 -4
  8. package/.pi/harnesses/agent-hub/footer.ts +4 -0
  9. package/.pi/harnesses/agent-hub/helpers.ts +18 -0
  10. package/.pi/harnesses/agent-hub/index.ts +537 -369
  11. package/.pi/harnesses/agent-hub/monitor-session-bridge.ts +10 -1
  12. package/.pi/harnesses/agent-hub/package.json +1 -1
  13. package/.pi/harnesses/agent-hub/peer-spawn-plan.ts +116 -0
  14. package/.pi/harnesses/agent-hub/posture.ts +103 -0
  15. package/.pi/harnesses/ask-user-remote/README.md +37 -3
  16. package/.pi/harnesses/ask-user-remote/index.ts +173 -17
  17. package/.pi/harnesses/coms/package.json +1 -1
  18. package/.pi/harnesses/damage-control-continue/package.json +1 -1
  19. package/.pi/harnesses/lib/fleet-dashboard-ops.ts +118 -0
  20. package/.pi/harnesses/lib/fleet-dashboard-view.ts +140 -0
  21. package/.pi/harnesses/lib/fleet-detail-view.ts +43 -0
  22. package/.pi/harnesses/lib/fleet-overlay.ts +26 -0
  23. package/.pi/harnesses/lib/fleet-panel.ts +34 -0
  24. package/.pi/harnesses/lib/fleet-read-model.ts +131 -0
  25. package/.pi/harnesses/lib/fleet-selection.ts +24 -0
  26. package/.pi/harnesses/package-lock.json +2011 -0
  27. package/.pi/harnesses/package.json +1 -0
  28. package/.versions/0.0.11/.pi/agents/dispatch-policy.yaml +32 -0
  29. package/.versions/0.0.11/.pi/agents/model-profiles.yaml +27 -0
  30. package/.versions/0.0.11/.pi/agents/peers.yaml +142 -0
  31. package/.versions/0.0.11/.pi/agents/teams.yaml +41 -0
  32. package/.versions/0.0.11/.pi/damage-control-rules.yaml +297 -0
  33. package/.versions/0.0.11/.pi/extensions/agent-fleet-update-check/README.md +57 -0
  34. package/.versions/0.0.11/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  35. package/.versions/0.0.11/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  36. package/.versions/0.0.11/.pi/extensions/btw/README.md +119 -0
  37. package/.versions/0.0.11/.pi/extensions/btw/index.ts +917 -0
  38. package/.versions/0.0.11/.pi/extensions/btw/package.json +6 -0
  39. package/.versions/0.0.11/.pi/extensions/btw/state.js +179 -0
  40. package/.versions/0.0.11/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
  41. package/.versions/0.0.11/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
  42. package/.versions/0.0.11/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  43. package/.versions/0.0.11/.pi/extensions/compact-and-continue/README.md +42 -0
  44. package/.versions/0.0.11/.pi/extensions/compact-and-continue/index.ts +120 -0
  45. package/.versions/0.0.11/.pi/extensions/compact-and-continue/package.json +6 -0
  46. package/.versions/0.0.11/.pi/extensions/mcp-bridge/README.md +46 -0
  47. package/.versions/0.0.11/.pi/extensions/mcp-bridge/index.ts +206 -0
  48. package/.versions/0.0.11/.pi/extensions/mcp-bridge/package.json +6 -0
  49. package/.versions/0.0.11/.pi/extensions/package-lock.json +1143 -0
  50. package/.versions/0.0.11/.pi/extensions/package.json +9 -0
  51. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/README.md +205 -0
  52. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/config.ts +198 -0
  53. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  54. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/index.ts +248 -0
  55. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/package.json +6 -0
  56. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  57. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  58. package/.versions/0.0.11/.pi/harnesses/agent-hub/README.md +1004 -0
  59. package/.versions/0.0.11/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  60. package/.versions/0.0.11/.pi/harnesses/agent-hub/artifacts.js +146 -0
  61. package/.versions/0.0.11/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
  62. package/.versions/0.0.11/.pi/harnesses/agent-hub/backend-policy.js +153 -0
  63. package/.versions/0.0.11/.pi/harnesses/agent-hub/context-window.js +106 -0
  64. package/.versions/0.0.11/.pi/harnesses/agent-hub/delegate.ts +435 -0
  65. package/.versions/0.0.11/.pi/harnesses/agent-hub/docs-lane.js +122 -0
  66. package/.versions/0.0.11/.pi/harnesses/agent-hub/drift-watchdog.js +211 -0
  67. package/.versions/0.0.11/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  68. package/.versions/0.0.11/.pi/harnesses/agent-hub/external-blocker.js +85 -0
  69. package/.versions/0.0.11/.pi/harnesses/agent-hub/footer.ts +31 -0
  70. package/.versions/0.0.11/.pi/harnesses/agent-hub/helpers.ts +248 -0
  71. package/.versions/0.0.11/.pi/harnesses/agent-hub/index.ts +9111 -0
  72. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  73. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
  74. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
  75. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  76. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  77. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  78. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  79. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-session-bridge.ts +266 -0
  80. package/.versions/0.0.11/.pi/harnesses/agent-hub/package.json +7 -0
  81. package/.versions/0.0.11/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
  82. package/.versions/0.0.11/.pi/harnesses/agent-hub/research-retention.js +34 -0
  83. package/.versions/0.0.11/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  84. package/.versions/0.0.11/.pi/harnesses/agent-hub/return-contract.js +293 -0
  85. package/.versions/0.0.11/.pi/harnesses/agent-hub/return-extract.js +75 -0
  86. package/.versions/0.0.11/.pi/harnesses/agent-hub/review-findings.js +102 -0
  87. package/.versions/0.0.11/.pi/harnesses/agent-hub/run-budget.js +479 -0
  88. package/.versions/0.0.11/.pi/harnesses/agent-hub/run-namespace.js +87 -0
  89. package/.versions/0.0.11/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  90. package/.versions/0.0.11/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  91. package/.versions/0.0.11/.pi/harnesses/agent-hub/session-health.js +110 -0
  92. package/.versions/0.0.11/.pi/harnesses/agent-hub/spawn.ts +354 -0
  93. package/.versions/0.0.11/.pi/harnesses/agent-hub/version.ts +42 -0
  94. package/.versions/0.0.11/.pi/harnesses/ask-user-remote/README.md +53 -0
  95. package/.versions/0.0.11/.pi/harnesses/ask-user-remote/index.ts +477 -0
  96. package/.versions/0.0.11/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  97. package/.versions/0.0.11/.pi/harnesses/coms/README.md +100 -0
  98. package/.versions/0.0.11/.pi/harnesses/coms/index.ts +1767 -0
  99. package/.versions/0.0.11/.pi/harnesses/coms/package.json +7 -0
  100. package/.versions/0.0.11/.pi/harnesses/coms/version.ts +42 -0
  101. package/.versions/0.0.11/.pi/harnesses/damage-control-continue/README.md +124 -0
  102. package/.versions/0.0.11/.pi/harnesses/damage-control-continue/index.ts +536 -0
  103. package/.versions/0.0.11/.pi/harnesses/damage-control-continue/package.json +7 -0
  104. package/.versions/0.0.11/.pi/harnesses/damage-control-continue/version.ts +42 -0
  105. package/.versions/0.0.11/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
  106. package/.versions/0.0.11/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  107. package/.versions/0.0.11/.pi/harnesses/lib/herdr-client.ts +472 -0
  108. package/.versions/0.0.11/.pi/harnesses/lib/herdr-presence.ts +399 -0
  109. package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
  110. package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  111. package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
  112. package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  113. package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
  114. package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  115. package/.versions/0.0.11/.pi/harnesses/lib/spawned-peers.js +190 -0
  116. package/.versions/0.0.11/.pi/harnesses/package-lock.json +2046 -0
  117. package/.versions/0.0.11/.pi/harnesses/package.json +10 -0
  118. package/.versions/0.0.11/.pi/prompts/af-build.md +24 -0
  119. package/{.claude/commands/code-simplify.md → .versions/0.0.11/.pi/prompts/af-code-simplify.md} +3 -3
  120. package/{.claude/commands/plan.md → .versions/0.0.11/.pi/prompts/af-plan.md} +1 -1
  121. package/{.claude/commands/review.md → .versions/0.0.11/.pi/prompts/af-review.md} +3 -3
  122. package/.versions/0.0.11/.pi/prompts/af-set-hermes-watchdog.md +6 -0
  123. package/.versions/0.0.11/.pi/prompts/af-ship.md +17 -0
  124. package/{.claude/commands/spec.md → .versions/0.0.11/.pi/prompts/af-spec.md} +1 -1
  125. package/{.claude/commands/test.md → .versions/0.0.11/.pi/prompts/af-test.md} +2 -2
  126. package/.versions/0.0.11/.pi/skills/bowser/SKILL.md +145 -0
  127. package/.versions/0.0.11/.version +1 -0
  128. package/.versions/0.0.11/agents/architect.md +24 -0
  129. package/.versions/0.0.11/agents/bowser.md +27 -0
  130. package/.versions/0.0.11/agents/builder.md +54 -0
  131. package/.versions/0.0.11/agents/code-reviewer.md +208 -0
  132. package/.versions/0.0.11/agents/deep-researcher.md +32 -0
  133. package/.versions/0.0.11/agents/documenter.md +18 -0
  134. package/.versions/0.0.11/agents/orchestrator.md +72 -0
  135. package/.versions/0.0.11/agents/plan-reviewer.md +83 -0
  136. package/.versions/0.0.11/agents/planner.md +70 -0
  137. package/.versions/0.0.11/agents/releaser.md +24 -0
  138. package/.versions/0.0.11/agents/researcher.md +28 -0
  139. package/.versions/0.0.11/agents/security-auditor.md +167 -0
  140. package/.versions/0.0.11/agents/test-engineer.md +153 -0
  141. package/.versions/0.0.11/agents/web-debugger.md +43 -0
  142. package/.versions/0.0.11/agents/web-performance-auditor.md +193 -0
  143. package/.versions/0.0.11/codex/CONDUCTOR.md +148 -0
  144. package/.versions/0.0.11/docs/ARCHITECTURE.md +301 -0
  145. package/.versions/0.0.11/docs/agent-fleet-setup.md +351 -0
  146. package/.versions/0.0.11/docs/claude-code-coms-bridge.md +127 -0
  147. package/.versions/0.0.11/docs/codex-remote-conductor.md +170 -0
  148. package/.versions/0.0.11/docs/coms-hermes-bridge.md +189 -0
  149. package/.versions/0.0.11/docs/getting-started.md +43 -0
  150. package/.versions/0.0.11/docs/npm-install.md +96 -0
  151. package/.versions/0.0.11/docs/pi-extensions.md +368 -0
  152. package/.versions/0.0.11/docs/pi-setup.md +57 -0
  153. package/.versions/0.0.11/docs/skill-anatomy.md +150 -0
  154. package/.versions/0.0.11/hermes/README.md +347 -0
  155. package/.versions/0.0.11/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
  156. package/.versions/0.0.11/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
  157. package/.versions/0.0.11/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  158. package/.versions/0.0.11/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  159. package/.versions/0.0.11/hermes/gates/gate-o-capability.md +8 -0
  160. package/.versions/0.0.11/hermes/gates/gate-o-validator-fixtures.json +1 -0
  161. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +770 -0
  162. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
  163. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
  164. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
  165. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
  166. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
  167. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
  168. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
  169. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
  170. package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
  171. package/.versions/0.0.11/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
  172. package/.versions/0.0.11/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  173. package/.versions/0.0.11/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  174. package/.versions/0.0.11/hermes/skills/hub-conductor/SKILL.md +84 -0
  175. package/.versions/0.0.11/hermes/skills/hub-liaison/SKILL.md +84 -0
  176. package/.versions/0.0.11/hermes/skills/hub-watchdog/SKILL.md +76 -0
  177. package/.versions/0.0.11/hermes/skills/hub-watchdog/manifest.json +1 -0
  178. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
  179. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
  180. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
  181. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
  182. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
  183. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
  184. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
  185. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
  186. package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
  187. package/.versions/0.0.11/hermes/watchdog-tests/__init__.py +0 -0
  188. package/.versions/0.0.11/hooks/coms-stop-hook.mjs +84 -0
  189. package/.versions/0.0.11/install-manifest.json +2743 -0
  190. package/.versions/0.0.11/justfile +261 -0
  191. package/.versions/0.0.11/manifest-meta.json +881 -0
  192. package/.versions/0.0.11/references/accessibility-checklist.md +160 -0
  193. package/.versions/0.0.11/references/definition-of-done.md +67 -0
  194. package/.versions/0.0.11/references/fleet-coordination-patterns.md +151 -0
  195. package/.versions/0.0.11/references/observability-checklist.md +91 -0
  196. package/.versions/0.0.11/references/orchestration-patterns.md +370 -0
  197. package/.versions/0.0.11/references/performance-checklist.md +153 -0
  198. package/.versions/0.0.11/references/prompting-patterns.md +380 -0
  199. package/.versions/0.0.11/references/security-checklist.md +179 -0
  200. package/.versions/0.0.11/references/testing-patterns.md +236 -0
  201. package/.versions/0.0.11/scripts/codex-conductor.ts +41 -0
  202. package/.versions/0.0.11/scripts/codex-remote-control.ts +167 -0
  203. package/.versions/0.0.11/scripts/coms-claude-bridge.ts +401 -0
  204. package/.versions/0.0.11/scripts/coms-cli.ts +484 -0
  205. package/.versions/0.0.11/scripts/coms-hermes-bridge.ts +413 -0
  206. package/.versions/0.0.11/scripts/fleet.ts +168 -0
  207. package/.versions/0.0.11/scripts/hermes-monitor-capability-runner.ts +25 -0
  208. package/.versions/0.0.11/scripts/hermes-monitor-scenario.ts +474 -0
  209. package/.versions/0.0.11/scripts/hermes-watchdog-capability-probe.ts +45 -0
  210. package/.versions/0.0.11/scripts/install-hermes-plugin.sh +180 -0
  211. package/.versions/0.0.11/scripts/lib/claude-bridge-core.ts +165 -0
  212. package/.versions/0.0.11/scripts/lib/codex-conductor.ts +88 -0
  213. package/.versions/0.0.11/scripts/lib/codex-remote-control.ts +480 -0
  214. package/.versions/0.0.11/scripts/lib/coms-envelope.ts +582 -0
  215. package/.versions/0.0.11/scripts/lib/fake-herdr-server.ts +88 -0
  216. package/.versions/0.0.11/scripts/lib/fleet-command.ts +119 -0
  217. package/.versions/0.0.11/scripts/lib/herdr-layout.ts +281 -0
  218. package/.versions/0.0.11/scripts/lib/hermes-bridge-core.ts +241 -0
  219. package/.versions/0.0.11/scripts/lib/hermes-monitor-events.ts +1 -0
  220. package/.versions/0.0.11/scripts/lib/hermes-monitor-herdr.ts +2 -0
  221. package/.versions/0.0.11/scripts/lib/hermes-monitor-model.ts +3 -0
  222. package/.versions/0.0.11/scripts/lib/hermes-monitor-registry.ts +2 -0
  223. package/.versions/0.0.11/scripts/lib/hermes-monitor-socket.ts +2 -0
  224. package/.versions/0.0.11/scripts/lib/hermes-monitor-store.ts +2 -0
  225. package/.versions/0.0.11/scripts/lib/monitor-env.ts +146 -0
  226. package/.versions/0.0.11/scripts/lib/peer-launch.ts +314 -0
  227. package/.versions/0.0.11/scripts/lib/persona-banner.ts +62 -0
  228. package/.versions/0.0.11/scripts/lib/spawn-stagger.ts +101 -0
  229. package/.versions/0.0.11/scripts/lib/team-project.ts +193 -0
  230. package/.versions/0.0.11/scripts/lib/team-snapshot.ts +147 -0
  231. package/.versions/0.0.11/scripts/peer-banner.ts +40 -0
  232. package/.versions/0.0.11/scripts/peer-launch.ts +259 -0
  233. package/.versions/0.0.11/scripts/team-snapshot.ts +237 -0
  234. package/.versions/0.0.11/scripts/team-up.ts +360 -0
  235. package/.versions/0.0.11/skills/_internal/grilling.md +11 -0
  236. package/.versions/0.0.11/skills/browser-testing-with-devtools/SKILL.md +351 -0
  237. package/.versions/0.0.11/skills/code-review-and-quality/SKILL.md +381 -0
  238. package/.versions/0.0.11/skills/compound-learning/SKILL.md +137 -0
  239. package/.versions/0.0.11/skills/context-engineering/SKILL.md +291 -0
  240. package/.versions/0.0.11/skills/deprecation-and-migration/SKILL.md +206 -0
  241. package/.versions/0.0.11/skills/designing-agents/SKILL.md +394 -0
  242. package/.versions/0.0.11/skills/designing-agents/pi-harness-authoring.md +222 -0
  243. package/.versions/0.0.11/skills/frontend-ui-engineering/SKILL.md +328 -0
  244. package/.versions/0.0.11/skills/git-workflow-and-versioning/SKILL.md +316 -0
  245. package/.versions/0.0.11/skills/idea-refine/SKILL.md +182 -0
  246. package/.versions/0.0.11/skills/idea-refine/examples.md +238 -0
  247. package/.versions/0.0.11/skills/idea-refine/frameworks.md +99 -0
  248. package/.versions/0.0.11/skills/idea-refine/refinement-criteria.md +113 -0
  249. package/.versions/0.0.11/skills/idea-refine/scripts/idea-refine.sh +15 -0
  250. package/.versions/0.0.11/skills/incremental-implementation/SKILL.md +287 -0
  251. package/.versions/0.0.11/skills/interview-me/SKILL.md +226 -0
  252. package/.versions/0.0.11/skills/orchestration-verification/SKILL.md +181 -0
  253. package/.versions/0.0.11/skills/peer-coms/SKILL.md +90 -0
  254. package/.versions/0.0.11/skills/performance-optimization/SKILL.md +350 -0
  255. package/.versions/0.0.11/skills/planning-and-task-breakdown/SKILL.md +254 -0
  256. package/.versions/0.0.11/skills/security-and-hardening/SKILL.md +461 -0
  257. package/.versions/0.0.11/skills/spec-driven-development/SKILL.md +257 -0
  258. package/.versions/0.0.11/skills/using-agent-skills/SKILL.md +199 -0
  259. package/.versions/0.0.11/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  260. package/.versions/0.0.11/vendor/agent-skills-upstream/LICENSE +21 -0
  261. package/.versions/0.0.11/vendor/agent-skills-upstream/README.md +11 -0
  262. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  263. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  264. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  265. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  266. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  267. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  268. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  269. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  270. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  271. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  272. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  273. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  274. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  275. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  276. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  277. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  278. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  279. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  280. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  281. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  282. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  283. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  284. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  285. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  286. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  287. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  288. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  289. package/.versions/0.0.11/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  290. package/.versions/1.0.0/.pi/agents/dispatch-policy.yaml +32 -0
  291. package/.versions/1.0.0/.pi/agents/model-profiles.yaml +27 -0
  292. package/.versions/1.0.0/.pi/agents/peers.yaml +142 -0
  293. package/.versions/1.0.0/.pi/agents/teams.yaml +41 -0
  294. package/.versions/1.0.0/.pi/damage-control-rules.yaml +297 -0
  295. package/.versions/1.0.0/.pi/extensions/agent-fleet-update-check/README.md +57 -0
  296. package/.versions/1.0.0/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  297. package/.versions/1.0.0/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  298. package/.versions/1.0.0/.pi/extensions/btw/README.md +120 -0
  299. package/.versions/1.0.0/.pi/extensions/btw/index.ts +914 -0
  300. package/.versions/1.0.0/.pi/extensions/btw/package.json +6 -0
  301. package/.versions/1.0.0/.pi/extensions/btw/state.js +179 -0
  302. package/.versions/1.0.0/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
  303. package/.versions/1.0.0/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
  304. package/.versions/1.0.0/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  305. package/.versions/1.0.0/.pi/extensions/compact-and-continue/README.md +42 -0
  306. package/.versions/1.0.0/.pi/extensions/compact-and-continue/index.ts +120 -0
  307. package/.versions/1.0.0/.pi/extensions/compact-and-continue/package.json +6 -0
  308. package/.versions/1.0.0/.pi/extensions/mcp-bridge/README.md +46 -0
  309. package/.versions/1.0.0/.pi/extensions/mcp-bridge/index.ts +206 -0
  310. package/.versions/1.0.0/.pi/extensions/mcp-bridge/package.json +6 -0
  311. package/.versions/1.0.0/.pi/extensions/package-lock.json +1143 -0
  312. package/.versions/1.0.0/.pi/extensions/package.json +9 -0
  313. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/README.md +205 -0
  314. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/config.ts +198 -0
  315. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  316. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/index.ts +248 -0
  317. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/package.json +6 -0
  318. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  319. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  320. package/.versions/1.0.0/.pi/harnesses/agent-hub/README.md +1056 -0
  321. package/.versions/1.0.0/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  322. package/.versions/1.0.0/.pi/harnesses/agent-hub/artifacts.js +146 -0
  323. package/.versions/1.0.0/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
  324. package/.versions/1.0.0/.pi/harnesses/agent-hub/backend-policy.js +174 -0
  325. package/.versions/1.0.0/.pi/harnesses/agent-hub/context-window.js +106 -0
  326. package/.versions/1.0.0/.pi/harnesses/agent-hub/delegate.ts +435 -0
  327. package/.versions/1.0.0/.pi/harnesses/agent-hub/docs-lane.js +122 -0
  328. package/.versions/1.0.0/.pi/harnesses/agent-hub/drift-watchdog.js +211 -0
  329. package/.versions/1.0.0/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  330. package/.versions/1.0.0/.pi/harnesses/agent-hub/external-blocker.js +85 -0
  331. package/.versions/1.0.0/.pi/harnesses/agent-hub/footer.ts +35 -0
  332. package/.versions/1.0.0/.pi/harnesses/agent-hub/helpers.ts +266 -0
  333. package/.versions/1.0.0/.pi/harnesses/agent-hub/index.ts +9279 -0
  334. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  335. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
  336. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
  337. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  338. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  339. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  340. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  341. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-session-bridge.ts +266 -0
  342. package/.versions/1.0.0/.pi/harnesses/agent-hub/package.json +7 -0
  343. package/.versions/1.0.0/.pi/harnesses/agent-hub/peer-spawn-plan.ts +116 -0
  344. package/.versions/1.0.0/.pi/harnesses/agent-hub/posture.ts +103 -0
  345. package/.versions/1.0.0/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
  346. package/.versions/1.0.0/.pi/harnesses/agent-hub/research-retention.js +34 -0
  347. package/.versions/1.0.0/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  348. package/.versions/1.0.0/.pi/harnesses/agent-hub/return-contract.js +293 -0
  349. package/.versions/1.0.0/.pi/harnesses/agent-hub/return-extract.js +75 -0
  350. package/.versions/1.0.0/.pi/harnesses/agent-hub/review-findings.js +102 -0
  351. package/.versions/1.0.0/.pi/harnesses/agent-hub/run-budget.js +479 -0
  352. package/.versions/1.0.0/.pi/harnesses/agent-hub/run-namespace.js +87 -0
  353. package/.versions/1.0.0/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  354. package/.versions/1.0.0/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  355. package/.versions/1.0.0/.pi/harnesses/agent-hub/session-health.js +110 -0
  356. package/.versions/1.0.0/.pi/harnesses/agent-hub/spawn.ts +354 -0
  357. package/.versions/1.0.0/.pi/harnesses/agent-hub/version.ts +42 -0
  358. package/.versions/1.0.0/.pi/harnesses/ask-user-remote/README.md +53 -0
  359. package/.versions/1.0.0/.pi/harnesses/ask-user-remote/index.ts +477 -0
  360. package/.versions/1.0.0/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  361. package/.versions/1.0.0/.pi/harnesses/coms/README.md +100 -0
  362. package/.versions/1.0.0/.pi/harnesses/coms/index.ts +1767 -0
  363. package/.versions/1.0.0/.pi/harnesses/coms/package.json +7 -0
  364. package/.versions/1.0.0/.pi/harnesses/coms/version.ts +42 -0
  365. package/.versions/1.0.0/.pi/harnesses/damage-control-continue/README.md +124 -0
  366. package/.versions/1.0.0/.pi/harnesses/damage-control-continue/index.ts +536 -0
  367. package/.versions/1.0.0/.pi/harnesses/damage-control-continue/package.json +7 -0
  368. package/.versions/1.0.0/.pi/harnesses/damage-control-continue/version.ts +42 -0
  369. package/.versions/1.0.0/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
  370. package/.versions/1.0.0/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  371. package/.versions/1.0.0/.pi/harnesses/lib/fleet-dashboard-ops.ts +118 -0
  372. package/.versions/1.0.0/.pi/harnesses/lib/fleet-dashboard-view.ts +140 -0
  373. package/.versions/1.0.0/.pi/harnesses/lib/fleet-detail-view.ts +43 -0
  374. package/.versions/1.0.0/.pi/harnesses/lib/fleet-overlay.ts +26 -0
  375. package/.versions/1.0.0/.pi/harnesses/lib/fleet-panel.ts +34 -0
  376. package/.versions/1.0.0/.pi/harnesses/lib/fleet-read-model.ts +131 -0
  377. package/.versions/1.0.0/.pi/harnesses/lib/fleet-selection.ts +24 -0
  378. package/.versions/1.0.0/.pi/harnesses/lib/herdr-client.ts +472 -0
  379. package/.versions/1.0.0/.pi/harnesses/lib/herdr-presence.ts +399 -0
  380. package/.versions/1.0.0/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
  381. package/.versions/1.0.0/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  382. package/.versions/1.0.0/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
  383. package/.versions/1.0.0/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  384. package/.versions/1.0.0/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
  385. package/.versions/1.0.0/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  386. package/.versions/1.0.0/.pi/harnesses/lib/spawned-peers.js +190 -0
  387. package/.versions/1.0.0/.pi/harnesses/package-lock.json +2046 -0
  388. package/.versions/1.0.0/.pi/harnesses/package.json +10 -0
  389. package/.versions/1.0.0/.pi/prompts/af-build.md +24 -0
  390. package/.versions/1.0.0/.pi/prompts/af-code-simplify.md +22 -0
  391. package/.versions/1.0.0/.pi/prompts/af-plan.md +16 -0
  392. package/.versions/1.0.0/.pi/prompts/af-review.md +16 -0
  393. package/.versions/1.0.0/.pi/prompts/af-set-hermes-watchdog.md +6 -0
  394. package/.versions/1.0.0/.pi/prompts/af-ship.md +17 -0
  395. package/.versions/1.0.0/.pi/prompts/af-spec.md +15 -0
  396. package/.versions/1.0.0/.pi/prompts/af-test.md +19 -0
  397. package/.versions/1.0.0/.pi/skills/bowser/SKILL.md +145 -0
  398. package/.versions/1.0.0/.version +1 -0
  399. package/.versions/1.0.0/agents/architect.md +24 -0
  400. package/.versions/1.0.0/agents/bowser.md +27 -0
  401. package/.versions/1.0.0/agents/builder.md +54 -0
  402. package/.versions/1.0.0/agents/code-reviewer.md +208 -0
  403. package/.versions/1.0.0/agents/deep-researcher.md +32 -0
  404. package/.versions/1.0.0/agents/documenter.md +18 -0
  405. package/.versions/1.0.0/agents/orchestrator.md +72 -0
  406. package/.versions/1.0.0/agents/plan-reviewer.md +83 -0
  407. package/.versions/1.0.0/agents/planner.md +70 -0
  408. package/.versions/1.0.0/agents/releaser.md +24 -0
  409. package/.versions/1.0.0/agents/researcher.md +28 -0
  410. package/.versions/1.0.0/agents/security-auditor.md +167 -0
  411. package/.versions/1.0.0/agents/test-engineer.md +153 -0
  412. package/.versions/1.0.0/agents/web-debugger.md +43 -0
  413. package/.versions/1.0.0/agents/web-performance-auditor.md +193 -0
  414. package/.versions/1.0.0/codex/CONDUCTOR.md +148 -0
  415. package/.versions/1.0.0/docs/ARCHITECTURE.md +337 -0
  416. package/.versions/1.0.0/docs/agent-fleet-setup.md +437 -0
  417. package/.versions/1.0.0/docs/claude-code-coms-bridge.md +128 -0
  418. package/.versions/1.0.0/docs/codex-remote-conductor.md +170 -0
  419. package/.versions/1.0.0/docs/coms-hermes-bridge.md +189 -0
  420. package/.versions/1.0.0/docs/getting-started.md +98 -0
  421. package/.versions/1.0.0/docs/npm-install.md +292 -0
  422. package/.versions/1.0.0/docs/pi-extensions.md +412 -0
  423. package/.versions/1.0.0/docs/pi-setup.md +74 -0
  424. package/.versions/1.0.0/docs/skill-anatomy.md +150 -0
  425. package/.versions/1.0.0/hermes/README.md +347 -0
  426. package/.versions/1.0.0/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
  427. package/.versions/1.0.0/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
  428. package/.versions/1.0.0/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  429. package/.versions/1.0.0/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  430. package/.versions/1.0.0/hermes/gates/gate-o-capability.md +8 -0
  431. package/.versions/1.0.0/hermes/gates/gate-o-validator-fixtures.json +1 -0
  432. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +770 -0
  433. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
  434. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
  435. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
  436. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
  437. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
  438. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
  439. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
  440. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
  441. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
  442. package/.versions/1.0.0/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
  443. package/.versions/1.0.0/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  444. package/.versions/1.0.0/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  445. package/.versions/1.0.0/hermes/skills/hub-conductor/SKILL.md +84 -0
  446. package/.versions/1.0.0/hermes/skills/hub-liaison/SKILL.md +84 -0
  447. package/.versions/1.0.0/hermes/skills/hub-watchdog/SKILL.md +76 -0
  448. package/.versions/1.0.0/hermes/skills/hub-watchdog/manifest.json +1 -0
  449. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
  450. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
  451. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
  452. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
  453. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
  454. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
  455. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
  456. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
  457. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
  458. package/.versions/1.0.0/hermes/watchdog-tests/__init__.py +0 -0
  459. package/.versions/1.0.0/hooks/coms-stop-hook.mjs +84 -0
  460. package/.versions/1.0.0/install-manifest.json +2745 -0
  461. package/.versions/1.0.0/justfile +272 -0
  462. package/.versions/1.0.0/manifest-meta.json +882 -0
  463. package/.versions/1.0.0/references/accessibility-checklist.md +160 -0
  464. package/.versions/1.0.0/references/definition-of-done.md +67 -0
  465. package/.versions/1.0.0/references/fleet-coordination-patterns.md +151 -0
  466. package/.versions/1.0.0/references/observability-checklist.md +91 -0
  467. package/.versions/1.0.0/references/orchestration-patterns.md +370 -0
  468. package/.versions/1.0.0/references/performance-checklist.md +153 -0
  469. package/.versions/1.0.0/references/prompting-patterns.md +380 -0
  470. package/.versions/1.0.0/references/security-checklist.md +179 -0
  471. package/.versions/1.0.0/references/testing-patterns.md +236 -0
  472. package/.versions/1.0.0/scripts/codex-conductor.ts +41 -0
  473. package/.versions/1.0.0/scripts/codex-remote-control.ts +167 -0
  474. package/.versions/1.0.0/scripts/coms-claude-bridge.ts +411 -0
  475. package/.versions/1.0.0/scripts/coms-cli.ts +484 -0
  476. package/.versions/1.0.0/scripts/coms-hermes-bridge.ts +413 -0
  477. package/.versions/1.0.0/scripts/fleet.ts +185 -0
  478. package/.versions/1.0.0/scripts/hermes-monitor-capability-runner.ts +25 -0
  479. package/.versions/1.0.0/scripts/hermes-monitor-scenario.ts +474 -0
  480. package/.versions/1.0.0/scripts/hermes-watchdog-capability-probe.ts +45 -0
  481. package/.versions/1.0.0/scripts/install-hermes-plugin.sh +180 -0
  482. package/.versions/1.0.0/scripts/lib/claude-bridge-core.ts +210 -0
  483. package/.versions/1.0.0/scripts/lib/codex-conductor.ts +88 -0
  484. package/.versions/1.0.0/scripts/lib/codex-remote-control.ts +480 -0
  485. package/.versions/1.0.0/scripts/lib/coms-envelope.ts +582 -0
  486. package/.versions/1.0.0/scripts/lib/fake-herdr-server.ts +88 -0
  487. package/.versions/1.0.0/scripts/lib/fleet-command.ts +266 -0
  488. package/.versions/1.0.0/scripts/lib/herdr-layout.ts +281 -0
  489. package/.versions/1.0.0/scripts/lib/hermes-bridge-core.ts +241 -0
  490. package/.versions/1.0.0/scripts/lib/hermes-monitor-events.ts +1 -0
  491. package/.versions/1.0.0/scripts/lib/hermes-monitor-herdr.ts +2 -0
  492. package/.versions/1.0.0/scripts/lib/hermes-monitor-model.ts +3 -0
  493. package/.versions/1.0.0/scripts/lib/hermes-monitor-registry.ts +2 -0
  494. package/.versions/1.0.0/scripts/lib/hermes-monitor-socket.ts +2 -0
  495. package/.versions/1.0.0/scripts/lib/hermes-monitor-store.ts +2 -0
  496. package/.versions/1.0.0/scripts/lib/monitor-env.ts +146 -0
  497. package/.versions/1.0.0/scripts/lib/peer-launch.ts +318 -0
  498. package/.versions/1.0.0/scripts/lib/persona-banner.ts +62 -0
  499. package/.versions/1.0.0/scripts/lib/spawn-stagger.ts +101 -0
  500. package/.versions/1.0.0/scripts/lib/team-project.ts +213 -0
  501. package/.versions/1.0.0/scripts/lib/team-snapshot.ts +147 -0
  502. package/.versions/1.0.0/scripts/peer-banner.ts +40 -0
  503. package/.versions/1.0.0/scripts/peer-launch.ts +259 -0
  504. package/.versions/1.0.0/scripts/team-snapshot.ts +237 -0
  505. package/.versions/1.0.0/scripts/team-up.ts +406 -0
  506. package/.versions/1.0.0/skills/_internal/grilling.md +11 -0
  507. package/.versions/1.0.0/skills/browser-testing-with-devtools/SKILL.md +351 -0
  508. package/.versions/1.0.0/skills/code-review-and-quality/SKILL.md +381 -0
  509. package/.versions/1.0.0/skills/compound-learning/SKILL.md +137 -0
  510. package/.versions/1.0.0/skills/context-engineering/SKILL.md +291 -0
  511. package/.versions/1.0.0/skills/deprecation-and-migration/SKILL.md +206 -0
  512. package/.versions/1.0.0/skills/designing-agents/SKILL.md +394 -0
  513. package/.versions/1.0.0/skills/designing-agents/pi-harness-authoring.md +222 -0
  514. package/.versions/1.0.0/skills/frontend-ui-engineering/SKILL.md +328 -0
  515. package/.versions/1.0.0/skills/git-workflow-and-versioning/SKILL.md +316 -0
  516. package/.versions/1.0.0/skills/idea-refine/SKILL.md +182 -0
  517. package/.versions/1.0.0/skills/idea-refine/examples.md +238 -0
  518. package/.versions/1.0.0/skills/idea-refine/frameworks.md +99 -0
  519. package/.versions/1.0.0/skills/idea-refine/refinement-criteria.md +113 -0
  520. package/.versions/1.0.0/skills/idea-refine/scripts/idea-refine.sh +15 -0
  521. package/.versions/1.0.0/skills/incremental-implementation/SKILL.md +287 -0
  522. package/.versions/1.0.0/skills/interview-me/SKILL.md +226 -0
  523. package/.versions/1.0.0/skills/orchestration-verification/SKILL.md +181 -0
  524. package/.versions/1.0.0/skills/peer-coms/SKILL.md +90 -0
  525. package/.versions/1.0.0/skills/performance-optimization/SKILL.md +350 -0
  526. package/.versions/1.0.0/skills/planning-and-task-breakdown/SKILL.md +254 -0
  527. package/.versions/1.0.0/skills/security-and-hardening/SKILL.md +461 -0
  528. package/.versions/1.0.0/skills/spec-driven-development/SKILL.md +257 -0
  529. package/.versions/1.0.0/skills/using-agent-skills/SKILL.md +199 -0
  530. package/.versions/1.0.0/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  531. package/.versions/1.0.0/vendor/agent-skills-upstream/LICENSE +21 -0
  532. package/.versions/1.0.0/vendor/agent-skills-upstream/README.md +11 -0
  533. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  534. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  535. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  536. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  537. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  538. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  539. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  540. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  541. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  542. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  543. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  544. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  545. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  546. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  547. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  548. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  549. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  550. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  551. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  552. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  553. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  554. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  555. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  556. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  557. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  558. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  559. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  560. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  561. package/CHANGELOG.md +149 -0
  562. package/README.md +117 -79
  563. package/agents/orchestrator.md +1 -1
  564. package/{.versions/0.0.8/skills/guided-workspace-setup/companion-manifest.json → bin/catalog/harness-runtime-closure.json} +2 -0
  565. package/bin/cli.js +289 -359
  566. package/bin/force-patch-changesets.js +18 -2
  567. package/bin/lib/apply.js +86 -32
  568. package/bin/lib/desired.js +87 -0
  569. package/bin/lib/detect-agent.js +22 -38
  570. package/bin/lib/doctor.js +283 -33
  571. package/bin/lib/features.js +78 -0
  572. package/bin/lib/manifest.js +127 -48
  573. package/bin/lib/overrides.js +35 -0
  574. package/bin/lib/personas.js +37 -0
  575. package/bin/lib/plan.js +18 -9
  576. package/bin/lib/purge.js +11 -0
  577. package/bin/lib/reconcile.js +68 -0
  578. package/bin/lib/scan.js +24 -0
  579. package/bin/lib/state.js +25 -1
  580. package/bin/lib/stt-wizard.js +33 -0
  581. package/bin/lib/transaction.js +149 -0
  582. package/bin/lib/tui.js +71 -0
  583. package/bin/lib/verify.js +9 -26
  584. package/bin/snapshot-version.js +3 -6
  585. package/docs/ARCHITECTURE.md +55 -21
  586. package/docs/MIGRATION-agent-fleet.md +222 -0
  587. package/docs/agent-fleet-setup.md +124 -64
  588. package/docs/claude-code-coms-bridge.md +21 -2
  589. package/docs/coms-hermes-bridge.md +1 -1
  590. package/docs/getting-started.md +61 -217
  591. package/docs/npm-install.md +207 -429
  592. package/docs/pi-extensions.md +90 -41
  593. package/docs/pi-setup.md +48 -545
  594. package/hermes/README.md +1 -1
  595. package/install-manifest.json +385 -1255
  596. package/justfile +45 -27
  597. package/manifest-meta.json +544 -134
  598. package/node_modules/pi-ask-user/README.md +43 -5
  599. package/node_modules/pi-ask-user/index.ts +630 -75
  600. package/node_modules/pi-ask-user/package.json +1 -1
  601. package/package.json +5 -11
  602. package/scripts/coms-claude-bridge.ts +10 -0
  603. package/scripts/fleet.ts +107 -90
  604. package/scripts/lib/claude-bridge-core.ts +45 -0
  605. package/scripts/lib/fleet-command.ts +170 -15
  606. package/scripts/lib/monitor-env.ts +27 -1
  607. package/scripts/lib/peer-launch.ts +6 -2
  608. package/scripts/lib/team-project.ts +24 -4
  609. package/scripts/team-up.ts +57 -11
  610. package/skills/designing-agents/SKILL.md +1 -1
  611. package/skills/designing-agents/pi-harness-authoring.md +3 -3
  612. package/.claude/commands/build.md +0 -44
  613. package/.claude/commands/design-agent.md +0 -14
  614. package/.claude/commands/doctor-agent-fleet.md +0 -22
  615. package/.claude/commands/orchestrate.md +0 -112
  616. package/.claude/commands/prime.md +0 -22
  617. package/.claude/commands/set-hermes-watchdog.md +0 -6
  618. package/.claude/commands/setup-agent-fleet.md +0 -17
  619. package/.claude/commands/ship.md +0 -72
  620. package/.claude/commands/webperf.md +0 -32
  621. package/.claude/orchestrate-teams.yaml +0 -24
  622. package/.opencode/commands/af-build.md +0 -17
  623. package/.opencode/commands/af-code-simplify.md +0 -16
  624. package/.opencode/commands/af-compound.md +0 -16
  625. package/.opencode/commands/af-design-agent.md +0 -15
  626. package/.opencode/commands/af-doctor-agent-fleet.md +0 -22
  627. package/.opencode/commands/af-orchestrate.md +0 -112
  628. package/.opencode/commands/af-plan.md +0 -16
  629. package/.opencode/commands/af-prime.md +0 -22
  630. package/.opencode/commands/af-review.md +0 -15
  631. package/.opencode/commands/af-set-hermes-watchdog.md +0 -6
  632. package/.opencode/commands/af-setup-agent-fleet.md +0 -17
  633. package/.opencode/commands/af-ship.md +0 -16
  634. package/.opencode/commands/af-spec.md +0 -16
  635. package/.opencode/commands/af-test.md +0 -21
  636. package/.opencode/commands/af-webperf.md +0 -32
  637. package/.opencode/orchestrate-teams.yaml +0 -24
  638. package/.pi/prompts/af-doctor-agent-fleet.md +0 -22
  639. package/.pi/prompts/af-setup-agent-fleet.md +0 -19
  640. package/.versions/0.0.1/.opencode/commands/af-doctor-agent-fleet.md +0 -15
  641. package/.versions/0.0.1/.opencode/commands/af-setup-agent-fleet.md +0 -15
  642. package/.versions/0.0.1/skills/guided-workspace-setup/SKILL.md +0 -506
  643. package/.versions/0.0.10/.opencode/commands/af-doctor-agent-fleet.md +0 -22
  644. package/.versions/0.0.10/.opencode/commands/af-setup-agent-fleet.md +0 -17
  645. package/.versions/0.0.10/.pi/prompts/af-doctor-agent-fleet.md +0 -22
  646. package/.versions/0.0.10/.pi/prompts/af-setup-agent-fleet.md +0 -19
  647. package/.versions/0.0.10/skills/guided-workspace-setup/SKILL.md +0 -226
  648. package/.versions/0.0.4/.opencode/commands/af-doctor-agent-fleet.md +0 -17
  649. package/.versions/0.0.4/.opencode/commands/af-setup-agent-fleet.md +0 -15
  650. package/.versions/0.0.4/skills/guided-workspace-setup/SKILL.md +0 -535
  651. package/.versions/0.0.4/skills/guided-workspace-setup/companion-manifest.json +0 -33
  652. package/.versions/0.0.5/.opencode/commands/af-doctor-agent-fleet.md +0 -17
  653. package/.versions/0.0.5/.opencode/commands/af-setup-agent-fleet.md +0 -15
  654. package/.versions/0.0.5/skills/guided-workspace-setup/SKILL.md +0 -542
  655. package/.versions/0.0.5/skills/guided-workspace-setup/companion-manifest.json +0 -35
  656. package/.versions/0.0.6/.opencode/commands/af-doctor-agent-fleet.md +0 -17
  657. package/.versions/0.0.6/.opencode/commands/af-setup-agent-fleet.md +0 -15
  658. package/.versions/0.0.6/.pi/prompts/af-doctor-agent-fleet.md +0 -15
  659. package/.versions/0.0.6/.pi/prompts/af-setup-agent-fleet.md +0 -27
  660. package/.versions/0.0.6/skills/guided-workspace-setup/SKILL.md +0 -544
  661. package/.versions/0.0.6/skills/guided-workspace-setup/companion-manifest.json +0 -35
  662. package/.versions/0.0.7/.opencode/commands/af-doctor-agent-fleet.md +0 -17
  663. package/.versions/0.0.7/.opencode/commands/af-setup-agent-fleet.md +0 -15
  664. package/.versions/0.0.7/.pi/prompts/af-doctor-agent-fleet.md +0 -15
  665. package/.versions/0.0.7/.pi/prompts/af-setup-agent-fleet.md +0 -27
  666. package/.versions/0.0.7/skills/guided-workspace-setup/SKILL.md +0 -544
  667. package/.versions/0.0.7/skills/guided-workspace-setup/companion-manifest.json +0 -35
  668. package/.versions/0.0.8/.opencode/commands/af-doctor-agent-fleet.md +0 -17
  669. package/.versions/0.0.8/.opencode/commands/af-setup-agent-fleet.md +0 -15
  670. package/.versions/0.0.8/.pi/prompts/af-doctor-agent-fleet.md +0 -15
  671. package/.versions/0.0.8/.pi/prompts/af-setup-agent-fleet.md +0 -27
  672. package/.versions/0.0.8/skills/guided-workspace-setup/SKILL.md +0 -544
  673. package/.versions/0.0.9/.opencode/commands/af-doctor-agent-fleet.md +0 -17
  674. package/.versions/0.0.9/.opencode/commands/af-setup-agent-fleet.md +0 -15
  675. package/.versions/0.0.9/.pi/prompts/af-doctor-agent-fleet.md +0 -15
  676. package/.versions/0.0.9/.pi/prompts/af-setup-agent-fleet.md +0 -27
  677. package/.versions/0.0.9/skills/guided-workspace-setup/SKILL.md +0 -544
  678. package/bin/lib/bootstrap.js +0 -323
  679. package/bin/lib/transform-persona.js +0 -180
  680. package/docs/opencode-setup.md +0 -281
  681. package/hooks/SIMPLIFY-IGNORE.md +0 -90
  682. package/hooks/hooks.json +0 -14
  683. package/hooks/session-start.sh +0 -74
  684. package/hooks/simplify-ignore.sh +0 -302
  685. package/skills/guided-workspace-setup/SKILL.md +0 -226
  686. /package/.versions/0.0.10/{skills/guided-workspace-setup/companion-manifest.json → bin/catalog/harness-runtime-closure.json} +0 -0
  687. /package/{.opencode/commands → .versions/0.0.11/.pi/prompts}/af-set-hermes-telegram.md +0 -0
  688. /package/.versions/{0.0.9/skills/guided-workspace-setup/companion-manifest.json → 0.0.11/bin/catalog/harness-runtime-closure.json} +0 -0
  689. /package/{.claude/commands/set-hermes-telegram.md → .versions/1.0.0/.pi/prompts/af-set-hermes-telegram.md} +0 -0
  690. /package/{skills/guided-workspace-setup/companion-manifest.json → .versions/1.0.0/bin/catalog/harness-runtime-closure.json} +0 -0
@@ -0,0 +1,368 @@
1
+ # pi Extensions
2
+
3
+ A catalog of the pi extensions in this repo — what each one does, how to run it, the
4
+ supporting data it needs, and how the ported set differs from upstream.
5
+
6
+ ---
7
+
8
+ ## Attribution
9
+
10
+ The session harnesses documented here — together with their supporting agent
11
+ definitions, design specs, and the `justfile` — are ported
12
+ from the **`pi-vs-claude-code`** project:
13
+
14
+ - **Author:** [disler](https://github.com/disler) (IndyDevDan)
15
+ - **Source:** <https://github.com/disler/pi-vs-claude-code>
16
+ - **License:** MIT — Copyright (c) 2026 IndyDevDan
17
+
18
+ Ported files retain their original authorship; this repo adapts them to its layout and
19
+ conventions. Runtime design specs for the imported harnesses live in `docs/pi-specs/`.
20
+
21
+ ---
22
+
23
+ ## What these extensions are
24
+
25
+ `.pi/extensions/` ships always-on **utility** extensions — `mcp-bridge`,
26
+ `chrome-devtools-mcp`, `compact-and-continue`, `agent-fleet-update-check`, `btw`, and
27
+ `pi-voice-stt`. pi
28
+ auto-discovers that directory, so they layer onto every session. `btw` adds a
29
+ `/af-btw <task>` prompt command (plus an `Alt+'` shortcut) that forks the current session
30
+ into an in-process sub-session and opens a live modal over it — full context, same
31
+ cwd, follow-up composer, with a compact result card landing in the main transcript at
32
+ idle. See [.pi/extensions/btw/README.md](../.pi/extensions/btw/README.md).
33
+
34
+ `pi-voice-stt` adds **Alt+S** push-to-talk dictation: it records the mic to a temp WAV via
35
+ `ffmpeg` and transcribes through one of three backends — a generic OpenAI-compatible endpoint,
36
+ Azure Speech (REST short-audio, with optional per-phrase language identification), or Azure
37
+ OpenAI Whisper (Azure AI Foundry). Alt+S toggles record→insert; Enter-while-recording
38
+ transcribes and sends; Esc cancels. It is **gated**: the hotkey binds only once a provider is
39
+ configured (project-local `.ai/stt.json`, the global `~/.pi/agent/stt.json`, or `PI_STT_CONFIG`),
40
+ so an unconfigured session is a no-op. `/af-stt doctor`
41
+ checks the setup. A simplified port of [`cgarrot/pi-voice-stt`](https://github.com/cgarrot/pi-voice-stt);
42
+ see [.pi/extensions/pi-voice-stt/README.md](../.pi/extensions/pi-voice-stt/README.md).
43
+
44
+ > **macOS terminal note:** Option-to-Alt behavior belongs to the outer terminal, not macOS or Pi.
45
+ > If an Option shortcut inserts a composed character such as `ß`, configure the terminal to send
46
+ > Option as Meta. In Zed, set `terminal.option_as_meta` to `true`. This enables the existing Alt
47
+ > shortcuts; it is not an OS-wide keybinding change.
48
+
49
+ The documented harnesses below are different: each is a **session harness**. They
50
+ reshape the whole pi session — some set orchestration/UI surfaces and some gate every
51
+ tool call. The unified `just fleet` entry point composes them with a deterministic
52
+ Fleet Core: `damage-control-continue`, `ask-user-remote`, Compact & Continue,
53
+ BTW, and the update checker. Voice is an optional feature, not Default Fleet Core. `just fleet hub` adds `agent-hub`; `just fleet peer`
54
+ adds standalone coms. Harnesses live in **`.pi/harnesses/`** — a directory pi does
55
+ *not* auto-discover — so a plain `pi` run still loads no safety/orchestration harness.
56
+
57
+ ### Selective loading — read this first
58
+
59
+ pi auto-discovers every extension directory under a project's `.pi/extensions/` and loads
60
+ all of them. If the harnesses lived there, a plain `pi` run would load them all at once
61
+ — UI surfaces would fight, orchestrators would collide, and harnesses that register the
62
+ same CLI flags would abort startup with duplicate registrations. So the harnesses live in
63
+ `.pi/harnesses/` instead, and you load the desired recipe explicitly:
64
+
65
+ - through the unified `justfile` interface — `just fleet`, `just fleet hub`, `just fleet peer <name>`, `just fleet team <preset>`, …
66
+ - or directly — `pi -e .pi/harnesses/<name>/index.ts` (advanced use; you must compose safety/utilities yourself)
67
+
68
+ When you consume this repo from another project, install the harness you want into
69
+ *its* `.pi/harnesses/` (`agent-fleet install --agent pi --items pi-harness:agent-hub`,
70
+ or the `pi-fleet-core` profile for the whole stack) and load it via that project's
71
+ `justfile` region, or point `pi -e` at the harness file directly — never drop the
72
+ harnesses into `.pi/extensions/`, and never load all of them at once. The supported multi-harness
73
+ exception is loading `damage-control-continue` and `ask-user-remote` before `agent-hub` for a guarded hub session (see
74
+ [pi-setup.md](pi-setup.md#optional-pi-extensions)).
75
+
76
+ ---
77
+
78
+ ## Setup
79
+
80
+ ```bash
81
+ just fleet install # one-time runtime deps only; starts no Pi/harness
82
+ just fleet # guarded Pi + STT and core utilities
83
+ just fleet hub # guarded multi-agent hub
84
+ just fleet team docs # hub + guarded Herdr peer team
85
+ just fleet peer code-reviewer --project af # ONE peer in its own Herdr pane, no team
86
+ just fleet help # unified command grammar
87
+ just --list # shows the single public `fleet` entry point
88
+ ```
89
+
90
+ `just install` runs `npm install` for both dependency roots: `.pi/extensions/` for the
91
+ utilities (`@modelcontextprotocol/sdk`, `typebox`) and `.pi/harnesses/` for the harnesses
92
+ (`@sinclair/typebox`, `yaml`). That is the **clone** path. In a target workspace the
93
+ installer handles it: the manifests are copied in as companions, and `agent-fleet install
94
+ --allow-exec` runs `npm ci --prefix .pi/extensions` and `npm ci --prefix .pi/harnesses`
95
+ for you (without `--allow-exec` those two steps are printed in the plan and skipped, for
96
+ you to run by hand). The extension dependencies are also root production dependencies of
97
+ the published `@chankov/agent-fleet` package, so a pi-package install resolves them from
98
+ the package's real path. The `@mariozechner/pi-*` packages are provided by the pi runtime
99
+ itself.
100
+
101
+ ---
102
+
103
+ ## Catalog
104
+
105
+ | Extension | Category | What it does | Run |
106
+ |-----------|----------|--------------|-----|
107
+ | [agent-hub](../.pi/harnesses/agent-hub/README.md) | Orchestration | Supported multi-agent hub: Fleet Core guardrails, dispatcher grid, specialist delegation, research helpers, persona gate, embedded coms, `/af-handoff`, peer-as-subagent, and footer `agent fleet v<version> · <model><thinking> · <team>` — plus, inside a [herdr](https://herdr.dev) pane, fleet tools (`herdr_spawn_peer` / `herdr_read_pane` / `herdr_close_pane` with human confirmation / `herdr_notify`) | `just fleet hub` |
108
+ | [ask-user-remote](../.pi/harnesses/ask-user-remote/README.md) | Orchestration | Captures stock `pi-ask-user` and registers the default `ask_user`; with `user-remote` live it races local UI against the Hermes bridge, otherwise it is stock local behavior | Fleet Core (`just fleet`) |
109
+ | [damage-control-continue](../.pi/harnesses/damage-control-continue/README.md) | Safety | Fleet Core safety harness; guards default Pi, Hub, native children, and Herdr Pi peers. Blocks feed back without aborting the turn; protected paths support explicit approval, while dangerous command patterns remain non-exemptible | `just fleet` |
110
+ | [coms](../.pi/harnesses/coms/README.md) | Messaging | Peer-to-peer messaging between agents on one machine, composed with Fleet Core safety and utilities | `just fleet peer <name>` |
111
+ | [Hermes local monitor transport](../hermes/README.md#local-agent-hub-monitor-integration) | Optional local companion | Owner-only discovery + Unix socket for agent-hub snapshots, cursor output, and exact-generation cancellation; consumed by a separate local Hermes client | Set the two monitor environment variables, then run `just fleet team <team>` |
112
+
113
+ Each extension directory has its own `README.md` with the full description, command/tool
114
+ surface, requirements, and per-extension upstream changes.
115
+
116
+ ### Migration: retired hard-stop harness
117
+
118
+ The former `.pi/harnesses/damage-control/` hard-stop harness and its standalone recipe
119
+ are retired. Refresh pi harnesses with `agent-fleet setup` (which
120
+ calls it): removal is bound by the ownership rule, so only an unchanged, recorded copy
121
+ goes — user-modified and unowned copies are preserved, and the managed `justfile` region
122
+ is refreshed without touching recipes outside the sentinels. Use `damage-control-continue` for standalone and
123
+ Agent Hub safety; missing child safety now fails closed instead of falling back or spawning
124
+ unguarded.
125
+
126
+ ### Harness version footer and provenance
127
+
128
+ The three persistent-UI harnesses — `agent-hub`, `coms`, and
129
+ `damage-control-continue` — each register `agent fleet v<version>` on one shared status key. In pi's
130
+ default status footer, that shared key gives a supported stack exactly one version instead of one
131
+ copy per harness. `agent-hub` replaces the default footer: it does **not** consume that status
132
+ key. Its custom footer reads its own adjacent stamped manifest and renders one local version
133
+ first — `agent fleet v<version> · <model><thinking> · <team>` — so an agent-hub stack also displays the
134
+ version exactly once.
135
+
136
+ The `agent fleet` half of that label is an [OSC 8](https://gist.github.com/egmontkob/eb114294efbcd5adb1944c9f3cb5feda)
137
+ terminal hyperlink to the project homepage, so a click in a terminal that supports hyperlinks
138
+ (Ghostty, iTerm2, WezTerm, Kitty, VS Code, GNOME Terminal, tmux 3.4+) opens the repository. It is a
139
+ terminal-level link, not a TUI control: pi has no mouse tracking, so a click cannot open an
140
+ in-process overlay — the URL goes to the OS opener. Terminals without OSC 8 support render the
141
+ label unchanged, and pi's `visibleWidth`/`truncateToWidth` strip OSC sequences, so the link costs no
142
+ footer columns. Set `AGENT_FLEET_NO_LINKS=1` to fall back to a plain label on multiplexers that
143
+ mangle unknown OSC sequences (GNU screen, tmux before 3.4).
144
+
145
+ The shared version status is independent of mutable owner status: for example, a
146
+ Damage-Control violation can replace its own safety message without overwriting the version
147
+ entry. The canonical value is the root `package.json` version. During a release,
148
+ `bin/sync-harness-versions.js` stamps that value into each adjacent persistent-harness
149
+ `package.json` after the root bump and before lockfile finalization and snapshotting. Each
150
+ harness keeps a local `version.ts` provenance reader so copied or symlinked harness directories
151
+ resolve their adjacent stamp rather than the launch directory. That local provenance does not
152
+ make a harness self-contained: copied target harnesses still require the existing full
153
+ `.pi/harnesses/` dependency installation described in [Setup](#setup).
154
+
155
+ ### `agent-hub` components
156
+
157
+ `agent-hub` is the consolidated orchestration harness. It replaces the retired standalone
158
+ `agent-team` recipe and absorbs the day-to-day pieces that previously required separate
159
+ harnesses:
160
+
161
+ - **Dispatcher grid** — fixed specialists from `.pi/agents/teams.yaml`, shown in a live dashboard
162
+ with compact/full view toggling.
163
+ - **Specialist delegation** — `dispatch_agent` for writable child-agent work and
164
+ `spawn_research` / `/af-research` for read-only investigation.
165
+ - **Verification Contract** — the dispatcher owns a ledger of checkable acceptance assertions
166
+ built before any builder runs, via the `set_assertions` / `update_assertion` tools. Each
167
+ assertion is tagged (`test` | `runtime-ui` | `code-grep` | `manual`) and advanced only on
168
+ *proven with evidence*; the ledger persists to `.pi/agent-sessions/assertions.json` (wiped at
169
+ session start like `findings/`) and shows a one-line status, keeping the contract out of the
170
+ dispatcher LLM context. It kills the parity failure (exemplar shipped, siblings missed) by
171
+ requiring a parity/touchpoint inventory for "behave like" requests and runtime proof for UI
172
+ assertions — see the [`orchestration-verification`](../skills/orchestration-verification/SKILL.md)
173
+ skill, which the `orchestrator` persona drives. Advisory in this phase (surfaced, not a hard
174
+ dispatch refusal).
175
+ - **Persona gate** — requires an orchestrator persona at startup unless disabled in the local
176
+ override file; the chosen persona also feeds the coms purpose when no explicit `--purpose` is set.
177
+ - **Operator controls** — `/af-zoom` timeline inspection plus child-agent kill/restart controls.
178
+ - **Damage-control + ask_user by default** — `just fleet hub` and `just fleet hub --solo` load the
179
+ `damage-control-continue` safety harness and `ask-user-remote` before `agent-hub`, so the
180
+ dispatcher's tool calls are checked against the rules file and the `askUserAvailable` probe sees
181
+ `ask_user`. A blocked call feeds back and the turn keeps going rather than aborting. `agent-hub` also
182
+ re-loads `damage-control-continue` into every native specialist, research helper, and nested
183
+ delegate (via an explicit `-e` that survives `--no-extensions`). Protected-path access can be
184
+ granted at runtime: `/af-allow <pattern> [turn|session]` in the hub pre-authorizes, a parent-session
185
+ block opens an approval dialog, and a headless child escalates to the hub. Protected deletion
186
+ offers only deny/once; other protected paths may be scoped to an agent or session. Denial and
187
+ timeout fail closed without aborting the child turn. Destructive bash patterns are never exemptible,
188
+ and a missing continue harness refuses child dispatch.
189
+ - **Embedded coms** — peer discovery, `coms_list` / `coms_send` / `coms_get` / `coms_await`,
190
+ `/af-handoff`, and peer-as-subagent flows.
191
+ - **Solo mode** — `just fleet hub --solo` keeps the dispatcher grid, delegation, research helpers, persona
192
+ gate, and controls, but starts without the embedded coms layer.
193
+ - **Optional Hermes local monitor transport** — uses `AGENT_FLEET_PROFILE_ID`, the absolute
194
+ `AGENT_FLEET_MONITOR_RUNTIME_DIR`, and the Herdr `HERDR_WORKSPACE_ID` and `HERDR_PANE_ID`
195
+ required to establish its stable hub identity. It is a source-owned, local-only transport—not a
196
+ Hermes SDK task/lifecycle RPC or a bundled plugin—and fails closed without validated owner-only
197
+ discovery, lease, token, and socket state. Follow the
198
+ [Hermes integration guide](../hermes/README.md#local-agent-hub-monitor-integration) for startup,
199
+ wire examples, cancellation semantics, and reconnect behavior.
200
+
201
+ ---
202
+
203
+ ## Two browser stacks — when to use which
204
+
205
+ This repo ships **two** ways to drive a browser from a pi agent. They are complementary, not redundant — the axis that separates them is the **tool model** (and where they can run), not just headless-vs-headful, since both can do either:
206
+
207
+ | | `bowser` / `playwright-cli` | `web-debugger` / `chrome-devtools-mcp` |
208
+ |---|---|---|
209
+ | Tool model | CLI over **Bash** (no tool schemas in context) | live `chrome_devtools__*` MCP tools |
210
+ | Strength | headless, parallel named sessions, background automation, scraping, token-efficient | interactive headful debugging, live DOM/console/network, performance traces |
211
+ | Where it runs | **dispatched subagent** (survives `--no-extensions`), peer, or main session | main session or **coms peer** (the extension must be loaded into the process) |
212
+ | Persona | `bowser` | `web-debugger` |
213
+ | Skill | `.pi/skills/bowser/` | `skills/browser-testing-with-devtools/` |
214
+
215
+ **Policy:**
216
+
217
+ - **Automated / CI / background / parallel runtime-UI evidence** → `bowser` (headless `playwright-cli`). This is what the `orchestrator` delegates as a subagent to close `runtime-ui` acceptance assertions.
218
+ - **Interactive debugging of a running dev app** → `web-debugger` (headful `chrome-devtools-mcp`), reached as a coms peer or run on the main session.
219
+ - **Manual visual inspection / login flows** → `web-debugger` headful, or attach to an existing Chrome.
220
+ - **Always require runtime evidence** — snapshot + console + network before/after a critical interaction; a screenshot only for visual/layout confirmation.
221
+
222
+ Why `web-debugger` is a coms peer and not a dispatchable subagent: its `chrome_devtools__*` tools come from the always-on `chrome-devtools-mcp` extension, and agent-hub spawns subagents with `--no-extensions`, so a dispatched child would not have those tools. A coms peer is its own pi process that loads the extension explicitly (via the `extensions:` field in `.pi/agents/peers.yaml`, routed through the `_peer-plus` recipe), and a long-lived peer maps naturally onto one persistent live browser. `bowser` has no such constraint because it only needs Bash + the `playwright-cli` binary on PATH.
223
+
224
+ ## One peer at a time — `just fleet peer`
225
+
226
+ `just fleet team <preset>` is the right tool for a *known* set of collaborators, but it
227
+ requires every peer to be declared in `.pi/agents/peers.yaml` and it builds a whole
228
+ workspace. When you want **one** more agent — often a Claude Code reviewer — next to
229
+ what you already have:
230
+
231
+ ```bash
232
+ just fleet peer code-reviewer --project af # peers.yaml decides the runner
233
+ just fleet peer scratch-reviewer --runner claude-code --model opus --project af
234
+ just fleet peer researcher --model openai-codex/gpt-5.6-luna --project af
235
+ just fleet peer web-debugger --browser --project af # persona peer + devtools MCP
236
+ just fleet peer nick --here --project af # this terminal, not a pane
237
+ just fleet peer anything --runner claude-code --dry-run # print the plan, touch nothing
238
+ ```
239
+
240
+ **The name decides the shape of the peer** — one verb, three launchers:
241
+
242
+ | The name… | Peer | Recipe |
243
+ |---|---|---|
244
+ | is declared in `peers.yaml` | whatever it declares (`runner`, `model`, `extensions`, `env_file`) | per declaration |
245
+ | matches `agents/<name>.md` | that guarded persona peer | `_peer` / `_peer-plus` |
246
+ | matches nothing | Fleet Core + coms under that identity, no persona | `_fleet-peer` |
247
+ | `--runner claude-code` | interactive Claude Code + its coms bridge in one pane | `_claude-peer` |
248
+
249
+ The third row is what this command meant before pane placement existed, and it is the
250
+ only shape that accepts raw pi arguments — everything after `--` goes to pi verbatim
251
+ (`just fleet peer nick --here -- --session /path/to/session.json`). Note that the
252
+ persona-by-name rule can change what an existing invocation means: `agents/architect.md`
253
+ exists, so `just fleet peer architect` is now the architect persona peer. `--no-persona`
254
+ forces the plain Fleet Core shape back.
255
+
256
+ - **Placement** — by default the peer gets its own pane: run inside a herdr pane and it
257
+ splits *that* pane (`--direction right|down`); run outside herdr and it creates a
258
+ single-pane workspace labelled `<worktree-tag>-peer-<name>`, refusing to clobber an
259
+ existing one. `--here` runs it in the calling terminal instead.
260
+ - **Field resolution** — explicit flag → the `peers.yaml` declaration for that *name*
261
+ (searched across every team) → a convention default. A name the fleet already defines
262
+ keeps its declared fields; a name it does not need no manifest entry at all.
263
+ - **Nothing is silently dropped** — a flag that cannot apply to the resolved shape is an
264
+ error, not a no-op: `--all-extensions` on a persona peer, `--persona` on a Claude Code
265
+ peer, a mistyped flag, or a pi flag that forgot its `--` separator.
266
+ - **`--project` matters** — same rule as teams: the flag form is `--project af`;
267
+ `project=af` is a `just` variable override and is silently ignored, leaving the peer
268
+ in the shared `default` pool.
269
+ - **Readiness** — a pane launch waits (bounded) for the peer to register in the coms pool
270
+ and exits non-zero with the pane's last output if it never does. A peer that missed
271
+ the window has failed to start, not started slowly.
272
+
273
+ Pure logic in `scripts/lib/peer-launch.ts` (under `node --test`); the herdr wiring is
274
+ `scripts/peer-launch.ts`. Inside a hub session the equivalent is the `herdr_spawn_peer`
275
+ tool, which shares the same command builder and readiness policy.
276
+
277
+ ## Environment variables
278
+
279
+ The `justfile` sets `dotenv-load`, so a `.env` file at the repo root is auto-loaded
280
+ (`.env` is gitignored). Only a few extensions need keys:
281
+
282
+ | Variable | Needed by | Purpose |
283
+ |----------|-----------|---------|
284
+ | `PI_CHROME_DEVTOOLS_MODE` | `chrome-devtools-mcp` | `headless` runs Chrome with no UI; anything else (default) is headed |
285
+ | `PI_CHROME_DEVTOOLS_BROWSER_URL` | `chrome-devtools-mcp` | Attach to a running Chrome (e.g. `http://127.0.0.1:9222`) instead of launching one |
286
+ | `PI_CHROME_DEVTOOLS_USER_DATA_DIR` | `chrome-devtools-mcp` | Persistent Chrome profile path (else the default ephemeral `--isolated` profile) |
287
+ | `OPENAI_API_KEY` | `pi-voice-stt` (openai backend) | API key for the OpenAI-compatible transcription endpoint (var name overridable via `provider.apiKeyEnv`) |
288
+ | `AZURE_SPEECH_KEY` | `pi-voice-stt` (azure backend) | Azure Speech resource key |
289
+ | `AZURE_SPEECH_ENDPOINT` | `pi-voice-stt` (azure backend) | Azure resource endpoint, used when `provider.endpoint` is unset |
290
+ | `PI_STT_CONFIG` / `PI_STT_KEYBIND` | `pi-voice-stt` | Override config (inline JSON or path) / the record hotkey (default `alt+s`) |
291
+ | `AGENT_FLEET_SPAWN_DELAY` | `_peer` / `_peer-plus` recipes | Seconds to sleep before launching pi in a fleet pane (set per pane by `just fleet team`/`just fleet resume`, see below) |
292
+
293
+ The `chrome-devtools-mcp` server starts once at extension load, so changing its vars needs a pi
294
+ restart / `/reload` to take effect.
295
+
296
+ ### Spawn pre-warm/stagger
297
+
298
+ pi loads its credential store (`~/.pi/agent/auth.json`) once at boot under a short-retry
299
+ file lock. When the stored OAuth token is stale, the first pi to boot refreshes it over
300
+ the network *while holding that lock*; sibling panes spawned in the same instant (as
301
+ `just fleet team` / `just fleet resume` do) lose the lock race and come up
302
+ with every provider showing **unconfigured**. To dodge this, the team scripts check
303
+ `auth.json` before spawning (only `type`/`expires` are read — values never leave the
304
+ process): if any OAuth credential is expired or about to expire, one pi pane (the hub
305
+ when present, else the first pi peer) starts immediately and refreshes the token, and
306
+ every other pi pane gets `AGENT_FLEET_SPAWN_DELAY` in its pane env — the `_peer` /
307
+ `_peer-plus` recipes sleep that many seconds before launching pi. Fresh tokens mean zero
308
+ delay everywhere; `claude-code` runner panes never wait. Pure logic in
309
+ `scripts/lib/spawn-stagger.ts` (under `node --test`).
310
+
311
+ ---
312
+
313
+ ## Supporting data
314
+
315
+ These ported files are runtime dependencies of the extensions above:
316
+
317
+ - **`agents/`** — canonical persona Markdown files for shared and pi-specific agents.
318
+ Read by `agent-hub`.
319
+ - **`.pi/agents/`** — pi YAML configs only (`teams.yaml`, `peers.yaml`).
320
+ The earlier `reviewer` and `red-team` personas were folded into `code-reviewer` and
321
+ `security-auditor`; the remaining team/peer configs already reference the canonical names.
322
+ A peer entry may carry an optional `extensions:` field (comma-separated names under
323
+ `.pi/extensions/`) — Fleet's team launcher then routes it through the `_peer-plus` recipe so those
324
+ extensions load into the peer process. The `web-debugger` peer uses this to get
325
+ `chrome-devtools-mcp`'s `chrome_devtools__*` tools (see the two-browser-stacks section above).
326
+ - **`.pi/damage-control-rules.yaml`** — the destructive-command / protected-path rule set
327
+ for `damage-control-continue`.
328
+ - **`.pi/skills/bowser/`** — a pi-runtime skill for headless Playwright browser
329
+ automation, used by the `bowser` agent persona. Kept separate from the core
330
+ engineering `skills/`. It drives the external **Playwright Agent CLI**
331
+ (`playwright-cli`), which is **not** bundled — install it once with
332
+ `npm install -g @playwright/cli@latest` (deterministic setup checks for it when
333
+ `bowser` is selected). Docs: <https://playwright.dev/agent-cli/installation>.
334
+ - **`docs/pi-specs/`** — the original design specifications: `agent-forge` (now consolidated
335
+ into `agent-hub`), `agent-workflow` (retired `agent-chain`), and `damage-control`.
336
+
337
+ ---
338
+
339
+ ## Upstream changes
340
+
341
+ What changed relative to `disler/pi-vs-claude-code`:
342
+
343
+ - **Theme code removed.** Every ported harness imported `applyExtensionDefaults` from a
344
+ shared `themeMap.ts`. That import and its `session_start` call site were stripped from
345
+ the ported files; `themeMap.ts` and the 11 `.pi/themes/*.json` palettes are not ported.
346
+ Extensions render against pi's active theme.
347
+ - **Layout converted.** Flat `extensions/<name>.ts` files became
348
+ `.pi/harnesses/<name>/index.ts` directories, each with its own `package.json` and
349
+ `README.md`. They live under `.pi/harnesses/` — *not* `.pi/extensions/` — because pi
350
+ auto-discovers and loads everything in `.pi/extensions/`, while harnesses must be loaded
351
+ explicitly through recipes (with `damage-control-continue` + `ask-user-remote` before
352
+ `agent-hub` as the supported stack).
353
+ - **Tooling switched to npm.** `bun` / `bun.lock` are not used; the `justfile` recipes
354
+ point at the new paths and use npm.
355
+
356
+ ### Not ported
357
+
358
+ - The `pure-focus`, `theme-cycler`, and `cross-agent` extensions.
359
+ - `themeMap.ts` and all 11 `.pi/themes/*.json` theme palettes.
360
+ - The Claude Code `statusLine` config and `status_lines/status_line.py`, and the
361
+ `plan_w_team.md` command (it depended on team-agent files absent from the source).
362
+
363
+ ### A note on `.pi/settings.json`
364
+
365
+ Upstream shipped a `.pi/settings.json` that only set the (now-stripped) theme and
366
+ registered a prompt directory. This repo already keeps pi prompts in the standard
367
+ `.pi/prompts/` location, so no `.pi/settings.json` is shipped — it would carry nothing
368
+ useful.
@@ -0,0 +1,57 @@
1
+ # pi setup
2
+
3
+ Agent Fleet is pi-first. Its deterministic lifecycle writes copied workspace
4
+ artifacts; the package-native path exposes skills/prompts directly.
5
+
6
+ ## Lifecycle install
7
+
8
+ ```bash
9
+ npx @chankov/agent-fleet@latest setup
10
+ npx @chankov/agent-fleet@1.0.0 setup --preset default --features none --yes
11
+ npx @chankov/agent-fleet@1.0.0 setup --preset full --features none --yes
12
+ ```
13
+
14
+ Default is launchable Fleet Core and does not create `.claude/` or voice
15
+ configuration. Full selects stable, platform-applicable roots and may add the
16
+ recorded Claude Code coms bridge. Feature flags are named additions over a
17
+ preset; they are not an arbitrary package picker. Flags do not rewrite an
18
+ existing desired file unless `--save-desired` is explicit.
19
+
20
+ The installer owns only paths in `.ai/agent-fleet-state.json`. Normal uninstall
21
+ preserves `.ai/agent-fleet.json`, `.ai/agent-fleet-overrides.md`, `.ai/stt.json`,
22
+ and environment files. See [npm-install.md](npm-install.md) for `--migrate`,
23
+ `--purge-config`, doctor exits, and self-uninstall recovery.
24
+
25
+ ## Runtime closure
26
+
27
+ `just fleet` is the guarded Fleet Core launcher. It explicitly loads
28
+ `damage-control-continue`, `ask-user-remote`, compact-and-continue, BTW, and
29
+ the update checker. Voice is not a Default Core dependency. `just fleet hub`
30
+ adds agent-hub; `just fleet peer` adds coms; `just fleet team` uses Herdr.
31
+
32
+ ```bash
33
+ just fleet help
34
+ just fleet doctor
35
+ just fleet uninstall --yes
36
+ ```
37
+
38
+ Self-uninstall removes the managed justfile region and dispatcher scripts last,
39
+ so its report completes. Restore it only through `npx @chankov/agent-fleet
40
+ setup ...`; then `just fleet doctor` is available again.
41
+
42
+ ## Package-native skills and prompts
43
+
44
+ ```bash
45
+ pi install -l npm:@chankov/agent-fleet
46
+ ```
47
+
48
+ Do not also copy the same skills/prompts into `.pi/`; that creates collisions.
49
+ Harness-only composition (package-native skills/prompts plus copied harnesses)
50
+ is supported. The package bundles `pi-ask-user`; copied plain-pi installations
51
+ need their own compatible `pi-ask-user` source.
52
+
53
+ ## Project-owned configuration
54
+
55
+ `.ai/agent-fleet-overrides.md` is minimal committed project configuration;
56
+ `.ai/stt.json` contains provider names and environment-variable names, never
57
+ secret values. The root environment file is human-owned and append-only.
@@ -0,0 +1,150 @@
1
+ # Skill Anatomy
2
+
3
+ This document describes the structure and format of agent-fleet skill files. Use this as a guide when contributing new skills or understanding existing ones.
4
+
5
+ ## File Location
6
+
7
+ Every skill lives in its own directory under `skills/`:
8
+
9
+ ```
10
+ skills/
11
+ skill-name/
12
+ SKILL.md # Required: The skill definition
13
+ scripts/ # Optional: Runnable helpers used by the skill workflow
14
+ supporting-file.md # Optional: Reference material loaded on demand
15
+ ```
16
+
17
+ `SKILL.md` is the only required file. Add `scripts/` only when the skill actually ships runnable helpers, and omit the directory entirely for markdown-only skills.
18
+
19
+ ## SKILL.md Format
20
+
21
+ ### Frontmatter (Required)
22
+
23
+ ```yaml
24
+ ---
25
+ name: skill-name-with-hyphens
26
+ description: Guides agents through [task/workflow]. Use when [specific trigger conditions].
27
+ ---
28
+ ```
29
+
30
+ **Rules:**
31
+ - `name`: Lowercase, hyphen-separated. Must match the directory name.
32
+ - `description`: Start with what the skill does in third person, then include one or more clear "Use when" trigger conditions. Include both *what* and *when*. Maximum 1024 characters.
33
+
34
+ **Why this matters:** Agents discover skills by reading descriptions. The description is injected into the system prompt, so it must tell the agent both what the skill provides and when to activate it. Do not summarize the workflow — if the description contains process steps, the agent may follow the summary instead of reading the full skill.
35
+
36
+ ### Standard Sections (Recommended Pattern)
37
+
38
+ The frontmatter contract above is required. The section layout below is a recommended pattern, not a rigid template: equivalent headings are acceptable when they serve the same purpose clearly.
39
+
40
+ ```markdown
41
+ # Skill Title
42
+
43
+ ## Overview
44
+ One-two sentences explaining what this skill does and why it matters.
45
+
46
+ ## When to Use
47
+ - Bullet list of triggering conditions (symptoms, task types)
48
+ - When NOT to use (exclusions)
49
+
50
+ ## [Core Process / The Workflow / Steps]
51
+ The main workflow, broken into numbered steps or phases.
52
+ Include code examples where they help.
53
+ Use flowcharts (ASCII) where decision points exist.
54
+
55
+ ## [Specific Techniques / Patterns]
56
+ Detailed guidance for specific scenarios.
57
+ Code examples, templates, configuration.
58
+
59
+ ## Common Rationalizations
60
+ | Rationalization | Reality |
61
+ |---|---|
62
+ | Excuse agents use to skip steps | Why the excuse is wrong |
63
+
64
+ ## Red Flags
65
+ - Behavioral patterns indicating the skill is being violated
66
+ - Things to watch for during review
67
+
68
+ ## Verification
69
+ After completing the skill's process, confirm:
70
+ - [ ] Checklist of exit criteria
71
+ - [ ] Evidence requirements
72
+ ```
73
+
74
+ ## Section Purposes
75
+
76
+ ### Overview
77
+ The "elevator pitch" for the skill. Should answer: What does this skill do, and why should an agent follow it?
78
+
79
+ ### When to Use
80
+ Helps agents and humans decide if this skill applies to the current task. Include both positive triggers ("Use when X") and negative exclusions ("NOT for Y").
81
+
82
+ ### Core Process
83
+ The heart of the skill. This is the step-by-step workflow the agent follows. Must be specific and actionable — not vague advice.
84
+
85
+ **Good:** "Run `npm test` and verify all tests pass"
86
+ **Bad:** "Make sure the tests work"
87
+
88
+ ### Common Rationalizations
89
+ The most distinctive feature of well-crafted skills. These are excuses agents use to skip important steps, paired with rebuttals. They prevent the agent from rationalizing its way out of following the process.
90
+
91
+ Think of every time an agent has said "I'll add tests later" or "This is simple enough to skip the spec" — those go here with a factual counter-argument.
92
+
93
+ ### Red Flags
94
+ Observable signs that the skill is being violated. Useful during code review and self-monitoring.
95
+
96
+ ### Verification
97
+ The exit criteria. A checklist the agent uses to confirm the skill's process is complete. Every checkbox should be verifiable with evidence (test output, build result, screenshot, etc.).
98
+
99
+ ## Supporting Files
100
+
101
+ Create supporting files only when:
102
+ - Reference material exceeds 100 lines (keep the main SKILL.md focused)
103
+ - Code tools or scripts are needed
104
+ - Checklists are long enough to justify separate files
105
+
106
+ Keep patterns and principles inline when under 50 lines.
107
+
108
+ If a skill does not need runnable helpers, do not create an empty `scripts/` directory just to mirror other skills. Empty directories add noise without changing how the skill works.
109
+
110
+ ## Writing Principles
111
+
112
+ 1. **Process over knowledge.** Skills are workflows, not reference docs. Steps, not facts.
113
+ 2. **Specific over general.** "Run `npm test`" beats "verify the tests".
114
+ 3. **Evidence over assumption.** Every verification checkbox requires proof.
115
+ 4. **Anti-rationalization.** Every skip-worthy step needs a counter-argument in the rationalizations table.
116
+ 5. **Progressive disclosure.** Main SKILL.md is the entry point. Supporting files are loaded only when needed.
117
+ 6. **Token-conscious.** Every section must justify its inclusion. If removing it wouldn't change agent behavior, remove it.
118
+ 7. **Prompting-patterns applied.** Before finalizing a skill, verify its language against `references/prompting-patterns.md` — positive instructions over prohibitions, explain *why* behind non-obvious rules, no ALL-CAPS or reward/punishment language.
119
+
120
+ ## Naming Conventions
121
+
122
+ - Skill directories: `lowercase-hyphen-separated`
123
+ - Skill files: `SKILL.md` (always uppercase)
124
+ - Supporting files: `lowercase-hyphen-separated.md`
125
+ - References: stored in `references/` at the project root, not inside skill directories
126
+
127
+ ## Cross-Skill References
128
+
129
+ Reference other skills by name:
130
+
131
+ ```markdown
132
+ Follow the `test-driven-development` skill for writing tests.
133
+ If the build breaks, use the `debugging-and-error-recovery` skill.
134
+ ```
135
+
136
+ Don't duplicate content between skills — reference and link instead.
137
+
138
+ ## Required vs Recommended
139
+
140
+ Required:
141
+
142
+ - A `skills/<skill-name>/SKILL.md` file
143
+ - Valid YAML frontmatter with `name` and `description`
144
+ - A description that includes both what the skill does and when to use it
145
+
146
+ Recommended:
147
+
148
+ - The standard section flow shown above
149
+ - Equivalent headings such as `How It Works`, `Core Process`, or `Workflow` when they read more naturally for the skill
150
+ - Supporting files only when they keep the main `SKILL.md` focused