@chankov/agent-fleet 0.0.9 → 0.0.10

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 (354) hide show
  1. package/.claude/commands/doctor-agent-fleet.md +12 -7
  2. package/.claude/commands/setup-agent-fleet.md +7 -15
  3. package/.opencode/commands/af-doctor-agent-fleet.md +12 -7
  4. package/.opencode/commands/af-setup-agent-fleet.md +8 -6
  5. package/.pi/extensions/agent-fleet-update-check/README.md +2 -3
  6. package/.pi/extensions/btw/README.md +2 -2
  7. package/.pi/extensions/chrome-devtools-mcp/README.md +3 -6
  8. package/.pi/extensions/compact-and-continue/README.md +3 -3
  9. package/.pi/extensions/mcp-bridge/README.md +1 -1
  10. package/.pi/harnesses/agent-hub/README.md +139 -10
  11. package/.pi/harnesses/agent-hub/docs-lane.js +122 -0
  12. package/.pi/harnesses/agent-hub/external-blocker.js +85 -0
  13. package/.pi/harnesses/agent-hub/index.ts +448 -39
  14. package/.pi/harnesses/agent-hub/package.json +1 -1
  15. package/.pi/harnesses/agent-hub/review-findings.js +102 -0
  16. package/.pi/harnesses/agent-hub/run-budget.js +302 -4
  17. package/.pi/harnesses/agent-hub/run-namespace.js +87 -0
  18. package/.pi/harnesses/coms/package.json +1 -1
  19. package/.pi/harnesses/damage-control-continue/package.json +1 -1
  20. package/.pi/prompts/af-doctor-agent-fleet.md +13 -6
  21. package/.pi/prompts/af-setup-agent-fleet.md +7 -15
  22. package/.versions/0.0.10/.claude/commands/build.md +44 -0
  23. package/.versions/0.0.10/.claude/commands/code-simplify.md +22 -0
  24. package/.versions/0.0.10/.claude/commands/design-agent.md +14 -0
  25. package/.versions/0.0.10/.claude/commands/doctor-agent-fleet.md +22 -0
  26. package/.versions/0.0.10/.claude/commands/orchestrate.md +112 -0
  27. package/.versions/0.0.10/.claude/commands/plan.md +16 -0
  28. package/.versions/0.0.10/.claude/commands/prime.md +22 -0
  29. package/.versions/0.0.10/.claude/commands/review.md +16 -0
  30. package/.versions/0.0.10/.claude/commands/set-hermes-telegram.md +15 -0
  31. package/.versions/0.0.10/.claude/commands/set-hermes-watchdog.md +6 -0
  32. package/.versions/0.0.10/.claude/commands/setup-agent-fleet.md +17 -0
  33. package/.versions/0.0.10/.claude/commands/ship.md +72 -0
  34. package/.versions/0.0.10/.claude/commands/spec.md +15 -0
  35. package/.versions/0.0.10/.claude/commands/test.md +19 -0
  36. package/.versions/0.0.10/.claude/commands/webperf.md +32 -0
  37. package/.versions/0.0.10/.claude/orchestrate-teams.yaml +24 -0
  38. package/.versions/0.0.10/.opencode/commands/af-build.md +17 -0
  39. package/.versions/0.0.10/.opencode/commands/af-code-simplify.md +16 -0
  40. package/.versions/0.0.10/.opencode/commands/af-compound.md +16 -0
  41. package/.versions/0.0.10/.opencode/commands/af-design-agent.md +15 -0
  42. package/.versions/0.0.10/.opencode/commands/af-doctor-agent-fleet.md +22 -0
  43. package/.versions/0.0.10/.opencode/commands/af-orchestrate.md +112 -0
  44. package/.versions/0.0.10/.opencode/commands/af-plan.md +16 -0
  45. package/.versions/0.0.10/.opencode/commands/af-prime.md +22 -0
  46. package/.versions/0.0.10/.opencode/commands/af-review.md +15 -0
  47. package/.versions/0.0.10/.opencode/commands/af-set-hermes-telegram.md +15 -0
  48. package/.versions/0.0.10/.opencode/commands/af-set-hermes-watchdog.md +6 -0
  49. package/.versions/0.0.10/.opencode/commands/af-setup-agent-fleet.md +17 -0
  50. package/.versions/0.0.10/.opencode/commands/af-ship.md +16 -0
  51. package/.versions/0.0.10/.opencode/commands/af-spec.md +16 -0
  52. package/.versions/0.0.10/.opencode/commands/af-test.md +21 -0
  53. package/.versions/0.0.10/.opencode/commands/af-webperf.md +32 -0
  54. package/.versions/0.0.10/.opencode/orchestrate-teams.yaml +24 -0
  55. package/.versions/0.0.10/.pi/agents/dispatch-policy.yaml +32 -0
  56. package/.versions/0.0.10/.pi/agents/model-profiles.yaml +27 -0
  57. package/.versions/0.0.10/.pi/agents/peers.yaml +142 -0
  58. package/.versions/0.0.10/.pi/agents/teams.yaml +41 -0
  59. package/.versions/0.0.10/.pi/damage-control-rules.yaml +297 -0
  60. package/.versions/0.0.10/.pi/extensions/agent-fleet-update-check/README.md +57 -0
  61. package/.versions/0.0.10/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  62. package/.versions/0.0.10/.pi/extensions/agent-fleet-update-check/package.json +6 -0
  63. package/.versions/0.0.10/.pi/extensions/btw/README.md +118 -0
  64. package/.versions/0.0.10/.pi/extensions/btw/index.ts +917 -0
  65. package/.versions/0.0.10/.pi/extensions/btw/package.json +6 -0
  66. package/.versions/0.0.10/.pi/extensions/btw/state.js +179 -0
  67. package/.versions/0.0.10/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
  68. package/.versions/0.0.10/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
  69. package/.versions/0.0.10/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  70. package/.versions/0.0.10/.pi/extensions/compact-and-continue/README.md +42 -0
  71. package/.versions/0.0.10/.pi/extensions/compact-and-continue/index.ts +120 -0
  72. package/.versions/0.0.10/.pi/extensions/compact-and-continue/package.json +6 -0
  73. package/.versions/0.0.10/.pi/extensions/mcp-bridge/README.md +46 -0
  74. package/.versions/0.0.10/.pi/extensions/mcp-bridge/index.ts +206 -0
  75. package/.versions/0.0.10/.pi/extensions/mcp-bridge/package.json +6 -0
  76. package/.versions/0.0.10/.pi/extensions/package-lock.json +1143 -0
  77. package/.versions/0.0.10/.pi/extensions/package.json +9 -0
  78. package/.versions/0.0.10/.pi/extensions/pi-voice-stt/README.md +201 -0
  79. package/.versions/0.0.10/.pi/extensions/pi-voice-stt/config.ts +198 -0
  80. package/.versions/0.0.10/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  81. package/.versions/0.0.10/.pi/extensions/pi-voice-stt/index.ts +248 -0
  82. package/.versions/0.0.10/.pi/extensions/pi-voice-stt/package.json +6 -0
  83. package/.versions/0.0.10/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  84. package/.versions/0.0.10/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  85. package/.versions/0.0.10/.pi/harnesses/agent-hub/README.md +1001 -0
  86. package/.versions/0.0.10/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  87. package/.versions/0.0.10/.pi/harnesses/agent-hub/artifacts.js +146 -0
  88. package/.versions/0.0.10/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
  89. package/.versions/0.0.10/.pi/harnesses/agent-hub/backend-policy.js +153 -0
  90. package/.versions/0.0.10/.pi/harnesses/agent-hub/context-window.js +106 -0
  91. package/.versions/0.0.10/.pi/harnesses/agent-hub/delegate.ts +435 -0
  92. package/.versions/0.0.10/.pi/harnesses/agent-hub/docs-lane.js +122 -0
  93. package/.versions/0.0.10/.pi/harnesses/agent-hub/drift-watchdog.js +211 -0
  94. package/.versions/0.0.10/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  95. package/.versions/0.0.10/.pi/harnesses/agent-hub/external-blocker.js +85 -0
  96. package/.versions/0.0.10/.pi/harnesses/agent-hub/footer.ts +31 -0
  97. package/.versions/0.0.10/.pi/harnesses/agent-hub/helpers.ts +248 -0
  98. package/.versions/0.0.10/.pi/harnesses/agent-hub/index.ts +9111 -0
  99. package/.versions/0.0.10/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  100. package/.versions/0.0.10/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
  101. package/.versions/0.0.10/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
  102. package/.versions/0.0.10/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  103. package/.versions/0.0.10/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  104. package/.versions/0.0.10/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  105. package/.versions/0.0.10/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  106. package/.versions/0.0.10/.pi/harnesses/agent-hub/monitor-session-bridge.ts +257 -0
  107. package/.versions/0.0.10/.pi/harnesses/agent-hub/package.json +7 -0
  108. package/.versions/0.0.10/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
  109. package/.versions/0.0.10/.pi/harnesses/agent-hub/research-retention.js +34 -0
  110. package/.versions/0.0.10/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  111. package/.versions/0.0.10/.pi/harnesses/agent-hub/return-contract.js +293 -0
  112. package/.versions/0.0.10/.pi/harnesses/agent-hub/return-extract.js +75 -0
  113. package/.versions/0.0.10/.pi/harnesses/agent-hub/review-findings.js +102 -0
  114. package/.versions/0.0.10/.pi/harnesses/agent-hub/run-budget.js +479 -0
  115. package/.versions/0.0.10/.pi/harnesses/agent-hub/run-namespace.js +87 -0
  116. package/.versions/0.0.10/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  117. package/.versions/0.0.10/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  118. package/.versions/0.0.10/.pi/harnesses/agent-hub/session-health.js +110 -0
  119. package/.versions/0.0.10/.pi/harnesses/agent-hub/spawn.ts +354 -0
  120. package/.versions/0.0.10/.pi/harnesses/agent-hub/version.ts +42 -0
  121. package/.versions/0.0.10/.pi/harnesses/ask-user-remote/README.md +19 -0
  122. package/.versions/0.0.10/.pi/harnesses/ask-user-remote/index.ts +321 -0
  123. package/.versions/0.0.10/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  124. package/.versions/0.0.10/.pi/harnesses/coms/README.md +100 -0
  125. package/.versions/0.0.10/.pi/harnesses/coms/index.ts +1767 -0
  126. package/.versions/0.0.10/.pi/harnesses/coms/package.json +7 -0
  127. package/.versions/0.0.10/.pi/harnesses/coms/version.ts +42 -0
  128. package/.versions/0.0.10/.pi/harnesses/damage-control-continue/README.md +124 -0
  129. package/.versions/0.0.10/.pi/harnesses/damage-control-continue/index.ts +536 -0
  130. package/.versions/0.0.10/.pi/harnesses/damage-control-continue/package.json +7 -0
  131. package/.versions/0.0.10/.pi/harnesses/damage-control-continue/version.ts +42 -0
  132. package/.versions/0.0.10/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
  133. package/.versions/0.0.10/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  134. package/.versions/0.0.10/.pi/harnesses/lib/herdr-client.ts +472 -0
  135. package/.versions/0.0.10/.pi/harnesses/lib/herdr-presence.ts +399 -0
  136. package/.versions/0.0.10/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
  137. package/.versions/0.0.10/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
  138. package/.versions/0.0.10/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
  139. package/.versions/0.0.10/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
  140. package/.versions/0.0.10/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
  141. package/.versions/0.0.10/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
  142. package/.versions/0.0.10/.pi/harnesses/lib/spawned-peers.js +190 -0
  143. package/.versions/0.0.10/.pi/harnesses/package-lock.json +35 -0
  144. package/.versions/0.0.10/.pi/harnesses/package.json +9 -0
  145. package/.versions/0.0.10/.pi/prompts/af-build.md +24 -0
  146. package/.versions/0.0.10/.pi/prompts/af-code-simplify.md +22 -0
  147. package/.versions/0.0.10/.pi/prompts/af-doctor-agent-fleet.md +22 -0
  148. package/.versions/0.0.10/.pi/prompts/af-plan.md +16 -0
  149. package/.versions/0.0.10/.pi/prompts/af-review.md +16 -0
  150. package/.versions/0.0.10/.pi/prompts/af-set-hermes-telegram.md +15 -0
  151. package/.versions/0.0.10/.pi/prompts/af-set-hermes-watchdog.md +6 -0
  152. package/.versions/0.0.10/.pi/prompts/af-setup-agent-fleet.md +19 -0
  153. package/.versions/0.0.10/.pi/prompts/af-ship.md +17 -0
  154. package/.versions/0.0.10/.pi/prompts/af-spec.md +15 -0
  155. package/.versions/0.0.10/.pi/prompts/af-test.md +19 -0
  156. package/.versions/0.0.10/.pi/skills/bowser/SKILL.md +145 -0
  157. package/.versions/0.0.10/.version +1 -0
  158. package/.versions/0.0.10/agents/architect.md +24 -0
  159. package/.versions/0.0.10/agents/bowser.md +27 -0
  160. package/.versions/0.0.10/agents/builder.md +54 -0
  161. package/.versions/0.0.10/agents/code-reviewer.md +208 -0
  162. package/.versions/0.0.10/agents/deep-researcher.md +32 -0
  163. package/.versions/0.0.10/agents/documenter.md +18 -0
  164. package/.versions/0.0.10/agents/orchestrator.md +72 -0
  165. package/.versions/0.0.10/agents/plan-reviewer.md +83 -0
  166. package/.versions/0.0.10/agents/planner.md +70 -0
  167. package/.versions/0.0.10/agents/releaser.md +24 -0
  168. package/.versions/0.0.10/agents/researcher.md +28 -0
  169. package/.versions/0.0.10/agents/security-auditor.md +167 -0
  170. package/.versions/0.0.10/agents/test-engineer.md +153 -0
  171. package/.versions/0.0.10/agents/web-debugger.md +43 -0
  172. package/.versions/0.0.10/agents/web-performance-auditor.md +193 -0
  173. package/.versions/0.0.10/codex/CONDUCTOR.md +148 -0
  174. package/.versions/0.0.10/docs/ARCHITECTURE.md +303 -0
  175. package/.versions/0.0.10/docs/agent-fleet-setup.md +377 -0
  176. package/.versions/0.0.10/docs/claude-code-coms-bridge.md +109 -0
  177. package/.versions/0.0.10/docs/codex-remote-conductor.md +170 -0
  178. package/.versions/0.0.10/docs/coms-hermes-bridge.md +189 -0
  179. package/.versions/0.0.10/docs/getting-started.md +254 -0
  180. package/.versions/0.0.10/docs/npm-install.md +514 -0
  181. package/.versions/0.0.10/docs/opencode-setup.md +281 -0
  182. package/.versions/0.0.10/docs/pi-extensions.md +363 -0
  183. package/.versions/0.0.10/docs/pi-setup.md +571 -0
  184. package/.versions/0.0.10/docs/skill-anatomy.md +150 -0
  185. package/.versions/0.0.10/hermes/README.md +347 -0
  186. package/.versions/0.0.10/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
  187. package/.versions/0.0.10/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
  188. package/.versions/0.0.10/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  189. package/.versions/0.0.10/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  190. package/.versions/0.0.10/hermes/gates/gate-o-capability.md +8 -0
  191. package/.versions/0.0.10/hermes/gates/gate-o-validator-fixtures.json +1 -0
  192. package/.versions/0.0.10/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +770 -0
  193. package/.versions/0.0.10/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
  194. package/.versions/0.0.10/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
  195. package/.versions/0.0.10/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
  196. package/.versions/0.0.10/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
  197. package/.versions/0.0.10/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
  198. package/.versions/0.0.10/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
  199. package/.versions/0.0.10/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
  200. package/.versions/0.0.10/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
  201. package/.versions/0.0.10/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
  202. package/.versions/0.0.10/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
  203. package/.versions/0.0.10/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  204. package/.versions/0.0.10/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  205. package/.versions/0.0.10/hermes/skills/hub-conductor/SKILL.md +84 -0
  206. package/.versions/0.0.10/hermes/skills/hub-liaison/SKILL.md +84 -0
  207. package/.versions/0.0.10/hermes/skills/hub-watchdog/SKILL.md +76 -0
  208. package/.versions/0.0.10/hermes/skills/hub-watchdog/manifest.json +1 -0
  209. package/.versions/0.0.10/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
  210. package/.versions/0.0.10/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
  211. package/.versions/0.0.10/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
  212. package/.versions/0.0.10/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
  213. package/.versions/0.0.10/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
  214. package/.versions/0.0.10/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
  215. package/.versions/0.0.10/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
  216. package/.versions/0.0.10/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
  217. package/.versions/0.0.10/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
  218. package/.versions/0.0.10/hermes/watchdog-tests/__init__.py +0 -0
  219. package/.versions/0.0.10/hooks/SIMPLIFY-IGNORE.md +90 -0
  220. package/.versions/0.0.10/hooks/coms-stop-hook.mjs +84 -0
  221. package/.versions/0.0.10/hooks/hooks.json +14 -0
  222. package/.versions/0.0.10/hooks/session-start.sh +74 -0
  223. package/.versions/0.0.10/hooks/simplify-ignore.sh +302 -0
  224. package/.versions/0.0.10/install-manifest.json +3615 -0
  225. package/.versions/0.0.10/justfile +254 -0
  226. package/.versions/0.0.10/manifest-meta.json +472 -0
  227. package/.versions/0.0.10/references/accessibility-checklist.md +160 -0
  228. package/.versions/0.0.10/references/definition-of-done.md +67 -0
  229. package/.versions/0.0.10/references/fleet-coordination-patterns.md +151 -0
  230. package/.versions/0.0.10/references/observability-checklist.md +91 -0
  231. package/.versions/0.0.10/references/orchestration-patterns.md +370 -0
  232. package/.versions/0.0.10/references/performance-checklist.md +153 -0
  233. package/.versions/0.0.10/references/prompting-patterns.md +380 -0
  234. package/.versions/0.0.10/references/security-checklist.md +179 -0
  235. package/.versions/0.0.10/references/testing-patterns.md +236 -0
  236. package/.versions/0.0.10/scripts/codex-conductor.ts +41 -0
  237. package/.versions/0.0.10/scripts/codex-remote-control.ts +167 -0
  238. package/.versions/0.0.10/scripts/coms-claude-bridge.ts +401 -0
  239. package/.versions/0.0.10/scripts/coms-cli.ts +484 -0
  240. package/.versions/0.0.10/scripts/coms-hermes-bridge.ts +413 -0
  241. package/.versions/0.0.10/scripts/fleet.ts +168 -0
  242. package/.versions/0.0.10/scripts/hermes-monitor-capability-runner.ts +25 -0
  243. package/.versions/0.0.10/scripts/hermes-monitor-scenario.ts +474 -0
  244. package/.versions/0.0.10/scripts/hermes-watchdog-capability-probe.ts +45 -0
  245. package/.versions/0.0.10/scripts/install-hermes-plugin.sh +180 -0
  246. package/.versions/0.0.10/scripts/lib/claude-bridge-core.ts +165 -0
  247. package/.versions/0.0.10/scripts/lib/codex-conductor.ts +88 -0
  248. package/.versions/0.0.10/scripts/lib/codex-remote-control.ts +480 -0
  249. package/.versions/0.0.10/scripts/lib/coms-envelope.ts +582 -0
  250. package/.versions/0.0.10/scripts/lib/fake-herdr-server.ts +88 -0
  251. package/.versions/0.0.10/scripts/lib/fleet-command.ts +111 -0
  252. package/.versions/0.0.10/scripts/lib/herdr-layout.ts +281 -0
  253. package/.versions/0.0.10/scripts/lib/hermes-bridge-core.ts +241 -0
  254. package/.versions/0.0.10/scripts/lib/hermes-monitor-events.ts +1 -0
  255. package/.versions/0.0.10/scripts/lib/hermes-monitor-herdr.ts +2 -0
  256. package/.versions/0.0.10/scripts/lib/hermes-monitor-model.ts +3 -0
  257. package/.versions/0.0.10/scripts/lib/hermes-monitor-registry.ts +2 -0
  258. package/.versions/0.0.10/scripts/lib/hermes-monitor-socket.ts +2 -0
  259. package/.versions/0.0.10/scripts/lib/hermes-monitor-store.ts +2 -0
  260. package/.versions/0.0.10/scripts/lib/monitor-env.ts +120 -0
  261. package/.versions/0.0.10/scripts/lib/peer-launch.ts +314 -0
  262. package/.versions/0.0.10/scripts/lib/persona-banner.ts +62 -0
  263. package/.versions/0.0.10/scripts/lib/spawn-stagger.ts +101 -0
  264. package/.versions/0.0.10/scripts/lib/team-project.ts +193 -0
  265. package/.versions/0.0.10/scripts/lib/team-snapshot.ts +147 -0
  266. package/.versions/0.0.10/scripts/peer-banner.ts +40 -0
  267. package/.versions/0.0.10/scripts/peer-launch.ts +259 -0
  268. package/.versions/0.0.10/scripts/team-snapshot.ts +237 -0
  269. package/.versions/0.0.10/scripts/team-up.ts +360 -0
  270. package/.versions/0.0.10/skills/_internal/grilling.md +11 -0
  271. package/.versions/0.0.10/skills/browser-testing-with-devtools/SKILL.md +351 -0
  272. package/.versions/0.0.10/skills/code-review-and-quality/SKILL.md +381 -0
  273. package/.versions/0.0.10/skills/compound-learning/SKILL.md +137 -0
  274. package/.versions/0.0.10/skills/context-engineering/SKILL.md +291 -0
  275. package/.versions/0.0.10/skills/deprecation-and-migration/SKILL.md +206 -0
  276. package/.versions/0.0.10/skills/designing-agents/SKILL.md +394 -0
  277. package/.versions/0.0.10/skills/designing-agents/pi-harness-authoring.md +222 -0
  278. package/.versions/0.0.10/skills/frontend-ui-engineering/SKILL.md +328 -0
  279. package/.versions/0.0.10/skills/git-workflow-and-versioning/SKILL.md +316 -0
  280. package/.versions/0.0.10/skills/guided-workspace-setup/SKILL.md +226 -0
  281. package/.versions/0.0.10/skills/guided-workspace-setup/companion-manifest.json +38 -0
  282. package/.versions/0.0.10/skills/idea-refine/SKILL.md +182 -0
  283. package/.versions/0.0.10/skills/idea-refine/examples.md +238 -0
  284. package/.versions/0.0.10/skills/idea-refine/frameworks.md +99 -0
  285. package/.versions/0.0.10/skills/idea-refine/refinement-criteria.md +113 -0
  286. package/.versions/0.0.10/skills/idea-refine/scripts/idea-refine.sh +15 -0
  287. package/.versions/0.0.10/skills/incremental-implementation/SKILL.md +287 -0
  288. package/.versions/0.0.10/skills/interview-me/SKILL.md +226 -0
  289. package/.versions/0.0.10/skills/orchestration-verification/SKILL.md +181 -0
  290. package/.versions/0.0.10/skills/peer-coms/SKILL.md +90 -0
  291. package/.versions/0.0.10/skills/performance-optimization/SKILL.md +350 -0
  292. package/.versions/0.0.10/skills/planning-and-task-breakdown/SKILL.md +254 -0
  293. package/.versions/0.0.10/skills/security-and-hardening/SKILL.md +461 -0
  294. package/.versions/0.0.10/skills/spec-driven-development/SKILL.md +257 -0
  295. package/.versions/0.0.10/skills/using-agent-skills/SKILL.md +199 -0
  296. package/.versions/0.0.10/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  297. package/.versions/0.0.10/vendor/agent-skills-upstream/LICENSE +21 -0
  298. package/.versions/0.0.10/vendor/agent-skills-upstream/README.md +11 -0
  299. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  300. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  301. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  302. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  303. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  304. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  305. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  306. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  307. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  308. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  309. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  310. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  311. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  312. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  313. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  314. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  315. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  316. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  317. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  318. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  319. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  320. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  321. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  322. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  323. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  324. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  325. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  326. package/.versions/0.0.10/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  327. package/CHANGELOG.md +103 -0
  328. package/README.md +22 -5
  329. package/agents/code-reviewer.md +4 -0
  330. package/agents/orchestrator.md +7 -1
  331. package/agents/plan-reviewer.md +22 -1
  332. package/bin/build-manifest.js +68 -0
  333. package/bin/cli.js +679 -49
  334. package/bin/lib/apply.js +641 -0
  335. package/bin/lib/manifest.js +731 -0
  336. package/bin/lib/merge-forms.js +106 -0
  337. package/bin/lib/plan.js +569 -0
  338. package/bin/lib/state.js +213 -0
  339. package/bin/lib/verify.js +576 -0
  340. package/bin/snapshot-version.js +5 -0
  341. package/docs/ARCHITECTURE.md +52 -11
  342. package/docs/agent-fleet-setup.md +59 -48
  343. package/docs/getting-started.md +29 -6
  344. package/docs/npm-install.md +208 -31
  345. package/docs/opencode-setup.md +32 -0
  346. package/docs/pi-extensions.md +17 -10
  347. package/docs/pi-setup.md +164 -69
  348. package/install-manifest.json +3615 -0
  349. package/manifest-meta.json +472 -0
  350. package/package.json +8 -3
  351. package/skills/browser-testing-with-devtools/SKILL.md +3 -4
  352. package/skills/guided-workspace-setup/SKILL.md +172 -490
  353. package/skills/planning-and-task-breakdown/SKILL.md +18 -0
  354. package/skills/spec-driven-development/SKILL.md +12 -0
@@ -1,12 +1,13 @@
1
1
  # Agent Fleet — Project Files
2
2
 
3
- agent-fleet keeps up to two small files in a project's `.ai/` directory. They
4
- have different readers and different lifetimes, so they are kept separate.
3
+ agent-fleet keeps a few small files in a project's `.ai/` directory. They have
4
+ different readers and different lifetimes, so they are kept separate.
5
5
 
6
6
  | File | Read by | When |
7
7
  |------|---------|------|
8
8
  | `.ai/agent-fleet-overrides.md` | `spec-driven-development`, `planning-and-task-breakdown`, `browser-testing-with-devtools`, `git-workflow-and-versioning`, `compound-learning` (the `rules:`/`docs:` keys of `## agent-hub`), `agent-hub` pi harness | Every run of those skills / every session start of the harness |
9
- | `.ai/agent-fleet-setup.md` | `guided-workspace-setup` | Only when setup is run or re-run |
9
+ | `.ai/agent-fleet-state.json` | the `agent-fleet` CLI (`install`, `upgrade`, `uninstall`, `verify`, `doctor`) | Every plan and every apply |
10
+ | `.ai/agent-fleet-setup.md` | humans — rendered from the state file, never parsed back | Rewritten on every apply |
10
11
  | `.ai/stt.json` *(optional)* | `pi-voice-stt` extension | Every pi session start, when the extension is installed |
11
12
 
12
13
  The `.ai/stt.json` file is present only when the optional `pi-voice-stt` voice-dictation
@@ -15,7 +16,8 @@ extension has been configured (by guided setup or by hand). Like the overrides f
15
16
  live in a gitignored root `.env`. See [pi-voice-stt config](#ai-sttjson) below.
16
17
 
17
18
  Keep them split: the overrides file is loaded into context constantly, so it
18
- must stay minimal; the install record is consulted rarely, so it can be large.
19
+ must stay minimal; the install record is read only by the CLI, so it can be
20
+ large.
19
21
 
20
22
  ## The overrides file — `.ai/agent-fleet-overrides.md`
21
23
 
@@ -166,55 +168,61 @@ otherwise, never mid-run), and its **values never appear in `--dry-run`
166
168
  output** — only the path. Keep these files gitignored exactly like the root
167
169
  `.env` this section describes.
168
170
 
169
- ## The setup file — `.ai/agent-fleet-setup.md`
171
+ ## The install record — `.ai/agent-fleet-state.json` and `.ai/agent-fleet-setup.md`
170
172
 
171
- The `guided-workspace-setup` skill writes this file to record what it installed
172
- into the project — which skills, commands, personas, and extensions, by what
173
- method, and when. It reads the file on a re-run to add, update, or remove
174
- artifacts without reinstalling everything. No other skill loads it.
173
+ Two files, one source of truth. `.ai/agent-fleet-state.json` is what the
174
+ installer writes and the only thing it reads back: agent, method, package
175
+ version, source root, and one entry per installed item with a per-file sha256
176
+ (or, in symlink mode, the resolved link target). `.ai/agent-fleet-setup.md` is
177
+ **rendered from it** on every apply and never parsed back, so the two cannot
178
+ disagree — it exists for humans and for older readers that still look for
179
+ `version:` and `agent:`.
175
180
 
176
- | Section | Meaning |
177
- |---------|---------|
178
- | `workspace-summary` | Workspace path, coding agent, **agent-fleet version**, project shape, checks discovered |
179
- | `install-status` | Installed artifacts, their targets, and the method (`copy` or `symlink`) |
180
- | `doctor-runs` | One line per doctor pass (preflight / postflight, repaired / deleted / skipped counts) |
181
- | `verification` | Checks confirming the install |
181
+ Ownership is the point of the state file. An entry means "agent-fleet installed
182
+ this"; anything not listed is never removed or overwritten. That lookup is what
183
+ replaced the prose ownership rule the setup skill used to carry.
182
184
 
183
- ### The `version:` line
185
+ | State-file field | Meaning |
186
+ |---|---|
187
+ | `agent`, `method`, `sourceRoot` | How and from where this workspace was installed |
188
+ | `packageVersion` | The version that performed the last apply — the merge base for the next `upgrade` |
189
+ | `items` | One entry per installed artifact: strategy, method, files with hashes, JSON key paths |
190
+ | `externalPackages` | Packages the user was told to install; recorded, never installed for them |
191
+ | `events` | Last few applies (verb, version, action count, conflicts) |
192
+
193
+ **No secrets, ever.** Only env-var *names* may appear — for example in the
194
+ `pi-voice-stt` record. A test asserts nothing value-shaped is persisted.
184
195
 
185
- `workspace-summary` carries a `version:` line set to the package version that
186
- performed the install (e.g. `version: 1.4.2`). It drives the version-aware
187
- update flow — on every re-run, `guided-workspace-setup` compares this against
188
- the current package version and:
196
+ ### The recorded version and the three-way merge
189
197
 
190
- 1. Reads `CHANGELOG.md` between the two versions.
191
- 2. For each installed artifact, runs a three-way diff between
192
- *source@recorded*, the installed copy on disk, and *source@current*.
193
- 3. Surfaces the result in the install menu using these `Status` values:
198
+ `packageVersion` drives `upgrade`. For each installed artifact the engine
199
+ compares three sides: *source@recorded* from the package's `.versions/<x.y.z>/`
200
+ snapshot tree, the installed copy on disk, and *source@current*.
194
201
 
195
- | Status | Meaning |
202
+ | Outcome | What happens |
196
203
  |---|---|
197
- | `installed · upgrade available` | Source changed upstream; user copy still matches the old source → clean refresh |
198
- | `installed · conflicting upgrade` | Source changed upstream AND user modified the copy → menu shows the three-way diff before overwriting |
199
- | `installed · removed upstream` | Artifact gone in the new version → menu proposes deletion (subject to the removal-scope rule) |
200
- | `not installed · new in this version` | New artifact added in the new version → menu offers it, marked `★` if recommended |
204
+ | Only the source moved | Clean refresh |
205
+ | Only your copy moved | Kept — `upgrade` never eats a local edit |
206
+ | Both moved, to different content | **Conflict**: the incoming version is written as `<file>.new`, your file is untouched, the run exits `3` |
207
+ | Retired upstream | Proposed for removal by name, subject to the ownership rule |
201
208
 
202
- The diff sources at *source@recorded* are read from the package's
203
- `.versions/<x.y.z>/` snapshot tree, which the release pipeline writes for every
204
- published version. If the snapshot is missing (e.g. an unpublished local
205
- build), the skill falls back to "treat installed copy as canonical" and
206
- prompts for an explicit baseline.
209
+ If the snapshot is missing (an unpublished local build, or a version older than
210
+ `.versions/` retention), the comparison degrades to two-way, the installed copy
211
+ is treated as canonical, and `verify` says so as an advisory finding rather than
212
+ pretending a diff exists.
207
213
 
208
- ### Pre-versioning workspaces
214
+ ### Pre-engine workspaces
209
215
 
210
- A workspace whose `agent-fleet-setup.md` predates the `version:` line is
211
- treated as "pre-versioning". On first re-run, `guided-workspace-setup` prompts
212
- for a clean baseline: either accept the installed artifacts as matching the
213
- current source (stamp the current version), or re-run the install from scratch.
216
+ A workspace with only `.ai/agent-fleet-setup.md` and no state file predates the
217
+ installer engine. `verify` reads what it can from the markdown (`agent:`,
218
+ `version:`), reports `stateSource: "legacy-record"`, and `upgrade` says plainly
219
+ that ownership cannot be read back — run `install` once to reconstruct the state
220
+ file first. A workspace with no `version:` at all is pre-versioning: there is no
221
+ recorded baseline, so no three-way merge is attempted.
214
222
 
215
- Commit this file if the team should share install state — keep paths relative
216
- so it stays portable. A self-referencing checkout (agent-fleet itself) may
217
- instead `.gitignore` it, since its recorded paths are local to one machine.
223
+ Commit these files if the team should share install state — keep paths relative
224
+ so they stay portable. A self-referencing checkout (agent-fleet itself) may
225
+ instead `.gitignore` them, since their recorded paths are local to one machine.
218
226
 
219
227
  ## The `/orchestrate` command and its team config
220
228
 
@@ -310,18 +318,20 @@ required: <ENV_VAR_NAME>[, <ANOTHER_NAME>]
310
318
 
311
319
  ### `.ai/agent-fleet-setup.md`
312
320
 
313
- Written and maintained by `guided-workspace-setup`; shown here for reference.
321
+ Rendered from `.ai/agent-fleet-state.json` by every apply, for humans to read.
322
+ Edit the workspace, not this file — the next apply overwrites it.
314
323
 
315
324
  ```markdown
316
325
  # Agent Fleet — Workspace Setup
317
326
  #
318
- # Maintained by the guided-workspace-setup skill.
327
+ # Generated from .ai/agent-fleet-state.json by `agent-fleet install`.
328
+ # Edit the workspace, not this file: it is rewritten on every apply.
319
329
 
320
330
  ## workspace-summary
321
331
  agent: claude-code
322
332
  method: copy
323
333
  version: 1.4.2
324
- shape: <one line on the project shape>
334
+ source: /home/you/.npm/_npx/<hash>/node_modules/@chankov/agent-fleet
325
335
 
326
336
  ## install-status
327
337
  skills: [spec-driven-development, test-driven-development, code-review-and-quality]
@@ -329,12 +339,13 @@ commands: [spec, plan, build]
329
339
  personas: [code-reviewer]
330
340
  extensions: []
331
341
  harnesses: []
332
- harness-support: [] # justfile (managed region) + scripts/agents companions; tracked when any harness is installed
342
+ companions: [skills-internal-grilling]
343
+ external: []
333
344
  updated: 2026-05-22
334
345
 
335
346
  ## verification
336
- - Every recorded artifact exists at its target path.
337
- - No secrets are stored in this file.
347
+ - 21 item(s) recorded; run `agent-fleet verify` to check them against disk.
348
+ - No secrets are stored in this file or in .ai/agent-fleet-state.json.
338
349
  ```
339
350
 
340
351
  ### `.ai/stt.json`
@@ -13,10 +13,27 @@ Each skill is a Markdown file (`SKILL.md`) that describes a specific engineering
13
13
  | Audience | Path | Why |
14
14
  |---|---|---|
15
15
  | **Most users** — you want to use the skills in your projects | `npx @chankov/agent-fleet init` | One command; semver updates; cross-platform; no source dir to babysit. See [docs/npm-install.md](npm-install.md). |
16
+ | **You already know what you want** — or you're scripting a fresh repo | `npx @chankov/agent-fleet install --agent <a> --profile recommended --yes` | The CLI does every write itself: no coding agent, no model, no prompts. |
16
17
  | **Claude Code users** — you live in Claude Code and want plugin-managed updates | `/plugin marketplace add chankov/agent-fleet` | Best UX inside Claude Code; marketplace handles the lifecycle. |
17
- | **Skill authors / contributors** — you want to edit the skills and have changes flow into every connected workspace | `git clone` + `symlink` mode in `/setup-agent-fleet` | Edit-in-place; every connected workspace sees the change instantly. |
18
+ | **Skill authors / contributors** — you want to edit the skills themselves | `git clone` + work in the checkout | Inside an agent-fleet checkout `--method symlink` is available, so editing an installed artifact edits the source. |
18
19
 
19
- All three converge on the same `guided-workspace-setup` skill — they only differ in how the source files reach your workspace. None is being deprecated.
20
+ `init` is the conversational front-end; `install` is the engine underneath it.
21
+ Both end up in the same place — the same manifest, the same install record, the
22
+ same three-way merge on the next `upgrade`. None of the paths is being deprecated.
23
+
24
+ ### Installing without an agent
25
+
26
+ ```bash
27
+ npx @chankov/agent-fleet install --agent pi --profile recommended --yes
28
+ npx @chankov/agent-fleet verify # read-only report: recorded × on disk × shipped
29
+ npx @chankov/agent-fleet upgrade --dry-run # what a refresh would change
30
+ ```
31
+
32
+ Profiles: `minimal`, `recommended`, `full`, `pi-fleet-core`, `hermes-plugins`,
33
+ `codex-bridge`. Pick individual artifacts instead with `--items skill:test-driven-development,persona:code-reviewer`.
34
+ Every verb takes `--dry-run` and `--json`. **Artifacts install as copies** —
35
+ refresh them with `agent-fleet upgrade`, which keeps local edits and writes an
36
+ incoming conflict beside your file as `<file>.new`.
20
37
 
21
38
  ## Optional: see the fleet in Hermes Desktop
22
39
 
@@ -74,15 +91,21 @@ The runtime contract is generated under `$HOME/.local/state/agent-fleet/codex-co
74
91
 
75
92
  ## Quick Start (Any Agent)
76
93
 
77
- ### 1. Clone the repository
94
+ The CLI installs into `claude-code`, `opencode`, and `pi` workspaces. For **any
95
+ other** agent it has no target paths to write to, so the skills are loaded by
96
+ hand — that is what this section covers.
97
+
98
+ ### 1. Get the files
78
99
 
79
100
  ```bash
101
+ npm install --save-dev @chankov/agent-fleet # or:
80
102
  git clone https://github.com/chankov/agent-fleet.git
81
103
  ```
82
104
 
83
- > Skip this step if you installed via npm — the package contents are already
84
- > in `node_modules/agent-fleet/`. Use that path wherever this guide refers to
85
- > "the agent-fleet repo."
105
+ > The npm path puts the package contents in `node_modules/@chankov/agent-fleet/`.
106
+ > Use whichever of the two you have wherever this guide says "the agent-fleet repo."
107
+ > Don't use `agent-fleet install` here — it writes to `.claude/`, `.opencode/`, or
108
+ > `.pi/`, which an agent outside those three won't read.
86
109
 
87
110
  ### 2. Choose a skill
88
111
 
@@ -1,10 +1,12 @@
1
1
  # npm install path
2
2
 
3
3
  The `@chankov/agent-fleet` package ships every skill, persona, slash command,
4
- and pi extension as installable content, plus a thin CLI that hands off to the
5
- LLM-driven `guided-workspace-setup` skill. The CLI never writes installable
6
- artifacts on its own — that decision (and the conversation around it) belongs
7
- to the coding agent.
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.
8
10
 
9
11
  ## Package name vs CLI name
10
12
 
@@ -43,7 +45,7 @@ inside your agent.
43
45
 
44
46
  ### First-class pi package
45
47
 
46
- For pi users who want package-native loading instead of copied/symlinked setup artifacts:
48
+ For pi users who want package-native loading instead of copied setup artifacts:
47
49
 
48
50
  ```bash
49
51
  # Project-scoped; writes .pi/settings.json
@@ -57,7 +59,7 @@ The pi package manifest exposes this repo's skills, pi runtime skills, lifecycle
57
59
 
58
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.
59
61
 
60
- The package also ships assets for the **experimental Linux Codex Remote-Control conductor** (`codex/`, `systemd/`, lifecycle/wrapper scripts, recipes, and runbook). Guided setup copies or links 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.
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.
61
63
 
62
64
  ## Commands
63
65
 
@@ -85,9 +87,8 @@ are always overwritten because they're scaffolding, not user data.
85
87
  After the setup workflow finishes its install pass, **the bootstrap files
86
88
  are removed by default** so they don't clutter your agent's slash-command
87
89
  list. Re-run `npx @chankov/agent-fleet init` whenever you want the runtime's
88
- setup command back. To keep them in place across runs, reply `keep`
89
- to the Step 9 confirmation prompt — the skill will record
90
- `keep-installer: true` in `.ai/agent-fleet-setup.md`.
90
+ setup command back, or pick the "keep the installer commands" option at the
91
+ setup flow's confirmation to leave them in place.
91
92
 
92
93
  ### How the skill finds the source package
93
94
 
@@ -116,47 +117,213 @@ never scans your filesystem for other agent-fleet repos — that would
116
117
  silently pick up forks, stale checkouts, or dev clones that aren't what
117
118
  you installed.
118
119
 
119
- The marker is removed by the same Step 10b cleanup that removes the
120
- slash commands.
120
+ The marker is removed by the same end-of-setup cleanup that removes the
121
+ slash commands (`agent-fleet cleanup-installer`).
121
122
 
122
123
  | Flag | Default | Purpose |
123
124
  |------|---------|---------|
124
125
  | `--agent <claude-code\|opencode\|pi>` | auto-detect | Skip the agent prompt |
125
- | `--method <copy\|symlink>` | `copy` | Default install method passed to the skill |
126
126
  | `--workspace <path>` | `cwd` | Target workspace |
127
127
  | `--launch` | off | Shell into the coding agent after init (best effort) |
128
128
 
129
129
  ```bash
130
130
  npx @chankov/agent-fleet init --agent claude-code
131
- npx @chankov/agent-fleet init --workspace ~/projects/foo --method symlink
131
+ npx @chankov/agent-fleet init --workspace ~/projects/foo
132
132
  ```
133
133
 
134
134
  ### `npx @chankov/agent-fleet doctor`
135
135
 
136
- Deterministic preflight scan — walks every install-target directory, lists
137
- broken symlinks and stale persona references, and offers fixes. Same scan
138
- that the runtime's Agent Fleet doctor command runs inside the agent.
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.
139
148
 
140
149
  | Flag | Default | Purpose |
141
150
  |------|---------|---------|
142
151
  | `--workspace <path>` | `cwd` | Target workspace |
143
- | `--dry-run` | off | Show findings; do not apply |
144
- | `--yes` / `-y` | off | Apply all suggested fixes without prompting |
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 |
145
163
 
146
164
  ```bash
147
165
  npx @chankov/agent-fleet doctor --workspace ~/projects/foo --dry-run
148
- npx @chankov/agent-fleet doctor -y
166
+ npx @chankov/agent-fleet doctor --fix
167
+ ```
168
+
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.
195
+
196
+ ```bash
197
+ npx @chankov/agent-fleet verify
198
+ npx @chankov/agent-fleet verify --agent pi --json
199
+ ```
200
+
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.
205
+
206
+ The manifest itself is generated from the repository tree, never hand-written:
207
+
208
+ ```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
149
211
  ```
150
212
 
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 |
239
+
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
+ ```
248
+
249
+ Installing into a brand-new repository takes one command and no LLM:
250
+
251
+ ```bash
252
+ npx @chankov/agent-fleet@latest install --agent pi --profile recommended --yes
253
+ ```
254
+
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`:
307
+
308
+ ```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
311
+ ```
312
+
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
+
151
318
  ### `npx @chankov/agent-fleet update`
152
319
 
153
320
  Reads the workspace's `.ai/agent-fleet-setup.md`, compares the recorded
154
321
  package version against the installed package version, and **re-installs the
155
322
  runtime's setup command** so it is always available after an update.
156
323
  `guided-workspace-setup` removes the installer command at the end of a run by
157
- default (Step 10b), so a workspace that has completed setup once would
158
- otherwise have no command to hand off to. The actual diff-aware refresh then
159
- runs inside the coding agent via that command.
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`.
160
327
 
161
328
  The agent and install method are recovered from the bootstrap marker written
162
329
  at init time; if that marker was cleaned up too, `update` auto-detects the
@@ -244,25 +411,35 @@ npm is the recommended path for most users. The other two stay supported:
244
411
 
245
412
  - **[Claude Code plugin marketplace](../README.md#quick-start)** — best UX
246
413
  inside Claude Code. Same skills, marketplace-managed updates.
247
- - **Git clone + symlinks** — best for skill authors and contributors. Clone
248
- the repo, run the setup command for your runtime, and choose `symlink` in Step 8. Updates
249
- flow through `git pull`. Symlinks need Developer Mode on Windows.
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`.
250
418
 
251
419
  All three paths converge on the same `guided-workspace-setup` skill — the
252
420
  difference is only in how the source files reach the workspace.
253
421
 
254
422
  ## CI usage
255
423
 
256
- `npx @chankov/agent-fleet init` is interactive by default (it prompts for
257
- the agent when detection is ambiguous). For CI, pass `--agent` explicitly:
424
+ Every verb is scriptable, and a complete install needs no agent and no model:
258
425
 
259
426
  ```bash
260
- npx --yes @chankov/agent-fleet@latest init --agent claude-code --method copy --workspace .
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
261
430
  ```
262
431
 
263
- `doctor` accepts `--yes` for non-interactive repair. Note that the
264
- LLM-driven setup flow is not CI-runnable by design — confirmation gates
265
- exist precisely so a human approves every write.
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.
436
+
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.
266
443
 
267
444
  ## Receiving update notifications
268
445
 
@@ -27,6 +27,38 @@ This more closely matches how Claude Code behaves in practice, while still allow
27
27
 
28
28
  ## Installation
29
29
 
30
+ ### Recommended — the `agent-fleet` CLI (project-scoped)
31
+
32
+ The CLI writes OpenCode's targets directly: `.opencode/skills/`, `.opencode/commands/`,
33
+ and `.opencode/agent/` (personas transformed to `mode: subagent` on the way in).
34
+
35
+ ```bash
36
+ cd /path/to/your-project
37
+
38
+ # Guided: bootstraps the installer command, then run /af-setup-agent-fleet in OpenCode
39
+ npx @chankov/agent-fleet init --agent opencode
40
+
41
+ # Or straight to it — no agent, no model, no prompts:
42
+ npx @chankov/agent-fleet install --agent opencode --profile recommended --yes
43
+ npx @chankov/agent-fleet verify --agent opencode
44
+ ```
45
+
46
+ Refresh after a package update with `npx @chankov/agent-fleet upgrade` — it
47
+ three-way merges against the version recorded in `.ai/agent-fleet-state.json`,
48
+ so your local edits survive and a genuine conflict lands beside your file as
49
+ `<file>.new` (exit `3`) instead of overwriting it. Artifacts install as **copies**;
50
+ `agent-fleet doctor --fix` repairs anything that goes missing or dangling.
51
+
52
+ Profiles: `minimal`, `recommended`, `full`. Narrow it with
53
+ `--items skill:code-review-and-quality,command:review,persona:code-reviewer`, and
54
+ preview any verb with `--dry-run`. Full reference: [npm-install.md](npm-install.md).
55
+
56
+ ### Manual global install (advanced)
57
+
58
+ Use this only when you want the skills available in **every** OpenCode session on
59
+ the machine regardless of project — the CLI installs per workspace and does not
60
+ write to `~/.config/opencode/`.
61
+
30
62
  1. Clone the repository:
31
63
 
32
64
  ```bash
@@ -60,9 +60,11 @@ same CLI flags would abort startup with duplicate registrations. So the harnesse
60
60
  - through the unified `justfile` interface — `just fleet`, `just fleet hub`, `just fleet peer <name>`, `just fleet team <preset>`, …
61
61
  - or directly — `pi -e .pi/harnesses/<name>/index.ts` (advanced use; you must compose safety/utilities yourself)
62
62
 
63
- When you consume this repo from another project, point `pi -e` at the harness file you
64
- want, or symlink that one directory into *its* `.pi/harnesses/` — never drop the harnesses
65
- into `.pi/extensions/`, and never load all of them at once. The supported multi-harness
63
+ When you consume this repo from another project, install the harness you want into
64
+ *its* `.pi/harnesses/` (`agent-fleet install --agent pi --items pi-harness:agent-hub`,
65
+ or the `pi-fleet-core` profile for the whole stack) and load it via that project's
66
+ `justfile` region, or point `pi -e` at the harness file directly — never drop the
67
+ harnesses into `.pi/extensions/`, and never load all of them at once. The supported multi-harness
66
68
  exception is loading `damage-control-continue` and `ask-user-remote` before `agent-hub` for a guarded hub session (see
67
69
  [pi-setup.md](pi-setup.md#optional-pi-extensions)).
68
70
 
@@ -82,10 +84,14 @@ just --list # shows the single public `fleet` entry point
82
84
 
83
85
  `just install` runs `npm install` for both dependency roots: `.pi/extensions/` for the
84
86
  utilities (`@modelcontextprotocol/sdk`, `typebox`) and `.pi/harnesses/` for the harnesses
85
- (`@sinclair/typebox`, `yaml`). The extension dependencies are also root production dependencies
86
- of the published `@chankov/agent-fleet` package. This is intentional: npm does not install a
87
- nested `.pi/extensions/package.json`, and Node resolves symlinked extensions from their real path
88
- inside the package. The `@mariozechner/pi-*` packages are provided by the pi runtime itself.
87
+ (`@sinclair/typebox`, `yaml`). That is the **clone** path. In a target workspace the
88
+ installer handles it: the manifests are copied in as companions, and `agent-fleet install
89
+ --allow-exec` runs `npm ci --prefix .pi/extensions` and `npm ci --prefix .pi/harnesses`
90
+ for you (without `--allow-exec` those two steps are printed in the plan and skipped, for
91
+ you to run by hand). The extension dependencies are also root production dependencies of
92
+ the published `@chankov/agent-fleet` package, so a pi-package install resolves them from
93
+ the package's real path. The `@mariozechner/pi-*` packages are provided by the pi runtime
94
+ itself.
89
95
 
90
96
  ---
91
97
 
@@ -105,9 +111,10 @@ surface, requirements, and per-extension upstream changes.
105
111
  ### Migration: retired hard-stop harness
106
112
 
107
113
  The former `.pi/harnesses/damage-control/` hard-stop harness and its standalone recipe
108
- are retired. Refresh pi harnesses with guided setup: it removes only an unchanged,
109
- setup-recorded copy (or an agent-fleet source symlink), preserves user-modified/unowned copies,
110
- and refreshes the managed `justfile` region. Use `damage-control-continue` for standalone and
114
+ are retired. Refresh pi harnesses with `agent-fleet upgrade` (or guided setup, which
115
+ calls it): removal is bound by the ownership rule, so only an unchanged, recorded copy
116
+ goes — user-modified and unowned copies are preserved, and the managed `justfile` region
117
+ is refreshed without touching recipes outside the sentinels. Use `damage-control-continue` for standalone and
111
118
  Agent Hub safety; missing child safety now fails closed instead of falling back or spawning
112
119
  unguarded.
113
120