@sienklogic/plan-build-run 2.53.0 → 2.55.0

package/plugins/codex-pbr/references/plan-authoring.md

@@ -0,0 +1,246 @@
+# Plan Authoring Guide
+
+Quality guidelines for writing executable plans. Used by planner and plan-checker.
+
+---
+
+## Action Writing Guidelines
+
+The `<action>` element is the most important part of the plan. It must be specific enough that the executor agent can follow it mechanically without making design decisions.
+
+### Good Action
+```xml
+<action>
+1. Create file `src/auth/discord.ts`
+2. Import `OAuth2Client` from `discord-oauth2` package
+3. Export async function `authenticateWithDiscord(code: string): Promise<User>`
+   - Create OAuth2Client with env vars: DISCORD_CLIENT_ID, DISCORD_CLIENT_SECRET
+   - Exchange authorization code for access token
+   - Fetch user profile from Discord API: GET /api/users/@me
+   - Return User object with fields: id, username, avatar, email
+4. Export function `getDiscordAuthUrl(): string`
+   - Build OAuth2 authorization URL with scopes: identify, email
+   - Include redirect URI from env: DISCORD_REDIRECT_URI
+   - Return the URL string
+5. Add to `.env.example`:
+   DISCORD_CLIENT_ID=
+   DISCORD_CLIENT_SECRET=
+   DISCORD_REDIRECT_URI=http://localhost:3000/auth/callback
+</action>
+```
+
+### Bad Action
+```xml
+<action>
+Set up Discord OAuth authentication.
+</action>
+```
+
+### Action Rules
+
+1. **Number the steps** -- executor follows them in order
+2. **Name specific files** -- never say "create necessary files"
+3. **Name specific functions/exports** -- never say "implement the auth logic"
+4. **Include type signatures** -- when the project uses TypeScript
+5. **Reference existing code** -- when modifying files, say what to modify
+6. **Include code snippets** -- for complex patterns or configurations
+7. **Specify environment variables** -- with example values
+8. **Note error handling** -- only when it's a critical part of the task
+
+---
+
+## Verify Command Guidelines
+
+The `<verify>` element must contain commands that the executor can run to check the task is complete.
+
+### Good Verify
+```xml
+<verify>
+npx tsc --noEmit
+npm run test -- --grep "discord auth"
+ls -la src/auth/discord.ts
+</verify>
+```
+
+### Bad Verify
+```xml
+<verify>
+Check that authentication works.
+</verify>
+```
+
+### Verify Rules
+
+1. **Must be executable** -- actual shell commands, not descriptions
+2. **Must be deterministic** -- same result every time if code is correct
+3. **Prefer automated checks** -- type checking, tests, linting
+4. **Include existence checks** -- `ls` for created files
+5. **Include build checks** -- `npx tsc --noEmit` for TypeScript
+6. **Avoid interactive commands** -- no commands requiring user input
+
+---
+
+## Done Condition Guidelines
+
+The `<done>` element describes the observable outcome, not the implementation activity.
+
+### Good Done
+- "User can authenticate via Discord OAuth and is redirected to dashboard"
+- "Auth middleware rejects invalid tokens and passes valid tokens"
+- "All 12 unit tests pass for the auth module"
+
+### Bad Done
+- "Code was written"
+- "File was created"
+- "Feature is implemented"
+
+### Done Rules
+
+1. **Maps to a must-have** -- every done condition traces back to a frontmatter must-have
+2. **Observable** -- describes a state of the system, not an activity
+3. **Falsifiable** -- you can check whether it's true or false
+4. **User-oriented** -- prefer "user can..." over "code does..."
+
+---
+
+## Scope Limits
+
+### Per-Plan Limits
+
+| Constraint | Limit | Rationale |
+|-----------|-------|-----------|
+| Tasks per plan | **2-3** | Keeps plans atomic and recoverable |
+| Files per plan | **5-8** | Limits blast radius of failures |
+| Dependencies | **3 max** | Avoids deep dependency chains |
+
+### When to Split
+
+- More than 3 tasks? Split.
+- More than 8 files? Split.
+- Tasks in different functional areas? Split.
+- Some tasks need human checkpoints, others don't? Split into autonomous and checkpoint plans.
+
+### Split Signals
+
+| Signal | Action |
+|--------|--------|
+| >3 tasks needed | Split by subsystem -- one plan per subsystem |
+| Multiple unrelated subsystems | One plan per subsystem |
+| >5 files per task | Task is too big -- break it down |
+| Checkpoint + implementation in same plan | Separate the checkpoint into its own plan |
+| Discovery research + implementation | Separate plans -- research plan first |
+
+---
+
+## Discovery Levels
+
+When a plan requires research before execution, set the `discovery` field in plan frontmatter. Default is 1 for most plans.
+
+| Level | Name | Description | Executor Behavior |
+|-------|------|-------------|-------------------|
+| 0 | Skip | No research needed | Execute immediately |
+| 1 | Quick | Fast verification | Check official docs for 1-2 specific questions |
+| 2 | Standard | Normal research | Spawn researcher for phase research |
+| 3 | Deep | Extensive investigation | Full research cycle before execution |
+
+### Level 0 -- Skip
+**When to use**: Simple refactors, documentation updates, file renames, configuration tweaks, or any task where the implementation approach is unambiguous from the plan's `<action>` steps alone.
+
+### Level 1 -- Quick (default)
+**When to use**: Standard feature work where the technology is known but specific API signatures, config options, or version-specific behavior need a quick check.
+
+### Level 2 -- Standard
+**When to use**: Work involving unfamiliar libraries, new integration patterns, or approaches the executor hasn't seen in this codebase before.
+
+### Level 3 -- Deep
+**When to use**: High-risk or architecturally significant work where getting the approach wrong would require substantial rework.
+
+---
+
+## TDD Decision Heuristic
+
+When assigning `tdd="true"` or `tdd="false"` on a task, apply this test:
+
+> **Can you write `expect(fn(input)).toBe(output)` before writing `fn`?**
+> Yes → `tdd="true"`. No → `tdd="false"`.
+
+### When TDD Adds Value
+
+- Pure functions and data transformations
+- Business logic with defined inputs/outputs
+- API response parsing and validation
+- State machines and workflow transitions
+- Utility functions and helpers
+
+### When to Skip TDD
+
+- UI rendering and layout (test after)
+- Configuration and environment setup
+- Glue code wiring modules together
+- Simple CRUD with no business logic
+- File system operations and I/O plumbing
+- One-off scripts and migrations
+
+When the global config `features.tdd_mode: true` is set, all tasks default to TDD. The planner should still set `tdd="false"` on tasks matching the skip list above — the global flag is a project preference, not a mandate for every task.
+
+---
+
+## Dependency Graph Rules
+
+### File Conflict Detection
+
+Two plans CONFLICT if their `files_modified` lists overlap. Conflicting plans:
+- MUST be in different waves (cannot run in parallel)
+- MUST have explicit `depends_on` relationship
+- Later plan's `<action>` must reference what the earlier plan produces
+
+### Circular Dependencies
+
+**NEVER create circular dependencies.** If you detect a potential cycle, restructure the plans to break it. Common resolution: merge the circular plans into one, or extract the shared dependency into its own plan.
+
+---
+
+## @file: Output Pattern (Large Payloads)
+
+When a `pbr-tools` CLI command produces output exceeding 50,000 characters, the tool writes
+the JSON payload to a temporary file instead of emitting it inline. It then prints a single
+line of the form:
+
+```
+@file:/tmp/pbr-1234567890.json
+```
+
+This prevents stdout overflow in environments with limited buffer sizes (hooks, Task() runners).
+
+### Verify Step Pattern
+
+If a plan's `<verify>` step calls `pbr-tools` and inspects the output, guard against the
+`@file:` case:
+
+```bash
+OUT=$(node ${CLAUDE_PLUGIN_ROOT}/scripts/pbr-tools.js state load)
+if echo "$OUT" | grep -q '^@file:'; then
+  OUT=$(cat "${OUT#@file:}")
+fi
+echo "$OUT" | grep '"status"'
+```
+
+### Agent Prompt Handling
+
+When an agent receives `@file:` output from a spawned tool call, it must read the referenced
+file to obtain the actual JSON payload. The `@file:` prefix is a signal — not a path fragment
+to be appended to another command.
+
+Plan actions that spawn `pbr-tools` subcommands should instruct the agent:
+
+> If the output starts with `@file:`, read the file at that path to get the full JSON response.
+
+---
+
+## Context Fidelity Checklist
+
+Before writing plan files, verify context compliance:
+
+1. **Locked decision coverage**: For each locked decision in CONTEXT.md, identify the task that implements it.
+2. **Deferred idea exclusion**: Scan all tasks -- no task should implement a deferred idea.
+3. **Discretion area handling**: Each "Claude's Discretion" item should be addressed in at least one task.

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

@@ -0,0 +1,313 @@
+# 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"
+closes_issues:
+  - 42
+  - 57
+---
+```
+
+### 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. |
+| `data_contracts` | NO | array | Cross-boundary parameter mappings for calls where arguments originate from external boundaries. Format: `"param: source (context) [fallback]"` |
+| `closes_issues` | NO | number[] | GitHub issue numbers to close when this plan's final commit lands. Default: `[]` |
+
+### Data Contracts
+
+When a task's `<action>` includes calls across module boundaries where arguments come from external sources (hook stdin, env vars, API params, config files), document the parameter-to-source mapping in `data_contracts` frontmatter and in the `<action>` step itself.
+
+Example frontmatter:
+
+```yaml
+data_contracts:
+  - "sessionId: data.session_id (hook stdin) [undefined in CLI context]"
+  - "config: configLoad(planningDir) (disk) [resolveConfig(undefined)]"
+```
+
+Example in `<action>`:
+
+```
+3. Call classifyArtifact(llmConfig, planningDir, content, fileType, data.session_id)
+   Data contract: sessionId ← data.session_id from hook stdin (undefined in CLI context)
+```
+
+**When to apply:** Any call where caller and callee are in different modules AND at least one argument originates from an external boundary. Internal helper calls within the same module do not need contracts.
+
+---
+
+## 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