agent-policy-kit 0.2.0 → 0.4.0

package/docs/reference/presets.md

@@ -0,0 +1,128 @@
+# Presets
+
+This document lists the three presets of release 0.4.0: Light, Standard and Top-tier. It gives the model and effort that each preset selects for each role and AI assistant, the top models switch, the parallel limits and the design principles. It is for everyone who chooses a preset or wants to know why a preset has its values.
+
+A preset is a named set of preferences that the release supplies. The data is in `policies/fast.json` (Light), `policies/balanced.json` (Standard) and `policies/quality.json` (Top-tier). The CLI uses the ids `fast`, `balanced` and `quality`. The page and this document use the labels. For the roles, see [Roles](roles.md). For model IDs, efforts and access requirements, see [Model catalog](model-catalog.md). The detailed evidence is in the [model review of 2026-11-01](../research/2026-11-01-model-review.md).
+
+## Summary
+
+| Preset | CLI id | Description | Parallel limit per assistant |
+|---|---|---|---|
+| Light | `fast` | Light models for every role. Limits last longest. | 2 |
+| Standard | `balanced` | Stronger models for code, review, tests and docs. Fits most plans. | 3 |
+| Top-tier | `quality` | High-end models for most roles. Uses limits fastest. | 2 |
+
+Standard is the default preset. `setup --release` without `--preset` applies it. For the commands, see [Commands](../guide/commands.md).
+
+## Design principles
+
+The presets were reviewed on 2026-11-01. They are starting recommendations, not a quality ranking.
+
+- Subagent usage counts against the same plan limits as the main session. Each parallel session adds to that usage. The presets therefore differ in how much of the plan the subagents can use.
+- No comparative task benchmark was run for the presets. Configuration tests check settings, not model quality.
+- Vendors' effort labels and subscription usage are not directly comparable. One role can therefore get different effort levels in different assistants.
+- Presets pin at most `high`. The only exception is the Claude top choice at `xhigh`. Higher effort gives quickly diminishing returns. Higher levels stay available in Custom.
+- No preset bans a model. A model that a preset does not select stays available in Custom. Personal avoid lists stay available in preferences and CLI input.
+- Each table cell is `model · effort`. A cell without an effort means that the assistant has no per-role effort setting. Gemini and Grok cells have no effort for this reason. See [Roles](roles.md#how-effort-applies).
+
+### Light
+
+| Role | ChatGPT | Claude | Kimi | Gemini | Grok |
+|---|---|---|---|---|---|
+| Coder | Luna · high | Haiku 5.5 · medium | K2.8 Preview · low | Flash | Grok Build 0.1 |
+| Reviewer | Luna · high | Haiku 5.5 · high | K2.8 Preview · low | Flash | Grok Build 0.1 |
+| Code explorer | Luna · low | Haiku 5.5 · low | K2.8 Preview · low | Flash Lite | Grok Build 0.1 |
+| Test writer | Luna · high | Haiku 5.5 · high | K2.8 Preview · low | Flash | Grok Build 0.1 |
+| Docs writer | Luna · low | Haiku 5.5 · low | K2.8 Preview · low | Flash Lite | Grok Build 0.1 |
+| Task runner | Luna · low | Haiku 5.5 · low | K2.8 Preview · low | Flash Lite | Grok Build 0.1 |
+
+Light uses light models for every role, so plan limits last longest. It suits entry plans and many parallel sessions.
+
+- ChatGPT runs GPT-6 Luna at high for code, review and tests. OpenAI suggests high as the starting level for Luna. Luna is the cheapest Codex model at any level.
+- Claude gives reviews and test creation more reasoning than the Coder. Checking edge cases is different from executing known steps.
+- Kimi roles share one alias, and an alias has one effort. Light keeps that effort at low to save quota.
+- Gemini uses Flash for code, review and tests, and Flash Lite for lighter work.
+- Grok uses Grok Build 0.1, the fast coding model, for every role.
+
+### Standard
+
+| Role | ChatGPT | Claude | Kimi | Gemini | Grok |
+|---|---|---|---|---|---|
+| Coder | Sol · medium | Sonnet 5.5 · medium | K3 256K · high | Pro | Grok 4.7 |
+| Reviewer | Sol · high | Sonnet 5.5 · high | K3 256K · high | Pro | Grok 4.7 |
+| Code explorer | Luna · high | Haiku 5.5 · medium | K2.8 Preview · low | Flash | Grok Build 0.1 |
+| Test writer | Sol · high | Sonnet 5.5 · high | K3 256K · high | Pro | Grok 4.7 |
+| Docs writer | Terra · medium | Sonnet 5.5 · medium | K3 256K · high | Flash | Grok 4.7 |
+| Task runner | Luna · low | Haiku 5.5 · low | K2.8 Preview · low | Flash Lite | Grok Build 0.1 |
+
+Standard uses stronger models for implementation, review, test creation and documentation. It uses light models for fact gathering and mechanical work.
+
+- ChatGPT runs GPT-6.1 Sol for code, review and tests. Luna runs at high for exploration. GPT-6.1 Terra runs at medium for docs: OpenAI positions Terra for clear writing, at half of Sol's usage.
+- Claude's Haiku 5.5 explorer uses medium, its native default.
+- Kimi uses K3 256K for code, review, tests and docs. Its quota footprint is smaller than that of the full-context K3. Larger-context choices stay editable.
+- Gemini uses Flash for exploration and docs.
+- Grok adds Grok 4.7 for code, review, tests and docs.
+- No Standard role uses GPT-6 Astra, Fable or K3.1 Pro.
+
+### Top-tier
+
+| Role | ChatGPT | Claude | Kimi | Gemini | Grok |
+|---|---|---|---|---|---|
+| Coder | Sol · high | Opus 5.5 · high | K3 · high | Pro | Grok 4.7 |
+| Reviewer | Sol · high | Opus 5.5 · high | K3 · high | Pro | Grok 4.7 |
+| Code explorer | Sol · medium | Opus 5.5 · medium | K3 · high | Pro | Grok 4.7 |
+| Test writer | Sol · high | Opus 5.5 · high | K3 · high | Pro | Grok 4.7 |
+| Docs writer | Sol · medium | Opus 5.5 · medium | K3 · high | Pro | Grok 4.7 |
+| Task runner | Sol · medium | Sonnet 5.5 · medium | K2.8 Preview · high | Flash | Grok Build 0.1 |
+
+Top-tier uses GPT-6.1 Sol, Opus 5.5 and K3 at high effort for implementation, review and tests. It uses limits fastest. It suits top plans with few parallel sessions.
+
+- Exploration and documentation use the same high-end model. In ChatGPT and Claude they run at medium. Read-only discovery and writing do not need the edge-case checking that high is for.
+- In Claude, Kimi, Gemini and Grok, only the Task runner uses a lighter model. ChatGPT uses Sol for every role. Its Task runner runs at medium, the same as exploration and documentation.
+- Kimi keeps one effort per shared alias. K2.8 Preview has no medium level, so the Kimi Task runner uses high.
+- Gemini has one top tier, Pro. Gemini's Standard and Top-tier differ only in exploration, docs and the Task runner.
+- Grok also uses Grok 4.7 for exploration. The Grok Task runner keeps Grok Build 0.1.
+
+## Top models switch
+
+The top models switch is an option of Top-tier on the [configurator](../guide/configurator.md). It is not a separate preset. Each assistant has its own switch. The switch is off by default, because the top choices use limits much faster. Share links keep the switch state.
+
+When the switch is on, the Coder, Reviewer and Test writer use the top choice of the assistant:
+
+| Assistant | Top choice |
+|---|---|
+| ChatGPT | GPT-6 Astra · high |
+| Claude | Opus 5.5 · xhigh |
+| Kimi | K3.1 Pro · high |
+
+Gemini and Grok have no top choice.
+
+For Claude, the switch raises the Opus 5.5 effort instead of selecting Fable 5.1. Anthropic's own benchmarks put Opus 5.5 ahead of Fable 5.1 on every published coding benchmark, at 2.5 times lower price. Anthropic also suggests a higher Opus effort before Fable. Fable 5.1 stays available in Custom.
+
+The default subagent setting of Claude caps the effort at high. The `xhigh` top choice therefore does not raise subagents that have no named role. See [Roles](roles.md#default-subagent-per-assistant).
+
+## Parallel limits
+
+The parallel limit is the maximum number of subagents that run at the same time in one session. The defaults are Light 2, Standard 3 and Top-tier 2 for each assistant.
+
+- Light keeps short work bounded.
+- Standard lets three independent responsibilities overlap.
+- Top-tier limits long work on heavier models that runs at the same time.
+
+These values are product defaults, not benchmark results. A limit does not start tasks and does not measure quality. Each assistant can override its limit on the page or with `--TOOL-max-concurrent`. Some assistants enforce the limit natively. For others it is guidance only. See [AI assistants](assistants.md#native-limits).
+
+## Reasons by vendor
+
+These are short reasons. The sources and the detailed comparisons are in the [model review of 2026-11-01](../research/2026-11-01-model-review.md).
+
+- **OpenAI (ChatGPT):** OpenAI positions Astra for demanding work, Sol for a balance of capability and usage, Terra for fast, clear writing and Luna for focused, efficient work. In Codex credits per token, Astra costs 5 times Sol, Terra costs half of Sol and Luna costs a tenth of Terra. OpenAI's subagent guide suggests Sol for demanding agents, Luna for lighter subagent work, high for Luna, and names reviewer or security-focused agents as examples for high. The reviewer example of the same guide uses Sol at medium.
+- **Anthropic (Claude):** Anthropic suggests Sonnet for most coding, Opus for complex architectural work and Haiku for simple subagent tasks. Anthropic suggests Fable only when Opus 5.5 at a higher effort still falls short. Anthropic describes high as the level for work where verification matters and xhigh as deeper reasoning at higher token spend. Anthropic reports that Sonnet 5.5 scored lower at max than at xhigh, because it started review subagents more often.
+- **Moonshot (Kimi):** Kimi describes K2.8 Preview as efficient thinking and K3 256K as a smaller quota footprint than K3. Moonshot recommends K3 256K for routine feature work and K3 for large-codebase analysis and multi-file refactoring. K3.1 Pro Highspeed has the same capabilities as K3.1 Pro at a quota premium, so no preset uses it.
+- **Google (Gemini):** The presets use only the native role tiers of Antigravity. The tiers do not fix the underlying model, and there is no per-role effort.
+- **xAI (Grok):** Grok Build 0.1 is xAI's fast coding model and serves light work. Grok 4.7 is the flagship and serves code, review, tests and docs. Grok 4.6 and 4.5 stay available in Custom.
+
+Account access to each model varies by plan. A preset does not grant access. For plan requirements, see [Model catalog](model-catalog.md#access-requirements).
+
+## What a preset does not freeze
+
+A preset fixes the model IDs and effort levels that it writes. It does not fix what a provider alias or tier resolves to, and it does not keep a retired model available. For release selection and updates, see [Updates and removal](../guide/updates-and-removal.md). For the review procedure for the next release, see [Model review procedure](../maintainers/model-review.md).

package/docs/reference/roles.md

@@ -0,0 +1,157 @@
+# Roles
+
+This document describes the six subagent roles of APK: what each role does, its prompt, its permissions and the files that APK writes for it. It also describes the default subagent of each AI assistant and how effort applies. It is for everyone who selects roles or wants to know what a configured subagent receives.
+
+A role is a named subagent definition, for example `apk-reviewer`. The main agent decides whether to delegate. A role file does not start a subagent and does not require delegation. Main models, permissions and disabled agent features stay as they are. The roles are defined in `src/roles.mjs`. The page and the native files use the same definitions.
+
+## The six roles
+
+| Role | Native name | Kind | Assignment in the routing instructions |
+|---|---|---|---|
+| Coder | `apk-worker` | code | scoped implementation and fixes |
+| Reviewer | `apk-reviewer` | code | read-only correctness, security and regression review |
+| Code explorer | `apk-explorer` | light | read-only code and documentation discovery |
+| Test writer | `apk-tester` | code | test creation and targeted execution |
+| Docs writer | `apk-writer` | light | assigned documentation, examples and release notes |
+| Task runner | `apk-routine` | light | explicit commands and mechanical edits |
+
+The kind selects the default choice in preferences. Code roles use the `code` model and effort. Light roles use the `light` model and effort. A role-specific entry in `roles` overrides the default. See [Preferences](../guide/preferences.md).
+
+The native names are fixed. The CLI uses the ids `worker`, `reviewer`, `explorer`, `tester`, `writer` and `routine`.
+
+## Role selection
+
+By default, APK configures all six roles. The optional `selectedRoles` preference (or `--roles` on the command line) selects a subset. APK then writes role files and routing text only for the selected roles. A Kimi alias that only unselected roles use needs no provisioning and gets no effort pin.
+
+## Descriptions and prompts
+
+The description is the short text that the native client shows. The prompt is the body of the role file. Every prompt ends with the same sentence: "Do not create child agents; return any need for further delegation to the parent."
+
+### Coder
+
+Description: "Implements scoped changes, preserves peers' edits, and verifies the result."
+
+Prompt: "Implement the assigned change or fix within the assigned files. You share the workspace with other agents: preserve their edits. Verify the result and report changes, checks, and remaining limitations."
+
+### Reviewer
+
+Description: "Reviews correctness, security and regressions without edits; reports actionable evidence."
+
+Prompt: "Review the assigned change without editing files. Find actionable correctness, security, and regression issues. Report each finding with file and line evidence and explain its impact; distinguish confirmed issues from uncertainty."
+
+### Code explorer
+
+Description: "Maps code and documentation, cites sources, and separates facts from uncertainty."
+
+Prompt: "Explore the assigned code and documentation without editing files. Return a concise map or factual answer with source paths or citations. Distinguish verified facts from assumptions and unknowns."
+
+### Test writer
+
+Description: "Writes behavior and edge-case tests, reproduces issues, and runs targeted checks."
+
+Prompt: "Own the assigned tests and targeted execution. Reproduce the issue or establish a baseline, then test observable behavior and edge cases. Never weaken checks to make them pass. Do not edit application code unless explicitly assigned. Preserve peers' edits and report results and limitations."
+
+### Docs writer
+
+Description: "Updates assigned docs and examples, verifies claims, and keeps terminology consistent."
+
+Prompt: "Update only the assigned documentation, examples, or release notes. Verify claims against code or cited sources and use consistent terminology. Do not edit application code. Preserve peers' edits and report changes and unknowns."
+
+### Task runner
+
+Description: "Runs prescribed commands and mechanical edits; returns ambiguous decisions to the parent."
+
+Prompt: "Execute only the prescribed commands or clearly specified mechanical edits. Preserve other agents' work and report the outcome. Do not make ambiguous design or behavior decisions; return those decisions to the parent."
+
+## Permissions
+
+The Reviewer and the Code explorer are read-only roles. Their prompts tell them not to edit files. Three assistants also restrict them natively:
+
+| Assistant | Native read-only setting for Reviewer and Code explorer |
+|---|---|
+| ChatGPT | None. The prompt is the only restriction. |
+| Claude | `tools: Read, Grep, Glob` |
+| Kimi | `tools: [Read, Grep, Glob]` |
+| Gemini | None. The prompt is the only restriction. |
+| Grok | `permission_mode: plan` |
+
+The other four roles get no tool restriction. They use the permissions of the native client.
+
+## Role file contents
+
+For the file paths, see [AI assistants](assistants.md#files-written). Each file has these fields:
+
+| Assistant | Format | Fields |
+|---|---|---|
+| ChatGPT | TOML | `name`, `description`, `model`, `model_reasoning_effort` (only when the effort is pinned), `developer_instructions` (the prompt) |
+| Claude | Markdown with frontmatter | `name`, `description`, `model`, `effort` (only when pinned), `tools` (read-only roles); the body is the prompt |
+| Kimi | Markdown with frontmatter | `name`, `description`, `tools` (read-only roles); the body is the prompt and a routing note |
+| Gemini | Markdown with frontmatter | `name`, `description`, `model` (the tier), `subagent: true`; the body is the prompt |
+| Grok | Markdown with frontmatter | `name`, `description`, `permission_mode: plan` (read-only roles); the body is the prompt |
+
+- Kimi frontmatter does not select a model. The routing note in the body names the pool alias and the requested effort. The parent selects the alias when it spawns the subagent.
+- Grok takes the model of each role from `[subagents.models]` in `config.toml`, not from the role file.
+
+## Instruction block
+
+APK adds one block to the global instruction file of each assistant. The block starts with `<!-- BEGIN agent-policy-kit -->` and ends with `<!-- END agent-policy-kit -->`. It contains these sentences:
+
+1. "These preferences apply only if you choose to delegate to subagents. They do not require delegation or change how you handle work directly."
+2. A routing sentence that maps each selected role to its assignment, for example "When delegating, use apk-worker for scoped implementation and fixes, apk-reviewer for …".
+3. The parallel limit: "When delegating, run at most N subagents concurrently in this session." It also asks for one concrete result and explicit file ownership for each agent, and says that child agents return further delegation to the parent.
+4. Text for the assistant:
+   - ChatGPT and Claude: use the named role definitions for model and effort, which settings can override them, and that an omitted role effort uses the native default.
+   - Kimi: the pool alias and effort for each role, that roles that share an alias share its effort, and that the concurrency limit is guidance.
+   - Gemini: the tier for each role, and that per-role effort and a hard concurrency cap are not supported.
+   - Grok: use the named role definitions for model selection, and that subagents use the main session effort.
+5. If the avoid list is not empty: "Avoid these models when delegating: …. This is routing guidance."
+
+## Default subagent per assistant
+
+A subagent can start without a named role. Most assistants then use a native default. APK sets that default from the first selected role, in the order of the table in [The six roles](#the-six-roles). When the Coder is selected, it is the Coder.
+
+| Assistant | Model setting | Effort setting |
+|---|---|---|
+| ChatGPT | `agents.default_subagent_model` | `agents.default_subagent_reasoning_effort`, the same effort, when pinned |
+| Claude | `CLAUDE_CODE_SUBAGENT_MODEL` | `CLAUDE_CODE_SUBAGENT_EFFORT`, when pinned, capped at `high` |
+| Kimi | `secondary_model.default_model` (the alias) | The per-alias effort of that alias, when pinned |
+| Gemini | Not set | Not set |
+| Grok | `subagents.models.general-purpose` | Not set. Subagents use the main session effort. |
+
+- **Claude cap:** a role effort of `xhigh` or `max` becomes `high` for the default subagent. The Claude top choice at `xhigh` therefore does not raise subagents without a named role. Claude Code 2.1.316 or later reads `CLAUDE_CODE_SUBAGENT_EFFORT`. Earlier versions ignore it, and those subagents keep the main session effort.
+- **Gemini:** APK writes no configuration file for Antigravity, so subagents without a role follow native Antigravity behavior.
+- **Grok:** without the `general-purpose` entry, a subagent without a named type inherits the parent model.
+
+## How effort applies
+
+Effort is the reasoning level that a model uses. An unpinned effort (`null`, or `:native` on the command line) means that APK writes no effort field. The native client then uses its default. APK never changes the effort of the main agent to suit a subagent.
+
+| Assistant | Where the effort goes | Notes |
+|---|---|---|
+| ChatGPT | `model_reasoning_effort` in the role file | Levels follow the native Codex catalog. |
+| Claude | `effort` in the role file | `CLAUDE_CODE_EFFORT_LEVEL` overrides the `effort` field of subagents. Aliases and the resolved provider model can clamp or ignore a level. |
+| Kimi | `models.<alias>.overrides.default_effort` | One effort for each alias. See below. |
+| Gemini | None | `--effort` and `/effort` apply to the whole session. |
+| Grok | None | Grok Build resolves subagent effort from a spawn override, a role default, a persona default and then the parent session. APK writes only a model, so subagents use the main session effort. |
+
+A known model accepts only the levels in the [model catalog](model-catalog.md). The page offers only those levels.
+
+### Kimi alias effort
+
+Kimi sets effort for each alias, not for each role. An alias is a model entry in the Kimi `config.toml`. These rules apply:
+
+- Roles that use the same alias share its effort. A pin for an alias also applies to the unpinned roles that use the same alias.
+- Selected roles that use the same alias cannot request different explicit efforts. APK refuses such input before it plans a change: a preferences file with `INVALID_POLICY`, command-line flags with `INVALID_EXPLICIT_CONFIG` and a `--config` value with `INVALID_CONFIG`. One explicit effort and `null` can share an alias.
+- Setup can resolve a missing catalog alias to an existing alias with the same upstream model. If two roles then resolve to one alias with different pinned efforts, setup returns `kimi-resolved-effort-conflict`.
+- The pinned level must be in the `support_efforts` of the alias, including its `overrides`. If not, setup returns `kimi-supported-effort-required`.
+- If thinking is off (`thinking.enabled = false`) and any effort is pinned, setup returns `kimi-thinking-disabled`.
+- If some selected aliases have a pinned effort, others are unpinned, and `secondary_model.default_effort` is set, setup returns `kimi-mixed-native-default-effort`.
+- If a pinned alias is also the main model (`default_model`) and the pin changes its default effort, setup returns `kimi-main-effort-conflict`. This refusal does not apply when `thinking.effort` sets an explicit main effort that the alias supports. Use a separate native alias for subagents, or set the main effort deliberately.
+
+For the other Kimi prerequisites, see [AI assistants](assistants.md#kimi-kimi-code).
+
+## Related documents
+
+- [Presets](presets.md): the model and effort that each preset selects for each role.
+- [Ownership and state](ownership.md): how APK records and removes role files.
+- [Architecture](../maintainers/architecture.md): how the code generates the native files.