planner-orchestration

name	planner-orchestration
description	Enforce Kandev's single-session, user-controlled model workflow for feature, fix, debug, review, verification, and delivery work.

Single-Session Orchestration

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.

Model Checkpoints

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.

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. Design-package handoff. Once the spec, plan, and task files are ready, summarize their paths and end the turn. Do not call ask_user_question_kandev (or an equivalent approval prompt) to ask the user to approve the package or switch models. The user reviews the files, switches the main session if desired, and sends a later explicit implementation request. The files may remain draft/pending; do not wait for a separate approval marker.
3. Execution checkpoint. After that explicit request, read the 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. The user, not the harness, chooses the active implementation model.
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.

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.

Task-File Workflow

Feature work still follows /spec, /plan, and /spec-driven-development:

• 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.

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.

User-Authorized Subagents

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.

When the user authorizes subagents:

• 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.

If the user does not explicitly authorize delegation, do not infer permission from a plan's waves or parallelism labels.

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.

Task-Driven Validation And PR Review

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.

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.

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.

Guardrails

• 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 from the design-package handoff automatically or treat artifact creation as implementation authorization. Wait for a later explicit implementation request; the user controls any model switch between turns.
• Do not replace durable specs, plans, task files, tests, or verification with chat-only summaries.