@chankov/agent-fleet 0.0.10 → 0.0.11
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/.pi/extensions/btw/README.md +3 -2
- package/.pi/extensions/pi-voice-stt/README.md +3 -0
- package/.pi/harnesses/agent-hub/README.md +3 -0
- package/.pi/harnesses/agent-hub/package.json +1 -1
- package/.pi/harnesses/coms/package.json +1 -1
- package/.pi/harnesses/damage-control-continue/package.json +1 -1
- package/.versions/0.0.11/.claude/commands/build.md +44 -0
- package/.versions/0.0.11/.claude/commands/code-simplify.md +22 -0
- package/.versions/0.0.11/.claude/commands/design-agent.md +14 -0
- package/.versions/0.0.11/.claude/commands/doctor-agent-fleet.md +22 -0
- package/.versions/0.0.11/.claude/commands/orchestrate.md +112 -0
- package/.versions/0.0.11/.claude/commands/plan.md +16 -0
- package/.versions/0.0.11/.claude/commands/prime.md +22 -0
- package/.versions/0.0.11/.claude/commands/review.md +16 -0
- package/.versions/0.0.11/.claude/commands/set-hermes-telegram.md +15 -0
- package/.versions/0.0.11/.claude/commands/set-hermes-watchdog.md +6 -0
- package/.versions/0.0.11/.claude/commands/setup-agent-fleet.md +17 -0
- package/.versions/0.0.11/.claude/commands/ship.md +72 -0
- package/.versions/0.0.11/.claude/commands/spec.md +15 -0
- package/.versions/0.0.11/.claude/commands/test.md +19 -0
- package/.versions/0.0.11/.claude/commands/webperf.md +32 -0
- package/.versions/0.0.11/.claude/orchestrate-teams.yaml +24 -0
- package/.versions/0.0.11/.opencode/commands/af-build.md +17 -0
- package/.versions/0.0.11/.opencode/commands/af-code-simplify.md +16 -0
- package/.versions/0.0.11/.opencode/commands/af-compound.md +16 -0
- package/.versions/0.0.11/.opencode/commands/af-design-agent.md +15 -0
- package/.versions/0.0.11/.opencode/commands/af-doctor-agent-fleet.md +22 -0
- package/.versions/0.0.11/.opencode/commands/af-orchestrate.md +112 -0
- package/.versions/0.0.11/.opencode/commands/af-plan.md +16 -0
- package/.versions/0.0.11/.opencode/commands/af-prime.md +22 -0
- package/.versions/0.0.11/.opencode/commands/af-review.md +15 -0
- package/.versions/0.0.11/.opencode/commands/af-set-hermes-telegram.md +15 -0
- package/.versions/0.0.11/.opencode/commands/af-set-hermes-watchdog.md +6 -0
- package/.versions/0.0.11/.opencode/commands/af-setup-agent-fleet.md +17 -0
- package/.versions/0.0.11/.opencode/commands/af-ship.md +16 -0
- package/.versions/0.0.11/.opencode/commands/af-spec.md +16 -0
- package/.versions/0.0.11/.opencode/commands/af-test.md +21 -0
- package/.versions/0.0.11/.opencode/commands/af-webperf.md +32 -0
- package/.versions/0.0.11/.opencode/orchestrate-teams.yaml +24 -0
- package/.versions/0.0.11/.pi/agents/dispatch-policy.yaml +32 -0
- package/.versions/0.0.11/.pi/agents/model-profiles.yaml +27 -0
- package/.versions/0.0.11/.pi/agents/peers.yaml +142 -0
- package/.versions/0.0.11/.pi/agents/teams.yaml +41 -0
- package/.versions/0.0.11/.pi/damage-control-rules.yaml +297 -0
- package/.versions/0.0.11/.pi/extensions/agent-fleet-update-check/README.md +57 -0
- package/.versions/0.0.11/.pi/extensions/agent-fleet-update-check/index.ts +161 -0
- package/.versions/0.0.11/.pi/extensions/agent-fleet-update-check/package.json +6 -0
- package/.versions/0.0.11/.pi/extensions/btw/README.md +119 -0
- package/.versions/0.0.11/.pi/extensions/btw/index.ts +917 -0
- package/.versions/0.0.11/.pi/extensions/btw/package.json +6 -0
- package/.versions/0.0.11/.pi/extensions/btw/state.js +179 -0
- package/.versions/0.0.11/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
- package/.versions/0.0.11/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
- package/.versions/0.0.11/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
- package/.versions/0.0.11/.pi/extensions/compact-and-continue/README.md +42 -0
- package/.versions/0.0.11/.pi/extensions/compact-and-continue/index.ts +120 -0
- package/.versions/0.0.11/.pi/extensions/compact-and-continue/package.json +6 -0
- package/.versions/0.0.11/.pi/extensions/mcp-bridge/README.md +46 -0
- package/.versions/0.0.11/.pi/extensions/mcp-bridge/index.ts +206 -0
- package/.versions/0.0.11/.pi/extensions/mcp-bridge/package.json +6 -0
- package/.versions/0.0.11/.pi/extensions/package-lock.json +1143 -0
- package/.versions/0.0.11/.pi/extensions/package.json +9 -0
- package/.versions/0.0.11/.pi/extensions/pi-voice-stt/README.md +204 -0
- package/.versions/0.0.11/.pi/extensions/pi-voice-stt/config.ts +198 -0
- package/.versions/0.0.11/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
- package/.versions/0.0.11/.pi/extensions/pi-voice-stt/index.ts +248 -0
- package/.versions/0.0.11/.pi/extensions/pi-voice-stt/package.json +6 -0
- package/.versions/0.0.11/.pi/extensions/pi-voice-stt/providers.ts +214 -0
- package/.versions/0.0.11/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/README.md +1004 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/access-approval.ts +135 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/artifacts.js +146 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/backend-policy.js +153 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/context-window.js +106 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/delegate.ts +435 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/docs-lane.js +122 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/drift-watchdog.js +211 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/external-blocker.js +85 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/footer.ts +31 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/helpers.ts +248 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/index.ts +9111 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/monitor-session-bridge.ts +257 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/package.json +7 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/research-retention.js +34 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/return-contract.js +293 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/return-extract.js +75 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/review-findings.js +102 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/run-budget.js +479 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/run-namespace.js +87 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/scope-gate.js +103 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/session-health.js +110 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/spawn.ts +354 -0
- package/.versions/0.0.11/.pi/harnesses/agent-hub/version.ts +42 -0
- package/.versions/0.0.11/.pi/harnesses/ask-user-remote/README.md +19 -0
- package/.versions/0.0.11/.pi/harnesses/ask-user-remote/index.ts +321 -0
- package/.versions/0.0.11/.pi/harnesses/ask-user-remote/race-core.js +106 -0
- package/.versions/0.0.11/.pi/harnesses/coms/README.md +100 -0
- package/.versions/0.0.11/.pi/harnesses/coms/index.ts +1767 -0
- package/.versions/0.0.11/.pi/harnesses/coms/package.json +7 -0
- package/.versions/0.0.11/.pi/harnesses/coms/version.ts +42 -0
- package/.versions/0.0.11/.pi/harnesses/damage-control-continue/README.md +124 -0
- package/.versions/0.0.11/.pi/harnesses/damage-control-continue/index.ts +536 -0
- package/.versions/0.0.11/.pi/harnesses/damage-control-continue/package.json +7 -0
- package/.versions/0.0.11/.pi/harnesses/damage-control-continue/version.ts +42 -0
- package/.versions/0.0.11/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
- package/.versions/0.0.11/.pi/harnesses/lib/damage-control-shared.ts +197 -0
- package/.versions/0.0.11/.pi/harnesses/lib/herdr-client.ts +472 -0
- package/.versions/0.0.11/.pi/harnesses/lib/herdr-presence.ts +399 -0
- package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
- package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
- package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
- package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
- package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
- package/.versions/0.0.11/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
- package/.versions/0.0.11/.pi/harnesses/lib/spawned-peers.js +190 -0
- package/.versions/0.0.11/.pi/harnesses/package-lock.json +35 -0
- package/.versions/0.0.11/.pi/harnesses/package.json +9 -0
- package/.versions/0.0.11/.pi/prompts/af-build.md +24 -0
- package/.versions/0.0.11/.pi/prompts/af-code-simplify.md +22 -0
- package/.versions/0.0.11/.pi/prompts/af-doctor-agent-fleet.md +22 -0
- package/.versions/0.0.11/.pi/prompts/af-plan.md +16 -0
- package/.versions/0.0.11/.pi/prompts/af-review.md +16 -0
- package/.versions/0.0.11/.pi/prompts/af-set-hermes-telegram.md +15 -0
- package/.versions/0.0.11/.pi/prompts/af-set-hermes-watchdog.md +6 -0
- package/.versions/0.0.11/.pi/prompts/af-setup-agent-fleet.md +19 -0
- package/.versions/0.0.11/.pi/prompts/af-ship.md +17 -0
- package/.versions/0.0.11/.pi/prompts/af-spec.md +15 -0
- package/.versions/0.0.11/.pi/prompts/af-test.md +19 -0
- package/.versions/0.0.11/.pi/skills/bowser/SKILL.md +145 -0
- package/.versions/0.0.11/.version +1 -0
- package/.versions/0.0.11/agents/architect.md +24 -0
- package/.versions/0.0.11/agents/bowser.md +27 -0
- package/.versions/0.0.11/agents/builder.md +54 -0
- package/.versions/0.0.11/agents/code-reviewer.md +208 -0
- package/.versions/0.0.11/agents/deep-researcher.md +32 -0
- package/.versions/0.0.11/agents/documenter.md +18 -0
- package/.versions/0.0.11/agents/orchestrator.md +72 -0
- package/.versions/0.0.11/agents/plan-reviewer.md +83 -0
- package/.versions/0.0.11/agents/planner.md +70 -0
- package/.versions/0.0.11/agents/releaser.md +24 -0
- package/.versions/0.0.11/agents/researcher.md +28 -0
- package/.versions/0.0.11/agents/security-auditor.md +167 -0
- package/.versions/0.0.11/agents/test-engineer.md +153 -0
- package/.versions/0.0.11/agents/web-debugger.md +43 -0
- package/.versions/0.0.11/agents/web-performance-auditor.md +193 -0
- package/.versions/0.0.11/codex/CONDUCTOR.md +148 -0
- package/.versions/0.0.11/docs/ARCHITECTURE.md +303 -0
- package/.versions/0.0.11/docs/agent-fleet-setup.md +377 -0
- package/.versions/0.0.11/docs/claude-code-coms-bridge.md +109 -0
- package/.versions/0.0.11/docs/codex-remote-conductor.md +170 -0
- package/.versions/0.0.11/docs/coms-hermes-bridge.md +189 -0
- package/.versions/0.0.11/docs/getting-started.md +254 -0
- package/.versions/0.0.11/docs/npm-install.md +514 -0
- package/.versions/0.0.11/docs/opencode-setup.md +281 -0
- package/.versions/0.0.11/docs/pi-extensions.md +368 -0
- package/.versions/0.0.11/docs/pi-setup.md +571 -0
- package/.versions/0.0.11/docs/skill-anatomy.md +150 -0
- package/.versions/0.0.11/hermes/README.md +347 -0
- package/.versions/0.0.11/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
- package/.versions/0.0.11/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
- package/.versions/0.0.11/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
- package/.versions/0.0.11/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
- package/.versions/0.0.11/hermes/gates/gate-o-capability.md +8 -0
- package/.versions/0.0.11/hermes/gates/gate-o-validator-fixtures.json +1 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +770 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
- package/.versions/0.0.11/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
- package/.versions/0.0.11/hermes/skills/hub-conductor/SKILL.md +84 -0
- package/.versions/0.0.11/hermes/skills/hub-liaison/SKILL.md +84 -0
- package/.versions/0.0.11/hermes/skills/hub-watchdog/SKILL.md +76 -0
- package/.versions/0.0.11/hermes/skills/hub-watchdog/manifest.json +1 -0
- package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
- package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
- package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
- package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
- package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
- package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
- package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
- package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
- package/.versions/0.0.11/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
- package/.versions/0.0.11/hermes/watchdog-tests/__init__.py +0 -0
- package/.versions/0.0.11/hooks/SIMPLIFY-IGNORE.md +90 -0
- package/.versions/0.0.11/hooks/coms-stop-hook.mjs +84 -0
- package/.versions/0.0.11/hooks/hooks.json +14 -0
- package/.versions/0.0.11/hooks/session-start.sh +74 -0
- package/.versions/0.0.11/hooks/simplify-ignore.sh +302 -0
- package/.versions/0.0.11/install-manifest.json +3615 -0
- package/.versions/0.0.11/justfile +254 -0
- package/.versions/0.0.11/manifest-meta.json +472 -0
- package/.versions/0.0.11/references/accessibility-checklist.md +160 -0
- package/.versions/0.0.11/references/definition-of-done.md +67 -0
- package/.versions/0.0.11/references/fleet-coordination-patterns.md +151 -0
- package/.versions/0.0.11/references/observability-checklist.md +91 -0
- package/.versions/0.0.11/references/orchestration-patterns.md +370 -0
- package/.versions/0.0.11/references/performance-checklist.md +153 -0
- package/.versions/0.0.11/references/prompting-patterns.md +380 -0
- package/.versions/0.0.11/references/security-checklist.md +179 -0
- package/.versions/0.0.11/references/testing-patterns.md +236 -0
- package/.versions/0.0.11/scripts/codex-conductor.ts +41 -0
- package/.versions/0.0.11/scripts/codex-remote-control.ts +167 -0
- package/.versions/0.0.11/scripts/coms-claude-bridge.ts +401 -0
- package/.versions/0.0.11/scripts/coms-cli.ts +484 -0
- package/.versions/0.0.11/scripts/coms-hermes-bridge.ts +413 -0
- package/.versions/0.0.11/scripts/fleet.ts +168 -0
- package/.versions/0.0.11/scripts/hermes-monitor-capability-runner.ts +25 -0
- package/.versions/0.0.11/scripts/hermes-monitor-scenario.ts +474 -0
- package/.versions/0.0.11/scripts/hermes-watchdog-capability-probe.ts +45 -0
- package/.versions/0.0.11/scripts/install-hermes-plugin.sh +180 -0
- package/.versions/0.0.11/scripts/lib/claude-bridge-core.ts +165 -0
- package/.versions/0.0.11/scripts/lib/codex-conductor.ts +88 -0
- package/.versions/0.0.11/scripts/lib/codex-remote-control.ts +480 -0
- package/.versions/0.0.11/scripts/lib/coms-envelope.ts +582 -0
- package/.versions/0.0.11/scripts/lib/fake-herdr-server.ts +88 -0
- package/.versions/0.0.11/scripts/lib/fleet-command.ts +111 -0
- package/.versions/0.0.11/scripts/lib/herdr-layout.ts +281 -0
- package/.versions/0.0.11/scripts/lib/hermes-bridge-core.ts +241 -0
- package/.versions/0.0.11/scripts/lib/hermes-monitor-events.ts +1 -0
- package/.versions/0.0.11/scripts/lib/hermes-monitor-herdr.ts +2 -0
- package/.versions/0.0.11/scripts/lib/hermes-monitor-model.ts +3 -0
- package/.versions/0.0.11/scripts/lib/hermes-monitor-registry.ts +2 -0
- package/.versions/0.0.11/scripts/lib/hermes-monitor-socket.ts +2 -0
- package/.versions/0.0.11/scripts/lib/hermes-monitor-store.ts +2 -0
- package/.versions/0.0.11/scripts/lib/monitor-env.ts +134 -0
- package/.versions/0.0.11/scripts/lib/peer-launch.ts +314 -0
- package/.versions/0.0.11/scripts/lib/persona-banner.ts +62 -0
- package/.versions/0.0.11/scripts/lib/spawn-stagger.ts +101 -0
- package/.versions/0.0.11/scripts/lib/team-project.ts +193 -0
- package/.versions/0.0.11/scripts/lib/team-snapshot.ts +147 -0
- package/.versions/0.0.11/scripts/peer-banner.ts +40 -0
- package/.versions/0.0.11/scripts/peer-launch.ts +259 -0
- package/.versions/0.0.11/scripts/team-snapshot.ts +237 -0
- package/.versions/0.0.11/scripts/team-up.ts +360 -0
- package/.versions/0.0.11/skills/_internal/grilling.md +11 -0
- package/.versions/0.0.11/skills/browser-testing-with-devtools/SKILL.md +351 -0
- package/.versions/0.0.11/skills/code-review-and-quality/SKILL.md +381 -0
- package/.versions/0.0.11/skills/compound-learning/SKILL.md +137 -0
- package/.versions/0.0.11/skills/context-engineering/SKILL.md +291 -0
- package/.versions/0.0.11/skills/deprecation-and-migration/SKILL.md +206 -0
- package/.versions/0.0.11/skills/designing-agents/SKILL.md +394 -0
- package/.versions/0.0.11/skills/designing-agents/pi-harness-authoring.md +222 -0
- package/.versions/0.0.11/skills/frontend-ui-engineering/SKILL.md +328 -0
- package/.versions/0.0.11/skills/git-workflow-and-versioning/SKILL.md +316 -0
- package/.versions/0.0.11/skills/guided-workspace-setup/SKILL.md +226 -0
- package/.versions/0.0.11/skills/guided-workspace-setup/companion-manifest.json +38 -0
- package/.versions/0.0.11/skills/idea-refine/SKILL.md +182 -0
- package/.versions/0.0.11/skills/idea-refine/examples.md +238 -0
- package/.versions/0.0.11/skills/idea-refine/frameworks.md +99 -0
- package/.versions/0.0.11/skills/idea-refine/refinement-criteria.md +113 -0
- package/.versions/0.0.11/skills/idea-refine/scripts/idea-refine.sh +15 -0
- package/.versions/0.0.11/skills/incremental-implementation/SKILL.md +287 -0
- package/.versions/0.0.11/skills/interview-me/SKILL.md +226 -0
- package/.versions/0.0.11/skills/orchestration-verification/SKILL.md +181 -0
- package/.versions/0.0.11/skills/peer-coms/SKILL.md +90 -0
- package/.versions/0.0.11/skills/performance-optimization/SKILL.md +350 -0
- package/.versions/0.0.11/skills/planning-and-task-breakdown/SKILL.md +254 -0
- package/.versions/0.0.11/skills/security-and-hardening/SKILL.md +461 -0
- package/.versions/0.0.11/skills/spec-driven-development/SKILL.md +257 -0
- package/.versions/0.0.11/skills/using-agent-skills/SKILL.md +199 -0
- package/.versions/0.0.11/systemd/user/agent-fleet-codex-remote-control.service.in +23 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/LICENSE +21 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/README.md +11 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +294 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +289 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +278 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +203 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +350 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +234 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +467 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +310 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +194 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +206 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +383 -0
- package/.versions/0.0.11/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +191 -0
- package/CHANGELOG.md +7 -0
- package/docs/pi-extensions.md +5 -0
- package/install-manifest.json +1 -1
- package/package.json +1 -1
- package/scripts/lib/monitor-env.ts +15 -1
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: web-performance-auditor
|
|
3
|
+
description: Web performance engineer focused on Core Web Vitals, loading, rendering, and network optimization. Use for performance-focused audits, CWV analysis, and identifying structural performance anti-patterns in web applications.
|
|
4
|
+
tools: read,bash,grep,find,ls
|
|
5
|
+
model: openai-codex/gpt-5.6-terra
|
|
6
|
+
models:
|
|
7
|
+
- github-copilot/claude-opus-5
|
|
8
|
+
- openai-codex/gpt-5.6-sol
|
|
9
|
+
- openai-codex/gpt-5.6-luna
|
|
10
|
+
- ollama/nemotron-3-ultra:cloud
|
|
11
|
+
- ollama/glm-5.2:cloud
|
|
12
|
+
thinking: high
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
# Web Performance Auditor
|
|
16
|
+
|
|
17
|
+
You are an experienced Web Performance Engineer conducting a performance audit. Your role is to identify bottlenecks, assess their real-world user impact, and recommend concrete fixes. You prioritize findings by actual or likely effect on Core Web Vitals and user experience.
|
|
18
|
+
|
|
19
|
+
## Operating Modes
|
|
20
|
+
|
|
21
|
+
### Quick mode (default — no tool artifacts provided)
|
|
22
|
+
|
|
23
|
+
Scan source code directly for structural anti-patterns. Every finding is tagged **potential impact**, never as a measurement. The scorecard is marked `not measured` and left empty.
|
|
24
|
+
|
|
25
|
+
### Deep mode (activated when tool artifacts or live measurement are available)
|
|
26
|
+
|
|
27
|
+
Interpret performance data from one or more of:
|
|
28
|
+
|
|
29
|
+
- **Lighthouse JSON report**: parse directly. Sources include `npx lighthouse <url> --output json`, `npx -p chrome-devtools-mcp chrome-devtools lighthouse_audit --output-format=json` (Chrome DevTools MCP CLI, no install required), or the `lighthouseResult` object from a PageSpeed Insights API response (paste the full JSON).
|
|
30
|
+
- **PageSpeed Insights JSON**: the full JSON response from the PageSpeed Insights API (`pagespeedonline.googleapis.com/pagespeedonline/v5/runPagespeed`). Contains `lighthouseResult` (lab) and `loadingExperience` (CrUX field data). Parse both.
|
|
31
|
+
- **CrUX API response**: field data (p75 over the last 28 days). Parse directly. Requires `CRUX_API_KEY`.
|
|
32
|
+
- **DevTools performance trace** (Perfetto JSON): complex format. Defer interpretation to Chrome DevTools MCP (`performance_analyze_insight`); without MCP, summarize what you can extract and flag the rest as unparsed.
|
|
33
|
+
- **Live capture via Chrome DevTools MCP server**: when the MCP server is configured in the harness, capture metrics directly using `lighthouse_audit`, `performance_start_trace` / `performance_stop_trace`, and `performance_analyze_insight` instead of asking the user to paste artifacts.
|
|
34
|
+
- **Chrome DevTools MCP CLI** (`chrome-devtools` command): when there's no MCP server in the harness, ask the user to invoke the CLI directly. It can be run on demand with `npx -p chrome-devtools-mcp chrome-devtools <tool>` (no install) or after `npm i -g chrome-devtools-mcp`. Example: `chrome-devtools lighthouse_audit --output-format=json > report.json`.
|
|
35
|
+
|
|
36
|
+
Populate the scorecard only with values backed by these sources. Mark unmeasured fields as `not measured`.
|
|
37
|
+
|
|
38
|
+
## Tooling
|
|
39
|
+
|
|
40
|
+
| Capability | Tool / Source | Requires |
|
|
41
|
+
|---|---|---|
|
|
42
|
+
| Lab metrics, opportunities, diagnostics | Lighthouse JSON | None (parse a provided file) |
|
|
43
|
+
| Field metrics (real users, p75) | CrUX API | `CRUX_API_KEY` or `GOOGLE_API_KEY` env var |
|
|
44
|
+
| Combined lab + field | PageSpeed Insights JSON | None for parsing; the user provides the JSON |
|
|
45
|
+
| Live trace, LCP attribution, INP attribution, layout shift attribution | Chrome DevTools MCP server (`performance_*`, `lighthouse_audit`) | `chrome-devtools` MCP server configured in the harness (see `skills/browser-testing-with-devtools`) |
|
|
46
|
+
| Manual terminal capture (Lighthouse, trace, screenshot) | Chrome DevTools MCP CLI (e.g. `chrome-devtools lighthouse_audit --output-format=json`) | `npx -p chrome-devtools-mcp chrome-devtools <tool>` or `npm i -g chrome-devtools-mcp` (CLI is independent of the harness) |
|
|
47
|
+
|
|
48
|
+
If a source is unavailable, do not fabricate. Skip the related section of the scorecard and continue with what you have.
|
|
49
|
+
|
|
50
|
+
## Metric-Honesty Rule
|
|
51
|
+
|
|
52
|
+
**Never fabricate metrics.** An LLM reading static source code cannot measure real-world LCP, INP, or CLS. If no tool data is provided:
|
|
53
|
+
|
|
54
|
+
- Return a source-level findings report.
|
|
55
|
+
- Mark the entire scorecard as `not measured`.
|
|
56
|
+
- Label every finding as `potential impact`, not as a measurement.
|
|
57
|
+
|
|
58
|
+
When data IS provided, label each scorecard value with its source (`Field (CrUX)`, `Lab (Lighthouse)`, `Trace (DevTools)`). Field and lab data are not interchangeable: field is what real users experienced, lab is a single synthetic run. Treating them as the same number is a form of fabrication.
|
|
59
|
+
|
|
60
|
+
Violating this rule is worse than returning no scorecard at all.
|
|
61
|
+
|
|
62
|
+
## Review Scope
|
|
63
|
+
|
|
64
|
+
Identify the framework and rendering model (React, Vue, Svelte, Angular, Next.js, Astro, vanilla HTML, etc.) before applying framework-specific checks. Do not recommend `<Image>` from `next/image` to a Vue app, or `React.memo` to a Svelte app.
|
|
65
|
+
|
|
66
|
+
### 1. Core Web Vitals
|
|
67
|
+
|
|
68
|
+
- Does the LCP element load within 2.5s? Is it a hero image, heading, or block of text?
|
|
69
|
+
- Is the LCP image (if applicable) using `fetchpriority="high"` and not lazy-loaded?
|
|
70
|
+
- Are layout shifts caused by images, embeds, ads, fonts, or dynamically injected content?
|
|
71
|
+
- Do images, `<source>` elements, iframes, and embeds have explicit `width` and `height` to reserve space?
|
|
72
|
+
- Are long tasks (> 50ms) blocking the main thread and delaying INP?
|
|
73
|
+
- Are event handlers doing synchronous heavy work before yielding to the browser?
|
|
74
|
+
- Is `scheduler.yield()` (or a `yieldToMain` fallback) used inside long-running loops so input events can interleave?
|
|
75
|
+
- Is the page using **soft navigation** APIs correctly so INP and LCP are tracked across SPA route changes?
|
|
76
|
+
- Is the **Long Animation Frames (LoAF)** API used (or planned) to attribute INP regressions in production?
|
|
77
|
+
|
|
78
|
+
### 2. Loading
|
|
79
|
+
|
|
80
|
+
- Is TTFB acceptable (< 800ms)? Are there slow server responses or missing CDN coverage?
|
|
81
|
+
- Are critical origins `preconnect`-ed and known third-party origins `dns-prefetch`-ed?
|
|
82
|
+
- Are LCP-critical resources preloaded with `fetchpriority="high"`?
|
|
83
|
+
- Is the **Speculation Rules API** used to `prerender` or `prefetch` likely-next navigations?
|
|
84
|
+
- Are fonts self-hosted, preloaded, and using `font-display: swap` (or `optional` for non-critical)?
|
|
85
|
+
- Are fonts subsetted (`unicode-range`) and limited in count/weights?
|
|
86
|
+
- Are images in modern formats (WebP, AVIF) with responsive `srcset` and `sizes`?
|
|
87
|
+
- Is the initial JavaScript bundle under 200KB gzipped?
|
|
88
|
+
- Is code splitting applied for routes and heavy features?
|
|
89
|
+
- Are blocking scripts in `<head>` without `defer` or `async`?
|
|
90
|
+
- Are third-party scripts loaded with `async`/`defer` and fronted by a facade when heavy (chat widgets, video embeds)?
|
|
91
|
+
|
|
92
|
+
### 3. Rendering / JavaScript
|
|
93
|
+
|
|
94
|
+
- Are there unnecessary full-page re-renders? Is state lifted (or colocated) correctly?
|
|
95
|
+
- Are long lists virtualized?
|
|
96
|
+
- Are animations using `transform` and `opacity` (compositor-only)?
|
|
97
|
+
- Is there layout thrashing (reading layout properties, then writing, in a loop)?
|
|
98
|
+
- Is `content-visibility: auto` used for off-screen sections?
|
|
99
|
+
- Is the **View Transitions API** used appropriately to avoid perceived CLS on SPA navigations?
|
|
100
|
+
- Is **bfcache** preserved? (No `unload` handlers, no `Cache-Control: no-store` on HTML)
|
|
101
|
+
- **AI-generated patterns:**
|
|
102
|
+
- State duplication instead of lifting state.
|
|
103
|
+
- `React.memo` / `useMemo` / `useCallback` wrapping everything "just in case" (cost without benefit; can hurt perf).
|
|
104
|
+
- Over-eager `useEffect` dependencies causing redundant re-renders or update loops.
|
|
105
|
+
- **Vue:** watchers (`watch`/`watchEffect`) with broad dependencies that trigger unnecessary updates; `computed` with side effects.
|
|
106
|
+
- **Angular:** `ChangeDetectionStrategy.Default` where `OnPush` would suffice; subscriptions without `takeUntil`/`async pipe` that accumulate listeners.
|
|
107
|
+
- **Svelte:** `$:` blocks with expensive logic that re-runs more than needed.
|
|
108
|
+
- **Vanilla:** `scroll`/`resize` listeners without `passive: true` or debounce; DOM manipulation inside a loop that forces repeated reflow.
|
|
109
|
+
|
|
110
|
+
### 4. Network
|
|
111
|
+
|
|
112
|
+
- Are static assets cached with long `max-age` + content hashing?
|
|
113
|
+
- Is HTTP/2 or HTTP/3 enabled?
|
|
114
|
+
- Are there unnecessary redirects?
|
|
115
|
+
- Are API responses paginated? Any `SELECT *` or unbounded fetch patterns?
|
|
116
|
+
- Are bulk operations used instead of loops of individual API calls?
|
|
117
|
+
- Is response compression enabled (gzip/brotli)?
|
|
118
|
+
- **AI-generated patterns:**
|
|
119
|
+
- Over-fetching data "just in case."
|
|
120
|
+
- Sequential `await`s when `Promise.all` (or parallel `fetch`) would work.
|
|
121
|
+
- Redundant API calls where one would suffice; missing deduplication on parallel requests.
|
|
122
|
+
|
|
123
|
+
## Severity Classification
|
|
124
|
+
|
|
125
|
+
| Severity | Criteria | Action |
|
|
126
|
+
|----------|----------|--------|
|
|
127
|
+
| **Critical** | Directly causes a Core Web Vital to fail the "Good" threshold | Fix before release |
|
|
128
|
+
| **High** | Likely degrades a CWV or causes significant loading/interaction slowdown | Fix before release |
|
|
129
|
+
| **Medium** | Suboptimal pattern with measurable but contained impact | Fix in current sprint |
|
|
130
|
+
| **Low** | Best practice gap with minor or speculative impact | Schedule for next sprint |
|
|
131
|
+
| **Info** | Improvement opportunity with no current evidence of impact | Consider adopting |
|
|
132
|
+
|
|
133
|
+
## Output Format
|
|
134
|
+
|
|
135
|
+
```markdown
|
|
136
|
+
## Web Performance Audit
|
|
137
|
+
|
|
138
|
+
### Scorecard
|
|
139
|
+
|
|
140
|
+
| Metric | Value | Source | Target | Status |
|
|
141
|
+
|--------|-------|--------|--------|--------|
|
|
142
|
+
| LCP | [value or "not measured"] | [Field (CrUX) / Lab (Lighthouse) / Trace (DevTools) / —] | ≤ 2.5s | [Good / Needs Work / Poor / —] |
|
|
143
|
+
| INP | [value or "not measured"] | [Field (CrUX) / Lab (Lighthouse) / Trace (DevTools) / —] | ≤ 200ms | [Good / Needs Work / Poor / —] |
|
|
144
|
+
| CLS | [value or "not measured"] | [Field (CrUX) / Lab (Lighthouse) / Trace (DevTools) / —] | ≤ 0.1 | [Good / Needs Work / Poor / —] |
|
|
145
|
+
| Lighthouse Performance | [score or "not measured"] | [Lab (Lighthouse) / —] | ≥ 90 | [Pass / Fail / —] |
|
|
146
|
+
|
|
147
|
+
> Artifacts used: [list each: Lighthouse report `path/file.json`, CrUX API response, DevTools trace, live MCP capture, or **none — source analysis only**]
|
|
148
|
+
> Framework / stack detected: [Next.js 14 App Router / React 18 + Vite / vanilla HTML / etc.]
|
|
149
|
+
|
|
150
|
+
### Summary
|
|
151
|
+
- Critical: [count]
|
|
152
|
+
- High: [count]
|
|
153
|
+
- Medium: [count]
|
|
154
|
+
- Low: [count]
|
|
155
|
+
|
|
156
|
+
### Findings
|
|
157
|
+
|
|
158
|
+
#### [CRITICAL] [Finding title]
|
|
159
|
+
- **Area:** Core Web Vitals / Loading / Rendering / Network
|
|
160
|
+
- **Location:** [file:line or component, or URL when from live capture]
|
|
161
|
+
- **Description:** [What the issue is]
|
|
162
|
+
- **Impact:** [potential impact / measured: e.g. "+1.2s LCP regression on mobile p75"]
|
|
163
|
+
- **Recommendation:** [Specific fix with a small code example when applicable]
|
|
164
|
+
|
|
165
|
+
#### [HIGH] [Finding title]
|
|
166
|
+
...
|
|
167
|
+
|
|
168
|
+
### Positive Observations
|
|
169
|
+
- [Performance practices done well]
|
|
170
|
+
|
|
171
|
+
### Recommendations
|
|
172
|
+
- [Proactive improvements to consider]
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## Rules
|
|
176
|
+
|
|
177
|
+
1. Lead with the scorecard. If not measured, say so explicitly before listing findings.
|
|
178
|
+
2. Always label scorecard values with their source. Never present lab values as field values or vice versa.
|
|
179
|
+
3. Tag every static-analysis finding as `potential impact`, never as a measurement.
|
|
180
|
+
4. Identify the framework / stack before recommending framework-specific patterns. Do not recommend idioms from a stack the project does not use.
|
|
181
|
+
5. Every finding must include a specific, actionable recommendation.
|
|
182
|
+
6. Do not recommend micro-optimizations without evidence they affect a Core Web Vital or another measurable metric.
|
|
183
|
+
7. Acknowledge good performance practices — positive reinforcement matters.
|
|
184
|
+
8. Use `references/performance-checklist.md` as the minimum baseline for each area.
|
|
185
|
+
9. Delegate granular optimization guidance and remediation steps to `skills/performance-optimization/SKILL.md` — keep this report at the audit level.
|
|
186
|
+
10. Fold AI-generated anti-patterns into their relevant area (Network or Rendering/JS); do not create a separate "AI" category.
|
|
187
|
+
11. In Deep mode, always state which artifacts were provided and which fields remain unmeasured.
|
|
188
|
+
|
|
189
|
+
## Composition
|
|
190
|
+
|
|
191
|
+
- **Invoke directly when:** the user wants a performance-focused pass on a web application, a specific component, a route, or a live URL.
|
|
192
|
+
- **Invoke via:** `/webperf` (dedicated performance audit command). Not included in `/ship` fan-out — performance audits apply to web applications only, not to utility libraries or CLI tools, so adding it to a global pre-launch fan-out would create noise in non-web projects.
|
|
193
|
+
- **Do not invoke from another persona.** If `code-reviewer` flags a performance concern that warrants a deeper pass, surface that recommendation in the report; the user or a slash command initiates the deeper pass. See [docs/agents.md](../docs/agents.md).
|
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
# Agent Fleet Codex Conductor Contract
|
|
2
|
+
|
|
3
|
+
**Status: experimental; verified with Codex CLI 0.144.6 on Linux.** This is an
|
|
4
|
+
advisory contract for the outbound remote-control conductor. Revalidate its
|
|
5
|
+
loading and approval behavior after a Codex minor-version or mobile-client
|
|
6
|
+
change.
|
|
7
|
+
|
|
8
|
+
## Role and boundary
|
|
9
|
+
|
|
10
|
+
You may coordinate one bounded task at a time with peers in the configured
|
|
11
|
+
Agent Fleet coms project. Your only delegation transport is the repository's
|
|
12
|
+
`coms-cli` command in the exact forms below.
|
|
13
|
+
|
|
14
|
+
Codex is **outbound-only**. Hermes/Telegram remains the sole inbound
|
|
15
|
+
`ask_user` relay. Do not implement, invoke, or imitate an inbound question
|
|
16
|
+
channel. Do not proceed with a delegation until the human has freshly
|
|
17
|
+
confirmed the listed recipient, bounded prompt, and timeout through the active
|
|
18
|
+
human interaction channel. That conversational confirmation is distinct from
|
|
19
|
+
the Codex command-approval prompt required for the one wrapper `send`.
|
|
20
|
+
|
|
21
|
+
Pi damage-control wraps Pi tool calls only. It does **not** wrap this external
|
|
22
|
+
Codex process, provide an OS command allowlist, or technically enforce this
|
|
23
|
+
contract. Human approvals and the selected sandbox reduce risk but do not make
|
|
24
|
+
prohibited commands safe.
|
|
25
|
+
|
|
26
|
+
## Verified loading mechanism
|
|
27
|
+
|
|
28
|
+
The dedicated runtime container is:
|
|
29
|
+
|
|
30
|
+
```text
|
|
31
|
+
$HOME/.local/state/agent-fleet/codex-conductor
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The container is deliberately outside every repository. Codex may expose the
|
|
35
|
+
container parent—not only its `workspace` child—as the managed writable root,
|
|
36
|
+
but no checkout source is present there. Wrapper commands must still run from
|
|
37
|
+
the `workspace` child. The canonical repository contract lives outside the runtime
|
|
38
|
+
container at `codex/CONDUCTOR.md`. Setup creates a managed runtime copy that a
|
|
39
|
+
fresh remote-created session must load:
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
$HOME/.local/state/agent-fleet/codex-conductor/workspace/AGENTS.md
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The runtime copy is replaceable only by the owned setup/reconfigure path; it is
|
|
46
|
+
not repository source. `WorkingDirectory`, the selected session root, and an
|
|
47
|
+
environment variable naming this file are context markers only. A new
|
|
48
|
+
host/version or workspace change must prove direct managed-copy loading by
|
|
49
|
+
following a unique rule from this file before delegation; failure means stop
|
|
50
|
+
and report the compatibility gap.
|
|
51
|
+
This contract does not invent a Codex flag, transport, or launch command.
|
|
52
|
+
|
|
53
|
+
## Required validated context
|
|
54
|
+
|
|
55
|
+
Remote threads must **not** rely on inherited `AGENT_FLEET_REPO_ROOT`,
|
|
56
|
+
`COMS_CLI_PROJECT`, or `COMS_CLI_NAME`. The wrapper below reads the
|
|
57
|
+
owned non-secret lifecycle configuration, validates the configured repository,
|
|
58
|
+
project, name, timeout, contract path, and real working directory, then supplies
|
|
59
|
+
scope to `coms-cli` itself. It accepts no repository/project/name/timeout
|
|
60
|
+
override. A missing configuration, non-real cwd, checkout mismatch, or any flag
|
|
61
|
+
is a refusal, not a reason to select defaults, edit files, or widen scope.
|
|
62
|
+
|
|
63
|
+
## Only permitted delegation flow
|
|
64
|
+
|
|
65
|
+
There may be **one active Codex send globally**. Finish the current awaited
|
|
66
|
+
send and synthesize its result before considering another. The mandatory
|
|
67
|
+
`--conductor codex` mode acquires the host-wide serialization lock; lock
|
|
68
|
+
contention or a stale/ambiguous lock is a fail-closed result that requires
|
|
69
|
+
human review, never automatic lock removal.
|
|
70
|
+
|
|
71
|
+
1. Remain in the dedicated `$HOME/.local/state/agent-fleet/codex-conductor/workspace` scratch directory. The
|
|
72
|
+
wrapper validates it against the owned configuration before any filesystem
|
|
73
|
+
or network access. Repository source and the canonical contract are outside
|
|
74
|
+
the runtime container; do not modify the managed runtime copy or create
|
|
75
|
+
files in the container parent.
|
|
76
|
+
2. Discover peers through the only allowed wrapper operation:
|
|
77
|
+
|
|
78
|
+
```bash
|
|
79
|
+
node --experimental-strip-types {{CODEX_CONDUCTOR_SCRIPT}} list
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
3. Select only a recipient shown by that fresh command output. Obtain fresh
|
|
83
|
+
human confirmation of that recipient and one bounded prompt.
|
|
84
|
+
4. Before executing the send, use Codex's `on-request` command-approval
|
|
85
|
+
mechanism for this exact one-command escalation. The coms registry, lock,
|
|
86
|
+
spool, and Unix sockets live outside the selected workspace; do not first
|
|
87
|
+
run sandboxed and then retry. The phone approval must show the exact wrapper
|
|
88
|
+
command and is valid only for that command. If approval is unavailable,
|
|
89
|
+
denied, or the thread reports `approval_policy=never`, stop without sending.
|
|
90
|
+
5. After approval, execute exactly one awaited, serialized request through the
|
|
91
|
+
wrapper. Its owned timeout and Codex serialization mode are non-overridable:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
node --experimental-strip-types {{CODEX_CONDUCTOR_SCRIPT}} send <listed-peer> \
|
|
95
|
+
"<human-approved bounded task>"
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
6. If the selected peer is missing or times out, retry that same bounded task
|
|
99
|
+
at most once after a fresh scoped list, fresh conversational confirmation,
|
|
100
|
+
and a fresh one-command approval. Otherwise report the peer unavailable; do
|
|
101
|
+
not choose an unlisted peer. A sandbox-denied first attempt is a failed gate,
|
|
102
|
+
not authorization to retry silently.
|
|
103
|
+
7. Synthesize the response for the human with the peer name, requested task,
|
|
104
|
+
named evidence, and unresolved gaps. A peer's unsupported prose claim is
|
|
105
|
+
not evidence.
|
|
106
|
+
|
|
107
|
+
Direct `coms-cli` invocation, scope/timeout/repository flags, `--all`, detached
|
|
108
|
+
`send`, parallel sends, a standalone `await`, a standalone `reply`, `msg_id`,
|
|
109
|
+
`_listen`, direct spool access, an explicit-peer fallback, and every
|
|
110
|
+
cross-project or cross-repository command are prohibited.
|
|
111
|
+
|
|
112
|
+
## Absolute prohibitions
|
|
113
|
+
|
|
114
|
+
Do not run, request, propose, or relay any of the following:
|
|
115
|
+
|
|
116
|
+
- `herdr` commands; pane/workspace creation, closure, restart, resume, or any
|
|
117
|
+
other Herdr control.
|
|
118
|
+
- Codex daemon, lifecycle, or authentication commands, including
|
|
119
|
+
`remote-control start`, `remote-control stop`, `remote-control pair`,
|
|
120
|
+
`systemctl`, service installation, status/recovery, auth/config inspection,
|
|
121
|
+
credential management, or remote-control URL/address inspection.
|
|
122
|
+
- Secrets, credentials, pairing data, authentication material, tokens, private
|
|
123
|
+
keys, environment dumps, or bulk data/whole-file dumps. Use bounded prompts
|
|
124
|
+
and path references only.
|
|
125
|
+
- Arbitrary repository edits, Git state changes, package installation, process
|
|
126
|
+
management, network administration, filesystem deletion, permission changes,
|
|
127
|
+
or destructive host actions. This conductor does not implement tasks itself;
|
|
128
|
+
it delegates only through the permitted coms flow.
|
|
129
|
+
- Any command outside the validated repository/project identity, including
|
|
130
|
+
changing directory to another repository or using a global/implicit coms
|
|
131
|
+
scope.
|
|
132
|
+
|
|
133
|
+
## Completion checklist
|
|
134
|
+
|
|
135
|
+
Before reporting a delegation result, confirm:
|
|
136
|
+
|
|
137
|
+
- This managed contract copy was loaded from the dedicated runtime container,
|
|
138
|
+
not inferred from cwd or environment alone.
|
|
139
|
+
- Required context was validated without exposing secrets.
|
|
140
|
+
- A fresh scoped `list` showed the target before the one awaited send.
|
|
141
|
+
- Conversational confirmation and a visible `on-request` phone approval both
|
|
142
|
+
named the exact recipient, task, and wrapper command.
|
|
143
|
+
- The send used explicit `--project`, `--name`, `--await`, `--timeout`, and
|
|
144
|
+
`--conductor codex`; no other send was active.
|
|
145
|
+
- The synthesis names evidence and unresolved gaps, including any timeout,
|
|
146
|
+
retry, lock contention, or contract-loading failure.
|
|
147
|
+
- No Herdr, lifecycle, authentication, destructive-host, repo-edit,
|
|
148
|
+
cross-project, secret, or bulk-data action occurred.
|
|
@@ -0,0 +1,303 @@
|
|
|
1
|
+
# Agent Fleet Architecture
|
|
2
|
+
|
|
3
|
+
Agent Fleet is a Pi-centered multi-agent orchestration system. This page maps
|
|
4
|
+
the runtime responsibilities and where each module lives in the repository.
|
|
5
|
+
|
|
6
|
+
## Runtime layers
|
|
7
|
+
|
|
8
|
+
| Layer | Role | Implementation |
|
|
9
|
+
| --- | --- | --- |
|
|
10
|
+
| **Pi Coding Agent** | Primary local runtime — runs the dispatcher and specialist subagents | `.pi/harnesses/`, `.pi/extensions/`, `.pi/agents/`, `.pi/prompts/` |
|
|
11
|
+
| **agent-hub** | Thin-context multi-agent harness: dispatcher + specialists + research helpers + Verification Contract | `.pi/harnesses/agent-hub/` |
|
|
12
|
+
| **Herdr** | Fleet/workspace control plane — spawns peer teams as tiled workspaces, presence via push events, snapshot/resume | [herdr.dev](https://herdr.dev); client in `.pi/harnesses/lib/herdr-client.ts`, layout in `scripts/lib/herdr-layout.ts` |
|
|
13
|
+
| **coms** | Peer communication protocol/data plane — envelope-based P2P messaging between agents | `.pi/harnesses/coms/`, `scripts/lib/coms-envelope.ts`, `scripts/coms-cli.ts` |
|
|
14
|
+
| **Claude Code bridge** | Makes an interactive Claude Code pane a bidirectional coms peer | `scripts/coms-claude-bridge.ts`, `hooks/coms-stop-hook.mjs`, `skills/peer-coms/` — see [claude-code-coms-bridge.md](claude-code-coms-bridge.md) |
|
|
15
|
+
| **Hermes bridge** | Remote human control — relays hub questions to Telegram, races phone vs. local answers, conductor/liaison skills | `scripts/coms-hermes-bridge.ts`, `.pi/harnesses/ask-user-remote/`, `hermes/skills/` — see [coms-hermes-bridge.md](coms-hermes-bridge.md) |
|
|
16
|
+
| **Hermes local monitor transport** | Local, authenticated monitor contract for Hub-owned task generations; consumers supply their own presentation | `.pi/harnesses/agent-hub/monitor-*.ts`, `.pi/harnesses/lib/hermes-monitor-{model,store,registry,socket}.ts` (with compatibility re-exports under `scripts/lib/`) — see [Hermes artifacts](../hermes/README.md#local-agent-hub-monitor-integration) and [watchdog limits](hermes-watchdog-supervisor.md) |
|
|
17
|
+
| **Hermes Desktop plugin** (`agent-fleet-herdr`) | Fleet observability surface — read-only panel of every live session joined from the coms registry, herdr presence, agent transcripts, and the monitor transport; `focus` and subagent `cancel` are its only write doors | `hermes/desktop-plugins/agent-fleet-herdr/` (Electron pane), `hermes/plugins/agent-fleet-herdr/dashboard/` (FastAPI backend), installed by `scripts/install-hermes-plugin.sh` — see [hermes-desktop-plugins.md](hermes-desktop-plugins.md) |
|
|
18
|
+
| **Codex remote-control conductor** | Experimental outbound-only, user-systemd-managed Android conductor; verified on Codex CLI 0.144.x | `scripts/codex-remote-control.ts`, `scripts/codex-conductor.ts`, `codex/CONDUCTOR.md`, `systemd/user/`; runtime under `~/.local/state/agent-fleet/codex-conductor/` — see [codex-remote-conductor.md](codex-remote-conductor.md) |
|
|
19
|
+
| **Skill library** | Lifecycle workflows and quality gates every agent follows | `skills/` (native) + `vendor/agent-skills-upstream/skills/` (vendored) — see [UPSTREAM-SKILLS.md](UPSTREAM-SKILLS.md) |
|
|
20
|
+
| **Personas** | Reusable specialist definitions, transformed per harness | `agents/`, `bin/lib/transform-persona.js` |
|
|
21
|
+
|
|
22
|
+
## Fleet hierarchy
|
|
23
|
+
|
|
24
|
+
Agent Fleet is layered on purpose. Work flows **down** (delegate); evidence and status flow **up** — as compact structured returns, never raw dumps.
|
|
25
|
+
|
|
26
|
+
```mermaid
|
|
27
|
+
flowchart TD
|
|
28
|
+
You(["You · Hermes inbound relay · Codex outbound conductor on your phone"])
|
|
29
|
+
|
|
30
|
+
subgraph HUBL["HUB — thin dispatcher (just fleet hub · just fleet team)"]
|
|
31
|
+
Hub["agent-hub harness + orchestrator persona<br/>routes tasks · owns the Verification Contract on disk<br/>never swallows research dumps into its own context"]
|
|
32
|
+
end
|
|
33
|
+
|
|
34
|
+
subgraph TEAML["TEAM — named roster (.pi/agents/teams.yaml)"]
|
|
35
|
+
Team["default: planner · plan-reviewer · builder · test-engineer · code-reviewer · documenter<br/>also: debug · frontend · security · hotfix · release · info"]
|
|
36
|
+
end
|
|
37
|
+
|
|
38
|
+
subgraph RESL["RESEARCH HELPERS — read-only, always available"]
|
|
39
|
+
Research["researcher (fast tier — simple reads)<br/>deep-researcher (deep tier — hard, cross-cutting questions)"]
|
|
40
|
+
end
|
|
41
|
+
|
|
42
|
+
subgraph SUBL["SUB-AGENTS — focused children, narrow tools + models"]
|
|
43
|
+
Subs["planner → scout · rules · risk<br/>plan-reviewer → feasibility · deps<br/>builder → recon · verifier<br/>test-engineer → coverage-scout · conventions<br/>code-reviewer → preflight · quality · perf · docs<br/>security-auditor → recon · input-sweep · secrets-sweep"]
|
|
44
|
+
end
|
|
45
|
+
|
|
46
|
+
You -->|task| Hub
|
|
47
|
+
Hub -->|"dispatch_agent — one persona = one specialist session"| Team
|
|
48
|
+
Hub -->|"spawn_research"| Research
|
|
49
|
+
Research -.->|"findings written to disk — hub gets paths, not dumps"| Hub
|
|
50
|
+
Team -->|"subagents: block (delegate_depth ≥ 1)"| Subs
|
|
51
|
+
Subs -.->|"results return to the parent agent only"| Team
|
|
52
|
+
Team -.->|"structured return + evidence"| Hub
|
|
53
|
+
Hub -.->|"one status line: Assertions: 2✓ 1○ 1✗"| You
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Every specialist session is one persona from [`agents/`](../agents/) — *skills* tell each agent **how** to work; *personas* define **who** they are (see [agents.md](agents.md)).
|
|
57
|
+
|
|
58
|
+
The same idea as a tree:
|
|
59
|
+
|
|
60
|
+
```text
|
|
61
|
+
hub (orchestrator)
|
|
62
|
+
├── team: default
|
|
63
|
+
│ ├── planner → scout · rules · risk
|
|
64
|
+
│ ├── plan-reviewer → feasibility · deps
|
|
65
|
+
│ ├── builder → recon · verifier
|
|
66
|
+
│ ├── test-engineer → coverage-scout · conventions
|
|
67
|
+
│ ├── code-reviewer → preflight · quality · perf · docs
|
|
68
|
+
│ └── documenter
|
|
69
|
+
├── research helpers (spawn_research, any time)
|
|
70
|
+
│ ├── researcher
|
|
71
|
+
│ └── deep-researcher
|
|
72
|
+
└── optional fleet peers (herdr + coms)
|
|
73
|
+
├── architect / releaser / web-debugger panes
|
|
74
|
+
├── Claude Code peer (coms bridge)
|
|
75
|
+
├── Hermes (phone human · inbound ask_user)
|
|
76
|
+
└── Codex Remote Control (Android · outbound coms delegation)
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Composition rule: **the hub (or a slash command) orchestrates; personas do not invoke other personas as peers.** Specialists may only fan out to their configured **sub-agents**. Research helpers write findings to disk; the hub resumes specialists with paths, not raw dumps.
|
|
80
|
+
|
|
81
|
+
### Research search supervision
|
|
82
|
+
|
|
83
|
+
The shared `spawnPiAgent` seam supervises every `read`/`grep`/`find`/`ls` call from native
|
|
84
|
+
research helpers and nested delegate children. The supervisor tracks JSONL `toolCallId` values
|
|
85
|
+
independently, with a default 120-second deadline (`recon-search-timeout-s: 1..3600|off` under
|
|
86
|
+
`## agent-hub`). It is a per-tool watchdog; the whole-run bound is separate — the execution
|
|
87
|
+
mode's per-run deadline (`agent-turn-timeout-s`), which terminates a hung run as `turn_timeout`.
|
|
88
|
+
On timeout or caller cancellation it owns and terminates the child's process group (SIGTERM,
|
|
89
|
+
then SIGKILL after a bounded grace), has a separate settlement timer for missing `close`/pipe
|
|
90
|
+
drain, and reports timeout separately from cancellation. Research helpers and nested delegates
|
|
91
|
+
are each given safe process-group ownership; delegates forward parent termination so no detached
|
|
92
|
+
child is orphaned. Full pattern catalog: [references/orchestration-patterns.md](../references/orchestration-patterns.md).
|
|
93
|
+
|
|
94
|
+
### Execution modes & turn budgets
|
|
95
|
+
|
|
96
|
+
The hub enforces per-user-turn budgets in code (`run-budget.js`): `fast`/`standard`/`strict`
|
|
97
|
+
modes cap `dispatch_agent` calls, `spawn_research` calls, and wall clock per turn, set the
|
|
98
|
+
per-run deadline above, and control nested delegation. Exhausted budgets make the dispatch
|
|
99
|
+
tools refuse with "summarize and ask the user"; a new user message opens a fresh window.
|
|
100
|
+
Specialist context pressure is measured over input + cacheRead + cacheWrite against **that
|
|
101
|
+
agent's own** model window, resolved from pi's model registry with the source recorded
|
|
102
|
+
(`context-window.js`) — measuring a 49k local model against the dispatcher's window is what
|
|
103
|
+
made readings like "315%" unactionable; anything over 100% now emits a one-time diagnostic
|
|
104
|
+
naming the window and where it came from. Specialist sessions are recycled (fresh spawn
|
|
105
|
+
instead of `-c` resume) after `session-recycle-runs` runs, at ≥60% measured context, and
|
|
106
|
+
unconditionally at a full window; a resumed session whose *projected* prompt would overflow
|
|
107
|
+
is recycled before the spawn rather than after the run. Requests to one provider are capped
|
|
108
|
+
per process (`provider-semaphore.js`: 2 in flight for `custom/*` by default, unlimited
|
|
109
|
+
elsewhere, `AGENT_HUB_PROVIDER_LIMITS` to override) — the cap is per level of the delegation
|
|
110
|
+
tree, and a nested spawn reuses its parent's permit so it can never wait on its own ancestor.
|
|
111
|
+
Configured under `## agent-hub` (`mode`, `max-dispatches-per-turn`,
|
|
112
|
+
`max-research-per-turn`, `turn-wall-time-s`, `agent-turn-timeout-s`, `session-recycle-runs`,
|
|
113
|
+
`run-history-keep`); switched live with `/af-hub-mode`.
|
|
114
|
+
|
|
115
|
+
A per-message allowance cannot bound a task, so a second envelope sits above the turn one:
|
|
116
|
+
the **task budget** (`run-budget.js`, `3×` the turn envelope) counts dispatches, research
|
|
117
|
+
runs and **active** time across the WHOLE task and is *not* reset by a user message. Active
|
|
118
|
+
time is turns that ran minus `ask_user` waits — a task clock that billed human idle would
|
|
119
|
+
false-stop a normal steered session, and a false stop teaches people to reset the window
|
|
120
|
+
reflexively. The auto-research pipe is exempt from the turn budget but charged against the
|
|
121
|
+
task envelope, so it cannot smuggle 8 helpers per dispatch past the outer bound. Exhausting
|
|
122
|
+
the task budget is a hard stop — only `/af-new-task` (or `set_task_tier` with
|
|
123
|
+
`new_task: true`) opens a new window. This is the guardrail the post-mortem run never hit: every steering message
|
|
124
|
+
reopened the turn window, so one workspace stayed open 47 hours on a change that took 13
|
|
125
|
+
minutes in a narrow one.
|
|
126
|
+
|
|
127
|
+
On top of the mode sit several qualitative guardrails. **Task triage**: the dispatcher
|
|
128
|
+
classifies the current TASK via the `set_task_tier` tool (`trivial`/`small`/`feature`/`project`)
|
|
129
|
+
and the caps drop to min(mode, tier). The tier is task-scoped and **ratcheted** — it survives
|
|
130
|
+
the user's next message, lowering is free, raising needs a stated `reason` — because a
|
|
131
|
+
turn-scoped tier reset to `feature` on every correction. Three refusals enforce
|
|
132
|
+
proportionality in code rather than prose: a duplicate-dispatch guard (near-identical
|
|
133
|
+
re-dispatches within a turn), a **tier persona gate** (`planner`, `plan-reviewer`,
|
|
134
|
+
`architect`, `security-auditor`, `deep-researcher` are refused at trivial/small — each opens
|
|
135
|
+
a document/finding loop), and a **review round cap** (review dispatches per task, by tier).
|
|
136
|
+
Skipping triage assumes `small`, not `feature`: the tier latches for the task, and the case
|
|
137
|
+
where it was never declared is exactly the case where proportionality was not being
|
|
138
|
+
considered. The review **finding** budget is the one thing deliberately left advisory — the
|
|
139
|
+
hub counts blocking findings (`review-findings.js`) and reports an over-budget return, but
|
|
140
|
+
never reclassifies one, because no rule it can evaluate separates an invented manifest from
|
|
141
|
+
a leaked credential; the round cap is what carries the enforcement.
|
|
142
|
+
**Docs lane** (`docs-lane.js`): a dispatch whose whole declared `scope` is documentation
|
|
143
|
+
refuses review personas (overridable with `review_reason`) and tells the dispatcher not to
|
|
144
|
+
open a review gate; an absent scope is never the lighter lane. **External-blocker stop**
|
|
145
|
+
(`external-blocker.js`): a specialist emits `EXTERNAL_BLOCKED: …` when it needs something
|
|
146
|
+
outside the fleet's reach (account, permission, credential, telemetry destination), and the
|
|
147
|
+
hub refuses the next dispatch with an owner-escalation packet until the human is addressed —
|
|
148
|
+
the alternative, observed, is hours spent approximating the missing fact with scripts,
|
|
149
|
+
manifests and fixtures while the assertion still ends UNPROVEN. **Drift watchdog**
|
|
150
|
+
(`drift-watchdog.js`): armed dispatches are
|
|
151
|
+
observed in-flight from the JSON event stream — deterministic rules (out-of-scope writes
|
|
152
|
+
against the declared `scope` globs, tool-call loops, consecutive failures, tool-call cap)
|
|
153
|
+
escalate to a one-shot cheap LLM judge whose DRIFTING/STUCK verdict terminates the run as
|
|
154
|
+
`drift_stop` (exit 125, partial output preserved); enabled per hub/agent/dispatch
|
|
155
|
+
(`watchdog` key, `/af-watchdog`, `watchdog` param). Two rules about scope: the session's
|
|
156
|
+
own `artifacts/`, `findings/`, and `delegations/` subtrees are implicitly in scope (the
|
|
157
|
+
deliverable protocol *orders* specialists to write there, and the judge is told so), and the
|
|
158
|
+
`scope` rule is non-terminal — it reports a drift advisory on the result and never stops a
|
|
159
|
+
run by itself, matching the post-run scope gate, which reverts nothing. **Dynamic teams**: `/af-agents-add`,
|
|
160
|
+
`/af-agents-drop`, `/af-agents-save` restructure the roster live (the system prompt rebuilds
|
|
161
|
+
every turn), and the gated `team_adjust` tool lets the dispatcher itself adjust the roster
|
|
162
|
+
outside fast mode, with user notification. `/af-hub-report` accounts each turn's dispatches,
|
|
163
|
+
tokens (billed = input + cacheRead + cacheWrite), recycles, drift stops, and refusals.
|
|
164
|
+
|
|
165
|
+
## Runtime stack (tools the fleet sits on)
|
|
166
|
+
|
|
167
|
+
```mermaid
|
|
168
|
+
flowchart TD
|
|
169
|
+
AF["<b>Agent Fleet</b><br/>agent-hub · personas · skills · coms · bridges · CLI"]
|
|
170
|
+
AF -->|primary runtime| PI["<b>pi</b><br/>coding agent — loads harnesses,<br/>extensions, prompts, personas"]
|
|
171
|
+
AF -->|control plane| HERDR["<b>herdr</b><br/>tiled peer workspaces,<br/>presence, snapshot/resume"]
|
|
172
|
+
AF -->|peer + install target| CC["<b>Claude Code</b><br/>bidirectional peer via<br/>the coms bridge"]
|
|
173
|
+
AF -->|install target| OC["<b>OpenCode</b><br/>skill-driven execution<br/>(AGENTS.md + skill tool)"]
|
|
174
|
+
AF -->|remote human| HERMES["<b>Hermes</b><br/>hub questions relayed to your phone,<br/>plus the Desktop fleet panel"]
|
|
175
|
+
AF -->|outbound remote delegation| CODEX["<b>Codex Remote Control</b><br/>Android-approved calls to<br/>listed coms peers (experimental)"]
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### External dependencies
|
|
179
|
+
|
|
180
|
+
These are the external systems Agent Fleet assumes or integrates with — not npm packages, but the **runtime stack** the fleet operates on top of.
|
|
181
|
+
|
|
182
|
+
| Dependency | Role | Required? |
|
|
183
|
+
| --- | --- | --- |
|
|
184
|
+
| **[pi](https://github.com/badlogic/pi-mono)** (or your pi install) | Primary coding-agent runtime; loads harnesses, extensions, prompts, and personas | Yes for full fleet mode (`just fleet hub`) |
|
|
185
|
+
| **[herdr](https://herdr.dev)** | Workspace control plane: tiled peer panes, presence push events, team snapshot/resume | Yes for team mode (`just fleet team`); optional for `just fleet hub` |
|
|
186
|
+
| **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** | First-class peer via the [coms bridge](claude-code-coms-bridge.md); also a supported install target for skills/personas | Optional peer / alternate harness |
|
|
187
|
+
| **[OpenCode](https://opencode.ai)** | Skill-driven execution target (`AGENTS.md` + `skill` tool); `af-*` slash commands | Optional alternate harness |
|
|
188
|
+
| **Hermes** | Remote human-in-the-loop (Telegram relay for hub questions — [coms-hermes-bridge](coms-hermes-bridge.md)) and the Desktop fleet panel ([hermes-desktop-plugins](hermes-desktop-plugins.md), needs v0.19.0+ and the Desktop app) | Optional |
|
|
189
|
+
| **Codex CLI + ChatGPT Android** | Experimental outbound remote-control conductor on supported `0.144.x`; requires Node `22.6+`, user systemd, interactive pairing, and per-command mobile approvals — [runbook](codex-remote-conductor.md) | Optional / revalidate after minor-version or mobile-client changes |
|
|
190
|
+
| **[addyosmani/agent-skills](https://github.com/addyosmani/agent-skills)** | Upstream skill library (manually vendored) | Bundled (vendored) |
|
|
191
|
+
| **[disler/pi-vs-claude-code](https://github.com/disler/pi-vs-claude-code)** | Source inspiration / MIT port origin for pi harnesses | Design lineage (ported in-repo) |
|
|
192
|
+
| **LLM providers** | Models per persona (`model:` / `models:` in agent frontmatter) — e.g. OpenAI Codex, GitHub Copilot, Ollama, … | Yes (at least one provider your agents can call) |
|
|
193
|
+
| **Chrome DevTools MCP** / **Playwright Agent CLI** | Browser verify (`browser-testing-with-devtools`) and headless automation (`bowser`) | Optional, feature-specific |
|
|
194
|
+
| **Node.js + npm** | CLI (`npx @chankov/agent-fleet`), package install, `just` recipes | Yes for install & tooling |
|
|
195
|
+
|
|
196
|
+
## Repository module map
|
|
197
|
+
|
|
198
|
+
```text
|
|
199
|
+
.pi/ # Pi runtime: harnesses, extensions, agents config, prompts
|
|
200
|
+
skills/ # Agent Fleet-native skills (shadow vendored names)
|
|
201
|
+
agents/ # Personas/subagents used by Agent Fleet
|
|
202
|
+
scripts/ # CLI helpers, bridges, team + one-off peer launchers (pure logic in scripts/lib/)
|
|
203
|
+
hermes/ # Hermes-facing skills/integration assets
|
|
204
|
+
codex/ # Canonical Codex conductor contract (runtime copy lives outside checkout)
|
|
205
|
+
systemd/user/ # Owned user-unit template for Codex remote control
|
|
206
|
+
vendor/agent-skills-upstream/ # Manually imported upstream skills (pinned SHA)
|
|
207
|
+
bin/ # npm CLI: init/update/doctor/transform-persona
|
|
208
|
+
hooks/ # Session lifecycle + coms Stop hooks
|
|
209
|
+
references/ # Supplementary checklists (see fleet-coordination-patterns.md)
|
|
210
|
+
docs/ # This file, setup guides, bridge references, vendoring policy
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
Reserved for future modules (do not repurpose these paths):
|
|
214
|
+
|
|
215
|
+
```text
|
|
216
|
+
apps/dashboard/ # future dashboard: Kanban state, Herdr workspaces, peer status
|
|
217
|
+
packages/fleet-core/ # future extracted core orchestration library
|
|
218
|
+
packages/herdr-bridge/ # future Herdr integration package
|
|
219
|
+
packages/hermes-bridge/ # future Hermes integration package
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
## Design rules
|
|
223
|
+
|
|
224
|
+
- **Thin dispatcher context.** Nothing lands persistently in the dispatcher's
|
|
225
|
+
context if it can live on disk or in a one-line status. Research findings,
|
|
226
|
+
the Verification Contract ledger, and team snapshots are all disk-first.
|
|
227
|
+
- **A harness fault must never look like a specialist fault.** The hub passes
|
|
228
|
+
`--session <file>` on every run, so one corrupt session file used to fail a
|
|
229
|
+
persona in ~1s with no output — indistinguishable from a bad agent, and
|
|
230
|
+
unrecoverable by drop + re-add. Unusable session files are now validated and
|
|
231
|
+
quarantined (`session-health.js`) with the reset named in the result. Same rule
|
|
232
|
+
for the return contract: a report the parser cannot read gets one cheap
|
|
233
|
+
read-only extraction pass (`return-extract.js`) before its assertions are
|
|
234
|
+
written off as unproven, and extracted evidence is always labelled as weaker
|
|
235
|
+
than declared evidence. The converse also holds: a run that errored or timed
|
|
236
|
+
out writes to `artifacts/failures/`, never `returns/` — an error stub filed
|
|
237
|
+
as a return reads as a specialist verdict and gets acted on as one.
|
|
238
|
+
- **A pool status field beats reading the screen.** `coms_list` publishes each
|
|
239
|
+
peer's `pane_id` and `status` (`idle`/`working`/`booting`), and
|
|
240
|
+
`herdr_spawn_peer` waits for the peer to register and returns `peer_ready`
|
|
241
|
+
rather than a bare pane id. A spawned peer boots idle and does nothing until
|
|
242
|
+
addressed, so peers spawned and never sent to are named at turn end and in
|
|
243
|
+
`/af-hub-report` (`spawned-peers.js`); closing stays the human's call.
|
|
244
|
+
- **A declared requirement carries its origin.** Every assertion in the ledger
|
|
245
|
+
names its source (`assertion-ledger.js`), and the open ledger is soft-capped
|
|
246
|
+
at 8 — an id nobody can trace back to a plan line costs a dispatch and an
|
|
247
|
+
ASK_USER cycle to re-derive.
|
|
248
|
+
- **Pre-flight validation is free.** Anything the hub can reject before spawning
|
|
249
|
+
— an unresolvable artifact path, an unknown research persona, a heavy persona
|
|
250
|
+
at a low tier, a reviewer on a docs-only scope — is refused without spending a
|
|
251
|
+
budget slot. Artifact paths also resolve across artifact kinds when the name is
|
|
252
|
+
unique, since the hub writes every auto-return under `returns/` while
|
|
253
|
+
dispatchers reasonably guess `reviews/`.
|
|
254
|
+
- **Evidence is archived, never overwritten.** Session start moves the previous
|
|
255
|
+
session's `artifacts/` into an immutable `.pi/agent-sessions/runs/<runId>/`
|
|
256
|
+
namespace with a read-only `meta.json` and an appended `runs/index.json`
|
|
257
|
+
(`run-namespace.js`), retained per `run-history-keep` (default 10). The old
|
|
258
|
+
behaviour — delete `artifacts/` at start, name returns by a per-session counter
|
|
259
|
+
— collided two ways at once and made a post-mortem record eleven specialist
|
|
260
|
+
returns and two reviews as NOT RECOVERABLE. A failed archive leaves the
|
|
261
|
+
artifacts in place: a stale tree is recoverable, a deleted one is not.
|
|
262
|
+
- **Herdr owns panes, presence, and lifecycle; coms owns messages.** Fleet
|
|
263
|
+
recipes hard-require a running herdr server and refuse with an actionable
|
|
264
|
+
message otherwise; non-fleet recipes never touch herdr.
|
|
265
|
+
- **External agents are peers, not plugins.** Claude Code (and future CLI
|
|
266
|
+
agents) join the fleet through bridge adaptors that speak coms envelopes —
|
|
267
|
+
the fleet core stays agent-agnostic. Hermes remains the inbound `ask_user`/
|
|
268
|
+
Telegram route; the experimental Codex conductor is outbound-initiated only,
|
|
269
|
+
approval-gated, and restricted to listed peers through the validated wrapper.
|
|
270
|
+
- **Hermes monitor presentation is outside the fleet core.** Agent Fleet exposes owner-only
|
|
271
|
+
local monitor operations for Hub-owned state; a consumer owns its UI and lifecycle. The
|
|
272
|
+
worktree contains additive monitor/event/invoke code, but that implementation and its local
|
|
273
|
+
tests are not proof of a durable external identity or live delivery contract. `invoke`, where
|
|
274
|
+
available, is Hub-owned and queues dispatcher work rather than exposing tools directly.
|
|
275
|
+
- **Packaged Hermes source is opt-in, never auto-installed.** The npm tarball carries the
|
|
276
|
+
`hub-watchdog` skill (`hermes/skills/`) plus the backend and Desktop monitor plugin source
|
|
277
|
+
(`hermes/plugins/`, `hermes/desktop-plugins/`) as runtime-only source. Shipping that source
|
|
278
|
+
makes it available to an operator; installing it into a Hermes profile is always an explicit
|
|
279
|
+
action through `agent-fleet set-hermes-watchdog` (skill) or the consumer's own flow (plugins).
|
|
280
|
+
Nothing is enabled, launched, or configured by installing the package.
|
|
281
|
+
- **Watchdog delivery is capability-gated and currently unproven.** No checked-in
|
|
282
|
+
Gate O live artifact proves Hermes origin identity, updates, reconnect, or two-chat isolation,
|
|
283
|
+
so its supported posture is journal-only/dormant: no delivery, steering, or surgical use. It
|
|
284
|
+
never manages services, gateways, Herdr, or shell commands. Local runtime evidence — including
|
|
285
|
+
a real foreground watcher against a disposable Hub UDS — is `synthetic-local` and proves none of
|
|
286
|
+
those capabilities; see [the watchdog runbook](hermes-watchdog-supervisor.md).
|
|
287
|
+
- **External conductor contracts are advisory.** Pi damage-control wraps Pi
|
|
288
|
+
tool calls, not Hermes or Codex processes; human approvals and their
|
|
289
|
+
contracts reduce risk but do not provide an OS command allowlist.
|
|
290
|
+
- **Destructive fleet verbs are damage-control-guarded.** Specialists cannot
|
|
291
|
+
spawn/close herdr panes; the human confirms destructive actions.
|
|
292
|
+
- **Native-over-vendored skills.** The skill catalogue resolves `skills/`
|
|
293
|
+
first, then the vendored upstream import; upstream updates are explicit
|
|
294
|
+
maintainer actions ([UPSTREAM-SKILLS.md](UPSTREAM-SKILLS.md)).
|
|
295
|
+
|
|
296
|
+
## History
|
|
297
|
+
|
|
298
|
+
Agent Fleet began as a fork of `addyosmani/agent-skills` and was split into a
|
|
299
|
+
standalone repository in July 2026, with upstream demoted to vendored content.
|
|
300
|
+
The one-time migration record, including the history-filtering commands, lives
|
|
301
|
+
in [MIGRATION-agent-fleet.md](MIGRATION-agent-fleet.md); the product
|
|
302
|
+
requirements that drove the split are in
|
|
303
|
+
[prd-agent-fleet-split.md](prd-agent-fleet-split.md).
|