docs: loosen subagent guidance

Author: gaelic-ghost

ROADMAP.md

@@ -77,6 +77,7 @@ In Progress
 - Added root `docs/media` screenshot assets and README media guidance so the Codex plugin-directory catalog surface is visible without weakening text-first documentation.
 - Added coordinated OpenAI Codex Hooks guidance across `agent-plugin-skills` and `productivity-skills`, with future `maintain-project-hooks` work tracked in the productivity roadmap.
 - Updated `socket` and plugin guidance so ordinary user installs and updates default to Git-backed Codex marketplace sources and official marketplace add/upgrade commands.
+- Loosened coordinated Codex subagent guidance so skills preserve OpenAI's explicit-trigger model while allowing narrower workflow guidance, such as Codex Security repository-wide scans, to ask for and use subagents when the task depends on parallel file-pass review.
 - Added coordinated Codex subagent guidance across `agent-plugin-skills` and `productivity-skills`, grounding skill wording in OpenAI's current explicit-trigger `subagents` model while keeping the root docs clear about why the pass belongs in `socket`.
 - Prepared the `v6.1.0` minor release by adding the `maintain-project-api` productivity skill and keeping the monorepo-owned child docs, tests, and shared version surfaces aligned.
 - Added explicit `standard` and `subtrees` release-mode guidance, including the pull-only `SpeakSwiftlyServer` rule for `socket` subtree sync.

plugins/agent-plugin-skills/docs/maintainers/codex-subagent-skill-guidance.md

@@ -10,7 +10,7 @@ OpenAI's Codex docs call this feature `subagents`.
 
 - A `subagent` is a delegated agent that Codex starts to handle a specific task.
 - A `subagent workflow` is a workflow where Codex runs parallel agents and combines their results.
-- Codex only spawns subagents when the user explicitly asks for subagents or parallel agent work.
+- Codex only spawns subagents when there is an explicit trigger: the user asks for subagents or parallel agent work, or a narrower skill/plugin workflow instructs the agent to ask for and use subagents when the task clearly depends on them.
 - Subagents are best for bounded read-heavy discovery, tests, triage, log analysis, and summarization.
 - Write-heavy parallel work needs clear ownership because multiple agents editing code or docs at once can create conflicts and coordination overhead.
 
@@ -37,18 +37,19 @@ Weak candidates:
 
 When a skill includes a `Codex Subagent Fit` section, it should say:
 
-- subagents require an explicit user request
+- subagents require an explicit trigger, either from the user's request or from narrower workflow guidance that tells the agent to request permission before delegation
 - the subagent jobs must be bounded and independently useful
 - read-heavy discovery, triage, tests, docs pulling, and summarization are the default fit
 - workers should return concise evidence, findings, links, or file references instead of raw command logs
 - apply-mode or implementation edits should stay in the main thread unless the user asks for parallel implementation and each worker has a disjoint write scope
+- plugin-specific guidance can be stricter; for example, Codex Security repository-wide scans may require asking for subagent use because the scan quality depends on parallel file-pass review
 
 ## Review Checklist
 
 When auditing a skills repo, flag guidance that:
 
 - says or implies Codex will spawn subagents automatically
-- tells agents to delegate merely because a task is complex or lengthy
+- tells agents to delegate merely because a task is complex or lengthy, without a concrete workflow reason
 - recommends parallel writes without separate file ownership
 - hides token, latency, or coordination costs
 - asks subagents to dump raw exploratory output instead of distilled results

plugins/agent-plugin-skills/skills/bootstrap-skills-plugin-repo/SKILL.md

@@ -35,10 +35,11 @@ When creating or aligning `AGENTS.md`, include strict dependency guidance:
 
 When creating or aligning skills that can benefit from parallel support work, add optional `Codex Subagent Fit` guidance that matches OpenAI's current Codex subagent docs:
 
-- Codex only spawns subagents when the user explicitly asks for subagents or parallel agent work.
+- Codex only spawns subagents when there is an explicit trigger: the user asks for subagents or parallel agent work, or a narrower skill/plugin workflow instructs the agent to ask for and use subagents when the task clearly depends on them.
 - Good fits are bounded read-heavy discovery, docs pulling, tests, triage, log analysis, and summarization.
 - Subagents should return concise findings, evidence, links, or file references instead of raw intermediate output.
 - Apply-mode or implementation edits should stay in the main thread unless the user explicitly asks for parallel implementation and each worker has a disjoint write scope.
+- Plugin-specific guidance can be stricter. For example, Codex Security repository-wide scans may require asking for subagent use because the scan quality depends on parallel file-pass review.
 
 Do not add subagent guidance to every skill by default. Use `docs/maintainers/codex-subagent-skill-guidance.md` to decide whether the target skill has real parallelizable support work.
 

plugins/agent-plugin-skills/skills/sync-skills-repo-guidance/SKILL.md

@@ -62,12 +62,13 @@ When syncing `AGENTS.md`, include strict dependency guidance:
 When auditing target skills, treat subagent guidance as useful only when it is explicit, bounded, and tied to real parallel support work. Match OpenAI's current Codex wording:
 
 - use `subagent` and `subagent workflow` rather than vague older `multi-agent` language
-- say Codex only spawns subagents when the user explicitly asks for subagents or parallel agent work
+- say Codex only spawns subagents when there is an explicit trigger: the user asks for subagents or parallel agent work, or a narrower skill/plugin workflow instructs the agent to ask for and use subagents when the task clearly depends on them
 - prefer subagents for read-heavy discovery, docs pulling, tests, triage, log analysis, and summarization
 - ask workers for concise findings, evidence, links, or file references instead of raw intermediate output
 - keep write-heavy apply work in the main thread unless the user explicitly requests parallel implementation with disjoint write scopes
+- preserve plugin-specific guidance that is stricter about subagent use, such as Codex Security repository-wide scan workflows that ask for subagents because the file-pass review depends on parallel workers
 
-Flag skill guidance that implies automatic delegation, recommends parallel writes without ownership boundaries, or adds subagent advice to narrow single-file or sequential workflows.
+Flag skill guidance that implies automatic delegation, recommends parallel writes without ownership boundaries, adds subagent advice to narrow single-file or sequential workflows, or suppresses narrower plugin guidance that explicitly calls for subagents.
 
 ## Codex Hooks Guidance
 

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

@@ -8,7 +8,7 @@ This is a maintainer-focused translation of the official Codex subagent docs for
 
 OpenAI's Codex docs use the term `subagent` for a delegated agent Codex starts to handle a specific task. A `subagent workflow` is a workflow where Codex runs parallel agents and combines their results.
 
-Codex only spawns subagents when the user explicitly asks for subagents or parallel agent work. Do not write skill guidance that implies subagents start automatically just because a skill is active.
+Codex only spawns subagents when there is an explicit trigger: the user asks for subagents or parallel agent work, or a narrower skill/plugin workflow instructs the agent to ask for and use subagents when the task clearly depends on them. Do not write skill guidance that implies subagents start automatically just because a skill is active.
 
 ## Good Fits
 
@@ -32,7 +32,7 @@ Poor fits include:
 - one focused README, AGENTS, ROADMAP, CONTRIBUTING, ACCESSIBILITY, or API apply pass
 - write-heavy parallel edits to the same files or same tightly coupled document set
 - tasks where the main agent needs each result immediately before it can choose the next step
-- prompts where the user did not explicitly ask for subagents, delegation, or parallel agent work
+- prompts where neither the user nor applicable workflow guidance explicitly calls for subagents, delegation, or parallel agent work
 
 ## Skill Wording Pattern
 
@@ -41,7 +41,7 @@ Use wording like this in applicable skills:
 ```markdown
 ## Codex Subagent Fit
 
-When the user explicitly asks for subagents or parallel agent work, 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 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.
 
 Good subagent jobs for this skill:
 
@@ -54,7 +54,7 @@ Keep apply-mode edits in the main thread unless the user explicitly asks for par
 
 The important parts are:
 
-- name that the user must ask explicitly
+- name the explicit trigger for delegation, whether it came from the user or from narrower workflow guidance that tells the agent to ask before use
 - limit subagents to bounded jobs
 - prefer read-heavy discovery, triage, tests, and summarization
 - ask workers for summaries, findings, and file references instead of raw intermediate output

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 the user explicitly asks for subagents or parallel agent work, 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 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.
 
-Do not spawn subagents just because a slice is large. 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 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.
 
 ## Detail levels
 

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

@@ -56,7 +56,7 @@ The base contract requires:
 
 ## Codex Subagent Fit
 
-When the user explicitly asks for subagents or parallel agent work, use subagents only 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 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.
 
 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,9 +61,9 @@ The base contract is shaped to match the official Codex `AGENTS.md` guidance:
 
 ## Codex Subagent Fit
 
-When the user explicitly asks for subagents or parallel agent work, use subagents only 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 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.
 
-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 are explicit user-triggered workflows, best for bounded parallel discovery, tests, triage, and summarization.
+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.
 
 ## Codex Hooks Fit
 

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

@@ -52,7 +52,7 @@ The base contract requires:
 
 ## Codex Subagent Fit
 
-When the user explicitly asks for subagents or parallel agent work, use subagents only 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 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.
 
 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 the user explicitly asks for subagents or parallel agent work, use subagents only 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 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.
 
 ## Output Contract