@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/skills/begin/SKILL.md

@@ -0,0 +1,545 @@
+---
+name: begin
+description: "Start a new project. Deep questioning, research, requirements, and roadmap."
+allowed-tools: Read, Write, Bash, Glob, Grep, WebFetch, WebSearch, Task, AskUserQuestion
+---
+
+# /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
+
+## 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)
+
+Check if the current directory has existing code:
+
+```
+1. Run: ls to check directory contents
+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. Check if .planning/ already exists
+```
+
+**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
+- 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 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.
+
+**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
+
+**After gathering preferences:**
+
+1. Read the config template from `skills/begin/templates/config.json.tmpl`
+2. Apply the user's choices to the template
+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.
+
+---
+
+### 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`:**
+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
+
+---
+
+### Step 5: Research (delegated to subagents)
+
+Spawn parallel Task() subagents for research. Each researcher writes to `.planning/research/`.
+
+**Create `.planning/research/` directory first.**
+
+**For each research topic, spawn a Task():**
+
+```
+Task({
+  subagent_type: "pbr:researcher",
+  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.
+
+#### Researcher Prompt Template
+
+For each researcher, construct the prompt by reading the template and filling in placeholders:
+
+Read `skills/begin/templates/researcher-prompt.md.tmpl` for the prompt structure.
+
+**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",
+  model: "haiku",
+  prompt: <synthesis prompt>
+})
+```
+
+**NOTE**: The `pbr:synthesizer` subagent type auto-loads the agent definition. Do NOT inline it. Use `model: "haiku"` — synthesis is fast summarization work that doesn't need a large model.
+
+#### Synthesis Prompt Template
+
+Read `skills/begin/templates/synthesis-prompt.md.tmpl` for the prompt structure.
+
+**Placeholders to fill:**
+- `{List all .planning/research/*.md files that were created}` — list the research files produced in Step 5
+
+---
+
+### 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 in the format `{CATEGORY}-{NN}`:
+- `AUTH-01`: User can log in with Discord OAuth
+- `AUTH-02`: Protected routes redirect to login
+- `UI-01`: Dashboard shows player statistics
+- `UI-02`: Mobile-responsive layout
+
+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:**
+Read the template from `skills/begin/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",
+  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.
+
+#### Roadmap Prompt Template
+
+Read `skills/begin/templates/roadmap-prompt.md.tmpl` for the prompt structure.
+
+**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:**
+- Read `.planning/ROADMAP.md`
+- 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:
+
+**9a. Write PROJECT.md:**
+1. Read `skills/begin/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
+
+**9b. Write STATE.md:**
+1. Read `skills/begin/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).
+
+**9c. Write CONTEXT.md:**
+Create `.planning/CONTEXT.md` from information gathered during questioning:
+
+```markdown
+# Project Context
+
+## Locked Decisions
+{Technology choices, architecture decisions, and constraints that are NON-NEGOTIABLE}
+
+| Decision | Rationale | Locked By |
+|----------|-----------|-----------|
+| {e.g., "Use TypeScript"} | {User preference, team skill} | User |
+
+## User Constraints
+{Budget, timeline, skill level, hosting, team size}
+
+## Deferred Ideas
+{Features explicitly moved to v2 or out-of-scope}
+
+| Idea | Reason Deferred |
+|------|----------------|
+| {feature} | {reason} |
+```
+
+**9d. 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}
+- 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
+
+---
+
+## Completion
+
+After all steps complete, present the final summary:
+
+Use the branded stage banner from `references/ui-formatting.md`:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► PROJECT INITIALIZED ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+**{name}**
+
+{core value one-liner}
+
+Roadmap: {N} phases
+  1. {Phase 1 name}
+  2. {Phase 2 name}
+  ...
+
+Requirements: {N} committed, {M} deferred, {K} out-of-scope
+```
+
+Then use the "Next Up" routing block:
+```
+───────────────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Phase 1: {Name}** — {one-line goal}
+
+`/pbr:explore`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────────────
+
+**Also available:**
+- `/pbr:discuss 1` — talk through Phase 1 details before planning
+- `/pbr:plan 1` — jump straight to planning Phase 1
+- `/pbr:config` — adjust workflow settings
+
+───────────────────────────────────────────────────────────────
+```
+
+---
+
+## 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/phases/NN-*/` | Phase directories | Step 9 |

package/plugins/pbr/skills/begin/templates/PROJECT.md.tmpl

@@ -0,0 +1,33 @@
+# {project_name}
+
+## What This Is
+{2-3 sentences: current, accurate description}
+
+## Core Value
+{ONE sentence: the thing that matters most}
+
+## Requirements
+### Active (current scope)
+See: .planning/REQUIREMENTS.md
+
+### Out of Scope
+{Features explicitly excluded and why}
+
+## Context
+{Technical environment, prior work, constraints}
+
+## Constraints
+{Known constraints with rationale}
+
+## Key Decisions
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| {initial decisions from questioning} | {why} | -- Pending |
+
+## Milestones
+
+### Active
+- **{project_name} v1.0** -- Phases 1-{total} -- In progress
+
+### Completed
+(none yet)

package/plugins/pbr/skills/begin/templates/REQUIREMENTS.md.tmpl

@@ -0,0 +1,18 @@
+# Requirements: {project_name}
+
+## v1 Requirements (committed scope)
+
+### {Category}
+- [ ] **{CAT}-01**: {User-centric, testable requirement}
+
+## v2 Requirements (deferred)
+- **{CAT}-01**: {Deferred requirement with reason}
+
+## Out of Scope
+| Feature | Reason |
+|---------|--------|
+
+## Traceability
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| {REQ-ID} | -- | Pending |

package/plugins/pbr/skills/begin/templates/STATE.md.tmpl

@@ -0,0 +1,49 @@
+---
+version: 2
+current_phase: 1
+total_phases: {total}
+phase_slug: "{phase_1_slug}"
+phase_name: "{Phase 1 name}"
+status: "ready_to_plan"
+progress_percent: 0
+plans_total: 0
+plans_complete: 0
+last_activity: "{date}"
+last_command: "/pbr:begin"
+blockers: []
+active_checkpoint: null
+---
+# Project State
+
+## Project Reference
+See: .planning/PROJECT.md (updated {date})
+**Core value:** {One-liner}
+**Current focus:** Phase 1 - {name}
+
+## Current Position
+Phase: 1 of {total} ({Phase 1 name})
+Plan: 0 of 0 in current phase
+Status: Ready to plan
+Last activity: {date} -- Project initialized
+Progress: [░░░░░░░░░░░░░░░░░░░░] 0%
+
+## Accumulated Context
+
+### Decisions
+{Decisions from initialization}
+
+### Pending Todos
+None yet
+
+### Blockers/Concerns
+None yet
+
+## Milestone
+Current: {project_name} v1.0
+Phases: 1-{total}
+Status: In progress
+
+## Session Continuity
+Last session: {timestamp}
+Stopped at: Project initialization complete
+Resume file: None