@chankov/agent-fleet 0.0.11 → 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 (494) hide show
  1. package/.pi/extensions/agent-fleet-update-check/README.md +4 -4
  2. package/.pi/extensions/btw/README.md +26 -25
  3. package/.pi/extensions/btw/index.ts +80 -83
  4. package/.pi/extensions/pi-voice-stt/README.md +4 -3
  5. package/.pi/extensions/pi-voice-stt/config.ts +1 -1
  6. package/.pi/harnesses/agent-hub/README.md +106 -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/extensions/agent-fleet-update-check/README.md +4 -4
  29. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/README.md +4 -3
  30. package/.versions/0.0.11/.pi/extensions/pi-voice-stt/config.ts +1 -1
  31. package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-session-bridge.ts +10 -1
  32. package/.versions/0.0.11/.pi/harnesses/ask-user-remote/README.md +37 -3
  33. package/.versions/0.0.11/.pi/harnesses/ask-user-remote/index.ts +173 -17
  34. package/.versions/0.0.11/.pi/harnesses/package-lock.json +2011 -0
  35. package/.versions/0.0.11/.pi/harnesses/package.json +1 -0
  36. package/.versions/0.0.11/docs/ARCHITECTURE.md +6 -8
  37. package/.versions/0.0.11/docs/agent-fleet-setup.md +17 -43
  38. package/.versions/0.0.11/docs/claude-code-coms-bridge.md +20 -2
  39. package/.versions/0.0.11/docs/coms-hermes-bridge.md +1 -1
  40. package/.versions/0.0.11/docs/getting-started.md +26 -237
  41. package/.versions/0.0.11/docs/npm-install.md +60 -478
  42. package/.versions/0.0.11/docs/pi-extensions.md +4 -4
  43. package/.versions/0.0.11/docs/pi-setup.md +37 -551
  44. package/.versions/0.0.11/hermes/README.md +1 -1
  45. package/.versions/0.0.11/install-manifest.json +375 -1247
  46. package/.versions/0.0.11/justfile +13 -6
  47. package/.versions/0.0.11/manifest-meta.json +543 -134
  48. package/.versions/0.0.11/scripts/lib/fleet-command.ts +8 -0
  49. package/.versions/0.0.11/scripts/lib/monitor-env.ts +18 -6
  50. package/.versions/0.0.11/skills/designing-agents/SKILL.md +1 -1
  51. package/.versions/0.0.11/skills/designing-agents/pi-harness-authoring.md +1 -1
  52. package/.versions/1.0.0/.pi/agents/dispatch-policy.yaml +32 -0
  53. package/.versions/1.0.0/.pi/agents/model-profiles.yaml +27 -0
  54. package/.versions/1.0.0/.pi/agents/peers.yaml +142 -0
  55. package/.versions/1.0.0/.pi/agents/teams.yaml +41 -0
  56. package/.versions/1.0.0/.pi/damage-control-rules.yaml +297 -0
  57. package/.versions/1.0.0/.pi/extensions/agent-fleet-update-check/README.md +57 -0
  58. package/.versions/1.0.0/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  59. package/.versions/1.0.0/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  60. package/.versions/1.0.0/.pi/extensions/btw/README.md +120 -0
  61. package/.versions/1.0.0/.pi/extensions/btw/index.ts +914 -0
  62. package/.versions/1.0.0/.pi/extensions/btw/package.json +6 -0
  63. package/.versions/1.0.0/.pi/extensions/btw/state.js +179 -0
  64. package/.versions/1.0.0/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
  65. package/.versions/1.0.0/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
  66. package/.versions/1.0.0/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  67. package/.versions/1.0.0/.pi/extensions/compact-and-continue/README.md +42 -0
  68. package/.versions/1.0.0/.pi/extensions/compact-and-continue/index.ts +120 -0
  69. package/.versions/1.0.0/.pi/extensions/compact-and-continue/package.json +6 -0
  70. package/.versions/1.0.0/.pi/extensions/mcp-bridge/README.md +46 -0
  71. package/.versions/1.0.0/.pi/extensions/mcp-bridge/index.ts +206 -0
  72. package/.versions/1.0.0/.pi/extensions/mcp-bridge/package.json +6 -0
  73. package/.versions/1.0.0/.pi/extensions/package-lock.json +1143 -0
  74. package/.versions/1.0.0/.pi/extensions/package.json +9 -0
  75. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/README.md +205 -0
  76. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/config.ts +198 -0
  77. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  78. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/index.ts +248 -0
  79. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/package.json +6 -0
  80. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  81. package/.versions/1.0.0/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  82. package/.versions/1.0.0/.pi/harnesses/agent-hub/README.md +1056 -0
  83. package/.versions/1.0.0/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  84. package/.versions/1.0.0/.pi/harnesses/agent-hub/artifacts.js +146 -0
  85. package/.versions/1.0.0/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
  86. package/.versions/1.0.0/.pi/harnesses/agent-hub/backend-policy.js +174 -0
  87. package/.versions/1.0.0/.pi/harnesses/agent-hub/context-window.js +106 -0
  88. package/.versions/1.0.0/.pi/harnesses/agent-hub/delegate.ts +435 -0
  89. package/.versions/1.0.0/.pi/harnesses/agent-hub/docs-lane.js +122 -0
  90. package/.versions/1.0.0/.pi/harnesses/agent-hub/drift-watchdog.js +211 -0
  91. package/.versions/1.0.0/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  92. package/.versions/1.0.0/.pi/harnesses/agent-hub/external-blocker.js +85 -0
  93. package/.versions/1.0.0/.pi/harnesses/agent-hub/footer.ts +35 -0
  94. package/.versions/1.0.0/.pi/harnesses/agent-hub/helpers.ts +266 -0
  95. package/.versions/1.0.0/.pi/harnesses/agent-hub/index.ts +9279 -0
  96. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  97. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
  98. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
  99. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  100. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  101. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  102. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  103. package/.versions/1.0.0/.pi/harnesses/agent-hub/monitor-session-bridge.ts +266 -0
  104. package/.versions/1.0.0/.pi/harnesses/agent-hub/package.json +7 -0
  105. package/.versions/1.0.0/.pi/harnesses/agent-hub/peer-spawn-plan.ts +116 -0
  106. package/.versions/1.0.0/.pi/harnesses/agent-hub/posture.ts +103 -0
  107. package/.versions/1.0.0/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
  108. package/.versions/1.0.0/.pi/harnesses/agent-hub/research-retention.js +34 -0
  109. package/.versions/1.0.0/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  110. package/.versions/1.0.0/.pi/harnesses/agent-hub/return-contract.js +293 -0
  111. package/.versions/1.0.0/.pi/harnesses/agent-hub/return-extract.js +75 -0
  112. package/.versions/1.0.0/.pi/harnesses/agent-hub/review-findings.js +102 -0
  113. package/.versions/1.0.0/.pi/harnesses/agent-hub/run-budget.js +479 -0
  114. package/.versions/1.0.0/.pi/harnesses/agent-hub/run-namespace.js +87 -0
  115. package/.versions/1.0.0/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  116. package/.versions/1.0.0/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  117. package/.versions/1.0.0/.pi/harnesses/agent-hub/session-health.js +110 -0
  118. package/.versions/1.0.0/.pi/harnesses/agent-hub/spawn.ts +354 -0
  119. package/.versions/1.0.0/.pi/harnesses/agent-hub/version.ts +42 -0
  120. package/.versions/1.0.0/.pi/harnesses/ask-user-remote/README.md +53 -0
  121. package/.versions/1.0.0/.pi/harnesses/ask-user-remote/index.ts +477 -0
  122. package/.versions/1.0.0/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  123. package/.versions/1.0.0/.pi/harnesses/coms/README.md +100 -0
  124. package/.versions/1.0.0/.pi/harnesses/coms/index.ts +1767 -0
  125. package/.versions/1.0.0/.pi/harnesses/coms/package.json +7 -0
  126. package/.versions/1.0.0/.pi/harnesses/coms/version.ts +42 -0
  127. package/.versions/1.0.0/.pi/harnesses/damage-control-continue/README.md +124 -0
  128. package/.versions/1.0.0/.pi/harnesses/damage-control-continue/index.ts +536 -0
  129. package/.versions/1.0.0/.pi/harnesses/damage-control-continue/package.json +7 -0
  130. package/.versions/1.0.0/.pi/harnesses/damage-control-continue/version.ts +42 -0
  131. package/.versions/1.0.0/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
  132. package/.versions/1.0.0/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  133. package/.versions/1.0.0/.pi/harnesses/lib/fleet-dashboard-ops.ts +118 -0
  134. package/.versions/1.0.0/.pi/harnesses/lib/fleet-dashboard-view.ts +140 -0
  135. package/.versions/1.0.0/.pi/harnesses/lib/fleet-detail-view.ts +43 -0
  136. package/.versions/1.0.0/.pi/harnesses/lib/fleet-overlay.ts +26 -0
  137. package/.versions/1.0.0/.pi/harnesses/lib/fleet-panel.ts +34 -0
  138. package/.versions/1.0.0/.pi/harnesses/lib/fleet-read-model.ts +131 -0
  139. package/.versions/1.0.0/.pi/harnesses/lib/fleet-selection.ts +24 -0
  140. package/.versions/1.0.0/.pi/harnesses/lib/herdr-client.ts +472 -0
  141. package/.versions/1.0.0/.pi/harnesses/lib/herdr-presence.ts +399 -0
  142. package/.versions/1.0.0/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
  143. package/.versions/1.0.0/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  144. package/.versions/1.0.0/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
  145. package/.versions/1.0.0/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  146. package/.versions/1.0.0/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
  147. package/.versions/1.0.0/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  148. package/.versions/1.0.0/.pi/harnesses/lib/spawned-peers.js +190 -0
  149. package/.versions/1.0.0/.pi/harnesses/package-lock.json +2046 -0
  150. package/.versions/1.0.0/.pi/harnesses/package.json +10 -0
  151. package/.versions/1.0.0/.pi/prompts/af-build.md +24 -0
  152. package/{.claude/commands/code-simplify.md → .versions/1.0.0/.pi/prompts/af-code-simplify.md} +3 -3
  153. package/{.claude/commands/plan.md → .versions/1.0.0/.pi/prompts/af-plan.md} +1 -1
  154. package/.versions/{0.0.11/.claude/commands/review.md → 1.0.0/.pi/prompts/af-review.md} +3 -3
  155. package/.versions/1.0.0/.pi/prompts/af-set-hermes-watchdog.md +6 -0
  156. package/.versions/1.0.0/.pi/prompts/af-ship.md +17 -0
  157. package/.versions/{0.0.11/.claude/commands/spec.md → 1.0.0/.pi/prompts/af-spec.md} +1 -1
  158. package/.versions/{0.0.11/.claude/commands/test.md → 1.0.0/.pi/prompts/af-test.md} +2 -2
  159. package/.versions/1.0.0/.pi/skills/bowser/SKILL.md +145 -0
  160. package/.versions/1.0.0/.version +1 -0
  161. package/.versions/1.0.0/agents/architect.md +24 -0
  162. package/.versions/1.0.0/agents/bowser.md +27 -0
  163. package/.versions/1.0.0/agents/builder.md +54 -0
  164. package/.versions/1.0.0/agents/code-reviewer.md +208 -0
  165. package/.versions/1.0.0/agents/deep-researcher.md +32 -0
  166. package/.versions/1.0.0/agents/documenter.md +18 -0
  167. package/.versions/1.0.0/agents/orchestrator.md +72 -0
  168. package/.versions/1.0.0/agents/plan-reviewer.md +83 -0
  169. package/.versions/1.0.0/agents/planner.md +70 -0
  170. package/.versions/1.0.0/agents/releaser.md +24 -0
  171. package/.versions/1.0.0/agents/researcher.md +28 -0
  172. package/.versions/1.0.0/agents/security-auditor.md +167 -0
  173. package/.versions/1.0.0/agents/test-engineer.md +153 -0
  174. package/.versions/1.0.0/agents/web-debugger.md +43 -0
  175. package/.versions/1.0.0/agents/web-performance-auditor.md +193 -0
  176. package/.versions/1.0.0/codex/CONDUCTOR.md +148 -0
  177. package/.versions/1.0.0/docs/ARCHITECTURE.md +337 -0
  178. package/.versions/1.0.0/docs/agent-fleet-setup.md +437 -0
  179. package/.versions/1.0.0/docs/claude-code-coms-bridge.md +128 -0
  180. package/.versions/1.0.0/docs/codex-remote-conductor.md +170 -0
  181. package/.versions/1.0.0/docs/coms-hermes-bridge.md +189 -0
  182. package/.versions/1.0.0/docs/getting-started.md +98 -0
  183. package/.versions/1.0.0/docs/npm-install.md +292 -0
  184. package/.versions/1.0.0/docs/pi-extensions.md +412 -0
  185. package/.versions/1.0.0/docs/pi-setup.md +74 -0
  186. package/.versions/1.0.0/docs/skill-anatomy.md +150 -0
  187. package/.versions/1.0.0/hermes/README.md +347 -0
  188. package/.versions/1.0.0/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
  189. package/.versions/1.0.0/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
  190. package/.versions/1.0.0/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  191. package/.versions/1.0.0/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  192. package/.versions/1.0.0/hermes/gates/gate-o-capability.md +8 -0
  193. package/.versions/1.0.0/hermes/gates/gate-o-validator-fixtures.json +1 -0
  194. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +770 -0
  195. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
  196. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
  197. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
  198. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
  199. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
  200. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
  201. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
  202. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
  203. package/.versions/1.0.0/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
  204. package/.versions/1.0.0/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
  205. package/.versions/1.0.0/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  206. package/.versions/1.0.0/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  207. package/.versions/1.0.0/hermes/skills/hub-conductor/SKILL.md +84 -0
  208. package/.versions/1.0.0/hermes/skills/hub-liaison/SKILL.md +84 -0
  209. package/.versions/1.0.0/hermes/skills/hub-watchdog/SKILL.md +76 -0
  210. package/.versions/1.0.0/hermes/skills/hub-watchdog/manifest.json +1 -0
  211. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
  212. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
  213. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
  214. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
  215. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
  216. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
  217. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
  218. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
  219. package/.versions/1.0.0/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
  220. package/.versions/1.0.0/hermes/watchdog-tests/__init__.py +0 -0
  221. package/.versions/1.0.0/hooks/coms-stop-hook.mjs +84 -0
  222. package/.versions/1.0.0/install-manifest.json +2745 -0
  223. package/.versions/1.0.0/justfile +272 -0
  224. package/.versions/1.0.0/manifest-meta.json +882 -0
  225. package/.versions/1.0.0/references/accessibility-checklist.md +160 -0
  226. package/.versions/1.0.0/references/definition-of-done.md +67 -0
  227. package/.versions/1.0.0/references/fleet-coordination-patterns.md +151 -0
  228. package/.versions/1.0.0/references/observability-checklist.md +91 -0
  229. package/.versions/1.0.0/references/orchestration-patterns.md +370 -0
  230. package/.versions/1.0.0/references/performance-checklist.md +153 -0
  231. package/.versions/1.0.0/references/prompting-patterns.md +380 -0
  232. package/.versions/1.0.0/references/security-checklist.md +179 -0
  233. package/.versions/1.0.0/references/testing-patterns.md +236 -0
  234. package/.versions/1.0.0/scripts/codex-conductor.ts +41 -0
  235. package/.versions/1.0.0/scripts/codex-remote-control.ts +167 -0
  236. package/.versions/1.0.0/scripts/coms-claude-bridge.ts +411 -0
  237. package/.versions/1.0.0/scripts/coms-cli.ts +484 -0
  238. package/.versions/1.0.0/scripts/coms-hermes-bridge.ts +413 -0
  239. package/.versions/1.0.0/scripts/fleet.ts +185 -0
  240. package/.versions/1.0.0/scripts/hermes-monitor-capability-runner.ts +25 -0
  241. package/.versions/1.0.0/scripts/hermes-monitor-scenario.ts +474 -0
  242. package/.versions/1.0.0/scripts/hermes-watchdog-capability-probe.ts +45 -0
  243. package/.versions/1.0.0/scripts/install-hermes-plugin.sh +180 -0
  244. package/.versions/1.0.0/scripts/lib/claude-bridge-core.ts +210 -0
  245. package/.versions/1.0.0/scripts/lib/codex-conductor.ts +88 -0
  246. package/.versions/1.0.0/scripts/lib/codex-remote-control.ts +480 -0
  247. package/.versions/1.0.0/scripts/lib/coms-envelope.ts +582 -0
  248. package/.versions/1.0.0/scripts/lib/fake-herdr-server.ts +88 -0
  249. package/.versions/1.0.0/scripts/lib/fleet-command.ts +266 -0
  250. package/.versions/1.0.0/scripts/lib/herdr-layout.ts +281 -0
  251. package/.versions/1.0.0/scripts/lib/hermes-bridge-core.ts +241 -0
  252. package/.versions/1.0.0/scripts/lib/hermes-monitor-events.ts +1 -0
  253. package/.versions/1.0.0/scripts/lib/hermes-monitor-herdr.ts +2 -0
  254. package/.versions/1.0.0/scripts/lib/hermes-monitor-model.ts +3 -0
  255. package/.versions/1.0.0/scripts/lib/hermes-monitor-registry.ts +2 -0
  256. package/.versions/1.0.0/scripts/lib/hermes-monitor-socket.ts +2 -0
  257. package/.versions/1.0.0/scripts/lib/hermes-monitor-store.ts +2 -0
  258. package/.versions/1.0.0/scripts/lib/monitor-env.ts +146 -0
  259. package/.versions/1.0.0/scripts/lib/peer-launch.ts +318 -0
  260. package/.versions/1.0.0/scripts/lib/persona-banner.ts +62 -0
  261. package/.versions/1.0.0/scripts/lib/spawn-stagger.ts +101 -0
  262. package/.versions/1.0.0/scripts/lib/team-project.ts +213 -0
  263. package/.versions/1.0.0/scripts/lib/team-snapshot.ts +147 -0
  264. package/.versions/1.0.0/scripts/peer-banner.ts +40 -0
  265. package/.versions/1.0.0/scripts/peer-launch.ts +259 -0
  266. package/.versions/1.0.0/scripts/team-snapshot.ts +237 -0
  267. package/.versions/1.0.0/scripts/team-up.ts +406 -0
  268. package/.versions/1.0.0/skills/_internal/grilling.md +11 -0
  269. package/.versions/1.0.0/skills/browser-testing-with-devtools/SKILL.md +351 -0
  270. package/.versions/1.0.0/skills/code-review-and-quality/SKILL.md +381 -0
  271. package/.versions/1.0.0/skills/compound-learning/SKILL.md +137 -0
  272. package/.versions/1.0.0/skills/context-engineering/SKILL.md +291 -0
  273. package/.versions/1.0.0/skills/deprecation-and-migration/SKILL.md +206 -0
  274. package/.versions/1.0.0/skills/designing-agents/SKILL.md +394 -0
  275. package/.versions/1.0.0/skills/designing-agents/pi-harness-authoring.md +222 -0
  276. package/.versions/1.0.0/skills/frontend-ui-engineering/SKILL.md +328 -0
  277. package/.versions/1.0.0/skills/git-workflow-and-versioning/SKILL.md +316 -0
  278. package/.versions/1.0.0/skills/idea-refine/SKILL.md +182 -0
  279. package/.versions/1.0.0/skills/idea-refine/examples.md +238 -0
  280. package/.versions/1.0.0/skills/idea-refine/frameworks.md +99 -0
  281. package/.versions/1.0.0/skills/idea-refine/refinement-criteria.md +113 -0
  282. package/.versions/1.0.0/skills/idea-refine/scripts/idea-refine.sh +15 -0
  283. package/.versions/1.0.0/skills/incremental-implementation/SKILL.md +287 -0
  284. package/.versions/1.0.0/skills/interview-me/SKILL.md +226 -0
  285. package/.versions/1.0.0/skills/orchestration-verification/SKILL.md +181 -0
  286. package/.versions/1.0.0/skills/peer-coms/SKILL.md +90 -0
  287. package/.versions/1.0.0/skills/performance-optimization/SKILL.md +350 -0
  288. package/.versions/1.0.0/skills/planning-and-task-breakdown/SKILL.md +254 -0
  289. package/.versions/1.0.0/skills/security-and-hardening/SKILL.md +461 -0
  290. package/.versions/1.0.0/skills/spec-driven-development/SKILL.md +257 -0
  291. package/.versions/1.0.0/skills/using-agent-skills/SKILL.md +199 -0
  292. package/.versions/1.0.0/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  293. package/.versions/1.0.0/vendor/agent-skills-upstream/LICENSE +21 -0
  294. package/.versions/1.0.0/vendor/agent-skills-upstream/README.md +11 -0
  295. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  296. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  297. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  298. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  299. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  300. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  301. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  302. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  303. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  304. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  305. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  306. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  307. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  308. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  309. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  310. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  311. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  312. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  313. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  314. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  315. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  316. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  317. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  318. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  319. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  320. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  321. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  322. package/.versions/1.0.0/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  323. package/CHANGELOG.md +142 -0
  324. package/README.md +117 -79
  325. package/agents/orchestrator.md +1 -1
  326. package/bin/cli.js +289 -359
  327. package/bin/force-patch-changesets.js +18 -2
  328. package/bin/lib/apply.js +86 -32
  329. package/bin/lib/desired.js +87 -0
  330. package/bin/lib/detect-agent.js +22 -38
  331. package/bin/lib/doctor.js +283 -33
  332. package/bin/lib/features.js +78 -0
  333. package/bin/lib/manifest.js +127 -48
  334. package/bin/lib/overrides.js +35 -0
  335. package/bin/lib/personas.js +37 -0
  336. package/bin/lib/plan.js +18 -9
  337. package/bin/lib/purge.js +11 -0
  338. package/bin/lib/reconcile.js +68 -0
  339. package/bin/lib/scan.js +24 -0
  340. package/bin/lib/state.js +25 -1
  341. package/bin/lib/stt-wizard.js +33 -0
  342. package/bin/lib/transaction.js +149 -0
  343. package/bin/lib/tui.js +71 -0
  344. package/bin/lib/verify.js +9 -26
  345. package/bin/snapshot-version.js +3 -6
  346. package/docs/ARCHITECTURE.md +55 -21
  347. package/docs/MIGRATION-agent-fleet.md +222 -0
  348. package/docs/agent-fleet-setup.md +124 -64
  349. package/docs/claude-code-coms-bridge.md +21 -2
  350. package/docs/coms-hermes-bridge.md +1 -1
  351. package/docs/getting-started.md +61 -217
  352. package/docs/npm-install.md +207 -429
  353. package/docs/pi-extensions.md +85 -41
  354. package/docs/pi-setup.md +48 -545
  355. package/hermes/README.md +1 -1
  356. package/install-manifest.json +385 -1255
  357. package/justfile +45 -27
  358. package/manifest-meta.json +544 -134
  359. package/node_modules/pi-ask-user/README.md +43 -5
  360. package/node_modules/pi-ask-user/index.ts +630 -75
  361. package/node_modules/pi-ask-user/package.json +1 -1
  362. package/package.json +5 -11
  363. package/scripts/coms-claude-bridge.ts +10 -0
  364. package/scripts/fleet.ts +107 -90
  365. package/scripts/lib/claude-bridge-core.ts +45 -0
  366. package/scripts/lib/fleet-command.ts +170 -15
  367. package/scripts/lib/monitor-env.ts +18 -6
  368. package/scripts/lib/peer-launch.ts +6 -2
  369. package/scripts/lib/team-project.ts +24 -4
  370. package/scripts/team-up.ts +57 -11
  371. package/skills/designing-agents/SKILL.md +1 -1
  372. package/skills/designing-agents/pi-harness-authoring.md +3 -3
  373. package/.claude/commands/build.md +0 -44
  374. package/.claude/commands/design-agent.md +0 -14
  375. package/.claude/commands/doctor-agent-fleet.md +0 -22
  376. package/.claude/commands/orchestrate.md +0 -112
  377. package/.claude/commands/prime.md +0 -22
  378. package/.claude/commands/review.md +0 -16
  379. package/.claude/commands/set-hermes-telegram.md +0 -15
  380. package/.claude/commands/set-hermes-watchdog.md +0 -6
  381. package/.claude/commands/setup-agent-fleet.md +0 -17
  382. package/.claude/commands/ship.md +0 -72
  383. package/.claude/commands/spec.md +0 -15
  384. package/.claude/commands/test.md +0 -19
  385. package/.claude/commands/webperf.md +0 -32
  386. package/.claude/orchestrate-teams.yaml +0 -24
  387. package/.opencode/commands/af-build.md +0 -17
  388. package/.opencode/commands/af-code-simplify.md +0 -16
  389. package/.opencode/commands/af-compound.md +0 -16
  390. package/.opencode/commands/af-design-agent.md +0 -15
  391. package/.opencode/commands/af-doctor-agent-fleet.md +0 -22
  392. package/.opencode/commands/af-orchestrate.md +0 -112
  393. package/.opencode/commands/af-plan.md +0 -16
  394. package/.opencode/commands/af-prime.md +0 -22
  395. package/.opencode/commands/af-review.md +0 -15
  396. package/.opencode/commands/af-set-hermes-watchdog.md +0 -6
  397. package/.opencode/commands/af-setup-agent-fleet.md +0 -17
  398. package/.opencode/commands/af-ship.md +0 -16
  399. package/.opencode/commands/af-spec.md +0 -16
  400. package/.opencode/commands/af-test.md +0 -21
  401. package/.opencode/commands/af-webperf.md +0 -32
  402. package/.opencode/orchestrate-teams.yaml +0 -24
  403. package/.pi/prompts/af-doctor-agent-fleet.md +0 -22
  404. package/.pi/prompts/af-setup-agent-fleet.md +0 -19
  405. package/.versions/0.0.1/.opencode/commands/af-doctor-agent-fleet.md +0 -15
  406. package/.versions/0.0.1/.opencode/commands/af-setup-agent-fleet.md +0 -15
  407. package/.versions/0.0.1/skills/guided-workspace-setup/SKILL.md +0 -506
  408. package/.versions/0.0.10/.opencode/commands/af-doctor-agent-fleet.md +0 -22
  409. package/.versions/0.0.10/.opencode/commands/af-setup-agent-fleet.md +0 -17
  410. package/.versions/0.0.10/.pi/prompts/af-doctor-agent-fleet.md +0 -22
  411. package/.versions/0.0.10/.pi/prompts/af-setup-agent-fleet.md +0 -19
  412. package/.versions/0.0.10/skills/guided-workspace-setup/SKILL.md +0 -226
  413. package/.versions/0.0.11/.claude/commands/build.md +0 -44
  414. package/.versions/0.0.11/.claude/commands/code-simplify.md +0 -22
  415. package/.versions/0.0.11/.claude/commands/design-agent.md +0 -14
  416. package/.versions/0.0.11/.claude/commands/doctor-agent-fleet.md +0 -22
  417. package/.versions/0.0.11/.claude/commands/orchestrate.md +0 -112
  418. package/.versions/0.0.11/.claude/commands/plan.md +0 -16
  419. package/.versions/0.0.11/.claude/commands/prime.md +0 -22
  420. package/.versions/0.0.11/.claude/commands/set-hermes-telegram.md +0 -15
  421. package/.versions/0.0.11/.claude/commands/set-hermes-watchdog.md +0 -6
  422. package/.versions/0.0.11/.claude/commands/setup-agent-fleet.md +0 -17
  423. package/.versions/0.0.11/.claude/commands/ship.md +0 -72
  424. package/.versions/0.0.11/.claude/commands/webperf.md +0 -32
  425. package/.versions/0.0.11/.claude/orchestrate-teams.yaml +0 -24
  426. package/.versions/0.0.11/.opencode/commands/af-build.md +0 -17
  427. package/.versions/0.0.11/.opencode/commands/af-code-simplify.md +0 -16
  428. package/.versions/0.0.11/.opencode/commands/af-compound.md +0 -16
  429. package/.versions/0.0.11/.opencode/commands/af-design-agent.md +0 -15
  430. package/.versions/0.0.11/.opencode/commands/af-doctor-agent-fleet.md +0 -22
  431. package/.versions/0.0.11/.opencode/commands/af-orchestrate.md +0 -112
  432. package/.versions/0.0.11/.opencode/commands/af-plan.md +0 -16
  433. package/.versions/0.0.11/.opencode/commands/af-prime.md +0 -22
  434. package/.versions/0.0.11/.opencode/commands/af-review.md +0 -15
  435. package/.versions/0.0.11/.opencode/commands/af-set-hermes-telegram.md +0 -15
  436. package/.versions/0.0.11/.opencode/commands/af-set-hermes-watchdog.md +0 -6
  437. package/.versions/0.0.11/.opencode/commands/af-setup-agent-fleet.md +0 -17
  438. package/.versions/0.0.11/.opencode/commands/af-ship.md +0 -16
  439. package/.versions/0.0.11/.opencode/commands/af-spec.md +0 -16
  440. package/.versions/0.0.11/.opencode/commands/af-test.md +0 -21
  441. package/.versions/0.0.11/.opencode/commands/af-webperf.md +0 -32
  442. package/.versions/0.0.11/.opencode/orchestrate-teams.yaml +0 -24
  443. package/.versions/0.0.11/.pi/prompts/af-doctor-agent-fleet.md +0 -22
  444. package/.versions/0.0.11/.pi/prompts/af-setup-agent-fleet.md +0 -19
  445. package/.versions/0.0.11/docs/opencode-setup.md +0 -281
  446. package/.versions/0.0.11/hooks/SIMPLIFY-IGNORE.md +0 -90
  447. package/.versions/0.0.11/hooks/hooks.json +0 -14
  448. package/.versions/0.0.11/hooks/session-start.sh +0 -74
  449. package/.versions/0.0.11/hooks/simplify-ignore.sh +0 -302
  450. package/.versions/0.0.11/skills/guided-workspace-setup/SKILL.md +0 -226
  451. package/.versions/0.0.4/.opencode/commands/af-doctor-agent-fleet.md +0 -17
  452. package/.versions/0.0.4/.opencode/commands/af-setup-agent-fleet.md +0 -15
  453. package/.versions/0.0.4/skills/guided-workspace-setup/SKILL.md +0 -535
  454. package/.versions/0.0.4/skills/guided-workspace-setup/companion-manifest.json +0 -33
  455. package/.versions/0.0.5/.opencode/commands/af-doctor-agent-fleet.md +0 -17
  456. package/.versions/0.0.5/.opencode/commands/af-setup-agent-fleet.md +0 -15
  457. package/.versions/0.0.5/skills/guided-workspace-setup/SKILL.md +0 -542
  458. package/.versions/0.0.5/skills/guided-workspace-setup/companion-manifest.json +0 -35
  459. package/.versions/0.0.6/.opencode/commands/af-doctor-agent-fleet.md +0 -17
  460. package/.versions/0.0.6/.opencode/commands/af-setup-agent-fleet.md +0 -15
  461. package/.versions/0.0.6/.pi/prompts/af-doctor-agent-fleet.md +0 -15
  462. package/.versions/0.0.6/.pi/prompts/af-setup-agent-fleet.md +0 -27
  463. package/.versions/0.0.6/skills/guided-workspace-setup/SKILL.md +0 -544
  464. package/.versions/0.0.6/skills/guided-workspace-setup/companion-manifest.json +0 -35
  465. package/.versions/0.0.7/.opencode/commands/af-doctor-agent-fleet.md +0 -17
  466. package/.versions/0.0.7/.opencode/commands/af-setup-agent-fleet.md +0 -15
  467. package/.versions/0.0.7/.pi/prompts/af-doctor-agent-fleet.md +0 -15
  468. package/.versions/0.0.7/.pi/prompts/af-setup-agent-fleet.md +0 -27
  469. package/.versions/0.0.7/skills/guided-workspace-setup/SKILL.md +0 -544
  470. package/.versions/0.0.7/skills/guided-workspace-setup/companion-manifest.json +0 -35
  471. package/.versions/0.0.8/.opencode/commands/af-doctor-agent-fleet.md +0 -17
  472. package/.versions/0.0.8/.opencode/commands/af-setup-agent-fleet.md +0 -15
  473. package/.versions/0.0.8/.pi/prompts/af-doctor-agent-fleet.md +0 -15
  474. package/.versions/0.0.8/.pi/prompts/af-setup-agent-fleet.md +0 -27
  475. package/.versions/0.0.8/skills/guided-workspace-setup/SKILL.md +0 -544
  476. package/.versions/0.0.8/skills/guided-workspace-setup/companion-manifest.json +0 -36
  477. package/.versions/0.0.9/.opencode/commands/af-doctor-agent-fleet.md +0 -17
  478. package/.versions/0.0.9/.opencode/commands/af-setup-agent-fleet.md +0 -15
  479. package/.versions/0.0.9/.pi/prompts/af-doctor-agent-fleet.md +0 -15
  480. package/.versions/0.0.9/.pi/prompts/af-setup-agent-fleet.md +0 -27
  481. package/.versions/0.0.9/skills/guided-workspace-setup/SKILL.md +0 -544
  482. package/bin/lib/bootstrap.js +0 -323
  483. package/bin/lib/transform-persona.js +0 -180
  484. package/docs/opencode-setup.md +0 -281
  485. package/hooks/SIMPLIFY-IGNORE.md +0 -90
  486. package/hooks/hooks.json +0 -14
  487. package/hooks/session-start.sh +0 -74
  488. package/hooks/simplify-ignore.sh +0 -302
  489. package/skills/guided-workspace-setup/SKILL.md +0 -226
  490. /package/.versions/0.0.10/{skills/guided-workspace-setup/companion-manifest.json → bin/catalog/harness-runtime-closure.json} +0 -0
  491. /package/.versions/0.0.11/{skills/guided-workspace-setup/companion-manifest.json → bin/catalog/harness-runtime-closure.json} +0 -0
  492. /package/{.opencode/commands → .versions/1.0.0/.pi/prompts}/af-set-hermes-telegram.md +0 -0
  493. /package/.versions/{0.0.9/skills/guided-workspace-setup/companion-manifest.json → 1.0.0/bin/catalog/harness-runtime-closure.json} +0 -0
  494. /package/{skills/guided-workspace-setup/companion-manifest.json → bin/catalog/harness-runtime-closure.json} +0 -0
@@ -0,0 +1,337 @@
1
+ # Agent Fleet Architecture
2
+
3
+ Agent Fleet is a Pi-centered multi-agent orchestration system. This page maps
4
+ the runtime responsibilities and where each module lives in the repository.
5
+
6
+ ## Runtime layers
7
+
8
+ | Layer | Role | Implementation |
9
+ | --- | --- | --- |
10
+ | **Pi Coding Agent** | Primary local runtime — runs the dispatcher and specialist subagents | `.pi/harnesses/`, `.pi/extensions/`, `.pi/agents/`, `.pi/prompts/` |
11
+ | **agent-hub** | Thin-context multi-agent harness: dispatcher + specialists + research helpers + Verification Contract | `.pi/harnesses/agent-hub/` |
12
+ | **Herdr** | Fleet/workspace control plane — spawns peer teams as tiled workspaces, presence via push events, snapshot/resume | [herdr.dev](https://herdr.dev); client in `.pi/harnesses/lib/herdr-client.ts`, layout in `scripts/lib/herdr-layout.ts` |
13
+ | **coms** | Peer communication protocol/data plane — envelope-based P2P messaging between agents | `.pi/harnesses/coms/`, `scripts/lib/coms-envelope.ts`, `scripts/coms-cli.ts` |
14
+ | **Claude Code bridge** | Makes an interactive Claude Code pane a bidirectional coms peer | `scripts/coms-claude-bridge.ts`, `hooks/coms-stop-hook.mjs`, `skills/peer-coms/` — see [claude-code-coms-bridge.md](claude-code-coms-bridge.md) |
15
+ | **Hermes bridge** | Remote human control — relays hub questions to Telegram, races phone vs. local answers, conductor/liaison skills | `scripts/coms-hermes-bridge.ts`, `.pi/harnesses/ask-user-remote/`, `hermes/skills/` — see [coms-hermes-bridge.md](coms-hermes-bridge.md) |
16
+ | **Hermes local monitor transport** | Local, authenticated monitor contract for Hub-owned task generations; consumers supply their own presentation | `.pi/harnesses/agent-hub/monitor-*.ts`, `.pi/harnesses/lib/hermes-monitor-{model,store,registry,socket}.ts` (with compatibility re-exports under `scripts/lib/`) — see [Hermes artifacts](../hermes/README.md#local-agent-hub-monitor-integration) and [watchdog limits](hermes-watchdog-supervisor.md) |
17
+ | **Hermes Desktop plugin** (`agent-fleet-herdr`) | Fleet observability surface — read-only panel of every live session joined from the coms registry, herdr presence, agent transcripts, and the monitor transport; `focus` and subagent `cancel` are its only write doors | `hermes/desktop-plugins/agent-fleet-herdr/` (Electron pane), `hermes/plugins/agent-fleet-herdr/dashboard/` (FastAPI backend), installed by `scripts/install-hermes-plugin.sh` — see [hermes-desktop-plugins.md](hermes-desktop-plugins.md) |
18
+ | **Codex remote-control conductor** | Experimental outbound-only, user-systemd-managed Android conductor; verified on Codex CLI 0.144.x | `scripts/codex-remote-control.ts`, `scripts/codex-conductor.ts`, `codex/CONDUCTOR.md`, `systemd/user/`; runtime under `~/.local/state/agent-fleet/codex-conductor/` — see [codex-remote-conductor.md](codex-remote-conductor.md) |
19
+ | **Skill library** | Lifecycle workflows and quality gates every agent follows | `skills/` (native) + `vendor/agent-skills-upstream/skills/` (vendored) — see [UPSTREAM-SKILLS.md](UPSTREAM-SKILLS.md) |
20
+ | **Personas** | Reusable specialist definitions, installed verbatim | `agents/`, `bin/lib/personas.js` |
21
+
22
+ ## One Hub runtime, independent axes
23
+
24
+ Every public Pi launch through `just fleet` loads Fleet Core and the `agent-hub`
25
+ harness. Four independent choices shape that runtime:
26
+
27
+ | Axis | Choices | What it controls |
28
+ | --- | --- | --- |
29
+ | **Posture** | `operator`, `orchestrator` | Whether the main agent may use direct coding tools. Operator retains the captured `read`/`bash`/`edit`/`write` and approved extension surface; orchestrator removes direct coding tools and keeps dispatch, research, assertions, `ask_user`, and available coms/Herdr tools. |
30
+ | **Hub mode** | `fast`, `standard`, `strict` | Dispatch/research budgets and Verification Contract rigor. `/af-hub-mode` never grants or revokes coding tools. |
31
+ | **Native roster** | empty or one entry from `.pi/agents/teams.yaml` | Which in-process Pi specialist personas `dispatch_agent` may start. Roster changes do not change posture in a live session. |
32
+ | **Peer topology** | current terminal, Hub-only Herdr workspace, or Hub plus a `.pi/agents/peers.yaml` preset | Which separate, addressable Pi/Claude processes occupy sibling panes. Starting or spawning peers does not change posture or the native roster. |
33
+
34
+ Bare `just fleet` therefore means operator posture, an empty native roster, and
35
+ the current terminal. At startup an explicit `--posture` wins; otherwise
36
+ `--agents <roster>` implies orchestrator; otherwise operator is used. An
37
+ orchestrator startup requires a roster. `/af-posture` switches only posture in
38
+ the live session, while `/af-agents-*` changes only the native roster.
39
+
40
+ All Hub-owned slash commands remain registered in both postures. Runtime gates
41
+ control whether an action can proceed: without coms, Herdr, a visible target,
42
+ or an active roster, the corresponding command refuses with an actionable
43
+ message rather than disappearing. `--browser` and `--all-extensions` expand the
44
+ captured operator surface only when those optional extensions are installed.
45
+
46
+ The project selected by `--project <name>` is the coms namespace for the Hub
47
+ and every standing or dynamically spawned peer. The Hub-facing peer spawn API
48
+ cannot override it. Native subagents remain children of that Hub and inherit
49
+ its repository context; peers are separate processes in their own panes.
50
+
51
+ At dispatch time, `backend: "auto"` applies
52
+ `.pi/agents/dispatch-policy.yaml`; `backend: "native"` bypasses same-name peer
53
+ substitution; and `backend: "coms"` requires a visible same-name peer and never
54
+ falls back to a native child. `.pi/agents/peers.yaml` owns how a peer runs
55
+ (`runner`, persona, model, extensions, and declared `env_file`), not whether a
56
+ dispatch uses it.
57
+
58
+ ## Fleet hierarchy
59
+
60
+ Agent Fleet is layered on purpose. Work flows **down** (delegate); evidence and status flow **up** — as compact structured returns, never raw dumps.
61
+
62
+ ```mermaid
63
+ flowchart TD
64
+ You(["You · Hermes inbound relay · Codex outbound conductor on your phone"])
65
+
66
+ subgraph HUBL["HUB — guarded runtime (bare just fleet)"]
67
+ Hub["agent-hub harness<br/>operator or orchestrator posture · routes tasks<br/>owns the Verification Contract on disk · keeps research dumps out of its own context"]
68
+ end
69
+
70
+ subgraph TEAML["OPTIONAL NATIVE ROSTER (.pi/agents/teams.yaml)"]
71
+ Team["default: builder · test-engineer · code-reviewer · documenter<br/>also: plan · debug · frontend · security · hotfix · release · info"]
72
+ end
73
+
74
+ subgraph RESL["RESEARCH HELPERS — read-only, always available"]
75
+ Research["researcher (fast tier — simple reads)<br/>deep-researcher (deep tier — hard, cross-cutting questions)"]
76
+ end
77
+
78
+ subgraph SUBL["SUB-AGENTS — focused children, narrow tools + models"]
79
+ Subs["planner → scout · rules · risk<br/>plan-reviewer → feasibility · deps<br/>builder → recon · verifier<br/>test-engineer → coverage-scout · conventions<br/>code-reviewer → preflight · quality · perf · docs<br/>security-auditor → recon · input-sweep · secrets-sweep"]
80
+ end
81
+
82
+ You -->|task| Hub
83
+ Hub -->|"dispatch_agent — one persona = one specialist session"| Team
84
+ Hub -->|"spawn_research"| Research
85
+ Research -.->|"findings written to disk — hub gets paths, not dumps"| Hub
86
+ Team -->|"subagents: block (delegate_depth ≥ 1)"| Subs
87
+ Subs -.->|"results return to the parent agent only"| Team
88
+ Team -.->|"structured return + evidence"| Hub
89
+ Hub -.->|"one status line: Assertions: 2✓ 1○ 1✗"| You
90
+ ```
91
+
92
+ Every specialist session is one persona from [`agents/`](../agents/) — *skills* tell each agent **how** to work; *personas* define **who** they are (see [agents.md](agents.md)).
93
+
94
+ The same idea as a tree:
95
+
96
+ ```text
97
+ hub (operator by default; orchestrator when selected)
98
+ ├── optional native roster (empty by default; example: default)
99
+ │ ├── builder → recon · verifier
100
+ │ ├── test-engineer → coverage-scout · conventions
101
+ │ ├── code-reviewer → preflight · quality · perf · docs
102
+ │ └── documenter
103
+ ├── research helpers (spawn_research, any time)
104
+ │ ├── researcher
105
+ │ └── deep-researcher
106
+ └── optional fleet peers (herdr + coms)
107
+ ├── architect / releaser / web-debugger panes
108
+ ├── Claude Code peer (coms bridge)
109
+ ├── Hermes (phone human · inbound ask_user)
110
+ └── Codex Remote Control (Android · outbound coms delegation)
111
+ ```
112
+
113
+ Composition rule: **the hub (or a slash command) orchestrates; personas do not invoke other personas as peers.** Specialists may only fan out to their configured **sub-agents**. Research helpers write findings to disk; the hub resumes specialists with paths, not raw dumps.
114
+
115
+ ### Research search supervision
116
+
117
+ The shared `spawnPiAgent` seam supervises every `read`/`grep`/`find`/`ls` call from native
118
+ research helpers and nested delegate children. The supervisor tracks JSONL `toolCallId` values
119
+ independently, with a default 120-second deadline (`recon-search-timeout-s: 1..3600|off` under
120
+ `## agent-hub`). It is a per-tool watchdog; the whole-run bound is separate — the execution
121
+ mode's per-run deadline (`agent-turn-timeout-s`), which terminates a hung run as `turn_timeout`.
122
+ On timeout or caller cancellation it owns and terminates the child's process group (SIGTERM,
123
+ then SIGKILL after a bounded grace), has a separate settlement timer for missing `close`/pipe
124
+ drain, and reports timeout separately from cancellation. Research helpers and nested delegates
125
+ are each given safe process-group ownership; delegates forward parent termination so no detached
126
+ child is orphaned. Full pattern catalog: [references/orchestration-patterns.md](../references/orchestration-patterns.md).
127
+
128
+ ### Execution modes & turn budgets
129
+
130
+ The hub enforces per-user-turn budgets in code (`run-budget.js`): `fast`/`standard`/`strict`
131
+ modes cap `dispatch_agent` calls, `spawn_research` calls, and wall clock per turn, set the
132
+ per-run deadline above, and control nested delegation. Exhausted budgets make the dispatch
133
+ tools refuse with "summarize and ask the user"; a new user message opens a fresh window.
134
+ Specialist context pressure is measured over input + cacheRead + cacheWrite against **that
135
+ agent's own** model window, resolved from pi's model registry with the source recorded
136
+ (`context-window.js`) — measuring a 49k local model against the dispatcher's window is what
137
+ made readings like "315%" unactionable; anything over 100% now emits a one-time diagnostic
138
+ naming the window and where it came from. Specialist sessions are recycled (fresh spawn
139
+ instead of `-c` resume) after `session-recycle-runs` runs, at ≥60% measured context, and
140
+ unconditionally at a full window; a resumed session whose *projected* prompt would overflow
141
+ is recycled before the spawn rather than after the run. Requests to one provider are capped
142
+ per process (`provider-semaphore.js`: 2 in flight for `custom/*` by default, unlimited
143
+ elsewhere, `AGENT_HUB_PROVIDER_LIMITS` to override) — the cap is per level of the delegation
144
+ tree, and a nested spawn reuses its parent's permit so it can never wait on its own ancestor.
145
+ Configured under `## agent-hub` (`mode`, `max-dispatches-per-turn`,
146
+ `max-research-per-turn`, `turn-wall-time-s`, `agent-turn-timeout-s`, `session-recycle-runs`,
147
+ `run-history-keep`); switched live with `/af-hub-mode`.
148
+
149
+ A per-message allowance cannot bound a task, so a second envelope sits above the turn one:
150
+ the **task budget** (`run-budget.js`, `3×` the turn envelope) counts dispatches, research
151
+ runs and **active** time across the WHOLE task and is *not* reset by a user message. Active
152
+ time is turns that ran minus `ask_user` waits — a task clock that billed human idle would
153
+ false-stop a normal steered session, and a false stop teaches people to reset the window
154
+ reflexively. The auto-research pipe is exempt from the turn budget but charged against the
155
+ task envelope, so it cannot smuggle 8 helpers per dispatch past the outer bound. Exhausting
156
+ the task budget is a hard stop — only `/af-new-task` (or `set_task_tier` with
157
+ `new_task: true`) opens a new window. This is the guardrail the post-mortem run never hit: every steering message
158
+ reopened the turn window, so one workspace stayed open 47 hours on a change that took 13
159
+ minutes in a narrow one.
160
+
161
+ On top of the mode sit several qualitative guardrails. **Task triage**: the dispatcher
162
+ classifies the current TASK via the `set_task_tier` tool (`trivial`/`small`/`feature`/`project`)
163
+ and the caps drop to min(mode, tier). The tier is task-scoped and **ratcheted** — it survives
164
+ the user's next message, lowering is free, raising needs a stated `reason` — because a
165
+ turn-scoped tier reset to `feature` on every correction. Three refusals enforce
166
+ proportionality in code rather than prose: a duplicate-dispatch guard (near-identical
167
+ re-dispatches within a turn), a **tier persona gate** (`planner`, `plan-reviewer`,
168
+ `architect`, `security-auditor`, `deep-researcher` are refused at trivial/small — each opens
169
+ a document/finding loop), and a **review round cap** (review dispatches per task, by tier).
170
+ Skipping triage assumes `small`, not `feature`: the tier latches for the task, and the case
171
+ where it was never declared is exactly the case where proportionality was not being
172
+ considered. The review **finding** budget is the one thing deliberately left advisory — the
173
+ hub counts blocking findings (`review-findings.js`) and reports an over-budget return, but
174
+ never reclassifies one, because no rule it can evaluate separates an invented manifest from
175
+ a leaked credential; the round cap is what carries the enforcement.
176
+ **Docs lane** (`docs-lane.js`): a dispatch whose whole declared `scope` is documentation
177
+ refuses review personas (overridable with `review_reason`) and tells the dispatcher not to
178
+ open a review gate; an absent scope is never the lighter lane. **External-blocker stop**
179
+ (`external-blocker.js`): a specialist emits `EXTERNAL_BLOCKED: …` when it needs something
180
+ outside the fleet's reach (account, permission, credential, telemetry destination), and the
181
+ hub refuses the next dispatch with an owner-escalation packet until the human is addressed —
182
+ the alternative, observed, is hours spent approximating the missing fact with scripts,
183
+ manifests and fixtures while the assertion still ends UNPROVEN. **Drift watchdog**
184
+ (`drift-watchdog.js`): armed dispatches are
185
+ observed in-flight from the JSON event stream — deterministic rules (out-of-scope writes
186
+ against the declared `scope` globs, tool-call loops, consecutive failures, tool-call cap)
187
+ escalate to a one-shot cheap LLM judge whose DRIFTING/STUCK verdict terminates the run as
188
+ `drift_stop` (exit 125, partial output preserved); enabled per hub/agent/dispatch
189
+ (`watchdog` key, `/af-watchdog`, `watchdog` param). Two rules about scope: the session's
190
+ own `artifacts/`, `findings/`, and `delegations/` subtrees are implicitly in scope (the
191
+ deliverable protocol *orders* specialists to write there, and the judge is told so), and the
192
+ `scope` rule is non-terminal — it reports a drift advisory on the result and never stops a
193
+ run by itself, matching the post-run scope gate, which reverts nothing. **Dynamic teams**: `/af-agents-add`,
194
+ `/af-agents-drop`, `/af-agents-save` restructure the roster live (the system prompt rebuilds
195
+ every turn), and the gated `team_adjust` tool lets the dispatcher itself adjust the roster
196
+ outside fast mode, with user notification. `/af-hub-report` accounts each turn's dispatches,
197
+ tokens (billed = input + cacheRead + cacheWrite), recycles, drift stops, and refusals.
198
+
199
+ ## Runtime stack (tools the fleet sits on)
200
+
201
+ ```mermaid
202
+ flowchart TD
203
+ AF["<b>Agent Fleet</b><br/>agent-hub · personas · skills · coms · bridges · CLI"]
204
+ AF -->|primary runtime| PI["<b>pi</b><br/>coding agent — loads harnesses,<br/>extensions, prompts, personas"]
205
+ AF -->|control plane| HERDR["<b>herdr</b><br/>tiled peer workspaces,<br/>presence, snapshot/resume"]
206
+ AF -->|coms peer only| CC["<b>Claude Code</b><br/>bidirectional peer via<br/>the coms bridge<br/><i>not an install target</i>"]
207
+ AF -->|remote human| HERMES["<b>Hermes</b><br/>hub questions relayed to your phone,<br/>plus the Desktop fleet panel"]
208
+ AF -->|outbound remote delegation| CODEX["<b>Codex Remote Control</b><br/>Android-approved calls to<br/>listed coms peers (experimental)"]
209
+ ```
210
+
211
+ ### External dependencies
212
+
213
+ These are the external systems Agent Fleet assumes or integrates with — not npm packages, but the **runtime stack** the fleet operates on top of.
214
+
215
+ | Dependency | Role | Required? |
216
+ | --- | --- | --- |
217
+ | **[pi](https://github.com/badlogic/pi-mono)** (or your pi install) | Primary coding-agent runtime; loads harnesses, extensions, prompts, and personas | Yes for `just fleet` |
218
+ | **[herdr](https://herdr.dev)** | Workspace control plane: Hub/peer panes, presence push events, team snapshot/resume | Required for `--herdr` or `--peers`; optional for bare `just fleet` |
219
+ | **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** | First-class coms peer via the [coms bridge](claude-code-coms-bridge.md) — cross-model review and analysis. Never an install target: it hosts no skills, commands, or personas | Optional peer |
220
+ | **Hermes** | Remote human-in-the-loop (Telegram relay for hub questions — [coms-hermes-bridge](coms-hermes-bridge.md)) and the Desktop fleet panel ([hermes-desktop-plugins](hermes-desktop-plugins.md), needs v0.19.0+ and the Desktop app) | Optional |
221
+ | **Codex CLI + ChatGPT Android** | Experimental outbound remote-control conductor on supported `0.144.x`; requires Node `22.6+`, user systemd, interactive pairing, and per-command mobile approvals — [runbook](codex-remote-conductor.md) | Optional / revalidate after minor-version or mobile-client changes |
222
+ | **[addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)** | Upstream skill library (manually vendored) | Bundled (vendored) |
223
+ | **[disler/pi-vs-claude-code](https://github.com/disler/pi-vs-claude-code)** | Source inspiration / MIT port origin for pi harnesses | Design lineage (ported in-repo) |
224
+ | **LLM providers** | Models per persona (`model:` / `models:` in agent frontmatter) — e.g. OpenAI Codex, GitHub Copilot, Ollama, … | Yes (at least one provider your agents can call) |
225
+ | **Chrome DevTools MCP** / **Playwright Agent CLI** | Browser verify (`browser-testing-with-devtools`) and headless automation (`bowser`) | Optional, feature-specific |
226
+ | **Node.js + npm** | CLI (`npx @chankov/agent-fleet`), package install, `just` recipes | Yes for install & tooling |
227
+
228
+ ## Repository module map
229
+
230
+ ```text
231
+ .pi/ # Pi runtime: harnesses, extensions, agents config, prompts
232
+ skills/ # Agent Fleet-native skills (shadow vendored names)
233
+ agents/ # Personas/subagents used by Agent Fleet
234
+ scripts/ # CLI helpers, bridges, team + one-off peer launchers (pure logic in scripts/lib/)
235
+ hermes/ # Hermes-facing skills/integration assets
236
+ codex/ # Canonical Codex conductor contract (runtime copy lives outside checkout)
237
+ systemd/user/ # Owned user-unit template for Codex remote control
238
+ vendor/agent-skills-upstream/ # Manually imported upstream skills (pinned SHA)
239
+ bin/ # npm CLI: init/update/doctor + the installer engine
240
+ hooks/ # The coms bridge Stop hook
241
+ references/ # Supplementary checklists, installed with the skills that cite them
242
+ docs/ # This file, setup guides, bridge references, vendoring policy
243
+ ```
244
+
245
+ Reserved for future modules (do not repurpose these paths):
246
+
247
+ ```text
248
+ apps/dashboard/ # future dashboard: Kanban state, Herdr workspaces, peer status
249
+ packages/fleet-core/ # future extracted core orchestration library
250
+ packages/herdr-bridge/ # future Herdr integration package
251
+ packages/hermes-bridge/ # future Hermes integration package
252
+ ```
253
+
254
+ ## Design rules
255
+
256
+ - **Thin dispatcher context.** Nothing lands persistently in the dispatcher's
257
+ context if it can live on disk or in a one-line status. Research findings,
258
+ the Verification Contract ledger, and team snapshots are all disk-first.
259
+ - **A harness fault must never look like a specialist fault.** The hub passes
260
+ `--session <file>` on every run, so one corrupt session file used to fail a
261
+ persona in ~1s with no output — indistinguishable from a bad agent, and
262
+ unrecoverable by drop + re-add. Unusable session files are now validated and
263
+ quarantined (`session-health.js`) with the reset named in the result. Same rule
264
+ for the return contract: a report the parser cannot read gets one cheap
265
+ read-only extraction pass (`return-extract.js`) before its assertions are
266
+ written off as unproven, and extracted evidence is always labelled as weaker
267
+ than declared evidence. The converse also holds: a run that errored or timed
268
+ out writes to `artifacts/failures/`, never `returns/` — an error stub filed
269
+ as a return reads as a specialist verdict and gets acted on as one.
270
+ - **A pool status field beats reading the screen.** `coms_list` publishes each
271
+ peer's `pane_id` and `status` (`idle`/`working`/`booting`), and
272
+ `herdr_spawn_peer` waits for the peer to register and returns `peer_ready`
273
+ rather than a bare pane id. A spawned peer boots idle and does nothing until
274
+ addressed, so peers spawned and never sent to are named at turn end and in
275
+ `/af-hub-report` (`spawned-peers.js`); closing stays the human's call.
276
+ - **A declared requirement carries its origin.** Every assertion in the ledger
277
+ names its source (`assertion-ledger.js`), and the open ledger is soft-capped
278
+ at 8 — an id nobody can trace back to a plan line costs a dispatch and an
279
+ ASK_USER cycle to re-derive.
280
+ - **Pre-flight validation is free.** Anything the hub can reject before spawning
281
+ — an unresolvable artifact path, an unknown research persona, a heavy persona
282
+ at a low tier, a reviewer on a docs-only scope — is refused without spending a
283
+ budget slot. Artifact paths also resolve across artifact kinds when the name is
284
+ unique, since the hub writes every auto-return under `returns/` while
285
+ dispatchers reasonably guess `reviews/`.
286
+ - **Evidence is archived, never overwritten.** Session start moves the previous
287
+ session's `artifacts/` into an immutable `.pi/agent-sessions/runs/<runId>/`
288
+ namespace with a read-only `meta.json` and an appended `runs/index.json`
289
+ (`run-namespace.js`), retained per `run-history-keep` (default 10). The old
290
+ behaviour — delete `artifacts/` at start, name returns by a per-session counter
291
+ — collided two ways at once and made a post-mortem record eleven specialist
292
+ returns and two reviews as NOT RECOVERABLE. A failed archive leaves the
293
+ artifacts in place: a stale tree is recoverable, a deleted one is not.
294
+ - **Herdr owns panes, presence, and lifecycle; coms owns messages.** Herdr
295
+ topology recipes (`--herdr` or `--peers`) require a running server and refuse
296
+ with an actionable message otherwise. Bare Fleet does not require Herdr.
297
+ `--no-coms` leaves direct/native execution available but disables peer
298
+ messaging, peer-backed dispatch, and handoff from the Hub.
299
+ - **External agents are peers, not plugins.** Claude Code (and future CLI
300
+ agents) join the fleet through bridge adaptors that speak coms envelopes —
301
+ the fleet core stays agent-agnostic. Hermes remains the inbound `ask_user`/
302
+ Telegram route; the experimental Codex conductor is outbound-initiated only,
303
+ approval-gated, and restricted to listed peers through the validated wrapper.
304
+ - **Hermes monitor presentation is outside the fleet core.** Agent Fleet exposes owner-only
305
+ local monitor operations for Hub-owned state; a consumer owns its UI and lifecycle. The
306
+ worktree contains additive monitor/event/invoke code, but that implementation and its local
307
+ tests are not proof of a durable external identity or live delivery contract. `invoke`, where
308
+ available, is Hub-owned and queues dispatcher work rather than exposing tools directly.
309
+ - **Packaged Hermes source is opt-in, never auto-installed.** The npm tarball carries the
310
+ `hub-watchdog` skill (`hermes/skills/`) plus the backend and Desktop monitor plugin source
311
+ (`hermes/plugins/`, `hermes/desktop-plugins/`) as runtime-only source. Shipping that source
312
+ makes it available to an operator; installing it into a Hermes profile is always an explicit
313
+ action through `agent-fleet set-hermes-watchdog` (skill) or the consumer's own flow (plugins).
314
+ Nothing is enabled, launched, or configured by installing the package.
315
+ - **Watchdog delivery is capability-gated and currently unproven.** No checked-in
316
+ Gate O live artifact proves Hermes origin identity, updates, reconnect, or two-chat isolation,
317
+ so its supported posture is journal-only/dormant: no delivery, steering, or surgical use. It
318
+ never manages services, gateways, Herdr, or shell commands. Local runtime evidence — including
319
+ a real foreground watcher against a disposable Hub UDS — is `synthetic-local` and proves none of
320
+ those capabilities; see [the watchdog runbook](hermes-watchdog-supervisor.md).
321
+ - **External conductor contracts are advisory.** Pi damage-control wraps Pi
322
+ tool calls, not Hermes or Codex processes; human approvals and their
323
+ contracts reduce risk but do not provide an OS command allowlist.
324
+ - **Destructive fleet verbs are damage-control-guarded.** Specialists cannot
325
+ spawn/close herdr panes; the human confirms destructive actions.
326
+ - **Native-over-vendored skills.** The skill catalogue resolves `skills/`
327
+ first, then the vendored upstream import; upstream updates are explicit
328
+ maintainer actions ([UPSTREAM-SKILLS.md](UPSTREAM-SKILLS.md)).
329
+
330
+ ## History
331
+
332
+ Agent Fleet began as a fork of `addyosmani/agent-skills` and was split into a
333
+ standalone repository in July 2026, with upstream demoted to vendored content.
334
+ The one-time migration record, including the history-filtering commands, lives
335
+ in [MIGRATION-agent-fleet.md](MIGRATION-agent-fleet.md); the product
336
+ requirements that drove the split are in
337
+ [prd-agent-fleet-split.md](prd-agent-fleet-split.md).