@chankov/agent-fleet 2.0.7 → 2.0.8
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/{hermes → .pi/agent-fleet/hermes}/README.md +7 -7
- package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/activity.py +2 -2
- package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/coms_registry.py +2 -2
- package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/coms_send.py +1 -1
- package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/watch.py +2 -2
- package/{hermes → .pi/agent-fleet/hermes}/skills/hub-conductor/SKILL.md +1 -1
- package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/SKILL.md +3 -3
- package/{hooks → .pi/agent-fleet/hooks}/coms-stop-hook.mjs +2 -2
- package/{scripts → .pi/agent-fleet/scripts}/claude-code-preflight.ts +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/coms-claude-bridge.ts +6 -6
- package/{scripts → .pi/agent-fleet/scripts}/coms-cli.ts +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/coms-hermes-bridge.ts +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/fleet-codex-read.py +5 -3
- package/{scripts → .pi/agent-fleet/scripts}/fleet.ts +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/flow.ts +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/lib/claude-bridge-core.ts +2 -2
- package/{scripts → .pi/agent-fleet/scripts}/lib/coms-envelope.ts +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/lib/fleet-codex-transport.ts +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/lib/herdr-layout.ts +3 -3
- package/{scripts → .pi/agent-fleet/scripts}/lib/hermes-bridge-core.ts +1 -1
- package/.pi/agent-fleet/scripts/lib/hermes-monitor-events.ts +1 -0
- package/.pi/agent-fleet/scripts/lib/hermes-monitor-herdr.ts +2 -0
- package/{scripts → .pi/agent-fleet/scripts}/lib/hermes-monitor-model.ts +1 -1
- package/.pi/agent-fleet/scripts/lib/hermes-monitor-registry.ts +2 -0
- package/.pi/agent-fleet/scripts/lib/hermes-monitor-socket.ts +2 -0
- package/.pi/agent-fleet/scripts/lib/hermes-monitor-store.ts +2 -0
- package/{scripts → .pi/agent-fleet/scripts}/lib/monitor-env.ts +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/lib/peer-launch.ts +3 -3
- package/{scripts → .pi/agent-fleet/scripts}/lib/persona-banner.ts +1 -1
- package/.pi/agent-fleet/scripts/lib/persona-dirs.ts +25 -0
- package/{scripts → .pi/agent-fleet/scripts}/lib/runtime-dependencies.js +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/lib/spawn-stagger.ts +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/lib/team-project.ts +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/lib/team-snapshot.ts +2 -2
- package/{scripts → .pi/agent-fleet/scripts}/peer-banner.ts +5 -4
- package/{scripts → .pi/agent-fleet/scripts}/peer-launch.ts +7 -9
- package/{scripts → .pi/agent-fleet/scripts}/team-snapshot.ts +5 -5
- package/{scripts → .pi/agent-fleet/scripts}/team-up.ts +6 -6
- package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/agent-phase.ts +3 -3
- package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/envelopes.ts +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/model-profile.ts +1 -1
- package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/personas.ts +2 -2
- package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/trace.ts +1 -1
- package/.pi/agents/peers.yaml +3 -1
- package/.pi/harnesses/agent-hub/README.md +1 -1
- package/.pi/harnesses/agent-hub/config/agents.ts +5 -1
- package/.pi/harnesses/agent-hub/debate-command.ts +1 -1
- package/.pi/harnesses/agent-hub/index.ts +19 -19
- package/.pi/harnesses/agent-hub/package.json +1 -1
- package/.pi/harnesses/agent-hub/peer-spawn-plan.ts +1 -1
- package/.pi/harnesses/agent-hub/tools/fleet-tools.ts +3 -5
- package/.pi/harnesses/agent-hub/tools/herdr-executors.ts +2 -2
- package/.pi/harnesses/ask-user-remote/index.ts +2 -2
- package/.pi/harnesses/coms/package.json +1 -1
- package/.pi/harnesses/damage-control-continue/package.json +1 -1
- package/.pi/harnesses/lib/spawned-peers.js +1 -1
- package/.pi/prompts/af-constraints.md +31 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/README.md +347 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/desktop-plugins/agent-fleet-herdr/plugin.js +1291 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/desktop-plugins/agent-fleet-herdr/presentation.js +672 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/desktop-plugins/agent-fleet-monitor/plugin.js +19 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/desktop-plugins/agent-fleet-monitor/state.js +10 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/gates/gate-o-capability.md +8 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/gates/gate-o-validator-fixtures.json +1 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/activity.py +773 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/coms_registry.py +134 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/coms_send.py +350 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/herdr_source.py +193 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/manifest.json +4 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/plugin_api.py +444 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/sessions.py +205 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/tasks.py +300 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/dashboard/watch.py +819 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-herdr/plugin.yaml +8 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-monitor/dashboard/adapter.py +139 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-monitor/dashboard/manifest.json +11 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/plugins/agent-fleet-monitor/dashboard/plugin_api.py +50 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-conductor/SKILL.md +84 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-liaison/SKILL.md +84 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/SKILL.md +76 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/manifest.json +1 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog.py +249 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_actions.py +124 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_contract.py +76 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_delivery.py +10 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_engine.py +128 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_judgment.py +41 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_recovery.py +103 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_state.py +163 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/skills/hub-watchdog/scripts/watchdog_transport.py +138 -0
- package/.versions/2.0.8/.pi/agent-fleet/hermes/watchdog-tests/__init__.py +0 -0
- package/.versions/2.0.8/.pi/agent-fleet/hooks/coms-stop-hook.mjs +84 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/claude-code-preflight.ts +70 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/coms-claude-bridge.ts +411 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/coms-cli.ts +425 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/coms-hermes-bridge.ts +413 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/fleet-codex-client.ts +69 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/fleet-codex-read.py +148 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/fleet.ts +216 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/flow.ts +137 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/hermes-monitor-capability-runner.ts +25 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/hermes-monitor-scenario.ts +474 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/hermes-watchdog-capability-probe.ts +45 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/install-hermes-plugin.sh +180 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/claude-bridge-core.ts +210 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/coms-envelope.ts +582 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/fake-herdr-server.ts +88 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/fleet-codex-catalog.ts +63 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/fleet-codex-operations.ts +190 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/fleet-codex-session.ts +166 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/fleet-codex-transport.ts +124 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/fleet-command.ts +252 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/flow-command.ts +93 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/flow-maintenance.ts +230 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/herdr-layout.ts +281 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-bridge-core.ts +241 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-monitor-events.ts +1 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-monitor-herdr.ts +2 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-monitor-model.ts +3 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-monitor-registry.ts +2 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-monitor-socket.ts +2 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/hermes-monitor-store.ts +2 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/monitor-env.ts +146 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/peer-launch.ts +318 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/persona-banner.ts +62 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/persona-dirs.ts +25 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/runtime-dependencies.js +124 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/spawn-stagger.ts +101 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/team-project.ts +178 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/lib/team-snapshot.ts +147 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/package-lock.json +35 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/package.json +9 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/peer-banner.ts +41 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/peer-launch.ts +283 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/team-snapshot.ts +237 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/team-up.ts +378 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/agent-phase.ts +133 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/changes.ts +61 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/debate.ts +149 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/env.ts +34 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/envelopes.ts +169 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/gates.ts +81 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/git.ts +96 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/merge.ts +95 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/model-profile.ts +22 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/model-visibility.ts +92 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/permissions.ts +130 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/personas.ts +57 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/poll.ts +86 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/quality.ts +64 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/run.ts +108 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/trace.ts +34 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/voices.ts +128 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/lib/writer-lease.ts +112 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/tsconfig.json +22 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/wf-build-test.ts +61 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/wf-debate.ts +87 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/wf-document.ts +50 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/wf-poll.ts +95 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/wf-quality.ts +20 -0
- package/.versions/2.0.8/.pi/agent-fleet/scripts/workflows/wf-scout.ts +38 -0
- package/.versions/2.0.8/.pi/agents/dispatch-policy.yaml +32 -0
- package/.versions/2.0.8/.pi/agents/model-profiles.yaml +83 -0
- package/.versions/2.0.8/.pi/agents/peers.yaml +147 -0
- package/.versions/2.0.8/.pi/agents/teams.yaml +41 -0
- package/.versions/2.0.8/.pi/agents/voices.yaml +13 -0
- package/.versions/2.0.8/.pi/damage-control-rules.yaml +297 -0
- package/.versions/2.0.8/.pi/extensions/btw/README.md +120 -0
- package/.versions/2.0.8/.pi/extensions/btw/index.ts +914 -0
- package/.versions/2.0.8/.pi/extensions/btw/package.json +6 -0
- package/.versions/2.0.8/.pi/extensions/btw/state.js +179 -0
- package/.versions/2.0.8/.pi/extensions/chrome-devtools-mcp/README.md +55 -0
- package/.versions/2.0.8/.pi/extensions/chrome-devtools-mcp/index.ts +93 -0
- package/.versions/2.0.8/.pi/extensions/chrome-devtools-mcp/package.json +6 -0
- package/.versions/2.0.8/.pi/extensions/compact-and-continue/README.md +42 -0
- package/.versions/2.0.8/.pi/extensions/compact-and-continue/index.ts +120 -0
- package/.versions/2.0.8/.pi/extensions/compact-and-continue/package.json +6 -0
- package/.versions/2.0.8/.pi/extensions/mcp-bridge/README.md +46 -0
- package/.versions/2.0.8/.pi/extensions/mcp-bridge/index.ts +206 -0
- package/.versions/2.0.8/.pi/extensions/mcp-bridge/package.json +6 -0
- package/.versions/2.0.8/.pi/extensions/package-lock.json +1175 -0
- package/.versions/2.0.8/.pi/extensions/package.json +9 -0
- package/.versions/2.0.8/.pi/extensions/pi-voice-stt/README.md +205 -0
- package/.versions/2.0.8/.pi/extensions/pi-voice-stt/config.ts +198 -0
- package/.versions/2.0.8/.pi/extensions/pi-voice-stt/examples/stt.json +35 -0
- package/.versions/2.0.8/.pi/extensions/pi-voice-stt/index.ts +248 -0
- package/.versions/2.0.8/.pi/extensions/pi-voice-stt/package.json +6 -0
- package/.versions/2.0.8/.pi/extensions/pi-voice-stt/providers.ts +214 -0
- package/.versions/2.0.8/.pi/extensions/pi-voice-stt/recorder.ts +158 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/README.md +1203 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/acceptance.ts +62 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/access-approval.ts +135 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/artifacts.js +146 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/assertion-ledger.js +58 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/backend-policy.js +174 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/budget-continuation.ts +13 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/budget-recovery.ts +97 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/capability-confirmation.ts +47 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/capability-packs.ts +180 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agent-model-thinking.ts +10 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agent-model.ts +10 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agent-models-substitute.ts +10 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-add.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-drop.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-history.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-kill.ts +10 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-list.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-restart.ts +10 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-save.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/agents-team.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/budget-continue.ts +10 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/compound.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/coms.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/context-command.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/context.ts +43 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/debate.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/dispatch-policy.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/handoff.ts +10 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/hub-report.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/models.ts +10 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/poll.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/retry.ts +10 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/watchdog.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/work-mode.ts +29 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/commands/zoom.ts +10 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/config/agents.ts +177 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/config/model-profiles.ts +216 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/config/overrides.ts +153 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/context/agent-state.ts +30 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/context/assertions-artifacts.ts +213 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/context/budgets.ts +202 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/context/hub-state.ts +40 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/context-budget-snapshot.ts +105 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/context-pressure.ts +191 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/context-window.js +106 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/debate-command.ts +176 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/delegate.ts +446 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-coms.ts +237 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-core.ts +27 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-native-complete.ts +154 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-native-prepare.ts +156 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-native-spawn.ts +193 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-native-types.ts +230 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-native.ts +213 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/dispatch-observability.ts +225 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/docs-lane.js +122 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/drift-watchdog.js +218 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/evidence-rules.js +96 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/execution-evidence.ts +80 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/external-blocker.js +85 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/fixtures/registration-surface.json +57 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/footer.ts +30 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/helpers.ts +266 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/hub-state-audit.js +64 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/index.ts +2151 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/input/completions.ts +76 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/input/shortcuts.ts +18 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/lifecycle/context-pressure.ts +123 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/lifecycle/monitor-session.ts +104 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/lifecycle/session-orchestration.ts +143 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/lifecycle/turn-handlers.ts +74 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-control.ts +9 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-invoke-journal.ts +131 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-invoke.ts +92 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-lifecycle.ts +13 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-publisher.ts +59 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-recovery.ts +3 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-runtime.ts +3 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/monitor-session-bridge.ts +266 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/no-progress.ts +76 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/package.json +7 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/peer-spawn-plan.ts +116 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/policy/models.ts +153 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/policy/profile-activation.ts +62 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/policy/profile-runtime.ts +120 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/policy/roster.ts +94 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/policy/work-mode.ts +119 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/poll-command.ts +176 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/presentation.ts +48 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/prompts/context.ts +47 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/prompts/fragments.ts +115 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/prompts/session-start.ts +90 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/prompts/system-prompt.ts +112 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/provider-semaphore.js +138 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/research/controls.ts +74 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/research/runtime.ts +192 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/research/spawn-run.ts +156 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/research-watchdog.ts +40 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/return-contract.js +293 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/return-extract.js +75 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/review-findings.js +102 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/run-budget.js +537 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/run-namespace.js +87 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/safety-routing.ts +22 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/scope-gate.js +123 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/session-health.js +110 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/session-start.ts +42 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/spawn.ts +404 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/timeline.ts +54 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/action-executors.ts +149 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/coms-tools.ts +139 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/context.ts +134 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/dispatch-agent.ts +82 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/dispatch-execution.ts +273 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/execution-orchestration.ts +22 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/fleet-tools.ts +200 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/herdr-executors.ts +86 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/set-task-tier.ts +29 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/spawn-research.ts +62 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/team-adjust.ts +29 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/tools/verification-contract.ts +77 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/types.ts +63 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/activity-dots.ts +16 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/context-budget.ts +86 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/detail-panel.ts +178 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/fleet-dashboard.ts +125 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/grid.ts +42 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/history-store.ts +137 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/history.ts +234 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/pool.ts +103 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/running-strip.ts +139 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/ui/zoom.ts +204 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/version.ts +42 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/work-mode-controls.ts +56 -0
- package/.versions/2.0.8/.pi/harnesses/agent-hub/work-mode.ts +167 -0
- package/.versions/2.0.8/.pi/harnesses/ask-user-remote/README.md +59 -0
- package/.versions/2.0.8/.pi/harnesses/ask-user-remote/index.ts +558 -0
- package/.versions/2.0.8/.pi/harnesses/ask-user-remote/questions.ts +161 -0
- package/.versions/2.0.8/.pi/harnesses/ask-user-remote/race-core.js +124 -0
- package/.versions/2.0.8/.pi/harnesses/ask-user-remote/runtime-ask.ts +43 -0
- package/.versions/2.0.8/.pi/harnesses/coms/README.md +100 -0
- package/.versions/2.0.8/.pi/harnesses/coms/index.ts +282 -0
- package/.versions/2.0.8/.pi/harnesses/coms/package.json +7 -0
- package/.versions/2.0.8/.pi/harnesses/coms/version.ts +42 -0
- package/.versions/2.0.8/.pi/harnesses/damage-control-continue/README.md +135 -0
- package/.versions/2.0.8/.pi/harnesses/damage-control-continue/index.ts +541 -0
- package/.versions/2.0.8/.pi/harnesses/damage-control-continue/package.json +7 -0
- package/.versions/2.0.8/.pi/harnesses/damage-control-continue/version.ts +42 -0
- package/.versions/2.0.8/.pi/harnesses/lib/coms-core-io.ts +385 -0
- package/.versions/2.0.8/.pi/harnesses/lib/coms-core.ts +577 -0
- package/.versions/2.0.8/.pi/harnesses/lib/coms-registry-entry.ts +94 -0
- package/.versions/2.0.8/.pi/harnesses/lib/context-budget-child-prompt.ts +180 -0
- package/.versions/2.0.8/.pi/harnesses/lib/context-budget-hub-prompt.ts +114 -0
- package/.versions/2.0.8/.pi/harnesses/lib/context-budget-view.ts +107 -0
- package/.versions/2.0.8/.pi/harnesses/lib/context-budget.ts +114 -0
- package/.versions/2.0.8/.pi/harnesses/lib/damage-control-shared.ts +197 -0
- package/.versions/2.0.8/.pi/harnesses/lib/fixtures/context-budget-profiles.json +11 -0
- package/.versions/2.0.8/.pi/harnesses/lib/fixtures/hub-prompt-operator.legacy.txt +73 -0
- package/.versions/2.0.8/.pi/harnesses/lib/fixtures/hub-prompt-orchestrator.legacy.txt +73 -0
- package/.versions/2.0.8/.pi/harnesses/lib/fleet-dashboard-ops.ts +161 -0
- package/.versions/2.0.8/.pi/harnesses/lib/fleet-dashboard-view.ts +148 -0
- package/.versions/2.0.8/.pi/harnesses/lib/fleet-detail-view.ts +247 -0
- package/.versions/2.0.8/.pi/harnesses/lib/fleet-overlay.ts +26 -0
- package/.versions/2.0.8/.pi/harnesses/lib/fleet-panel.ts +34 -0
- package/.versions/2.0.8/.pi/harnesses/lib/fleet-read-model.ts +131 -0
- package/.versions/2.0.8/.pi/harnesses/lib/fleet-selection.ts +24 -0
- package/.versions/2.0.8/.pi/harnesses/lib/fleet-transcript-store.ts +244 -0
- package/.versions/2.0.8/.pi/harnesses/lib/herdr-client.ts +472 -0
- package/.versions/2.0.8/.pi/harnesses/lib/herdr-presence.ts +399 -0
- package/.versions/2.0.8/.pi/harnesses/lib/hermes-monitor-events.ts +136 -0
- package/.versions/2.0.8/.pi/harnesses/lib/hermes-monitor-herdr.ts +28 -0
- package/.versions/2.0.8/.pi/harnesses/lib/hermes-monitor-model.ts +18 -0
- package/.versions/2.0.8/.pi/harnesses/lib/hermes-monitor-registry.ts +6 -0
- package/.versions/2.0.8/.pi/harnesses/lib/hermes-monitor-socket.ts +163 -0
- package/.versions/2.0.8/.pi/harnesses/lib/hermes-monitor-store.ts +31 -0
- package/.versions/2.0.8/.pi/harnesses/lib/spawned-peers.js +190 -0
- package/.versions/2.0.8/.pi/harnesses/lib/update-check.ts +222 -0
- package/.versions/2.0.8/.pi/harnesses/package-lock.json +2039 -0
- package/.versions/2.0.8/.pi/harnesses/package.json +10 -0
- package/.versions/2.0.8/.pi/prompts/af-build.md +24 -0
- package/.versions/2.0.8/.pi/prompts/af-code-simplify.md +22 -0
- package/.versions/2.0.8/.pi/prompts/af-constraints.md +31 -0
- package/.versions/2.0.8/.pi/prompts/af-plan.md +17 -0
- package/.versions/2.0.8/.pi/prompts/af-review.md +16 -0
- package/.versions/2.0.8/.pi/prompts/af-set-hermes-telegram.md +15 -0
- package/.versions/2.0.8/.pi/prompts/af-set-hermes-watchdog.md +6 -0
- package/.versions/2.0.8/.pi/prompts/af-ship.md +17 -0
- package/.versions/2.0.8/.pi/prompts/af-spec.md +15 -0
- package/.versions/2.0.8/.pi/prompts/af-test.md +19 -0
- package/.versions/2.0.8/.pi/skills/bowser/SKILL.md +145 -0
- package/.versions/2.0.8/.version +1 -0
- package/.versions/2.0.8/agents/architect.md +25 -0
- package/.versions/2.0.8/agents/bowser.md +28 -0
- package/.versions/2.0.8/agents/builder.md +56 -0
- package/.versions/2.0.8/agents/code-reviewer.md +210 -0
- package/.versions/2.0.8/agents/deep-researcher.md +33 -0
- package/.versions/2.0.8/agents/documenter.md +23 -0
- package/.versions/2.0.8/agents/orchestrator.md +23 -0
- package/.versions/2.0.8/agents/plan-reviewer.md +84 -0
- package/.versions/2.0.8/agents/planner.md +106 -0
- package/.versions/2.0.8/agents/releaser.md +25 -0
- package/.versions/2.0.8/agents/researcher.md +31 -0
- package/.versions/2.0.8/agents/security-auditor.md +168 -0
- package/.versions/2.0.8/agents/test-engineer.md +154 -0
- package/.versions/2.0.8/agents/web-debugger.md +44 -0
- package/.versions/2.0.8/agents/web-performance-auditor.md +194 -0
- package/.versions/2.0.8/bin/catalog/harness-runtime-closure.json +32 -0
- package/.versions/2.0.8/codex/fleet-session-client/SKILL.md +34 -0
- package/.versions/2.0.8/codex/fleet-session-client.zip +0 -0
- package/.versions/2.0.8/docs/ARCHITECTURE.md +416 -0
- package/.versions/2.0.8/docs/agent-fleet-setup.md +568 -0
- package/.versions/2.0.8/docs/claude-code-coms-bridge.md +134 -0
- package/.versions/2.0.8/docs/codex-session-bridge.md +219 -0
- package/.versions/2.0.8/docs/coms-hermes-bridge.md +188 -0
- package/.versions/2.0.8/docs/getting-started.md +126 -0
- package/.versions/2.0.8/docs/npm-install.md +356 -0
- package/.versions/2.0.8/docs/pi-extensions.md +446 -0
- package/.versions/2.0.8/docs/pi-setup.md +76 -0
- package/.versions/2.0.8/docs/skill-anatomy.md +150 -0
- package/.versions/2.0.8/install-manifest.json +2991 -0
- package/.versions/2.0.8/justfile +247 -0
- package/.versions/2.0.8/manifest-meta.json +970 -0
- package/.versions/2.0.8/references/accessibility-checklist.md +160 -0
- package/.versions/2.0.8/references/communication-contract.md +26 -0
- package/.versions/2.0.8/references/definition-of-done.md +67 -0
- package/.versions/2.0.8/references/fleet-coordination-patterns.md +171 -0
- package/.versions/2.0.8/references/observability-checklist.md +92 -0
- package/.versions/2.0.8/references/orchestration-patterns.md +370 -0
- package/.versions/2.0.8/references/performance-checklist.md +236 -0
- package/.versions/2.0.8/references/prompting-patterns.md +380 -0
- package/.versions/2.0.8/references/security-checklist.md +245 -0
- package/.versions/2.0.8/references/testing-patterns.md +235 -0
- package/.versions/2.0.8/references/workflow-authoring.md +304 -0
- package/.versions/2.0.8/skills/_internal/grilling.md +59 -0
- package/.versions/2.0.8/skills/browser-testing-with-devtools/SKILL.md +351 -0
- package/.versions/2.0.8/skills/code-review-and-quality/SKILL.md +396 -0
- package/.versions/2.0.8/skills/compound-learning/SKILL.md +137 -0
- package/.versions/2.0.8/skills/constraint-driven-development/SKILL.md +338 -0
- package/.versions/2.0.8/skills/constraint-driven-development/references/floor-guard.md +99 -0
- package/.versions/2.0.8/skills/context-engineering/SKILL.md +341 -0
- package/.versions/2.0.8/skills/deprecation-and-migration/SKILL.md +247 -0
- package/.versions/2.0.8/skills/designing-agents/SKILL.md +394 -0
- package/.versions/2.0.8/skills/designing-agents/pi-harness-authoring.md +222 -0
- package/.versions/2.0.8/skills/drafting-workflows/SKILL.md +143 -0
- package/.versions/2.0.8/skills/drafting-workflows/scripts/make-workflow.ts +177 -0
- package/.versions/2.0.8/skills/frontend-ui-engineering/SKILL.md +328 -0
- package/.versions/2.0.8/skills/git-workflow-and-versioning/SKILL.md +316 -0
- package/.versions/2.0.8/skills/idea-refine/SKILL.md +182 -0
- package/.versions/2.0.8/skills/idea-refine/examples.md +238 -0
- package/.versions/2.0.8/skills/idea-refine/frameworks.md +99 -0
- package/.versions/2.0.8/skills/idea-refine/refinement-criteria.md +113 -0
- package/.versions/2.0.8/skills/idea-refine/scripts/idea-refine.sh +15 -0
- package/.versions/2.0.8/skills/incremental-implementation/SKILL.md +302 -0
- package/.versions/2.0.8/skills/interview-me/SKILL.md +226 -0
- package/.versions/2.0.8/skills/orchestration-verification/SKILL.md +181 -0
- package/.versions/2.0.8/skills/peer-coms/SKILL.md +90 -0
- package/.versions/2.0.8/skills/performance-optimization/SKILL.md +496 -0
- package/.versions/2.0.8/skills/planning-and-task-breakdown/SKILL.md +289 -0
- package/.versions/2.0.8/skills/security-and-hardening/SKILL.md +524 -0
- package/.versions/2.0.8/skills/spec-driven-development/SKILL.md +295 -0
- package/.versions/2.0.8/skills/using-agent-skills/SKILL.md +198 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/LICENSE +21 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/README.md +430 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +367 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/browser-testing-with-devtools/SKILL.md +317 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/ci-cd-and-automation/SKILL.md +390 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +396 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/code-simplification/SKILL.md +331 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/constraint-driven-development/SKILL.md +311 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/constraint-driven-development/references/floor-guard.md +99 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +337 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +300 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +247 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +288 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +243 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +328 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +355 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/idea-refine/SKILL.md +178 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/idea-refine/examples.md +238 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/idea-refine/frameworks.md +99 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/idea-refine/refinement-criteria.md +113 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/idea-refine/scripts/idea-refine.sh +15 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +249 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/interview-me/SKILL.md +225 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +238 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +496 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +257 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +524 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +330 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +216 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +245 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +398 -0
- package/.versions/2.0.8/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +192 -0
- package/CHANGELOG.md +39 -0
- package/README.md +10 -9
- package/bin/catalog/harness-runtime-closure.json +23 -22
- package/bin/cli.js +24 -1
- package/bin/lib/apply.js +6 -2
- package/bin/lib/detect-agent.js +1 -1
- package/bin/lib/doctor.js +3 -3
- package/bin/lib/manifest.js +23 -16
- package/bin/lib/path-boundaries.js +96 -0
- package/bin/lib/personas.js +15 -2
- package/bin/lib/set-hermes-telegram.js +2 -2
- package/bin/lib/set-hermes-watchdog.js +1 -1
- package/bin/lib/state.js +5 -1
- package/bin/lib/verify.js +43 -5
- package/bin/snapshot-version.js +6 -6
- package/codex/fleet-session-client/SKILL.md +3 -3
- package/docs/ARCHITECTURE.md +29 -20
- package/docs/MIGRATION-agent-fleet.md +11 -7
- package/docs/agent-fleet-setup.md +9 -2
- package/docs/claude-code-coms-bridge.md +10 -9
- package/docs/codex-session-bridge.md +18 -18
- package/docs/coms-hermes-bridge.md +6 -6
- package/docs/hermes-watchdog-supervisor.md +1 -1
- package/docs/npm-install.md +30 -1
- package/docs/pi-extensions.md +6 -6
- package/docs/workflows.md +9 -5
- package/install-manifest.json +202 -97
- package/justfile +19 -19
- package/manifest-meta.json +50 -38
- package/package.json +26 -26
- package/references/observability-checklist.md +1 -0
- package/references/performance-checklist.md +83 -0
- package/references/prompting-patterns.md +1 -1
- package/references/security-checklist.md +85 -19
- package/references/testing-patterns.md +12 -13
- package/references/workflow-authoring.md +5 -5
- package/skills/code-review-and-quality/SKILL.md +17 -2
- package/skills/constraint-driven-development/SKILL.md +338 -0
- package/skills/constraint-driven-development/references/floor-guard.md +99 -0
- package/skills/context-engineering/SKILL.md +52 -2
- package/skills/deprecation-and-migration/SKILL.md +42 -1
- package/skills/designing-agents/SKILL.md +12 -12
- package/skills/drafting-workflows/SKILL.md +6 -6
- package/skills/drafting-workflows/scripts/make-workflow.ts +3 -3
- package/skills/frontend-ui-engineering/SKILL.md +2 -2
- package/skills/git-workflow-and-versioning/SKILL.md +1 -1
- package/skills/incremental-implementation/SKILL.md +13 -9
- package/skills/peer-coms/SKILL.md +4 -4
- package/skills/performance-optimization/SKILL.md +152 -6
- package/skills/planning-and-task-breakdown/SKILL.md +32 -8
- package/skills/security-and-hardening/SKILL.md +84 -21
- package/skills/spec-driven-development/SKILL.md +41 -2
- package/skills/using-agent-skills/SKILL.md +3 -2
- package/vendor/agent-skills-upstream/README.md +427 -8
- package/vendor/agent-skills-upstream/skills/api-and-interface-design/SKILL.md +73 -0
- package/vendor/agent-skills-upstream/skills/code-review-and-quality/SKILL.md +2 -2
- package/vendor/agent-skills-upstream/skills/constraint-driven-development/SKILL.md +311 -0
- package/vendor/agent-skills-upstream/skills/constraint-driven-development/references/floor-guard.md +99 -0
- package/vendor/agent-skills-upstream/skills/context-engineering/SKILL.md +49 -1
- package/vendor/agent-skills-upstream/skills/debugging-and-error-recovery/SKILL.md +4 -4
- package/vendor/agent-skills-upstream/skills/deprecation-and-migration/SKILL.md +1 -1
- package/vendor/agent-skills-upstream/skills/documentation-and-adrs/SKILL.md +12 -2
- package/vendor/agent-skills-upstream/skills/doubt-driven-development/SKILL.md +3 -3
- package/vendor/agent-skills-upstream/skills/frontend-ui-engineering/SKILL.md +1 -1
- package/vendor/agent-skills-upstream/skills/git-workflow-and-versioning/SKILL.md +1 -1
- package/vendor/agent-skills-upstream/skills/incremental-implementation/SKILL.md +9 -9
- package/vendor/agent-skills-upstream/skills/observability-and-instrumentation/SKILL.md +36 -1
- package/vendor/agent-skills-upstream/skills/performance-optimization/SKILL.md +151 -5
- package/vendor/agent-skills-upstream/skills/planning-and-task-breakdown/SKILL.md +32 -9
- package/vendor/agent-skills-upstream/skills/security-and-hardening/SKILL.md +64 -7
- package/vendor/agent-skills-upstream/skills/shipping-and-launch/SKILL.md +26 -6
- package/vendor/agent-skills-upstream/skills/source-driven-development/SKILL.md +23 -1
- package/vendor/agent-skills-upstream/skills/spec-driven-development/SKILL.md +42 -3
- package/vendor/agent-skills-upstream/skills/test-driven-development/SKILL.md +18 -3
- package/vendor/agent-skills-upstream/skills/using-agent-skills/SKILL.md +3 -2
- package/scripts/lib/hermes-monitor-events.ts +0 -1
- package/scripts/lib/hermes-monitor-herdr.ts +0 -2
- package/scripts/lib/hermes-monitor-registry.ts +0 -2
- package/scripts/lib/hermes-monitor-socket.ts +0 -2
- package/scripts/lib/hermes-monitor-store.ts +0 -2
- /package/{hermes → .pi/agent-fleet/hermes}/desktop-plugins/agent-fleet-herdr/plugin.js +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/desktop-plugins/agent-fleet-herdr/presentation.js +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/desktop-plugins/agent-fleet-monitor/plugin.js +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/desktop-plugins/agent-fleet-monitor/state.js +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/herdr_source.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/manifest.json +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/plugin_api.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/sessions.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/dashboard/tasks.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-herdr/plugin.yaml +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-monitor/dashboard/adapter.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-monitor/dashboard/dist/index.js +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-monitor/dashboard/manifest.json +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/plugins/agent-fleet-monitor/dashboard/plugin_api.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-liaison/SKILL.md +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/manifest.json +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_actions.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_contract.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_delivery.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_engine.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_judgment.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_recovery.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_state.py +0 -0
- /package/{hermes → .pi/agent-fleet/hermes}/skills/hub-watchdog/scripts/watchdog_transport.py +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/fleet-codex-client.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/hermes-watchdog-capability-probe.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/lib/fake-herdr-server.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/lib/fleet-codex-catalog.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/lib/fleet-codex-operations.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/lib/fleet-codex-session.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/lib/fleet-command.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/lib/flow-command.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/lib/flow-maintenance.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/package-lock.json +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/package.json +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/changes.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/debate.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/env.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/gates.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/git.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/merge.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/model-visibility.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/permissions.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/poll.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/quality.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/run.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/voices.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/lib/writer-lease.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/tsconfig.json +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/wf-build-test.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/wf-debate.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/wf-document.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/wf-poll.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/wf-quality.ts +0 -0
- /package/{scripts → .pi/agent-fleet/scripts}/workflows/wf-scout.ts +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: performance-optimization
|
|
3
|
-
description: Optimizes application performance. Use when performance requirements exist, when you suspect performance regressions,
|
|
3
|
+
description: Optimizes application performance across frontend, backend, queries, and databases. Use when performance requirements exist, when you suspect performance regressions, when Core Web Vitals or load times need improvement, when N+1 query patterns need fixing, or when profiling reveals bottlenecks.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Performance Optimization
|
|
@@ -33,7 +33,7 @@ Measure before optimizing. Performance work without measurement is guessing —
|
|
|
33
33
|
1. MEASURE → Establish baseline with real data
|
|
34
34
|
2. IDENTIFY → Find the actual bottleneck (not assumed)
|
|
35
35
|
3. FIX → Address the specific bottleneck
|
|
36
|
-
4. VERIFY → Measure again
|
|
36
|
+
4. VERIFY → Measure again; keep or revert
|
|
37
37
|
5. GUARD → Add monitoring or tests to prevent regression
|
|
38
38
|
```
|
|
39
39
|
|
|
@@ -149,6 +149,58 @@ const tasks = await db.tasks.findMany({
|
|
|
149
149
|
});
|
|
150
150
|
```
|
|
151
151
|
|
|
152
|
+
#### Queries That Ignore Their Index
|
|
153
|
+
|
|
154
|
+
"Add an index" is the guess. The query plan is the measurement:
|
|
155
|
+
|
|
156
|
+
```sql
|
|
157
|
+
EXPLAIN ANALYZE
|
|
158
|
+
SELECT id, title FROM tasks
|
|
159
|
+
WHERE owner_id = 42 ORDER BY created_at DESC LIMIT 20;
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
Three things in the output decide the fix:
|
|
163
|
+
|
|
164
|
+
| What you see | What it means |
|
|
165
|
+
|---|---|
|
|
166
|
+
| `Seq Scan` on a large table where you expected an index | No usable index for this predicate |
|
|
167
|
+
| Estimated `rows=` off from actual by an order of magnitude | Stale statistics; the planner is choosing on bad information |
|
|
168
|
+
| A `Sort` node above the scan | The index covers the filter but not the `ORDER BY` |
|
|
169
|
+
|
|
170
|
+
Index for the **shape of the query**, not the column in isolation. In a composite index, equality columns come first, then the range or sort column:
|
|
171
|
+
|
|
172
|
+
```sql
|
|
173
|
+
CREATE INDEX idx_tasks_owner_created ON tasks (owner_id, created_at DESC);
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
**When an index will not help:**
|
|
177
|
+
|
|
178
|
+
| Situation | Why |
|
|
179
|
+
|---|---|
|
|
180
|
+
| Low selectivity, querying the dominant value (a `status` column that is 95% `active`, filtered on `active`) | A sequential scan is genuinely cheaper; the planner will ignore the index. Filtering on the rare value is the opposite case, and a partial index serves it well |
|
|
181
|
+
| Leading wildcard (`LIKE '%term'`) | A B-tree cannot seek without a prefix; needs trigram or full-text |
|
|
182
|
+
| Function on the column (`WHERE lower(email) = ?`) | The plain column index is unusable; index the expression instead |
|
|
183
|
+
| Write-heavy table | Every index is a tax on every `INSERT`/`UPDATE`; measure the write cost, not just the read gain |
|
|
184
|
+
|
|
185
|
+
Re-run `EXPLAIN ANALYZE` after. An index that did not change the plan is a revert (Step 4), and it is not free: it still costs on every write.
|
|
186
|
+
|
|
187
|
+
#### Connection Pool Exhaustion
|
|
188
|
+
|
|
189
|
+
The signature is distinctive: **every** endpoint slows at once, the slow time is spent waiting for a connection rather than executing, and the database reports mostly idle sessions.
|
|
190
|
+
|
|
191
|
+
```typescript
|
|
192
|
+
// BAD: a pool per request or per module — under serverless this multiplies
|
|
193
|
+
// by instance count and exhausts the database's connection limit
|
|
194
|
+
// GOOD: one pool per process, sized against the database's ceiling
|
|
195
|
+
const pool = new Pool({
|
|
196
|
+
max: 10, // instances × max must stay under max_connections
|
|
197
|
+
idleTimeoutMillis: 30_000,
|
|
198
|
+
connectionTimeoutMillis: 5_000, // fail fast instead of queueing forever
|
|
199
|
+
});
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
**Bigger is not faster.** A pool larger than what the database can execute concurrently just relocates the queue from your app to the database, where it is harder to see. When instance count is unbounded (serverless, autoscaling), a proxy that multiplexes connections (pgbouncer, RDS Proxy) is the fix, not a higher `max`.
|
|
203
|
+
|
|
152
204
|
#### Missing Image Optimization (Frontend)
|
|
153
205
|
|
|
154
206
|
```html
|
|
@@ -264,6 +316,16 @@ function App() {
|
|
|
264
316
|
|
|
265
317
|
#### Missing Caching (Backend)
|
|
266
318
|
|
|
319
|
+
Cache what is expensive to produce and read far more often than it changes. Caching a query that was already fast adds a network hop, a staleness bug, and an eviction policy to maintain, in exchange for nothing.
|
|
320
|
+
|
|
321
|
+
**Pick the layer deliberately:**
|
|
322
|
+
|
|
323
|
+
| Layer | Visible to | Use when | Cost |
|
|
324
|
+
|---|---|---|---|
|
|
325
|
+
| In-process (`Map`, LRU) | One instance | Small, hot, per-instance staleness is acceptable | Each instance drifts independently; invalidation reaches only one |
|
|
326
|
+
| Shared (Redis, Memcached) | All instances | Instances must agree, or the value is expensive to recompute | A network hop, and another service to run and monitor |
|
|
327
|
+
| CDN / edge | Everyone, per URL | Responses are public and identical for a given key | Invalidation is the hard part; assume you cannot recall a bad response quickly |
|
|
328
|
+
|
|
267
329
|
```typescript
|
|
268
330
|
// Cache frequently-read, rarely-changed data
|
|
269
331
|
const CACHE_TTL = 5 * 60 * 1000; // 5 minutes
|
|
@@ -289,9 +351,73 @@ app.use('/static', express.static('public', {
|
|
|
289
351
|
res.set('Cache-Control', 'public, max-age=300'); // 5 minutes
|
|
290
352
|
```
|
|
291
353
|
|
|
292
|
-
|
|
354
|
+
**Key design decides correctness.** Every input that changes the response belongs in the key: tenant, locale, permissions, feature flags. A key that omits the viewer is how one user's data gets served to another, and that ships as a performance win.
|
|
355
|
+
|
|
356
|
+
**Choose one invalidation strategy, not three:**
|
|
357
|
+
|
|
358
|
+
| Strategy | Trade-off |
|
|
359
|
+
|---|---|
|
|
360
|
+
| TTL | Simplest. You accept staleness up to the TTL, so state the acceptable window explicitly |
|
|
361
|
+
| Event or tag based | Fresh on write, but writers now have to know the cache topology |
|
|
362
|
+
| Versioned keys (`user:42:profile:v7`) | Never invalidate, just stop reading old keys. Costs memory until eviction |
|
|
363
|
+
|
|
364
|
+
**Guard against the stampede.** A hot key expires, every concurrent request misses together, and the origin takes the full load at once, which is how a cache turns into an outage instead of preventing one. Serve stale while a single request recomputes (`stale-while-revalidate`), or coalesce concurrent misses behind one in-flight promise so N waiters cause one recompute.
|
|
365
|
+
|
|
366
|
+
**Do not cache:** anything whose staleness is a correctness bug (balances, permissions, inventory at checkout), or per-user data under a key that does not identify the user. See `../../references/performance-checklist.md` for request coalescing, write strategies, negative caching, and the cache checklist.
|
|
367
|
+
|
|
368
|
+
### Step 4: Verify (Keep or Revert)
|
|
369
|
+
|
|
370
|
+
A fix is a hypothesis until you re-measure. This step decides whether it survives.
|
|
371
|
+
|
|
372
|
+
**Re-measure the way you measured the baseline:** same command, same conditions, same fixed budget (wall-clock, sample count, or request count). A baseline taken on a cold cache against a result taken on a warm one measures the cache, not your change.
|
|
373
|
+
|
|
374
|
+
**Change one thing at a time.** Three optimizations landed together produce one number, and you cannot attribute it. If they must ship together, measure each in isolation first.
|
|
375
|
+
|
|
376
|
+
**Beat the noise, not just the mean.** Repeat the measurement and compare the delta against run-to-run variance. A 3% gain inside ±5% variance is not a gain; it is a different sample.
|
|
377
|
+
|
|
378
|
+
Then decide, strictly:
|
|
379
|
+
|
|
380
|
+
| Result vs. baseline | Action |
|
|
381
|
+
|---|---|
|
|
382
|
+
| Past the threshold, tests green | **Keep.** Commit with the before/after numbers in the message. |
|
|
383
|
+
| Within noise (no measurable change) | **Revert.** |
|
|
384
|
+
| Worse | **Revert.** |
|
|
385
|
+
| Improved, but a test went red | **Revert.** A regression wearing a win's clothing. |
|
|
386
|
+
|
|
387
|
+
**"Neutral" is a revert, not a keep.** This is the step teams skip: the change is already written, throwing it away feels wasteful, so it lands unmeasured, and the codebase accretes complexity that never bought anything. Code you keep, you maintain forever. Make it pay for itself.
|
|
388
|
+
|
|
389
|
+
**Correctness gates the metric.** The suite stays green *and* the number moves. An "optimization" that wins by dropping work the product needed (skipping a validation, caching something that must be fresh, removing an `await` that was load-bearing) is a regression, not a win.
|
|
390
|
+
|
|
391
|
+
#### Log every attempt, including the reverted ones
|
|
392
|
+
|
|
393
|
+
Reverted work leaves no trace in git history, which is exactly why the same dead idea gets tried again next quarter. Keep a short ledger so a discarded idea stays discarded:
|
|
394
|
+
|
|
395
|
+
| Idea | Baseline → Result | Verdict | Why |
|
|
396
|
+
|---|---|---|---|
|
|
397
|
+
| Memoize the row component | INP 240ms → 235ms | reverted | Inside noise (±15ms). Rows weren't the bottleneck. |
|
|
398
|
+
| Virtualize the list | INP 240ms → 90ms | kept | Long tasks gone from the trace. |
|
|
399
|
+
| Preconnect to the API origin | LCP 2.8s → 2.8s | reverted | Already same-origin. |
|
|
400
|
+
|
|
401
|
+
A section in the PR description or a `PERF.md` in the repo both work. What matters is that the next person (or the next agent) reads it before proposing an experiment, and doesn't re-run one that already failed.
|
|
402
|
+
|
|
403
|
+
### Step 5: Guard Against Regression
|
|
404
|
+
|
|
405
|
+
Guard the metric the user actually feels, not every available number. Use the
|
|
406
|
+
same LCP, INP, p95 latency, or other primary metric that justified the fix.
|
|
407
|
+
|
|
408
|
+
Use two complementary layers when the surface is user-facing:
|
|
409
|
+
|
|
410
|
+
- **Synthetic CI gate:** Catch reproducible regressions before merge with a
|
|
411
|
+
performance budget. Repeat noisy measurements or compare a median/trend so
|
|
412
|
+
normal run-to-run variance does not turn the gate into a flaky check.
|
|
413
|
+
- **Field monitoring:** Alert on a meaningful p75 movement in RUM data. Use
|
|
414
|
+
attributed `web-vitals` data to locate the cause; treat CrUX's rolling window
|
|
415
|
+
as confirmation rather than an immediate alert.
|
|
416
|
+
|
|
417
|
+
When either guard fires, return to Step 1 and establish a fresh baseline before
|
|
418
|
+
proposing another fix.
|
|
293
419
|
|
|
294
|
-
Set budgets and enforce them
|
|
420
|
+
**Set budgets and enforce them:**
|
|
295
421
|
|
|
296
422
|
```
|
|
297
423
|
JavaScript bundle: < 200KB gzipped (initial load)
|
|
@@ -314,7 +440,7 @@ npx lhci autorun
|
|
|
314
440
|
|
|
315
441
|
## See Also
|
|
316
442
|
|
|
317
|
-
For detailed performance checklists, optimization commands, and anti-pattern reference, see
|
|
443
|
+
For detailed performance checklists, optimization commands, and anti-pattern reference, see `../../references/performance-checklist.md`.
|
|
318
444
|
|
|
319
445
|
|
|
320
446
|
## Common Rationalizations
|
|
@@ -326,25 +452,45 @@ For detailed performance checklists, optimization commands, and anti-pattern ref
|
|
|
326
452
|
| "This optimization is obvious" | If you didn't measure, you don't know. Profile first. |
|
|
327
453
|
| "Users won't notice 100ms" | Research shows 100ms delays impact conversion rates. Users notice more than you think. |
|
|
328
454
|
| "The framework handles performance" | Frameworks prevent some issues but can't fix N+1 queries or oversized bundles. |
|
|
455
|
+
| "The query is slow, add an index" | Read the plan first. The index may already exist and be unusable, and every index taxes writes forever. |
|
|
456
|
+
| "Just cache it" | Caching an already-cheap call buys nothing and adds a staleness bug. Cache what is expensive *and* re-read far more than written. |
|
|
457
|
+
| "Raise the pool size, we're running out of connections" | A pool bigger than the database can serve moves the queue somewhere less visible. Find what holds connections. |
|
|
458
|
+
| "It didn't help much, but it doesn't hurt" | Neutral changes are a revert. You pay maintenance on them forever and got nothing back. |
|
|
459
|
+
| "We already wrote it, may as well keep it" | Sunk cost. The measurement doesn't care how long the change took to write. |
|
|
460
|
+
| "The improvement is obvious, no need to re-measure" | Then re-measuring is cheap and proves it. Unmeasured wins are how neutral complexity lands. |
|
|
329
461
|
|
|
330
462
|
## Red Flags
|
|
331
463
|
|
|
332
464
|
- Optimization without profiling data to justify it
|
|
333
465
|
- N+1 query patterns in data fetching
|
|
466
|
+
- An index added without a query plan before and after to justify it
|
|
467
|
+
- A cache key that omits an input the response depends on (tenant, locale, viewer)
|
|
468
|
+
- A cache with no stated staleness window and no invalidation strategy
|
|
469
|
+
- Connection pool size raised in response to exhaustion, without finding what holds connections
|
|
334
470
|
- List endpoints without pagination
|
|
335
471
|
- Images without dimensions, lazy loading, or responsive sizes
|
|
336
472
|
- Bundle size growing without review
|
|
337
473
|
- No performance monitoring in production
|
|
338
474
|
- `React.memo` and `useMemo` everywhere (overusing is as bad as underusing)
|
|
475
|
+
- Optimizations kept without a re-measurement that justifies them
|
|
476
|
+
- Several optimizations bundled into one measurement, so no single change can be attributed
|
|
477
|
+
- A "win" that required a test to be changed, skipped, or deleted
|
|
478
|
+
- The same failed optimization attempted more than once because nobody recorded the first attempt
|
|
339
479
|
|
|
340
480
|
## Verification
|
|
341
481
|
|
|
342
482
|
After any performance-related change:
|
|
343
483
|
|
|
344
484
|
- [ ] Before and after measurements exist (specific numbers)
|
|
485
|
+
- [ ] The result was re-measured the same way as the baseline (same command, same conditions)
|
|
486
|
+
- [ ] The improvement exceeds run-to-run variance, not just the mean
|
|
487
|
+
- [ ] Changes that didn't beat the baseline were reverted, not kept as neutral
|
|
488
|
+
- [ ] Attempts are logged, kept and reverted alike, so a dead idea isn't re-run
|
|
345
489
|
- [ ] The specific bottleneck is identified and addressed
|
|
346
490
|
- [ ] Core Web Vitals are within "Good" thresholds
|
|
347
491
|
- [ ] Bundle size hasn't increased significantly
|
|
348
492
|
- [ ] No N+1 queries in new data fetching code
|
|
349
|
-
- [ ]
|
|
493
|
+
- [ ] Any new index is justified by a query plan before and after, and its write cost was considered
|
|
494
|
+
- [ ] Any new cache states what it keys on and how it goes stale
|
|
495
|
+
- [ ] The measured user-facing metric has a synthetic budget or field monitor that can detect regression
|
|
350
496
|
- [ ] Existing tests still pass (optimization didn't break behavior)
|
|
@@ -51,7 +51,24 @@ The task list is **embedded** in the plan file as the `## Task List` section. Do
|
|
|
51
51
|
|
|
52
52
|
Match the project's existing `docs` vs `Docs` capitalization, and create the directory if it does not exist.
|
|
53
53
|
|
|
54
|
-
**Project overrides:** if `.ai/agent-fleet-overrides.md` has a `## planning-and-task-breakdown` section, its keys (`plan-dir`, `naming`, `todo`) override these defaults — `todo: separate` restores a standalone `todo.md
|
|
54
|
+
**Project overrides:** if `.ai/agent-fleet-overrides.md` has a `## planning-and-task-breakdown` section, its keys (`plan-dir`, `naming`, `todo`) override these defaults — `todo: separate` restores a standalone `todo.md`, and `todo: tracker` routes tasks to an external issue tracker (below). See [docs/agent-fleet-setup.md](../../docs/agent-fleet-setup.md).
|
|
55
|
+
|
|
56
|
+
### Task List Target
|
|
57
|
+
|
|
58
|
+
The **task list target** is where tasks and checkpoints are recorded. It is defined once, here; every other reference in this skill defers to it.
|
|
59
|
+
|
|
60
|
+
- **Default (`todo: embedded`)** — the `## Task List` section of the plan file itself. No separate file.
|
|
61
|
+
- **`todo: separate`** — a standalone checklist-style `todo.md` next to the plan.
|
|
62
|
+
- **`todo: tracker`** — one item per task in the designated issue tracker (GitHub Issues, Jira, Linear, `bd`/beads). Map the Step 4 structure onto the tracker's fields: acceptance criteria and verification steps in the item body, dependencies via the tracker's linking mechanism (`bd dep add`, "blocked by", etc.). Record Step 5 checkpoints as tracker items too, or keep them as a checklist in the plan document if the tracker has no natural equivalent.
|
|
63
|
+
|
|
64
|
+
With a tracker, name it in the plan (e.g. "Tasks tracked in Linear project FOO") so downstream steps and future sessions know where to look, and keep the plan's `## Task List` section as an ordered index of tracker item IDs or links rather than a duplicate checklist.
|
|
65
|
+
|
|
66
|
+
**Never overwrite an incomplete plan.** Before writing the resolved plan path, check whether it already exists and still contains unchecked tasks:
|
|
67
|
+
|
|
68
|
+
- Same work being replanned (the user asked to revise or extend this plan) → update the existing file in place.
|
|
69
|
+
- Different work → **stop and ask.** The unchecked tasks may be mid-build in another session or another flow worktree. Do not delete, overwrite, or rename the existing plan on your own; present the conflict and let the user decide (finish the old plan first, explicitly discard it, or say where the new plan should go).
|
|
70
|
+
|
|
71
|
+
The same rule applies to a tracker target: never bulk-close or delete another plan's open items to make room for new ones.
|
|
55
72
|
|
|
56
73
|
## The Planning Process
|
|
57
74
|
|
|
@@ -64,11 +81,11 @@ Before writing any code, operate in read-only mode:
|
|
|
64
81
|
- Map dependencies between components
|
|
65
82
|
- Note risks and unknowns
|
|
66
83
|
|
|
67
|
-
**Do NOT write code during planning.** The output is a plan document, not implementation.
|
|
84
|
+
**Do NOT write code during planning.** The output is a plan document and a task list recorded in the task list target (see Output Location), not implementation.
|
|
68
85
|
|
|
69
86
|
**Grilling (required before writing tasks):** Read the shared internal helper at [`../_internal/grilling.md`](../_internal/grilling.md). Inventory load-bearing decisions. Skip anything already explicit in chat, prompt, PRD, spec, or rules. Grill every remaining fork (multiple valid ways, contradiction, competing code patterns) one question at a time, with a recommended option. Do not write tasks while a load-bearing choice is still silently assumed. Update Architecture Decisions, Risks, and Open Questions with accepted, rejected, or deferred choices. If nothing is open, note that grilling found no unspecified forks and continue.
|
|
70
87
|
|
|
71
|
-
**Model poll (planner, when `delegate` is available):** On an unresolved architectural fork at task tier `feature` or `project`, run `voice-1`, `voice-2`, and `voice-3` **after** recon (`scout`/`rules`), never in the same message, with a character-for-character identical instruction. Do not poll on `trivial`/`small` (delegation is off) and do not invent a poll if `delegate` is missing. Agreement becomes an accepted architectural decision in the plan, naming the voices; write a `POLL-{prd-name}.md` digest next to the plan and cite it. Divergence becomes one `ASK_USER:` question with one option per position plus a recommendation and reason — do not write the plan in that same turn. The optional communication contract at [
|
|
88
|
+
**Model poll (planner, when `delegate` is available):** On an unresolved architectural fork at task tier `feature` or `project`, run `voice-1`, `voice-2`, and `voice-3` **after** recon (`scout`/`rules`), never in the same message, with a character-for-character identical instruction. Do not poll on `trivial`/`small` (delegation is off) and do not invent a poll if `delegate` is missing. Agreement becomes an accepted architectural decision in the plan, naming the voices; write a `POLL-{prd-name}.md` digest next to the plan and cite it. Divergence becomes one `ASK_USER:` question with one option per position plus a recommendation and reason — do not write the plan in that same turn. The optional communication contract at [`../../references/communication-contract.md`](../../references/communication-contract.md) is not loaded automatically; enable it with `append-prompt: references/communication-contract.md` in `## agent-hub`.
|
|
72
89
|
|
|
73
90
|
### Step 2: Identify the Dependency Graph
|
|
74
91
|
|
|
@@ -116,7 +133,7 @@ Each vertical slice delivers working, testable functionality.
|
|
|
116
133
|
|
|
117
134
|
### Step 4: Write Tasks
|
|
118
135
|
|
|
119
|
-
Each task follows this structure:
|
|
136
|
+
Each task follows this structure, whether it lands in the plan's `## Task List`, a standalone `todo.md`, or an external tracker item (see Output Location):
|
|
120
137
|
|
|
121
138
|
```markdown
|
|
122
139
|
## Task [N]: [Short descriptive title]
|
|
@@ -128,8 +145,8 @@ Each task follows this structure:
|
|
|
128
145
|
- [ ] [Specific, testable condition]
|
|
129
146
|
|
|
130
147
|
**Verification:**
|
|
131
|
-
- [ ] Tests pass: `
|
|
132
|
-
- [ ] Build succeeds:
|
|
148
|
+
- [ ] Tests pass: [the project's `quality:` command, or the repository's focused-test command]
|
|
149
|
+
- [ ] Build succeeds: [the repository's build command]
|
|
133
150
|
- [ ] Manual check: [description of what to verify]
|
|
134
151
|
|
|
135
152
|
**Dependencies:** [Task numbers this depends on, or "None"]
|
|
@@ -148,7 +165,7 @@ Arrange tasks so that:
|
|
|
148
165
|
3. Verification checkpoints occur after every 2-3 tasks
|
|
149
166
|
4. High-risk tasks are early (fail fast)
|
|
150
167
|
|
|
151
|
-
Add explicit checkpoints:
|
|
168
|
+
Add explicit checkpoints to the task list target:
|
|
152
169
|
|
|
153
170
|
```markdown
|
|
154
171
|
## Checkpoint: After Tasks 1-3
|
|
@@ -213,6 +230,8 @@ If a task is 5-8 files (Multi-component feature , such as Search with filtering
|
|
|
213
230
|
- [Question needing human input]
|
|
214
231
|
```
|
|
215
232
|
|
|
233
|
+
When tasks live in an external tracker, keep the Task List section above as an ordered index of tracker item IDs or links instead of a duplicate checklist.
|
|
234
|
+
|
|
216
235
|
## Parallelization Opportunities
|
|
217
236
|
|
|
218
237
|
When multiple agents or sessions are available:
|
|
@@ -229,6 +248,7 @@ When multiple agents or sessions are available:
|
|
|
229
248
|
| "The tasks are obvious" | Write them down anyway. Explicit tasks surface hidden dependencies and forgotten edge cases. |
|
|
230
249
|
| "Planning is overhead" | Planning is the task. Implementation without a plan is just typing. |
|
|
231
250
|
| "I can hold it all in my head" | Context windows are finite. Written plans survive session boundaries and compaction. |
|
|
251
|
+
| "The old plan is stale, I'll just replace it" | Unchecked tasks may be mid-build in another session or flow worktree. Overwriting them destroys work state that exists nowhere else. Stop and ask. |
|
|
232
252
|
| "The PRD already covers everything, no need to grill" | Then grilling produces zero questions. Still run the inventory so silent forks do not slip through. |
|
|
233
253
|
| "I'll pick the obvious variant and note it in Architecture Decisions" | If more than one variant exists and none was mandated, it is not obvious to the programmer who was not in the room. Ask, then record the choice. |
|
|
234
254
|
| "Re-confirming the PRD points shows thoroughness" | Re-asking settled requirements wastes the user and implies the agent did not read them. Skip them. |
|
|
@@ -236,6 +256,8 @@ When multiple agents or sessions are available:
|
|
|
236
256
|
## Red Flags
|
|
237
257
|
|
|
238
258
|
- Starting implementation without a written task list
|
|
259
|
+
- Overwriting a plan that still has unchecked tasks for different work, without asking
|
|
260
|
+
- Writing a `todo.md` when the project has designated an external tracker (or scattering tasks across both)
|
|
239
261
|
- Tasks that say "implement the feature" without acceptance criteria
|
|
240
262
|
- No verification steps in the plan
|
|
241
263
|
- All tasks touches more than 8+ files
|
|
@@ -252,6 +274,8 @@ Before starting implementation, confirm:
|
|
|
252
274
|
- [ ] Every task has acceptance criteria
|
|
253
275
|
- [ ] Every task has a verification step
|
|
254
276
|
- [ ] Task dependencies are identified and ordered correctly
|
|
277
|
+
- [ ] Tasks are recorded in the task list target resolved from `todo` (default: the plan's `## Task List`)
|
|
278
|
+
- [ ] No pre-existing incomplete plan was overwritten without explicit user confirmation
|
|
255
279
|
- [ ] No task touches more than ~5 files
|
|
256
280
|
- [ ] Checkpoints exist between major phases
|
|
257
281
|
- [ ] The human has reviewed and approved the plan
|
|
@@ -262,4 +286,4 @@ Before starting implementation, confirm:
|
|
|
262
286
|
|
|
263
287
|
## See Also
|
|
264
288
|
|
|
265
|
-
Acceptance criteria are per-task and answer "did we build the right thing?". They sit on top of the project-wide Definition of Done, the standing bar every task clears before it counts as done. See
|
|
289
|
+
Acceptance criteria are per-task and answer "did we build the right thing?". They sit on top of the project-wide Definition of Done, the standing bar every task clears before it counts as done. See `../../references/definition-of-done.md`.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: security-and-hardening
|
|
3
|
-
description: Hardens code against vulnerabilities. Use when handling user input, authentication, data storage, or external integrations. Use when building any feature that accepts untrusted data, manages user sessions, or interacts with third-party services.
|
|
3
|
+
description: Hardens code against vulnerabilities. Use when auditing an input handler for vulnerabilities, when handling user input, authentication, data storage, or external integrations, or when checking a login flow is safe against the OWASP Top Ten. Use when building any feature that accepts untrusted data, manages user sessions, or interacts with third-party services. Use when auditing dependencies for known vulnerabilities, triaging package-manager audit findings, or assessing supply-chain risk in a new package. Use when personal data or privacy compliance (GDPR, CCPA) is involved.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Security and Hardening
|
|
@@ -22,7 +22,7 @@ Security-first development practices for web applications. Treat every external
|
|
|
22
22
|
|
|
23
23
|
Controls bolted on without a threat model are guesses. Before hardening, spend five minutes thinking like an attacker:
|
|
24
24
|
|
|
25
|
-
1. **Map the trust boundaries.** Where does untrusted data cross into your system? HTTP requests, form fields, file uploads, webhooks, third-party APIs, message queues, and **LLM output
|
|
25
|
+
1. **Map the trust boundaries.** Where does untrusted data cross into your system? HTTP requests, form fields, file uploads, webhooks, third-party APIs, message queues, and **LLM output** — plus the local values that look internal because the OS handed them to you: another process's command line or environment, filenames on a shared volume, a path in a job payload. Trust follows who *wrote* a value, not which channel delivered it. Every boundary is attack surface.
|
|
26
26
|
2. **Name the assets.** What's worth stealing or breaking? Credentials, PII, payment data, admin actions, money movement.
|
|
27
27
|
3. **Run STRIDE over each boundary** — a quick lens, not a ceremony:
|
|
28
28
|
|
|
@@ -50,7 +50,7 @@ If you can't name the trust boundaries for a feature, you're not ready to secure
|
|
|
50
50
|
- **Hash passwords** with bcrypt/scrypt/argon2 (never store plaintext)
|
|
51
51
|
- **Set security headers** (CSP, HSTS, X-Frame-Options, X-Content-Type-Options)
|
|
52
52
|
- **Use httpOnly, secure, sameSite cookies** for sessions
|
|
53
|
-
- **Run
|
|
53
|
+
- **Run the detected package manager's native audit** against the committed lockfile before every release
|
|
54
54
|
|
|
55
55
|
### Ask First (Requires Human Approval)
|
|
56
56
|
|
|
@@ -74,7 +74,7 @@ If you can't name the trust boundaries for a feature, you're not ready to secure
|
|
|
74
74
|
|
|
75
75
|
## OWASP Top 10 Prevention Patterns
|
|
76
76
|
|
|
77
|
-
These are prevention patterns, not a ranking. For the 2021 ordering, see the quick-reference table in
|
|
77
|
+
These are prevention patterns, not a ranking. For the 2021 ordering, see the quick-reference table in `../../references/security-checklist.md`.
|
|
78
78
|
|
|
79
79
|
### Injection (SQL, NoSQL, OS Command)
|
|
80
80
|
|
|
@@ -269,16 +269,24 @@ function validateUpload(file: UploadedFile) {
|
|
|
269
269
|
}
|
|
270
270
|
```
|
|
271
271
|
|
|
272
|
-
|
|
272
|
+
### Destructive Operations on Derived Paths
|
|
273
273
|
|
|
274
|
-
|
|
274
|
+
A delete, move, or overwrite is only as safe as the value that names its target. Reading that value from the kernel, a job payload, or a sibling service proves where it *arrived from*, not who *wrote* it — another process's command line is as attacker-controlled as a form field. A shape check ("absolute path, at least one directory deep") proves well-formedness and gets mistaken for authorization; that is how a cleanup routine deletes the root instead of the leaf.
|
|
275
|
+
|
|
276
|
+
Before a destructive call, require all three: the resolved target sits under an **allowlisted root** (compare after resolving symlinks, never on the raw string); it is at least one level **below** that root, so a root is never itself the target; and it carries **evidence that it is yours**, read *before* the operation and before any teardown that removes it — otherwise "absent" and "not mine" are indistinguishable. On refusal, log the rejected target and stop: a cleanup that falls back to a broader default path is the failure this guards against. Worked example in `../../references/security-checklist.md`.
|
|
277
|
+
|
|
278
|
+
Two limits, because the check reads stronger than it is. A marker inside the tree is self-attestation — anything that can write there can write the marker — so the expected owner has to come from authenticated state, and the marker needs integrity protection (restrictive ownership, or a MAC) before it counts as authorization. And resolving a path and then operating on the *name* is a check/use race wherever an untrusted process can swap an ancestor: on a shared volume, hold the target by descriptor and use no-follow, beneath-the-root operations, or make sure the hierarchy cannot change for the duration.
|
|
279
|
+
|
|
280
|
+
## Triaging Dependency Audit Results
|
|
281
|
+
|
|
282
|
+
Package-manager audits report known advisories; they do not prove a package is trustworthy or that vulnerable code is reachable. Use this decision tree:
|
|
275
283
|
|
|
276
284
|
```
|
|
277
|
-
|
|
285
|
+
The native package-manager audit reports a vulnerability
|
|
278
286
|
├── Severity: critical or high
|
|
279
|
-
│ ├── Is the vulnerable code reachable in
|
|
287
|
+
│ ├── Is the vulnerable code reachable in runtime, build, test, or deployment paths?
|
|
280
288
|
│ │ ├── YES --> Fix immediately (update, patch, or replace the dependency)
|
|
281
|
-
│ │ └── NO (
|
|
289
|
+
│ │ └── NO (confirmed unused across those paths) --> Fix soon, but not a blocker
|
|
282
290
|
│ └── Is a fix available?
|
|
283
291
|
│ ├── YES --> Update to the patched version
|
|
284
292
|
│ └── NO --> Check for workarounds, consider replacing the dependency, or add to allowlist with a review date
|
|
@@ -298,12 +306,16 @@ When you defer a fix, document the reason and set a review date.
|
|
|
298
306
|
|
|
299
307
|
### Supply-Chain Hygiene
|
|
300
308
|
|
|
301
|
-
|
|
309
|
+
Do not assume npm or treat the nearest manifest as the install root. Apply this order:
|
|
310
|
+
|
|
311
|
+
1. **Find the installation boundary and manager.** Use the workspace root that owns the lockfile, or an independent nested project only when it is outside that workspace. There, corroborate `packageManager` (when present), the lockfile, and CI; stop on disagreement or competing lockfiles. Pin the manager version and use the matrix in `../../references/security-checklist.md`.
|
|
312
|
+
2. **Block dependency scripts before first execution.** Bootstrap with scripts disabled or a documented fail-closed policy, inspect the pending script source, approve only the minimum required packages, commit the policy, then verify with a clean frozen/immutable install. Never blanket-approve scripts.
|
|
302
313
|
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
- **
|
|
306
|
-
- **
|
|
314
|
+
Audits only find known advisories; they do not catch a newly malicious or typosquatted package. Therefore:
|
|
315
|
+
|
|
316
|
+
- **Never apply forced audit remediation automatically** (`npm audit fix --force` or equivalent). Preview the remediation, read changelogs, and test each resulting upgrade; forced fixes may cross declared dependency ranges.
|
|
317
|
+
- **Verify registry signatures and provenance where supported** (`npm audit signatures`, `pnpm audit signatures`) and treat absence as a signal to investigate, not automatic proof of compromise.
|
|
318
|
+
- **Review new dependencies, lockfile diffs, and script-policy changes together** — ownership, maintenance, release age, provenance, transitive graph, and typosquats such as `cross-env` vs `crossenv` (OWASP **A06**, **LLM03**).
|
|
307
319
|
|
|
308
320
|
## Rate Limiting
|
|
309
321
|
|
|
@@ -325,6 +337,20 @@ app.use('/api/auth/', rateLimit({
|
|
|
325
337
|
}));
|
|
326
338
|
```
|
|
327
339
|
|
|
340
|
+
**Count in a shared store once there is more than one process.** `express-rate-limit` keeps its counters in process memory by default. Behind a load balancer each instance holds its own count, so the effective limit is `max × instances`; on serverless or edge runtimes a fresh invocation starts from zero, so the auth limit above may never fire. Pass a shared `store` (Redis via `rate-limit-redis`), or use an HTTP-based limiter that works where a long-lived TCP connection does not (for example `@upstash/ratelimit`):
|
|
341
|
+
|
|
342
|
+
```typescript
|
|
343
|
+
import { Ratelimit } from '@upstash/ratelimit';
|
|
344
|
+
import { Redis } from '@upstash/redis';
|
|
345
|
+
|
|
346
|
+
const authLimiter = new Ratelimit({
|
|
347
|
+
redis: Redis.fromEnv(), // UPSTASH_REDIS_REST_URL + _TOKEN
|
|
348
|
+
limiter: Ratelimit.slidingWindow(10, '15 m'), // 10 attempts per 15 minutes, across all instances
|
|
349
|
+
});
|
|
350
|
+
const { success } = await authLimiter.limit(`login:${req.ip}`);
|
|
351
|
+
if (!success) return res.status(429).end();
|
|
352
|
+
```
|
|
353
|
+
|
|
328
354
|
## Secrets Management
|
|
329
355
|
|
|
330
356
|
```
|
|
@@ -349,6 +375,27 @@ git diff --cached | grep -i "password\|secret\|api_key\|token"
|
|
|
349
375
|
|
|
350
376
|
**If a secret is ever committed, rotate it.** Deleting the line or rewriting history is not enough — assume it's compromised the moment it reaches a remote. Revoke and reissue the key first, then purge it from history.
|
|
351
377
|
|
|
378
|
+
## Data Privacy & Compliance
|
|
379
|
+
|
|
380
|
+
Securing data is "can an attacker read it?" Privacy is "should *we* even hold it, and for how long?" — a separate question that hardening doesn't answer. The cheapest data to protect, breach, and comply over is the data you never collected. Treat personal data as a liability to minimize, not an asset to hoard.
|
|
381
|
+
|
|
382
|
+
**Know what you hold.** You can't protect or honor a deletion request for data you can't find. Classify fields as you add them:
|
|
383
|
+
|
|
384
|
+
| Class | Examples | Handling |
|
|
385
|
+
|---|---|---|
|
|
386
|
+
| **Non-personal** | Aggregates, anonymized counts | Normal handling |
|
|
387
|
+
| **Personal (PII)** | Name, email, IP, device/user IDs | Minimize, access-control, include in export/delete |
|
|
388
|
+
| **Sensitive** | Health, finance, location, biometrics, gov IDs, anything about minors | Extra basis to collect, stricter access, often encryption + audit logging |
|
|
389
|
+
|
|
390
|
+
**Operating rules:**
|
|
391
|
+
- **Minimize and set a purpose.** Collect a field only against a stated use. "It might be useful later" is not a purpose — it's latent breach scope. Don't log PII into telemetry (the `observability-and-instrumentation` skill makes the same point from the ops side).
|
|
392
|
+
- **Set retention up front, then actually delete.** Every personal-data store needs a TTL and a working deletion path — including backups, caches, search indexes, and analytics copies. Data with no expiry is a breach scheduled for later.
|
|
393
|
+
- **Support the data-subject rights your jurisdiction requires** (GDPR/CCPA and kin): export, correct, and delete on request. These are engineering features — design the schema so a user's data is *findable* and *erasable*, not smeared irreversibly across systems.
|
|
394
|
+
- **Get consent before collection or third-party sharing**, and make it auditable. Sending PII to an analytics/ad/LLM vendor is "sharing" — the user's choice gates it, and the vendor needs a data-processing agreement.
|
|
395
|
+
- **Localize defaults, don't hardcode one region's law.** Data-residency and rules differ by user location; make the policy a configurable boundary, not an assumption.
|
|
396
|
+
|
|
397
|
+
When data crosses a trust boundary, validate it as untrusted (see Input Validation above); when a privacy incident exposes personal data, the breach-notification clock is part of the postmortem — follow the `debugging-and-error-recovery` skill.
|
|
398
|
+
|
|
352
399
|
## Securing AI / LLM Features
|
|
353
400
|
|
|
354
401
|
If your app calls an LLM — chatbots, summarizers, agents, RAG — it inherits a new attack surface. Map it to the [OWASP Top 10 for LLM Applications (2025)](https://genai.owasp.org/llm-top-10/):
|
|
@@ -396,11 +443,15 @@ container.textContent = await llm.reply(userMessage);
|
|
|
396
443
|
- [ ] SQL queries are parameterized
|
|
397
444
|
- [ ] HTML output is encoded/escaped
|
|
398
445
|
- [ ] Server-side URL fetches are allowlisted (no SSRF to internal services)
|
|
446
|
+
- [ ] Delete/move/overwrite targets built from data are checked against an allowlisted root, a minimum depth, and ownership evidence read before the operation
|
|
399
447
|
|
|
400
448
|
### Data
|
|
401
449
|
- [ ] No secrets in code or version control
|
|
402
450
|
- [ ] Sensitive fields excluded from API responses
|
|
403
451
|
- [ ] PII encrypted at rest (if applicable)
|
|
452
|
+
- [ ] Personal data is classified, collected against a stated purpose, and minimized
|
|
453
|
+
- [ ] Personal data has a retention limit and a working deletion path (incl. backups/indexes)
|
|
454
|
+
- [ ] Export/delete (data-subject) requests are supported where required; sharing with third parties has consent
|
|
404
455
|
|
|
405
456
|
### Infrastructure
|
|
406
457
|
- [ ] Security headers configured (CSP, HSTS, etc.)
|
|
@@ -409,8 +460,9 @@ container.textContent = await llm.reply(userMessage);
|
|
|
409
460
|
- [ ] Error messages don't expose internals
|
|
410
461
|
|
|
411
462
|
### Supply Chain
|
|
412
|
-
- [ ]
|
|
413
|
-
- [ ]
|
|
463
|
+
- [ ] One authoritative lockfile committed; CI uses that manager's frozen/immutable install
|
|
464
|
+
- [ ] Native audit triaged by reachability and fix risk; dependency install scripts blocked unless explicitly approved
|
|
465
|
+
- [ ] New dependencies reviewed (ownership, provenance, release age, transitive graph)
|
|
414
466
|
|
|
415
467
|
### AI / LLM (if used)
|
|
416
468
|
- [ ] Model output treated as untrusted (no eval/SQL/innerHTML/shell)
|
|
@@ -419,7 +471,7 @@ container.textContent = await llm.reply(userMessage);
|
|
|
419
471
|
```
|
|
420
472
|
## See Also
|
|
421
473
|
|
|
422
|
-
For detailed security checklists and pre-commit verification steps, see
|
|
474
|
+
For detailed security checklists and pre-commit verification steps, see `../../references/security-checklist.md`.
|
|
423
475
|
|
|
424
476
|
## Common Rationalizations
|
|
425
477
|
|
|
@@ -432,30 +484,41 @@ For detailed security checklists and pre-commit verification steps, see `referen
|
|
|
432
484
|
| "It's just a prototype" | Prototypes become production. Security habits from day one. |
|
|
433
485
|
| "Threat modeling is overkill here" | Five minutes of "how would I attack this?" prevents the design flaws no control can patch later. |
|
|
434
486
|
| "It's just LLM output, it's only text" | That "text" can be a SQL statement, a script tag, or a shell command. Treat it like any untrusted input. |
|
|
487
|
+
| "The audit passed, so the dependency is safe" | Audits match known advisories. They do not detect a newly malicious package or make unreviewed install scripts safe to execute. |
|
|
488
|
+
| "Collect it now, we might need it later" | Data you don't hold can't be breached, subpoenaed, or mis-deleted. "Might need it" is breach scope, not a purpose. |
|
|
489
|
+
| "We'll handle deletion requests manually" | Manual erasure misses backups, caches, and analytics copies. If the schema can't find a user's data, you can't honor the request — design for it. |
|
|
490
|
+
| "Compliance is legal's problem, not ours" | Export, deletion, retention, and consent are schema and code. Legal can't bolt them on after you've smeared PII across ten systems. |
|
|
435
491
|
|
|
436
492
|
## Red Flags
|
|
437
493
|
|
|
438
494
|
- User input passed directly to database queries, shell commands, or HTML rendering
|
|
495
|
+
- A delete, move, or overwrite whose target comes from a payload, a config value, or another process's command line, guarded only by a shape check on the path
|
|
439
496
|
- Secrets in source code or commit history
|
|
440
497
|
- API endpoints without authentication or authorization checks
|
|
441
498
|
- Missing CORS configuration or wildcard (`*`) origins
|
|
442
|
-
- No rate limiting on authentication endpoints
|
|
499
|
+
- No rate limiting on authentication endpoints, or an in-memory limiter in front of more than one instance
|
|
443
500
|
- Stack traces or internal errors exposed to users
|
|
444
|
-
- Dependencies with known critical vulnerabilities
|
|
501
|
+
- Dependencies with known critical vulnerabilities, competing lockfiles at one installation boundary, non-reproducible installs, or blanket-approved scripts
|
|
445
502
|
- Server fetches user-supplied URLs without an allowlist (SSRF)
|
|
446
503
|
- LLM/model output passed into a query, the DOM, a shell, or `eval`
|
|
447
504
|
- Secrets, PII, or the full system prompt placed inside an LLM context window
|
|
505
|
+
- Personal data collected with no stated purpose, retention limit, or deletion path
|
|
506
|
+
- PII sent to analytics/ad/LLM vendors with no consent or data-processing agreement
|
|
507
|
+
- "Delete my account" that only flips a flag while the personal data lingers in stores and backups
|
|
448
508
|
|
|
449
509
|
## Verification
|
|
450
510
|
|
|
451
511
|
After implementing security-relevant code:
|
|
452
512
|
|
|
453
|
-
- [ ]
|
|
513
|
+
- [ ] The native audit has no unmitigated reachable critical/high findings; CI preserves the authoritative lockfile and blocks unreviewed dependency scripts
|
|
454
514
|
- [ ] No secrets in source code or git history
|
|
455
515
|
- [ ] All user input validated at system boundaries
|
|
516
|
+
- [ ] Destructive filesystem operations resolve symlinks, then verify allowlisted root, minimum depth, and ownership before running
|
|
456
517
|
- [ ] Authentication and authorization checked on every protected endpoint
|
|
457
518
|
- [ ] Security headers present in response (check with browser DevTools)
|
|
458
519
|
- [ ] Error responses don't expose internal details
|
|
459
|
-
- [ ] Rate limiting active on auth endpoints
|
|
520
|
+
- [ ] Rate limiting active on auth endpoints, backed by a shared store when more than one instance serves traffic
|
|
460
521
|
- [ ] Server-side URL fetches validated against an allowlist (no SSRF)
|
|
461
522
|
- [ ] LLM/model output validated and encoded before use (if AI features present)
|
|
523
|
+
- [ ] Personal data is classified, minimized to a stated purpose, and has a retention limit
|
|
524
|
+
- [ ] Deletion and export requests work end-to-end (including backups, caches, and analytics copies)
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spec-driven-development
|
|
3
|
-
description: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, only exist as a vague idea, or need to be grilled before planning.
|
|
3
|
+
description: Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when drafting a PRD or requirements document with objectives and scope, or when requirements are unclear, ambiguous, only exist as a vague idea, or need to be grilled before planning. Use when a single requirement spans several independently testable capabilities and needs decomposing into a capability map of modules before specifying.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Spec-Driven Development
|
|
@@ -46,7 +46,7 @@ Match the project's existing `docs` vs `Docs` capitalization, and create the dir
|
|
|
46
46
|
|
|
47
47
|
## The Gated Workflow
|
|
48
48
|
|
|
49
|
-
Spec-driven development has four phases. Do not advance to the next phase until the current one is validated.
|
|
49
|
+
Spec-driven development has four phases, preceded by a scope check (Phase 0) that activates only when one request bundles several independently testable capabilities. Do not advance to the next phase until the current one is validated.
|
|
50
50
|
|
|
51
51
|
```
|
|
52
52
|
SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
|
|
@@ -56,6 +56,39 @@ SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
|
|
|
56
56
|
reviews reviews reviews reviews
|
|
57
57
|
```
|
|
58
58
|
|
|
59
|
+
### Phase 0: Scope Check
|
|
60
|
+
|
|
61
|
+
Most requests describe one capability. If this one does, skip this phase and go straight to Specify — Phase 0 exists for the exception, not the rule, and it puts no hierarchy on single-capability features.
|
|
62
|
+
|
|
63
|
+
**Detection.** Decompose before specifying when a single requirement bundles several independently testable capabilities:
|
|
64
|
+
|
|
65
|
+
- The requirement names distinct capabilities with their own consumers or data (e.g. identity, billing, notifications, reporting)
|
|
66
|
+
- Acceptance criteria cluster into groups that could ship and be verified separately
|
|
67
|
+
- One capability could be cut or replaced without rewriting the others' requirements
|
|
68
|
+
|
|
69
|
+
**Propose a capability map before writing any spec.** Small and reviewable — a module table plus a build order, not a project plan:
|
|
70
|
+
|
|
71
|
+
```markdown
|
|
72
|
+
# Capability Map: [Initiative Name]
|
|
73
|
+
|
|
74
|
+
| Module id | Responsibility | Depends on |
|
|
75
|
+
|---|---|---|
|
|
76
|
+
| identity | Accounts, sessions, SSO | — |
|
|
77
|
+
| billing | Plans, invoices, payments | identity |
|
|
78
|
+
| notifications | Email and webhook fan-out | identity |
|
|
79
|
+
| reporting | Usage dashboards | billing, notifications |
|
|
80
|
+
|
|
81
|
+
Build order: identity → billing, notifications → reporting
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
- **Stable module ids.** Kebab-case, chosen once, never renamed mid-initiative. Specs, plans, and downstream commands select work by these ids instead of guessing which spec is active.
|
|
85
|
+
- **Dependency direction, no cycles.** Arrows point one way. If two modules each need the other, they are one module.
|
|
86
|
+
- **Interfaces live at the boundary.** The map records that `billing` depends on `identity`; the contract between them belongs in the provider module's spec (see `api-and-interface-design` for designing it).
|
|
87
|
+
|
|
88
|
+
**The map is gated like every phase.** The human reviews module boundaries, dependency direction, and build order before any module spec is written. Getting the map wrong is expensive; reviewing ten lines is not.
|
|
89
|
+
|
|
90
|
+
**Then recurse per module.** Run Specify → Plan → Tasks → Implement for each module in dependency order. Each module gets its own spec, scoped to that module's objective, boundaries, and success criteria. Save the approved map in the same spec directory the Output Convention above resolves to (default `docs/prds/{area}/`), as `CAPABILITY-MAP-{topic}.md`, and give each module its own PRD under the project's normal naming with the module id as the `{topic}` slug. The map, not filename guessing, is the index of what exists.
|
|
91
|
+
|
|
59
92
|
### Phase 1: Specify
|
|
60
93
|
|
|
61
94
|
**Gather context first.** Before writing any spec content, identify and read the sources the spec will build on:
|
|
@@ -231,6 +264,8 @@ The spec is a living document, not a one-time artifact:
|
|
|
231
264
|
| "The spec will slow us down" | A 15-minute spec prevents hours of rework. Waterfall in 15 minutes beats debugging in 15 hours. |
|
|
232
265
|
| "Requirements will change anyway" | That's why the spec is a living document. An outdated spec is still better than no spec. |
|
|
233
266
|
| "The user knows what they want" | Even clear requests have implicit assumptions. The spec surfaces those assumptions. |
|
|
267
|
+
| "It's one big feature; splitting it is overhead" | If acceptance criteria cluster into independently testable groups, a monolithic spec forces every downstream task to reason over the whole contract. A ten-line capability map is the cheap alternative. |
|
|
268
|
+
| "I'll decompose during planning" | Planning slices tasks within a spec. By then the oversized artifact already exists — module boundaries and dependency direction must be decided before the spec is written, not after. |
|
|
234
269
|
|
|
235
270
|
## Red Flags
|
|
236
271
|
|
|
@@ -241,6 +276,8 @@ The spec is a living document, not a one-time artifact:
|
|
|
241
276
|
- Skipping the spec because "it's obvious what to build"
|
|
242
277
|
- Re-asking a requirement already explicit in chat, prompt, or rules
|
|
243
278
|
- Locking a spec that silently picks among several valid approaches
|
|
279
|
+
- One spec whose requirements span several independently testable capabilities
|
|
280
|
+
- Module boundaries or build order decided implicitly during implementation because no capability map was approved up front
|
|
244
281
|
|
|
245
282
|
## Verification
|
|
246
283
|
|
|
@@ -254,3 +291,5 @@ Before proceeding to implementation, confirm:
|
|
|
254
291
|
- [ ] Success criteria are specific and testable
|
|
255
292
|
- [ ] Boundaries (Always/Ask First/Never) are defined
|
|
256
293
|
- [ ] The spec is saved to its output location (see Output Location)
|
|
294
|
+
- [ ] If the request bundles several independently testable capabilities, a capability map (module ids, dependency direction, build order) was approved before any module spec was written
|
|
295
|
+
- [ ] Every module spec traces to a module id in the approved map
|