@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/references/plan-format.md

@@ -0,0 +1,283 @@
+# Plan Format Reference
+
+Complete reference for the XML task specification used in Plan-Build-Run plan files.
+
+---
+
+## Plan File Structure
+
+Every plan file has two sections:
+1. **YAML Frontmatter** — metadata about the plan
+2. **XML Tasks** — the executable task specifications
+
+---
+
+## YAML Frontmatter
+
+```yaml
+---
+phase: "02-authentication"
+plan: "02-01"
+type: "feature"
+wave: 1
+depends_on: []
+files_modified:
+  - "src/auth/discord.ts"
+  - "src/middleware/auth.ts"
+autonomous: true
+discovery: 1
+gap_closure: false
+must_haves:
+  truths:
+    - "User can authenticate via Discord OAuth"
+    - "JWT token is set in httpOnly cookie"
+  artifacts:
+    - "src/auth/discord.ts: >50 lines"
+    - "src/middleware/auth.ts: >30 lines"
+  key_links:
+    - "Auth middleware applied to protected routes"
+    - "Login button calls authenticateWithDiscord()"
+provides:
+  - "AuthService class"
+  - "POST /api/auth/login endpoint"
+  - "requireAuth() middleware"
+consumes:
+  - "Database connection (from plan 01-01)"
+---
+```
+
+### Frontmatter Fields
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `phase` | YES | string | Phase directory name (e.g., "02-authentication") |
+| `plan` | YES | string | Plan ID: `{phase_num}-{plan_num}` (e.g., "02-01") |
+| `type` | YES | enum | `feature`, `bugfix`, `refactor`, `infrastructure`, `docs` |
+| `wave` | YES | int | Execution wave (1 = independent, 2+ = has deps) |
+| `depends_on` | YES | array | Plan IDs that must complete first. `[]` if Wave 1. |
+| `files_modified` | YES | array | All files this plan creates or modifies |
+| `autonomous` | YES | bool | `true` if no human checkpoints |
+| `discovery` | NO | int | Research level: 0=skip, 1=quick, 2=standard, 3=deep. Default: 1 |
+| `gap_closure` | NO | bool | `true` if this is a gap-closure plan. Default: false |
+| `must_haves` | YES | object | Goal-backward derivation |
+| `must_haves.truths` | YES | array | Observable truths that must be true when done |
+| `must_haves.artifacts` | YES | array | Files/modules that must exist. Append `: >N lines` for size hints. |
+| `must_haves.key_links` | YES | array | Connections between components. Append `: grep command` for verification. |
+| `provides` | NO | array | What this plan exports for other plans to consume (classes, endpoints, modules) |
+| `consumes` | NO | array | What this plan needs from prior plans. Format: `"Thing (from plan XX-YY)"` |
+| `dependency_fingerprints` | NO | object | Hashes of dependency phase SUMMARY.md files at plan-creation time. Used to detect stale plans. |
+
+---
+
+## Summary Section
+
+Every plan file MUST end with a `## Summary` section after all XML tasks. This section provides a compact overview (~500 tokens) for injection into executor prompts, avoiding the need to inline the full plan (~1,500 tokens).
+
+Format:
+
+```
+## Summary
+
+**Plan {plan_id}**: {1-sentence description of what this plan does}
+
+**Tasks:**
+1. {task_id}: {task name} -- {files touched}
+2. {task_id}: {task name} -- {files touched}
+3. {task_id}: {task name} -- {files touched}
+
+**Key files:** {comma-separated list of all files_modified}
+
+**Must-haves:** {comma-separated list of truths from frontmatter}
+
+**Provides:** {comma-separated list from provides field}
+
+**Consumes:** {comma-separated list from consumes field, or "None"}
+```
+
+The Summary section is generated by the planner agent at plan creation time. It is a denormalized view of plan metadata -- if the plan is revised, the Summary must also be updated.
+
+---
+
+## Task Types
+
+### Standard Auto Task
+
+```xml
+<task id="02-01-T1" type="auto" complexity="medium">
+  <name>Create Discord OAuth client module</name>
+  <files>
+    src/auth/discord.ts
+    src/auth/types.ts
+  </files>
+  <action>
+    1. Create file `src/auth/types.ts`
+       - Export interface `DiscordUser` with fields: id, username, avatar, email
+       - Export interface `AuthTokens` with fields: accessToken, refreshToken, expiresAt
+
+    2. Create file `src/auth/discord.ts`
+       - Import `OAuth2Client` from `discord-oauth2`
+       - Import `DiscordUser`, `AuthTokens` from `./types`
+       - Export async function `authenticateWithDiscord(code: string): Promise<DiscordUser>`
+         - Create OAuth2Client with DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET from env
+         - Exchange authorization code for access token
+         - Fetch user profile: GET /api/users/@me
+         - Return DiscordUser object
+       - Export function `getDiscordAuthUrl(): string`
+         - Build OAuth2 URL with scopes: identify, email
+         - Include DISCORD_REDIRECT_URI from env
+
+    3. Add to `.env.example`:
+       DISCORD_CLIENT_ID=
+       DISCORD_CLIENT_SECRET=
+       DISCORD_REDIRECT_URI=http://localhost:3000/auth/callback
+  </action>
+  <verify>
+    npx tsc --noEmit
+    ls src/auth/discord.ts
+    ls src/auth/types.ts
+  </verify>
+  <done>Discord OAuth client module exists and compiles without errors</done>
+</task>
+```
+
+### TDD Task
+
+```xml
+<task id="02-01-T2" type="auto" tdd="true" complexity="medium">
+  <name>Implement auth middleware with TDD</name>
+  <files>
+    src/middleware/auth.ts
+    tests/middleware/auth.test.ts
+  </files>
+  <action>
+    RED:
+    1. Create `tests/middleware/auth.test.ts`
+       - Test: "rejects request without token" — expect 401
+       - Test: "rejects request with invalid token" — expect 401
+       - Test: "passes request with valid token" — expect next() called
+
+    GREEN:
+    2. Create `src/middleware/auth.ts`
+       - Export function `requireAuth(req, res, next)`
+       - Extract JWT from httpOnly cookie
+       - Verify token with jsonwebtoken
+       - If valid: attach user to req, call next()
+       - If invalid: respond 401
+
+    REFACTOR:
+    3. Extract token verification into `verifyToken()` helper
+  </action>
+  <verify>
+    npm test -- --grep "auth middleware"
+  </verify>
+  <done>Auth middleware rejects invalid tokens and passes valid tokens</done>
+</task>
+```
+
+### Checkpoint: Human Verify
+
+```xml
+<task id="03-02-T3" type="checkpoint:human-verify">
+  <name>Verify OAuth callback flow</name>
+  <files>
+    src/pages/auth/callback.ts
+  </files>
+  <action>
+    1. Create the OAuth callback page at `src/pages/auth/callback.ts`
+    2. Wire it to call `authenticateWithDiscord()` with the authorization code
+    3. On success: set JWT cookie and redirect to dashboard
+    4. On failure: redirect to login with error message
+  </action>
+  <verify>
+    what-built: OAuth callback page that exchanges Discord auth code for JWT
+    how-to-verify: |
+      1. Click "Login with Discord" button
+      2. Authorize the application in Discord
+      3. Verify you are redirected to the dashboard
+      4. Check browser cookies for JWT token
+    resume-signal: "User confirms OAuth flow works end-to-end"
+  </verify>
+  <done>User can complete full Discord OAuth login flow</done>
+</task>
+```
+
+### Checkpoint: Decision
+
+```xml
+<task id="04-01-T1" type="checkpoint:decision">
+  <name>Choose database migration strategy</name>
+  <files></files>
+  <action>
+    Present the user with the migration strategy options after research.
+  </action>
+  <verify>
+    decision: "Which migration strategy to use for production database?"
+    context: "We need to decide how to handle schema changes in production."
+    options: |
+      A) Prisma Migrate — automatic migrations, good for development, requires care in production
+      B) Manual SQL — full control, more work, explicit about what changes
+      C) TypeORM migrations — auto-generated from entities, reversible
+    resume-signal: "User selects option A, B, or C"
+  </verify>
+  <done>Database migration strategy decided and documented in CONTEXT.md</done>
+</task>
+```
+
+### Checkpoint: Human Action
+
+```xml
+<task id="05-03-T2" type="checkpoint:human-action">
+  <name>Configure production environment</name>
+  <files>
+    .env.production
+  </files>
+  <action>
+    1. Create `.env.production.example` with all required variables listed
+    2. Document each variable's purpose in comments
+  </action>
+  <verify>
+    what-needed: "Production environment variables must be set"
+    how-to-do: |
+      1. Copy `.env.production.example` to `.env.production`
+      2. Fill in production values for:
+         - DATABASE_URL (production database connection string)
+         - DISCORD_CLIENT_ID (production Discord app)
+         - DISCORD_CLIENT_SECRET (production Discord app)
+         - JWT_SECRET (generate with: openssl rand -base64 32)
+    resume-signal: "User confirms .env.production is configured"
+  </verify>
+  <done>Production environment is configured with real credentials</done>
+</task>
+```
+
+---
+
+## The 5 Mandatory Elements
+
+Every task MUST have ALL 5. No exceptions.
+
+| Element | Purpose | Rules |
+|---------|---------|-------|
+| `<name>` | What the task does | Imperative verb phrase. Short. |
+| `<files>` | Files touched | One per line. Actual file paths. |
+| `<action>` | How to do it | Numbered steps. Specific. Code snippets for complex work. |
+| `<verify>` | How to check | Executable shell commands. Or checkpoint format. |
+| `<done>` | How to know it worked | Observable user/system behavior. Maps to a must-have. |
+
+---
+
+## Task ID Format
+
+```
+{plan_id}-T{sequential_number}
+
+Examples:
+  02-01-T1  — Phase 02, Plan 01, Task 1
+  02-01-T2  — Phase 02, Plan 01, Task 2
+  03-02-T1  — Phase 03, Plan 02, Task 1
+```
+
+Task IDs are unique within a phase. They are used for:
+- Commit message references
+- Checkpoint continuation references
+- SUMMARY.md task result tracking

package/plugins/pbr/references/planning-config.md

@@ -0,0 +1,213 @@
+# Planning Config Reference
+
+Schema, fields, defaults, and behavioral effects of Plan-Build-Run's `config.json`.
+
+---
+
+## Overview
+
+Plan-Build-Run's configuration lives at `.planning/config.json` in the project root. It is created by `/pbr:begin` and can be modified via `/pbr:config` or by editing the file directly. The config controls workflow behavior, model selection, parallelization, git integration, and confirmation gates.
+
+---
+
+## Schema Version
+
+```json
+{ "version": 2 }
+```
+
+The `version` field tracks schema migrations. Current version is `2`. When loading a config with an older version, Plan-Build-Run runs automatic migration (e.g., v1 to v2 adds missing fields with defaults, renames `model_profile` to per-agent `models` object).
+
+---
+
+## Top-Level Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `version` | number | `2` | Config schema version |
+| `context_strategy` | string | `"aggressive"` | Context budget strategy: `aggressive`, `balanced`, `minimal` |
+| `mode` | string | `"interactive"` | Workflow mode: `interactive` |
+| `depth` | string | `"standard"` | Research/planning depth: `quick`, `standard`, `comprehensive` |
+
+### depth
+
+Controls how thorough research and planning phases are:
+
+| Value | Behavior |
+|-------|----------|
+| `quick` | Minimal research, smaller plans, faster execution |
+| `standard` | Balanced research depth, standard plan detail |
+| `comprehensive` | Deep research with multiple sources, detailed plans with more tasks |
+
+### context_strategy
+
+Controls how aggressively Plan-Build-Run manages context budget:
+
+| Value | Behavior |
+|-------|----------|
+| `aggressive` | Proactive compaction warnings, strict context isolation, minimal file reads in main context |
+| `balanced` | Moderate context management with some inline reads |
+| `minimal` | Relaxed context management, more inline content allowed |
+
+---
+
+## features
+
+Boolean toggles that enable or disable specific workflow capabilities.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `structured_planning` | `true` | Use phased planning with ROADMAP and plan files |
+| `goal_verification` | `true` | Run verifier agent after builds to check goals are met |
+| `integration_verification` | `true` | Run cross-phase integration checks |
+| `context_isolation` | `true` | Isolate work into subagents to protect main context |
+| `atomic_commits` | `true` | Require one commit per task (vs. batched commits) |
+| `session_persistence` | `true` | Persist state across sessions via STATE.md |
+| `research_phase` | `true` | Run research before planning |
+| `plan_checking` | `true` | Run plan-checker agent before execution |
+| `tdd_mode` | `false` | Enable Test-Driven Development for all tasks (Red-Green-Refactor) |
+| `status_line` | `true` | Show status line in session UI |
+| `auto_continue` | `false` | Write `.auto-next` signal on phase completion for automatic continuation |
+| `auto_advance` | `false` | Chain build→review→plan automatically in autonomous mode (requires `mode: autonomous`) |
+| `team_discussions` | `false` | Enable team-based discussion workflows (never used for execution) |
+| `inline_verify` | `false` | Run per-task verification after each executor commit (opt-in, adds latency) |
+
+### Notable interactions
+
+- `goal_verification: false` skips the post-build verification step. The build skill appends a note suggesting `/pbr:review` manually.
+- `tdd_mode: true` causes all task types to follow Red-Green-Refactor, producing 3 commits per task instead of 1.
+- `auto_continue: true` writes a `.planning/.auto-next` file containing the next command (e.g., `/pbr:plan 4`), allowing wrapper scripts to chain phases.
+- `auto_advance: true` + `mode: autonomous` enables full phase cycling: build completes → auto-invoke review → if verification passes → auto-invoke plan for next phase. Hard stops at: checkpoints, verification gaps, errors, milestone boundaries.
+- `inline_verify: true` spawns a haiku-model verifier after each plan completes within a wave. Adds ~10-20s latency per plan but catches issues before dependent plans run.
+
+---
+
+## models
+
+Per-agent model selection. See `references/model-profiles.md` for full details.
+
+```json
+{
+  "models": {
+    "researcher": "sonnet",
+    "planner": "inherit",
+    "executor": "inherit",
+    "verifier": "sonnet",
+    "integration_checker": "sonnet",
+    "debugger": "inherit",
+    "mapper": "sonnet",
+    "synthesizer": "haiku"
+  }
+}
+```
+
+Valid values: `sonnet`, `opus`, `haiku`, `inherit`.
+
+---
+
+## parallelization
+
+Controls whether and how plans execute concurrently.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable parallel plan execution within a wave |
+| `plan_level` | boolean | `true` | Parallelize at plan level (multiple plans in same wave) |
+| `task_level` | boolean | `false` | Parallelize at task level within a plan (not currently used) |
+| `max_concurrent_agents` | number | `3` | Maximum simultaneous executor subagents |
+| `min_plans_for_parallel` | number | `2` | Minimum plans in a wave to trigger parallel execution |
+| `use_teams` | boolean | `false` | Use Agent Teams for coordination (discussion only, never execution) |
+
+### Behavior
+
+When `enabled: true` and a wave has >= `min_plans_for_parallel` plans, the build orchestrator spawns up to `max_concurrent_agents` executor Task() calls in parallel using `run_in_background: true`.
+
+When `enabled: false` or a wave has only 1 plan, executors run sequentially.
+
+Git lock conflicts can occur with parallel execution. Executors handle this with retry logic (wait 2s, max 3 attempts). If conflicts persist, reduce `max_concurrent_agents` to 1.
+
+---
+
+## planning
+
+Controls planning behavior and documentation.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `commit_docs` | boolean | `true` | Commit planning docs (SUMMARY, VERIFICATION) after builds |
+| `max_tasks_per_plan` | number | `3` | Maximum tasks per plan (keeps plans focused and atomic) |
+| `search_gitignored` | boolean | `false` | Include gitignored files in codebase scanning |
+
+### commit_docs
+
+When `true`, after all plans in a phase complete, the build orchestrator stages and commits planning artifacts:
+```
+docs({phase}): add build summaries and verification
+```
+
+When `false`, planning docs remain unstaged/uncommitted.
+
+---
+
+## git
+
+Controls git integration and branching.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `branching` | string | `"none"` | Branching strategy: `none`, `phase`, `milestone`, `disabled` |
+| `commit_format` | string | `"{type}({phase}-{plan}): {description}"` | Commit message template |
+| `phase_branch_template` | string | `"plan-build-run/phase-{phase}-{slug}"` | Phase branch naming |
+| `milestone_branch_template` | string | `"plan-build-run/{milestone}-{slug}"` | Milestone branch naming |
+| `mode` | string | `"enabled"` | Git mode: `enabled` or `disabled` |
+
+See `references/git-integration.md` for full branching strategy details.
+
+### mode: disabled
+
+When `git.mode` is `"disabled"`, no git commands are run at all -- no commits, no branching, no hook validation. Useful for prototyping or non-git projects.
+
+---
+
+## gates
+
+Confirmation gates that pause execution to ask the user before proceeding.
+
+| Field | Default | When Triggered |
+|-------|---------|----------------|
+| `confirm_project` | `true` | Before creating a new Plan-Build-Run project (`/pbr:begin`) |
+| `confirm_roadmap` | `true` | Before finalizing a roadmap |
+| `confirm_plan` | `true` | Before finalizing plans for a phase |
+| `confirm_execute` | `false` | Before starting phase execution (`/pbr:build`) |
+| `confirm_transition` | `true` | Before transitioning to the next phase |
+| `issues_review` | `true` | Before proceeding when issues are detected |
+
+Setting a gate to `false` makes that step automatic (no user prompt).
+
+---
+
+## safety
+
+Safety controls for destructive or external operations.
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `always_confirm_destructive` | boolean | `true` | Always ask before destructive git operations |
+| `always_confirm_external_services` | boolean | `true` | Always ask before calling external APIs or services |
+
+These cannot be disabled via `/pbr:config` -- they require manual editing of `config.json` as a deliberate action.
+
+---
+
+## Validation Rules
+
+When modifying config (via `/pbr:config` or direct edit):
+
+| Field | Valid Values |
+|-------|-------------|
+| `depth` | `quick`, `standard`, `comprehensive` |
+| `models.*` | `sonnet`, `inherit`, `haiku`, `opus` |
+| `context_strategy` | `aggressive`, `balanced`, `minimal` |
+| `git.branching` | `none`, `phase`, `milestone`, `disabled` |
+| `git.mode` | `enabled`, `disabled` |
+| All boolean fields | `true`, `false` |