@chankov/agent-fleet 0.0.2 → 0.0.4

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 (362) hide show
  1. package/.claude/commands/doctor-agent-fleet.md +1 -1
  2. package/.claude/commands/setup-agent-fleet.md +5 -5
  3. package/.opencode/commands/af-doctor-agent-fleet.md +2 -0
  4. package/.opencode/commands/af-setup-agent-fleet.md +1 -1
  5. package/.pi/agents/peers.yaml +4 -0
  6. package/.pi/agents/teams.yaml +2 -2
  7. package/.pi/harnesses/agent-hub/README.md +254 -18
  8. package/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  9. package/.pi/harnesses/agent-hub/delegate.ts +32 -9
  10. package/.pi/harnesses/agent-hub/drift-watchdog.js +165 -0
  11. package/.pi/harnesses/agent-hub/footer.ts +29 -0
  12. package/.pi/harnesses/agent-hub/helpers.ts +49 -0
  13. package/.pi/harnesses/agent-hub/index.ts +1269 -322
  14. package/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  15. package/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  16. package/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  17. package/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  18. package/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  19. package/.pi/harnesses/agent-hub/monitor-session-bridge.ts +11 -0
  20. package/.pi/harnesses/agent-hub/package.json +5 -4
  21. package/.pi/harnesses/agent-hub/research-retention.js +34 -0
  22. package/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  23. package/.pi/harnesses/agent-hub/run-budget.js +155 -0
  24. package/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  25. package/.pi/harnesses/agent-hub/spawn.ts +161 -94
  26. package/.pi/harnesses/agent-hub/version.ts +18 -0
  27. package/.pi/harnesses/ask-user-remote/README.md +2 -0
  28. package/.pi/harnesses/coms/README.md +21 -0
  29. package/.pi/harnesses/coms/index.ts +2 -0
  30. package/.pi/harnesses/coms/package.json +5 -4
  31. package/.pi/harnesses/coms/version.ts +18 -0
  32. package/.pi/harnesses/damage-control-continue/README.md +32 -31
  33. package/.pi/harnesses/damage-control-continue/index.ts +23 -9
  34. package/.pi/harnesses/damage-control-continue/package.json +5 -4
  35. package/.pi/harnesses/damage-control-continue/version.ts +18 -0
  36. package/.pi/harnesses/{damage-control/shared.ts → lib/damage-control-shared.ts} +20 -6
  37. package/.pi/prompts/doctor-agent-fleet.md +1 -1
  38. package/.pi/prompts/setup-agent-fleet.md +5 -5
  39. package/.versions/0.0.4/.claude/commands/build.md +44 -0
  40. package/.versions/0.0.4/.claude/commands/code-simplify.md +22 -0
  41. package/.versions/0.0.4/.claude/commands/design-agent.md +14 -0
  42. package/.versions/0.0.4/.claude/commands/doctor-agent-fleet.md +17 -0
  43. package/.versions/0.0.4/.claude/commands/orchestrate.md +112 -0
  44. package/.versions/0.0.4/.claude/commands/plan.md +16 -0
  45. package/.versions/0.0.4/.claude/commands/prime.md +22 -0
  46. package/.versions/0.0.4/.claude/commands/review.md +16 -0
  47. package/.versions/0.0.4/.claude/commands/setup-agent-fleet.md +25 -0
  48. package/.versions/0.0.4/.claude/commands/ship.md +72 -0
  49. package/.versions/0.0.4/.claude/commands/spec.md +15 -0
  50. package/.versions/0.0.4/.claude/commands/test.md +19 -0
  51. package/.versions/0.0.4/.claude/commands/webperf.md +32 -0
  52. package/.versions/0.0.4/.claude/orchestrate-teams.yaml +24 -0
  53. package/.versions/0.0.4/.opencode/commands/af-build.md +17 -0
  54. package/.versions/0.0.4/.opencode/commands/af-code-simplify.md +16 -0
  55. package/.versions/0.0.4/.opencode/commands/af-compound.md +16 -0
  56. package/.versions/0.0.4/.opencode/commands/af-design-agent.md +15 -0
  57. package/.versions/0.0.4/.opencode/commands/af-doctor-agent-fleet.md +17 -0
  58. package/.versions/0.0.4/.opencode/commands/af-orchestrate.md +112 -0
  59. package/.versions/0.0.4/.opencode/commands/af-plan.md +16 -0
  60. package/.versions/0.0.4/.opencode/commands/af-prime.md +22 -0
  61. package/.versions/0.0.4/.opencode/commands/af-review.md +15 -0
  62. package/.versions/0.0.4/.opencode/commands/af-setup-agent-fleet.md +15 -0
  63. package/.versions/0.0.4/.opencode/commands/af-ship.md +16 -0
  64. package/.versions/0.0.4/.opencode/commands/af-spec.md +16 -0
  65. package/.versions/0.0.4/.opencode/commands/af-test.md +21 -0
  66. package/.versions/0.0.4/.opencode/commands/af-webperf.md +32 -0
  67. package/.versions/0.0.4/.opencode/orchestrate-teams.yaml +24 -0
  68. package/.versions/0.0.4/.pi/agents/dispatch-policy.yaml +32 -0
  69. package/.versions/0.0.4/.pi/agents/model-profiles.yaml +20 -0
  70. package/.versions/0.0.4/.pi/agents/peers.yaml +146 -0
  71. package/.versions/0.0.4/.pi/agents/teams.yaml +39 -0
  72. package/.versions/0.0.4/.pi/damage-control-rules.yaml +297 -0
  73. package/.versions/0.0.4/.pi/extensions/agent-fleet-update-check/README.md +58 -0
  74. package/.versions/0.0.4/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
  75. package/{.pi/harnesses/damage-control → .versions/0.0.4/.pi/extensions/agent-fleet-update-check}/package.json +1 -1
  76. package/.versions/0.0.4/.pi/extensions/btw/README.md +118 -0
  77. package/.versions/0.0.4/.pi/extensions/btw/index.ts +917 -0
  78. package/.versions/0.0.4/.pi/extensions/btw/package.json +6 -0
  79. package/.versions/0.0.4/.pi/extensions/btw/state.js +179 -0
  80. package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/README.md +58 -0
  81. package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/index.ts +92 -0
  82. package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
  83. package/.versions/0.0.4/.pi/extensions/compact-and-continue/README.md +42 -0
  84. package/.versions/0.0.4/.pi/extensions/compact-and-continue/index.ts +120 -0
  85. package/.versions/0.0.4/.pi/extensions/compact-and-continue/package.json +6 -0
  86. package/.versions/0.0.4/.pi/extensions/mcp-bridge/README.md +46 -0
  87. package/.versions/0.0.4/.pi/extensions/mcp-bridge/index.ts +206 -0
  88. package/.versions/0.0.4/.pi/extensions/mcp-bridge/package.json +6 -0
  89. package/.versions/0.0.4/.pi/extensions/package-lock.json +1143 -0
  90. package/.versions/0.0.4/.pi/extensions/package.json +9 -0
  91. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/README.md +201 -0
  92. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/config.ts +198 -0
  93. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
  94. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/index.ts +248 -0
  95. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/package.json +6 -0
  96. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/providers.ts +214 -0
  97. package/.versions/0.0.4/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
  98. package/.versions/0.0.4/.pi/harnesses/agent-hub/README.md +798 -0
  99. package/.versions/0.0.4/.pi/harnesses/agent-hub/access-approval.ts +135 -0
  100. package/.versions/0.0.4/.pi/harnesses/agent-hub/artifacts.js +92 -0
  101. package/.versions/0.0.4/.pi/harnesses/agent-hub/backend-policy.js +153 -0
  102. package/.versions/0.0.4/.pi/harnesses/agent-hub/delegate.ts +386 -0
  103. package/.versions/0.0.4/.pi/harnesses/agent-hub/drift-watchdog.js +165 -0
  104. package/.versions/0.0.4/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
  105. package/.versions/0.0.4/.pi/harnesses/agent-hub/footer.ts +29 -0
  106. package/.versions/0.0.4/.pi/harnesses/agent-hub/helpers.ts +214 -0
  107. package/.versions/0.0.4/.pi/harnesses/agent-hub/index.ts +8045 -0
  108. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
  109. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
  110. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
  111. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
  112. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
  113. package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-session-bridge.ts +11 -0
  114. package/.versions/0.0.4/.pi/harnesses/agent-hub/package.json +7 -0
  115. package/.versions/0.0.4/.pi/harnesses/agent-hub/research-retention.js +34 -0
  116. package/.versions/0.0.4/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
  117. package/.versions/0.0.4/.pi/harnesses/agent-hub/return-contract.js +215 -0
  118. package/.versions/0.0.4/.pi/harnesses/agent-hub/run-budget.js +155 -0
  119. package/.versions/0.0.4/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
  120. package/.versions/0.0.4/.pi/harnesses/agent-hub/scope-gate.js +103 -0
  121. package/.versions/0.0.4/.pi/harnesses/agent-hub/spawn.ts +246 -0
  122. package/.versions/0.0.4/.pi/harnesses/agent-hub/version.ts +18 -0
  123. package/.versions/0.0.4/.pi/harnesses/ask-user-remote/README.md +18 -0
  124. package/.versions/0.0.4/.pi/harnesses/ask-user-remote/index.ts +293 -0
  125. package/.versions/0.0.4/.pi/harnesses/ask-user-remote/race-core.js +106 -0
  126. package/.versions/0.0.4/.pi/harnesses/coms/README.md +92 -0
  127. package/.versions/0.0.4/.pi/harnesses/coms/index.ts +1745 -0
  128. package/.versions/0.0.4/.pi/harnesses/coms/package.json +7 -0
  129. package/.versions/0.0.4/.pi/harnesses/coms/version.ts +18 -0
  130. package/.versions/0.0.4/.pi/harnesses/damage-control-continue/README.md +117 -0
  131. package/.versions/0.0.4/.pi/harnesses/damage-control-continue/index.ts +536 -0
  132. package/.versions/0.0.4/.pi/harnesses/damage-control-continue/package.json +7 -0
  133. package/.versions/0.0.4/.pi/harnesses/damage-control-continue/version.ts +18 -0
  134. package/.versions/0.0.4/.pi/harnesses/lib/damage-control-shared.ts +197 -0
  135. package/.versions/0.0.4/.pi/harnesses/lib/herdr-client.ts +458 -0
  136. package/.versions/0.0.4/.pi/harnesses/lib/herdr-presence.ts +288 -0
  137. package/.versions/0.0.4/.pi/harnesses/package-lock.json +35 -0
  138. package/.versions/0.0.4/.pi/harnesses/package.json +9 -0
  139. package/.versions/0.0.4/.pi/prompts/build.md +24 -0
  140. package/.versions/0.0.4/.pi/prompts/code-simplify.md +22 -0
  141. package/.versions/0.0.4/.pi/prompts/doctor-agent-fleet.md +15 -0
  142. package/.versions/0.0.4/.pi/prompts/plan.md +16 -0
  143. package/.versions/0.0.4/.pi/prompts/review.md +16 -0
  144. package/.versions/0.0.4/.pi/prompts/setup-agent-fleet.md +27 -0
  145. package/.versions/0.0.4/.pi/prompts/ship.md +17 -0
  146. package/.versions/0.0.4/.pi/prompts/spec.md +15 -0
  147. package/.versions/0.0.4/.pi/prompts/test.md +19 -0
  148. package/.versions/0.0.4/.pi/skills/bowser/SKILL.md +145 -0
  149. package/.versions/0.0.4/.version +1 -0
  150. package/.versions/0.0.4/agents/architect.md +23 -0
  151. package/.versions/0.0.4/agents/bowser.md +26 -0
  152. package/.versions/0.0.4/agents/builder.md +53 -0
  153. package/.versions/0.0.4/agents/code-reviewer.md +205 -0
  154. package/.versions/0.0.4/agents/deep-researcher.md +31 -0
  155. package/.versions/0.0.4/agents/documenter.md +18 -0
  156. package/.versions/0.0.4/agents/orchestrator.md +54 -0
  157. package/.versions/0.0.4/agents/plan-reviewer.md +60 -0
  158. package/.versions/0.0.4/agents/planner.md +69 -0
  159. package/.versions/0.0.4/agents/releaser.md +24 -0
  160. package/.versions/0.0.4/agents/researcher.md +28 -0
  161. package/.versions/0.0.4/agents/security-auditor.md +166 -0
  162. package/.versions/0.0.4/agents/test-engineer.md +151 -0
  163. package/.versions/0.0.4/agents/web-debugger.md +42 -0
  164. package/.versions/0.0.4/agents/web-performance-auditor.md +192 -0
  165. package/.versions/0.0.4/codex/CONDUCTOR.md +148 -0
  166. package/.versions/0.0.4/docs/ARCHITECTURE.md +210 -0
  167. package/.versions/0.0.4/docs/agent-fleet-setup.md +366 -0
  168. package/.versions/0.0.4/docs/claude-code-coms-bridge.md +103 -0
  169. package/.versions/0.0.4/docs/codex-remote-conductor.md +170 -0
  170. package/.versions/0.0.4/docs/coms-hermes-bridge.md +121 -0
  171. package/.versions/0.0.4/docs/getting-started.md +183 -0
  172. package/.versions/0.0.4/docs/npm-install.md +337 -0
  173. package/.versions/0.0.4/docs/opencode-setup.md +248 -0
  174. package/.versions/0.0.4/docs/pi-extensions.md +288 -0
  175. package/.versions/0.0.4/docs/pi-setup.md +463 -0
  176. package/.versions/0.0.4/docs/skill-anatomy.md +150 -0
  177. package/.versions/0.0.4/hermes/README.md +228 -0
  178. package/.versions/0.0.4/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  179. package/.versions/0.0.4/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  180. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-cap.test.py +15 -0
  181. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-discovery.test.py +19 -0
  182. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-envelope.test.py +13 -0
  183. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-forged-owner.test.py +11 -0
  184. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-lease-list.test.py +9 -0
  185. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-multihub.test.py +17 -0
  186. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-output.test.py +34 -0
  187. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +151 -0
  188. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter.test.py +39 -0
  189. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  190. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/plugin-api-validation.test.py +12 -0
  191. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  192. package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/review-live-wiring.red.test.py +22 -0
  193. package/.versions/0.0.4/hermes/skills/hub-conductor/SKILL.md +84 -0
  194. package/.versions/0.0.4/hermes/skills/hub-liaison/SKILL.md +84 -0
  195. package/.versions/0.0.4/hooks/SIMPLIFY-IGNORE.md +90 -0
  196. package/.versions/0.0.4/hooks/coms-stop-hook.mjs +73 -0
  197. package/.versions/0.0.4/hooks/hooks.json +14 -0
  198. package/.versions/0.0.4/hooks/session-start.sh +74 -0
  199. package/.versions/0.0.4/hooks/simplify-ignore.sh +302 -0
  200. package/.versions/0.0.4/justfile +256 -0
  201. package/.versions/0.0.4/references/accessibility-checklist.md +160 -0
  202. package/.versions/0.0.4/references/definition-of-done.md +67 -0
  203. package/.versions/0.0.4/references/fleet-coordination-patterns.md +151 -0
  204. package/.versions/0.0.4/references/observability-checklist.md +91 -0
  205. package/.versions/0.0.4/references/orchestration-patterns.md +370 -0
  206. package/.versions/0.0.4/references/performance-checklist.md +153 -0
  207. package/.versions/0.0.4/references/prompting-patterns.md +380 -0
  208. package/.versions/0.0.4/references/security-checklist.md +179 -0
  209. package/.versions/0.0.4/references/testing-patterns.md +236 -0
  210. package/.versions/0.0.4/scripts/codex-conductor.ts +41 -0
  211. package/.versions/0.0.4/scripts/codex-remote-control.ts +167 -0
  212. package/.versions/0.0.4/scripts/coms-claude-bridge.ts +286 -0
  213. package/.versions/0.0.4/scripts/coms-cli.ts +484 -0
  214. package/.versions/0.0.4/scripts/coms-hermes-bridge.ts +403 -0
  215. package/.versions/0.0.4/scripts/hermes-monitor-capability-runner.ts +25 -0
  216. package/.versions/0.0.4/scripts/hermes-monitor-scenario.ts +7 -0
  217. package/.versions/0.0.4/scripts/lib/claude-bridge-core.ts +100 -0
  218. package/.versions/0.0.4/scripts/lib/codex-conductor.ts +88 -0
  219. package/.versions/0.0.4/scripts/lib/codex-remote-control.ts +480 -0
  220. package/.versions/0.0.4/scripts/lib/coms-envelope.ts +539 -0
  221. package/.versions/0.0.4/scripts/lib/fake-herdr-server.ts +88 -0
  222. package/.versions/0.0.4/scripts/lib/herdr-layout.ts +263 -0
  223. package/.versions/0.0.4/scripts/lib/hermes-bridge-core.ts +238 -0
  224. package/.versions/0.0.4/scripts/lib/hermes-monitor-herdr.ts +28 -0
  225. package/.versions/0.0.4/scripts/lib/hermes-monitor-model.ts +9 -0
  226. package/.versions/0.0.4/scripts/lib/hermes-monitor-registry.ts +6 -0
  227. package/.versions/0.0.4/scripts/lib/hermes-monitor-socket.ts +118 -0
  228. package/.versions/0.0.4/scripts/lib/hermes-monitor-store.ts +31 -0
  229. package/.versions/0.0.4/scripts/lib/persona-banner.ts +62 -0
  230. package/.versions/0.0.4/scripts/lib/spawn-stagger.ts +101 -0
  231. package/.versions/0.0.4/scripts/lib/team-project.ts +184 -0
  232. package/.versions/0.0.4/scripts/lib/team-snapshot.ts +147 -0
  233. package/.versions/0.0.4/scripts/peer-banner.ts +40 -0
  234. package/.versions/0.0.4/scripts/team-snapshot.ts +238 -0
  235. package/.versions/0.0.4/scripts/team-up.ts +333 -0
  236. package/.versions/0.0.4/skills/_internal/grilling.md +11 -0
  237. package/.versions/0.0.4/skills/browser-testing-with-devtools/SKILL.md +352 -0
  238. package/.versions/0.0.4/skills/code-review-and-quality/SKILL.md +381 -0
  239. package/.versions/0.0.4/skills/compound-learning/SKILL.md +137 -0
  240. package/.versions/0.0.4/skills/context-engineering/SKILL.md +291 -0
  241. package/.versions/0.0.4/skills/deprecation-and-migration/SKILL.md +206 -0
  242. package/.versions/0.0.4/skills/designing-agents/SKILL.md +394 -0
  243. package/.versions/0.0.4/skills/designing-agents/pi-harness-authoring.md +222 -0
  244. package/.versions/0.0.4/skills/frontend-ui-engineering/SKILL.md +328 -0
  245. package/.versions/0.0.4/skills/git-workflow-and-versioning/SKILL.md +316 -0
  246. package/.versions/0.0.4/skills/guided-workspace-setup/SKILL.md +535 -0
  247. package/.versions/0.0.4/skills/guided-workspace-setup/companion-manifest.json +33 -0
  248. package/.versions/0.0.4/skills/idea-refine/SKILL.md +182 -0
  249. package/.versions/0.0.4/skills/idea-refine/examples.md +238 -0
  250. package/.versions/0.0.4/skills/idea-refine/frameworks.md +99 -0
  251. package/.versions/0.0.4/skills/idea-refine/refinement-criteria.md +113 -0
  252. package/.versions/0.0.4/skills/idea-refine/scripts/idea-refine.sh +15 -0
  253. package/.versions/0.0.4/skills/incremental-implementation/SKILL.md +287 -0
  254. package/.versions/0.0.4/skills/interview-me/SKILL.md +226 -0
  255. package/.versions/0.0.4/skills/orchestration-verification/SKILL.md +181 -0
  256. package/.versions/0.0.4/skills/peer-coms/SKILL.md +90 -0
  257. package/.versions/0.0.4/skills/performance-optimization/SKILL.md +350 -0
  258. package/.versions/0.0.4/skills/planning-and-task-breakdown/SKILL.md +236 -0
  259. package/.versions/0.0.4/skills/security-and-hardening/SKILL.md +461 -0
  260. package/.versions/0.0.4/skills/spec-driven-development/SKILL.md +245 -0
  261. package/.versions/0.0.4/skills/using-agent-skills/SKILL.md +199 -0
  262. package/.versions/0.0.4/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  263. package/.versions/0.0.4/vendor/agent-skills-upstream/LICENSE +21 -0
  264. package/.versions/0.0.4/vendor/agent-skills-upstream/README.md +11 -0
  265. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
  266. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
  267. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
  268. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
  269. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
  270. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
  271. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
  272. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
  273. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
  274. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
  275. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
  276. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
  277. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
  278. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
  279. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
  280. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
  281. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
  282. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
  283. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
  284. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
  285. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
  286. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
  287. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
  288. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
  289. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
  290. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
  291. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
  292. package/.versions/0.0.4/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
  293. package/CHANGELOG.md +53 -0
  294. package/README.md +103 -541
  295. package/agents/architect.md +1 -1
  296. package/agents/builder.md +1 -1
  297. package/agents/code-reviewer.md +1 -1
  298. package/agents/deep-researcher.md +3 -3
  299. package/agents/orchestrator.md +20 -11
  300. package/agents/plan-reviewer.md +3 -3
  301. package/agents/planner.md +1 -1
  302. package/agents/security-auditor.md +1 -1
  303. package/agents/test-engineer.md +11 -4
  304. package/bin/lib/validate-overrides.js +19 -0
  305. package/bin/snapshot-version.js +17 -1
  306. package/bin/sync-harness-versions.js +94 -0
  307. package/codex/CONDUCTOR.md +148 -0
  308. package/docs/ARCHITECTURE.md +210 -0
  309. package/docs/agent-fleet-setup.md +11 -0
  310. package/docs/claude-code-coms-bridge.md +10 -0
  311. package/docs/codex-remote-conductor.md +170 -0
  312. package/docs/coms-hermes-bridge.md +121 -0
  313. package/docs/getting-started.md +14 -0
  314. package/docs/npm-install.md +2 -0
  315. package/docs/pi-extensions.md +49 -14
  316. package/docs/pi-setup.md +12 -4
  317. package/hermes/README.md +228 -0
  318. package/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
  319. package/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
  320. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-cap.test.py +15 -0
  321. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-discovery.test.py +19 -0
  322. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-envelope.test.py +13 -0
  323. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-forged-owner.test.py +11 -0
  324. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-lease-list.test.py +9 -0
  325. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-multihub.test.py +17 -0
  326. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-output.test.py +34 -0
  327. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +151 -0
  328. package/hermes/plugins/agent-fleet-monitor/dashboard/adapter.test.py +39 -0
  329. package/hermes/plugins/agent-fleet-monitor/dashboard/dist/index.js +10 -0
  330. package/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
  331. package/hermes/plugins/agent-fleet-monitor/dashboard/plugin-api-validation.test.py +12 -0
  332. package/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
  333. package/hermes/plugins/agent-fleet-monitor/dashboard/review-live-wiring.red.test.py +22 -0
  334. package/hermes/skills/hub-conductor/SKILL.md +84 -0
  335. package/hermes/skills/hub-liaison/SKILL.md +84 -0
  336. package/justfile +106 -23
  337. package/package.json +17 -5
  338. package/scripts/codex-conductor.ts +41 -0
  339. package/scripts/codex-remote-control.ts +167 -0
  340. package/scripts/coms-cli.ts +311 -199
  341. package/scripts/coms-hermes-bridge.ts +2 -2
  342. package/scripts/lib/codex-conductor.ts +88 -0
  343. package/scripts/lib/codex-remote-control.ts +480 -0
  344. package/scripts/lib/coms-envelope.ts +51 -6
  345. package/scripts/lib/fake-herdr-server.ts +88 -0
  346. package/scripts/lib/herdr-layout.ts +18 -3
  347. package/scripts/lib/hermes-bridge-core.ts +4 -4
  348. package/scripts/lib/hermes-monitor-herdr.ts +28 -0
  349. package/scripts/lib/hermes-monitor-model.ts +9 -0
  350. package/scripts/lib/hermes-monitor-registry.ts +6 -0
  351. package/scripts/lib/hermes-monitor-socket.ts +118 -0
  352. package/scripts/lib/hermes-monitor-store.ts +31 -0
  353. package/scripts/lib/team-project.ts +85 -1
  354. package/scripts/team-up.ts +77 -18
  355. package/skills/designing-agents/SKILL.md +2 -2
  356. package/skills/designing-agents/pi-harness-authoring.md +26 -13
  357. package/skills/guided-workspace-setup/SKILL.md +131 -102
  358. package/skills/guided-workspace-setup/companion-manifest.json +33 -0
  359. package/skills/peer-coms/SKILL.md +9 -0
  360. package/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
  361. package/.pi/harnesses/damage-control/README.md +0 -65
  362. package/.pi/harnesses/damage-control/index.ts +0 -250
@@ -26,16 +26,20 @@ It maintains two files in the target's `.ai/` directory: `agent-fleet-overrides.
26
26
 
27
27
  ### 1. Detect interaction capability
28
28
 
29
- Determine which interaction mode this runtime supports. The mode is chosen by agent:
29
+ Determine which interaction mode this runtime supports, then drive **every** decision in this flow — doctor fixes, the Express question, the group menus, overrides, method, confirmation — through the shared interaction contract below:
30
30
 
31
- - **`claude-code` → `AskUserQuestion` questionnaires (primary).** Drive every Step 6 group through `AskUserQuestion` rather than printing a table and waiting for a free-text reply. Because the tool caps at 4 options per question and supports `multiSelect: true`, use this two-tier strategy:
32
- - **Quick path first.** For each group, ask one `AskUserQuestion` (multiSelect off) offering `Recommended set` / `Everything` / `Customise` / `Skip group`. Only when the user picks `Customise` do you drill in. This avoids questionnaire fatigue on the ~20-item Skills group.
33
- - **Customise drill-in.** Present the group's items as `AskUserQuestion` multiSelect prompts chunked by sub-category (the existing `Group` column), ≤ 4 options per question; a sub-category with > 4 items splits into sequential questions. Pre-selection still follows the Step 6 state rules (installed → pre-checked).
31
+ - **`pi` → the `ask_user` widget**, provided by the external `pi-ask-user` package; when it is absent, Step 5b bootstraps it first (install → reload → re-run) so this mode becomes available on the second pass. Because the Step 6 groups are large, prefer bootstrapping `pi-ask-user` over falling straight to the tabular fallback.
32
+ - **`claude-code` → `AskUserQuestion`.** Same contract; the tool caps at 4 options per question, so drill-in chunks are ≤ 4 options instead of ≤ 9.
33
+ - **`opencode` / any other runtime → its native select widget if supplied**, else the **tabular fallback** (defined at the end of Step 6): print the group table and take the picks as a text reply — always accepting the shortcuts `all`, `recommended`, `none`, `keep`, or a comma-separated list of item names/numbers.
34
34
 
35
- The selection semantics are **identical** to the tabular menu (unchecked installed item = remove, `recommended` adds `★` on top, etc.) — only the rendering differs.
36
- - **`pi` → native multi-select widget.** Provided by the external `pi-ask-user` package; when it is absent, Step 5b bootstraps it first (install → reload → re-run) so this mode becomes available on the second pass. Because the Step 6 groups are large, prefer bootstrapping `pi-ask-user` over falling straight to the tabular fallback.
37
- - **`opencode` / any other runtime → native multi-select widget if supplied**, else the tabular fallback below.
38
- - **Tabular fallback** (any runtime lacking the above) — print the group table (Step 6 format) and ask the user to reply with the picks. Always accept the shortcuts `all`, `recommended`, `none`, or a comma-separated list of item names/numbers.
35
+ **The interaction contract (widget modes).** One question = one `ask_user` / `AskUserQuestion` call whose **options carry the data** — never a markdown table pasted into the question or `context`:
36
+
37
+ - **Options are data.** Each option is `{title, description}`. The title is the pick itself — `<name>`, plus ` ★` when recommended and a short `[st]` state token (Step 6) when relevant, ≤ ~40 chars. The description says in plain words what the item is and what picking it does ("update available — refresh from source", "modified locally — refreshing overwrites your edits"). No status legend on widget screens — the words live in the descriptions; the token legend survives only in the tabular fallback.
38
+ - **Screen budget.** ≤ 8 short `context` lines and ≤ 9 options per call (≤ 4 on `AskUserQuestion`). A larger set splits into sequential chunks by sub-category, with `part i/n` in the question text. Anything longer — diffs, changelog deltas, the Step 9 plan — is printed as normal agent text *before* the call, and that call passes `displayMode: "inline"` so the printed material stays visible (the default overlay would cover it).
39
+ - **No pre-selection exists.** The `ask_user` multi-select starts with nothing checked and has no preselect parameter. Installed state is therefore conveyed by **counts in quick-screen option titles** and by per-item state words in drill-in descriptions — and **removal is never expressed by leaving an item unselected**. Removing is its own explicit "select items to remove" screen (Step 6).
40
+ - **Two-tier quick path.** Every Step 6 group opens with a single-select quick screen; multi-select drill-ins appear only behind `Customise` / `Remove some…`. This keeps a ~20-item group to one screen in the common case.
41
+ - **Freeform stays on.** Pass `allowFreeform: true` so the shortcuts (`all`, `recommended`, `none`, `keep`, comma-lists) keep working as typed replies with unchanged semantics.
42
+ - **Cancel is a no-op.** `esc`/cancel on a group, doctor, or override screen means "keep as-is / skip this screen" — never consent to install, refresh, or remove. Only the Step 9 confirm treats cancel as "do not apply".
39
43
 
40
44
  ### 2. Resolve inputs
41
45
 
@@ -69,11 +73,11 @@ Target map, relative to the workspace root:
69
73
  | Hooks *(claude-code only)* | `.claude/hooks/<name>`, registered in `.claude/settings.json` | — | — |
70
74
  | pi extensions | — | — | `.pi/extensions/<name>/` |
71
75
  | pi harnesses | — | — | `.pi/harnesses/<name>/` |
72
- | pi harness support | — | — | `justfile` (agent-fleet managed region), `scripts/*.ts`, `.pi/agents/*.yaml`, `.pi/damage-control-rules.yaml`, `.pi/harnesses/package.json` |
76
+ | pi harness support | — | — | `justfile` (managed region) plus `companion-manifest.json` runtime closure and existing pi support files |
73
77
 
74
78
  **Personas are generated, not copied.** The canonical persona format in `agents/*.md` is pi-flavored (agent-hub frontmatter: `models`, `thinking`, `delegate_depth`, `subagents`, …). For `pi` the file is installed as-is (copy or symlink). For `claude-code` and `opencode` the install runs the deterministic transformer instead — `node <source-root>/bin/cli.js transform-persona --agent <agent> --workspace <workspace> <name…>` — which translates `tools`/`model` to the target's vocabulary, adds `mode: subagent` for opencode, and drops the agent-hub-only keys. Never transform persona frontmatter by hand in this skill; the mapping lives in `bin/lib/transform-persona.js`, under test. Its `--list` flag prints the per-agent availability matrix (pi-only personas — `bowser`, `web-debugger`, `orchestrator` — are excluded for other agents and must not appear in their menu).
75
79
 
76
- The **pi harness support** row is not a menu group of its own — it is the set of shared files the harnesses need in order to launch (the `justfile` recipes, the `team-up` script, the peer/team YAML, the damage-control rules, and the harness `package.json` of runtime deps). These travel **with** the pi harnesses group (Step 6, group 6): whenever any harness is installed, refreshed, or removed, this support set is refreshed from source in the same pass. The `justfile` specifically is refreshed from the **current** source, so retired-harness recipes are pruned and new-harness recipes added automatically — see Step 6 and Step 10 for the merge and removal rules.
80
+ The **pi harness support** row is not a menu group of its own. Its authoritative runtime file list is `skills/guided-workspace-setup/companion-manifest.json`; load and validate that manifest before an apply, refresh, removal, or verification pass. It includes the managed `justfile`, Codex/Hermes/systemd directories, conductor runbooks, top-level runtime scripts, and their recursive `scripts/lib` imports. These travel **with** the pi harnesses group (Step 6, group 6): whenever any harness is installed, refreshed, or removed, apply the complete manifest closure in the same pass. The `justfile` specifically is refreshed from the **current** source, so retired-harness recipes are pruned and new-harness recipes added automatically. Guided setup copies or links repository assets only: it never runs `systemctl`, starts/stops Codex, pairs a device, reads auth state, copies credentials, or creates the external runtime workspace. The later operator-run `conductor-codex-setup` recipe copies canonical `codex/CONDUCTOR.md` into `$HOME/.local/state/agent-fleet/codex-conductor/workspace/AGENTS.md` with a validated absolute wrapper path.
77
81
 
78
82
  When neither the built-in map nor the agent's `*-setup.md` defines a path for a selected artifact, ask the user instead of guessing.
79
83
 
@@ -118,9 +122,9 @@ Also flag any YAML configs (`teams.yaml`, `peers.yaml`) that still reference rem
118
122
 
119
123
  Also flag malformed peer entries in `.pi/agents/peers.yaml`: field lines (`persona:`, `model:`, ...) sitting under a team heading before any `- name: ...` list item — the team-up launcher's minimal parser silently drops them, so the peer never spawns. **Advisory only**: report with the missing `- name: <peer>` suggestion, never rewrite the file yourself. (`agent-fleet doctor` runs this same check.)
120
124
 
121
- Also validate `.ai/agent-fleet-overrides.md` when it exists, against the schema in `docs/agent-fleet-setup.md`: unknown sections, unknown keys in known sections, invalid values for the mechanically parsed `agent-hub` keys (`thinking.*` levels, `delegate-depth.*`, `persona-gate`), `rules:` folders and `docs:` entry points that don't exist, and `## env` `required:` names that are neither set nor declared in the root `.env`. These findings are **advisory only** — report them in the table with fix "edit by hand", never edit the overrides file yourself. (`agent-fleet doctor` runs this same validation.)
125
+ Also validate `.ai/agent-fleet-overrides.md` when it exists, against the schema in `docs/agent-fleet-setup.md`: unknown sections, unknown keys in known sections, invalid values for the mechanically parsed `agent-hub` keys (`thinking.*` levels, `delegate-depth.*`, `persona-gate`), `rules:` folders and `docs:` entry points that don't exist, and `## env` `required:` names that are neither set nor declared in the root `.env`. These findings are **advisory only** — report them in the findings summary with fix "edit by hand", never edit the overrides file yourself. (`agent-fleet doctor` runs this same validation.)
122
126
 
123
- Present findings in a single table (keep it narrow — same widget constraint as Step 6/9: short `Issue`/`Fix` phrases, paths relative to the workspace, no overflowing cells):
127
+ Present the findings per the Step 1 interaction contract. **Widget mode:** print a 1–3 line text summary (counts per kind, plus the advisory findings — which are report-only and never offered as applyable options), then ask one multi-select — *"Which fixes should I apply now?"* — where each option's title is `<path> — <issue>` and its description is the proposed fix (`repoint → code-reviewer.md`, `delete broken link`), chunked per the Step 1 budget. An empty selection or cancel applies nothing. **Tabular fallback:** print the findings table instead (short `Issue`/`Fix` phrases, workspace-relative paths) and ask for the picks in text:
124
128
 
125
129
  | # | Path | Issue | Fix |
126
130
  |---|---|---|---|
@@ -128,7 +132,7 @@ Present findings in a single table (keep it narrow — same widget constraint as
128
132
  | 2 | `.pi/agents/red-team.md` | broken link, no replacement | delete |
129
133
  | 3 | `.pi/agents/teams.yaml` | refs `red-team` | rename → `security-auditor` |
130
134
 
131
- Then ask, multi-select: which fixes to apply now. Apply only the picked ones; record skipped items so the install menu can surface them again. Append a `## doctor-runs` line to `.ai/agent-fleet-setup.md` with the date, agent, phase (`preflight`), and `repaired` / `deleted` / `skipped` counts.
135
+ Either way, apply only the picked fixes; record skipped items so the install menu can surface them again. Append a `## doctor-runs` line to `.ai/agent-fleet-setup.md` with the date, agent, phase (`preflight`), and `repaired` / `deleted` / `skipped` counts.
132
136
 
133
137
  The doctor scan is also exposed standalone as `/doctor-agent-fleet` — running it outside a setup pass is this same scan-and-repair flow without the rest of the install menu.
134
138
 
@@ -148,49 +152,48 @@ From the Step 4 analysis, determine whether `pi-ask-user` is already available:
148
152
  4. Record the package under the `external-pi-packages` / `project-packages` line in `.ai/agent-fleet-setup.md` (same convention as Step 6's external-package handling) — do not copy files from `node_modules`.
149
153
  5. **Stop the pass here.** Print: *"`pi-ask-user` installed. Reload pi (restart the session or `/reload`), then re-run `/setup-agent-fleet` — the menu will then use native multi-select. Nothing else has been written to your workspace."* Do not continue to Step 6 on this pass: the tool only becomes callable after the reload.
150
154
 
151
- On the **re-run**, Step 4 finds `pi-ask-user` installed, this step is a no-op, and Step 6 renders every group as a true checkbox widget. In Step 6's External-pi-packages group, the already-installed `pi-ask-user` simply shows `installed · project package` and is pre-checked to keep — the bootstrap is not repeated. Do **not** bootstrap other external pi packages here; optional suggestions such as `pi-codex-image-gen` are offered only in Group 7 and installed only when the user selects them.
155
+ On the **re-run**, Step 4 finds `pi-ask-user` installed, this step is a no-op, and Step 6 runs on native `ask_user` screens. In Step 6's External-pi-packages group, the already-installed `pi-ask-user` simply counts toward `Keep as-is` (`installed · project package`) — the bootstrap is not repeated. Do **not** bootstrap other external pi packages here; optional suggestions such as `pi-codex-image-gen` are offered only in Group 7 and installed only when the user selects them.
152
156
 
153
157
  ### 6. Present the install menu
154
158
 
155
- Offer every installable artifact, split into the groups below. **Each group is its own multi-select prompt** so the user picks one screen at a time. On `claude-code` (per Step 1) each group is rendered as `AskUserQuestion` questionnaire chunks (quick-path, then ≤ 4-option drill-in) rather than one wide table — but the **selection semantics are identical** (unchecked installed item = remove, `recommended` adds `★` on top, etc.). The groups are deliberately broad — 7 total (4 shared + 3 pi-only), so a non-`pi` workspace sees only 4 screens. Several groups bundle more than one artifact type; within such a group, a leading `Group` column labels the sub-category and rows are ordered by it so the table still reads as labeled sections. Render every group's items as a markdown table using this fixed format:
159
+ Offer every installable artifact, split into the groups below. The groups are deliberately broad — 7 total (4 shared + 3 pi-only), so a non-`pi` workspace sees only 4 groups. Several groups bundle more than one artifact type; within such a group, a sub-category label (the `Group` value: lifecycle phase for Skills, `rw`/`ro`/`pi-only` for personas, …) orders the items and names the drill-in chunks.
156
160
 
157
- | Pick | Item | Group | St | Purpose |
158
- |---|---|---|---|---|
159
- | `[x]` / `[ ]` | `<name>` (append ` ★` when recommended) | sub-category (see each group) — omit the column for single-type groups | short status token (see legend) | one-line purpose, ≤ ~6 words |
161
+ **Item states.** Compute every candidate item's state first — states drive the quick-screen counts, the drill-in descriptions, and what confirming does:
160
162
 
161
- **Keep it narrow.** The `pi-ask-user` widget renders the table at fixed column widths, so wide cells force horizontal overflow — the user then has to zoom out, which makes the widget re-render and flicker. Render compact so the whole table fits a standard terminal width:
163
+ | Current state | `[st]` token | Surfaces where | What selecting does |
164
+ |---|---|---|---|
165
+ | `installed · up to date` | `ok` | counted in `Keep as-is`; listed on the remove screen | keep (no-op); removable only via the remove screen |
166
+ | `installed · outdated` (source newer than the installed copy; copy-mode only) | `upd` | counted in `Apply updates`; listed in Customise | refresh to current source |
167
+ | `installed · modified` (target diverged from source) | `mod` | listed in Customise — never auto-refreshed by `Apply updates` | refresh from source — description must warn **local edits will be overwritten**; leave unselected to preserve them |
168
+ | `installed · upgrade available` (recorded version != current; user copy still matches the recorded-version source) | `upd` | counted in `Apply updates` | clean refresh to the current-version source |
169
+ | `installed · conflicting upgrade` (recorded version != current; user modified the copy AND source changed upstream) | `cflt` | its own diff-then-ask exchange — never resolved by Express, `Apply updates`, or a plain chunk pick | nothing until the user accepts the overwrite after the three-way diff |
170
+ | `installed · removed upstream` (artifact gone in the current version) | `gone` | counted in `Apply updates` as a proposed deletion; always itemised in Step 9 | propose deletion in Step 10 (subject to the removal-scope rule); decline to keep the local copy |
171
+ | `not installed` | `—` | listed in Customise | install when selected |
172
+ | `not installed · new in this version` (artifact added between recorded and current) | `new` | listed in Customise; `★` when recommended | install when selected |
173
+ | `broken · skipped in preflight` (carried over from Step 5) | `brk` | counted in `Apply updates` as link cleanup; always itemised in Step 9 | remove the dangling link in Step 10; select it in Customise to attempt repair instead |
162
174
 
163
- - Use the short `St` token, never the long state name. Print the legend once, on a single line above the table: `St: ok=up to date · upd=update available · mod=modified locally · cflt=conflicting upgrade · gone=removed upstream · new=new this version · pkg=project package · — =not installed · brk=broken`.
164
- - Fold the recommendation mark into `Item` (append ` ★`) — do **not** add a separate `Rec` column.
165
- - Keep `Purpose` to a short phrase (truncate with `…` if needed); keep `Group` labels short (`UI`, `focus`, `safety`, `orch`, `msg`, `ext`, `skill`, `ref`, `hook`, `rw`, `ro`).
166
- - Keep the context preamble and the after-table prompt to short single lines — no multi-clause sentences that overflow the terminal.
175
+ **The Express question (one screen, before group 1).** After computing states, ask one single-select that can resolve the whole menu:
167
176
 
168
- **Pre-selection rule.** The `Pick` column is pre-ticked from the workspace's current state — not from preference. Every item is either pre-checked `[x]` (touched if confirmed) or pre-unchecked `[ ]` (left alone if confirmed):
177
+ - **Fresh workspace** (no install record): `Recommended ★ (n items)` — select every `★` item across the groups this agent sees / `Everything (m items)` / `Custom — group by group` / `Nothing — skip the menu`.
178
+ - **Existing workspace**: `Keep everything as-is (n installed)` / `Apply updates (k items)` — refresh every `upd`, propose the `gone`/`brk` cleanups, install nothing new / `Keep + add recommended ★ (adds j)` / `Custom — group by group`.
169
179
 
170
- | Current state | `St` token | Pre-check | What confirming will do |
171
- |---|---|---|---|
172
- | `installed · up to date` | `ok` | `[x]` | no-op (kept as-is) |
173
- | `installed · outdated` (source newer than the installed copy; copy-mode only) | `upd` | `[x]` | refresh to current source |
174
- | `installed · modified` (target diverged from source) | `mod` | `[x]` | refresh from source — **local edits will be overwritten**; untick to preserve them |
175
- | `installed · upgrade available` (recorded version != current; user copy still matches the recorded-version source) | `upd` | `[x]` | clean refresh to the current-version source |
176
- | `installed · conflicting upgrade` (recorded version != current; user modified the copy AND source changed upstream) | `cflt` | `[ ]` | nothing — show the three-way diff (recorded vs installed vs current) inline and ask before any write; tick only after the user accepts the overwrite |
177
- | `installed · removed upstream` (artifact gone in the current version) | `gone` | `[x]` | propose deletion in Step 10 (subject to the removal-scope rule); untick to keep the local copy |
178
- | `not installed` | `—` | `[ ]` | nothing — unless the user ticks it to install |
179
- | `not installed · new in this version` (artifact added between recorded and current) | `new` | `[ ]` | nothing — unless the user ticks it; marked `★` if recommended |
180
- | `broken · skipped in preflight` (carried over from Step 5) | `brk` | `[ ]` | remove the dangling link in Step 10; tick it to attempt repair instead |
181
- | `not installed · ★ recommended` | `—` | `[ ]` | nothing — unless the user ticks it or replies `recommended` |
182
-
183
- **The three-way diff for `conflicting upgrade`.** For each row in that state, compare:
180
+ An Express answer other than `Custom` skips all seven group screens and goes straight to Step 7 — with two exceptions Express can never resolve: (a) every `cflt` row still gets its per-row diff-then-ask exchange before Step 9, and (b) `gone`/`brk` cleanups are always itemised by name in the Step 9 summary, so nothing is deleted unseen. Mandatory pairings (group 6) apply to Express picks too. Cancel on the Express question = `Custom`.
181
+
182
+ **Per-group screens (the `Custom` path).** Each group runs at most three screens, all within the Step 1 budget:
183
+
184
+ 1. **Quick screen** (single-select). Fresh: `Recommended ★ (n)` / `Everything (m)` / `Customise` / `Skip group`. Existing: `Keep as-is (n installed)` / `Apply updates (k changed)` / `Customise` / `Remove some…`. Counts come from the state table; a group with nothing installed and nothing recommended may go straight to its Customise chunks.
185
+ 2. **Customise drill-in** (multi-select, only when picked). The group's items chunked by sub-category, ≤ 9 options per call (`part i/n`; ≤ 4 on `AskUserQuestion`). Titles: `<name> ★ [st]`. Descriptions: the purpose in ≤ ~6 words plus the state in plain words and its consequence (`mod` → "refreshing overwrites your local edits"). Selecting an item installs or refreshes it; **leaving an installed item unselected keeps it as-is — it does not remove it.** `cflt` rows are listed for visibility, but selecting one only queues its diff-then-ask exchange.
186
+ 3. **Remove screen** (multi-select, only via `Remove some…` or when the user asks to remove). Lists **only** installed items the removal-scope rule allows (current inventory + recorded / symlinked-to-source). Selecting an item marks it for removal in Step 9/10; an empty selection or cancel removes nothing. Items held by a mandatory pairing (`damage-control-continue` and `ask-user-remote` while `agent-hub` stays kept) are not listed; explain the pairing if the user asks for them. A source-retired `damage-control` hard-stop harness is a `gone` cleanup, not a selectable inventory item; apply the retired-artifact ownership rule below.
187
+
188
+ **The three-way diff for `conflicting upgrade`.** For each `cflt` row, print the diff as normal agent text, comparing:
184
189
 
185
190
  - *source @ recorded* — read from `<source-root>/.versions/<recorded-version>/<artifact-path>`
186
191
  - *installed copy* — read from the target path in the workspace
187
192
  - *source @ current* — read from `<source-root>/<artifact-path>`
188
193
 
189
- If the recorded snapshot is missing (unpublished local build, or a version older than the snapshot retention), fall back to "treat installed copy as canonical" — do not pretend a diff exists. Mention the missing snapshot in the row's status text so the user can decide.
190
-
191
- After the table, ask: *"Which items in this group? — adjust the picks, or reply `all` / `recommended` / `none` / `keep` (keep the pre-selection as shown)."* `recommended` ticks every `★` item **in addition to** the already-installed pre-selection (so the user never accidentally removes installed items by accepting recommendations). `keep` is the no-change shortcut.
194
+ Then ask a single-select with `displayMode: "inline"` (so the printed diff stays visible): `Overwrite with v<current>` / `Keep my copy`. Cancel = keep. If the recorded snapshot is missing (unpublished local build, or a version older than the snapshot retention), fall back to "treat installed copy as canonical" — do not pretend a diff exists; state the missing snapshot before asking.
192
195
 
193
- For an already-configured workspace, an **unchecked installed item means *remove it*** (subject to the removal-scope rule); a **checked one means *keep or update it***. An `St` token appears for every row — even `—` (not installed) — with the legend shown once above the table, so the user always sees an explicit state instead of inferring it from an empty checkbox.
196
+ **After every group** (and after an Express answer), restate the outcome in one line using the state vocabulary — e.g. *"Skills: keep `code-review-and-quality` (up to date), install `security-and-hardening` (recommended), remove `performance-optimization`."* — so the user can correct it before moving on. Freeform replies on any group screen keep the shortcut semantics: `recommended` selects every `★` item **in addition to** what is installed (it never implies removal), `keep` is the no-change shortcut, `none` skips the group, `all` selects everything.
194
197
 
195
198
  **Source availability filter — never substitute across agents.** Each row is offered only when the source file the **chosen agent** needs already exists in this repo. The source location is fixed per agent:
196
199
 
@@ -208,7 +211,7 @@ If the per-agent source is missing, the row is **not shown** — never silently
208
211
 
209
212
  Groups, in order. Groups 1–4 apply to every agent; groups 5–7 are shown **only when the agent is `pi`**.
210
213
 
211
- 1. **Skills** *(`Group` column = lifecycle phase)* — one screen for all skills, ordered by phase. The catalogue spans **two skill roots**: fleet-native `skills/` and the vendored upstream import `vendor/agent-skills-upstream/skills/` (see `docs/UPSTREAM-SKILLS.md`). When the same name exists in both, **the native `skills/` copy wins** and the vendored one is never offered as a separate row; names that exist only in the vendor root are offered from there. Record the resolved source root per skill in the install record so `doctor` and `update` know which copy (and which upstream commit) a workspace got:
214
+ 1. **Skills** *(sub-category = lifecycle phase)* — one group for all skills, chunked by phase in the drill-in. The catalogue spans **two skill roots**: fleet-native `skills/` and the vendored upstream import `vendor/agent-skills-upstream/skills/` (see `docs/UPSTREAM-SKILLS.md`). When the same name exists in both, **the native `skills/` copy wins** and the vendored one is never offered as a separate row; names that exist only in the vendor root are offered from there. Record the resolved source root per skill in the install record so `doctor` and `update` know which copy (and which upstream commit) a workspace got:
212
215
  - *Define / Plan* — `spec-driven-development` ★, `planning-and-task-breakdown` ★, `idea-refine`
213
216
  - *Build* — `incremental-implementation` ★, `test-driven-development` ★, `context-engineering`, `source-driven-development`, `frontend-ui-engineering`, `api-and-interface-design`
214
217
  - *Verify* — `browser-testing-with-devtools`, `debugging-and-error-recovery` ★
@@ -220,29 +223,29 @@ Groups, in order. Groups 1–4 apply to every agent; groups 5–7 are shown **on
220
223
 
221
224
  **Internal skill companions.** `skills/_internal/grilling.md` is not a menu row and has no `SKILL.md`; it is a shared helper for `idea-refine`, `spec-driven-development`, and `planning-and-task-breakdown`. Whenever any of those three skills is installed, kept, refreshed, or removed, apply the helper as a sibling at `<skills-target>/_internal/grilling.md` using the same copy/symlink method, record it as a companion rather than a selected skill, and keep it while any installed parent skill still references it.
222
225
 
223
- 2. **Agent personas** *(`Group` column = `rw` / `ro` / `pi-only`)* — one screen listing the **full availability matrix** for the chosen agent (never a hardcoded subset; `transform-persona --list --agent <agent>` is the authoritative roster). Read-only personas carry a read-only toolset and an explicit "Do NOT modify files." rule:
226
+ 2. **Agent personas** *(sub-category = `rw` / `ro` / `pi-only`)* — one group covering the **full availability matrix** for the chosen agent (never a hardcoded subset; `transform-persona --list --agent <agent>` is the authoritative roster). Read-only personas carry a read-only toolset and an explicit "Do NOT modify files." rule:
224
227
  - *rw* — `builder` ★, `test-engineer` ★, `documenter`, `planner` *(scoped: writes only the plan document in the plan directory; bash limited to read-only git inspection)*, `architect`, `releaser`
225
228
  - *ro* — `code-reviewer` ★, `security-auditor`, `plan-reviewer`, `researcher`, `deep-researcher`
226
229
  - *pi-only* *(shown only when the agent is `pi`)* — `bowser`, `web-debugger`, `orchestrator`
227
230
 
228
231
  For `claude-code`/`opencode`, installed rows are **generated artifacts** (see Step 3): record them with `transformed: true` in `## install-status`, and compute their status by comparing the installed file against `transform(current source)` — and for upgrades against `transform(.versions/<recorded>/agents/<name>.md)` — never against the raw canonical source, whose bytes legitimately differ from the generated output.
229
- 3. **Commands / prompts** *(single-type — no `Group` column)* — mapped to the chosen agent; items without a per-agent source are filtered out, no cross-tool substitution. Full candidate list: `spec` ★, `plan` ★, `build` ★, `test` ★, `review` ★, `orchestrate` ★, `compound`, `code-simplify`, `ship`, `design-agent`, `prime`. The actual menu shows only items whose per-agent source file exists — for example, `.pi/prompts/design-agent.md` and `.pi/prompts/prime.md` are absent, so neither is offered when the agent is `pi`; and `orchestrate` has a source for `claude-code` (`.claude/commands/orchestrate.md`) and `opencode` (`.opencode/commands/af-orchestrate.md`) but **not** `pi` (no `.pi/prompts/orchestrate.md`), so the existing source-availability filter surfaces it for claude-code + opencode and hides it for pi automatically. `compound` follows the same pattern (`.claude/commands/compound.md` / `.opencode/commands/af-compound.md`, no pi prompt — the agent-hub harness ships its own `/compound` command); when `compound` is selected, recommend the `compound-learning` skill alongside it. *(`setup` and `doctor` are installer-only — never offered, since they live in the source agent-fleet repo and act on target workspaces from there.)*
232
+ 3. **Commands / prompts** *(single-type — no sub-category)* — mapped to the chosen agent; items without a per-agent source are filtered out, no cross-tool substitution. Full candidate list: `spec` ★, `plan` ★, `build` ★, `test` ★, `review` ★, `orchestrate` ★, `compound`, `code-simplify`, `ship`, `design-agent`, `prime`. The actual menu shows only items whose per-agent source file exists — for example, `.pi/prompts/design-agent.md` and `.pi/prompts/prime.md` are absent, so neither is offered when the agent is `pi`; and `orchestrate` has a source for `claude-code` (`.claude/commands/orchestrate.md`) and `opencode` (`.opencode/commands/af-orchestrate.md`) but **not** `pi` (no `.pi/prompts/orchestrate.md`), so the existing source-availability filter surfaces it for claude-code + opencode and hides it for pi automatically. `compound` follows the same pattern (`.claude/commands/compound.md` / `.opencode/commands/af-compound.md`, no pi prompt — the agent-hub harness ships its own `/compound` command); when `compound` is selected, recommend the `compound-learning` skill alongside it. *(`setup` and `doctor` are installer-only — never offered, since they live in the source agent-fleet repo and act on target workspaces from there.)*
230
233
 
231
234
  **`orchestrate` carries a team-config companion.** `orchestrate-teams.yaml` (the named-team roster the `/orchestrate` command reads) is not its own menu row — it is a companion of the `orchestrate` command (same idea as the pi harness `justfile` companion). Whenever `orchestrate` is installed/kept/removed, install/remove the agent's team config from source in the same pass — `.claude/orchestrate-teams.yaml` for claude-code, `.opencode/orchestrate-teams.yaml` for opencode. Treat it as a normal versioned artifact for the Step 6 status tokens: a user-edited copy is `mod`/`cflt` and gets the three-way-diff treatment, never a silent clobber of their team definitions. **Removal safety:** when `orchestrate` is removed, the team config is removed **only** if it still matches the shipped source (unedited); a user-edited `orchestrate-teams.yaml` is preserved and listed under "Skipped — user-modified" rather than deleted, so custom team definitions survive an uninstall.
232
- 4. **References & Hooks** *(`Group` column = `reference` / `hook`)* — one screen for the shared non-agent-specific artifacts:
235
+ 4. **References & Hooks** *(sub-category = `reference` / `hook`)* — one group for the shared non-agent-specific artifacts:
233
236
  - *reference* — testing, performance, security, accessibility checklists *(offered for every agent)*
234
237
  - *hook* — `session-start.sh`, `simplify-ignore.sh` (+ `simplify-ignore-test.sh`) *(**claude-code only** — hooks register into `.claude/settings.json`, and neither `docs/opencode-setup.md` nor `docs/pi-setup.md` defines a hook install path)*
235
238
 
236
239
  The **hook** sub-category is shown only when the agent is `claude-code`. For `opencode`/`pi` this group degrades to **References only** — no hook rows.
237
- 5. **pi extensions & runtime skills** *(pi only; `Group` column = `extension` / `runtime-skill`)* — always-on once installed:
240
+ 5. **pi extensions & runtime skills** *(pi only; sub-category = `extension` / `runtime-skill`)* — always-on once installed:
238
241
  - *extension* — `mcp-bridge`, `chrome-devtools-mcp`, `compact-and-continue`, `agent-fleet-update-check` ★, `btw`, `pi-voice-stt`
239
242
  - *runtime-skill* — `bowser`
240
243
 
241
244
  **Two complementary browser stacks.** `bowser` (runtime-skill, here) and `chrome-devtools-mcp` (extension, here) cover different browser needs and pair well — `bowser`/`playwright-cli` for headless, parallel, delegatable automation; `chrome-devtools-mcp` (driven by the `web-debugger` persona in group 2) for interactive headful debugging with live DOM/console/network. When the user wants full browser coverage, recommend both; when they only want one, fit it to the use case (automation vs interactive debug). See `docs/pi-extensions.md` ("Two browser stacks — when to use which").
242
245
 
243
- **`bowser` external CLI dependency.** The `bowser` runtime-skill drives the external **Playwright Agent CLI** (`playwright-cli`), which is **not** an agent-fleet artifact and is not copied from this repo (same idea as the `pi-ask-user` external package). Whenever `bowser` is ticked (installed or kept), check whether `playwright-cli` is on `PATH` (`playwright-cli --help`, or `npx playwright-cli --help`). If it is missing, tell the user and offer the install — `npm install -g @playwright/cli@latest` (global) or note the `npx playwright-cli` ad-hoc fallback — then surface it in the Step 9 plan as an external dependency, not a file write. Record it under the same `external-pi-packages` / `project-packages` convention in `.ai/agent-fleet-setup.md` so re-runs re-verify it. Do not silently install a global package without the user's confirmation, and never block the `bowser` install on it — a missing CLI is a warning, not a hard stop. Install reference: <https://playwright.dev/agent-cli/installation>.
246
+ **`bowser` external CLI dependency.** The `bowser` runtime-skill drives the external **Playwright Agent CLI** (`playwright-cli`), which is **not** an agent-fleet artifact and is not copied from this repo (same idea as the `pi-ask-user` external package). Whenever `bowser` is selected (installed or kept), check whether `playwright-cli` is on `PATH` (`playwright-cli --help`, or `npx playwright-cli --help`). If it is missing, tell the user and offer the install — `npm install -g @playwright/cli@latest` (global) or note the `npx playwright-cli` ad-hoc fallback — then surface it in the Step 9 plan as an external dependency, not a file write. Record it under the same `external-pi-packages` / `project-packages` convention in `.ai/agent-fleet-setup.md` so re-runs re-verify it. Do not silently install a global package without the user's confirmation, and never block the `bowser` install on it — a missing CLI is a warning, not a hard stop. Install reference: <https://playwright.dev/agent-cli/installation>.
244
247
 
245
- **`pi-voice-stt` provider configuration.** The `pi-voice-stt` extension (Alt+S voice dictation) is a **gated no-op until a provider is configured** — installing the files alone binds no hotkey. Whenever it is ticked (installed or kept) **and** the workspace has no `.ai/stt.json` yet, offer (don't force) to configure it now; the user may skip and run `/stt doctor` later. The config write is a **companion** of the extension (same idea as the `orchestrate-teams.yaml` companion), applied in Step 10, not a separate menu row. When the user opts in, ask the provider:
248
+ **`pi-voice-stt` provider configuration.** The `pi-voice-stt` extension (Alt+S voice dictation) is a **gated no-op until a provider is configured** — installing the files alone binds no hotkey. Whenever it is selected (installed or kept) **and** the workspace has no `.ai/stt.json` yet, offer (don't force) to configure it now; the user may skip and run `/stt doctor` later. The config write is a **companion** of the extension (same idea as the `orchestrate-teams.yaml` companion), applied in Step 10, not a separate menu row. When the user opts in, ask the provider:
246
249
  - **Azure Speech** (`type: azure`) — collect the resource endpoint and (optionally) candidate `locales` for per-phrase language identification, e.g. `["bg-BG","en-US"]`. Default env var names: `AZURE_SPEECH_KEY`, `AZURE_SPEECH_ENDPOINT`.
247
250
  - **Azure OpenAI Whisper** (`type: azure-openai`) — Whisper on Azure OpenAI / Azure AI Foundry; best for mixed-language speech. Collect the resource `endpoint` and the Whisper `deployment` name, plus `apiVersion` (default `2024-10-21`). **Use the legacy data-plane host `https://<resource>.openai.azure.com` (or `…cognitiveservices.azure.com`), not the Foundry `…services.ai.azure.com` host** — audio transcription 404s on the Foundry `/openai/v1` endpoint. Default env vars: `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT` — but a multi-service Azure AI Services resource can reuse the Speech key, so offer `apiKeyEnv: AZURE_SPEECH_KEY` when the user says the key is shared.
248
251
  - **OpenAI-compatible** (`type: openai`) — collect `baseUrl` (default `https://api.openai.com/v1`; a `http://127.0.0.1:*/v1` loopback is allowed for local whisper) and `model` (default `whisper-1`). Default env var: `OPENAI_API_KEY`.
@@ -252,21 +255,22 @@ Groups, in order. Groups 1–4 apply to every agent; groups 5–7 are shown **on
252
255
  2. `<workspace>/.env` (repo root, auto-loaded by the `justfile`'s `dotenv-load`) — append the referenced secret variables as **empty placeholders** only if absent (`AZURE_SPEECH_KEY=`, `AZURE_SPEECH_ENDPOINT=`, or `OPENAI_API_KEY=`); never overwrite an existing value, and tell the user to fill them in. Ensure `.env` is gitignored — add a `.env` line to the workspace `.gitignore` if no `.env`/`.env*` rule already covers it.
253
256
 
254
257
  Record `.ai/stt.json` (and the `.env` keys touched) in `## install-status`. On a later removal of `pi-voice-stt`, delete `.ai/stt.json` **only** if it still matches what setup wrote (unedited; a user-edited config is preserved and listed under "Skipped — user-modified"), and **never** delete `.env`, its values, or the `.gitignore` line. Secrets in `.env` outlive the extension.
255
- 6. **pi harnesses** *(pi only; `Group` column = harness category — install many, load through the explicit recipes; `just hub` stacks `damage-control-continue` + `ask-user-remote` before `agent-hub`)* — one screen for all harnesses:
258
+ 6. **pi harnesses** *(pi only; sub-category = harness category — install many, load through the explicit recipes; `just hub` stacks `damage-control-continue` + `ask-user-remote` before `agent-hub`)* — one group for all harnesses:
256
259
  - *orchestration* — `agent-hub`, `ask-user-remote`
257
- - *safety* — `damage-control`, `damage-control-continue`
260
+ - *safety* — `damage-control-continue`
258
261
  - *messaging* — `coms`
259
262
 
260
- **Mandatory pairing: `agent-hub` ⇒ `damage-control` + `damage-control-continue` + `ask-user-remote`.** When `agent-hub` is ticked (installed or kept), auto-tick **both** damage-control variants and `ask-user-remote` in the same pass and refuse to untick any of them while `agent-hub` stays selected — explain that the hub's `just hub` main session loads `damage-control-continue` and `ask-user-remote` before `agent-hub` (so recipes pointing at missing harnesses would fail to launch or lose the `ask_user` handoff path), and the hub re-loads a guardrail into every spawned subagent as their only protection: `damage-control` (hard-stop) into specialists, `damage-control-continue` into research helpers. Removing either guardrail leaves part of the session unguarded; removing `ask-user-remote` makes agent-hub's `askUserAvailable` probe omit `ask_user` from the dispatcher tools. These harnesses without `agent-hub` remain freely selectable.
263
+ **Mandatory pairing: `agent-hub` ⇒ `damage-control-continue` + `ask-user-remote`.** When `agent-hub` is selected (installed or kept), auto-include `damage-control-continue` and `ask-user-remote` in the same pass, state the auto-inclusion in the restate line, and keep both off the remove screen while `agent-hub` stays selected. The `just hub` main session loads both before `agent-hub`; the hub then loads `damage-control-continue` into every native specialist, researcher, and nested delegate. Removing it leaves child dispatch fail-closed; removing `ask-user-remote` makes the hub's `askUserAvailable` probe omit `ask_user` from dispatcher tools. Either harness remains freely selectable without `agent-hub`.
261
264
 
262
- **Harness companions (refreshed with the group, not separate rows).** A harness directory does not run on its own — the launch recipes live in the `justfile`, and several harnesses shell out to support files. So whenever **any** harness in this group is ticked (installed/kept) or unticked (removed), refresh its companions from source in the same pass — they are not shown as their own menu rows:
263
- - `justfile` — the `just hub` / `just team-up` / `just conductor` / `just safe-coms` launch recipes plus private helpers.
264
- - `scripts/team-up.ts` — used by the `team-up` recipe.
265
+ **Retired hard-stop cleanup.** `damage-control` (the former hard-stop harness) is no longer inventory and must never be installed or offered. On an upgrade, classify an existing `.pi/harnesses/damage-control/` as an upstream-removed (`gone`) artifact. Propose removal only when it is recorded in `## install-status` and still matches the recorded-version snapshot, or is a symlink whose target path is inside the agent-fleet source root (including a now-broken link to the retired source path). Preserve a user-modified regular copy or any unrecorded/unowned copy as `Skipped — user-modified` / `Skipped — not owned`; never delete it silently. Itemise the cleanup in Step 9, and remove its install-status row only when the owned artifact is actually removed.
266
+
267
+ **Harness companions (refreshed with the group, not separate rows).** A harness directory does not run on its own — the launch recipes live in the `justfile`, and several harnesses shell out to support files. So whenever **any** harness in this group is installed, kept, or removed, refresh its companions from source in the same pass — they are not shown as their own menu rows:
268
+ - Every path in `companion-manifest.json` — the sole list for Codex/Hermes/systemd directories, conductor docs, top-level runtime scripts, and recursive `scripts/lib` imports. Do not recreate a partial hand-maintained list.
265
269
  - `.pi/agents/peers.yaml`, `.pi/agents/teams.yaml`, and the peer personas they name (e.g. `architect`, `releaser`) — read by `team-up`.
266
270
  - `.pi/damage-control-rules.yaml` — the rule set the damage-control harness loads.
267
271
  - `.pi/harnesses/package.json` (+ `npm install --prefix .pi/harnesses`) — the harness runtime deps (`yaml`, `@sinclair/typebox`).
268
272
 
269
- **The `justfile` is the one that goes stale on upgrade.** Refresh it from the **current** source, never leave the installed copy as-is: the source `justfile` is canonical, so refreshing it prunes recipes for harnesses retired since the recorded version and adds recipes for new ones. A workspace whose harness set changed between versions but whose `justfile` was left untouched is the exact failure this rule prevents — `just --list` keeps recipes pointing at deleted `.pi/harnesses/<name>/` dirs and lacks recipes for the new harnesses. Treat the `justfile` as a normal versioned artifact subject to the Step 6 status rules: it carries its own `St` token in the menu's after-table restate line (`ok`/`upd`/`mod`/`cflt`), and a user-edited `justfile` gets the same three-way diff and pre-unchecked `cflt` treatment as any other modified file — never a silent clobber. The `.versions/<recorded>/justfile` snapshot is the recorded-side of that diff.
273
+ **The `justfile` is the one that goes stale on upgrade.** Refresh it from the **current** source, never leave the installed copy as-is: the source `justfile` is canonical, so refreshing it prunes recipes for harnesses retired since the recorded version and adds recipes for new ones. A workspace whose harness set changed between versions but whose `justfile` was left untouched is the exact failure this rule prevents — `just --list` keeps recipes pointing at deleted `.pi/harnesses/<name>/` dirs and lacks recipes for the new harnesses. Treat the `justfile` as a normal versioned artifact subject to the Step 6 status rules: it carries its own state (`ok`/`upd`/`mod`/`cflt`) in the group's restate line, and a user-edited `justfile` gets the same `cflt` diff-then-ask treatment as any other modified file — never a silent clobber. The `.versions/<recorded>/justfile` snapshot is the recorded-side of that diff.
270
274
 
271
275
  **The `justfile` managed region.** The source `justfile` wraps its recipes between `# >>> agent-fleet:harnesses … >>>` and `# <<< agent-fleet:harnesses <<<` sentinels. Only that region is agent-fleet'. When refreshing into a target that has its own recipes outside the sentinels, replace **only** the managed region (preserving the user's recipes); if the target has no sentinels but every recipe matches the recorded-version `justfile` snapshot (i.e. the user never edited it), it is wholly ours — refresh the whole file, re-introducing the sentinels. If the target has no sentinels **and** has diverged from the snapshot, treat it as `mod`/`cflt` and show the diff before touching it. When merging into a `justfile` that already declares its own `set dotenv-load`, drop that line from the region rather than duplicating the setting (just errors on a repeated setting).
272
276
 
@@ -274,26 +278,34 @@ Groups, in order. Groups 1–4 apply to every agent; groups 5–7 are shown **on
274
278
 
275
279
  Defaults differ by workspace state:
276
280
 
277
- - **Fresh workspace (no install record).** Pre-selection is empty; replying `recommended` ticks the `★` items across groups 1–4. pi groups (5–7) stay empty unless the agent is `pi`.
278
- - **Existing workspace.** Pre-selection mirrors the install record — every `installed · *` row starts `[x]`. Replying `keep` accepts that pre-selection unchanged; replying `recommended` adds the `★` items on top of what is already installed (it never silently unticks installed items).
281
+ - **Fresh workspace (no install record).** Nothing is installed, so quick screens open on their fresh variant; `Recommended ★` — on Express or on a group quick screen — selects the `★` items across groups 1–4, plus 5–7 when the agent is `pi`.
282
+ - **Existing workspace.** The install record feeds the state table: every `installed · *` item counts toward `Keep as-is` and appears with its state in the drill-ins. `keep` (or the `Keep as-is` option) leaves everything untouched; `recommended` adds the `★` items on top of what is already installed — it never implies removing anything.
279
283
 
280
- Because groups now span sub-categories, the shortcuts (`all`, `recommended`, `none`, `keep`) and any comma-separated picks apply to the **whole group screen**, across every sub-category in it. After every group, restate the picks in one line so the user can correct them before moving on. The restate line uses the same status vocabulary — for example: *"Skills: keep `code-review-and-quality` (up to date), install `security-and-hardening` (recommended), remove `performance-optimization`."*
284
+ Because groups span sub-categories, the freeform shortcuts (`all`, `recommended`, `none`, `keep`) and any comma-separated picks apply to the **whole group**, across every chunk in it.
281
285
 
282
- **External pi package status.** For Group 7, treat each row as an external pi package rather than an agent-fleet artifact. In the rendered table the `St` cell is `pkg` for any installed scope (state the scope in the after-table restate line) and `—` when not installed. Apply the same decision logic to every external package row, with package-specific install commands:
286
+ **External pi package status.** For Group 7, treat each item as an external pi package rather than an agent-fleet artifact. Its title token is `pkg` for any installed scope (state the scope in the restate line) and `—` when not installed. Apply the same decision logic to every external package item, with package-specific install commands:
283
287
 
284
- - `installed · bundled by @chankov/agent-fleet` — only for packages actually exposed by this repo's pi manifest (currently `pi-ask-user`). Leave the row unchecked/no-op and do not add a duplicate package entry. Do **not** show `pi-codex-image-gen` as bundled by this repo.
285
- - `installed · project package` — `.pi/settings.json`/`pi list` already records the package spec (for example `npm:pi-ask-user` or `npm:pi-codex-image-gen`); pre-check it to keep.
286
- - `installed · global package` — user settings already provide the package; leave project install unchecked unless the user wants a project-scoped pin.
288
+ - `installed · bundled by @chankov/agent-fleet` — only for packages actually exposed by this repo's pi manifest (currently `pi-ask-user`). Treat the item as a no-op keep and do not add a duplicate package entry. Do **not** show `pi-codex-image-gen` as bundled by this repo.
289
+ - `installed · project package` — `.pi/settings.json`/`pi list` already records the package spec (for example `npm:pi-ask-user` or `npm:pi-codex-image-gen`); count it toward `Keep as-is`.
290
+ - `installed · global package` — user settings already provide the package; do not add a project install unless the user wants a project-scoped pin.
287
291
  - `not installed` — show the project-scoped command for the row. Use `pi install -l npm:pi-ask-user` for `pi-ask-user` and `pi install -l npm:pi-codex-image-gen` for `pi-codex-image-gen`. Mention the global form (`pi install npm:<package>`) only when the user chose a global pi setup.
288
292
 
289
293
  When an external pi package is selected during clone/symlink or manual pi setup — or when `pi-ask-user` is installed by the Step 5b bootstrap — record that package's npm spec under an `external-pi-packages` / `project-packages` line in `.ai/agent-fleet-setup.md`; do not copy files from `node_modules` or this repo. When deselected later, remove only the package entry this setup owns (for example the project-scoped `.pi/settings.json` entry it recorded). A setup-recorded external package spec such as `npm:pi-codex-image-gen` is governed by this Group 7 ownership rule. Never remove a user-owned global package, an unrecorded project package, or a package entry that predates the install record; surface those as skipped/not owned instead.
290
294
 
291
- **Removal scope — what "unchecked = remove" actually touches.** A target item is eligible for removal only when **both** are true:
295
+ **Removal scope — what the remove screen (and `gone`/`brk` cleanup) may touch.** A target item is eligible for removal only when **both** are true:
296
+
297
+ 1. **It is part of the current agent-fleet inventory, or is an owned artifact removed upstream.** Current inventory names match artifacts shipped in the source repo's canonical trees (`skills/`, `vendor/agent-skills-upstream/skills/`, `agents/`, `.claude/commands/`, `.pi/prompts/`, `.pi/extensions/`, `.pi/harnesses/`, `.pi/skills/`, `references/`, `hooks/`). A source-retired artifact is eligible only as a `gone` cleanup when its old path is present in the recorded-version snapshot; this exception currently covers the retired `.pi/harnesses/damage-control/` hard-stop harness. External pi packages are governed by the Group 7 ownership rule above. Other out-of-inventory items are never proposed for removal.
298
+ 2. **Ownership is proven.** For current inventory, `## install-status` records the item or it is a symlink into the source root. For a source-retired artifact, it must be recorded and byte-match the recorded-version snapshot, or be a symlink whose stored target is inside the source root (a broken symlink caused by retirement still counts). A differing regular copy is user-modified and must be preserved.
299
+
300
+ If a candidate fails either test, list it once under `Skipped — user-modified` or `Skipped — not owned by agent-fleet` in the Step 9 plan and leave it alone. Settings files (`.claude/settings.json`, `.opencode/config*`, env vars, MCP config) are touched **only** to remove agent-fleet' own hook registrations — never other keys, never user env vars, never third-party MCP entries.
301
+
302
+ **Tabular fallback rendering (no-widget runtimes only).** When Step 1 resolved to the tabular fallback, render each group as one compact markdown table and take the picks as a text reply — this legacy format keeps the old pre-checked semantics, since a printed table *can* show them:
292
303
 
293
- 1. **It is part of the agent-fleet inventory.** Its name matches an artifact shipped in the source repo's canonical trees (`skills/`, `vendor/agent-skills-upstream/skills/`, `agents/`, `.claude/commands/`, `.pi/prompts/`, `.pi/extensions/`, `.pi/harnesses/`, `.pi/skills/`, `references/`, `hooks/`). External pi packages are governed by the Group 7 ownership rule above. Other out-of-inventory items — user-authored skills, project-specific commands, custom personas, third-party plugins, external pi packages not managed by Group 7 (not setup-owned entries), unrelated dotfiles — are never proposed for removal even if they sit in the same directory.
294
- 2. **It is recorded in this workspace's install record.** The `## install-status` section of `.ai/agent-fleet-setup.md` lists it as previously installed by this skill, *or* it is a symlink whose target resolves into the agent-fleet source root (which is unambiguously ours).
304
+ | Pick | Item | Group | St | Purpose |
305
+ |---|---|---|---|---|
306
+ | `[x]` / `[ ]` | `<name>` (append ` ★` when recommended) | sub-category — omit for single-type groups | short status token | one-line purpose, ≤ ~6 words |
295
307
 
296
- If a candidate fails either test, list it once under a "Skipped — not owned by agent-fleet" line in the Step 9 plan and leave it alone. Settings files (`.claude/settings.json`, `.opencode/config*`, env vars, MCP config) are touched **only** to remove agent-fleet' own hook registrations — never other keys, never user env vars, never third-party MCP entries.
308
+ Print the token legend once, on a single line above the first table: `St: ok=up to date · upd=update available · mod=modified locally · cflt=conflicting upgrade · gone=removed upstream · new=new this version · pkg=project package · — =not installed · brk=broken`. Pre-check `[x]` every installed row (except `cflt` and `brk`, which start `[ ]`); in a reply, an unchecked installed item means *remove it* (still bound by the removal-scope rule) and a checked one means *keep or update it*. Keep cells narrow — wide cells overflow the terminal. This format and its uncheck-to-remove gesture exist **only** here; never use them on widget screens.
297
309
 
298
310
  ### 7. Offer project overrides
299
311
 
@@ -313,11 +325,11 @@ In the same `## agent-hub` draft, offer the project-knowledge keys when the Step
313
325
 
314
326
  Both keys accept comma-separated repo-relative paths; semantics and persona behavior are documented in `docs/agent-fleet-setup.md`. Skip a key when nothing matching exists — an empty guess sends every specialist hunting for files that aren't there.
315
327
 
316
- Write each section as terse `key: value` lines, never prose: the lifecycle skills and `agent-hub` load this file on every run/session start and parse it by key, so it stays minimal. Show the draft and let the user edit, accept, or skip each section. Reference env-var names for any credentials; keep secrets out of the file. When any drafted section references env-var names (browser-testing roles, STT keys), also offer an `## env` section with `required: <NAME>[, <NAME>]` listing those names — only `agent-fleet doctor` reads it, to warn on unset vars.
328
+ Write each section as terse `key: value` lines, never prose: the lifecycle skills and `agent-hub` load this file on every run/session start and parse it by key, so it stays minimal. Collect the decisions per the Step 1 contract: print each drafted section as agent text, then — with ≤ 2 drafted sections — ask one single-select per section, `Accept` / `Edit (reply with the replacement)` / `Skip`, with `displayMode: "inline"` so the draft stays visible; with more sections, ask one multi-select *"Which override sections should the file include?"* (titles = section names, descriptions = one-line gist) and run the `Accept`/`Edit`/`Skip` pass only for sections the user flags for changes. Cancel on a section = skip it. Reference env-var names for any credentials; keep secrets out of the file. When any drafted section references env-var names (browser-testing roles, STT keys), also offer an `## env` section with `required: <NAME>[, <NAME>]` listing those names — only `agent-fleet doctor` reads it, to warn on unset vars.
317
329
 
318
330
  ### 8. Choose the install method
319
331
 
320
- Ask `copy` or `symlink` for this run.
332
+ If the install record's `## workspace-summary` already carries a `method:` line, **reuse it without asking** — the choice is per-workspace, not per-run. State the reused method in the Step 9 summary (`Method: symlink (from install record)`); the user can override by saying so there. Ask `copy` or `symlink` only on a first install (no record, or a record without a `method:` line) — one single-select whose option descriptions name the trade-off (copy = self-contained, survives moving the source; symlink = tracks the source repo live).
321
333
 
322
334
  - `copy` — copy each artifact into its target path.
323
335
  - `symlink` — link each target path to the source artifact in the agent-fleet repo.
@@ -326,38 +338,45 @@ Ask `copy` or `symlink` for this run.
326
338
 
327
339
  ### 9. Confirm the plan
328
340
 
329
- Present the plan compactly — the **"Keep it narrow"** rule from Step 6 applies here too, since this confirmation renders in the same `pi-ask-user` widget. Do **not** render a wide multi-column table: a `Target paths` column plus a `Notes` column plus an `Artifacts` cell that lists every skill name is exactly what overflows the terminal and forces the user to zoom out. Instead, group the plan by action — one short line per action, each artifact list wrapping naturally:
341
+ Present the plan as compact agent text — printed **before** the confirm question, never packed into its `context` (Step 1 budget). Do **not** render a wide multi-column table: a `Target paths` column plus a `Notes` column plus an `Artifacts` cell that lists every skill name is exactly what overflows the terminal and forces the user to zoom out. Group the plan by action — one short line per action, each artifact list wrapping naturally:
330
342
 
331
- - `Add (N): a, b, c` — newly ticked items
332
- - `Refresh (N): a, b` — re-installed from source; append `— overwrites local edits` when any row was `mod`
333
- - `Remove (N): a` — unticked installed items (removal-scope rule already applied)
343
+ - `Add (N): a, b, c` — newly selected items
344
+ - `Refresh (N): a, b` — re-installed from source; append `— overwrites local edits` when any item was `mod`
345
+ - `Remove (N): a` — remove-screen picks plus accepted `gone`/`brk` cleanups, each named (removal-scope rule already applied)
334
346
  - `Keep (N)` — render as a count, not a full name list (expand only if the user asks)
335
347
  - `Records: stamp v<current>, update install-status + overrides`
336
348
  - `Method: copy` (or `symlink`)
337
349
 
338
- Target paths are deterministic from the per-agent source map, so omit them from the confirmation — show a path only when the user asks. When the version delta from Step 4 is non-empty, lead with a short **"Changes since `v<recorded>` → `v<current>`"** heading followed by one short bullet per change (sourced from `CHANGELOG.md`, only the entries between the two versions) — bullets on their own lines, never crammed into one long line that overflows. Ask the user to confirm, and write nothing until they do.
350
+ Target paths are deterministic from the per-agent source map, so omit them from the confirmation — show a path only when the user asks. When the version delta from Step 4 is non-empty, lead with a short **"Changes since `v<recorded>` → `v<current>`"** heading followed by one short bullet per change (sourced from `CHANGELOG.md`, only the entries between the two versions) — bullets on their own lines, never crammed into one long line that overflows.
351
+
352
+ **The confirm question.** Then confirm with **one single-select**, asked with `displayMode: "inline"` so the printed plan stays visible:
353
+
354
+ - `Apply — and remove the installer commands` *(the default; the installer files are `/setup-agent-fleet` and `/doctor-agent-fleet` — the `/af-*` variants for OpenCode — plus the `guided-workspace-setup` skill body; they can be restored later with `npx @chankov/agent-fleet init`)*
355
+ - `Apply — keep the installer commands` *(records `keep-installer: true` in `## workspace-summary` and skips Step 10b)*
356
+ - `Adjust picks` *(the freeform reply names the group(s) to revisit; reopen only those quick screens, then re-print the plan and re-confirm)*
357
+ - `Cancel — write nothing`
339
358
 
340
- **Installer cleanup line.** The summary always ends with one line stating that the installer slash commands (`/setup-agent-fleet`, `/doctor-agent-fleet` — or `/af-*-agent-fleet` for OpenCode — plus the `guided-workspace-setup` skill body) will be removed after apply, so they do not pollute the user's slash-command list. Add the verbatim suffix: *"Reply `keep` to leave them in place; re-run `npx @chankov/agent-fleet init` later if removed."* If the user replies `keep`, record `keep-installer: true` in `## workspace-summary` and skip Step 10b. Otherwise the default is to remove them.
359
+ Cancel (`esc`) = write nothing. When the install record already carries `keep-installer: true`, collapse the two Apply options into a single `Apply` and add `Installer: kept (from install record)` to the plan print — do not re-offer the removal.
341
360
 
342
361
  ### 10. Apply the setup
343
362
 
344
363
  Apply the changes: create directories, add or update selected artifacts, and remove deselected ones — **bound by the removal-scope rule from Step 6**. Selected personas for `claude-code`/`opencode` are applied with `node <source-root>/bin/cli.js transform-persona --agent <agent> --workspace <workspace> <name…>` and recorded with `transformed: true`; pi personas follow the normal copy/symlink path. Before deleting any target, verify both conditions: (a) the name is in the agent-fleet inventory and (b) the item is either listed in `## install-status` or is a symlink resolving into the source repo. If either check fails, skip the deletion silently and log the path under a "Skipped — not owned by agent-fleet" line in the final report.
345
364
 
346
- **Apply without mid-flight questions.** Refresh every ticked item from its per-agent source unconditionally. Do not pause to ask whether to overwrite a modified file — `installed · modified` already appeared in Step 6 with the explicit warning that refreshing overwrites local edits, and the user's tick is the consent. The Step 9 confirmation is the single gate; nothing further is asked during apply. (If the apply hits a genuine error — permission denied, source missing, broken target type — stop, report it, and ask how to proceed; that is not the same as soliciting consent.)
365
+ **Apply without mid-flight questions.** Refresh every selected item from its per-agent source unconditionally. Do not pause to ask whether to overwrite a modified file — the `mod` item's description already warned in Step 6 that refreshing overwrites local edits, and the user's selection is the consent. The Step 9 confirmation is the single gate; nothing further is asked during apply. (If the apply hits a genuine error — permission denied, source missing, broken target type — stop, report it, and ask how to proceed; that is not the same as soliciting consent.)
347
366
 
348
367
  For settings files (`.claude/settings.json` and equivalents), edit only the agent-fleet hook entries; leave every other key — user permissions, env vars, third-party MCP servers, custom hooks — untouched.
349
368
 
350
369
  **pi harness companions.** When this pass installs, refreshes, or removes any pi harness (Step 6 group 6), apply the companion set in the same pass per the Step 6 rules:
351
370
 
352
- - Refresh `scripts/team-up.ts`, `.pi/agents/peers.yaml`, `.pi/agents/teams.yaml`, the peer personas they name, `.pi/damage-control-rules.yaml`, and `.pi/harnesses/package.json` from source (then `npm install --prefix .pi/harnesses` for the runtime deps).
371
+ - Load `companion-manifest.json` from this skill directory and validate every listed source path before writing. Copy or symlink each listed directory recursively and each listed file exactly. This installs the complete Codex/Hermes/systemd/script closure without starting services, pairing, reading auth state, or copying credentials.
353
372
  - Refresh the `justfile` from the **current** source into its managed region (between the `# >>> agent-fleet:harnesses … >>>` / `# <<< agent-fleet:harnesses <<<` sentinels), preserving any user recipes outside it — this is what prunes retired-harness recipes and adds new ones. In symlink mode, link the whole `justfile` to source **only** when the target has no `justfile` or its existing one is wholly agent-fleet'; if the target carries user recipes, fall back to a copy-mode managed-region rewrite so those recipes survive.
354
- - **Removal:** when the **last** pi harness is removed, strip the agent-fleet managed region from the `justfile` (and drop the now-orphaned `scripts/`/`.pi/agents/` companions that no remaining harness needs), bound by the same removal-scope rule — never delete user recipes outside the sentinels, and never delete a companion the user authored.
373
+ - Record every manifest target under `harness-support` in `## install-status`. **Removal:** when the **last** pi harness is removed, strip the managed `justfile` region and remove only manifest targets recorded as owned (or symlinked into the source root). Preserve user recipes, unrecorded regular files, and any companion still needed by another selected harness. Never touch user systemd state, Codex auth, pairing material, or credentials.
355
374
 
356
375
  **`pi-voice-stt` config companion.** When this pass installs `pi-voice-stt` and the user opted into provider configuration (Step 6 group 5 note), write `.ai/stt.json` (non-secret config) and append the referenced env-var placeholders to the workspace root `.env` (creating it and the `.gitignore` rule if needed) in this same pass — never write key values into `.ai/`. On removal of `pi-voice-stt`, delete `.ai/stt.json` only if unedited, and leave `.env` untouched. Record both under `## install-status`.
357
376
 
358
377
  Then write both `.ai/` files: the agreed override sections from Step 7 into `.ai/agent-fleet-overrides.md`, and the install record — artifacts, target paths, method, **package version**, date — into `.ai/agent-fleet-setup.md`. The `version:` line in `## workspace-summary` is set to the package version from Step 2; this is what the next re-run will compare against to compute the version delta.
359
378
 
360
- ### 10b. Remove the installer artifacts (unless the user said `keep`)
379
+ ### 10b. Remove the installer artifacts (unless the user chose to keep them)
361
380
 
362
381
  After Step 10 has written the catalogue + the `.ai/` files, the installer files dropped by `npx @chankov/agent-fleet init` — the `setup-agent-fleet` / `doctor-agent-fleet` slash commands and the `guided-workspace-setup` skill body itself — are no longer needed in the workspace. They were bootstrap plumbing, not part of the user's permanent install. Leaving them in place pollutes the agent's slash-command list and confuses re-runs (which should always go through `init`, not a stale local copy).
363
382
 
@@ -393,14 +412,19 @@ Close the report with one line explaining the installer-cleanup outcome:
393
412
  |---|---|
394
413
  | "The user wants everything — I'll install all skills without asking." | Loading every skill wastes context and dilutes discovery. The per-group menu and the `★` recommendations exist so a workspace gets only what it needs. |
395
414
  | "I'll skip the doctor preflight — the menu will surface broken items anyway." | Broken symlinks distort the install menu's `installed` / `not installed` state. Repair first so the menu reflects reality. |
396
- | "I'll collapse the 7 groups into one big checklist — it's faster." | The 7 groups are how the user reasons about scope (skills vs personas vs commands vs pi-only). A single flat list of ~50 items makes recommendations and sub-category labels meaningless. Keep the 7 screens; within a multi-type group, the `Group` column preserves the sub-sections. |
397
- | "I'll re-split the Skills group back into one screen per phase — six small screens are clearer." | The whole point of the restructure is 7 screens, not 19. The `Group` column already labels the phase within the single Skills screen; splitting it back re-introduces the screen sprawl we removed. |
415
+ | "I'll collapse the 7 groups into one big checklist — it's faster." | The Express question is the sanctioned shortcut — one single-select that resolves all groups. A flat ~50-item multi-select is not: it blows the screen budget and makes recommendations and sub-category labels meaningless. Keep the groups; chunk drill-ins by sub-category. |
416
+ | "I'll show every group's drill-in chunks unconditionally — the user should see all items." | The quick screen exists to spare the user ~20-item lists they didn't ask for. Chunks appear only behind `Customise` / `Remove some…`; the quick screen's counts already say what's installed and what's recommended. |
417
+ | "`ask_user` can't pre-check installed items, so I'll print the old markdown table and parse a text reply instead." | The quick path exists precisely for this: counts in option titles, state words in descriptions, removal via the explicit remove screen. The table format belongs only to the no-widget tabular fallback. |
418
+ | "I'll paste the group table into the `ask_user` context so the user sees everything at once." | The widget wraps and scrolls *options*, not tables. A table in `context` overflows, flickers, and defeats the redesign. Budget: ≤ 8 context lines, ≤ 9 options; long material prints as agent text before an `inline` call. |
419
+ | "The user didn't select an installed item in the Customise chunk — they must want it removed." | Not selecting means keep-as-is. Removal happens only through the explicit remove screen (or an accepted `gone`/`brk` cleanup); an accidental non-pick must never delete an artifact. |
420
+ | "The user pressed `esc` — I'll treat the defaults as accepted and continue." | Cancel is a no-op/skip on every screen except the Step 9 confirm, where it means *do not apply*. Treating cancel as consent is how workspaces get written to without agreement. |
421
+ | "Express said `Apply updates`, so the `cflt` row gets refreshed too." | Express never resolves conflicts. Every `cflt` row gets its printed three-way diff and its own inline question, whatever Express answered. |
398
422
  | "The agent is `pi` and `pi-ask-user` is missing — I'll just run the menu in the tabular fallback and skip the bootstrap." | Step 5b exists precisely to avoid forcing a ~50-row menu through plain text. Offer the install-then-reload bootstrap first; only fall back to tabular if the user *declines*. |
399
423
  | "I installed `pi-ask-user` in Step 5b, so I'll keep going straight into the install menu in the same pass." | The tool only becomes callable after pi reloads. Stop the pass after install, ask the user to reload and re-run; the native widget is unavailable until then. |
400
424
  | "I'll copy the files now and confirm afterwards." | Writing before the Step 9 confirmation can clobber config the user wanted to keep. Confirmation is the only gate that protects the target workspace. |
401
425
  | "There is no `*-setup.md` for this agent, so I'll guess the install paths." | Guessed paths put artifacts where the agent never loads them. Read the agent's setup doc, or use the built-in map — a location is never invented. |
402
426
  | "The workspace already has a `.claude/` directory, so setup is done." | A directory existing is not install state. The `## install-status` section is the only record of what this skill installed; read it before deciding. |
403
- | "An existing file differs from the source — I'll pause and ask the user mid-apply whether to overwrite." | Step 6 already surfaced `installed · modified` with the warning that refreshing overwrites local edits. The user's tick is the consent. Mid-apply questions break the apply pass; they were replaced by the upfront status. |
427
+ | "An existing file differs from the source — I'll pause and ask the user mid-apply whether to overwrite." | Step 6 already surfaced `mod` with the warning that refreshing overwrites local edits. The user's selection is the consent. Mid-apply questions break the apply pass; they were replaced by the upfront status. |
404
428
  | "`.pi/prompts/design-agent.md` doesn't exist, but `.claude/commands/design-agent.md` does — I'll symlink to the Claude file so the user gets the prompt." | That mixes runtimes silently and lets the source repo's claude-code tree drive a pi target. The source availability filter forbids it: items without a per-agent source are not offered at all. |
405
429
  | "The harness directories installed fine — the `justfile` is just launch shortcuts, I'll leave the existing one." | The `justfile` is how harnesses are launched; if it is not refreshed from the current source, retired-harness recipes linger (pointing at deleted `.pi/harnesses/<name>/` dirs) and newly added harnesses (for example `ask-user-remote` or the Hermes `conductor` recipe) have no recipe at all. It is a companion of the harness group and must be refreshed whenever any harness changes. |
406
430
  | "I'll just copy the source `justfile` over the target's to refresh it." | A wholesale copy clobbers any recipes the user authored. Refresh only the managed region between the `agent-fleet:harnesses` sentinels; a user-edited `justfile` outside that region is `mod`/`cflt` and gets the three-way diff first — never a silent overwrite. |
@@ -412,25 +436,28 @@ Close the report with one line explaining the installer-cleanup outcome:
412
436
  | "`/setup-agent-fleet` and `/doctor-agent-fleet` are useful — I'll re-install them at the end of apply so the user can re-run them locally." | They are installer commands that the CLI bootstraps and the skill itself cleans up in Step 10b by default. Keeping them is opt-in via `keep` in Step 9. Re-installing them silently undoes the cleanup the user implicitly chose. |
413
437
  | "The bootstrap marker is missing — I'll search the user's `~/repos/`, `~/projects/`, and `/media/` for any clone of `agent-fleet` to use as the source root." | Scanning the user's filesystem picks up dev clones, forks, half-edited working trees, and stale checkouts that are NOT the package the user installed from. The npm-installed copy is the only authoritative source after `init`. Without the marker, ask the user explicitly — never guess. |
414
438
  | "This `SKILL.md` is two levels below the workspace's `.pi/skills/`, so the workspace root must be the source root." | Bootstrap copies `SKILL.md` into the workspace precisely so the slash command can load it. The workspace is the *target* of the install, not the source. Use the marker file to find the real source; resolving from `SKILL.md`'s workspace location always lies. |
415
- | "The recorded version differs from the current — I'll just refresh everything to the new source without showing the diff." | Conflicting upgrades (user-modified copy + source changed upstream) require the three-way diff to be shown in Step 6, with the row pre-unchecked. Refreshing silently overwrites work the user did between versions. |
439
+ | "The recorded version differs from the current — I'll just refresh everything to the new source without showing the diff." | Conflicting upgrades (user-modified copy + source changed upstream) require the three-way diff printed and the per-row inline question answered. Refreshing silently overwrites work the user did between versions. |
416
440
  | "The `.versions/<recorded>/` snapshot is missing — I'll pretend the installed copy matches the recorded source and refresh anyway." | A missing snapshot means we cannot compute the three-way diff. The skill must fall back to "treat installed copy as canonical" and surface the missing snapshot in the row's status so the user can decide — never pretend a diff exists. |
417
441
  | "The workspace has no `version:` line — I'll silently stamp the current version and move on." | A pre-versioning workspace must be flagged in Step 4 and the user prompted: stamp the current version (assume copies match) or wipe and reinstall. Silent stamping hides a real decision. |
418
- | "The user didn't say anything about the installer cleanup line — I'll leave the installer files in place to be safe." | The default is to remove. Step 9's confirmation line explicitly states the cleanup will happen unless the user replies `keep`. Silence is consent for the default, not opt-out from it. |
419
- | "I'll add `setup-agent-fleet` and `doctor-agent-fleet` to the install menu so the user can pick whether to keep them." | They are still installer-only and excluded from the menu. The keep-vs-remove choice is the single Step 9 line, not a menu group — adding them to the menu re-opens the pollution we just fixed. |
442
+ | "The user picked plain `Apply` — I'll leave the installer files in place to be safe." | The default Apply option removes them; keeping is the explicit `Apply — keep the installer commands` option (or a recorded `keep-installer: true`). Choosing the default is consent for the cleanup, not opt-out from it. |
443
+ | "I'll add `setup-agent-fleet` and `doctor-agent-fleet` to the install menu so the user can pick whether to keep them." | They are still installer-only and excluded from the menu. The keep-vs-remove choice is the pair of Apply options on the Step 9 confirm, not a menu group — adding them to the menu re-opens the pollution we just fixed. |
420
444
  | "The skill is currently executing; deleting its own file in Step 10b will crash mid-run." | The agent loads the skill into memory at the start of execution. Removing the file on disk does not unload the in-memory copy — Steps 10b and 11 complete normally before control returns. |
421
445
 
422
446
  ## Red Flags
423
447
 
424
448
  - Files written to the target workspace before the Step 9 confirmation.
425
449
  - The doctor preflight skipped on a workspace that already has prior install state.
426
- - An install menu rendered as one undifferentiated list instead of the 7 grouped tables (≤ 8), or the Skills group re-split into one screen per phase.
427
- - A multi-type group (Skills, Agent personas, References & Hooks, pi extensions & runtime skills, pi harnesses) rendered without the `Group` sub-category column.
450
+ - The install menu rendered as one undifferentiated list instead of the Express question plus per-group quick screens, or drill-in chunks shown unconditionally instead of behind `Customise` / `Remove some…`.
451
+ - A markdown table or status legend rendered inside a widget call's question or `context`, or a widget screen exceeding the Step 1 budget (> 9 options, > 8 context lines, > 4 options on `AskUserQuestion`).
452
+ - The widget flow replaced by free-text table replies while `ask_user` / `AskUserQuestion` is available.
428
453
  - The agent is `pi`, `pi-ask-user` is missing, and the install menu was rendered in tabular fallback without first offering the Step 5b bootstrap.
429
454
  - Step 5b installed `pi-ask-user` but the pass continued into the install menu instead of stopping for the user to reload and re-run.
430
- - A menu group rendered without a per-row `St` token (or without the legend that defines them), or with installed items not pre-checked.
431
- - A menu table rendered with the long `installed · …` state names, a separate `Rec` column, or wide cells/preamble that overflow the terminal — render the compact form so the `pi-ask-user` widget fits without zooming.
455
+ - A drill-in chunk not split by sub-category, or a widget option whose title/description omits the item's state — the user must never infer state from nothing.
456
+ - An artifact removed without an explicit remove-screen pick (or accepted `gone`/`brk` cleanup) — including an unselected Customise item treated as a removal.
457
+ - `esc`/cancel treated as consent on any screen, or Express / `Apply updates` refreshing a `cflt` row.
458
+ - A three-way diff, override draft, or the Step 9 plan asked about with the default overlay covering it instead of `displayMode: "inline"`.
432
459
  - The Step 9 confirmation rendered as a wide multi-column table (a `Target paths` or `Notes` column, or an `Artifacts` cell listing every skill name) instead of compact action-grouped lines, or the "Changes since" delta crammed into one long line instead of short per-change bullets.
433
- - A `recommended` reply that silently unticks already-installed items instead of adding `★` items on top.
460
+ - A `recommended` reply that silently drops already-installed items instead of adding `★` items on top.
434
461
  - `setup`, `doctor`, or `guided-workspace-setup` shown in the install menu — they are installer-only.
435
462
  - An item offered for one agent whose per-agent source file does not exist (cross-tool substitution).
436
463
  - Hook rows offered to a non-`claude-code` agent (group 4 should degrade to References-only for `opencode`/`pi`).
@@ -449,14 +476,14 @@ Close the report with one line explaining the installer-cleanup outcome:
449
476
  - An existing, differing target file overwritten without asking the user.
450
477
  - A re-run that ignores the existing `## install-status` and reinstalls everything.
451
478
  - A `pi` workspace using `agent-hub` reached Step 7 without being offered the `## agent-hub` / `language: <value>` override, or an existing language value was overwritten instead of preserved.
452
- - `agent-hub` installed or kept without `damage-control` **and** `damage-control-continue` — the mandatory pairing was skipped, or an untick of either damage-control variant was accepted while `agent-hub` stayed selected.
479
+ - `agent-hub` installed or kept without `damage-control-continue` **and** `ask-user-remote` — the mandatory pairing was skipped, or removal of either required companion was accepted while `agent-hub` stayed selected.
453
480
  - The `bowser` runtime-skill installed without checking for the external `playwright-cli` CLI — or a global `@playwright/cli` install run without the user's confirmation.
454
481
  - The overrides file padded with install status, summaries, or prose instead of terse `key: value` sections.
455
482
  - A re-run that detects a non-empty version delta but skips the "Changes since v<recorded> → v<current>" block in Step 9.
456
- - A `conflicting upgrade` row pre-checked, or the three-way diff omitted for it.
483
+ - A `cflt` row refreshed without its printed diff and inline question, or the diff omitted entirely.
457
484
  - A pre-versioning workspace stamped with the current version without prompting the user first.
458
485
  - The post-apply `version:` line not matching the package version from Step 2.
459
- - Step 9 summary missing the installer-cleanup line, or the line stated `keep` as the default.
486
+ - The Step 9 confirm question missing the installer-cleanup choice (the two Apply variants), or keep presented as the default.
460
487
  - Source root resolved by scanning the filesystem for `agent-fleet` repos (`find`, `fd`, `grep -r`, …) instead of using `.ai/.agent-fleet-bootstrap.json` or asking the user.
461
488
  - Source root resolved by treating `SKILL.md`'s workspace location (`.pi/skills/...` or `.claude/skills/...`) as the package root.
462
489
  - The bootstrap marker file (`.ai/.agent-fleet-bootstrap.json`) ignored when present, or trusted blindly when the path it names no longer exists.
@@ -472,15 +499,16 @@ After completing the workflow, confirm:
472
499
  - [ ] The coding agent was confirmed, and `docs/<agent>-setup.md` was read for `opencode`/`pi` (or the built-in map used for `claude-code`).
473
500
  - [ ] The doctor preflight ran on any workspace with prior install state, and its findings were resolved or explicitly skipped.
474
501
  - [ ] On `pi`, Step 5b ran before the menu: `pi-ask-user` was either already present (no-op) or its install-then-reload bootstrap was offered; the pass stopped after install when it was bootstrapped, and was not forced when the user declined.
475
- - [ ] The install menu was presented as the 7 grouped tables (groups 5–7 shown only for `pi`), not 19 screens and not one flat list; each was its own multi-select with `★` recommendations marked.
476
- - [ ] Each multi-type group (Skills, Agent personas, References & Hooks, and the pi extension/harness groups) carried a `Group` sub-category column ordering its rows.
477
- - [ ] Every row carried an explicit `St` token (`ok`, `upd`, `mod`, `cflt`, `gone`, `new`, `pkg`, `—`, or `brk`) with the legend shown once above the table — never blank and never the long `installed · …` state names that overflow the widget.
478
- - [ ] Installed items were pre-checked `[x]`; not-installed items were pre-checked `[ ]`; `recommended` added `★` items on top of the pre-selection without unticking installed ones.
502
+ - [ ] The menu opened with the Express question; per-group quick screens ran only on `Custom` (groups 5–7 shown only for `pi`); drill-in chunks appeared only behind `Customise` / `Remove some…` — never one flat list, never unconditional chunks.
503
+ - [ ] A fresh-workspace Express path reached the Step 9 confirm in ≤ 4 widget prompts (Express → overrides → method → confirm); a no-change re-run in ≤ 2 (`Keep as-is` → confirm).
504
+ - [ ] Every widget screen stayed within the Step 1 budget (≤ 9 options, ≤ 8 context lines; ≤ 4 options on `AskUserQuestion`); no markdown table or token legend appeared inside a widget call; drill-in chunks were split by sub-category.
505
+ - [ ] Every drill-in option carried its state — `[st]` token in the title, plain words in the description; `recommended` added `★` items on top of what is installed without dropping anything.
506
+ - [ ] No artifact was removed without an explicit remove-screen pick or an accepted `gone`/`brk` cleanup; unselected Customise items were kept as-is; cancel was treated as skip/no-op everywhere except the Step 9 confirm, where it meant do-not-apply.
479
507
  - [ ] Items lacking a per-agent source were filtered out of the menu — no cross-tool substitution offered.
480
508
  - [ ] Hooks were offered only for `claude-code`; References were still offered for all agents.
481
509
  - [ ] On `claude-code`, groups were driven via `AskUserQuestion` (quick-path + ≤ 4-option chunks), not free-text table replies.
482
510
  - [ ] The personas group listed the full `transform-persona --list` roster for the chosen agent; pi-only personas appeared only for `pi`; selected personas for `claude-code`/`opencode` were written by the `transform-persona` CLI and recorded with `transformed: true`.
483
- - [ ] Apply ran without any overwrite-this-file prompt; ticked items refreshed unconditionally and unticked modified items were preserved.
511
+ - [ ] Apply ran without any overwrite-this-file prompt; selected items refreshed unconditionally and unselected modified items were preserved.
484
512
  - [ ] `setup`, `doctor`, and `guided-workspace-setup` were excluded from the install menu.
485
513
  - [ ] Every selected artifact exists at its resolved target path; every deselected one was removed **only if** the removal-scope rule allowed it (in inventory + in install record / symlink-into-source).
486
514
  - [ ] When pi harnesses were installed/refreshed/removed, the `justfile` and harness support files were refreshed from the current source: the `justfile` lists a recipe for every installed harness, none for a removed one, and points at no missing `.pi/harnesses/<name>/`; user recipes outside the managed-region sentinels were preserved.
@@ -488,16 +516,17 @@ After completing the workflow, confirm:
488
516
  - [ ] Settings-file edits were limited to agent-fleet' own hook entries; no user keys, env vars, or third-party MCP entries were modified.
489
517
  - [ ] `.ai/agent-fleet-overrides.md` holds the agreed override sections as terse `key: value` lines, and nothing else.
490
518
  - [ ] For `pi` workspaces using `agent-hub`, the `## agent-hub` language override was offered (an existing legacy `## agent-team` section kept its name), existing values were preserved, and omitting the section was treated as default English.
491
- - [ ] If `agent-hub` was installed or kept, `damage-control` was installed/kept alongside it (mandatory pairing) and could not be deselected while `agent-hub` remained.
519
+ - [ ] If `agent-hub` was installed or kept, `damage-control-continue` and `ask-user-remote` were installed/kept alongside it (mandatory pairing) and could not be deselected while `agent-hub` remained.
520
+ - [ ] Any retired `.pi/harnesses/damage-control/` copy was removed only when recorded and unchanged (or symlinked into source); user-modified or unowned copies were preserved.
492
521
  - [ ] If the `bowser` runtime-skill was installed or kept, the external `playwright-cli` dependency was checked, and a missing CLI was surfaced with the install offer (`npm install -g @playwright/cli@latest`) rather than silently installed or treated as a hard failure.
493
522
  - [ ] `.ai/agent-fleet-setup.md` holds an up-to-date install record, including at least one `## doctor-runs` entry for this session, and a `version:` line in `## workspace-summary` that matches the package version from Step 2.
494
- - [ ] Step 9 was rendered as compact action-grouped lines (Add / Refresh / Remove / Keep-count / Records / Method), not a wide `Target paths` + `Notes` table that overflows the widget.
523
+ - [ ] Step 9 was rendered as compact action-grouped lines (Add / Refresh / Remove / Keep-count / Records / Method) printed as agent text, followed by the single `inline` confirm question — not a wide `Target paths` + `Notes` table, and not a plan packed into the question's `context`.
495
524
  - [ ] When the version delta was non-empty, Step 9's summary led with the "Changes since v<recorded> → v<current>" heading followed by short per-change bullets sourced from `CHANGELOG.md` — never one long overflowing line.
496
- - [ ] Every `conflicting upgrade` row was rendered with its three-way diff in Step 6 and was not pre-checked.
525
+ - [ ] Every `cflt` row got its three-way diff printed as text plus its own inline question, and was never resolved by Express or `Apply updates`.
497
526
  - [ ] A pre-versioning workspace was flagged in Step 4 and the user was prompted to stamp or wipe — not silently stamped.
498
527
  - [ ] Source root was resolved from `.ai/.agent-fleet-bootstrap.json` if present, or from `SKILL.md`'s realpath (symlink mode), or by asking the user — **never** by scanning the filesystem.
499
528
  - [ ] If the bootstrap marker named a path that no longer exists, the user was warned and asked for a new path — not silently ignored.
500
- - [ ] Step 9 summary ended with the installer-cleanup line: states remove-by-default and offers `keep` as the opt-out.
529
+ - [ ] The Step 9 confirm carried the installer-cleanup choice as its two Apply options (remove-by-default, keep as the explicit alternative), collapsed to one `Apply` only when `keep-installer: true` was already recorded.
501
530
  - [ ] Step 10b ran (or was explicitly skipped because `keep-installer: true`); the installer files are absent from the workspace unless the user opted to keep them.
502
531
  - [ ] Step 11 report includes the one-line installer-cleanup outcome.
503
532
  - [ ] No broken symlinks remain in any of the scanned install-target directories.