@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
@@ -1,514 +1,292 @@
1
- # npm install path
1
+ # Install and lifecycle
2
2
 
3
- The `@chankov/agent-fleet` package ships every skill, persona, slash command,
4
- and pi extension as installable content, plus the CLI that installs them. The
5
- CLI is the whole installer: it decides paths, computes per-item state, performs
6
- the three-way merge, and does every write, so a complete install needs no coding
7
- agent and no model. The `guided-workspace-setup` skill is a conversational
8
- front-end over it — it asks which artifacts a project wants and drafts the
9
- overrides file; the CLI does the rest.
3
+ `@chankov/agent-fleet` is a deterministic pi workspace installer. It needs no
4
+ coding agent or model: `setup`, `doctor`, and `uninstall` are the public
5
+ lifecycle commands.
10
6
 
11
- ## Package name vs CLI name
7
+ - [First install](#first-install) — a repository that has never had Agent Fleet
8
+ - [Updating an existing install](#updating-an-existing-install) — a new version shipped
9
+ - [What reconcile does to each file](#what-reconcile-does-to-each-file) — **read this before your first update**
10
+ - [Doctor and uninstall](#doctor-and-uninstall)
12
11
 
13
- | | Name |
14
- |---|---|
15
- | **npm package** (use this for `npm install` and the first `npx`) | `@chankov/agent-fleet` |
16
- | **CLI binary** (the command the package ships) | `agent-fleet` |
17
-
18
- The package is published under the `@chankov` npm scope to guarantee identity —
19
- only [Nikolay Chankov](https://www.npmjs.com/~chankov) can publish to that
20
- scope. The CLI binary stays the short name `agent-fleet` because that's what
21
- goes on `PATH` after install.
22
-
23
- So:
24
-
25
- - First time / one-shot: `npx @chankov/agent-fleet <cmd>` — npx resolves the
26
- scoped package and runs its bin.
27
- - After a project / global install: `npx agent-fleet <cmd>` works too,
28
- because the bin is named `agent-fleet`.
12
+ ## First install
29
13
 
30
- ## Quick start
31
-
32
- ### Guided workspace setup
14
+ Run the package command from the target repository. There is no `just fleet`
15
+ recipe yet — the managed justfile region is one of the things setup *writes* —
16
+ so the first install always goes through `npx`:
33
17
 
34
18
  ```bash
35
- # In the workspace you want to configure:
36
- npx @chankov/agent-fleet init
37
- # Then open your coding agent in this directory and run the command it prints:
38
- # Claude Code: /setup-agent-fleet
39
- # Pi/OpenCode: /af-setup-agent-fleet
19
+ cd ~/projects/my-app
20
+ npx @chankov/agent-fleet@latest setup
40
21
  ```
41
22
 
42
- That's it. `npx` fetches the package, the CLI detects your coding agent and
43
- prints the runtime-appropriate command, which runs the full guided install
44
- inside your agent.
45
-
46
- ### First-class pi package
47
-
48
- For pi users who want package-native loading instead of copied setup artifacts:
23
+ In a real TTY this opens the installer: pick **Default** or **Full**, add
24
+ optional comma-separated features, read the exact reconciliation plan, and
25
+ confirm once to apply. For automation, name the selection and consent up front:
49
26
 
50
27
  ```bash
51
- # Project-scoped; writes .pi/settings.json
52
- pi install -l npm:@chankov/agent-fleet
53
-
54
- # Or global for every pi session
55
- pi install npm:@chankov/agent-fleet
28
+ npx @chankov/agent-fleet@latest setup --preset default --features none --yes
56
29
  ```
57
30
 
58
- The pi package manifest exposes this repo's skills, pi runtime skills, lifecycle prompts, and bundled `pi-ask-user` resources. The bundled companion provides the `ask_user` tool and `ask-user` skill without a separate `pi-ask-user` install.
59
-
60
- It intentionally does not auto-expose this repo's own `.pi/extensions` or harness directories; install those through guided setup or the pi setup docs so their runtime dependencies are handled explicitly. `pi-codex-image-gen` is also not bundled or required; guided setup may offer it as an optional suggested external npm/pi package when package installation is available, and installs it only if selected (`pi install -l npm:pi-codex-image-gen`). Minimal setup works without it.
61
-
62
- The package also ships assets for the **experimental Linux Codex Remote-Control conductor** (`codex/`, `systemd/`, lifecycle/wrapper scripts, recipes, and runbook). Guided setup copies those assets with selected pi harnesses but never enables systemd, edits Codex config, starts a service, or pairs a phone. Those remain explicit operator actions and support only Codex CLI `0.144.x`; see [codex-remote-conductor.md](codex-remote-conductor.md). Its managed runtime contract is created later under `$HOME/.local/state/agent-fleet/codex-conductor/`, not inside the npm package or target checkout.
63
-
64
- ## Commands
31
+ Pin the exact version when the run has to be reproducible:
65
32
 
66
- ### `npx @chankov/agent-fleet init`
67
-
68
- Materializes the package, **bootstraps the installer artifacts** into the
69
- workspace, and hands off to the runtime's Agent Fleet setup command. Claude Code
70
- uses unprefixed installer commands; Pi and OpenCode use `/af-setup-agent-fleet`
71
- and `/af-doctor-agent-fleet`.
72
-
73
- What `init` writes per agent:
74
-
75
- | Agent | Files written to the workspace |
76
- |---|---|
77
- | `claude-code` | `.claude/commands/setup-agent-fleet.md`, `.claude/commands/doctor-agent-fleet.md`, `.claude/skills/guided-workspace-setup/SKILL.md` |
78
- | `pi` | `.pi/prompts/af-setup-agent-fleet.md`, `.pi/prompts/af-doctor-agent-fleet.md`, `.pi/skills/guided-workspace-setup/SKILL.md` |
79
- | `opencode` | `.opencode/commands/af-setup-agent-fleet.md`, `.opencode/commands/af-doctor-agent-fleet.md`, `.opencode/skills/guided-workspace-setup/SKILL.md` |
80
-
81
- These are **just the plumbing** — the slash commands, plus the skill they
82
- invoke. The actual catalogue (spec-driven-development, code-reviewer,
83
- test-engineer, pi extensions, …) is picked by you inside the setup workflow. Re-run
84
- `init` to refresh the plumbing after a package upgrade; bootstrap files
85
- are always overwritten because they're scaffolding, not user data.
86
-
87
- After the setup workflow finishes its install pass, **the bootstrap files
88
- are removed by default** so they don't clutter your agent's slash-command
89
- list. Re-run `npx @chankov/agent-fleet init` whenever you want the runtime's
90
- setup command back, or pick the "keep the installer commands" option at the
91
- setup flow's confirmation to leave them in place.
92
-
93
- ### How the skill finds the source package
94
-
95
- `init` writes one extra file alongside the bootstrap: `.ai/.agent-fleet-bootstrap.json`.
96
- This is the **authoritative** record of where the npm package lives:
97
-
98
- ```json
99
- {
100
- "sourceRoot": "/home/you/.npm/_npx/<hash>/node_modules/@chankov/agent-fleet",
101
- "version": "0.3.0",
102
- "agent": "pi",
103
- "method": "copy",
104
- "bootstrappedAt": "2026-05-24T..."
105
- }
33
+ ```bash
34
+ npx @chankov/agent-fleet@1.0.0 setup --preset default --features none --yes
106
35
  ```
107
36
 
108
- When the Agent Fleet setup command runs inside your agent, it reads this marker
109
- *first* to find the source package. This matters on dev machines where you
110
- may also have a git clone of `agent-fleet` elsewhere — the marker prevents
111
- the skill from accidentally using that clone instead of the version the
112
- user just installed via npm.
113
-
114
- If the marker is missing or its `sourceRoot` no longer exists (e.g. npx
115
- cleaned its cache), the skill **asks you explicitly** for the path. It
116
- never scans your filesystem for other agent-fleet repos — that would
117
- silently pick up forks, stale checkouts, or dev clones that aren't what
118
- you installed.
37
+ **Default** is the launchable, stable Fleet Core and creates neither `.claude/`
38
+ nor voice configuration. **Full** selects every stable, platform-applicable
39
+ catalogue root; it may install the recorded Claude Code coms bridge. Features
40
+ are additive named capabilities (`browser`, `voice`, `hermes`, `telegram`,
41
+ `claude-bridge`, and the experimental `codex-remote`), not an arbitrary
42
+ package-entry mode — `setup --help` lists them.
119
43
 
120
- The marker is removed by the same end-of-setup cleanup that removes the
121
- slash commands (`agent-fleet cleanup-installer`).
44
+ ### Then install the runtime dependencies
122
45
 
123
- | Flag | Default | Purpose |
124
- |------|---------|---------|
125
- | `--agent <claude-code\|opencode\|pi>` | auto-detect | Skip the agent prompt |
126
- | `--workspace <path>` | `cwd` | Target workspace |
127
- | `--launch` | off | Shell into the coding agent after init (best effort) |
46
+ Setup writes files; it does not run commands for you. The two `npm` steps that
47
+ the harnesses and extensions need are planned as `skip` with the reason *"runs a
48
+ command — re-run with `--allow-exec` to include it"*. **A workspace is not
49
+ launchable until they run.** Either let setup run them:
128
50
 
129
51
  ```bash
130
- npx @chankov/agent-fleet init --agent claude-code
131
- npx @chankov/agent-fleet init --workspace ~/projects/foo
52
+ npx @chankov/agent-fleet@latest setup --preset default --features none --allow-exec --yes
132
53
  ```
133
54
 
134
- ### `npx @chankov/agent-fleet doctor`
135
-
136
- Finds and repairs breakage. Two sources, one report:
137
-
138
- - **Recorded items** that are missing, dangling, or linked outside the source
139
- root. These are repaired through the *same* `apply()` path `install` writes
140
- with — a repaired file is byte-identical to a freshly installed one, which is
141
- the structural reason setup and repair cannot drift apart.
142
- - **The scan**, for what the install record cannot own: broken symlinks in a
143
- pre-engine workspace, and stale persona names in `.pi/agents/*.yaml`
144
- (`reviewer` → `code-reviewer`, `red-team` → `security-auditor`).
145
-
146
- Overrides problems and malformed `peers.yaml` entries are **advisory** —
147
- reported, never auto-fixed, because the fix is always a hand edit.
148
-
149
- | Flag | Default | Purpose |
150
- |------|---------|---------|
151
- | `--workspace <path>` | `cwd` | Target workspace |
152
- | `--agent <name>` | recorded → detected | Override the agent whose targets are checked |
153
- | `--fix` | off | Apply the repairs without prompting |
154
- | `--dry-run` | off | Report only; never write, never prompt |
155
- | `--json` | off | Emit the machine report on stdout |
156
- | `--yes` / `-y` | off | Alias for `--fix` |
157
-
158
- | Exit code | Meaning |
159
- |-----------|---------|
160
- | `0` | nothing to repair |
161
- | `1` | could not run |
162
- | `2` | repairable issues found, advisories present, or a repair failed |
55
+ …or run them afterwards through the recipe setup just installed:
163
56
 
164
57
  ```bash
165
- npx @chankov/agent-fleet doctor --workspace ~/projects/foo --dry-run
166
- npx @chankov/agent-fleet doctor --fix
58
+ just fleet deps # npm install in .pi/extensions and .pi/harnesses
59
+ just fleet doctor # confirm the workspace is whole
167
60
  ```
168
61
 
169
- ### `npx @chankov/agent-fleet verify`
170
-
171
- Read-only report of the workspace against `install-manifest.json` — the
172
- generated catalogue of every installable artifact. Compares three things per
173
- item: what `.ai/agent-fleet-state.json` records, what is on disk, and what the
174
- current package ships. Writes nothing and fixes nothing.
175
-
176
- | Flag | Default | Purpose |
177
- |------|---------|---------|
178
- | `--workspace <path>` | `cwd` | Target workspace |
179
- | `--agent <name>` | recorded → detected | Override the agent whose targets are checked |
180
- | `--json` | off | Emit the machine report on stdout |
181
- | `--no-doctor` | off | Skip the symlink/persona/overrides scan |
182
-
183
- | Exit code | Meaning |
184
- |-----------|---------|
185
- | `0` | no broken items, no problem findings |
186
- | `1` | could not run (bad flags, missing manifest, unreadable workspace) |
187
- | `2` | problem findings, or items in a broken state |
188
-
189
- Item states: `absent`, `linked`, `up-to-date`, `outdated`, `modified`,
190
- `partial`, `conflict`, `missing`, `broken-link`, `foreign-link`, `gone`.
191
- An available upgrade (`outdated`) and a deliberate local edit (`modified`) are
192
- reported but do **not** fail the run — neither is a broken workspace.
193
- Findings are likewise split into `problem` and `advisory`; only problems
194
- affect the exit code.
62
+ ### Verify the result
195
63
 
196
64
  ```bash
197
- npx @chankov/agent-fleet verify
198
- npx @chankov/agent-fleet verify --agent pi --json
65
+ just fleet doctor # exit 0 = nothing to repair, 2 = repairable findings
66
+ just fleet # Hub in operator posture, empty native roster
199
67
  ```
200
68
 
201
- `--json` is also the interface `guided-workspace-setup` builds its menu from:
202
- the report carries `groups` (agent-filtered headings), `profiles` (the
203
- shortcuts), and per-item `subcategory`, `title`, `summary`, `recommended`,
204
- `owned`, and `state` — everything a selection screen needs, from one command.
69
+ From here on `just fleet setup`, `just fleet doctor`, and `just fleet uninstall`
70
+ are available as thin wrappers over `npx @chankov/agent-fleet@latest`. They are
71
+ a convenience for a workspace that already has the justfile — never the
72
+ first-install path.
205
73
 
206
- The manifest itself is generated from the repository tree, never hand-written:
74
+ ### Source checkout
75
+
76
+ Inside an Agent Fleet checkout, use the local CLI instead of the published
77
+ package:
207
78
 
208
79
  ```bash
209
- node bin/build-manifest.js # regenerate install-manifest.json
210
- node bin/build-manifest.js --check # fail if the committed copy is stale
80
+ node bin/cli.js setup --workspace ~/projects/my-app --preset default --features none --yes
211
81
  ```
212
82
 
213
- ### `npx @chankov/agent-fleet install` / `upgrade` / `uninstall`
214
-
215
- Three verbs over the same manifest, differing only in which action classes they
216
- admit. `install` acts on a selection you name; `upgrade` acts on whatever the
217
- workspace already has; `uninstall` removes what the state file records.
218
-
219
- All three write the machine state file `.ai/agent-fleet-state.json` and render
220
- `.ai/agent-fleet-setup.md` from it. No coding agent and no model is involved at
221
- any point.
222
-
223
- | Flag | Applies to | Purpose |
224
- |------|-----------|---------|
225
- | `--profile <name[,name]>` | install | Named selections, unioned |
226
- | `--items <id[,id]>` | install, uninstall | Explicit item ids |
227
- | `--all` | uninstall | Remove everything the state file records |
228
- | `-y, --yes` | all | Apply without the confirmation prompt |
229
- | `--allow-exec` | install, upgrade | Include items that run a command |
230
- | `--accept-theirs` / `--accept-ours` | install, upgrade | Resolve conflicts non-interactively |
231
- | `--dry-run` | all | Print the plan, write nothing |
232
- | `--json` | all | Emit the machine plan/result on stdout (needs `--yes` or `--dry-run`) |
233
-
234
- | Exit code | Meaning |
235
- |-----------|---------|
236
- | `0` | applied, or nothing to do |
237
- | `1` | could not plan, or a step failed partway |
238
- | `3` | conflicts — changed both locally and upstream |
83
+ ## Updating an existing install
239
84
 
240
- ```bash
241
- npx @chankov/agent-fleet install --agent pi --profile recommended --yes
242
- npx @chankov/agent-fleet install --items skill:test-driven-development --dry-run
243
- npx @chankov/agent-fleet upgrade --dry-run
244
- npx @chankov/agent-fleet upgrade --yes --accept-ours
245
- npx @chankov/agent-fleet uninstall --items skill:peer-coms --yes
246
- npx @chankov/agent-fleet uninstall --all --dry-run
247
- ```
85
+ ### 1. Notice there is one
248
86
 
249
- Installing into a brand-new repository takes one command and no LLM:
87
+ A pi session started from a workspace with an install record prints a one-line
88
+ banner on its first turn (`pi-extension:agent-fleet-update-check`, installed by
89
+ Default):
250
90
 
251
- ```bash
252
- npx @chankov/agent-fleet@latest install --agent pi --profile recommended --yes
91
+ ```
92
+ agent-fleet update available: 0.1.0 → 0.2.0. Run "npx @chankov/agent-fleet@latest setup" to reconcile the workspace.
253
93
  ```
254
94
 
255
- Run it without `--profile`, `--items`, or `--yes` in a terminal and it asks
256
- which profile to use; piped or scripted, it requires the flags rather than
257
- guessing a catalogue for you.
258
-
259
- Profiles available: `minimal`, `recommended`, `full`, `pi-fleet-core`,
260
- `hermes-plugins`, `codex-bridge`.
261
-
262
- **The two verbs treat a local edit differently, on purpose.** Selecting an item
263
- in `install` is your consent to overwrite your edits to it — those items are
264
- listed as `overwrites` in the plan. `upgrade` carries no such consent, so a file
265
- you edited is preserved (`keep`) whenever the source did not also move. When
266
- *both* changed, it is a conflict: the incoming version is written beside yours
267
- as `<file>.new`, your file is left exactly as it is, and the run exits `3`.
268
-
269
- Files shared with you — the `justfile` managed region and `.claude/settings.json`
270
- — are only partly ours. Recipes outside the `agent-fleet:harnesses` sentinels
271
- and settings keys we did not write are never read as drift and never rewritten.
272
-
273
- A selection never removes anything — installing a narrower profile keeps what is
274
- already there. Upgrade never widens the install either; newly catalogued
275
- artifacts are counted as available and added only by an explicit `install`.
276
-
277
- **Artifacts are installed as copies, always.** `--method symlink` is accepted only when the
278
- workspace is itself an agent-fleet checkout (its `package.json` names `@chankov/agent-fleet`) —
279
- the one place where editing an installed artifact is *meant* to edit the source. Anywhere else a
280
- symlink install is a trap: the link target can never move again, an npx cache clean breaks every
281
- link at once, a `git pull` in the source silently rewrites artifacts the workspace never agreed to
282
- change, and Windows needs Developer Mode. A copy plus `agent-fleet upgrade` gives the same
283
- freshness with a real three-way merge behind it.
284
-
285
- A workspace that recorded `symlink` before this restriction is not left half-supported: `verify`
286
- reports it as an advisory finding, and the next `install` or `upgrade` re-materialises every
287
- linked item as a real file and flips the recorded method to `copy`. An explicit
288
- `--method symlink` outside a checkout is refused rather than silently downgraded.
289
-
290
- **`uninstall` is bound by the ownership rule.** Only paths recorded in
291
- `.ai/agent-fleet-state.json` are eligible, and a recorded file whose bytes no
292
- longer match what we wrote is kept and listed as skipped. Removing an item takes
293
- its companions with it *unless* another installed item still needs them, and an
294
- item another installed item pins is refused by name — so removing one pi
295
- extension cannot delete the `package.json` five others run from, and removing
296
- `damage-control-continue` while `agent-hub` is installed is refused rather than
297
- silently leaving the hub without its safety harness. Removing the last pi
298
- harness strips the `agent-fleet:harnesses` region from the `justfile` and leaves
299
- the rest of the file alone.
300
-
301
- **Some items the engine will not apply, by design.** Each carries a `consent`
302
- class: `file` (plain writes, covered by `--yes`), `exec` (runs a command,
303
- requires `--allow-exec`), `external` (a package you install yourself), and
304
- `operator` (a Hermes profile, a user systemd unit, device pairing). Operator and
305
- external items print their declared steps in the plan and are never performed —
306
- including by `--yes`:
95
+ To ask directly, without a session — it prints one line when an update exists
96
+ and stays silent when you are current:
307
97
 
308
98
  ```bash
309
- npx @chankov/agent-fleet install --agent pi --profile hermes-plugins --dry-run
310
- npx @chankov/agent-fleet install --agent pi --profile codex-bridge --dry-run
99
+ npx @chankov/agent-fleet check-update
311
100
  ```
312
101
 
313
- Both print the exact command list for a human to run and touch nothing. Their
314
- targets are outside the workspace, which is the one place the engine is allowed
315
- to write — so they stay reported rather than automated, and no out-of-workspace
316
- path ever enters the state file.
317
-
318
- ### `npx @chankov/agent-fleet update`
319
-
320
- Reads the workspace's `.ai/agent-fleet-setup.md`, compares the recorded
321
- package version against the installed package version, and **re-installs the
322
- runtime's setup command** so it is always available after an update.
323
- `guided-workspace-setup` removes the installer command at the end of a run by
324
- default, so a workspace that has completed setup once would otherwise have no
325
- command to hand off to. The actual refresh then runs inside the coding agent via
326
- that command — or, with no agent at all, via `upgrade`.
102
+ `pi update --extensions` updates pi's own extensions. It does **not** update
103
+ this installer or anything it wrote.
327
104
 
328
- The agent and install method are recovered from the bootstrap marker written
329
- at init time; if that marker was cleaned up too, `update` auto-detects the
330
- agent (and prompts only when the workspace has more than one agent dir).
331
- Override with `--agent` / `--method`, or preview with `--dry-run`.
105
+ ### 2. Preview the reconcile
332
106
 
333
- ```bash
334
- # Upgrade the package itself first, then check the delta:
335
- npm install -g @chankov/agent-fleet@latest
336
- npx agent-fleet update --workspace .
337
- # The setup command is now back — run the command printed by update to review diffs.
338
- ```
339
-
340
- ### `npx @chankov/agent-fleet transform-persona`
341
-
342
- Generates per-agent subagent definitions from the canonical personas in
343
- `agents/*.md`. `pi` gets the canonical file unchanged; `claude-code` and
344
- `opencode` get a transformed copy — `tools`/`model` translated to the target's
345
- vocabulary (`read→Read`, `find/ls→Glob`, `claude-opus-*→opus`, …; `mode:
346
- subagent` + tool denials for OpenCode), agent-hub-only frontmatter dropped,
347
- body untouched. pi-only personas (`bowser`, `orchestrator`) are refused for
348
- other agents. This is what the Agent Fleet setup workflow runs during apply; transformed installs are always
349
- copies (never symlinks), recorded with `transformed: true`.
350
-
351
- | Flag | Default | Purpose |
352
- |------|---------|---------|
353
- | `--agent <claude-code\|opencode\|pi>` | — (required) | Target agent |
354
- | `--list` | off | Print the availability matrix (persona → target path) |
355
- | `--all` | off | Transform every available persona |
356
- | `--workspace <path>` | — | Write into `<path>`; omit to print to stdout |
357
- | `--dry-run` | off | With `--workspace`: show what would be written |
107
+ Always worth it, always free — `--dry-run` writes nothing and needs no consent:
358
108
 
359
109
  ```bash
360
- npx @chankov/agent-fleet transform-persona --list --agent claude-code
361
- npx @chankov/agent-fleet transform-persona --agent claude-code code-reviewer
362
- npx @chankov/agent-fleet transform-persona --agent opencode --all --workspace .
110
+ just fleet setup --dry-run
111
+ # or, without the justfile recipe:
112
+ npx @chankov/agent-fleet@latest setup --dry-run
363
113
  ```
364
114
 
365
- ## Versioning
366
-
367
- The package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html):
115
+ The plan names every action and its reason. What you are reading for:
368
116
 
369
- | Change | Bump |
117
+ | Line in the plan | Means |
370
118
  |---|---|
371
- | Skill removed, renamed, or its documented workflow changes; persona retired; command removed; install-record schema breakage | **major** |
372
- | New skill, new persona, new command, new option in an existing skill | **minor** |
373
- | Wording fix, doctor scan improvement, CLI bug fix | **patch** |
119
+ | `create` | New in this version, or a feature you added |
120
+ | `refresh … source is newer; the local copy is unmodified` | Clean update. Safe. |
121
+ | `refresh … locally modified — selecting it overwrites your edits` | **Your edit is about to be lost.** See below. |
122
+ | `conflict … changed both locally and upstream` | The run will exit `3` and write nothing until you choose a policy |
123
+ | `keep` | Unchanged, or installed but outside this selection |
124
+ | `remove` | Retired upstream and recorded as ours |
125
+ | `skip … runs a command` | The `npm` steps — follow with `just fleet deps` |
374
126
 
375
- ### Pinning
376
-
377
- To pin a workspace to a specific version, install the package as a project
378
- dependency instead of using `npx`:
127
+ ### 3. Apply it
379
128
 
380
129
  ```bash
381
- npm install --save-dev @chankov/agent-fleet@0.0.1
382
- npx agent-fleet init # resolves to the pinned 0.0.1
130
+ just fleet setup # interactive: shows the plan, asks once
131
+ just fleet setup --yes # non-interactive
132
+ just fleet deps # if the plan skipped the exec steps
133
+ just fleet doctor # verify
383
134
  ```
384
135
 
385
- Or pin globally:
136
+ Your `--preset` / `--features` selection is **remembered**. `.ai/agent-fleet.json`
137
+ is the desired state, so a plain `setup` reconciles to whatever that file says —
138
+ you do not restate the preset on every update. Flags passed on an update are
139
+ ephemeral for that run only unless you add `--save-desired`:
386
140
 
387
141
  ```bash
388
- npm install -g @chankov/agent-fleet@0.0.1
142
+ just fleet setup --features voice,browser --yes # this run only
143
+ just fleet setup --features voice,browser --save-desired --yes # persisted
389
144
  ```
390
145
 
391
- ### What "update" actually changes
392
-
393
- The package update is just `npm`'s usual upgrade. The interesting part runs
394
- inside the agent: `guided-workspace-setup` reads the `version:` line from
395
- `.ai/agent-fleet-setup.md`, computes the delta against the current package
396
- version, and surfaces per-artifact `Status` based on a three-way diff:
397
-
398
- | Status | Means |
399
- |---|---|
400
- | `installed · upgrade available` | Source changed upstream; user copy still matches the old source → clean refresh |
401
- | `installed · conflicting upgrade` | Source changed upstream AND user modified the copy → three-way diff shown, write requires explicit consent |
402
- | `installed · removed upstream` | Artifact gone in the new version → proposed for deletion (subject to the removal-scope rule) |
403
- | `not installed · new in this version` | New artifact added in the new version → offered, marked `★` if recommended |
404
-
405
- The diff is sourced from `.versions/<recorded-version>/` inside the package —
406
- a snapshot the release pipeline writes for every published version.
407
-
408
- ## Other install paths
409
-
410
- npm is the recommended path for most users. The other two stay supported:
411
-
412
- - **[Claude Code plugin marketplace](../README.md#quick-start)** — best UX
413
- inside Claude Code. Same skills, marketplace-managed updates.
414
- - **Git clone** — best for skill authors and contributors. Clone the repo and
415
- work in it directly; inside an agent-fleet checkout `--method symlink` is
416
- available, so an edit to an installed artifact edits the source. For any other
417
- workspace, install copies and run `agent-fleet upgrade` after a `git pull`.
146
+ ### 4. Handle a conflict
418
147
 
419
- All three paths converge on the same `guided-workspace-setup` skill — the
420
- difference is only in how the source files reach the workspace.
148
+ A conflict is *both* sides changing: you edited an installed file **and** the new
149
+ version changed the same file. Setup refuses to guess — it exits `3` before
150
+ writing anything:
421
151
 
422
- ## CI usage
152
+ ```
153
+ conflict skill:code-review-and-quality changed both locally and upstream
154
+ exit 3
155
+ ```
423
156
 
424
- Every verb is scriptable, and a complete install needs no agent and no model:
157
+ Resolve by naming a policy for the run:
425
158
 
426
159
  ```bash
427
- mkdir fresh-repo && cd fresh-repo && git init
428
- npx --yes @chankov/agent-fleet@latest install --agent pi --profile recommended --yes
429
- npx --yes @chankov/agent-fleet@latest verify
160
+ just fleet setup --on-conflict theirs --yes # take the package version
161
+ just fleet setup --on-conflict ours --yes # keep your copy
430
162
  ```
431
163
 
432
- Gate on the exit codes: `verify` exits `2` on drift or problem findings,
433
- `upgrade` exits `3` when a file changed both locally and upstream, and `doctor`
434
- exits `2` when anything repairable is left. `--json` puts the machine report on
435
- stdout and nothing else.
164
+ `theirs` writes the incoming file and your version is gone; `ours` keeps your
165
+ file and this item stays behind the package until you reconcile it by hand. To
166
+ keep a local edit *and* pick up the new upstream content, copy your edit out
167
+ first, take `theirs`, then re-apply it.
168
+
169
+ ### Keeping local edits across updates
170
+
171
+ If you have customized an installed artifact — a skill under `.pi/skills/`, a
172
+ persona under `agents/` — understand that `setup` is a **reconcile to the
173
+ package**, not a merge in your favour. A file you edited where upstream did not
174
+ change is refreshed and your edit is overwritten, without a conflict and without
175
+ a prompt. `--dry-run` is what makes this visible before it happens.
176
+
177
+ The durable ways to customize:
178
+
179
+ - **`.ai/agent-fleet-overrides.md`** — human-owned, never overwritten. Spec/plan
180
+ paths, dev server, branch policy, per-persona models, dispatcher language.
181
+ See [agent-fleet-setup.md](agent-fleet-setup.md). This is the intended door.
182
+ - **Your own artifacts** — a skill under a name Agent Fleet does not ship is not
183
+ in the catalogue, so no lifecycle command touches it.
184
+ - **Deselect the item** — `setup` never removes what falls outside the current
185
+ selection, so a narrower preset leaves an item installed and frozen (`keep …
186
+ installed but not in this selection`).
187
+
188
+ Editing a shipped artifact in place is the one approach the lifecycle actively
189
+ works against.
190
+
191
+ ## What reconcile does to each file
192
+
193
+ The engine classifies every recorded file by comparing three things: the copy on
194
+ disk, the current package source, and the *baseline* — the same file as it
195
+ shipped in the version recorded in `.ai/agent-fleet-state.json`, read from the
196
+ package's `.versions/<x.y.z>/` snapshot tree.
197
+
198
+ | Disk vs source vs baseline | State | `setup` does |
199
+ |---|---|---|
200
+ | Disk matches source | `up-to-date` | `keep` |
201
+ | Disk matches baseline, source moved | `outdated` | `refresh` — clean update |
202
+ | Source matches baseline, disk moved | `modified` | **`refresh` — overwrites your edit** |
203
+ | Disk and source both moved, differently | `conflict` | exits `3` unless `--on-conflict` |
204
+ | Recorded, but no source in this version | `gone` | `keep` (the deprecated `upgrade` proposes removal) |
205
+ | Recorded, missing or mis-linked on disk | breakage | `repair`, regardless of selection |
206
+
207
+ Two things narrow this. If the `.versions/` snapshot for the recorded version is
208
+ missing (an unpublished local build, or a version older than retention), there is
209
+ no baseline: the comparison degrades to two-way, an edited file reads as
210
+ `modified`, and no `conflict` can be detected. And `keep`-on-local-edit is the
211
+ behaviour of the **deprecated `upgrade` verb**, not of `setup` — if you have
212
+ relied on `upgrade` preserving your edits, that is the difference to plan for.
213
+
214
+ ## Desired state and migration
215
+
216
+ The desired selection lives in `.ai/agent-fleet.json` — human-owned, meant to be
217
+ committed. Command-line preset and feature flags are ephemeral over an existing
218
+ file unless `--save-desired` is passed. When the file is missing, setup writes
219
+ the selected desired state in the same transaction as its artifacts.
220
+
221
+ The first major-release migration, from a workspace that predates the state
222
+ file, is deliberately strict:
436
223
 
437
- Running the same install twice produces zero actions on the second run — that
438
- is asserted by test, not left to discipline.
439
-
440
- The conversational flow (`init` → the runtime's setup command) stays interactive
441
- by design; its confirmation gates exist so a human approves every write. Pass
442
- `--agent` explicitly to `init` in CI so it never prompts.
224
+ ```bash
225
+ # Preview is safe and does not require consent.
226
+ npx @chankov/agent-fleet@latest setup --migrate --dry-run
443
227
 
444
- ## Receiving update notifications
228
+ # Automation must name the desired state and explicitly consent to migration.
229
+ npx @chankov/agent-fleet@latest setup --migrate --preset default --features none --yes
230
+ ```
445
231
 
446
- Three independent mechanisms surface "a new version is published" without
447
- you having to remember to check. All three share a single cache at
448
- `$XDG_CACHE_HOME/agent-fleet/latest-version.json` (24h TTL) so the
449
- registry is hit at most once per day.
232
+ Migration lists each exact removal before consent and removes only unchanged,
233
+ state-owned legacy artifacts. Foreign or locally modified files survive.
450
234
 
451
- ### 1. CLI update-notifier (always on)
235
+ `init`, `install`, `upgrade`, and `update` are deprecated. `init` and `update`
236
+ dispatch to `setup`; `install` and `upgrade` keep their historical selection and
237
+ three-way-merge semantics and warn. New scripts should use `setup`.
452
238
 
453
- Every `npx @chankov/agent-fleet <cmd>` invocation runs a fast cache read
454
- on entry. If the cached latest version exceeds the running CLI version, a
455
- banner prints to stderr before the command output:
239
+ ## Doctor and uninstall
456
240
 
457
- ```
458
- ┌──────────────────────────────────────────────────────────────┐
459
- │ agent-fleet update available: 0.1.0 → 0.2.0 │
460
- │ Run: npx @chankov/agent-fleet@latest update │
461
- │ Releases: https://github.com/chankov/agent-fleet/releases │
462
- └──────────────────────────────────────────────────────────────┘
241
+ ```bash
242
+ npx @chankov/agent-fleet doctor # read-only; never prompts
243
+ npx @chankov/agent-fleet doctor --fix
244
+ npx @chankov/agent-fleet uninstall --all --yes
245
+ npx @chankov/agent-fleet uninstall --all --purge-config --yes
463
246
  ```
464
247
 
465
- If the cache is stale, a detached background process refreshes it for the
466
- *next* invocation — the current run is never blocked.
248
+ Uninstall removes only paths recorded in `.ai/agent-fleet-state.json`, and
249
+ preserves any recorded path whose bytes no longer match what we wrote. It also
250
+ preserves human configuration by default: `.ai/agent-fleet.json`,
251
+ `.ai/agent-fleet-overrides.md`, `.ai/stt.json`, and environment files.
252
+ `--purge-config` is the separate destructive gate for the three human config
253
+ files; environment files are never removed.
467
254
 
468
- ### 2. Claude Code session-start hook
255
+ A self-hosted workspace may use `just fleet uninstall --yes`. It removes ordinary
256
+ owned artifacts first, then the managed justfile region and launcher scripts,
257
+ and finally lifecycle state/journal data; the already-running command prints its
258
+ final report from memory. Because that removes `just fleet`, reinstall with the
259
+ package CLI, then use `just fleet` again:
469
260
 
470
- When `hooks/session-start.sh` is installed (offered in Group 18 of `/setup-agent-fleet`),
471
- every new Claude Code session runs the check with a 3-second wall-clock cap.
472
- If an upgrade is available, the banner is injected into the session context
473
- so Claude can mention it on its first turn — e.g. *"Note: agent-fleet 0.2.0
474
- is available; want me to apply it via `/setup-agent-fleet`?"*
475
-
476
- ### 3. pi extension (`agent-fleet-update-check`)
477
-
478
- When installed from the Pi setup flow, the extension fires on the
479
- first `agent_start` event of each pi session and emits a `ctx.ui.notify`
480
- message in the pi UI if a newer version is published. Reads the same cache
481
- as the CLI — no double-fetching.
482
-
483
- ### Opting out
261
+ ```bash
262
+ npx @chankov/agent-fleet@latest setup --preset default --features none --yes
263
+ just fleet doctor
264
+ ```
484
265
 
485
- Any of these environment variables disables all three:
266
+ ## Package-native pi install
486
267
 
487
268
  ```bash
488
- export AGENT_SKILLS_NO_UPDATE_CHECK=1 # agent-fleet-specific
489
- export NO_UPDATE_NOTIFIER=1 # conventional, also honoured
490
- # CI=true is auto-detected — banners never appear in CI logs
269
+ pi install -l npm:@chankov/agent-fleet
491
270
  ```
492
271
 
493
- ### Forcing a manual check
272
+ This exposes package-native skills and prompts. Do not also copy the same skills
273
+ and prompts into `.pi/`; `doctor` reports that ownership overlap as a read-only
274
+ `pi-package-ownership` advisory. Harness-only composition is supported:
275
+ package-native skills/prompts with copied Fleet Core harnesses.
494
276
 
495
- ```bash
496
- # Block on a single registry fetch; print the banner if outdated
497
- npx @chankov/agent-fleet check-update
277
+ ## Safety contract
498
278
 
499
- # Bypass the cache entirely
500
- rm ~/.cache/agent-fleet/latest-version.json
501
- npx @chankov/agent-fleet check-update
502
- ```
279
+ All lifecycle commands support `--dry-run`; JSON output requires either
280
+ `--dry-run` or `--yes`. Files outside state ownership are never adopted for
281
+ removal. A failed file transaction rolls back rather than reporting success, and
282
+ `.ai/agent-fleet-transaction.json` is the crash-recovery journal `doctor --fix`
283
+ reads.
284
+
285
+ | Exit | Meaning |
286
+ |---|---|
287
+ | `0` | Success, or nothing to do |
288
+ | `1` | Could not run |
289
+ | `2` | `doctor` found repairable issues |
290
+ | `3` | `setup` hit unresolved conflicts and wrote nothing |
503
291
 
504
- ## Troubleshooting
505
-
506
- - **"Could not auto-detect your coding agent."** Pass `--agent` or run
507
- `init` from a workspace that already has one of `.claude/`, `.opencode/`,
508
- or `.pi/`.
509
- - **`update` says "no install record".** Run `init` once first; the install
510
- record is what `update` reads.
511
- - **The version-aware menu shows `(snapshot missing)`.** The recorded version
512
- is older than the snapshot retention in this package. The skill falls back
513
- to "treat installed copy as canonical" — refresh manually if you want to
514
- reset the baseline.
292
+ See [Migration](MIGRATION-agent-fleet.md) for the full major-release matrix.