From 995b60fb907a46d782c4182a2624dedfd6738c12 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 31 Oct 2026 10:40:54 -0400 Subject: [PATCH] docs(planning): anchor upstream pointers and label judgment Add section anchors, as-of dates and recheck triggers to the workflow, teammate and maxTurns claims, and mark the advisor default and the upload reader's model pin as this repository's own judgment. Refs: #6916 Co-Authored-By: Claude Opus 5.5 --- .changes/planning/fix-6916-upstream-pointers-b7e20d16.md | 7 +++++++ plugins/planning/agents/plan-reviewer.md | 2 +- plugins/planning/agents/upload-reader.md | 4 ++-- plugins/planning/skills/draft-goal-condition/SKILL.md | 9 +++++++-- .../planning/skills/interview/context/session-config.md | 8 ++++---- plugins/planning/skills/plan/SKILL.md | 4 ++-- 6 files changed, 23 insertions(+), 11 deletions(-) create mode 100644 .changes/planning/fix-6916-upstream-pointers-b7e20d16.md diff --git a/.changes/planning/fix-6916-upstream-pointers-b7e20d16.md b/.changes/planning/fix-6916-upstream-pointers-b7e20d16.md new file mode 100644 index 00000000000..341c72eaca7 --- /dev/null +++ b/.changes/planning/fix-6916-upstream-pointers-b7e20d16.md @@ -0,0 +1,7 @@ +--- +bump: patch +--- + +### Fixed + +- `/planning:plan`, `/planning:draft-goal-condition` and `/planning:interview` point at the exact upstream sections behind their workflow, teammate and advisor claims, and the advisor default and the upload reader's model pin are labeled as this repository's judgment. diff --git a/plugins/planning/agents/plan-reviewer.md b/plugins/planning/agents/plan-reviewer.md index 53b820a92d0..955bb7adc89 100644 --- a/plugins/planning/agents/plan-reviewer.md +++ b/plugins/planning/agents/plan-reviewer.md @@ -40,7 +40,7 @@ dispatch. **Verification.** Claim: `maxTurns: 25` in this agent definition takes effect for a plugin agent; at the limit the subagent stops and Claude Code returns its output marked partial, which Claude can -resume. Basis: https://code.claude.com/docs/en/sub-agents, whose `maxTurns` frontmatter row reads +resume. Basis: https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields, whose `maxTurns` row reads "Maximum number of agentic turns before the subagent stops" and says the partial marking requires Claude Code v2.1.246 or later, and whose plugin-agents note lists only `hooks`, `mcpServers` and `permissionMode` as ignored, so `maxTurns` and `effort` are honored. As-of: 2026-09-29. Recheck when diff --git a/plugins/planning/agents/upload-reader.md b/plugins/planning/agents/upload-reader.md index c245c24f478..441b36de2d0 100644 --- a/plugins/planning/agents/upload-reader.md +++ b/plugins/planning/agents/upload-reader.md @@ -36,8 +36,8 @@ or "none"> Not read: ``` -**Model and effort.** `opus` keeps the reader at least as strong as the text trying to steer it; -`medium` bounds one file's read. The Read-only cage is what contains an obeyed plant; this framing +**Model and effort.** We chose `opus` so the reader holds up against text trying to steer it, and +`medium` to bound one file's read; no upstream page sets either. The Read-only cage is what contains an obeyed plant; this framing is what keeps it from being obeyed. - **Pointer:** for how a `tools` list withholds tools from a subagent, see diff --git a/plugins/planning/skills/draft-goal-condition/SKILL.md b/plugins/planning/skills/draft-goal-condition/SKILL.md index 56dbf00ad99..2853435f642 100644 --- a/plugins/planning/skills/draft-goal-condition/SKILL.md +++ b/plugins/planning/skills/draft-goal-condition/SKILL.md @@ -49,7 +49,9 @@ see the result. When either is missing, prompt once instead. - **Custom per-turn logic across all sessions** (deterministic script check, settings-scoped) → a prompt-based Stop hook. - **More agents than one conversation can coordinate** (or orchestration worth codifying as a - rerunnable script) → a dynamic workflow. This row composes with `/goal`: the workflow does the + rerunnable script; for the scale each approach fits, see + [When to use a workflow](https://code.claude.com/docs/en/workflows#when-to-use-a-workflow), as of + 2026-10-31; recheck when that section's comparison table changes) → a dynamic workflow. This row composes with `/goal`: the workflow does the parallel work, the goal sets the hard completion requirement. Route away from drafting only when the intent wants the fan-out and *no* across-turn completion condition; when it wants both, draft the condition here and say the workflow rides alongside it. @@ -77,7 +79,10 @@ Two caveats on the workflow row, each of which turns a plausible recommendation workflow lever reaches all paid plans (on Pro it is switched on from the **Dynamic workflows** row in `/config`), while the standing setting needs a model that offers `xhigh` effort. - **The lever is unreachable from an ordinary subagent.** The `Workflow` tool is filtered out of - every non-fork subagent (the filter is on `https://code.claude.com/docs/en/sub-agents`; + every non-fork subagent (the filter is in + [sub-agents: available tools](https://code.claude.com/docs/en/sub-agents#available-tools), as of + 2026-10-31; recheck when `Workflow` leaves that list or a fork stops keeping the main session's + tools; `/discovery:research`, if enabled, selects its workflow-backed deep tier only in the main conversation for this reason). A lever whose work lands in dispatched non-fork subagents (the loop lanes' workers, for instance) cannot be the workflow row; recommend it only where the diff --git a/plugins/planning/skills/interview/context/session-config.md b/plugins/planning/skills/interview/context/session-config.md index 6c785f5f87c..d482a2deb70 100644 --- a/plugins/planning/skills/interview/context/session-config.md +++ b/plugins/planning/skills/interview/context/session-config.md @@ -64,8 +64,8 @@ be read, say so, cite the URL, and recommend no level for either phase. ## Advisor pairing -For non-trivial work this skill does not recommend a faster main model running -**without** a stronger advisor: it recommends the faster main model paired with a +As this skill's own judgment, for non-trivial work it does not recommend a faster main model +running **without** a stronger advisor: it recommends the faster main model paired with a stronger advisor that the main model escalates hard decisions to, rather than paying for the stronger model on every routine turn (for when the advisor is consulted, see , as of 2026-10-11; @@ -86,8 +86,8 @@ Two cautions apply before recommending a pairing: - **Pointer**: for both cautions, see - and, for the baseline, . -- **As of**: 2026-10-10 + and, for the baseline, . +- **As of**: 2026-10-31 - **Recheck trigger**: either section is renamed, moved, or stops covering advisor engagement or the stronger-model-alone baseline. diff --git a/plugins/planning/skills/plan/SKILL.md b/plugins/planning/skills/plan/SKILL.md index 1cf7c4ee2e5..b5cdd59d6ea 100644 --- a/plugins/planning/skills/plan/SKILL.md +++ b/plugins/planning/skills/plan/SKILL.md @@ -63,7 +63,7 @@ These hold after a compaction re-attach. Later steps say how to carry them out. - **Reviewer.** Before assessing blast radius, dispatch a fresh-context plan-reviewer sub-agent for any plan you present. The producing thread does not self-attack the plan inline. A change skipped under the one-sentence rule (Purpose) has no plan to review. - **Hard-to-reverse decisions escalate EARLY** regardless of confidence. Below-bar judgment calls go to an interview round before the plan locks. -- **Agent teams.** Route a phase to an agent team only when the parallel-safe workers must message each other and agent teams are enabled; otherwise use sub-agent workers or sequential. Teammates are not worktree-isolated, so disjoint file ownership is mandatory. +- **Agent teams.** Route a phase to an agent team only when the parallel-safe workers must message each other and agent teams are enabled; otherwise use sub-agent workers or sequential. Teammates are not worktree-isolated, so disjoint file ownership is mandatory; for why, see [agent teams: avoid file conflicts](https://code.claude.com/docs/en/agent-teams#avoid-file-conflicts) (as of 2026-10-31; recheck when that section changes how teammates share files). ### Step 4.7: Outcome gate (before Step 5. Verify the PLAN, not a recap) @@ -226,7 +226,7 @@ Apply the reviewer rule under Planning Process before blast radius or presentati 1. Gather the plan draft + design artifacts (or `design-resolution.md`) + the Brief 2. **Surface the cost.** Tell the user, in one sentence, that a fresh-context plan review runs now whatever they answer: one bounded sub-agent (default `effort: medium`, capped turns). -3. Dispatch the plugin's **`plan-reviewer`** agent (`agents/plan-reviewer.md`) with the prompt from [context/plan-reviewer.md](context/plan-reviewer.md). Do not substitute a generic read-only sub-agent, and pass no `effort` on the call: the agent definition carries the reviewer's bounded `effort` and `maxTurns` (the effort record in `agents/plan-reviewer.md`). A complete report ends with its `### Summary` counts, or is the literal `No plan gaps found.` for a clean pass; treat any other return as incomplete whether or not a partial marker is present (older clients do not mark a `maxTurns` stop): resume it (or re-dispatch with a narrowed brief); never treat a partial table as a clean pass. +3. Dispatch the plugin's **`plan-reviewer`** agent (`agents/plan-reviewer.md`) with the prompt from [context/plan-reviewer.md](context/plan-reviewer.md). Do not substitute a generic read-only sub-agent, and pass no `effort` on the call: the agent definition carries the reviewer's bounded `effort` and `maxTurns` (the effort record in `agents/plan-reviewer.md`). A complete report ends with its `### Summary` counts, or is the literal `No plan gaps found.` for a clean pass; treat any other return as incomplete whether or not a partial marker is present (whether a `maxTurns` stop is marked depends on the client: the `maxTurns` record in `agents/plan-reviewer.md`): resume it (or re-dispatch with a narrowed brief); never treat a partial table as a clean pass. 4. **Verify reviewer findings** against the actual code/files before applying fixes. Sub-agent findings are synthesis, not ground truth 5. Fix every confirmed gap BEFORE proceeding; never present a plan with known gaps. A fix that displaces a user answer or adds an external effect follows "Plan changes after the Brief" below