Initializes projects: detects existing code, questions for requirements, researches via subagents, scopes needs, generates roadmap.
From pbrnpx claudepluginhub sienklogic/plan-build-run --plugin pbrThis skill is limited to using the following tools:
templates/PROJECT.md.tmpltemplates/REQUIREMENTS.md.tmpltemplates/STATE.md.tmpltemplates/config.json.tmpltemplates/researcher-prompt.md.tmpltemplates/roadmap-prompt.md.tmpltemplates/synthesis-prompt.md.tmplSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Designs and optimizes AI agent action spaces, tool definitions, observation formats, error recovery, and context for higher task completion rates.
STOP — DO NOT READ THIS FILE. You are already reading it. This prompt was injected into your context by Claude Code's plugin system. Using the Read tool on this SKILL.md file wastes ~7,600 tokens. Begin executing Step 1 immediately.
You are the orchestrator for /pbr:begin. This skill initializes a new Plan-Build-Run project through deep questioning, optional research, requirements scoping, and roadmap generation. Your job is to stay lean — delegate heavy work to Task() subagents and keep the user's main context window clean.
Reference: skills/shared/context-budget.md for the universal orchestrator rules.
Additionally for this skill:
Before ANY tool calls, display this banner:
╔══════════════════════════════════════════════════════════════╗
║ PLAN-BUILD-RUN ► STARTING PROJECT ║
╚══════════════════════════════════════════════════════════════╝
Then proceed to Step 1.
.planning/ directory (or user confirms overwrite)Execute these steps in order. Each step specifies whether it runs inline (in your context) or is delegated to a subagent.
Cross-platform note: Use the Glob tool (not Bash
lsorfind) for all file and directory discovery. Bash file commands fail on Windows due to path separator issues.
Check if the current directory has existing code:
1. Use Glob to check directory contents (e.g., pattern "*" at project root)
2. Look for indicators of existing code:
- package.json, requirements.txt, CMakeLists.txt, go.mod, Cargo.toml
- src/, lib/, app/ directories
- .git/ directory with commits
3. Use Glob to check if .planning/ already exists (e.g., pattern ".planning/*")
If existing code found:
Use the yes-no pattern from skills/shared/gate-prompts.md:
question: "This looks like an existing codebase. Run /pbr:scan to analyze what's here first?"
options:
- label: "Yes, scan" description: "Run /pbr:scan first to analyze existing code"
- label: "No, begin" description: "Proceed with /pbr:begin on top of existing code"
/pbr:scan and stopIf .planning/ already exists:
Use the yes-no pattern from skills/shared/gate-prompts.md:
question: "A .planning/ directory already exists. This will overwrite it. Continue?"
options:
- label: "Yes" description: "Overwrite existing planning directory"
- label: "No" description: "Cancel — keep existing planning"
Keeping existing .planning/ directory. Use `/pbr:status` to see current project state, or `/pbr:plan` to continue planning.
Do NOT re-prompt the same question or any other question. The skill is finished.Reference: Read references/questioning.md for technique details.
Have a natural conversation to understand the user's vision. Do NOT present a form or checklist. Instead, have a flowing conversation that covers these areas organically:
Required context to gather:
Conversation approach:
Keep going until you have:
Anti-patterns:
Before asking any workflow preference questions, offer the user a quick-start option:
Use AskUserQuestion: question: "How do you want to configure this project?" header: "Setup mode" options: - label: "Quick start" description: "Use all defaults — model balanced, depth standard, interactive mode, parallel on. Writes config in seconds." - label: "Custom setup" description: "Walk through model selection, features, and preferences step by step."
If user selects "Quick start":
inherit use your Claude Code session model. For cost savings, run on Sonnet -- orchestration and inherit agents work well at that tier. See references/model-profiles.md for details.".planning/config.json immediately using the default config below (no further questions):
{
"version": 2,
"context_strategy": "aggressive",
"mode": "interactive",
"depth": "standard",
"features": {
"structured_planning": true,
"goal_verification": true,
"integration_verification": true,
"context_isolation": true,
"atomic_commits": true,
"session_persistence": true,
"research_phase": true,
"plan_checking": true,
"tdd_mode": false,
"status_line": true,
"auto_continue": false,
"auto_advance": false,
"team_discussions": false,
"inline_verify": false
},
"models": {
"researcher": "sonnet",
"planner": "inherit",
"executor": "inherit",
"verifier": "sonnet",
"integration_checker": "sonnet",
"debugger": "inherit",
"mapper": "sonnet",
"synthesizer": "haiku"
},
"parallelization": {
"enabled": true,
"plan_level": true,
"task_level": false,
"max_concurrent_agents": 3,
"min_plans_for_parallel": 2,
"use_teams": false
},
"planning": {
"commit_docs": true,
"max_tasks_per_plan": 3,
"search_gitignored": false
},
"git": {
"branching": "none",
"commit_format": "{type}({phase}-{plan}): {description}",
"phase_branch_template": "plan-build-run/phase-{phase}-{slug}",
"milestone_branch_template": "plan-build-run/{milestone}-{slug}",
"mode": "enabled"
},
"gates": {
"confirm_project": true,
"confirm_roadmap": true,
"confirm_plan": true,
"confirm_execute": false,
"confirm_transition": true,
"issues_review": true
},
"safety": {
"always_confirm_destructive": true,
"always_confirm_external_services": true
}
}
.planning/.active-skill with text "begin"/pbr:config."If user selects "Custom setup": proceed to Step 3 normally.
After understanding the project, configure the Plan-Build-Run workflow. Use AskUserQuestion for each preference below. Present them sequentially with conversational bridging (e.g., "Great. Next...") to keep the flow natural.
3-model. Model Profile:
Note: These profiles control agent models. The orchestrator uses your Claude Code session model. For cost optimization, consider running on Sonnet -- agents with inherit will follow. See references/model-profiles.md.
Use AskUserQuestion: question: "Which model profile should agents use?" header: "Models" options: - label: "Balanced (Recommended)" description: "Sonnet for most agents, Haiku for synthesizer. Good quality/cost tradeoff." - label: "Quality" description: "Opus for executor and planner, Sonnet for others. Best results, highest cost." - label: "Budget" description: "Haiku for most agents. Fastest and cheapest, but lower quality."
Apply the selected profile to the models block in config.json:
3-features. Workflow Features: Use AskUserQuestion: question: "Any extra workflow features?" header: "Features" multiSelect: true options: - label: "Auto-continue" description: "Automatically chain commands (build → review → next phase) without prompting" - label: "TDD mode" description: "Write tests before implementation in executor agents" - label: "Strict gates" description: "Require verification AND review to pass before advancing phases" - label: "Git branching" description: "Create a branch per phase for cleaner PR history"
Apply selections:
features.auto_continue: truefeatures.tdd_mode: truegates.verification: true, gates.review: true, gates.plan_approval: truegit.branching: "phase"3a. Mode:
Use the toggle-confirm pattern from skills/shared/gate-prompts.md:
question: "How do you want to work?"
header: "Mode"
options:
- label: "Interactive" description: "Pause at key gates for your approval (default)"
- label: "Autonomous" description: "Auto-proceed, only stop for critical decisions"
interactive (default) — confirm at gates (roadmap, plans, transitions)autonomous — auto-proceed, only stop for critical decisions3b. Depth:
Use the depth-select pattern from skills/shared/gate-prompts.md:
question: "How thorough should planning be?"
quick — 3-5 phases, skip research, ~50% cheaperstandard (default) — 5-8 phases, includes researchcomprehensive — 8-12 phases, full deep research, ~2x cost3c. Parallelization:
Use the toggle-confirm pattern from skills/shared/gate-prompts.md:
question: "Run multiple agents in parallel when plans are independent?"
header: "Parallel"
options:
- label: "Enable" description: "Parallel execution of independent plans (default)"
- label: "Disable" description: "Sequential execution only"
enabled (default) — parallel execution of independent plansdisabled — sequential execution3d. Git Branching:
Use the git-strategy-select pattern from skills/shared/gate-prompts.md:
question: "Git branching strategy?"
none (default) — commit to current branchphase — create branch per phasemilestone — create branch per milestone3e. Commit Planning Docs:
Use the yes-no pattern from skills/shared/gate-prompts.md:
question: "Should planning documents (.planning/ directory) be committed to git?"
options:
- label: "Yes" description: "Commit planning docs (default)"
- label: "No" description: "Add .planning/ to .gitignore"
yes (default) — commit planning docsno — add .planning/ to .gitignore3d-claude. CLAUDE.md Integration:
Check if a CLAUDE.md file exists in the project root.
If it exists: Read it. If it does NOT already contain a "Plan-Build-Run" section, append the block below.
If it does NOT exist: Create CLAUDE.md with the block below.
Append/create:
## Plan-Build-Run
This project uses [Plan-Build-Run](https://github.com/SienkLogic/plan-build-run) for structured development.
- Project state: `.planning/STATE.md` (source of truth for current phase and progress)
- Configuration: `.planning/config.json`
- Run `/pbr:status` to see current project state and suggested next action.
**After compaction or context recovery**: Read `.planning/STATE.md` (especially the `## Session Continuity` section) before proceeding with any work. The PreCompact hook writes recovery state there automatically.
After gathering preferences:
CRITICAL (no hook): You MUST create the .planning/ directory and write config.json NOW. Do not proceed without this.
${CLAUDE_SKILL_DIR}/templates/config.json.tmpl.planning/ directory.planning/config.json with the user's preferencesIMPORTANT: This step MUST happen BEFORE research (Step 5) because depth controls how many researchers to spawn.
CRITICAL (hook-enforced): Write .active-skill NOW. Write the text "begin" to .planning/.active-skill using the Write tool. Verify the file exists before proceeding.
Based on the depth setting from Step 3, determine the research approach:
Depth-to-Discovery mapping:
| Depth | Discovery Level | Researchers | Topics |
|---|---|---|---|
| quick | Level 0 | 0 | Skip research entirely |
| standard | Level 1 | 2 | STACK.md, FEATURES.md |
| standard + brownfield | Level 2 | 2-3 | STACK.md, FEATURES.md, + codebase mapping |
| comprehensive | Level 3 | 4 | STACK.md, FEATURES.md, ARCHITECTURE.md, PITFALLS.md |
If depth is quick:
If depth is standard or comprehensive:
gates.confirm_research is true in config:
Use the yes-no pattern from skills/shared/gate-prompts.md:
question: "I'd like to research the technology landscape before planning. This helps create better plans. Proceed with research?"
options:
- label: "Yes" description: "Run research agents (recommended for standard/comprehensive)"
- label: "No" description: "Skip research, move straight to requirements"
gates.confirm_research is false (default): proceed directly to Step 5 (research runs automatically)Spawn parallel Task() subagents for research. Each researcher writes to .planning/research/.
CRITICAL (no hook): Create .planning/research/ directory NOW before spawning researchers. Do NOT skip this step.
Learnings injection (opt-in): Before spawning researchers, check if global learnings exist:
node {resolved_plugin_root}/scripts/pbr-tools.js learnings query --tags "stack,tech" 2>/dev/null
If the command succeeds AND returns a non-empty JSON array:
Write the results to a temp file:
node {resolved_plugin_root}/scripts/pbr-tools.js learnings query --tags "stack,tech" > /tmp/pbr-learnings-$$.md
Note the temp file path as {learnings_temp_path}
Add this file to the researcher's files_to_read block (see below)
If no learnings exist or the command fails: skip injection silently.
For each research topic, spawn a Task():
Task({
subagent_type: "pbr:researcher",
// After researcher: check for ## RESEARCH COMPLETE or ## RESEARCH BLOCKED
prompt: <see researcher prompt template below>
})
NOTE: The pbr:researcher subagent type auto-loads the agent definition from agents/researcher.md. Do NOT inline the agent definition — it wastes main context.
Path resolution: Before constructing any agent prompt, resolve ${CLAUDE_PLUGIN_ROOT} to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it. Use the resolved absolute path for any pbr-tools.js or template references included in the prompt.
For each researcher, construct the prompt by reading the template and filling in placeholders:
Read ${CLAUDE_SKILL_DIR}/templates/researcher-prompt.md.tmpl for the prompt structure.
Prepend this block to the researcher prompt before sending:
<files_to_read>
CRITICAL (no hook): Read these files BEFORE any other action:
1. .planning/REQUIREMENTS.md — scoped requirements (if exists)
{if learnings_temp_path exists}2. {learnings_temp_path} — cross-project learnings (tech stack patterns from past PBR projects){/if}
</files_to_read>
If {learnings_temp_path} was produced in the learnings injection step above, replace {if...}{/if} with the actual line. If no learnings were found, omit line 2 entirely.
Placeholders to fill:
{project name from questioning} — project name gathered in Step 2{2-3 sentence description from questioning} — project description from Step 2{any locked technology choices} — technology constraints from Step 2{budget, timeline, skill level, etc.} — user constraints from Step 2{topic} — the research topic being assigned (e.g., "Technology Stack Analysis"){TOPIC} — the output filename (e.g., STACK, FEATURES, ARCHITECTURE, PITFALLS){topic-specific questions} — see topic-specific questions belowTopic-specific questions:
STACK.md (Level 1+):
FEATURES.md (Level 1+):
ARCHITECTURE.md (Level 3 only):
PITFALLS.md (Level 3 only):
Parallelization:
run_in_background: true for each researcher◐ Spawning {N} researchers in parallel...TaskOutput with block: false for each agent and report statusAfter all researchers complete, display to the user: ◐ Spawning synthesizer...
Spawn a synthesis agent:
Task({
subagent_type: "pbr:synthesizer",
prompt: <synthesis prompt>
})
NOTE: The pbr:synthesizer subagent type auto-loads the agent definition. Do NOT inline it. The agent definition specifies model: sonnet — do not override it.
Path resolution: Before constructing the agent prompt, resolve ${CLAUDE_PLUGIN_ROOT} to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it.
Read ${CLAUDE_SKILL_DIR}/templates/synthesis-prompt.md.tmpl for the prompt structure.
Prepend this block to the synthesizer prompt before sending:
<files_to_read>
CRITICAL (no hook): Read these files BEFORE any other action:
1. .planning/research/*.md — all research output files from Step 5
</files_to_read>
Placeholders to fill:
{List all .planning/research/*.md files that were created} — list the research files produced in Step 5After the synthesizer completes, check for completion markers in the Task() output:
## SYNTHESIS COMPLETE is present: proceed normally## SYNTHESIS BLOCKED is present: warn the user and offer to proceed without synthesis:
⚠ Synthesizer reported BLOCKED: {reason from output}
Research files are still available individually in .planning/research/.
Use AskUserQuestion (pattern: yes-no from skills/shared/gate-prompts.md):
question: "Synthesis was blocked. Continue without synthesis?"
header: "Blocked"
options:
- label: "Yes" description: "Proceed to requirements — use individual research files"
- label: "No" description: "Stop and investigate"
If synthesis succeeded, display:
✓ Research synthesis complete — see .planning/research/SUMMARY.md
Present research findings (if any) and interactively scope requirements with the user.
7a. Present findings:
If research was done, read .planning/research/SUMMARY.md and present key findings:
7b. Feature identification: From the questioning session, list all features and capabilities discussed. Group them into categories.
Example categories: Auth, UI, API, Data, Infrastructure, Testing, etc.
7c. Scope each category: For each category, present the features and ask the user to classify each:
7d. Assign REQ-IDs: For each committed requirement, assign an ID using the REQ-F/REQ-NF schema:
REQ-F-xxx numbered sequentially within each category (REQ-F-001, REQ-F-002, ...)REQ-NF-xxx numbered sequentially across all NFR categories (REQ-NF-001, REQ-NF-002, ...)REQ-F-001: User can log in with Discord OAuth, REQ-NF-001: Page loads in <2s on 4GEach requirement must be:
7e. Write REQUIREMENTS.md:
CRITICAL (no hook): Write REQUIREMENTS.md NOW. The roadmap planner depends on this file.
Read the template from ${CLAUDE_SKILL_DIR}/templates/REQUIREMENTS.md.tmpl and write .planning/REQUIREMENTS.md with:
Display to the user: ◐ Spawning planner (roadmap)...
Spawn the planner in roadmap mode:
Task({
subagent_type: "pbr:planner",
// After planner: check for ## PLANNING COMPLETE or ## PLANNING FAILED
prompt: <roadmap prompt>
})
NOTE: The pbr:planner subagent type auto-loads the agent definition. Do NOT inline it. The planner agent will read REQUIREMENTS.md and SUMMARY.md from disk — you only need to tell it what to do and where files are.
Path resolution: Before constructing the agent prompt, resolve ${CLAUDE_PLUGIN_ROOT} to its absolute path. Do not pass the variable literally in prompts — Task() contexts may not expand it.
Read ${CLAUDE_SKILL_DIR}/templates/roadmap-prompt.md.tmpl for the prompt structure.
Prepend this block to the roadmap planner prompt before sending:
<files_to_read>
CRITICAL (no hook): Read these files BEFORE any other action:
1. .planning/REQUIREMENTS.md — scoped requirements for phase planning
2. .planning/research/SUMMARY.md — research synthesis (if exists)
</files_to_read>
Placeholders to fill:
{project name} — project name from Step 2{description} — project description from Step 2{quick|standard|comprehensive} — depth setting from Step 3After the planner completes:
.planning/ROADMAP.md exists on disk using Glob before attempting to read it. If missing, the planner may have failed silently — warn: ⚠ ROADMAP.md not found after planner completed. Re-spawning planner... and retry once..planning/ROADMAP.md## Milestone: section wrapping the phases (the planner should generate this). If not, the initial set of phases constitutes the first milestone — add the section header yourself.✓ Roadmap created — {N} phases in milestone "{name}"
gates.confirm_roadmap is true in config, use the approve-revise-abort pattern from skills/shared/gate-prompts.md:
question: "Approve this roadmap?"
options:
Write the project state files from templates:
CRITICAL (no hook): You MUST write all 5 state initialization files (Steps 9a-9e). Do NOT skip any.
CRITICAL (no hook): Write PROJECT.md NOW. Do NOT skip this step.
9a. Write PROJECT.md:
${CLAUDE_SKILL_DIR}/templates/PROJECT.md.tmpl{project_name} — from questioning{2-3 sentences} — project description from questioning{ONE sentence} — core value statement.planning/PROJECT.md## Milestones section is filled in with the project name and phase count from the roadmapCRITICAL (no hook): Write STATE.md NOW. Do NOT skip this step.
9b. Write STATE.md:
${CLAUDE_SKILL_DIR}/templates/STATE.md.tmpl{date} — today's date{total} — total phase count from roadmap{Phase 1 name} — from roadmap.planning/STATE.md## Milestone section with the project name and total phase countskills/shared/state-update.md (150 lines max).CRITICAL (no hook): Write CONTEXT.md NOW. Do NOT skip this step.
9c. Write CONTEXT.md:
${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl.planning/CONTEXT.mdCRITICAL (no hook): Write HISTORY.md NOW. Do NOT skip this step.
9d. Write HISTORY.md:
Create .planning/HISTORY.md with an initial entry:
# Project History
## {date} — Project Created
- Initialized Plan-Build-Run project
- Depth: {depth}, Mode: {mode}
- Roadmap: {N} phases planned
CRITICAL (no hook): Create phase directories NOW. Do NOT skip this step.
9e. Create phase directories: For each phase in the roadmap, create the directory structure:
.planning/phases/01-{slug}/
.planning/phases/02-{slug}/
...
Where {slug} is the phase name in kebab-case (e.g., project-setup, authentication).
Reference: skills/shared/commit-planning-docs.md for the standard commit pattern.
10a. Gitignore:
If planning.commit_docs is false in config:
.planning/ to .gitignoreIf planning.commit_docs is true:
.planning/research/ to .gitignore (research is always excluded — it's reference material, not project state)10b. Initial commit (if desired):
If gates.confirm_project is true in config:
gates.confirm_commit_docs is true OR this is a brownfield project (existing code detected in Step 1):
Use the yes-no pattern from skills/shared/gate-prompts.md:
question: "Everything look good? Commit the planning docs?"
options:
- label: "Yes" description: "Stage and commit .planning/ files"
- label: "No" description: "Let me review and adjust first"
planning.commit_docs is true:
.planning/ files (excluding research/ if gitignored)chore: initialize plan-build-run project planninggates.confirm_commit_docs is false AND greenfield: skip the question and commit automatically if planning.commit_docs is trueDelete .planning/.active-skill if it exists. This must happen on all paths (success, partial, and failure) before reporting results.
After all steps complete, present the final summary using the stage banner format from Read references/ui-formatting.md:
Display the PROJECT INITIALIZED ✓ banner with project name, core value, phase list, and requirement counts. Then display the "Next Up" block (see § "Next Up Block" in ui-formatting.md) pointing to /pbr:discuss 1 with alternatives: /pbr:explore, /pbr:plan 1, /pbr:milestone new, /pbr:config. Include <sub>/clear first → fresh context window</sub> inside the Next Up routing block.
If a researcher Task() fails or times out:
⚠ Research on {topic} failed. Proceeding without it. You can re-research during /pbr:plan.If user says they want to start over mid-flow:
If .planning/ directory can't be created, display:
╔══════════════════════════════════════════════════════════════╗
║ ERROR ║
╚══════════════════════════════════════════════════════════════╝
Cannot create .planning/ directory.
**To fix:** Check directory permissions or specify an alternative path.
| File | Purpose | When |
|---|---|---|
.planning/config.json | Workflow configuration | Step 3 |
.planning/research/*.md | Research documents | Step 5 (if research enabled) |
.planning/research/SUMMARY.md | Research synthesis | Step 6 (if research enabled) |
.planning/REQUIREMENTS.md | Scoped requirements | Step 7 |
.planning/ROADMAP.md | Phase roadmap | Step 8 |
.planning/PROJECT.md | Project overview | Step 9 |
.planning/STATE.md | Current state tracker | Step 9 |
.planning/CONTEXT.md | Decisions and constraints | Step 9 |
.planning/HISTORY.md | Project history log | Step 9 |
.planning/phases/NN-*/ | Phase directories | Step 9 |