@chankov/agent-fleet 0.0.3 → 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.
- package/.claude/commands/setup-agent-fleet.md +1 -1
- package/.opencode/commands/af-setup-agent-fleet.md +1 -1
- package/.pi/harnesses/agent-hub/README.md +199 -16
- package/.pi/harnesses/agent-hub/access-approval.ts +135 -0
- package/.pi/harnesses/agent-hub/delegate.ts +32 -9
- package/.pi/harnesses/agent-hub/drift-watchdog.js +165 -0
- package/.pi/harnesses/agent-hub/footer.ts +29 -0
- package/.pi/harnesses/agent-hub/helpers.ts +49 -0
- package/.pi/harnesses/agent-hub/index.ts +1033 -242
- package/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
- package/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
- package/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
- package/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
- package/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
- package/.pi/harnesses/agent-hub/monitor-session-bridge.ts +11 -0
- package/.pi/harnesses/agent-hub/package.json +5 -4
- package/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
- package/.pi/harnesses/agent-hub/run-budget.js +155 -0
- package/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
- package/.pi/harnesses/agent-hub/spawn.ts +161 -94
- package/.pi/harnesses/agent-hub/version.ts +18 -0
- package/.pi/harnesses/coms/README.md +10 -0
- package/.pi/harnesses/coms/index.ts +2 -0
- package/.pi/harnesses/coms/package.json +5 -4
- package/.pi/harnesses/coms/version.ts +18 -0
- package/.pi/harnesses/damage-control-continue/README.md +32 -31
- package/.pi/harnesses/damage-control-continue/index.ts +23 -9
- package/.pi/harnesses/damage-control-continue/package.json +5 -4
- package/.pi/harnesses/damage-control-continue/version.ts +18 -0
- package/.pi/harnesses/{damage-control/shared.ts → lib/damage-control-shared.ts} +20 -6
- package/.pi/prompts/setup-agent-fleet.md +1 -1
- package/.versions/0.0.4/.claude/commands/build.md +44 -0
- package/.versions/0.0.4/.claude/commands/code-simplify.md +22 -0
- package/.versions/0.0.4/.claude/commands/design-agent.md +14 -0
- package/.versions/0.0.4/.claude/commands/doctor-agent-fleet.md +17 -0
- package/.versions/0.0.4/.claude/commands/orchestrate.md +112 -0
- package/.versions/0.0.4/.claude/commands/plan.md +16 -0
- package/.versions/0.0.4/.claude/commands/prime.md +22 -0
- package/.versions/0.0.4/.claude/commands/review.md +16 -0
- package/.versions/0.0.4/.claude/commands/setup-agent-fleet.md +25 -0
- package/.versions/0.0.4/.claude/commands/ship.md +72 -0
- package/.versions/0.0.4/.claude/commands/spec.md +15 -0
- package/.versions/0.0.4/.claude/commands/test.md +19 -0
- package/.versions/0.0.4/.claude/commands/webperf.md +32 -0
- package/.versions/0.0.4/.claude/orchestrate-teams.yaml +24 -0
- package/.versions/0.0.4/.opencode/commands/af-build.md +17 -0
- package/.versions/0.0.4/.opencode/commands/af-code-simplify.md +16 -0
- package/.versions/0.0.4/.opencode/commands/af-compound.md +16 -0
- package/.versions/0.0.4/.opencode/commands/af-design-agent.md +15 -0
- package/.versions/0.0.4/.opencode/commands/af-doctor-agent-fleet.md +17 -0
- package/.versions/0.0.4/.opencode/commands/af-orchestrate.md +112 -0
- package/.versions/0.0.4/.opencode/commands/af-plan.md +16 -0
- package/.versions/0.0.4/.opencode/commands/af-prime.md +22 -0
- package/.versions/0.0.4/.opencode/commands/af-review.md +15 -0
- package/.versions/0.0.4/.opencode/commands/af-setup-agent-fleet.md +15 -0
- package/.versions/0.0.4/.opencode/commands/af-ship.md +16 -0
- package/.versions/0.0.4/.opencode/commands/af-spec.md +16 -0
- package/.versions/0.0.4/.opencode/commands/af-test.md +21 -0
- package/.versions/0.0.4/.opencode/commands/af-webperf.md +32 -0
- package/.versions/0.0.4/.opencode/orchestrate-teams.yaml +24 -0
- package/.versions/0.0.4/.pi/agents/dispatch-policy.yaml +32 -0
- package/.versions/0.0.4/.pi/agents/model-profiles.yaml +20 -0
- package/.versions/0.0.4/.pi/agents/peers.yaml +146 -0
- package/.versions/0.0.4/.pi/agents/teams.yaml +39 -0
- package/.versions/0.0.4/.pi/damage-control-rules.yaml +297 -0
- package/.versions/0.0.4/.pi/extensions/agent-fleet-update-check/README.md +58 -0
- package/.versions/0.0.4/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
- package/{.pi/harnesses/damage-control → .versions/0.0.4/.pi/extensions/agent-fleet-update-check}/package.json +1 -1
- package/.versions/0.0.4/.pi/extensions/btw/README.md +118 -0
- package/.versions/0.0.4/.pi/extensions/btw/index.ts +917 -0
- package/.versions/0.0.4/.pi/extensions/btw/package.json +6 -0
- package/.versions/0.0.4/.pi/extensions/btw/state.js +179 -0
- package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/README.md +58 -0
- package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/index.ts +92 -0
- package/.versions/0.0.4/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
- package/.versions/0.0.4/.pi/extensions/compact-and-continue/README.md +42 -0
- package/.versions/0.0.4/.pi/extensions/compact-and-continue/index.ts +120 -0
- package/.versions/0.0.4/.pi/extensions/compact-and-continue/package.json +6 -0
- package/.versions/0.0.4/.pi/extensions/mcp-bridge/README.md +46 -0
- package/.versions/0.0.4/.pi/extensions/mcp-bridge/index.ts +206 -0
- package/.versions/0.0.4/.pi/extensions/mcp-bridge/package.json +6 -0
- package/.versions/0.0.4/.pi/extensions/package-lock.json +1143 -0
- package/.versions/0.0.4/.pi/extensions/package.json +9 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/README.md +201 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/config.ts +198 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/index.ts +248 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/package.json +6 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/providers.ts +214 -0
- package/.versions/0.0.4/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/README.md +798 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/access-approval.ts +135 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/artifacts.js +92 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/backend-policy.js +153 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/delegate.ts +386 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/drift-watchdog.js +165 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/footer.ts +29 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/helpers.ts +214 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/index.ts +8045 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/monitor-session-bridge.ts +11 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/package.json +7 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/research-retention.js +34 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/return-contract.js +215 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/run-budget.js +155 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/scope-gate.js +103 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/spawn.ts +246 -0
- package/.versions/0.0.4/.pi/harnesses/agent-hub/version.ts +18 -0
- package/.versions/0.0.4/.pi/harnesses/ask-user-remote/README.md +18 -0
- package/.versions/0.0.4/.pi/harnesses/ask-user-remote/index.ts +293 -0
- package/.versions/0.0.4/.pi/harnesses/ask-user-remote/race-core.js +106 -0
- package/.versions/0.0.4/.pi/harnesses/coms/README.md +92 -0
- package/.versions/0.0.4/.pi/harnesses/coms/index.ts +1745 -0
- package/.versions/0.0.4/.pi/harnesses/coms/package.json +7 -0
- package/.versions/0.0.4/.pi/harnesses/coms/version.ts +18 -0
- package/.versions/0.0.4/.pi/harnesses/damage-control-continue/README.md +117 -0
- package/.versions/0.0.4/.pi/harnesses/damage-control-continue/index.ts +536 -0
- package/.versions/0.0.4/.pi/harnesses/damage-control-continue/package.json +7 -0
- package/.versions/0.0.4/.pi/harnesses/damage-control-continue/version.ts +18 -0
- package/.versions/0.0.4/.pi/harnesses/lib/damage-control-shared.ts +197 -0
- package/.versions/0.0.4/.pi/harnesses/lib/herdr-client.ts +458 -0
- package/.versions/0.0.4/.pi/harnesses/lib/herdr-presence.ts +288 -0
- package/.versions/0.0.4/.pi/harnesses/package-lock.json +35 -0
- package/.versions/0.0.4/.pi/harnesses/package.json +9 -0
- package/.versions/0.0.4/.pi/prompts/build.md +24 -0
- package/.versions/0.0.4/.pi/prompts/code-simplify.md +22 -0
- package/.versions/0.0.4/.pi/prompts/doctor-agent-fleet.md +15 -0
- package/.versions/0.0.4/.pi/prompts/plan.md +16 -0
- package/.versions/0.0.4/.pi/prompts/review.md +16 -0
- package/.versions/0.0.4/.pi/prompts/setup-agent-fleet.md +27 -0
- package/.versions/0.0.4/.pi/prompts/ship.md +17 -0
- package/.versions/0.0.4/.pi/prompts/spec.md +15 -0
- package/.versions/0.0.4/.pi/prompts/test.md +19 -0
- package/.versions/0.0.4/.pi/skills/bowser/SKILL.md +145 -0
- package/.versions/0.0.4/.version +1 -0
- package/.versions/0.0.4/agents/architect.md +23 -0
- package/.versions/0.0.4/agents/bowser.md +26 -0
- package/.versions/0.0.4/agents/builder.md +53 -0
- package/.versions/0.0.4/agents/code-reviewer.md +205 -0
- package/.versions/0.0.4/agents/deep-researcher.md +31 -0
- package/.versions/0.0.4/agents/documenter.md +18 -0
- package/.versions/0.0.4/agents/orchestrator.md +54 -0
- package/.versions/0.0.4/agents/plan-reviewer.md +60 -0
- package/.versions/0.0.4/agents/planner.md +69 -0
- package/.versions/0.0.4/agents/releaser.md +24 -0
- package/.versions/0.0.4/agents/researcher.md +28 -0
- package/.versions/0.0.4/agents/security-auditor.md +166 -0
- package/.versions/0.0.4/agents/test-engineer.md +151 -0
- package/.versions/0.0.4/agents/web-debugger.md +42 -0
- package/.versions/0.0.4/agents/web-performance-auditor.md +192 -0
- package/.versions/0.0.4/codex/CONDUCTOR.md +148 -0
- package/.versions/0.0.4/docs/ARCHITECTURE.md +210 -0
- package/.versions/0.0.4/docs/agent-fleet-setup.md +366 -0
- package/.versions/0.0.4/docs/claude-code-coms-bridge.md +103 -0
- package/.versions/0.0.4/docs/codex-remote-conductor.md +170 -0
- package/.versions/0.0.4/docs/coms-hermes-bridge.md +121 -0
- package/.versions/0.0.4/docs/getting-started.md +183 -0
- package/.versions/0.0.4/docs/npm-install.md +337 -0
- package/.versions/0.0.4/docs/opencode-setup.md +248 -0
- package/.versions/0.0.4/docs/pi-extensions.md +288 -0
- package/.versions/0.0.4/docs/pi-setup.md +463 -0
- package/.versions/0.0.4/docs/skill-anatomy.md +150 -0
- package/.versions/0.0.4/hermes/README.md +228 -0
- package/.versions/0.0.4/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
- package/.versions/0.0.4/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-cap.test.py +15 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-discovery.test.py +19 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-envelope.test.py +13 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-forged-owner.test.py +11 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-lease-list.test.py +9 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-multihub.test.py +17 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter-output.test.py +34 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +151 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/adapter.test.py +39 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/plugin-api-validation.test.py +12 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
- package/.versions/0.0.4/hermes/plugins/agent-fleet-monitor/dashboard/review-live-wiring.red.test.py +22 -0
- package/.versions/0.0.4/hermes/skills/hub-conductor/SKILL.md +84 -0
- package/.versions/0.0.4/hermes/skills/hub-liaison/SKILL.md +84 -0
- package/.versions/0.0.4/hooks/SIMPLIFY-IGNORE.md +90 -0
- package/.versions/0.0.4/hooks/coms-stop-hook.mjs +73 -0
- package/.versions/0.0.4/hooks/hooks.json +14 -0
- package/.versions/0.0.4/hooks/session-start.sh +74 -0
- package/.versions/0.0.4/hooks/simplify-ignore.sh +302 -0
- package/.versions/0.0.4/justfile +256 -0
- package/.versions/0.0.4/references/accessibility-checklist.md +160 -0
- package/.versions/0.0.4/references/definition-of-done.md +67 -0
- package/.versions/0.0.4/references/fleet-coordination-patterns.md +151 -0
- package/.versions/0.0.4/references/observability-checklist.md +91 -0
- package/.versions/0.0.4/references/orchestration-patterns.md +370 -0
- package/.versions/0.0.4/references/performance-checklist.md +153 -0
- package/.versions/0.0.4/references/prompting-patterns.md +380 -0
- package/.versions/0.0.4/references/security-checklist.md +179 -0
- package/.versions/0.0.4/references/testing-patterns.md +236 -0
- package/.versions/0.0.4/scripts/codex-conductor.ts +41 -0
- package/.versions/0.0.4/scripts/codex-remote-control.ts +167 -0
- package/.versions/0.0.4/scripts/coms-claude-bridge.ts +286 -0
- package/.versions/0.0.4/scripts/coms-cli.ts +484 -0
- package/.versions/0.0.4/scripts/coms-hermes-bridge.ts +403 -0
- package/.versions/0.0.4/scripts/hermes-monitor-capability-runner.ts +25 -0
- package/.versions/0.0.4/scripts/hermes-monitor-scenario.ts +7 -0
- package/.versions/0.0.4/scripts/lib/claude-bridge-core.ts +100 -0
- package/.versions/0.0.4/scripts/lib/codex-conductor.ts +88 -0
- package/.versions/0.0.4/scripts/lib/codex-remote-control.ts +480 -0
- package/.versions/0.0.4/scripts/lib/coms-envelope.ts +539 -0
- package/.versions/0.0.4/scripts/lib/fake-herdr-server.ts +88 -0
- package/.versions/0.0.4/scripts/lib/herdr-layout.ts +263 -0
- package/.versions/0.0.4/scripts/lib/hermes-bridge-core.ts +238 -0
- package/.versions/0.0.4/scripts/lib/hermes-monitor-herdr.ts +28 -0
- package/.versions/0.0.4/scripts/lib/hermes-monitor-model.ts +9 -0
- package/.versions/0.0.4/scripts/lib/hermes-monitor-registry.ts +6 -0
- package/.versions/0.0.4/scripts/lib/hermes-monitor-socket.ts +118 -0
- package/.versions/0.0.4/scripts/lib/hermes-monitor-store.ts +31 -0
- package/.versions/0.0.4/scripts/lib/persona-banner.ts +62 -0
- package/.versions/0.0.4/scripts/lib/spawn-stagger.ts +101 -0
- package/.versions/0.0.4/scripts/lib/team-project.ts +184 -0
- package/.versions/0.0.4/scripts/lib/team-snapshot.ts +147 -0
- package/.versions/0.0.4/scripts/peer-banner.ts +40 -0
- package/.versions/0.0.4/scripts/team-snapshot.ts +238 -0
- package/.versions/0.0.4/scripts/team-up.ts +333 -0
- package/.versions/0.0.4/skills/_internal/grilling.md +11 -0
- package/.versions/0.0.4/skills/browser-testing-with-devtools/SKILL.md +352 -0
- package/.versions/0.0.4/skills/code-review-and-quality/SKILL.md +381 -0
- package/.versions/0.0.4/skills/compound-learning/SKILL.md +137 -0
- package/.versions/0.0.4/skills/context-engineering/SKILL.md +291 -0
- package/.versions/0.0.4/skills/deprecation-and-migration/SKILL.md +206 -0
- package/.versions/0.0.4/skills/designing-agents/SKILL.md +394 -0
- package/.versions/0.0.4/skills/designing-agents/pi-harness-authoring.md +222 -0
- package/.versions/0.0.4/skills/frontend-ui-engineering/SKILL.md +328 -0
- package/.versions/0.0.4/skills/git-workflow-and-versioning/SKILL.md +316 -0
- package/.versions/0.0.4/skills/guided-workspace-setup/SKILL.md +535 -0
- package/.versions/0.0.4/skills/guided-workspace-setup/companion-manifest.json +33 -0
- package/.versions/0.0.4/skills/idea-refine/SKILL.md +182 -0
- package/.versions/0.0.4/skills/idea-refine/examples.md +238 -0
- package/.versions/0.0.4/skills/idea-refine/frameworks.md +99 -0
- package/.versions/0.0.4/skills/idea-refine/refinement-criteria.md +113 -0
- package/.versions/0.0.4/skills/idea-refine/scripts/idea-refine.sh +15 -0
- package/.versions/0.0.4/skills/incremental-implementation/SKILL.md +287 -0
- package/.versions/0.0.4/skills/interview-me/SKILL.md +226 -0
- package/.versions/0.0.4/skills/orchestration-verification/SKILL.md +181 -0
- package/.versions/0.0.4/skills/peer-coms/SKILL.md +90 -0
- package/.versions/0.0.4/skills/performance-optimization/SKILL.md +350 -0
- package/.versions/0.0.4/skills/planning-and-task-breakdown/SKILL.md +236 -0
- package/.versions/0.0.4/skills/security-and-hardening/SKILL.md +461 -0
- package/.versions/0.0.4/skills/spec-driven-development/SKILL.md +245 -0
- package/.versions/0.0.4/skills/using-agent-skills/SKILL.md +199 -0
- package/.versions/0.0.4/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/LICENSE +21 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/README.md +11 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
- package/.versions/0.0.4/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
- package/CHANGELOG.md +53 -0
- package/README.md +3 -3
- package/agents/builder.md +1 -1
- package/agents/code-reviewer.md +1 -1
- package/agents/deep-researcher.md +3 -3
- package/agents/orchestrator.md +20 -11
- package/agents/plan-reviewer.md +3 -3
- package/agents/test-engineer.md +11 -4
- package/bin/lib/validate-overrides.js +19 -0
- package/bin/sync-harness-versions.js +94 -0
- package/docs/ARCHITECTURE.md +46 -1
- package/docs/agent-fleet-setup.md +10 -0
- package/docs/pi-extensions.md +49 -14
- package/docs/pi-setup.md +10 -4
- package/hermes/README.md +180 -0
- package/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
- package/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-cap.test.py +15 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-discovery.test.py +19 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-envelope.test.py +13 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-forged-owner.test.py +11 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-lease-list.test.py +9 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-multihub.test.py +17 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter-output.test.py +34 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +151 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/adapter.test.py +39 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/dist/index.js +10 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/plugin-api-validation.test.py +12 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
- package/hermes/plugins/agent-fleet-monitor/dashboard/review-live-wiring.red.test.py +22 -0
- package/justfile +6 -10
- package/package.json +9 -4
- package/scripts/lib/fake-herdr-server.ts +88 -0
- package/scripts/lib/hermes-monitor-herdr.ts +28 -0
- package/scripts/lib/hermes-monitor-model.ts +9 -0
- package/scripts/lib/hermes-monitor-registry.ts +6 -0
- package/scripts/lib/hermes-monitor-socket.ts +118 -0
- package/scripts/lib/hermes-monitor-store.ts +31 -0
- package/skills/designing-agents/SKILL.md +2 -2
- package/skills/designing-agents/pi-harness-authoring.md +26 -13
- package/skills/guided-workspace-setup/SKILL.md +11 -8
- package/.pi/harnesses/damage-control/README.md +0 -65
- package/.pi/harnesses/damage-control/index.ts +0 -250
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
# coms Hermes bridge
|
|
2
|
+
|
|
3
|
+
Protocol contract for the Hermes ⇄ pi `coms` bridge. The first implemented daemon is `scripts/coms-hermes-bridge.ts`, which registers a `user-remote` peer and turns coms prompt envelopes into Hermes/Telegram questions.
|
|
4
|
+
|
|
5
|
+
## Pieces
|
|
6
|
+
|
|
7
|
+
| Piece | Role |
|
|
8
|
+
| --- | --- |
|
|
9
|
+
| `scripts/coms-hermes-bridge.ts` | Daemon peer, default name `user-remote`, purpose `Remote human via Hermes/Telegram`. Accepts prompt, cancel, and ping envelopes. |
|
|
10
|
+
| `scripts/lib/hermes-bridge-core.ts` | Pure contract logic: qid validation, Telegram formatting, answer-file validation, answer mapping, timeout outcome, state transitions, and log records. |
|
|
11
|
+
| `scripts/lib/coms-envelope.ts` | Shared non-pi envelope wire shapes, including additive `cancel` envelopes. |
|
|
12
|
+
| `~/.pi/coms/hermes-bridge/questions/` | Private answer-file wire written by the Hermes gateway/liaison. |
|
|
13
|
+
| `~/.pi/coms/hermes-bridge/log.ndjson` | Bridge observability log. |
|
|
14
|
+
|
|
15
|
+
## user-remote topology
|
|
16
|
+
|
|
17
|
+
1. A pi peer sends a coms `prompt` envelope to `user-remote`.
|
|
18
|
+
2. The bridge derives `qid` from `prompt.msg_id`, formats the question, and runs `hermes send --to <target> <message>` (`<target>` defaults to `telegram`).
|
|
19
|
+
3. The human replies in Telegram; the Hermes gateway/liaison writes the answer file.
|
|
20
|
+
4. The bridge polls the questions directory, validates the file, maps the answer, sends a coms `response` envelope, and removes the answer file.
|
|
21
|
+
|
|
22
|
+
## Protocol contract v1
|
|
23
|
+
|
|
24
|
+
### qid and correlation
|
|
25
|
+
|
|
26
|
+
`qid` is exactly the prompt envelope's `msg_id`. It must match the 26-character Crockford ULID regex `^[0-9A-HJKMNP-TV-Z]{26}$`. The same `qid` is the only correlation key across coms, Telegram, answer files, state, and logs.
|
|
27
|
+
|
|
28
|
+
### Telegram question format
|
|
29
|
+
|
|
30
|
+
`formatTelegramQuestion` emits UTF-16 text capped at 4096 code units:
|
|
31
|
+
|
|
32
|
+
```text
|
|
33
|
+
❓ [HUB-Q:<qid>] <question>
|
|
34
|
+
|
|
35
|
+
Context: <context, truncated if needed>
|
|
36
|
+
|
|
37
|
+
Options:
|
|
38
|
+
1. <title> — <description>
|
|
39
|
+
...
|
|
40
|
+
|
|
41
|
+
↩ Reply to this message, or type: HUB-Q:<qid>: <answer>
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`Context:` is omitted when absent. `Options:` is omitted when no options are supplied. Context receives the remaining budget after the header, options, and reply instruction.
|
|
45
|
+
|
|
46
|
+
### Answer-file path, schema, and validation
|
|
47
|
+
|
|
48
|
+
The private wire path is:
|
|
49
|
+
|
|
50
|
+
```text
|
|
51
|
+
~/.pi/coms/hermes-bridge/questions/<qid>.answer.json
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
Schema:
|
|
55
|
+
|
|
56
|
+
```json
|
|
57
|
+
{
|
|
58
|
+
"qid": "<26-character Crockford ULID>",
|
|
59
|
+
"answer": "<text>",
|
|
60
|
+
"answered_by": "telegram:<user>",
|
|
61
|
+
"at": "<ISO timestamp>"
|
|
62
|
+
}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Validation rejects and ignores files unless all conditions hold: filename ends in `.answer.json`; filename qid is valid; filename qid is currently pending; JSON parses; object fields match the schema; `at` parses as a timestamp; and body `qid` equals the filename qid. Rejection reasons are `invalid_path`, `invalid_qid`, `foreign_qid`, `invalid_json`, `invalid_schema`, and `qid_mismatch`; the daemon logs rejected files as `answer_rejected` and removes them. Exception: an `invalid_json` file is treated as a possible partial write and left in place for a short grace window (`max(2 × poll interval, 1s)` from first sighting); it is rejected and removed only if it still fails to parse after the grace expires.
|
|
66
|
+
|
|
67
|
+
### Answer mapping
|
|
68
|
+
|
|
69
|
+
If options exist and the trimmed answer is a 1-based number for an option, the response is `{ "kind": "selection", "selections": ["<option title>"] }`. If options exist and the trimmed answer case-insensitively equals an option title, it maps to the same selection shape. All other answers map to `{ "kind": "freeform", "text": "<trimmed answer>" }`.
|
|
70
|
+
|
|
71
|
+
### Cancel semantics
|
|
72
|
+
|
|
73
|
+
`cancel` is an additive coms envelope with shape `{ "type": "cancel", "msg_id", "from", "to", "created_at", "ref_msg_id" }`; `ref_msg_id` is the target `qid`. The bridge acks well-formed cancel envelopes before handling them.
|
|
74
|
+
|
|
75
|
+
For a pending qid, cancel clears the timeout, removes the pending question, records terminal state `cancelled`, appends a `cancelled` log event, and sends a Telegram note: `✖ [HUB-Q:<qid>] The question was cancelled — it was answered from the console.` Cancel for a non-pending or invalid qid is a no-op after the envelope ack. A later answer file for a closed qid is treated as `late_answer`: logged, removed, and answered in Telegram with a polite ignored note; no response envelope is sent.
|
|
76
|
+
|
|
77
|
+
### Timeouts
|
|
78
|
+
|
|
79
|
+
The per-question remote timeout defaults to `PI_COMS_TIMEOUT_MS`, or `1800000` ms when unset/invalid; `--timeout <ms>` overrides it. On timeout, the bridge removes the pending question, records terminal state `timeout`, logs `timeout`, sends the Telegram note `⌛ [HUB-Q:<qid>] The question timed out after <ms>ms.`, and sends an error response envelope with error `no remote answer within <ms>ms` and `response: null`.
|
|
80
|
+
|
|
81
|
+
### States
|
|
82
|
+
|
|
83
|
+
Question states are in-memory per qid: `pending`, `delivered`, `answered`, `cancelled`, and `timeout`. Implemented transitions are: `null + question_received → pending`; `pending + delivered → delivered`; `pending + delivery_error → null`; `pending|delivered + answered → answered` (the daemon currently answers from delivered or pending if the file arrives quickly); `pending|delivered + cancelled → cancelled`; `pending|delivered + timeout → timeout`; and terminal `answered|cancelled|timeout + late_answer` remains terminal.
|
|
84
|
+
|
|
85
|
+
### ndjson logging
|
|
86
|
+
|
|
87
|
+
The bridge appends one JSON object per line to `~/.pi/coms/hermes-bridge/log.ndjson`. Core log records have shape `{ "at": "<ISO>", "qid": "<qid>", "event": "<event>", "detail"?: <value> }`. Contract events are `question_received`, `delivered`, `delivery_error`, `answered`, `cancelled`, `timeout`, and `late_answer`; the daemon also writes `answer_rejected` for invalid answer files. Ping agent cards report `queue_depth` as the current number of pending questions.
|
|
88
|
+
|
|
89
|
+
## Hermes as conductor
|
|
90
|
+
|
|
91
|
+
Hermes can also act as the conductor without this daemon: use `coms-cli list` to discover peers and `coms-cli send --await --timeout <ms>` to delegate to hub-team pi peers, then synthesize the results for the human. This conductor topology uses the existing coms CLI as the bridge; no standing Hermes peer is required.
|
|
92
|
+
|
|
93
|
+
Launch a visible conductor workspace with:
|
|
94
|
+
|
|
95
|
+
```bash
|
|
96
|
+
just conductor docs # live herdr workspace: conductor pane + docs team panes
|
|
97
|
+
just conductor-dry docs # no herdr calls; prints the planned layout JSON
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The live recipe reuses `scripts/team-up.ts --conductor`: it creates a normal herdr workspace labeled `<worktree-tag>-conductor-<team>` (the tag is the last dot-segment of the checkout's basename, so the same team from a different worktree gets its own workspace), places a `conductor` pane running `hermes -p dev`, and tiles the chosen team beside it. Team peers keep their normal coms harness and herdr presence reporting, so they continue to show agent state in the sidebar; Hermes' own herdr-agent-state plugin is responsible for the conductor pane's state.
|
|
101
|
+
|
|
102
|
+
Hard boundary: the Hermes conductor must not run `herdr` commands, drive panes, create/kill workspaces, or manage fleet lifecycle. Herdr driving stays with the human/orchestrator so the damage-control model remains intact; see `.pi/damage-control-rules.yaml` for the authoritative no-herdr boundary. Hermes may only operate inside the project coms pool through the documented coms CLI commands.
|
|
103
|
+
|
|
104
|
+
## Hermes and the experimental Codex conductor
|
|
105
|
+
|
|
106
|
+
Hermes/Telegram remains the **inbound** human `ask_user` complement to the
|
|
107
|
+
experimental Codex remote-control conductor. Codex is outbound-initiated,
|
|
108
|
+
approval-gated, and serialized; it is not an inbound question channel. The Codex user service and control-pane lifecycle are
|
|
109
|
+
separate from Hermes. See the [experimental Codex operator runbook](codex-remote-conductor.md).
|
|
110
|
+
|
|
111
|
+
Both conductor contracts are advisory outside Pi damage-control: Pi wraps Pi
|
|
112
|
+
tool calls, not Hermes or Codex, and neither has an OS command allowlist.
|
|
113
|
+
Human confirmation, approvals, and sandboxing reduce risk but do not
|
|
114
|
+
technically enforce either external contract.
|
|
115
|
+
|
|
116
|
+
## Deferred
|
|
117
|
+
|
|
118
|
+
- Standing conductor peer for pi → Hermes inbound messages.
|
|
119
|
+
- Telegram-driven conductor profile.
|
|
120
|
+
- Group/multi-recipient questions and non-text answers.
|
|
121
|
+
- Kanban-driven orchestration on top of the same conductor contract.
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
# Getting Started with agent-fleet
|
|
2
|
+
|
|
3
|
+
agent-fleet works with any AI coding agent that accepts Markdown instructions. This guide covers the universal approach. For tool-specific setup, see the dedicated guides.
|
|
4
|
+
|
|
5
|
+
## How Skills Work
|
|
6
|
+
|
|
7
|
+
Each skill is a Markdown file (`SKILL.md`) that describes a specific engineering workflow. When loaded into an agent's context, the agent follows the workflow — including verification steps, anti-patterns to avoid, and exit criteria.
|
|
8
|
+
|
|
9
|
+
**Skills are not reference docs.** They're step-by-step processes the agent follows.
|
|
10
|
+
|
|
11
|
+
## Install path — which one fits you?
|
|
12
|
+
|
|
13
|
+
| Audience | Path | Why |
|
|
14
|
+
|---|---|---|
|
|
15
|
+
| **Most users** — you want to use the skills in your projects | `npx @chankov/agent-fleet init` | One command; semver updates; cross-platform; no source dir to babysit. See [docs/npm-install.md](npm-install.md). |
|
|
16
|
+
| **Claude Code users** — you live in Claude Code and want plugin-managed updates | `/plugin marketplace add chankov/agent-fleet` | Best UX inside Claude Code; marketplace handles the lifecycle. |
|
|
17
|
+
| **Skill authors / contributors** — you want to edit the skills and have changes flow into every connected workspace | `git clone` + `symlink` mode in `/setup-agent-fleet` | Edit-in-place; every connected workspace sees the change instantly. |
|
|
18
|
+
|
|
19
|
+
All three converge on the same `guided-workspace-setup` skill — they only differ in how the source files reach your workspace. None is being deprecated.
|
|
20
|
+
|
|
21
|
+
## Optional experimental Android conductor
|
|
22
|
+
|
|
23
|
+
Linux/pi fleet users can pair Codex Remote Control with ChatGPT Android and delegate one approval-gated task at a time to peers already running in a coms project. It is optional, supports only Codex CLI `0.144.x`, requires Node `22.6+` and user systemd, and does not replace Hermes as the inbound `ask_user` route.
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
cd /path/to/agent-fleet
|
|
27
|
+
just conductor-codex-setup docs --project af
|
|
28
|
+
just conductor-codex-pair
|
|
29
|
+
just conductor-codex-start
|
|
30
|
+
just hub-team docs --project af
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
The runtime contract is generated under `$HOME/.local/state/agent-fleet/codex-conductor/`, outside the checkout. Pairing is interactive secret-bearing output and must never be captured. Read the complete [Codex conductor runbook](codex-remote-conductor.md) before enabling the service.
|
|
34
|
+
|
|
35
|
+
## Quick Start (Any Agent)
|
|
36
|
+
|
|
37
|
+
### 1. Clone the repository
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
git clone https://github.com/chankov/agent-fleet.git
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
> Skip this step if you installed via npm — the package contents are already
|
|
44
|
+
> in `node_modules/agent-fleet/`. Use that path wherever this guide refers to
|
|
45
|
+
> "the agent-fleet repo."
|
|
46
|
+
|
|
47
|
+
### 2. Choose a skill
|
|
48
|
+
|
|
49
|
+
Browse the `skills/` directory. Each subdirectory contains a `SKILL.md` with:
|
|
50
|
+
- **When to use** — triggers that indicate this skill applies
|
|
51
|
+
- **Process** — step-by-step workflow
|
|
52
|
+
- **Verification** — how to confirm the work is done
|
|
53
|
+
- **Common rationalizations** — excuses the agent might use to skip steps
|
|
54
|
+
- **Red flags** — signs the skill is being violated
|
|
55
|
+
|
|
56
|
+
### 3. Load the skill into your agent
|
|
57
|
+
|
|
58
|
+
Copy the relevant `SKILL.md` content into your agent's system prompt, rules file, or conversation. The most common approaches:
|
|
59
|
+
|
|
60
|
+
**System prompt:** Paste the skill content at the start of the session.
|
|
61
|
+
|
|
62
|
+
**Rules file:** Add skill content to your project's rules file (CLAUDE.md, AGENTS.md, etc.).
|
|
63
|
+
|
|
64
|
+
**Conversation:** Reference the skill when giving instructions: "Follow the test-driven-development process for this change."
|
|
65
|
+
|
|
66
|
+
### 4. Use the meta-skill for discovery
|
|
67
|
+
|
|
68
|
+
Start with the `using-agent-skills` skill loaded. It contains a flowchart that maps task types to the appropriate skill.
|
|
69
|
+
|
|
70
|
+
## Recommended Setup
|
|
71
|
+
|
|
72
|
+
### Minimal (Start here)
|
|
73
|
+
|
|
74
|
+
Load three essential skills into your rules file:
|
|
75
|
+
|
|
76
|
+
1. **spec-driven-development** — For defining what to build
|
|
77
|
+
2. **test-driven-development** — For proving it works
|
|
78
|
+
3. **code-review-and-quality** — For verifying quality before merge
|
|
79
|
+
|
|
80
|
+
These three cover the most critical quality gaps in AI-assisted development.
|
|
81
|
+
|
|
82
|
+
### Full Lifecycle
|
|
83
|
+
|
|
84
|
+
For comprehensive coverage, load skills by phase:
|
|
85
|
+
|
|
86
|
+
```
|
|
87
|
+
Starting a project: spec-driven-development → planning-and-task-breakdown
|
|
88
|
+
During development: incremental-implementation + test-driven-development
|
|
89
|
+
Before merge: code-review-and-quality + security-and-hardening
|
|
90
|
+
Before deploy: shipping-and-launch
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
### Context-Aware Loading
|
|
94
|
+
|
|
95
|
+
Don't load all skills at once — it wastes context. Load skills relevant to the current task:
|
|
96
|
+
|
|
97
|
+
- Working on UI? Load `frontend-ui-engineering`
|
|
98
|
+
- Debugging? Load `debugging-and-error-recovery`
|
|
99
|
+
- Setting up CI? Load `ci-cd-and-automation`
|
|
100
|
+
|
|
101
|
+
## Skill Anatomy
|
|
102
|
+
|
|
103
|
+
Every skill follows the same structure:
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
YAML frontmatter (name, description)
|
|
107
|
+
├── Overview — What this skill does
|
|
108
|
+
├── When to Use — Triggers and conditions
|
|
109
|
+
├── Core Process — Step-by-step workflow
|
|
110
|
+
├── Examples — Code samples and patterns
|
|
111
|
+
├── Common Rationalizations — Excuses and rebuttals
|
|
112
|
+
├── Red Flags — Signs the skill is being violated
|
|
113
|
+
└── Verification — Exit criteria checklist
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
See [skill-anatomy.md](skill-anatomy.md) for the full specification.
|
|
117
|
+
|
|
118
|
+
## Using Agents
|
|
119
|
+
|
|
120
|
+
The `agents/` directory contains pre-configured agent personas:
|
|
121
|
+
|
|
122
|
+
| Agent | Purpose |
|
|
123
|
+
|-------|---------|
|
|
124
|
+
| `code-reviewer.md` | Five-axis code review (read-only) |
|
|
125
|
+
| `test-engineer.md` | Test strategy and writing |
|
|
126
|
+
| `security-auditor.md` | Vulnerability detection (read-only) |
|
|
127
|
+
| `web-performance-auditor.md` | Core Web Vitals & performance audit (read-only, via `/webperf`) |
|
|
128
|
+
| `planner.md` | Numbered implementation plans (read-only) |
|
|
129
|
+
| `plan-reviewer.md` | Critiques and validates plans (read-only) |
|
|
130
|
+
| `builder.md` | Implements an approved plan |
|
|
131
|
+
| `documenter.md` | READMEs and inline docs |
|
|
132
|
+
|
|
133
|
+
Load an agent definition when you need specialized review. For example, ask your coding agent to "review this change using the code-reviewer agent persona" and provide the agent definition.
|
|
134
|
+
|
|
135
|
+
## Using Commands
|
|
136
|
+
|
|
137
|
+
The `.claude/commands/` directory contains slash commands for Claude Code:
|
|
138
|
+
|
|
139
|
+
| Command | Skill Invoked |
|
|
140
|
+
|---------|---------------|
|
|
141
|
+
| `/setup-agent-fleet` | guided-workspace-setup |
|
|
142
|
+
| `/spec` | spec-driven-development |
|
|
143
|
+
| `/plan` | planning-and-task-breakdown |
|
|
144
|
+
| `/build` | incremental-implementation + test-driven-development |
|
|
145
|
+
| `/build auto` | planning-and-task-breakdown → incremental-implementation + test-driven-development (whole plan, one approval) |
|
|
146
|
+
| `/test` | test-driven-development |
|
|
147
|
+
| `/review` | code-review-and-quality |
|
|
148
|
+
| `/code-simplify` | code-simplification |
|
|
149
|
+
| `/ship` | shipping-and-launch |
|
|
150
|
+
| `/webperf` | web-performance-auditor (specialist agent, web apps only) |
|
|
151
|
+
|
|
152
|
+
## Using References
|
|
153
|
+
|
|
154
|
+
The `references/` directory contains supplementary checklists:
|
|
155
|
+
|
|
156
|
+
| Reference | Use With |
|
|
157
|
+
|-----------|----------|
|
|
158
|
+
| `testing-patterns.md` | test-driven-development |
|
|
159
|
+
| `performance-checklist.md` | performance-optimization |
|
|
160
|
+
| `security-checklist.md` | security-and-hardening |
|
|
161
|
+
| `accessibility-checklist.md` | frontend-ui-engineering |
|
|
162
|
+
| `definition-of-done.md` | incremental-implementation, planning-and-task-breakdown |
|
|
163
|
+
| `observability-checklist.md` | observability-and-instrumentation |
|
|
164
|
+
| `orchestration-patterns.md` | orchestration-verification, designing-agents |
|
|
165
|
+
| `prompting-patterns.md` | context-engineering |
|
|
166
|
+
|
|
167
|
+
Load a reference when you need detailed patterns beyond what the skill covers.
|
|
168
|
+
|
|
169
|
+
## Spec and task artifacts
|
|
170
|
+
|
|
171
|
+
The `/spec` and `/plan` commands create working artifacts (`SPEC.md`, `tasks/plan.md`, `tasks/todo.md`). Treat them as **living documents** while the work is in progress:
|
|
172
|
+
|
|
173
|
+
- Keep them in version control during development so the human and the agent have a shared source of truth.
|
|
174
|
+
- Update them when scope or decisions change.
|
|
175
|
+
- If your repo doesn’t want these files long‑term, delete them before merge or add the folder to `.gitignore` — the workflow doesn’t require them to be permanent.
|
|
176
|
+
|
|
177
|
+
## Tips
|
|
178
|
+
|
|
179
|
+
1. **Start with spec-driven-development** for any non-trivial work
|
|
180
|
+
2. **Always load test-driven-development** when writing code
|
|
181
|
+
3. **Don't skip verification steps** — they're the whole point
|
|
182
|
+
4. **Load skills selectively** — more context isn't always better
|
|
183
|
+
5. **Use the agents for review** — different perspectives catch different issues
|
|
@@ -0,0 +1,337 @@
|
|
|
1
|
+
# npm install path
|
|
2
|
+
|
|
3
|
+
The `@chankov/agent-fleet` package ships every skill, persona, slash command,
|
|
4
|
+
and pi extension as installable content, plus a thin CLI that hands off to the
|
|
5
|
+
LLM-driven `guided-workspace-setup` skill. The CLI never writes installable
|
|
6
|
+
artifacts on its own — that decision (and the conversation around it) belongs
|
|
7
|
+
to the coding agent.
|
|
8
|
+
|
|
9
|
+
## Package name vs CLI name
|
|
10
|
+
|
|
11
|
+
| | Name |
|
|
12
|
+
|---|---|
|
|
13
|
+
| **npm package** (use this for `npm install` and the first `npx`) | `@chankov/agent-fleet` |
|
|
14
|
+
| **CLI binary** (the command the package ships) | `agent-fleet` |
|
|
15
|
+
|
|
16
|
+
The package is published under the `@chankov` npm scope to guarantee identity —
|
|
17
|
+
only [Nikolay Chankov](https://www.npmjs.com/~chankov) can publish to that
|
|
18
|
+
scope. The CLI binary stays the short name `agent-fleet` because that's what
|
|
19
|
+
goes on `PATH` after install.
|
|
20
|
+
|
|
21
|
+
So:
|
|
22
|
+
|
|
23
|
+
- First time / one-shot: `npx @chankov/agent-fleet <cmd>` — npx resolves the
|
|
24
|
+
scoped package and runs its bin.
|
|
25
|
+
- After a project / global install: `npx agent-fleet <cmd>` works too,
|
|
26
|
+
because the bin is named `agent-fleet`.
|
|
27
|
+
|
|
28
|
+
## Quick start
|
|
29
|
+
|
|
30
|
+
### Guided workspace setup
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
# In the workspace you want to configure:
|
|
34
|
+
npx @chankov/agent-fleet init
|
|
35
|
+
# Then open your coding agent in this directory and run:
|
|
36
|
+
# /setup-agent-fleet
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
That's it. `npx` fetches the package, the CLI detects your coding agent and
|
|
40
|
+
prints the next-step command, and `/setup-agent-fleet` runs the full guided install
|
|
41
|
+
inside your agent.
|
|
42
|
+
|
|
43
|
+
### First-class pi package
|
|
44
|
+
|
|
45
|
+
For pi users who want package-native loading instead of copied/symlinked setup artifacts:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
# Project-scoped; writes .pi/settings.json
|
|
49
|
+
pi install -l npm:@chankov/agent-fleet
|
|
50
|
+
|
|
51
|
+
# Or global for every pi session
|
|
52
|
+
pi install npm:@chankov/agent-fleet
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
The pi package manifest exposes this repo's skills, pi runtime skills, lifecycle prompts, and bundled `pi-ask-user` resources. The bundled companion provides the `ask_user` tool and `ask-user` skill without a separate `pi-ask-user` install.
|
|
56
|
+
|
|
57
|
+
It intentionally does not auto-expose this repo's own `.pi/extensions` or harness directories; install those through guided setup or the pi setup docs so their runtime dependencies are handled explicitly. `pi-codex-image-gen` is also not bundled or required; guided setup may offer it as an optional suggested external npm/pi package when package installation is available, and installs it only if selected (`pi install -l npm:pi-codex-image-gen`). Minimal setup works without it.
|
|
58
|
+
|
|
59
|
+
The package also ships assets for the **experimental Linux Codex Remote-Control conductor** (`codex/`, `systemd/`, lifecycle/wrapper scripts, recipes, and runbook). Guided setup copies or links those assets with selected pi harnesses but never enables systemd, edits Codex config, starts a service, or pairs a phone. Those remain explicit operator actions and support only Codex CLI `0.144.x`; see [codex-remote-conductor.md](codex-remote-conductor.md). Its managed runtime contract is created later under `$HOME/.local/state/agent-fleet/codex-conductor/`, not inside the npm package or target checkout.
|
|
60
|
+
|
|
61
|
+
## Commands
|
|
62
|
+
|
|
63
|
+
### `npx @chankov/agent-fleet init`
|
|
64
|
+
|
|
65
|
+
Materializes the package, **bootstraps the installer artifacts** into the
|
|
66
|
+
workspace (so the agent has a `/setup-agent-fleet` and `/doctor-agent-fleet` command to invoke),
|
|
67
|
+
and hands off to `/setup-agent-fleet`.
|
|
68
|
+
|
|
69
|
+
What `init` writes per agent:
|
|
70
|
+
|
|
71
|
+
| Agent | Files written to the workspace |
|
|
72
|
+
|---|---|
|
|
73
|
+
| `claude-code` | `.claude/commands/setup-agent-fleet.md`, `.claude/commands/doctor-agent-fleet.md`, `.claude/skills/guided-workspace-setup/SKILL.md` |
|
|
74
|
+
| `pi` | `.pi/prompts/setup-agent-fleet.md`, `.pi/prompts/doctor-agent-fleet.md`, `.pi/skills/guided-workspace-setup/SKILL.md` |
|
|
75
|
+
| `opencode` | `.opencode/commands/af-setup-agent-fleet.md`, `.opencode/commands/af-doctor-agent-fleet.md`, `.opencode/skills/guided-workspace-setup/SKILL.md` |
|
|
76
|
+
|
|
77
|
+
These are **just the plumbing** — the slash commands, plus the skill they
|
|
78
|
+
invoke. The actual catalogue (spec-driven-development, code-reviewer,
|
|
79
|
+
test-engineer, pi extensions, …) is picked by you inside `/setup-agent-fleet`. Re-run
|
|
80
|
+
`init` to refresh the plumbing after a package upgrade; bootstrap files
|
|
81
|
+
are always overwritten because they're scaffolding, not user data.
|
|
82
|
+
|
|
83
|
+
After `/setup-agent-fleet` finishes its install pass, **the bootstrap files
|
|
84
|
+
are removed by default** so they don't clutter your agent's slash-command
|
|
85
|
+
list. Re-run `npx @chankov/agent-fleet init` whenever you want
|
|
86
|
+
`/setup-agent-fleet` back. To keep them in place across runs, reply `keep`
|
|
87
|
+
to the Step 9 confirmation prompt — the skill will record
|
|
88
|
+
`keep-installer: true` in `.ai/agent-fleet-setup.md`.
|
|
89
|
+
|
|
90
|
+
### How the skill finds the source package
|
|
91
|
+
|
|
92
|
+
`init` writes one extra file alongside the bootstrap: `.ai/.agent-fleet-bootstrap.json`.
|
|
93
|
+
This is the **authoritative** record of where the npm package lives:
|
|
94
|
+
|
|
95
|
+
```json
|
|
96
|
+
{
|
|
97
|
+
"sourceRoot": "/home/you/.npm/_npx/<hash>/node_modules/@chankov/agent-fleet",
|
|
98
|
+
"version": "0.3.0",
|
|
99
|
+
"agent": "pi",
|
|
100
|
+
"method": "copy",
|
|
101
|
+
"bootstrappedAt": "2026-05-24T..."
|
|
102
|
+
}
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
When `/setup-agent-fleet` runs inside your agent, it reads this marker
|
|
106
|
+
*first* to find the source package. This matters on dev machines where you
|
|
107
|
+
may also have a git clone of `agent-fleet` elsewhere — the marker prevents
|
|
108
|
+
the skill from accidentally using that clone instead of the version the
|
|
109
|
+
user just installed via npm.
|
|
110
|
+
|
|
111
|
+
If the marker is missing or its `sourceRoot` no longer exists (e.g. npx
|
|
112
|
+
cleaned its cache), the skill **asks you explicitly** for the path. It
|
|
113
|
+
never scans your filesystem for other agent-fleet repos — that would
|
|
114
|
+
silently pick up forks, stale checkouts, or dev clones that aren't what
|
|
115
|
+
you installed.
|
|
116
|
+
|
|
117
|
+
The marker is removed by the same Step 10b cleanup that removes the
|
|
118
|
+
slash commands.
|
|
119
|
+
|
|
120
|
+
| Flag | Default | Purpose |
|
|
121
|
+
|------|---------|---------|
|
|
122
|
+
| `--agent <claude-code\|opencode\|pi>` | auto-detect | Skip the agent prompt |
|
|
123
|
+
| `--method <copy\|symlink>` | `copy` | Default install method passed to the skill |
|
|
124
|
+
| `--workspace <path>` | `cwd` | Target workspace |
|
|
125
|
+
| `--launch` | off | Shell into the coding agent after init (best effort) |
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
npx @chankov/agent-fleet init --agent claude-code
|
|
129
|
+
npx @chankov/agent-fleet init --workspace ~/projects/foo --method symlink
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### `npx @chankov/agent-fleet doctor`
|
|
133
|
+
|
|
134
|
+
Deterministic preflight scan — walks every install-target directory, lists
|
|
135
|
+
broken symlinks and stale persona references, and offers fixes. Same scan
|
|
136
|
+
that `/doctor-agent-fleet` runs inside the agent.
|
|
137
|
+
|
|
138
|
+
| Flag | Default | Purpose |
|
|
139
|
+
|------|---------|---------|
|
|
140
|
+
| `--workspace <path>` | `cwd` | Target workspace |
|
|
141
|
+
| `--dry-run` | off | Show findings; do not apply |
|
|
142
|
+
| `--yes` / `-y` | off | Apply all suggested fixes without prompting |
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
npx @chankov/agent-fleet doctor --workspace ~/projects/foo --dry-run
|
|
146
|
+
npx @chankov/agent-fleet doctor -y
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### `npx @chankov/agent-fleet update`
|
|
150
|
+
|
|
151
|
+
Reads the workspace's `.ai/agent-fleet-setup.md`, compares the recorded
|
|
152
|
+
package version against the installed package version, and **re-installs the
|
|
153
|
+
`/setup-agent-fleet` command** so it is always available after an update.
|
|
154
|
+
`guided-workspace-setup` removes the installer command at the end of a run by
|
|
155
|
+
default (Step 10b), so a workspace that has completed setup once would
|
|
156
|
+
otherwise have no command to hand off to. The actual diff-aware refresh then
|
|
157
|
+
runs inside the coding agent via `/setup-agent-fleet`.
|
|
158
|
+
|
|
159
|
+
The agent and install method are recovered from the bootstrap marker written
|
|
160
|
+
at init time; if that marker was cleaned up too, `update` auto-detects the
|
|
161
|
+
agent (and prompts only when the workspace has more than one agent dir).
|
|
162
|
+
Override with `--agent` / `--method`, or preview with `--dry-run`.
|
|
163
|
+
|
|
164
|
+
```bash
|
|
165
|
+
# Upgrade the package itself first, then check the delta:
|
|
166
|
+
npm install -g @chankov/agent-fleet@latest
|
|
167
|
+
npx agent-fleet update --workspace .
|
|
168
|
+
# /setup-agent-fleet is now back in your workspace — open your agent and run
|
|
169
|
+
# it to review per-artifact diffs.
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
### `npx @chankov/agent-fleet transform-persona`
|
|
173
|
+
|
|
174
|
+
Generates per-agent subagent definitions from the canonical personas in
|
|
175
|
+
`agents/*.md`. `pi` gets the canonical file unchanged; `claude-code` and
|
|
176
|
+
`opencode` get a transformed copy — `tools`/`model` translated to the target's
|
|
177
|
+
vocabulary (`read→Read`, `find/ls→Glob`, `claude-opus-*→opus`, …; `mode:
|
|
178
|
+
subagent` + tool denials for OpenCode), agent-hub-only frontmatter dropped,
|
|
179
|
+
body untouched. pi-only personas (`bowser`, `orchestrator`) are refused for
|
|
180
|
+
other agents. This is what
|
|
181
|
+
`/setup-agent-fleet` runs during apply; transformed installs are always
|
|
182
|
+
copies (never symlinks), recorded with `transformed: true`.
|
|
183
|
+
|
|
184
|
+
| Flag | Default | Purpose |
|
|
185
|
+
|------|---------|---------|
|
|
186
|
+
| `--agent <claude-code\|opencode\|pi>` | — (required) | Target agent |
|
|
187
|
+
| `--list` | off | Print the availability matrix (persona → target path) |
|
|
188
|
+
| `--all` | off | Transform every available persona |
|
|
189
|
+
| `--workspace <path>` | — | Write into `<path>`; omit to print to stdout |
|
|
190
|
+
| `--dry-run` | off | With `--workspace`: show what would be written |
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
npx @chankov/agent-fleet transform-persona --list --agent claude-code
|
|
194
|
+
npx @chankov/agent-fleet transform-persona --agent claude-code code-reviewer
|
|
195
|
+
npx @chankov/agent-fleet transform-persona --agent opencode --all --workspace .
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
## Versioning
|
|
199
|
+
|
|
200
|
+
The package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html):
|
|
201
|
+
|
|
202
|
+
| Change | Bump |
|
|
203
|
+
|---|---|
|
|
204
|
+
| Skill removed, renamed, or its documented workflow changes; persona retired; command removed; install-record schema breakage | **major** |
|
|
205
|
+
| New skill, new persona, new command, new option in an existing skill | **minor** |
|
|
206
|
+
| Wording fix, doctor scan improvement, CLI bug fix | **patch** |
|
|
207
|
+
|
|
208
|
+
### Pinning
|
|
209
|
+
|
|
210
|
+
To pin a workspace to a specific version, install the package as a project
|
|
211
|
+
dependency instead of using `npx`:
|
|
212
|
+
|
|
213
|
+
```bash
|
|
214
|
+
npm install --save-dev @chankov/agent-fleet@0.0.1
|
|
215
|
+
npx agent-fleet init # resolves to the pinned 0.0.1
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Or pin globally:
|
|
219
|
+
|
|
220
|
+
```bash
|
|
221
|
+
npm install -g @chankov/agent-fleet@0.0.1
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
### What "update" actually changes
|
|
225
|
+
|
|
226
|
+
The package update is just `npm`'s usual upgrade. The interesting part runs
|
|
227
|
+
inside the agent: `guided-workspace-setup` reads the `version:` line from
|
|
228
|
+
`.ai/agent-fleet-setup.md`, computes the delta against the current package
|
|
229
|
+
version, and surfaces per-artifact `Status` based on a three-way diff:
|
|
230
|
+
|
|
231
|
+
| Status | Means |
|
|
232
|
+
|---|---|
|
|
233
|
+
| `installed · upgrade available` | Source changed upstream; user copy still matches the old source → clean refresh |
|
|
234
|
+
| `installed · conflicting upgrade` | Source changed upstream AND user modified the copy → three-way diff shown, write requires explicit consent |
|
|
235
|
+
| `installed · removed upstream` | Artifact gone in the new version → proposed for deletion (subject to the removal-scope rule) |
|
|
236
|
+
| `not installed · new in this version` | New artifact added in the new version → offered, marked `★` if recommended |
|
|
237
|
+
|
|
238
|
+
The diff is sourced from `.versions/<recorded-version>/` inside the package —
|
|
239
|
+
a snapshot the release pipeline writes for every published version.
|
|
240
|
+
|
|
241
|
+
## Other install paths
|
|
242
|
+
|
|
243
|
+
npm is the recommended path for most users. The other two stay supported:
|
|
244
|
+
|
|
245
|
+
- **[Claude Code plugin marketplace](../README.md#quick-start)** — best UX
|
|
246
|
+
inside Claude Code. Same skills, marketplace-managed updates.
|
|
247
|
+
- **Git clone + symlinks** — best for skill authors and contributors. Clone
|
|
248
|
+
the repo, run `/setup-agent-fleet` from there, choose `symlink` in Step 8. Updates
|
|
249
|
+
flow through `git pull`. Symlinks need Developer Mode on Windows.
|
|
250
|
+
|
|
251
|
+
All three paths converge on the same `guided-workspace-setup` skill — the
|
|
252
|
+
difference is only in how the source files reach the workspace.
|
|
253
|
+
|
|
254
|
+
## CI usage
|
|
255
|
+
|
|
256
|
+
`npx @chankov/agent-fleet init` is interactive by default (it prompts for
|
|
257
|
+
the agent when detection is ambiguous). For CI, pass `--agent` explicitly:
|
|
258
|
+
|
|
259
|
+
```bash
|
|
260
|
+
npx --yes @chankov/agent-fleet@latest init --agent claude-code --method copy --workspace .
|
|
261
|
+
```
|
|
262
|
+
|
|
263
|
+
`doctor` accepts `--yes` for non-interactive repair. Note that the
|
|
264
|
+
LLM-driven `/setup-agent-fleet` flow is not CI-runnable by design — confirmation gates
|
|
265
|
+
exist precisely so a human approves every write.
|
|
266
|
+
|
|
267
|
+
## Receiving update notifications
|
|
268
|
+
|
|
269
|
+
Three independent mechanisms surface "a new version is published" without
|
|
270
|
+
you having to remember to check. All three share a single cache at
|
|
271
|
+
`$XDG_CACHE_HOME/agent-fleet/latest-version.json` (24h TTL) so the
|
|
272
|
+
registry is hit at most once per day.
|
|
273
|
+
|
|
274
|
+
### 1. CLI update-notifier (always on)
|
|
275
|
+
|
|
276
|
+
Every `npx @chankov/agent-fleet <cmd>` invocation runs a fast cache read
|
|
277
|
+
on entry. If the cached latest version exceeds the running CLI version, a
|
|
278
|
+
banner prints to stderr before the command output:
|
|
279
|
+
|
|
280
|
+
```
|
|
281
|
+
┌──────────────────────────────────────────────────────────────┐
|
|
282
|
+
│ agent-fleet update available: 0.1.0 → 0.2.0 │
|
|
283
|
+
│ Run: npx @chankov/agent-fleet@latest update │
|
|
284
|
+
│ Releases: https://github.com/chankov/agent-fleet/releases │
|
|
285
|
+
└──────────────────────────────────────────────────────────────┘
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
If the cache is stale, a detached background process refreshes it for the
|
|
289
|
+
*next* invocation — the current run is never blocked.
|
|
290
|
+
|
|
291
|
+
### 2. Claude Code session-start hook
|
|
292
|
+
|
|
293
|
+
When `hooks/session-start.sh` is installed (offered in Group 18 of `/setup-agent-fleet`),
|
|
294
|
+
every new Claude Code session runs the check with a 3-second wall-clock cap.
|
|
295
|
+
If an upgrade is available, the banner is injected into the session context
|
|
296
|
+
so Claude can mention it on its first turn — e.g. *"Note: agent-fleet 0.2.0
|
|
297
|
+
is available; want me to apply it via `/setup-agent-fleet`?"*
|
|
298
|
+
|
|
299
|
+
### 3. pi extension (`agent-fleet-update-check`)
|
|
300
|
+
|
|
301
|
+
When installed (offered in Group 10 of `/setup-agent-fleet`), the extension fires on the
|
|
302
|
+
first `agent_start` event of each pi session and emits a `ctx.ui.notify`
|
|
303
|
+
message in the pi UI if a newer version is published. Reads the same cache
|
|
304
|
+
as the CLI — no double-fetching.
|
|
305
|
+
|
|
306
|
+
### Opting out
|
|
307
|
+
|
|
308
|
+
Any of these environment variables disables all three:
|
|
309
|
+
|
|
310
|
+
```bash
|
|
311
|
+
export AGENT_SKILLS_NO_UPDATE_CHECK=1 # agent-fleet-specific
|
|
312
|
+
export NO_UPDATE_NOTIFIER=1 # conventional, also honoured
|
|
313
|
+
# CI=true is auto-detected — banners never appear in CI logs
|
|
314
|
+
```
|
|
315
|
+
|
|
316
|
+
### Forcing a manual check
|
|
317
|
+
|
|
318
|
+
```bash
|
|
319
|
+
# Block on a single registry fetch; print the banner if outdated
|
|
320
|
+
npx @chankov/agent-fleet check-update
|
|
321
|
+
|
|
322
|
+
# Bypass the cache entirely
|
|
323
|
+
rm ~/.cache/agent-fleet/latest-version.json
|
|
324
|
+
npx @chankov/agent-fleet check-update
|
|
325
|
+
```
|
|
326
|
+
|
|
327
|
+
## Troubleshooting
|
|
328
|
+
|
|
329
|
+
- **"Could not auto-detect your coding agent."** Pass `--agent` or run
|
|
330
|
+
`init` from a workspace that already has one of `.claude/`, `.opencode/`,
|
|
331
|
+
or `.pi/`.
|
|
332
|
+
- **`update` says "no install record".** Run `init` once first; the install
|
|
333
|
+
record is what `update` reads.
|
|
334
|
+
- **The version-aware menu shows `(snapshot missing)`.** The recorded version
|
|
335
|
+
is older than the snapshot retention in this package. The skill falls back
|
|
336
|
+
to "treat installed copy as canonical" — refresh manually if you want to
|
|
337
|
+
reset the baseline.
|