@sienklogic/plan-build-run 2.21.0 → 2.21.2

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

@@ -1,288 +0,0 @@
-<!-- canonical: ../../pbr/references/plan-format.md -->
-# 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)"
-requirement_ids:
-  - "P02-G1"
-  - "P02-G2"
----
-```
-
-### 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)"` |
-| `requirement_ids` | NO | array | Requirement IDs from REQUIREMENTS.md or ROADMAP.md goal IDs that this plan addresses. Enables bidirectional traceability between plans and requirements/goals. |
-| `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/copilot-pbr/references/planning-config.md

@@ -1,214 +0,0 @@
-<!-- canonical: ../../pbr/references/planning-config.md -->
-# 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` |