@sienklogic/plan-build-run 2.0.0 → 2.0.1

package/plugins/pbr/references/integration-patterns.md

@@ -1,117 +1,117 @@
-# Integration Patterns Reference
-
-Technology-specific grep/search patterns and E2E flow templates for integration-checker.
-
-## E2E Flow Templates
-
-### Authentication Flow
-
-| Step | Check |
-|------|-------|
-| 1. Login form exists | Component with email/password fields or OAuth button |
-| 2. Form submits to auth endpoint | onSubmit calls auth API or redirects to OAuth |
-| 3. Backend validates credentials | Route handler with validation logic |
-| 4. Token/session created | JWT generation or session creation |
-| 5. Token stored client-side | Cookie set or localStorage/state |
-| 6. Requests include auth | Auth header or cookie sent with API calls |
-| 7. Protected routes accessible | Auth middleware passes with valid token |
-| 8. Invalid auth redirects | 401 or redirect when no/invalid token |
-
-### Data Display Flow
-
-| Step | Check |
-|------|-------|
-| 1. Page/component renders | Component file with JSX/HTML |
-| 2. Component requests data | useEffect/useSWR/useQuery with API call |
-| 3. API route handles request | Route handler exists for endpoint |
-| 4. Handler queries data source | Database query or service call |
-| 5. Data returned | res.json() or return with data |
-| 6. Component renders data | Data mapped to JSX elements |
-| 7. Loading state handled | Loading indicator while fetching |
-| 8. Error state handled | Error message on failure |
-
-### Form Submission Flow
-
-| Step | Check |
-|------|-------|
-| 1. Form component exists | Form element with inputs |
-| 2. Client-side validation | Schema or manual checks |
-| 3. Submit calls API | fetch/axios with form data |
-| 4. Server validates input | Input validation in handler |
-| 5. Server processes request | Business logic (CRUD) |
-| 6. Database mutation | Write operation |
-| 7. Success response | Response with success status |
-| 8. UI reflects success | Toast/redirect/state update |
-| 9. Error handling | Server errors shown in form |
-
-### CRUD Flow (per entity)
-
-| Step | Check |
-|------|-------|
-| 1. List view | Component renders list |
-| 2. Create form | Component with creation UI |
-| 3. Create API | POST route with handler |
-| 4. Read/detail API | GET route with handler |
-| 5. Update form | Component with edit UI |
-| 6. Update API | PUT/PATCH route with handler |
-| 7. Delete action | Delete button/handler |
-| 8. Delete API | DELETE route with handler |
-| 9. Frontend calls all CRUD | All operations invoked from UI |
-| 10. Auth on all ops | All operations require auth (if applicable) |
-
-## Technology-Specific Search Patterns
-
-### React / Next.js
-
-```bash
-# Component imports and usage
-grep -rn "import.*{Component}" src/ --include="*.tsx"
-grep -rn "<{Component}" src/ --include="*.tsx"
-
-# Context providers (must wrap the app)
-grep -rn "Provider" src/app/layout.tsx src/pages/_app.tsx 2>/dev/null
-
-# Client vs Server components (Next.js)
-grep -rn "'use client'\|\"use client\"" src/ --include="*.tsx"
-
-# Next.js API routes (App Router)
-find src/app/api -name "route.ts" 2>/dev/null
-
-# Next.js middleware
-find src -name "middleware.ts" -maxdepth 2 2>/dev/null
-
-# Data fetching hooks
-grep -rn "useSWR\|useQuery\|useMutation\|getServerSideProps\|getStaticProps" src/ --include="*.tsx" --include="*.ts"
-```
-
-### Express / Node.js API
-
-```bash
-# Route registration on main app
-grep -rn "app\.use\|router\.use" src/ --include="*.ts" --include="*.js"
-
-# Middleware chain order (important for auth)
-grep -rn "\.use(" src/app.ts src/server.ts src/index.ts 2>/dev/null
-
-# Error handling middleware (must be last)
-grep -rn "err.*req.*res.*next\|ErrorHandler\|errorMiddleware" src/ --include="*.ts" --include="*.js"
-
-# Database connection used in routes
-grep -rn "db\.\|prisma\.\|knex\.\|mongoose\.\|sequelize\." src/ --include="*.ts" --include="*.js" | grep -v "node_modules"
-```
-
-### Python (Django / Flask / FastAPI)
-
-```bash
-# URL patterns
-grep -rn "urlpatterns\|path(\|route(" */urls.py **/urls.py 2>/dev/null
-
-# View imports
-grep -rn "from.*views.*import\|from.*api.*import" */urls.py **/urls.py 2>/dev/null
-
-# Middleware registration
-grep -rn "MIDDLEWARE" */settings.py 2>/dev/null
-
-# Model imports in views
-grep -rn "from.*models.*import" */views.py **/views.py 2>/dev/null
-```
+# Integration Patterns Reference
+
+Technology-specific grep/search patterns and E2E flow templates for integration-checker.
+
+## E2E Flow Templates
+
+### Authentication Flow
+
+| Step | Check |
+|------|-------|
+| 1. Login form exists | Component with email/password fields or OAuth button |
+| 2. Form submits to auth endpoint | onSubmit calls auth API or redirects to OAuth |
+| 3. Backend validates credentials | Route handler with validation logic |
+| 4. Token/session created | JWT generation or session creation |
+| 5. Token stored client-side | Cookie set or localStorage/state |
+| 6. Requests include auth | Auth header or cookie sent with API calls |
+| 7. Protected routes accessible | Auth middleware passes with valid token |
+| 8. Invalid auth redirects | 401 or redirect when no/invalid token |
+
+### Data Display Flow
+
+| Step | Check |
+|------|-------|
+| 1. Page/component renders | Component file with JSX/HTML |
+| 2. Component requests data | useEffect/useSWR/useQuery with API call |
+| 3. API route handles request | Route handler exists for endpoint |
+| 4. Handler queries data source | Database query or service call |
+| 5. Data returned | res.json() or return with data |
+| 6. Component renders data | Data mapped to JSX elements |
+| 7. Loading state handled | Loading indicator while fetching |
+| 8. Error state handled | Error message on failure |
+
+### Form Submission Flow
+
+| Step | Check |
+|------|-------|
+| 1. Form component exists | Form element with inputs |
+| 2. Client-side validation | Schema or manual checks |
+| 3. Submit calls API | fetch/axios with form data |
+| 4. Server validates input | Input validation in handler |
+| 5. Server processes request | Business logic (CRUD) |
+| 6. Database mutation | Write operation |
+| 7. Success response | Response with success status |
+| 8. UI reflects success | Toast/redirect/state update |
+| 9. Error handling | Server errors shown in form |
+
+### CRUD Flow (per entity)
+
+| Step | Check |
+|------|-------|
+| 1. List view | Component renders list |
+| 2. Create form | Component with creation UI |
+| 3. Create API | POST route with handler |
+| 4. Read/detail API | GET route with handler |
+| 5. Update form | Component with edit UI |
+| 6. Update API | PUT/PATCH route with handler |
+| 7. Delete action | Delete button/handler |
+| 8. Delete API | DELETE route with handler |
+| 9. Frontend calls all CRUD | All operations invoked from UI |
+| 10. Auth on all ops | All operations require auth (if applicable) |
+
+## Technology-Specific Search Patterns
+
+### React / Next.js
+
+```bash
+# Component imports and usage
+grep -rn "import.*{Component}" src/ --include="*.tsx"
+grep -rn "<{Component}" src/ --include="*.tsx"
+
+# Context providers (must wrap the app)
+grep -rn "Provider" src/app/layout.tsx src/pages/_app.tsx 2>/dev/null
+
+# Client vs Server components (Next.js)
+grep -rn "'use client'\|\"use client\"" src/ --include="*.tsx"
+
+# Next.js API routes (App Router)
+find src/app/api -name "route.ts" 2>/dev/null
+
+# Next.js middleware
+find src -name "middleware.ts" -maxdepth 2 2>/dev/null
+
+# Data fetching hooks
+grep -rn "useSWR\|useQuery\|useMutation\|getServerSideProps\|getStaticProps" src/ --include="*.tsx" --include="*.ts"
+```
+
+### Express / Node.js API
+
+```bash
+# Route registration on main app
+grep -rn "app\.use\|router\.use" src/ --include="*.ts" --include="*.js"
+
+# Middleware chain order (important for auth)
+grep -rn "\.use(" src/app.ts src/server.ts src/index.ts 2>/dev/null
+
+# Error handling middleware (must be last)
+grep -rn "err.*req.*res.*next\|ErrorHandler\|errorMiddleware" src/ --include="*.ts" --include="*.js"
+
+# Database connection used in routes
+grep -rn "db\.\|prisma\.\|knex\.\|mongoose\.\|sequelize\." src/ --include="*.ts" --include="*.js" | grep -v "node_modules"
+```
+
+### Python (Django / Flask / FastAPI)
+
+```bash
+# URL patterns
+grep -rn "urlpatterns\|path(\|route(" */urls.py **/urls.py 2>/dev/null
+
+# View imports
+grep -rn "from.*views.*import\|from.*api.*import" */urls.py **/urls.py 2>/dev/null
+
+# Middleware registration
+grep -rn "MIDDLEWARE" */settings.py 2>/dev/null
+
+# Model imports in views
+grep -rn "from.*models.*import" */views.py **/views.py 2>/dev/null
+```

package/plugins/pbr/references/model-profiles.md

@@ -1,99 +1,99 @@
-# Model Profiles Reference
-
-How Plan-Build-Run maps agents to models and how to configure model selection.
-
----
-
-## Agent-to-Model Mapping
-
-Each Plan-Build-Run agent has a default model specified in its agent definition frontmatter (`model:` field). These defaults are overridden by the `models` section of `config.json`.
-
-### Default Agent Models
-
-| Agent | Default Model | Rationale |
-|-------|---------------|-----------|
-| `researcher` | `sonnet` | Research requires strong reasoning for source evaluation and synthesis |
-| `planner` | `inherit` | Planning is complex; inherits the session's primary model |
-| `executor` | `inherit` | Execution needs the full capability of the session model |
-| `verifier` | `sonnet` | Verification needs solid reasoning but not the heaviest model |
-| `integration-checker` | `sonnet` | Cross-phase analysis requires strong pattern matching |
-| `plan-checker` | `sonnet` | Plan quality analysis needs good analytical capability |
-| `debugger` | `inherit` | Debugging is complex; inherits session model |
-| `codebase-mapper` | `sonnet` | Codebase analysis requires thorough reasoning |
-| `synthesizer` | `haiku` | Synthesis is mechanical combination; speed over depth |
-| `general` | `inherit` | Lightweight utility; inherits session model |
-
-The `inherit` value means the agent uses whatever model the parent session is running (typically the user's configured Claude model).
-
----
-
-## Model Profile Presets
-
-The `/pbr:config model-profile {preset}` command sets all agent models at once using a preset:
-
-| Profile | Researcher | Planner | Executor | Verifier | Int-Checker | Debugger | Mapper | Synthesizer |
-|---------|-----------|---------|----------|----------|-------------|----------|--------|-------------|
-| `quality` | opus | opus | opus | opus | sonnet | opus | sonnet | sonnet |
-| `balanced` | sonnet | inherit | inherit | sonnet | sonnet | inherit | sonnet | haiku |
-| `budget` | haiku | haiku | haiku | haiku | haiku | haiku | haiku | haiku |
-| `adaptive` | sonnet | sonnet | inherit | sonnet | haiku | inherit | haiku | haiku |
-
-### Preset Descriptions
-
-- **quality**: Maximum capability across all agents. Best results but highest token cost. Use for critical projects or complex architectures.
-- **balanced**: The default preset. Front-loads intelligence in research and verification, inherits session model for planning and execution. Good general-purpose choice.
-- **budget**: All agents use haiku. Fastest and cheapest, but reduced quality for complex reasoning tasks. Suitable for well-defined, mechanical work.
-- **adaptive**: Front-loads intelligence in research and planning (where decisions matter most), uses lighter models for mechanical execution and verification. Good cost-quality tradeoff.
-
----
-
-## Configuring Models
-
-### Per-Agent Configuration
-
-Set an individual agent's model via `/pbr:config`:
-
-```
-/pbr:config model executor sonnet
-/pbr:config model verifier opus
-```
-
-Or edit `config.json` directly:
-
-```json
-{
-  "models": {
-    "researcher": "sonnet",
-    "planner": "inherit",
-    "executor": "inherit",
-    "verifier": "sonnet",
-    "integration_checker": "sonnet",
-    "debugger": "inherit",
-    "mapper": "sonnet",
-    "synthesizer": "haiku"
-  }
-}
-```
-
-### Valid Model Values
-
-| Value | Meaning |
-|-------|---------|
-| `sonnet` | Claude Sonnet (4.5/4.6) -- balanced speed and capability |
-| `opus` | Claude Opus (4.6) -- highest capability, slower |
-| `haiku` | Claude Haiku (4.5) -- fastest, lower capability |
-| `inherit` | Use the session's primary model (whatever the user is running) |
-
-Note: Claude Code 2.1.45+ supports Sonnet 4.6. Model values are abstract names — Claude Code resolves them to the latest available version.
-
----
-
-## Model Selection in Skill Orchestration
-
-Skills that spawn subagents use the `model` parameter in `Task()` calls. Some skills hardcode a lighter model for specific tasks:
-
-- **Build skill**: Spawns inline verifiers with `model: "haiku"` for quick spot-checks
-- **Build skill**: Spawns codebase mapper updates with `model: "haiku"` for incremental map refreshes
-- **Plan skill**: Uses the configured `planner` model for main planning work
-
-The `subagent_type` parameter automatically loads the agent definition, and the model from `config.json` takes precedence over the agent's default `model:` frontmatter field.
+# Model Profiles Reference
+
+How Plan-Build-Run maps agents to models and how to configure model selection.
+
+---
+
+## Agent-to-Model Mapping
+
+Each Plan-Build-Run agent has a default model specified in its agent definition frontmatter (`model:` field). These defaults are overridden by the `models` section of `config.json`.
+
+### Default Agent Models
+
+| Agent | Default Model | Rationale |
+|-------|---------------|-----------|
+| `researcher` | `sonnet` | Research requires strong reasoning for source evaluation and synthesis |
+| `planner` | `inherit` | Planning is complex; inherits the session's primary model |
+| `executor` | `inherit` | Execution needs the full capability of the session model |
+| `verifier` | `sonnet` | Verification needs solid reasoning but not the heaviest model |
+| `integration-checker` | `sonnet` | Cross-phase analysis requires strong pattern matching |
+| `plan-checker` | `sonnet` | Plan quality analysis needs good analytical capability |
+| `debugger` | `inherit` | Debugging is complex; inherits session model |
+| `codebase-mapper` | `sonnet` | Codebase analysis requires thorough reasoning |
+| `synthesizer` | `haiku` | Synthesis is mechanical combination; speed over depth |
+| `general` | `inherit` | Lightweight utility; inherits session model |
+
+The `inherit` value means the agent uses whatever model the parent session is running (typically the user's configured Claude model).
+
+---
+
+## Model Profile Presets
+
+The `/pbr:config model-profile {preset}` command sets all agent models at once using a preset:
+
+| Profile | Researcher | Planner | Executor | Verifier | Int-Checker | Debugger | Mapper | Synthesizer |
+|---------|-----------|---------|----------|----------|-------------|----------|--------|-------------|
+| `quality` | opus | opus | opus | opus | sonnet | opus | sonnet | sonnet |
+| `balanced` | sonnet | inherit | inherit | sonnet | sonnet | inherit | sonnet | haiku |
+| `budget` | haiku | haiku | haiku | haiku | haiku | haiku | haiku | haiku |
+| `adaptive` | sonnet | sonnet | inherit | sonnet | haiku | inherit | haiku | haiku |
+
+### Preset Descriptions
+
+- **quality**: Maximum capability across all agents. Best results but highest token cost. Use for critical projects or complex architectures.
+- **balanced**: The default preset. Front-loads intelligence in research and verification, inherits session model for planning and execution. Good general-purpose choice.
+- **budget**: All agents use haiku. Fastest and cheapest, but reduced quality for complex reasoning tasks. Suitable for well-defined, mechanical work.
+- **adaptive**: Front-loads intelligence in research and planning (where decisions matter most), uses lighter models for mechanical execution and verification. Good cost-quality tradeoff.
+
+---
+
+## Configuring Models
+
+### Per-Agent Configuration
+
+Set an individual agent's model via `/pbr:config`:
+
+```
+/pbr:config model executor sonnet
+/pbr:config model verifier opus
+```
+
+Or edit `config.json` directly:
+
+```json
+{
+  "models": {
+    "researcher": "sonnet",
+    "planner": "inherit",
+    "executor": "inherit",
+    "verifier": "sonnet",
+    "integration_checker": "sonnet",
+    "debugger": "inherit",
+    "mapper": "sonnet",
+    "synthesizer": "haiku"
+  }
+}
+```
+
+### Valid Model Values
+
+| Value | Meaning |
+|-------|---------|
+| `sonnet` | Claude Sonnet (4.5/4.6) -- balanced speed and capability |
+| `opus` | Claude Opus (4.6) -- highest capability, slower |
+| `haiku` | Claude Haiku (4.5) -- fastest, lower capability |
+| `inherit` | Use the session's primary model (whatever the user is running) |
+
+Note: Claude Code 2.1.45+ supports Sonnet 4.6. Model values are abstract names — Claude Code resolves them to the latest available version.
+
+---
+
+## Model Selection in Skill Orchestration
+
+Skills that spawn subagents use the `model` parameter in `Task()` calls. Some skills hardcode a lighter model for specific tasks:
+
+- **Build skill**: Spawns inline verifiers with `model: "haiku"` for quick spot-checks
+- **Build skill**: Spawns codebase mapper updates with `model: "haiku"` for incremental map refreshes
+- **Plan skill**: Uses the configured `planner` model for main planning work
+
+The `subagent_type` parameter automatically loads the agent definition, and the model from `config.json` takes precedence over the agent's default `model:` frontmatter field.

package/plugins/pbr/references/model-selection.md

@@ -1,31 +1,31 @@
-# Model Selection Reference
-
-Plan-Build-Run uses adaptive model selection to balance cost and capability.
-
-## How It Works
-
-1. The planner annotates each task with `complexity="simple|medium|complex"`
-2. The build skill maps complexity to a model via `config.models.complexity_map`
-3. The executor agent is spawned with the selected model
-
-## Default Mapping
-
-| Complexity | Model | Rationale |
-|-----------|-------|-----------|
-| simple | haiku | Fast, cheap — sufficient for mechanical changes |
-| medium | sonnet | Good balance for standard feature work |
-| complex | inherit | Uses session model — typically Opus for critical work |
-
-## Override Mechanisms
-
-1. **Per-task override**: Add `model="sonnet"` attribute to task XML in PLAN.md
-2. **Config override**: Set `models.complexity_map` in config.json to change defaults
-3. **Agent-level override**: Set `models.executor` in config.json to force a single model for all executor spawns (disables adaptive selection)
-
-## Heuristics
-
-The planner uses these signals to determine complexity:
-- File count and types
-- Task name keywords
-- Dependency count
-- Whether the task introduces new patterns vs. follows established ones
+# Model Selection Reference
+
+Plan-Build-Run uses adaptive model selection to balance cost and capability.
+
+## How It Works
+
+1. The planner annotates each task with `complexity="simple|medium|complex"`
+2. The build skill maps complexity to a model via `config.models.complexity_map`
+3. The executor agent is spawned with the selected model
+
+## Default Mapping
+
+| Complexity | Model | Rationale |
+|-----------|-------|-----------|
+| simple | haiku | Fast, cheap — sufficient for mechanical changes |
+| medium | sonnet | Good balance for standard feature work |
+| complex | inherit | Uses session model — typically Opus for critical work |
+
+## Override Mechanisms
+
+1. **Per-task override**: Add `model="sonnet"` attribute to task XML in PLAN.md
+2. **Config override**: Set `models.complexity_map` in config.json to change defaults
+3. **Agent-level override**: Set `models.executor` in config.json to force a single model for all executor spawns (disables adaptive selection)
+
+## Heuristics
+
+The planner uses these signals to determine complexity:
+- File count and types
+- Task name keywords
+- Dependency count
+- Whether the task introduces new patterns vs. follows established ones