docs: clarify workflow-driven subagents

Author: gaelic-ghost

plugins/productivity-skills/docs/maintainers/codex-subagent-guidance.md

@@ -41,7 +41,7 @@ Use wording like this in applicable skills:
 ```markdown
 ## Codex Subagent Fit
 
-When subagents are explicitly requested or clearly called for by applicable workflow guidance, this skill can split read-heavy discovery into bounded subagent tasks and keep the main thread focused on decisions and final edits.
+When subagents are explicitly requested, or applicable workflow guidance tells the agent to ask and the user allows it, this skill can split read-heavy discovery into bounded subagent tasks and keep the main thread focused on decisions and final edits.
 
 Good subagent jobs for this skill:
 

plugins/productivity-skills/skills/explain-code-slice/SKILL.md

@@ -93,9 +93,9 @@ Treat comparison requests as first-class trigger cases, not as an advanced follo
 
 ## Codex subagent fit
 
-When subagents are explicitly requested or clearly called for by applicable workflow guidance, this skill can split read-heavy discovery for large code slices into bounded subagent tasks. Good subagent jobs include mapping call sites, reading tests, checking docs, or tracing one branch of a comparison, with each worker returning concise file references and findings.
+When subagents are explicitly requested, or applicable workflow guidance tells the agent to ask and the user allows it, this skill can split read-heavy discovery for large code slices into bounded subagent tasks. Good subagent jobs include mapping call sites, reading tests, checking docs, or tracing one branch of a comparison, with each worker returning concise file references and findings.
 
-Do not spawn subagents just because a slice is large. Use them when the request or applicable workflow guidance makes delegation part of the job. Keep the final explanation in the main thread so the user gets one coherent walkthrough, and keep any write or refactor follow-up outside this skill unless the user asks for that next step.
+Do not spawn subagents just because a slice is large. Use them when the request explicitly asks for delegation or applicable workflow guidance tells the agent to ask and the user allows it. Keep the final explanation in the main thread so the user gets one coherent walkthrough, and keep any write or refactor follow-up outside this skill unless the user asks for that next step.
 
 ## Detail levels
 

plugins/productivity-skills/skills/maintain-project-accessibility/SKILL.md

@@ -56,7 +56,7 @@ The base contract requires:
 
 ## Codex Subagent Fit
 
-When subagents are explicitly requested or clearly called for by applicable workflow guidance, use them for read-heavy accessibility evidence gathering before the main workflow edits or reports. Good jobs include checking documented verification commands, inventorying UI surfaces, reading known-gap notes, or comparing accessibility claims against repo evidence.
+When subagents are explicitly requested, or applicable workflow guidance tells the agent to ask and the user allows it, use them for read-heavy accessibility evidence gathering before the main workflow edits or reports. Good jobs include checking documented verification commands, inventorying UI surfaces, reading known-gap notes, or comparing accessibility claims against repo evidence.
 
 Keep `apply` edits in the main thread because this skill owns one target `ACCESSIBILITY.md` file and must avoid unsupported compliance claims. Ask workers for concise evidence, risks, and file references rather than drafted conformance language.
 

plugins/productivity-skills/skills/maintain-project-agents/SKILL.md

@@ -61,7 +61,7 @@ The base contract is shaped to match the official Codex `AGENTS.md` guidance:
 
 ## Codex Subagent Fit
 
-When subagents are explicitly requested or clearly called for by applicable workflow guidance, use them for bounded read-heavy checks before the main workflow edits or reports. Good jobs include auditing command accuracy, comparing repo instructions against nearby docs, checking safety boundaries, or reading nested guidance files in separate directories.
+When subagents are explicitly requested, or applicable workflow guidance tells the agent to ask and the user allows it, use them for bounded read-heavy checks before the main workflow edits or reports. Good jobs include auditing command accuracy, comparing repo instructions against nearby docs, checking safety boundaries, or reading nested guidance files in separate directories.
 
 Keep `apply` edits in the main thread because this skill owns one target `AGENTS.md` file and needs one coherent policy voice. If a target `AGENTS.md` mentions subagents, make the wording match OpenAI's current Codex rule: subagents need an explicit trigger, are best for bounded parallel discovery, tests, triage, and summarization, and may be called for by narrower plugin guidance that tells the agent to ask before delegation.
 

plugins/productivity-skills/skills/maintain-project-api/SKILL.md

@@ -52,7 +52,7 @@ The base contract requires:
 
 ## Codex Subagent Fit
 
-When subagents are explicitly requested or clearly called for by applicable workflow guidance, use them for read-heavy API evidence gathering before the main workflow edits or reports. Good jobs include inventorying endpoints or public symbols, checking examples against tests, reading schema definitions, or comparing compatibility claims against release notes.
+When subagents are explicitly requested, or applicable workflow guidance tells the agent to ask and the user allows it, use them for read-heavy API evidence gathering before the main workflow edits or reports. Good jobs include inventorying endpoints or public symbols, checking examples against tests, reading schema definitions, or comparing compatibility claims against release notes.
 
 Keep `apply` edits in the main thread because this skill owns one target `API.md` file and must avoid invented endpoints, schemas, credentials, or support promises. Ask workers for concise evidence and file references instead of replacement API prose.
 

plugins/productivity-skills/skills/maintain-project-architecture/SKILL.md

@@ -71,7 +71,7 @@ When the user asks for a new slice explanation, use `explain-code-slice` for the
 
 ## Codex Subagent Fit
 
-When subagents are explicitly requested or clearly called for by applicable workflow guidance, use them for read-heavy discovery. Good jobs include scanning package manifests, listing products and targets, finding entrypoints, or tracing one candidate slice. Keep writes to `ARCHITECTURE.md`, `SLICES.md`, and `architecture.json` in the main thread so the architecture story stays coherent.
+When subagents are explicitly requested, or applicable workflow guidance tells the agent to ask and the user allows it, use them for read-heavy discovery. Good jobs include scanning package manifests, listing products and targets, finding entrypoints, or tracing one candidate slice. Keep writes to `ARCHITECTURE.md`, `SLICES.md`, and `architecture.json` in the main thread so the architecture story stays coherent.
 
 ## Output Contract
 

plugins/productivity-skills/skills/maintain-project-contributing/SKILL.md

@@ -54,7 +54,7 @@ The base contract requires:
 
 ## Codex Subagent Fit
 
-When subagents are explicitly requested or clearly called for by applicable workflow guidance, use them for read-heavy contribution-guide discovery before the main workflow edits or reports. Good jobs include checking setup commands, comparing PR expectations against repo policy, reading workflow docs, or verifying contributor-facing tool requirements.
+When subagents are explicitly requested, or applicable workflow guidance tells the agent to ask and the user allows it, use them for read-heavy contribution-guide discovery before the main workflow edits or reports. Good jobs include checking setup commands, comparing PR expectations against repo policy, reading workflow docs, or verifying contributor-facing tool requirements.
 
 Keep `apply` edits in the main thread because this skill owns one target `CONTRIBUTING.md` file and needs one coherent contributor contract. Ask workers for concise evidence and file references, not replacement guide prose.
 

plugins/productivity-skills/skills/maintain-project-readme/SKILL.md

@@ -46,7 +46,7 @@ This skill is the primary layer for README maintenance. It defines the canonical
 
 ## Codex Subagent Fit
 
-When subagents are explicitly requested or clearly called for by applicable workflow guidance, use them for read-heavy README discovery before the main workflow edits or reports. Good jobs include checking source docs, inventorying commands, inspecting sibling package metadata, or comparing README claims against one upstream source per worker.
+When subagents are explicitly requested, or applicable workflow guidance tells the agent to ask and the user allows it, use them for read-heavy README discovery before the main workflow edits or reports. Good jobs include checking source docs, inventorying commands, inspecting sibling package metadata, or comparing README claims against one upstream source per worker.
 
 Keep `apply` edits in the main thread because this skill has one target file and a hard-enforced schema. Ask subagents to return concise evidence and file references, not replacement README prose.
 

plugins/productivity-skills/skills/maintain-project-repo/SKILL.md

@@ -113,7 +113,7 @@ Install or refresh the reusable `maintain-project-repo` toolkit inside a general
 
 ## Codex Subagent Fit
 
-When subagents are explicitly requested or clearly called for by applicable workflow guidance, use them for read-heavy repo-maintenance discovery before the main workflow installs, refreshes, or reports. Good jobs include inspecting existing validation scripts, checking CI wrapper shape, reading release docs, or inventorying repo-specific commands in separate directories.
+When subagents are explicitly requested, or applicable workflow guidance tells the agent to ask and the user allows it, use them for read-heavy repo-maintenance discovery before the main workflow installs, refreshes, or reports. Good jobs include inspecting existing validation scripts, checking CI wrapper shape, reading release docs, or inventorying repo-specific commands in separate directories.
 
 Keep managed file installation, refresh, and release guidance in the main thread unless the user explicitly requests parallel implementation with disjoint write scopes. Subagents should return concise findings and file references so the main thread can make one coherent decision about the managed toolkit.
 

plugins/productivity-skills/skills/maintain-project-roadmap/SKILL.md

@@ -40,7 +40,7 @@ This skill is the general template layer for roadmap maintenance. It defines the
 
 ## Codex Subagent Fit
 
-When subagents are explicitly requested or clearly called for by applicable workflow guidance, use them for read-heavy roadmap discovery before the main workflow edits or reports. Good jobs include checking one milestone family per worker, comparing roadmap claims against release notes, or gathering evidence from docs and issues for backlog triage.
+When subagents are explicitly requested, or applicable workflow guidance tells the agent to ask and the user allows it, use them for read-heavy roadmap discovery before the main workflow edits or reports. Good jobs include checking one milestone family per worker, comparing roadmap claims against release notes, or gathering evidence from docs and issues for backlog triage.
 
 Keep `apply` edits in the main thread because this skill owns one target roadmap and must preserve one coherent planning structure. Ask workers for concise findings, candidate changes, and references instead of direct roadmap rewrites.