/begin

name: begin
description: "Start a new project. Deep questioning, research, requirements, and roadmap."
allowed-tools: Read, Write, Bash, Glob, Grep, WebFetch, WebSearch, Task, AskUserQuestion
argument-hint: "[--auto]"

**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:new-project — Project Initialization

**References:** `@references/questioning.md`, `@references/ui-brand.md`

You are the orchestrator for `/pbr:new-project`. 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. Reference: `skills/shared/agent-type-resolution.md` for agent type fallback when spawning Task() subagents.

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.

Multi-Session Sync

Before any phase-modifying operations, this skill acquires a claim on the project:

acquireClaim(planningDir, sessionId)

Where `planningDir` is the `.planning/` directory and `sessionId` is the current session identifier. If the claim fails (another session owns it), display: "Another session owns this project. Use `/pbr:progress` to see active claims."

On completion or error, release the claim:

releaseClaim(planningDir, sessionId)

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)

**CRITICAL — Run init command FIRST before any Glob calls or manual file checks:**

node plugins/pbr/scripts/pbr-tools.js init begin

Store the JSON result as `blob`. This single call replaces multiple Glob/filesystem checks with a pre-computed payload:

• `blob.has_planning` — whether .planning/ directory exists
• `blob.has_existing_code` — whether brownfield indicators were found
• `blob.brownfield_indicators` — array of detected indicators (package.json, src/, etc.)
• `blob.has_git` — whether .git directory exists
• `blob.existing_phases` — count of existing phase directories
• `blob.state` — existing STATE.md frontmatter (or null if no project)
• `blob.config` — existing config.json contents (or null)

> **Cross-platform note**: The init command handles all filesystem checks cross-platform. No Glob or Bash file discovery needed.

**If `blob.has_existing_code` is true:** **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding: Use the **yes-no** pattern from `skills/shared/gate-prompts.md`: question: "This looks like an existing codebase. Run /pbr:map-codebase to analyze what's here first?" options:

• label: "Yes, scan" description: "Run /pbr:map-codebase first to analyze existing code"
• label: "No, begin" description: "Proceed with /pbr:new-project on top of existing code"
• If user selects "Yes, scan": suggest `/pbr:map-codebase` and stop
• If user selects "No, begin": proceed to Step 2

**If `blob.has_planning` is true:** **CRITICAL -- DO NOT SKIP**: Present the following choice to the user via AskUserQuestion before proceeding: 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:progress` to see current project state, or `/pbr:plan-phase` 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 t