docs(planning): anchor upstream pointers and label judgment

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

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

plugins/planning/agents/upload-reader.md

@@ -36,8 +36,8 @@ or "none">
 Not read: <anything skipped and why; or "nothing">
 ```
 
-**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

plugins/planning/skills/draft-goal-condition/SKILL.md

@@ -50,7 +50,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.
@@ -78,7 +80,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

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
 <https://code.claude.com/docs/en/advisor#when-claude-consults-the-advisor>, as of 2026-10-11;
@@ -86,8 +86,8 @@ Two cautions apply before recommending a pairing:
 
 - **Pointer**: for both cautions, see
   <https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#advisor-strategy-escalate-hard-decisions>
-  and, for the baseline, <https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#choose-between-the-strategies>.
-- **As of**: 2026-10-10
+  and, for the baseline, <https://platform.claude.com/docs/en/about-claude/models/optimizing-for-cost-and-intelligence#combine-models>.
+- **As of**: 2026-10-31
 - **Recheck trigger**: either section is renamed, moved, or stops covering advisor engagement
   or the stronger-model-alone baseline.
 

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