begin

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.

/pbr:begin — Project Initialization

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.

Context Budget

Reference: skills/shared/context-budget.md for the universal orchestrator rules.

Additionally for this skill:

• Minimize reading subagent output — read only summaries, not full research docs
• Delegate all analysis work to subagents — the orchestrator routes, it doesn't analyze

Step 0 — Immediate Output

Before ANY tool calls, display this banner:

╔══════════════════════════════════════════════════════════════╗
║  PLAN-BUILD-RUN ► STARTING PROJECT                           ║
╚══════════════════════════════════════════════════════════════╝

Then proceed to Step 1.

Prerequisites

• Working directory should be the project root
• No existing .planning/ directory (or user confirms overwrite)

---

Orchestration Flow

Execute these steps in order. Each step specifies whether it runs inline (in your context) or is delegated to a subagent.

---

Step 1: Detect Brownfield (inline)

Cross-platform note: Use the Glob tool (not Bash ls or find) 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"

• If user selects "Yes, scan": suggest /pbr:scan and stop
• If user selects "No, begin": proceed to Step 2

If .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"

• If user selects "No": STOP IMMEDIATELY. Do not ask again. Do not proceed to Step 2. End the skill with this message:

  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.
• If user selects "Yes": proceed (existing directory will be overwritten during state initialization)

---

Step 2: Deep Questioning (inline)

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:

1. What they want to build — The core product/feature/system
2. Problem being solved — Why does this need to exist? Who is it for?
3. Success criteria — How will they know it works? What does "done" look like?
4. Existing constraints — Technology choices already made, hosting, budget, timeline, team size
5. Key decisions already made — Framework, language, architecture preferences
6. Edge cases and concerns — What worries them? What's the hardest part?

Conversation approach:

• Start broad: "What are you building?"
• Go deeper on each answer: "What does that mean exactly?" "Show me an example."
• Surface assumptions: "Why do you assume that?" "Have you considered X?"
• Find edges: "What happens when...?" "What about...?"
• Reveal motivation: "Why does that matter?"
• Avoid leading questions — let the user define their vision

Keep going until you have:

• A clear, concrete understanding of what they want to build
• At least 3 specific success criteria
• Known constraints and decisions
• A sense of complexity and scope

Anti-patterns:

• DO NOT present a bulleted checklist and ask them to fill it in
• DO NOT ask all questions at once — have a conversation
• DO NOT assume technologies — let them tell you
• DO NOT rush — this is the foundation for everything that follows

---

Step 2.5: Fast-Path Offer (inline)

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":

• Tell the user: "Tip: Agents set to 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."
• Write .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
    }
  }
  

• Write .planning/.active-skill with text "begin"
• Write CLAUDE.md integration block (see Step 3d-claude below) using the project name gathered in Step 2
• Skip to Step 4 (Research Decision)
• Tell the user: "Quick start selected. Using all defaults — you can adjust later with /pbr:config."

If user selects "Custom setup": proceed to Step 3 normally.

---

Step 3: Workflow Preferences (inline)

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:

• Balanced: executor=sonnet, researcher=sonnet, planner=sonnet, verifier=sonnet, synthesizer=haiku
• Quality: executor=opus, researcher=sonnet, planner=opus, verifier=sonnet, synthesizer=sonnet
• Budget: executor=haiku, researcher=haiku, planner=sonnet, verifier=haiku, synthesizer=haiku

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:

• Auto-continue: Set features.auto_continue: true
• TDD mode: Set features.tdd_mode: true
• Strict gates: Set gates.verification: true, gates.review: true, gates.plan_approval: true
• Git branching: Set git.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 decisions

3b. 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% cheaper
• standard (default) — 5-8 phases, includes research
• comprehensive — 8-12 phases, full deep research, ~2x cost

3c. 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 plans
• disabled — sequential execution

3d. Git Branching: Use the git-strategy-select pattern from skills/shared/gate-prompts.md: question: "Git branching strategy?"

• none (default) — commit to current branch
• phase — create branch per phase
• milestone — create branch per milestone

3e. 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 docs
• no — add .planning/ to .gitignore

3d-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.

1. Read the config template from ${CLAUDE_SKILL_DIR}/templates/config.json.tmpl
2. Apply the user's choices to the template (including 3d-claude CLAUDE.md integration)
3. Create .planning/ directory
4. Write .planning/config.json with the user's preferences

IMPORTANT: 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.

---

Step 4: Research Decision (inline)

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:

• Skip to Step 7 (Requirements Scoping)
• Tell user: "Skipping research phase (depth: quick). Moving straight to requirements."

If depth is standard or comprehensive:

• If 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"
  • If user selects "No": skip to Step 7
  • If user selects "Yes": proceed to Step 5
• If gates.confirm_research is false (default): proceed directly to Step 5 (research runs automatically)

---

Step 5: Research (delegated to subagents)

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.

Researcher Prompt Template

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 below

Topic-specific questions:

STACK.md (Level 1+):

• What is the standard technology stack for this type of project?
• What are the current recommended versions?
• What are the key dependencies and their compatibility?
• What build tools and development workflow is standard?

FEATURES.md (Level 1+):

• How are similar features typically implemented in this stack?
• What libraries/packages are commonly used for each feature area?
• What are standard patterns for the key features described?
• What third-party integrations are typically needed?

ARCHITECTURE.md (Level 3 only):

• What is the recommended architecture for this type of project?
• How should the codebase be organized?
• What are the standard patterns for data flow, state management, etc.?
• How should components communicate?

PITFALLS.md (Level 3 only):

• What commonly goes wrong with this type of project?
• What are the most common mistakes developers make?
• What performance issues are typical?
• What security concerns exist?

Parallelization:

• Spawn ALL researchers in parallel (multiple Task() calls in one response)
• Use run_in_background: true for each researcher
• Before spawning, display to the user: ◐ Spawning {N} researchers in parallel...
• While waiting, display progress to the user:
  • After spawning: list of topics being researched
  • Periodically (every ~30s): check TaskOutput with block: false for each agent and report status
  • When each completes: "✓ {topic} researcher complete ({duration})"
  • When all complete: "All {N} researchers finished. Proceeding to synthesis."
• Wait for all to complete before proceeding

---

Step 6: Synthesis (delegated to subagent)

After 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.

Synthesis Prompt Template

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 5

After the synthesizer completes, check for completion markers in the Task() output:

• If ## SYNTHESIS COMPLETE is present: proceed normally
• If ## 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 "Yes": proceed to Step 7 without SUMMARY.md
  • If "No": stop and suggest reviewing .planning/research/ files
• If neither marker is found: warn the user that the synthesizer may not have completed successfully, but proceed if SUMMARY.md exists on disk

If synthesis succeeded, display:

✓ Research synthesis complete — see .planning/research/SUMMARY.md

---

Step 7: Requirements Scoping (inline)

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:

• Recommended stack
• Key architectural decisions
• Notable pitfalls to be aware of

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:

• v1 (committed) — Will be built in this project
• v2 (deferred) — Will be built later, not now
• Out of scope — Will NOT be built

7d. Assign REQ-IDs: For each committed requirement, assign an ID using the REQ-F/REQ-NF schema:

• Functional requirements: REQ-F-xxx numbered sequentially within each category (REQ-F-001, REQ-F-002, ...)
• Non-functional requirements: REQ-NF-xxx numbered sequentially across all NFR categories (REQ-NF-001, REQ-NF-002, ...)
• Examples: REQ-F-001: User can log in with Discord OAuth, REQ-NF-001: Page loads in <2s on 4G

Each requirement must be:

• User-centric — describes a capability from the user's perspective
• Testable — you can verify whether it's met or not
• Specific — not vague ("fast" is bad, "page loads in <2s" is good)

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:

• All v1 requirements grouped by category
• All v2 requirements with deferral reasons
• Out-of-scope items with rationale
• Traceability table (all REQ-IDs, no phases assigned yet)

---

Step 8: Roadmap Generation (delegated to subagent)

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.

Roadmap Prompt Template

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 3

After the planner completes:

• Spot-check: Verify .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.
• Read .planning/ROADMAP.md
• Count the phases from the roadmap content
• Verify the roadmap contains a ## 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.
• Display:

  ✓ Roadmap created — {N} phases in milestone "{name}"
  

• If gates.confirm_roadmap is true in config, use the approve-revise-abort pattern from skills/shared/gate-prompts.md: question: "Approve this roadmap?" options:
  • label: "Approve" description: "Proceed with this roadmap"
  • label: "Request changes" description: "Discuss adjustments before proceeding"
  • label: "Abort" description: "Cancel and start over"
  • If user selects "Request changes": edit the roadmap inline (small changes) or re-spawn planner
  • If user selects "Approve": proceed to Step 9
  • If user selects "Abort": stop execution

---

Step 9: State Initialization (inline)

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:

1. Read ${CLAUDE_SKILL_DIR}/templates/PROJECT.md.tmpl
2. Fill in:
   • {project_name} — from questioning
   • {2-3 sentences} — project description from questioning
   • {ONE sentence} — core value statement
   • Out-of-scope features
   • Technical context and constraints
   • Initial key decisions from the questioning conversation
3. Write to .planning/PROJECT.md
4. Ensure the ## Milestones section is filled in with the project name and phase count from the roadmap

CRITICAL (no hook): Write STATE.md NOW. Do NOT skip this step.

9b. Write STATE.md:

1. Read ${CLAUDE_SKILL_DIR}/templates/STATE.md.tmpl
2. Fill in:
   • {date} — today's date
   • {total} — total phase count from roadmap
   • {Phase 1 name} — from roadmap
   • Core value one-liner
   • Decisions from initialization
3. Write to .planning/STATE.md
4. Fill in the ## Milestone section with the project name and total phase count
5. STATE.md size limit: Follow size limit enforcement rules in skills/shared/state-update.md (150 lines max).

CRITICAL (no hook): Write CONTEXT.md NOW. Do NOT skip this step.

9c. Write CONTEXT.md:

1. Read ${CLAUDE_SKILL_DIR}/templates/project-CONTEXT.md.tmpl
2. Fill in from the questioning conversation:
   • Locked Decisions: all technology choices and architecture decisions from Step 2
   • User Constraints: budget, timeline, skill level, hosting, team
   • Deferred Ideas: out-of-scope items identified in Step 7c scoping
   • Claude's Discretion: any areas where user said "you decide"
3. Write to .planning/CONTEXT.md

CRITICAL (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).

---

Step 10: Git Setup (inline)

Reference: skills/shared/commit-planning-docs.md for the standard commit pattern.

10a. Gitignore: If planning.commit_docs is false in config:

• Add .planning/ to .gitignore

If planning.commit_docs is true:

• Add .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:

• Present a summary of everything created:
  • Project: {name}
  • Core value: {one-liner}
  • Phases: {count} phases in roadmap
  • Requirements: {count} v1 requirements
  • Config: depth={depth}, mode={mode}
• If 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"
  • If user selects "Yes" and planning.commit_docs is true:
    • Stage .planning/ files (excluding research/ if gitignored)
    • Commit: chore: initialize plan-build-run project planning
  • If user selects "No": let user review and adjust
• If gates.confirm_commit_docs is false AND greenfield: skip the question and commit automatically if planning.commit_docs is true

---

Cleanup

Delete .planning/.active-skill if it exists. This must happen on all paths (success, partial, and failure) before reporting results.

Completion

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.

---

Error Handling

Research agent fails

If a researcher Task() fails or times out:

• Note which topic wasn't researched
• Continue with available research
• Display: ⚠ Research on {topic} failed. Proceeding without it. You can re-research during /pbr:plan.

User wants to restart

If user says they want to start over mid-flow:

• Confirm: "Start over from the beginning? Current progress will be lost."
• If yes: restart from Step 2

Config write fails

If .planning/ directory can't be created, display:

╔══════════════════════════════════════════════════════════════╗
║  ERROR                                                       ║
╚══════════════════════════════════════════════════════════════╝

Cannot create .planning/ directory.

**To fix:** Check directory permissions or specify an alternative path.

---

Files Created by /pbr:begin

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