j-mauro-r/SAT-Dengue-V2 / .agents/skills/deepworkplan/addons/agentkit
deepworkplan-addon-agentkit
VerifiedOptional DeepWorkPlan addon that integrates coding-agents-kit (the `ak` command, DailybotHQ/coding-agents-kit pinned at v1.0.1, interface 1) as the headless delegation transport - a thin integrator that detects the kit through `ak doctor --json`, offers it (never imposes it) from onboard Phase 7b, documents the install from a clone of the pinned tag plus the kit's install.sh, records the acceptance in the .dwp/config.json addon registry, and maps a v7 plan's delegation operations (launch, observe, collect, cancel) onto one `ak run` per delegate in a dedicated git worktree. Never required, never a conformance gate. The kit launches agents in autonomy by default and its opt-out (--ask or AGENTKIT_PERMISSIONS=ask) always wins; the pack spells no CLI autonomy flag, never passes --auto, and passes --ask always for a read-only delegate and for writing delegates when a plan records the opt-out.
DeepWorkPlan — agentkit Addon (headless delegation transport)
Integrate coding-agents-kit — one command surface (ak) for every
terminal coding agent (claude, codex, cursor, opencode, pi, cline, grok and
their provider variants, multiple accounts through profiles) — as the
headless transport a v7 plan may use to delegate a parallel_safe
task. This is an opt-in addon, never required for a repo to be
AI-first and never a conformance gate: without it every task runs in the
current session exactly as before.
This addon is a thin integrator. The kit is its own product
(https://github.com/DailybotHQ/coding-agents-kit, MIT, works without
DWP); everything this addon relies on is the kit's frozen interface 1
(ak run, ak env, ak doctor --json, the exit codes) at the pinned tag.
| Pin | Value |
|---|---|
| Product | DailybotHQ/coding-agents-kit |
| Tag | v1.0.1 (autonomy by default since v0.2.0; accounts, ak usage, ak pick, ak profiles --json, --trust-cwd and the agentkit-orchestrate skill since v0.5.0; Cursor's Linux login and Claude's keychain login kind since v0.5.1; a default account per CLI, AGENTKIT_DEFAULT_PROFILE_<CLI>, since v0.5.2; Codex started with --no-daemon when a shared home records a daemon from another machine, since v0.5.3; ak capacity with its usage cache, ak lease and ak pick --owner since v0.6.0; ak capacity --self inside Codex lanes, ak pick --owner counting the owner's own leases with --reuse @profile for a successor, one account per kind and profile, and Grok folder trust since v0.6.1; Antigravity quota and every account listed in ak usage since v0.7.0; a profile's suffixed credential variable counted as its login since v0.7.1; the first stable release, its interface committed to semantic versioning, v1.0.0; every profile, @default included, its own account inside a devcontainer-kit container, since v1.0.1) |
| Interface | 1 (ak doctor --json → "interface": 1) |
| Registry key | agentkit (.dwp/config.json → addons.agentkit) |
| Transport | headless — provides subagents, cancel_children, model_routing; requires the agent_delegation grant |
Read these first (all relative inside the skill)
SPEC.md— the normative contract: detection, offer, install, the transport mapping, the permission rules.templates/INTEGRATION.md— reasoning guidance for one delegate end to end (worktree, prompt, run, collect).../../execute/delegation.md— when a plan may delegate at all.
When this runs
onboardPhase 7b offers it as an explicit opt-in when the developer wants a plan to hand bounded tasks to other coding agents.executeuses it only throughdelegation.md, only on a v7 plan whose contract grantsagent_delegation, only for aparallel_safetask (or a read-only delegate), and only whenresources.py abilitiesshowsaddon:agentkitas asubagentssource.- Direct invocation, to install or check the kit.
Trust boundary (write scope)
allowed-tools includes write-capable Edit, Write, and Bash. The
write scope is bounded:
- Before consent: read-only. Detection is
command -v akandak doctor --json(key names only, never values). - Writes (only after explicit acceptance): the kit install through its
own pinned installer, the
addons.agentkitregistry entry, and — during a delegation — a dedicated git worktree for the delegate plus the collected result under the plan'sanalysis_results/delegations/<id>/. - It MUST NOT: spell a CLI autonomy flag (they stay in the kit's
providers.toml) or pass--auto(autonomy is already the kit's default) —--askis the one flag it passes: always for a read-only delegate (no worktree,--cwdthe repository), and for a writing delegate when the plan records the opt-out; drop or override an--ask/AGENTKIT_PERMISSIONS=askopt-out; read, print or write any provider key value; let a delegate write outside its worktree; install a coding-agent CLI unasked (ak installis the developer's call); run a delegate the ledger refused; or treat a delegate's result as evidence.
Permissions (the kit's, never the pack's)
Since v0.2.0 the kit launches every agent in autonomy by default: ak
adds the CLI's own autonomy flag, kept only in the kit's providers.toml.
The opt-out always wins: --ask on the command, or
AGENTKIT_PERMISSIONS=ask set by the developer (in the environment or the
kit's env file) or inherited from an opted-out session, suppresses the flag even when the same command says --auto and
even when the kit's env file says AGENTKIT_PERMISSIONS=auto. Autonomy is
meant for disposable or sandboxed environments, such as a dev container.
For delegation this means: a plan that grants agent_delegation on a host
accepts autonomous delegates confined to their own worktree, which is not a
sandbox. Say so when asking for the grant and offer the opt-out. When the
plan records it, launch each delegate with ak run --ask …; a delegate in
ask mode has no terminal, so it may stop at its first prompt, and
--timeout bounds it.
Read-only intent means ask. A read-only delegate (research, review,
analysis) gets no worktree and runs in the repository itself, so it is
always launched with --ask, whatever the plan records — autonomy
there would approve writes in the developer's checkout. Writing delegates
keep the autonomy default inside their own worktree, and the opt-out still
wins for them.
The flow
Step 0 — Detect (read-only)
command -v ak → ak doctor --json → read interface (must be 1;
anything else is one warning and "not available"), permissions (auto
or ask — how delegates will launch), the installed kinds and whether each
is logged in (file presence only), and the profile names. No state installs
anything.
Step 1 — Offer (never impose)
Explain what it adds — a plan may hand a bounded parallel_safe task to
another coding agent, in its own worktree, and verify the result with its
own gates — and what it costs: a machine-level install, provider accounts
you already have, per-plan consent (agent_delegation), and agents that run
in autonomy unless you opt out (--ask / AGENTKIT_PERMISSIONS=ask).
Declining is a complete answer.
Step 2 — Install (pinned; point-don't-run by default)
git clone --branch v1.0.1 https://github.com/DailybotHQ/coding-agents-kit
./coding-agents-kit/install.sh
Before running the installer, check the tag and the release's SHA256SUMS
(pinned digest, at least one file verified) as
../machine-installs.md shows.
(Windows: the same tagged clone, then .\coding-agents-kit\install.ps1.)
The installer touches no network, installs no CLI and never overwrites the
env file. Run it yourself only interactively and with explicit acceptance;
re-detect afterwards.
Step 3 — Record
python3 ../../shared/config.py enable agentkit --version v1.0.1 --repo <repo>.
Delegation still needs each plan's contract to grant agent_delegation —
enabling the addon grants nothing.
Step 4 — Transport (during execute)
One delegate = one ak run in one dedicated worktree
(templates/INTEGRATION.md):
| Operation | Mapping |
|---|---|
| launch | git worktree add <wt> -b dwp/<plan>/<delegation_id>; record ledger.py delegate launch (with prompt_digest); start ak run <kind> @<profile> --cwd <wt> --timeout <s> --output-format json [--ask] -- "<prompt>" in the background, stdout to the result file (--ask when the plan records the opt-out; always for a read-only delegate, --cwd the repository) |
| observe | ledger.py delegate observe; the background process is alive or has exited |
| collect | on exit read the one JSON object (exit 0 → completed, otherwise failed); ledger.py delegate collect with result_path; integrate the worktree's diff; run the task's gates here |
| cancel | send SIGTERM to ak run (the kit kills the whole process tree, exit 5); ledger.py delegate cancel |
Accounts and lanes (coding-agents-kit v0.5.0 and later)
Beyond one headless delegate, the kit is how a lead spreads lanes over the
developer's accounts (../../guide/orchestration-at-scale.md §16):
- Accounts. One CLI × one profile.
@defaultis the CLI's own home;@namelives under the profiles root.ak profileslists them (login yes/no, key names);ak profiles --jsonemits schemaprofiles-v1. Sincev0.5.1a Claude login is reported asfileonly with.credentials.json,keychainwhen the macOS Keychain item exists,nonewhen neither does (for example@defaultcopied into a container without its token) andunknownwhen the Keychain cannot be asked — presence only, the secret is never read. A Cursor login on Linux (a container or Linux host,~/.config/cursor/auth.json) is recognised byak usageandak doctor. - Default account per CLI (
v0.5.2).AGENTKIT_DEFAULT_PROFILE_<CLI>(environment or env file) names the account a bareak <cli>,ak run <cli>andak env <cli>use; a positional@profile,AGENTKIT_PROFILEor an explicit@defaultwins, and the profile must exist. In a dev container it comes from devcontainer-kit's host-profile[agents] default_profile. The addon never relies on it for a delegate: everyak runit launches names the chosen@<profile>explicitly (@defaultfor the CLI's own home), so the account recorded in the lane table and indelegate launchis the one that ran. - Every profile is its own account (
v1.0.1). Each ak profile,@defaultincluded, is an independent account — also inside a devcontainer-kit container, where@defaultis no longer merged into a named profile — soak usagelists@defaultandak <cli> @defaultlaunches the CLI's own home. - A Codex home shared across machines (
v0.5.3). A host profile shared into a container, or one volume shared by several containers, can record an app-server daemon installed by another machine; Codex then refused to start. An interactiveak codexadds--no-daemononly when the recorded daemon is missing here or built for another OS (AGENTKIT_CODEX_NO_DAEMON=1forces it);ak doctorreports each account's daemon state. - Quota.
ak usage --jsonreports every account's windows and status — once per batch, never in a loop (each call contacts the vendors). Fromv0.6.0, an agent's own room comes from the cachedak capacitybelow. - Choice.
ak pick <kind> --count Nreturns up to N accounts with room, best first (--exclude @p,--model <m>,--need 5h:40); exit 1 means none qualifies and names the soonest reset. The lead records each pick in the plan's lane table. - Claude token per profile.
CLAUDE_CODE_OAUTH_TOKEN(@default) andCLAUDE_CODE_OAUTH_TOKEN_<SUFFIX>(@name) live in the kit's env file and reach only that profile's Claude; a named profile never falls back. Handled by name only. - Pre-trusted folder.
ak <kind> @p --trust-cwd(orAGENTKIT_TRUST_CWD=1) pre-trusts the launch folder, so a lane started in a pane shows no folder-trust screen. Claude's per-profile bypass-permissions acknowledgement is the developer's one-time step when the profile is created; no agent answers it. - The lead's loop is the kit's own
agentkit-orchestrateskill (ak --skill orchestrate): inventory, pick, run, verify, fail over, report the spend. This addon adds only the plan side — the lane table, the journal record and the plan's gates.
Using an account is never a reason to look past an opt-out: --ask and
AGENTKIT_PERMISSIONS=ask win in every lane too.
Capacity and leases (coding-agents-kit v0.6.0 and later)
What lets a swarm hand work on before an account runs out
(../../guide/swarm.md §17):
- Own capacity.
ak capacity --self --json(schemacapacity-v1) gives the running account'sheadroom_pct,binding_window,resets_atand averdict—ok,low(≤ 25 %),critical(≤ 10 % or rate-limited) orunknown(no quota source: cursor, grok; Antigravity fromv0.7.0where its login file is readable, not the macOS Keychain) — withpick's arithmetic, read from a 300 s usage cache so a check at every task boundary stays cheap.--selfresolves the accountaklaunched; outside anaklaunch it exits 3 and never guesses. The pack never calls it directly:../../shared/swarm.py capacitywraps it and turns the verdict intocontinue,prepareorhandoff(capacity unknown, never ok, without the kit or with an older one). - Thresholds and drills.
AGENTKIT_CAPACITY_LOW/_CRITICAL(or--low/--critical) move the thresholds;AGENTKIT_CAPACITY_CAP=@p=PCTcan only lower a reading — it is how a drill makes an account look poor, and it can never make one look richer. - Leases.
ak lease <kind> @<profile> --owner <addr> [--ttl …]holds an account for one lane (a Codex profile takes one lease: one writer per auth file);ak lease release …frees it once a successor accepted the handoff;ak lease lslists them.ak pick <kind> --owner <lead>skips accounts leased to others and ranks the rest byheadroom / (1 + leases). Leases are advisory records — numbers, profile names and pane addresses, never a credential. - The pool. Work moves only among the accounts the developer declared for the plan, within each vendor's terms: no agent creates an account, renews a login or spends a Codex reset.
With an older kit, the developer assigns accounts and an agent reads its own
room once per task boundary with ak usage <kind> @<profile> --json.
Failure-mode guardrails
- Never required, never blocking. Not installed, not logged in, unknown interface, refused by the ledger: run the task in this session.
- The result is a claim.
result_textis what the agent said; only the plan's own gate runner turns the work intoobservedevidence. - Secrets stay names. Provider keys are environment variable names; the kit never prints values and neither does this addon.
Validation checklist (component 4 — mirrored from SPEC §8)
SKILL.md,SPEC.md,addon.json,templates/INTEGRATION.mdexist; the descriptor pinsDailybotHQ/coding-agents-kitv1.0.1, interface 1, transportheadless.- Detection is read-only and reports
interface1, or one warning. - Install used the pinned tagged clone +
install.sh; nothing piped. - The registry entry exists only after acceptance.
- Every writing delegate ran in its own worktree (
--askwhen the plan records the opt-out) and every read-only one with--ask; no autonomy flag was spelled by the addon, and each result was gated here.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 470k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |