refactor(harness): simplify model routing (#1973)
This commit is contained in:
Carlos Florêncio
@@ -1,205 +1,120 @@
|
||||
---
|
||||
name: planner-orchestration
|
||||
description: Enforce Kandev's planner-and-worker execution model. Use in the user-started primary session for feature, fix, debug, review, verification, and delivery work; use in delegated sessions to distinguish worker execution from planner coordination.
|
||||
description: Enforce Kandev's single-session, user-controlled model workflow for feature, fix, debug, review, verification, and delivery work.
|
||||
---
|
||||
|
||||
# Planner Orchestration
|
||||
# Single-Session Orchestration
|
||||
|
||||
The user-started primary session is the **planner** and default architect. A
|
||||
custom subagent launched through native delegation is a **worker**.
|
||||
The user-started primary conversation owns durable artifacts, integration
|
||||
judgment, and user communication. Platform-provided explorers and other
|
||||
predefined subagents may continue to serve the harness's normal investigation
|
||||
workflow. This skill governs planned implementation delegation, not the
|
||||
platform's general exploration behavior.
|
||||
|
||||
## Planner Contract
|
||||
## Model Checkpoints
|
||||
|
||||
The planner may:
|
||||
The user, not the harness, selects the model. Keep each phase in the primary
|
||||
conversation so the active model, transcript, and costs are visible in one place.
|
||||
|
||||
- Clarify intent and ask the user for decisions.
|
||||
- Read repository context needed to create or review a plan.
|
||||
- Create and update specs, plans, task files, and ADRs.
|
||||
- Decompose work, assign file ownership, and order dependency waves.
|
||||
- Spawn workers, monitor results, review diffs and reports, and communicate
|
||||
status to the user.
|
||||
1. **Design checkpoint — strong model.** Use the user's strong model for
|
||||
clarification, codebase investigation, specs, plans, task decomposition, and
|
||||
high-risk design decisions. Default Codex guidance is GPT-5.6 Sol/high.
|
||||
2. **Implementation checkpoint — user switch.** Once the spec, plan, and task
|
||||
files are ready, summarize their paths and ask the user to switch the main
|
||||
session to the lower-cost implementation model. Default Codex guidance is
|
||||
GPT-5.6 Terra/medium. Do not silently continue on the strong model when the
|
||||
user has asked for a cost-controlled workflow.
|
||||
3. **Execution checkpoint — lower-cost model.** In the same conversation, read
|
||||
the approved task file, mark it `in_progress`, implement with `/tdd`, run its
|
||||
exact targeted checks, and mark it `done`. Work sequentially through the
|
||||
plan by default.
|
||||
4. **Escalation checkpoint.** Stop and ask the user to switch back to a stronger
|
||||
model before an architectural redesign, a new public contract, a migration or
|
||||
persistence boundary, or a high-impact security decision. Record a durable
|
||||
decision when the `/record` trigger applies.
|
||||
|
||||
The planner may directly do small scoped work: one clear concern, a few
|
||||
localized files, no meaningful isolation/parallelism benefit, and quick bounded
|
||||
verification. This includes small code/test/harness/docs edits, focused checks,
|
||||
routine Git/GitHub steps, PR-thread triage/replies, and small PR fixups. Apply
|
||||
the relevant skill/TDD, preserve dirty-worktree safety, and use final delegated
|
||||
Spark `verify` after commit and before push for code, tests, or config. Supply
|
||||
the `/commit` hook receipt so changed-scope verification avoids only proven
|
||||
duplicate hook work.
|
||||
Luna/low is appropriate only for clearly mechanical, read-only work such as
|
||||
short status summaries or simple command-output interpretation. It is not the
|
||||
default implementation or test model. The active agent must never claim a model
|
||||
change occurred based on self-identification; use runtime model-usage metadata
|
||||
when such confirmation is needed.
|
||||
|
||||
The planner performs initial log/session inspection, call-path tracing, and
|
||||
reproduction directly. Do not delegate that first pass, waiting, or status
|
||||
relays. Delegate when ROI or independent evidence matters: broad/unknown exploration
|
||||
after local triage,
|
||||
substantial plan work, large/cross-component changes, parallel packets,
|
||||
long/noisy E2E or debugging, exceptional specialists, and final change-aware
|
||||
`verify`. Keep long monitoring with cheap `pr-poller`. Estimate context reload and
|
||||
coordination cost; delegation is not default ceremony. Reuse a worker thread
|
||||
for related followups. Architect is user-requested independent second opinion,
|
||||
not an automatic planner step.
|
||||
## Task-File Workflow
|
||||
|
||||
## Native Delegation Only
|
||||
Feature work still follows `/spec`, `/plan`, and `/spec-driven-development`:
|
||||
|
||||
Delegate through the active coding harness, targeting the registered project
|
||||
agent for the work packet:
|
||||
- Store the accepted spec in `docs/specs/<slug>/spec.md`.
|
||||
- Store `plan.md` and independently actionable sibling task files in
|
||||
`docs/plans/<slug>/`.
|
||||
- Use `pending`, `in_progress`, and `done` task-file status as the durable
|
||||
execution record. The primary agent updates both the current task and the
|
||||
plan's status after each completed task.
|
||||
- Keep task files small enough that the same conversation can resume from their
|
||||
acceptance criteria, owned files, and exact verification command after a user
|
||||
switches model.
|
||||
|
||||
- Claude Code: use the native `Agent` tool and `.claude/agents/<role>.md`.
|
||||
- Codex: use native `spawn_agent`, `send_message`/`followup_task`, and
|
||||
`wait_agent` with `.codex/agents/<role>.toml`.
|
||||
- Cursor: use Cursor's native custom-subagent invocation and
|
||||
`.cursor/agents/<role>.md`.
|
||||
- OpenCode: use the native `Task` tool and `.opencode/agents/<role>.md`.
|
||||
Task files are a model-switch handoff and, if the user explicitly asks for
|
||||
subagents, a compact work packet. They must include intent, dependencies, owned
|
||||
files, acceptance criteria, verification, and risks, but must not name an agent
|
||||
role or model tier.
|
||||
|
||||
Never use Kandev MCP `spawn_session_kandev`, `create_task_kandev`, or
|
||||
`message_task_kandev` to create or control implementation workers. Those APIs
|
||||
manage Kandev platform entities and may be used only when the user explicitly
|
||||
asks to create or manage Kandev tasks or sessions. They are not a delegation
|
||||
fallback. If native harness delegation is unavailable, stop and report it.
|
||||
## User-Authorized Subagents
|
||||
|
||||
In Codex, a registered `agent_type` is a role override. Spawn it with
|
||||
`fork_turns: "none"` or a bounded recent-turn count, never `fork_turns: "all"`.
|
||||
Put the complete work packet and the paths to read in the initial prompt so the
|
||||
worker has the context that an all-history fork would otherwise provide.
|
||||
Plans may label dependency waves and parallel-safe candidates. That is planning
|
||||
information only: execute sequentially unless the user explicitly asks to use
|
||||
subagents after selecting the implementation model.
|
||||
|
||||
## Worker Contract
|
||||
When the user authorizes subagents:
|
||||
|
||||
A worker executes exactly one bounded assignment. It follows the assigned
|
||||
execution skill, edits only its owned files (including, when applicable, only
|
||||
its assigned task file), runs the named verification, and reports results to
|
||||
the planner. Shared plan files require explicit ownership and their updates
|
||||
must be serialized, never performed by parallel workers. Workers do not spawn
|
||||
other workers or broaden their assignment.
|
||||
- Use the platform's native delegation tool, never Kandev task/session MCP APIs.
|
||||
- Do not recreate project custom-agent files or pin a different worker model.
|
||||
The child must use the active model the user selected in the primary session.
|
||||
- Use `fork_turns: "none"` (or the platform equivalent), not a full-history
|
||||
fork. Put the task-file path, owned files, acceptance criteria, exact command,
|
||||
and dependencies in the initial prompt.
|
||||
- Launch only tasks explicitly marked parallel-safe with disjoint files and no
|
||||
shared schema, migration, generated contract, lockfile, or package config.
|
||||
- Tell each child not to spawn further children. Update shared `plan.md` status
|
||||
serially in the primary session.
|
||||
- Confirm model routing from runtime usage metadata, not a model's prose. If it
|
||||
does not show the user-selected model, stop the delegation and report it.
|
||||
|
||||
## Work Packet
|
||||
If the user does not explicitly authorize delegation, do not infer permission
|
||||
from a plan's waves or parallelism labels.
|
||||
|
||||
Every delegated assignment must contain:
|
||||
The read-only `pr-poller` is a delivery exception, not an implementation
|
||||
worker. Launch it only after the user explicitly asks to wait for or monitor PR
|
||||
updates; it reports status to the primary conversation and never remediates,
|
||||
comments, or spawns children.
|
||||
|
||||
```text
|
||||
Role: <architect | implementer | test-engineer | qa | code-review | security-auditor |
|
||||
simplify | verify | pr-poller | spark-explorer | spark-implementer>
|
||||
Objective: <one bounded outcome>
|
||||
Inputs: <task/spec/plan paths and relevant context>
|
||||
Owned files: <specific paths or narrow search targets>
|
||||
Forbidden files: <overlapping or out-of-scope paths>
|
||||
Acceptance:
|
||||
- <observable condition>
|
||||
Verification:
|
||||
- <exact command>
|
||||
Dependencies: <completed task IDs or none>
|
||||
Output:
|
||||
- Follow the role's exact output contract when it defines one.
|
||||
- Otherwise: summary, files changed, commands/results, blockers, risks, divergence.
|
||||
Constraints:
|
||||
- Follow scoped AGENTS.md and assigned skills.
|
||||
- Do not spawn subagents.
|
||||
```
|
||||
## Task-Driven Validation And PR Review
|
||||
|
||||
Pass a compact **handoff capsule** to a follow-up worker instead of the parent
|
||||
transcript or pasted full specs. Include only: intent/acceptance; base and head
|
||||
SHA when applicable; changed files and entry points; named spec/ADR sections;
|
||||
risk tags; exact targeted commands/results; and uncertainties. Link the paths
|
||||
and named sections the worker must read.
|
||||
Each task file owns its TDD requirement and exact unit, integration, or E2E
|
||||
commands. Its completed status and recorded command results are the pre-PR
|
||||
evidence; do not add a second generic validation pass here.
|
||||
|
||||
Workers share a mutable checkout unless the runtime explicitly provides an
|
||||
isolated worktree. Run them sequentially by default. Parallelize only when
|
||||
their owned files do not overlap and neither worker changes shared schemas,
|
||||
generated contracts, migrations, lockfiles, package-wide configuration, or
|
||||
shared plan status. Serialize `plan.md` updates even when a work packet
|
||||
explicitly assigns shared-plan ownership.
|
||||
Do not automatically run `/simplify`, `/qa`, `/code-review`, security review,
|
||||
or broad `/verify` before opening a PR. Those duplicate the task validation and
|
||||
the two configured PR AI reviewers. Run them only when the user explicitly asks
|
||||
or an actionable PR/CI finding requires a focused remediation.
|
||||
|
||||
## Model Tiers
|
||||
After the PR opens, the two configured AI reviewers are the semantic-review
|
||||
gate. Use `/pr-fixup` only to address a CI failure or actionable reviewer
|
||||
finding. A remediation reruns its relevant task-defined checks, not a broad
|
||||
local suite unless explicitly requested.
|
||||
Treat the OpenCode App as trusted semantic evidence only when `trusted_producer=true` confirms its dedicated producer provenance.
|
||||
|
||||
The planner inherits the strong model selected by the user. Platform mirrors
|
||||
pin workers by role:
|
||||
## Guardrails
|
||||
|
||||
- Balanced workers: implementation, tests, QA, simplification.
|
||||
- Cheap workers: polling, including Codex `pr-poller` on Luna/low.
|
||||
- Codex `verify` is pinned to GPT-5.3-Codex-Spark/medium for deterministic
|
||||
mechanical verification; this uses Spark's separate quota while
|
||||
`pr-poller` remains the cheap polling role.
|
||||
- Frontier workers: architecture, security, and deep code review only.
|
||||
- Spark is a Codex-only, opt-in specialist tier: use `spark-explorer` for
|
||||
bounded read-only evidence gathering and `spark-implementer` only for
|
||||
explicit, localized low-risk UI or code edits. It does not replace the
|
||||
balanced, frontier, or cheap tiers outside the Codex `verify` exception, and
|
||||
is not for polling, architecture, security, or deep review.
|
||||
|
||||
Do not omit a worker model when omission inherits the planner's model, except
|
||||
for OpenCode where this repository intentionally keeps provider choice
|
||||
inherited.
|
||||
|
||||
## Evidence, Risk Routing, And Completion
|
||||
|
||||
The planner derives risk tags from the union of worker reports and its own
|
||||
inspection. Use `localized`, `user-flow`, `integration`, `public-contract`,
|
||||
`persistence`, `concurrency`, `security`, and `architecture`. An uncertainty
|
||||
uses the stronger applicable gate.
|
||||
|
||||
| Evidence or risk | Required route |
|
||||
| --- | --- |
|
||||
| Routine work, including ordinary integration with faithful targeted tests | Qualifying PR AI semantic evidence and final `verify` when PR delivery is in scope. |
|
||||
| Unusually large/complex multi-component behavior or an important integration boundary lacking faithful tests | Add `qa`, semantic evidence, and final `verify`. |
|
||||
| Unusually large/complex/cross-cutting architecture; terminal readiness cannot wait for contradictory or repeatedly unavailable PR evidence; explicit request; or a deep automated-review gap | Add local frontier `code-review`. |
|
||||
| High-impact new/changed authz, workspace-isolation, secrets, untrusted-execution, or credential-trust boundary; explicit request; or concrete automated security concern | Add `security-auditor`, applicable review/QA, and final `verify`. |
|
||||
|
||||
When PR delivery is in scope, one qualifying automated AI PR review is the
|
||||
default semantic evidence; defer routine local `code-review` until that review.
|
||||
Use local review only for the exceptional routes above. A qualifying review names the
|
||||
selected/configured reviewer; has known, complete review and head evidence with
|
||||
matching PR-view checks/opening/closing SHA and a complete check snapshot; has
|
||||
an API review `commit_id` exactly equal to the stable evidence head (timestamps
|
||||
never prove head coverage); is an APPROVED
|
||||
review without a blocker signal or a COMMENTED review with the explicit
|
||||
`<!-- kandev-review: clean -->` terminal marker; covers changed code and tests;
|
||||
for the configured dedicated `${OPENCODE_REVIEW_APP_SLUG}[bot]` OpenCode App, require emitted `trusted_producer=true` on that COMMENTED exact-head record; its raw predicate binds the dedicated-App marker and fixed workflow/run-attempt API, and displayed check names never qualify, so unrelated Actions reviews cannot qualify;
|
||||
other explicitly selected reviewers retain the generic exact-head eligibility and blocker gates without App provenance;
|
||||
and has no active `CHANGES_REQUESTED`, unresolved blocker, actionable review
|
||||
thread, or blocked exact-current-head review from any author. Dismissed,
|
||||
pending, unknown, blocked, or ambiguous commented reviews never qualify; nor
|
||||
does arbitrary bot prose. Do not wait for every configured bot, but do not
|
||||
ignore any actionable finding that has arrived. A head change makes prior PR
|
||||
review stale. Without PR delivery, use local review only when semantic review
|
||||
is needed by the exceptional routes above.
|
||||
|
||||
`qa` is exceptional, not a consequence of an ordinary integration tag. Use it
|
||||
only for unusually large/complex multi-component behavior or important
|
||||
integration behavior without faithful tests. A routine fix preserving an
|
||||
existing security boundary does not require `security-auditor`.
|
||||
|
||||
The planner accepts a worker result only after checking that its file scope,
|
||||
acceptance criteria, and reported verification match the assignment. Any
|
||||
follow-up remains a bounded worker assignment, not planner execution. Reuse
|
||||
the same native agent thread for remediation or re-review when role, change,
|
||||
and file scope remain materially the same. Spawn a fresh thread after a major
|
||||
redesign, unrelated scope, stale/noisy context, or when independent judgment
|
||||
is specifically needed.
|
||||
|
||||
The planner's acceptance check is not a substitute for a required quality
|
||||
gate. Keep responsibilities separate:
|
||||
|
||||
- The planner checks assignment scope, acceptance criteria, and evidence.
|
||||
- `code-review` or qualifying PR AI evidence performs semantic diff review.
|
||||
- `qa` challenges integrated behavior and edge cases when risk requires it.
|
||||
- `verify` mechanically runs required uncovered format, typecheck, test, and
|
||||
lint commands on the committed artifact; eligible hook evidence may replace
|
||||
exact changed-file format/lint duplicates only.
|
||||
|
||||
For every final remediation affecting code, tests, or config, commit first,
|
||||
then final `verify` before push. A small, scope-preserving PR remediation uses
|
||||
the reviewer
|
||||
finding, focused tests, final Spark `verify`, and fresh qualifying exact-head
|
||||
automated review; it almost never relaunches QA, code-review, or
|
||||
security-auditor just because original tags remain. Relaunch one only if the
|
||||
fix becomes large/complex, changes a contract or trust boundary, invalidates
|
||||
prior evidence, or exposes a gap that gate must assess. A bug fix preserving
|
||||
an existing ADR or invariant is not by itself a new boundary. Simplification,
|
||||
when used, happens before semantic review so its edits are covered.
|
||||
|
||||
When a final verifier is silent after two normal status waits, inspect the
|
||||
worker state and its owned command/process group before waiting again. If no
|
||||
command remains, interrupt that same worker once to retrieve its buffered
|
||||
completion report; do not replace it. Start another verifier only after the
|
||||
first is confirmed stopped and did not produce a usable exact-artifact result.
|
||||
If liveness cannot be established, report verification blocked. This recovers
|
||||
completed reports without paying for duplicate full suites.
|
||||
- Do not treat a plan wave as authorization to launch implementation workers;
|
||||
that decision remains with the user. This does not restrict platform-provided
|
||||
explorers or other harness-managed investigation agents.
|
||||
- Do not use Kandev MCP task/session APIs as a worker mechanism. Use them only
|
||||
when the user explicitly asks to manage persistent Kandev tasks or sessions.
|
||||
- Do not create worktrees solely to parallelize plan tasks unless the user has
|
||||
explicitly authorized subagents for parallel-safe tasks.
|
||||
- Do not continue past a model checkpoint by assuming the user accepted the
|
||||
cost. State the recommended switch and wait when the choice materially
|
||||
affects cost or quality.
|
||||
- Do not replace durable specs, plans, task files, tests, or verification with
|
||||
chat-only summaries.
|
||||
|
||||
Reference in New Issue
Block a user