Skip to content

akiiwa-games/AgentCompass / skills/agent-compass

agent-compass

Flagged

Choose owner, model and effort, outbound authorization, advisor use, and continuation for delegated work. Reads local usage and effective account policy, profiles the task with the configured System-One scorer, then allocates a compatible worker. Use for independent worker or advisor work; ordinary local execution needs no routing.

FileKindSize
SKILL.mdskill md5.5 KB
agents/openai.yamlconfig427 B
calibration/README.mdmarkdown55.2 KB
calibration/arena_capture.pyscript14.0 KB
calibration/community.pyscript25.2 KB
calibration/five_axis.pyscript196.4 KB
calibration/measurements.pyscript68.4 KB
calibration/refresh.pyscript48.6 KB
calibration/series.pyscript10.2 KB
calibration/sources.pyscript24.1 KB
calibration/tiers.pyscript14.6 KB
grok-bot/.gitignoreother47 B
grok-bot/dependency_patch.pyscript4.5 KB
grok-bot/install_cli.pyscript3.6 KB
grok-bot/test-recovery.mjsscript8.6 KB
grok-bot/test_install_cli.pyscript4.1 KB
grok-bot/upstream.jsonconfig3.4 KB
references/accounts.jsonconfig155.9 KB
references/classifier-cases.jsonconfig21.5 KB
references/dispatch-lifecycle.mdmarkdown28.9 KB
references/dispatch-rules.mdmarkdown11.3 KB
references/effort-matching.mdmarkdown5.1 KB
references/fast-modes.mdmarkdown3.5 KB
references/five-axis-scores.jsonconfig3.1 MB
references/gemini-decisions-api.mdmarkdown2.9 KB
references/grok-bot.mdmarkdown13.0 KB
references/herdr.mdmarkdown5.1 KB
references/jev-api.mdmarkdown1.6 KB
references/level-3-conversion.jsonconfig2.4 KB
references/model-capabilities.jsonconfig3.6 KB
references/model-capabilities.mdmarkdown14.6 KB
references/parent-address-gate.mdmarkdown10.1 KB
references/plan-templates.jsonconfig13.2 KB
references/provider-discovery.mdmarkdown11.5 KB
references/provider-usage.mdmarkdown4.1 KB
references/public-data.jsonconfig816 B
references/public-measurements.jsonconfig1.3 MB
references/roll-reference.mdmarkdown26.7 KB
references/router-internals.mdmarkdown93.7 KB
references/task-classifier.mdmarkdown6.1 KB
references/user-scores.jsonconfig6.8 KB
references/work-kinds.mdmarkdown4.7 KB
references/worker-communication.mdmarkdown2.1 KB
scripts/account_fleet.pyscript32.9 KB
scripts/account_state.pyscript22.2 KB
scripts/accounts_override.pyscript14.8 KB
scripts/allocator.pyscript19.8 KB
scripts/antigravity_plan.pyscript18.7 KB
scripts/antigravity_telemetry.pyscript5.1 KB
scripts/auto_bundles.pyscript31.3 KB
scripts/axis_scores.pyscript40.3 KB
scripts/caller_input.pyscript3.0 KB
scripts/candidate_eval.pyscript54.0 KB
scripts/candidate_ranking.pyscript9.5 KB
scripts/capability_catalog.pyscript8.0 KB
scripts/check_router_contract.pyscript2.8 KB
scripts/conftest.pyscript2.5 KB
scripts/cwd_policy.pyscript1.5 KB
scripts/data_age.pyscript1.5 KB
scripts/decision_ledger.pyscript18.9 KB
scripts/demo_plan.pyscript6.3 KB
scripts/dispatch_fallback.pyscript40.3 KB
scripts/dispatch_flow.pyscript58.7 KB
scripts/dispatch_ground_truth.pyscript43.5 KB
scripts/dispatch_registry.pyscript113.7 KB
scripts/entry.pyscript1.7 KB
scripts/env_vars.pyscript580 B
scripts/fast_modes.pyscript2.5 KB
scripts/fixtures/grok-api-responses.jsonconfig907 B
scripts/fixtures/reference-accounts.jsonconfig26.9 KB
scripts/grok_bot_paths.pyscript1005 B
scripts/host_herdr.pyscript16.8 KB
scripts/host_placement.pyscript9.4 KB
scripts/host_policy.pyscript10.1 KB
scripts/launch_failures.pyscript5.9 KB
scripts/launch_values.pyscript12.3 KB
scripts/ledger_snapshot.pyscript11.1 KB
scripts/live_models.pyscript21.1 KB
scripts/model_latch.pyscript7.6 KB
scripts/model_resolution.pyscript18.0 KB
scripts/override_store.pyscript2.2 KB
scripts/plan_state_residue.pyscript5.0 KB
scripts/provider_inventory.pyscript128.2 KB
scripts/provider_retry.pyscript34.6 KB
scripts/public_data.pyscript59.2 KB
scripts/quota_economy.pyscript38.0 KB
scripts/quota_exhaustion.pyscript5.9 KB
scripts/quota_overrides.pyscript25.6 KB
scripts/quota_pools.pyscript29.8 KB
scripts/reference_provenance.pyscript32.3 KB
scripts/released_names.pyscript3.8 KB
scripts/roll.pyscript106.3 KB
scripts/route_judge.pyscript83.4 KB
scripts/route_simulation.pyscript26.3 KB
scripts/router_test_support.pyscript6.7 KB
scripts/run_grok_bot.pyscript18.8 KB
scripts/scorer_client.pyscript55.2 KB
scripts/stage_help.pyscript5.8 KB
scripts/state_upgrade.pyscript24.0 KB
scripts/subscription_cli.pyscript3.6 KB
scripts/task_intake.pyscript33.6 KB
scripts/test_account_identity.pyscript7.1 KB
scripts/test_account_state.pyscript63.3 KB
scripts/test_accounts_override.pyscript30.1 KB
scripts/test_allocator.pyscript94.2 KB
scripts/test_antigravity_plan.pyscript13.2 KB
scripts/test_applicable_quota.pyscript9.1 KB
scripts/test_auto_bundles.pyscript10.8 KB
scripts/test_billing_routing_policy.pyscript9.9 KB
scripts/test_cadence_count.pyscript32.2 KB
scripts/test_calibration_units.pyscript27.0 KB
scripts/test_capability_catalog.pyscript5.0 KB
scripts/test_decision_ledger.pyscript8.5 KB
scripts/test_demo_plan.pyscript3.4 KB
scripts/test_derived_state.pyscript21.6 KB
scripts/test_dispatch.pyscript322.3 KB
scripts/test_dispatch_answers.pyscript14.8 KB
scripts/test_dispatch_fallback.pyscript53.2 KB
scripts/test_entry.pyscript1.6 KB
scripts/test_fast_modes.pyscript9.9 KB
scripts/test_five_axis.pyscript290.1 KB
scripts/test_five_axis_economy.pyscript105.0 KB
scripts/test_fleet_parity.pyscript15.6 KB
scripts/test_grok_bot.pyscript47.7 KB
scripts/test_ground_truth_recording.pyscript68.8 KB
scripts/test_herdr.pyscript14.1 KB
scripts/test_host_policy.pyscript24.6 KB
scripts/test_launch_values.pyscript8.0 KB
scripts/test_metered_usd.pyscript60.4 KB
scripts/test_model_resolution.pyscript9.2 KB
scripts/test_named_route_facts.pyscript28.6 KB
scripts/test_native_hosts.pyscript6.0 KB
scripts/test_new_user_fleet.pyscript3.3 KB
scripts/test_no_hardcode_classification.pyscript75.1 KB
scripts/test_no_legacy_scoring.pyscript6.5 KB
scripts/test_override_store.pyscript2.3 KB
scripts/test_plan_says_why.pyscript44.9 KB
scripts/test_provider_inventory.pyscript83.2 KB
scripts/test_provider_names.pyscript126.0 KB
scripts/test_provider_pools.pyscript14.2 KB
scripts/test_public_data.pyscript93.5 KB
scripts/test_quota_exhaustion.pyscript5.6 KB
scripts/test_rate_limit_windows.pyscript6.3 KB
scripts/test_record_says_why.pyscript26.5 KB
scripts/test_reference_provenance.pyscript16.7 KB
scripts/test_refresh_entry.pyscript110.7 KB
scripts/test_released_names.pyscript4.1 KB
scripts/test_reset_priority.pyscript4.8 KB
scripts/test_roll_answers.pyscript44.7 KB
scripts/test_roll_notifications.pyscript10.4 KB
scripts/test_route_judge.pyscript99.8 KB
scripts/test_route_simulation.pyscript7.0 KB
scripts/test_routing_parity.pyscript32.3 KB
scripts/test_routing_review.pyscript25.1 KB
scripts/test_setup_discovery_parity.pyscript9.5 KB
scripts/test_stage_help.pyscript2.0 KB
scripts/test_state_upgrade.pyscript13.8 KB
scripts/test_turn_refusal.pyscript16.7 KB
scripts/test_usage_cache.pyscript4.9 KB
scripts/test_usage_collector.pyscript21.4 KB
scripts/test_usage_core_claude_accounts.pyscript1.8 KB
scripts/test_usage_core_grok_cli_billing.pyscript15.6 KB
scripts/test_usage_core_magpie.pyscript5.4 KB
scripts/test_usage_core_magpie_pool.pyscript10.8 KB
scripts/test_usage_core_safety.pyscript24.4 KB
scripts/test_user_scores.pyscript102.3 KB
scripts/test_venice_usage.pyscript1.3 KB
scripts/test_window_scope.pyscript5.5 KB
scripts/turn_refusal.pyscript10.7 KB
scripts/usage_cache.pyscript4.7 KB
scripts/usage_collector.pyscript7.4 KB
scripts/usage_core.pyscript142.0 KB
scripts/usage_magpie.pyscript10.6 KB
scripts/usage_reading.pyscript17.1 KB
scripts/user_scores.pyscript72.8 KB
scripts/venice_usage.pyscript2.6 KB
scripts/window_scope.pyscript3.2 KB
scripts/worker_context.pyscript8.9 KB
scripts/worker_sessions.pyscript10.9 KB

references/dispatch-rules.md

View on GitHub
# Rules for a dispatching session

The global rule block AgentCompass installs is a short pointer to this skill. Read this file before you launch, continue or replace a worker, an advisor or any sub-agent. Each rule names the reference that holds its details; this file does not repeat them.

## 1. One entry, then do exactly `next_action`

1. Launch through `agentcompass roll` only, one brief per independent task ([SKILL.md](../SKILL.md#dispatch)). Never call Paseo `create_agent`, a host's `Agent`/`Task`, `spawn_agent`, `invoke_subagent`, `run_dot_task.py` or a host's worker launcher (`paseo run`, `orca orchestration worker-start`) yourself. A model CLI asked for one answer from a shell (`claude -p`, `codex exec`, `agy -p`, `gemini -p`, `opencode run`, `pi -p`) is a quick call, not a dispatch, and the gate does not read it as a launch; work you hand to a worker still goes through `roll`. A host's built-in tool agent is tool use, not a dispatch: in Claude Code `web-fetch` (reads a web page), `statusline-setup` (what `/statusline` runs) and `claude-code-guide` (answers questions about Claude Code). Codex and Antigravity have none; `Explore`, `Plan`, `general-purpose` and every other agent type are dispatches. The gate lets the built-in tool agents through unless a project or user agent definition takes one of their names. Antigravity's `browser_subagent` and each host's own web tools are ordinary tools and were never part of this rule.
2. Read `status` and do exactly `next_action`; `launched` means the worker runs, so start nothing else for that task. When `next_action` says completion arrives as a notification, finish any independent work and end your turn so the notification wakes you — never sleep or poll (`paseo ls`, `get_agent_status`, result files) in a shell command. Result variants: [roll reference](roll-reference.md).
3. A delegated worker (`AGENTCOMPASS_WORKER=1`, or a `Parent session agent ID:` contract at the end of its brief) does its assignment itself and does not delegate again unless the brief appoints it coordinator.

## 2. Model and effort belong to the router

1. Never pick a model or effort, and never raise the effort the router returned.
2. Only when the user named a model or effort in this request: add `--provider <p> --account <a> --model <m> --effort <e> --basis "<the user's words>"` to `roll` ([router internals, record an override](router-internals.md#b-record-an-explicit-user-modeleffort-override)).
3. When an account or model becomes unavailable (subscription expired, account removed, quota exhausted, `named_model_unavailable`), roll again. Do not substitute a model that looks similar.

## 3. Continue a worker, or replace it

Worker notifications carry the continuation verdict; host fields such as `contextWindowUsedTokens` and `contextWindowMaxTokens` are not the rotation measure. The verdict is `same worker` only when the worker is under the rotation threshold **and** nothing advises against a new turn to it. The gate enforces three of those conditions on a parent's new turn to its own worker: the account carries no leftover meter fields, the account's confirmed quota exhaustion is not latched, and no quota window the bundle draws refuses a launch. An account outside automatic routing or a model unchecked since the launch does not stop a new turn: continuing a worker is not choosing its account or model. The verdict adds advice the gate does not enforce: the worker's own last turn did not end in a provider failure, its account is ready, and neither its account, quota pool nor model is held after a provider failure (`turn_refusal.py`). Otherwise the verdict says `roll` and names the reason, or `rotate` at the threshold; a worker the router cannot resolve, or a check that cannot be read in time (such as `carried_context_unavailable` or `session_state_unavailable`), says `unknown`. An `unknown` verdict caused by unavailable telemetry is not by itself a reason to replace a worker; only `roll` or `rotate` are. On `roll` or `rotate`, do not send the follow-up to that worker; a parent that sends it anyway is admitted by the gate whenever the three enforced conditions pass. The verdict's own registry and quota reads are read-only and bounded (it records no hold and waits on no writer); it loads the fleet through `load_accounts`, which may update host policy and holds as it does for every other caller.

1. Follow-up work should go to the same worker (Paseo `send_agent_prompt`, a host's `SendMessage`, or `agentcompass roll --resume <id>` / matching `--workspace` for a new brief) while its verdict says `same worker` (or `unknown` only from unavailable telemetry): its accumulated uncompressed context is under the configured context rotation threshold (`rotate_after_carried_tokens`, set in the tray). Count `compacted_tokens + context_tokens`: the context before every earlier compaction plus the current window, never the current window alone.
2. At or above `rotate_after_carried_tokens`, write the progress and the remaining work into a handoff brief and run `agentcompass roll --brief <handoff.md>` for a fresh worker. Changing the owner, model or effort also means rolling again.
3. A correction or redesign of a worker's own task is the same task, not a new one. When the result is rejected or the design changes (wrong approach, a constraint was missed, scope moves), send the corrected task to that worker instead of cancelling it and rolling a fresh one. Its context about the code and the earlier attempt is what the redo needs. Replace it only when point 2 applies or its context window cannot hold the rest of the work. A different kind of task with little shared context still gets its own brief and its own roll.
4. The limit applies to starting a new turn. A parent may still send control messages (steer, cut scope, answer a question, wrap up and hand off) to its own worker while that worker is running. An idle worker, or one whose state or ownership is unknown, gets no exception: collect its output, `cancel_agent` if needed, and roll the handoff ([gate contract](parent-address-gate.md#disabled-target-quota-and-context-rotation-gate-contract)).

## 4. Permission mode on every launch

`roll` sets the mode for the launches it performs. When you start a worker yourself (`status: native`, or a native launch recorded with `record`), pass the mode explicitly; a provider default can leave a worker waiting on a permission prompt while its status still says running.

- First choice: `selected_bundle.modeId` (or `route_bundle.modeId`) from the router.
- Otherwise by provider: Codex `full-access`, Claude `bypassPermissions` (`bypass` is not a valid value), Antigravity `full-access`, OpenCode `build`; Pi and Grok take no mode. Full table: [router internals, launch contract](router-internals.md#3-worker-launch-communication--permission-contract).
- Narrow the mode for read-only roles (reviewer, advisor); never widen it.
- After launch, read the agent's status once to confirm the mode took effect and it is not waiting on a permission.

## 5. Gate and audit

1. When the gate hook is installed (`agentcompass gate-hook`, wired into each host's `PreToolUse` / `tool_call`), it blocks a sub-agent launch that has no `plan` or `record` entry in `~/.agent-compass/router-ledger.jsonl` from the last 15 minutes. Run `roll` (or `record`, below) first. `agentcompass uninstall` removes the hook.
2. The daily audit compares sub-agent launches with ledger records and reviews every `--keep-whole` reason.
3. Route only sub-agent, worker and advisor sessions. A one-shot, tool-less classification or structured-JSON call made inside a business or evaluation script is not a dispatch: do not write `record` entries for it.
4. Exhausted quota windows block new launches, and an unchecked model starts only on a route the user named; exhausted windows and the rotation limit block a parent's new turn to its own idle worker, never its control messages to its own running worker. A message to an agent the caller does not own is communication and is not checked ([gate contract](parent-address-gate.md)).
5. An account outside host policy's `allowed_accounts` and a model unchecked in model management are out of automatic routing: no plan, fallback, automatic resume or scorer chooses them. A route the user names in this request (`roll --provider/--account/--model --basis`, `record --constraint user_override`) still dispatches on them, and the decision carries a warning that names the switch; `roll --resume <agent_id>` on such a worker proceeds with the same warning. A `hard_constraint` record does not override them: a project rule is shared between machines, the switches are this machine's. A plan they block names the account or model and the switch, as the user's own setting; do not ask the user to change it, offer the named route.

## 6. A launch the router cannot perform

Some launches must go through the host's own sub-agent tool, for example a review agent defined in a project's `.claude/agents/` that a commit gate counts by agent type. Record the forced route first, then launch natively with the same model and an explicit permission mode:

```bash
agentcompass record --constraint hard_constraint --provider <p> --account <a> --model <m> --effort <e> --basis "<the project rule or user instruction that forces this route>"
```

Use `--constraint user_override` when the user named the route; only that constraint launches on an account kept out of automatic routing on this host (any other answers `status: blocked`, exit 2, and its `next_action` says why). `record` says in `warnings` what it did not look at or read: each quota window of the named model that was not read, a flag the stage does not take, a name read as another row. `record` writes the current session ID, so the gate matches it even right after another `roll`. Project-specific instructions of this kind (which agent, which model) belong in that project's own `CLAUDE.md` / `AGENTS.md`.

## 7. Parent address and worker messages

1. Every brief carries the real parent session ID, host and message address; without them, do not launch. Never substitute `top-level`, a task ID or the worker's own ID. `roll` fills these in and appends the [worker communication contract](worker-communication.md); a native launch must carry both too ([parent address gate](parent-address-gate.md)).
2. Each dispatch has one report channel, and `roll` writes that channel into the [worker communication contract](worker-communication.md). A dispatch with a completion watcher does not send `[Worker final report]`; the watcher sends one `[AgentCompass worker notification]` that already contains the final reply. A dispatch with no watcher (CLI, Dot, Grok Bot, Herdr, native, Cindy, T3, agy) still sends `[Worker final report]` itself. A question is still a real message (Paseo: `send_agent_prompt` with `background: true, notifyOnFinish: false`) and the turn ends. UI-only question tools (`AskUserQuestion`, `ask_user_question`, `request_user_input`, `request_user_input_async`) never reach the parent.
3. A parent that adds work to, releases or resumes its own worker keeps `notifyOnFinish` true (or omits it). That completion notification is the one end message for the continued turn; the worker does not also send a report.
4. No channel, no parent address, or a failed send: return `BLOCKED / needs_input` with the exact question and the delivery problem through the normal result channel.
5. None of this stops a main session from asking the real user, and it does not replace platform approvals.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall