@sienklogic/plan-build-run 2.56.1 → 2.56.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,13 @@ All notable changes to Plan-Build-Run will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [2.56.2](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.56.1...plan-build-run-v2.56.2) (2026-03-03)
9
+
10
+
11
+ ### Bug Fixes
12
+
13
+ * **tools:** block non-PBR agent types by default with [native] bypass ([0256189](https://github.com/SienkLogic/plan-build-run/commit/02561890e49dba88df03d3977f9a8597740bd389))
14
+
8
15
  ## [2.56.1](https://github.com/SienkLogic/plan-build-run/compare/plan-build-run-v2.56.0...plan-build-run-v2.56.1) (2026-03-03)
9
16
 
10
17
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sienklogic/plan-build-run",
3
- "version": "2.56.1",
3
+ "version": "2.56.2",
4
4
  "description": "Plan it, Build it, Run it — structured development workflow for Claude Code",
5
5
  "keywords": [
6
6
  "claude-code",
@@ -153,11 +153,11 @@ Task({
153
153
  })
154
154
  ```
155
155
 
156
- Also spawn a git analysis agent (can use a Bash agent or general-purpose):
156
+ Also spawn a git analysis agent:
157
157
 
158
158
  ```
159
159
  Task({
160
- subagent_type: "Bash",
160
+ subagent_type: "pbr:general",
161
161
  model: "haiku",
162
162
  prompt: "Run these git commands in {project_dir}:
163
163
  1. git log --since='{from}' --until='{to}' --format='%h|%s|%an|%ai' --all
@@ -21,7 +21,9 @@ Then proceed to Step 1.
21
21
 
22
22
  You are running the **explore** skill. Your job is to help the user think through ideas that might become a todo, requirement, phase, decision, or nothing yet. This is Socratic conversation, not requirements gathering. No phase number is needed.
23
23
 
24
- This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading and mid-conversation research.
24
+ This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading, upfront research, and mid-conversation research.
25
+
26
+ **CRITICAL: Agent type rule** — When spawning ANY research or analysis Task(), ALWAYS use `subagent_type: "pbr:researcher"`. NEVER use `general-purpose`, `Explore`, or other non-PBR agent types. The PreToolUse hook will block non-PBR agents.
25
27
 
26
28
  ---
27
29
 
@@ -103,6 +105,31 @@ Reference `skills/shared/domain-probes.md` for technology-specific follow-up que
103
105
 
104
106
  ---
105
107
 
108
+ ## Upfront Research Delegation
109
+
110
+ When the user's initial request is research-heavy (e.g., "explore best practices for X", "research how other projects do Y", "compare approaches to Z"), delegate immediately to `pbr:researcher` agents rather than doing inline research.
111
+
112
+ **Detection**: If `$ARGUMENTS` contains words like "research", "compare", "explore examples", "best practices", "how do others", or describes gathering external information — this is an upfront research task.
113
+
114
+ **Pattern**: Spawn one or more `pbr:researcher` agents in parallel, then synthesize their findings inline:
115
+
116
+ ```
117
+ Task({
118
+ subagent_type: "pbr:researcher",
119
+ prompt: "<research_assignment>
120
+ Topic: {specific research question from user's request}
121
+ Output: Return findings as structured markdown in your response.
122
+ Mode: external-research
123
+
124
+ {detailed research instructions}
125
+ </research_assignment>"
126
+ })
127
+ ```
128
+
129
+ After researchers complete, synthesize findings inline and continue the Socratic conversation with the user about what was discovered.
130
+
131
+ ---
132
+
106
133
  ## Mid-Conversation Research
107
134
 
108
135
  When a knowledge gap emerges during the conversation — you're unsure about a library, pattern, or approach — surface it explicitly.
@@ -44,6 +44,7 @@ Task({
44
44
  2. **Budget: ~500 tokens.** The briefing must be concise. The subagent reads full files in its own context; the orchestrator receives only the summary.
45
45
  3. **No suggestions.** The briefing reports state, it does not recommend actions. The skill logic decides what to do.
46
46
  4. **Read-only.** The briefing task must not write any files.
47
+ 5. **No subagent_type needed.** This is the ONE exception to the "always use `pbr:*` agents" rule. Bare `Task()` without `subagent_type` is intentional here — these are lightweight read-only briefings that don't need agent-specific prompts. Do NOT generalize this pattern to other Task() calls — all research, execution, and analysis Task() calls MUST use `subagent_type: "pbr:{agent}"`.
47
48
 
48
49
  ### Using the Briefing
49
50
 
@@ -26,6 +26,7 @@ These rules prevent context rot -- quality degradation as the context window fil
26
26
  ## Task/Subagent Rules (apply to every skill)
27
27
 
28
28
  10. **Never** invoke `Skill()` inside a `Task()` subagent -- the Skill tool is not available in subagent contexts. Agents spawned by `Task()` cannot resolve `$pbr-*` skill prefixes, so `Skill({ skill: "pbr:plan" })` will silently fail. Instead, chain skills at the orchestrator level (return control to the orchestrator, then call `Skill()` from there). For subagent work, use `subagent_type: "pbr:{agent}"` which auto-loads agent definitions.
29
+ 11. **NEVER** use non-PBR agent types (`general-purpose`, `Explore`, `Plan`, `Bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "pbr:{agent}"` (e.g., `pbr:researcher`, `pbr:executor`, `pbr:general`). PBR agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this. A PreToolUse hook **blocks** non-PBR agent spawns by default. Exceptions: (a) bare `Task()` with no `subagent_type` for lightweight read-only briefings (see context-loader-task pattern), (b) if the user says "use native agents", add `[native]` to the Task description to bypass the block for that call.
29
30
 
30
31
  ## Behavioral Rules (apply to every skill)
31
32
 
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pbr",
3
3
  "displayName": "Plan-Build-Run",
4
- "version": "2.56.1",
4
+ "version": "2.56.2",
5
5
  "description": "Plan-Build-Run — Structured development workflow for GitHub Copilot CLI. Solves context rot through disciplined agent delegation, structured planning, atomic execution, and goal-backward verification.",
6
6
  "author": {
7
7
  "name": "SienkLogic",
@@ -153,11 +153,11 @@ Task({
153
153
  })
154
154
  ```
155
155
 
156
- Also spawn a git analysis agent (can use a Bash agent or general-purpose):
156
+ Also spawn a git analysis agent:
157
157
 
158
158
  ```
159
159
  Task({
160
- subagent_type: "Bash",
160
+ subagent_type: "pbr:general",
161
161
  model: "haiku",
162
162
  prompt: "Run these git commands in {project_dir}:
163
163
  1. git log --since='{from}' --until='{to}' --format='%h|%s|%an|%ai' --all
@@ -21,7 +21,9 @@ Then proceed to Step 1.
21
21
 
22
22
  You are running the **explore** skill. Your job is to help the user think through ideas that might become a todo, requirement, phase, decision, or nothing yet. This is Socratic conversation, not requirements gathering. No phase number is needed.
23
23
 
24
- This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading and mid-conversation research.
24
+ This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading, upfront research, and mid-conversation research.
25
+
26
+ **CRITICAL: Agent type rule** — When spawning ANY research or analysis Task(), ALWAYS use `subagent_type: "pbr:researcher"`. NEVER use `general-purpose`, `Explore`, or other non-PBR agent types. The PreToolUse hook will block non-PBR agents.
25
27
 
26
28
  ---
27
29
 
@@ -103,6 +105,31 @@ Reference `skills/shared/domain-probes.md` for technology-specific follow-up que
103
105
 
104
106
  ---
105
107
 
108
+ ## Upfront Research Delegation
109
+
110
+ When the user's initial request is research-heavy (e.g., "explore best practices for X", "research how other projects do Y", "compare approaches to Z"), delegate immediately to `pbr:researcher` agents rather than doing inline research.
111
+
112
+ **Detection**: If `$ARGUMENTS` contains words like "research", "compare", "explore examples", "best practices", "how do others", or describes gathering external information — this is an upfront research task.
113
+
114
+ **Pattern**: Spawn one or more `pbr:researcher` agents in parallel, then synthesize their findings inline:
115
+
116
+ ```
117
+ Task({
118
+ subagent_type: "pbr:researcher",
119
+ prompt: "<research_assignment>
120
+ Topic: {specific research question from user's request}
121
+ Output: Return findings as structured markdown in your response.
122
+ Mode: external-research
123
+
124
+ {detailed research instructions}
125
+ </research_assignment>"
126
+ })
127
+ ```
128
+
129
+ After researchers complete, synthesize findings inline and continue the Socratic conversation with the user about what was discovered.
130
+
131
+ ---
132
+
106
133
  ## Mid-Conversation Research
107
134
 
108
135
  When a knowledge gap emerges during the conversation — you're unsure about a library, pattern, or approach — surface it explicitly.
@@ -44,6 +44,7 @@ Task({
44
44
  2. **Budget: ~500 tokens.** The briefing must be concise. The subagent reads full files in its own context; the orchestrator receives only the summary.
45
45
  3. **No suggestions.** The briefing reports state, it does not recommend actions. The skill logic decides what to do.
46
46
  4. **Read-only.** The briefing task must not write any files.
47
+ 5. **No subagent_type needed.** This is the ONE exception to the "always use `pbr:*` agents" rule. Bare `Task()` without `subagent_type` is intentional here — these are lightweight read-only briefings that don't need agent-specific prompts. Do NOT generalize this pattern to other Task() calls — all research, execution, and analysis Task() calls MUST use `subagent_type: "pbr:{agent}"`.
47
48
 
48
49
  ### Using the Briefing
49
50
 
@@ -26,6 +26,7 @@ These rules prevent context rot -- quality degradation as the context window fil
26
26
  ## Task/Subagent Rules (apply to every skill)
27
27
 
28
28
  10. **Never** invoke `Skill()` inside a `Task()` subagent -- the Skill tool is not available in subagent contexts. Agents spawned by `Task()` cannot resolve `/pbr:*` skill prefixes, so `Skill({ skill: "pbr:plan" })` will silently fail. Instead, chain skills at the orchestrator level (return control to the orchestrator, then call `Skill()` from there). For subagent work, use `subagent_type: "pbr:{agent}"` which auto-loads agent definitions.
29
+ 11. **NEVER** use non-PBR agent types (`general-purpose`, `Explore`, `Plan`, `Bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "pbr:{agent}"` (e.g., `pbr:researcher`, `pbr:executor`, `pbr:general`). PBR agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this. A PreToolUse hook **blocks** non-PBR agent spawns by default. Exceptions: (a) bare `Task()` with no `subagent_type` for lightweight read-only briefings (see context-loader-task pattern), (b) if the user says "use native agents", add `[native]` to the Task description to bypass the block for that call.
29
30
 
30
31
  ## Behavioral Rules (apply to every skill)
31
32
 
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pbr",
3
3
  "displayName": "Plan-Build-Run",
4
- "version": "2.56.1",
4
+ "version": "2.56.2",
5
5
  "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
6
6
  "author": {
7
7
  "name": "SienkLogic",
@@ -154,11 +154,11 @@ Task({
154
154
  })
155
155
  ```
156
156
 
157
- Also spawn a git analysis agent (can use a Bash agent or general-purpose):
157
+ Also spawn a git analysis agent:
158
158
 
159
159
  ```
160
160
  Task({
161
- subagent_type: "Bash",
161
+ subagent_type: "pbr:general",
162
162
  model: "haiku",
163
163
  prompt: "Run these git commands in {project_dir}:
164
164
  1. git log --since='{from}' --until='{to}' --format='%h|%s|%an|%ai' --all
@@ -22,7 +22,9 @@ Then proceed to Step 1.
22
22
 
23
23
  You are running the **explore** skill. Your job is to help the user think through ideas that might become a todo, requirement, phase, decision, or nothing yet. This is Socratic conversation, not requirements gathering. No phase number is needed.
24
24
 
25
- This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading and mid-conversation research.
25
+ This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading, upfront research, and mid-conversation research.
26
+
27
+ **CRITICAL: Agent type rule** — When spawning ANY research or analysis Task(), ALWAYS use `subagent_type: "pbr:researcher"`. NEVER use `general-purpose`, `Explore`, or other non-PBR agent types. The PreToolUse hook will block non-PBR agents.
26
28
 
27
29
  ---
28
30
 
@@ -104,6 +106,31 @@ Reference `skills/shared/domain-probes.md` for technology-specific follow-up que
104
106
 
105
107
  ---
106
108
 
109
+ ## Upfront Research Delegation
110
+
111
+ When the user's initial request is research-heavy (e.g., "explore best practices for X", "research how other projects do Y", "compare approaches to Z"), delegate immediately to `pbr:researcher` agents rather than doing inline research.
112
+
113
+ **Detection**: If `$ARGUMENTS` contains words like "research", "compare", "explore examples", "best practices", "how do others", or describes gathering external information — this is an upfront research task.
114
+
115
+ **Pattern**: Spawn one or more `pbr:researcher` agents in parallel, then synthesize their findings inline:
116
+
117
+ ```
118
+ Task({
119
+ subagent_type: "pbr:researcher",
120
+ prompt: "<research_assignment>
121
+ Topic: {specific research question from user's request}
122
+ Output: Return findings as structured markdown in your response.
123
+ Mode: external-research
124
+
125
+ {detailed research instructions}
126
+ </research_assignment>"
127
+ })
128
+ ```
129
+
130
+ After researchers complete, synthesize findings inline and continue the Socratic conversation with the user about what was discovered.
131
+
132
+ ---
133
+
107
134
  ## Mid-Conversation Research
108
135
 
109
136
  When a knowledge gap emerges during the conversation — you're unsure about a library, pattern, or approach — surface it explicitly.
@@ -44,6 +44,7 @@ Task({
44
44
  2. **Budget: ~500 tokens.** The briefing must be concise. The subagent reads full files in its own context; the orchestrator receives only the summary.
45
45
  3. **No suggestions.** The briefing reports state, it does not recommend actions. The skill logic decides what to do.
46
46
  4. **Read-only.** The briefing task must not write any files.
47
+ 5. **No subagent_type needed.** This is the ONE exception to the "always use `pbr:*` agents" rule. Bare `Task()` without `subagent_type` is intentional here — these are lightweight read-only briefings that don't need agent-specific prompts. Do NOT generalize this pattern to other Task() calls — all research, execution, and analysis Task() calls MUST use `subagent_type: "pbr:{agent}"`.
47
48
 
48
49
  ### Using the Briefing
49
50
 
@@ -26,6 +26,7 @@ These rules prevent context rot -- quality degradation as the context window fil
26
26
  ## Task/Subagent Rules (apply to every skill)
27
27
 
28
28
  10. **Never** invoke `Skill()` inside a `Task()` subagent -- the Skill tool is not available in subagent contexts. Agents spawned by `Task()` cannot resolve `/pbr:*` skill prefixes, so `Skill({ skill: "pbr:plan" })` will silently fail. Instead, chain skills at the orchestrator level (return control to the orchestrator, then call `Skill()` from there). For subagent work, use `subagent_type: "pbr:{agent}"` which auto-loads agent definitions.
29
+ 11. **NEVER** use non-PBR agent types (`general-purpose`, `Explore`, `Plan`, `Bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "pbr:{agent}"` (e.g., `pbr:researcher`, `pbr:executor`, `pbr:general`). PBR agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this. A PreToolUse hook **blocks** non-PBR agent spawns by default. Exceptions: (a) bare `Task()` with no `subagent_type` for lightweight read-only briefings (see context-loader-task pattern), (b) if the user says "use native agents", add `[native]` to the Task description to bypass the block for that call.
29
30
 
30
31
  ## Behavioral Rules (apply to every skill)
31
32
 
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pbr",
3
- "version": "2.56.1",
3
+ "version": "2.56.2",
4
4
  "description": "Plan-Build-Run — Structured development workflow for Claude Code. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
5
5
  "author": {
6
6
  "name": "SienkLogic",
@@ -13,7 +13,7 @@
13
13
  * checkUnmanagedCommit(data) — PreToolUse Bash: advises git commits to use /pbr:quick
14
14
  *
15
15
  * All functions return null for pass, or { exitCode, output } for action.
16
- * checkNonPbrAgent always returns advisory (exitCode 0) — never blocks Task().
16
+ * checkNonPbrAgent defaults to blocking (exitCode 2) — blocks non-PBR agents.
17
17
  */
18
18
 
19
19
  'use strict';
@@ -136,8 +136,9 @@ const AGENT_MAPPING = {
136
136
  * - subagent_type is missing/empty (can't determine type)
137
137
  * - Enforcement level is "off"
138
138
  *
139
- * In "advisory" mode (default): returns exitCode 0 with additionalContext.
140
- * In "block" mode: returns exitCode 2 with decision/reason to hard-block the agent spawn.
139
+ * Defaults to **blocking** (exitCode 2) unless config overrides to "advisory".
140
+ * This is stricter than checkUnmanagedSourceWrite/checkUnmanagedCommit because
141
+ * non-PBR agents bypass audit logging, workflow context, and project-aware prompts.
141
142
  *
142
143
  * @param {Object} data - parsed hook input from Claude Code
143
144
  * @returns {null|{ exitCode: number, output: Object }}
@@ -149,6 +150,10 @@ function checkNonPbrAgent(data) {
149
150
  // Already using a PBR agent
150
151
  if (subagentType.startsWith('pbr:')) return null;
151
152
 
153
+ // Per-call bypass: user says "use native agents" and the LLM includes [native] in description
154
+ const description = (data.tool_input && data.tool_input.description) || '';
155
+ if (/\[native\]/i.test(description)) return null;
156
+
152
157
  const cwd = process.cwd();
153
158
  const planningDir = path.join(cwd, '.planning');
154
159
 
@@ -158,14 +163,35 @@ function checkNonPbrAgent(data) {
158
163
  const config = loadEnforcementConfig(planningDir);
159
164
  if (config.level === 'off') return null;
160
165
 
166
+ // For agent enforcement, determine the effective level.
167
+ // Priority: workflow.enforce_pbr_agents > workflow.enforce_pbr_skills > default "block"
168
+ // Agent enforcement is stricter than source write/commit checks — blocks by default.
169
+ let agentLevel = 'block'; // default: block non-PBR agents
170
+ try {
171
+ const configPath = path.join(planningDir, 'config.json');
172
+ const parsed = JSON.parse(fs.readFileSync(configPath, 'utf8'));
173
+ const agentExplicit = parsed.workflow && parsed.workflow.enforce_pbr_agents;
174
+ const skillExplicit = parsed.workflow && parsed.workflow.enforce_pbr_skills;
175
+ if (agentExplicit === 'advisory' || agentExplicit === 'block' || agentExplicit === 'off') {
176
+ agentLevel = agentExplicit;
177
+ } else if (skillExplicit === 'advisory' || skillExplicit === 'block' || skillExplicit === 'off') {
178
+ agentLevel = skillExplicit;
179
+ }
180
+ } catch (_e) {
181
+ // No config — keep default (block)
182
+ }
183
+
184
+ if (agentLevel === 'off') return null;
185
+
161
186
  const suggestion = AGENT_MAPPING[subagentType] || 'a pbr:* agent (e.g., pbr:researcher, pbr:general, pbr:executor)';
162
187
 
163
- if (config.level === 'block') {
188
+ // Block non-PBR agents unless explicitly set to advisory
189
+ if (agentLevel !== 'advisory') {
164
190
  const blockMessage =
165
191
  `PBR workflow violation: spawning generic agent "${subagentType}" is blocked. ` +
166
192
  `Use ${suggestion} instead. ` +
167
193
  'PBR agents are auto-loaded via subagent_type — just change the type, no extra setup needed. ' +
168
- 'Set workflow.enforce_pbr_skills: "advisory" in config to allow with warnings.';
194
+ 'If the user explicitly requested a native agent, add [native] to the Task description to bypass this check.';
169
195
 
170
196
  logHook('enforce-pbr-workflow', 'PreToolUse', 'block', { agentType: subagentType, suggestion });
171
197
  return {
@@ -155,11 +155,11 @@ Task({
155
155
  })
156
156
  ```
157
157
 
158
- Also spawn a git analysis agent (can use a Bash agent or general-purpose):
158
+ Also spawn a git analysis agent:
159
159
 
160
160
  ```
161
161
  Task({
162
- subagent_type: "Bash",
162
+ subagent_type: "pbr:general",
163
163
  model: "haiku",
164
164
  prompt: "Run these git commands in {project_dir}:
165
165
  1. git log --since='{from}' --until='{to}' --format='%h|%s|%an|%ai' --all
@@ -23,7 +23,9 @@ Then proceed to Step 1.
23
23
 
24
24
  You are running the **explore** skill. Your job is to help the user think through ideas that might become a todo, requirement, phase, decision, or nothing yet. This is Socratic conversation, not requirements gathering. No phase number is needed.
25
25
 
26
- This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading and mid-conversation research.
26
+ This skill runs **inline** (no Task delegation), with optional Task() spawns for context loading, upfront research, and mid-conversation research.
27
+
28
+ **CRITICAL: Agent type rule** — When spawning ANY research or analysis Task(), ALWAYS use `subagent_type: "pbr:researcher"`. NEVER use `general-purpose`, `Explore`, or other non-PBR agent types. The PreToolUse hook will block non-PBR agents.
27
29
 
28
30
  ---
29
31
 
@@ -105,6 +107,31 @@ Reference `skills/shared/domain-probes.md` for technology-specific follow-up que
105
107
 
106
108
  ---
107
109
 
110
+ ## Upfront Research Delegation
111
+
112
+ When the user's initial request is research-heavy (e.g., "explore best practices for X", "research how other projects do Y", "compare approaches to Z"), delegate immediately to `pbr:researcher` agents rather than doing inline research.
113
+
114
+ **Detection**: If `$ARGUMENTS` contains words like "research", "compare", "explore examples", "best practices", "how do others", or describes gathering external information — this is an upfront research task.
115
+
116
+ **Pattern**: Spawn one or more `pbr:researcher` agents in parallel, then synthesize their findings inline:
117
+
118
+ ```
119
+ Task({
120
+ subagent_type: "pbr:researcher",
121
+ prompt: "<research_assignment>
122
+ Topic: {specific research question from user's request}
123
+ Output: Return findings as structured markdown in your response.
124
+ Mode: external-research
125
+
126
+ {detailed research instructions}
127
+ </research_assignment>"
128
+ })
129
+ ```
130
+
131
+ After researchers complete, synthesize findings inline and continue the Socratic conversation with the user about what was discovered.
132
+
133
+ ---
134
+
108
135
  ## Mid-Conversation Research
109
136
 
110
137
  When a knowledge gap emerges during the conversation — you're unsure about a library, pattern, or approach — surface it explicitly.
@@ -44,6 +44,7 @@ Task({
44
44
  2. **Budget: ~500 tokens.** The briefing must be concise. The subagent reads full files in its own context; the orchestrator receives only the summary.
45
45
  3. **No suggestions.** The briefing reports state, it does not recommend actions. The skill logic decides what to do.
46
46
  4. **Read-only.** The briefing task must not write any files.
47
+ 5. **No subagent_type needed.** This is the ONE exception to the "always use `pbr:*` agents" rule. Bare `Task()` without `subagent_type` is intentional here — these are lightweight read-only briefings that don't need agent-specific prompts. Do NOT generalize this pattern to other Task() calls — all research, execution, and analysis Task() calls MUST use `subagent_type: "pbr:{agent}"`.
47
48
 
48
49
  ### Using the Briefing
49
50
 
@@ -26,6 +26,7 @@ These rules prevent context rot -- quality degradation as the context window fil
26
26
  ## Task/Subagent Rules (apply to every skill)
27
27
 
28
28
  10. **Never** invoke `Skill()` inside a `Task()` subagent -- the Skill tool is not available in subagent contexts. Subagents spawned by `Task()` cannot resolve `/pbr:*` skill prefixes, so `Skill({ skill: "pbr:plan" })` will silently fail. Instead, chain skills at the orchestrator level (return control to the orchestrator, then call `Skill()` from there). For subagent work, use `subagent_type: "pbr:{agent}"` which auto-loads agent definitions.
29
+ 11. **NEVER** use non-PBR agent types (`general-purpose`, `Explore`, `Plan`, `Bash`, `feature-dev`, etc.) -- ALWAYS use `subagent_type: "pbr:{agent}"` (e.g., `pbr:researcher`, `pbr:executor`, `pbr:general`). PBR agents have project-aware prompts, audit logging, and workflow context. Generic agents bypass all of this. A PreToolUse hook **blocks** non-PBR agent spawns by default. Exceptions: (a) bare `Task()` with no `subagent_type` for lightweight read-only briefings (see context-loader-task pattern), (b) if the user says "use native agents", add `[native]` to the Task description to bypass the block for that call.
29
30
 
30
31
  ## Behavioral Rules (apply to every skill)
31
32