@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 +7 -0
- package/package.json +1 -1
- package/plugins/codex-pbr/skills/audit/SKILL.md +2 -2
- package/plugins/codex-pbr/skills/explore/SKILL.md +28 -1
- package/plugins/codex-pbr/skills/shared/context-loader-task.md +1 -0
- package/plugins/codex-pbr/skills/shared/universal-anti-patterns.md +1 -0
- package/plugins/copilot-pbr/plugin.json +1 -1
- package/plugins/copilot-pbr/skills/audit/SKILL.md +2 -2
- package/plugins/copilot-pbr/skills/explore/SKILL.md +28 -1
- package/plugins/copilot-pbr/skills/shared/context-loader-task.md +1 -0
- package/plugins/copilot-pbr/skills/shared/universal-anti-patterns.md +1 -0
- package/plugins/cursor-pbr/.cursor-plugin/plugin.json +1 -1
- package/plugins/cursor-pbr/skills/audit/SKILL.md +2 -2
- package/plugins/cursor-pbr/skills/explore/SKILL.md +28 -1
- package/plugins/cursor-pbr/skills/shared/context-loader-task.md +1 -0
- package/plugins/cursor-pbr/skills/shared/universal-anti-patterns.md +1 -0
- package/plugins/pbr/.claude-plugin/plugin.json +1 -1
- package/plugins/pbr/scripts/enforce-pbr-workflow.js +31 -5
- package/plugins/pbr/skills/audit/SKILL.md +2 -2
- package/plugins/pbr/skills/explore/SKILL.md +28 -1
- package/plugins/pbr/skills/shared/context-loader-task.md +1 -0
- package/plugins/pbr/skills/shared/universal-anti-patterns.md +1 -0
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
|
@@ -153,11 +153,11 @@ Task({
|
|
|
153
153
|
})
|
|
154
154
|
```
|
|
155
155
|
|
|
156
|
-
Also spawn a git analysis agent
|
|
156
|
+
Also spawn a git analysis agent:
|
|
157
157
|
|
|
158
158
|
```
|
|
159
159
|
Task({
|
|
160
|
-
subagent_type: "
|
|
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.
|
|
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
|
|
156
|
+
Also spawn a git analysis agent:
|
|
157
157
|
|
|
158
158
|
```
|
|
159
159
|
Task({
|
|
160
|
-
subagent_type: "
|
|
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.
|
|
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
|
|
157
|
+
Also spawn a git analysis agent:
|
|
158
158
|
|
|
159
159
|
```
|
|
160
160
|
Task({
|
|
161
|
-
subagent_type: "
|
|
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.
|
|
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
|
|
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
|
-
*
|
|
140
|
-
*
|
|
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
|
-
|
|
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
|
-
'
|
|
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
|
|
158
|
+
Also spawn a git analysis agent:
|
|
159
159
|
|
|
160
160
|
```
|
|
161
161
|
Task({
|
|
162
|
-
subagent_type: "
|
|
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
|
|