planflow-ai 1.3.2 → 1.3.5

package/.claude/resources/core/model-routing.md

@@ -7,7 +7,7 @@ Automatic model selection at phase boundaries during `/execute-plan`. Each phase
 
 **Scope**: `/execute-plan` only. Other skills (discovery, review, brainstorm) do not have pre-defined complexity scores and are not routed.
 
-**Config**: Controlled by `model_routing` key in `flow/.flowconfig` (default: `true`). Set `model_routing: false` to disable.
+**Config**: Controlled by `model_routing` key in `flow/.flowconfig` (default: `false`). Set `model_routing: true` to enable.
 
 ---
 
@@ -23,12 +23,16 @@ Automatic model selection at phase boundaries during `/execute-plan`. Each phase
 
 ## Platform Mappings
 
+Always use the **latest and most capable model** from each provider. Model names below are examples — always prefer the most recent version available at runtime.
+
 | Tier | Claude Code | Codex (OpenAI) | Cursor |
 |------|------------|----------------|--------|
 | Fast | `haiku` | `gpt-4.1-mini` | auto (fast) |
 | Standard | `sonnet` | `gpt-4.1` | auto (normal) |
 | Powerful | `opus` | `o3` | auto (max) |
 
+**Default model (when routing is OFF)**: Always use the most capable/recent model from the active provider — e.g., `opus` for Anthropic, `o3` for OpenAI. This is the default behavior.
+
 **Fallback rule**: If a platform doesn't support a tier, fall back to the next tier up (e.g., if no haiku equivalent, use Standard).
 
 ---
@@ -37,7 +41,7 @@ Automatic model selection at phase boundaries during `/execute-plan`. Each phase
 
 ### At Each Phase Boundary
 
-1. **Check config**: Read `model_routing` from `flow/.flowconfig`. If `false` or missing key, skip routing (use session default).
+1. **Check config**: Read `model_routing` from `flow/.flowconfig`. If `false`, missing key, or not set, skip routing (use the most capable session model — this is the default).
 2. **Read complexity**: Get the phase's complexity score from the plan file.
 3. **Look up tier**: Map score to tier using the table above.
 4. **Spawn subagent**: Use the Agent tool with `model={tier_model}` to implement the phase.

package/.claude/resources/core/phase-isolation.md

@@ -0,0 +1,222 @@
+
+# Phase Isolation
+
+## Purpose
+
+When `phase_isolation: true` in `flow/.flowconfig` (default), each `/execute-plan` phase implementation runs in an **isolated Agent sub-agent** with a clean context window. The sub-agent receives only the context it needs and returns a structured JSON summary. This eliminates context rot — phase 7 has the same quality as phase 1.
+
+**Core principle**: Clean context in, structured summary out.
+
+---
+
+## Architecture
+
+```
+Coordinator (main session)
+    │
+    ├─ Present phase in Plan Mode → User approves
+    │
+    ├─ Prepare isolated context (see Context Template below)
+    │
+    ├─ Spawn Agent sub-agent:
+    │   model: [tier from model routing]
+    │   mode: "auto"
+    │   prompt: [focused context + instructions + return format]
+    │
+    ├─ Receive structured JSON summary (1-2K tokens)
+    │
+    ├─ Process summary:
+    │   ├─ Update plan file (mark tasks [x])
+    │   ├─ Accumulate files_modified list
+    │   ├─ Append patterns to pending-patterns.md
+    │   ├─ Git commit (if enabled)
+    │   └─ Handle errors (present to user if status != success)
+    │
+    └─ Next phase...
+```
+
+Planning and user approval always happen in the **main session** (full context). Only the **implementation step** is isolated.
+
+---
+
+## Context Template
+
+The Agent sub-agent prompt must include exactly these sections:
+
+```markdown
+# Phase Implementation: {Phase N — Phase Name}
+
+## Plan
+**Feature**: {feature name}
+**Plan file**: {path to plan file}
+
+## Phase Scope
+{Scope description from plan}
+
+## Tasks
+{Task list from plan, as checklist}
+
+## Files Modified in Previous Phases
+{List of file paths created/modified so far, or "None — this is Phase 1"}
+
+## Project Patterns
+Read these files before implementing:
+- `.claude/rules/core/allowed-patterns.md`
+- `.claude/rules/core/forbidden-patterns.md`
+
+## Design Context
+{Only if UI phase — include design tokens from discovery doc}
+{Otherwise omit this section entirely}
+
+## Instructions
+1. Read the plan file to understand the full feature context
+2. Implement all tasks listed above
+3. Follow the project patterns from the files listed
+4. Return a JSON summary in the exact format below — do NOT return markdown
+
+## Return Format
+Return ONLY a JSON object (no markdown fences, no explanation):
+{see Return Format Schema below}
+```
+
+### Context Size Target
+
+The prompt should be **under 2K tokens** (excluding files the sub-agent reads itself via the Read tool). Keep it focused — the sub-agent will read project files as needed during implementation.
+
+---
+
+## Return Format Schema
+
+The sub-agent must return a JSON object with this structure:
+
+```json
+{
+  "status": "success",
+  "phase": "Phase 1: Create Core Resource",
+  "summary": "One-paragraph description of what was implemented and any notable decisions.",
+  "files_created": [
+    "src/types/auth.ts"
+  ],
+  "files_modified": [
+    "src/api/routes.ts",
+    "src/utils/helpers.ts"
+  ],
+  "decisions": [
+    "Chose JWT over sessions because discovery DR-4 specified stateless auth"
+  ],
+  "deviations": [
+    "Task 3 deferred — requires database migration first"
+  ],
+  "errors": [],
+  "patterns_captured": [
+    {
+      "category": "allowed",
+      "name": "Zod schema co-location",
+      "description": "All Zod schemas live next to their type definitions",
+      "confidence": "high"
+    }
+  ]
+}
+```
+
+### Field Descriptions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `status` | `"success" \| "failure" \| "partial"` | Yes | Overall phase outcome |
+| `phase` | string | Yes | Phase number and name |
+| `summary` | string | Yes | 1-3 sentence description of what was done |
+| `files_created` | string[] | Yes | Paths of new files created (empty array if none) |
+| `files_modified` | string[] | Yes | Paths of existing files modified (empty array if none) |
+| `decisions` | string[] | No | Architecture/design decisions made during implementation |
+| `deviations` | string[] | No | Tasks skipped or changed from plan |
+| `errors` | string[] | No | Errors encountered (even if resolved) |
+| `patterns_captured` | object[] | No | Patterns observed during implementation |
+
+### Failure Return Example
+
+```json
+{
+  "status": "failure",
+  "phase": "Phase 3: API Integration",
+  "summary": "Failed to implement API routes. Missing dependency '@auth/core' not in package.json.",
+  "files_created": [],
+  "files_modified": ["src/api/auth.ts"],
+  "decisions": [],
+  "deviations": [],
+  "errors": [
+    "Cannot find module '@auth/core' — dependency not installed",
+    "Partial implementation in src/api/auth.ts — needs cleanup"
+  ],
+  "patterns_captured": []
+}
+```
+
+---
+
+## Coordinator Processing
+
+After receiving the sub-agent's JSON summary, the coordinator:
+
+### On Success (`status: "success"`)
+
+1. **Update plan file**: Mark all phase tasks as `[x]`
+2. **Accumulate file list**: Merge `files_created` and `files_modified` into running list
+3. **Buffer patterns**: Append `patterns_captured` entries to `flow/resources/pending-patterns.md`
+4. **Git commit**: If `commit: true`, run `git add -A && git commit -m "Phase N: {name} — {feature}"`
+5. **Log decisions**: Include `decisions` in phase completion message
+6. **Proceed**: Move to next phase
+
+### On Failure (`status: "failure"`)
+
+1. **Present error**: Show `errors` array to user
+2. **Show partial work**: List `files_modified` so user knows what was touched
+3. **Ask user**: "Phase failed. Options: (1) Retry phase, (2) Skip and continue, (3) Stop execution"
+4. **Do NOT auto-retry**: Let user decide
+
+### On Partial (`status: "partial"`)
+
+1. **Present summary**: Show what was completed and what wasn't
+2. **Show deviations**: List `deviations` explaining what was skipped
+3. **Ask user**: "Phase partially complete. Continue to next phase or retry remaining tasks?"
+
+---
+
+## Aggregated Phases
+
+When phases are aggregated (combined complexity ≤ 6), they run as **one sub-agent call** with all tasks from all aggregated phases. The context template lists all phases and tasks together. The return uses the highest phase number as the `phase` field.
+
+---
+
+## Configuration
+
+### `.flowconfig` Setting
+
+```yaml
+phase_isolation: true    # Run phases in isolated sub-agents (default: true)
+```
+
+- `true` (default): Each phase runs in an isolated Agent sub-agent
+- `false`: Phases execute inline in the main session (legacy behavior, useful for debugging)
+
+### Interaction with Model Routing
+
+Phase isolation **enhances** model routing — it doesn't replace it:
+
+| Setting | Behavior |
+|---------|----------|
+| `model_routing: true` + `phase_isolation: true` | Sub-agent spawned with correct tier model AND clean context |
+| `model_routing: true` + `phase_isolation: false` | Sub-agent spawned with correct tier model, inherits session context |
+| `model_routing: false` + `phase_isolation: true` | Sub-agent spawned with session model, clean context |
+| `model_routing: false` + `phase_isolation: false` | Inline execution, no sub-agents (original behavior) |
+
+---
+
+## Rules
+
+1. **Planning stays in session** — only implementation is isolated
+2. **Under 2K token prompts** — keep context focused, let sub-agent read files
+3. **JSON return only** — no markdown in the return, pure JSON
+4. **Coordinator validates** — check status field before proceeding
+5. **Never auto-retry** — on failure, present to user and ask
+6. **Pass paths, not content** — give file paths, sub-agent reads them

package/.claude/resources/core/session-scratchpad.md

@@ -0,0 +1,105 @@
+
+# Session Scratchpad
+
+## Purpose
+
+The session scratchpad (`flow/.scratchpad.md`) is an ephemeral per-session file for raw notes, temporary analysis, and in-progress observations. It bridges the gap between transient session work and permanent artifacts (ledger, brain, memory).
+
+**Core principle**: Write things down so they survive compaction; promote the valuable ones before session ends.
+
+---
+
+## Session Start Behavior
+
+On session start:
+1. If `flow/.scratchpad.md` exists and has content, read it silently
+2. If entries look stale (from a previous session), scan for promotable items:
+   - Learnings → promote to `flow/ledger.md`
+   - Error patterns → promote to `flow/brain/errors/`
+   - Feature context → promote to `flow/brain/features/`
+   - User preferences → promote to `flow/ledger.md` (User Preferences section)
+3. After promotion, clear the file (reset to empty template)
+4. If the file is empty or doesn't exist, skip — no action needed
+
+---
+
+## Write Triggers
+
+Write to the scratchpad when you encounter:
+
+| Trigger | Example Entry |
+|---------|---------------|
+| **Non-obvious error resolution** | "Fixed ESM import issue — need `type: module` in package.json AND `moduleResolution: node16` in tsconfig" |
+| **Architectural insight** | "This project uses barrel exports everywhere — new files need re-export in index.ts" |
+| **Dead-end approach** | "Tried using `fs.watch` for file monitoring — unreliable on Linux, switched to chokidar" |
+| **User preference discovered** | "User prefers terse responses, no trailing summaries" |
+| **Open question** | "Need to verify: does the CI pipeline run on Node 18 or 20?" |
+| **Mid-task context** | "Reviewing auth module — found 3 unused imports, will clean up after main task" |
+
+### What NOT to Write
+
+- Routine file reads or grep results (re-readable)
+- Build/test output (captured in logs)
+- Things already captured by brain-capture blocks
+- Obvious facts derivable from the code
+- Full code snippets (reference file:line instead)
+
+---
+
+## File Format
+
+```markdown
+# Session Scratchpad
+
+## Notes
+
+- [{timestamp}] {note}
+- [{timestamp}] {note}
+
+## Open Questions
+
+- {question}
+
+## Promote Before Session End
+
+- [ ] {item to promote} → {target: ledger/brain/memory}
+```
+
+Keep under **50 lines**. When approaching the limit, promote older entries or discard low-value ones.
+
+---
+
+## Promotion Rules
+
+Before session ends (or when the scratchpad is getting full):
+
+1. **Scan each entry** and classify:
+   - **Promote**: Valuable insight that should persist → move to appropriate target
+   - **Discard**: Transient note, already acted on, or no future value → delete
+2. **Promotion targets**:
+   | Content Type | Target | Section |
+   |-------------|--------|---------|
+   | Project learning / workaround | `flow/ledger.md` | What Works / What Didn't Work |
+   | User preference | `flow/ledger.md` | User Preferences |
+   | Error pattern | `flow/brain/errors/{name}.md` | New or updated entry |
+   | Feature context | `flow/brain/features/{name}.md` | Timeline update |
+   | Reusable pattern | `flow/resources/pending-patterns.md` | Pattern capture buffer |
+3. **After promotion**, clear the scratchpad (leave just the empty template headers)
+
+---
+
+## Compaction Integration
+
+During `/compact`, the scratchpad is in the **preserve** list — its contents survive compaction summaries. This is critical because scratchpad notes often contain context that would otherwise be lost.
+
+After compaction, the model should re-read `flow/.scratchpad.md` to restore any notes written before compaction.
+
+---
+
+## Rules
+
+1. **Lightweight writes** — single-line entries, not paragraphs
+2. **No duplication** — don't write what brain-capture already captures
+3. **Self-manage size** — promote or discard when approaching 50 lines
+4. **Promote before ending** — always scan for promotable items before session ends
+5. **Not a task list** — use `flow/tasklist.md` for tasks, scratchpad is for observations

package/.claude/resources/skills/_index.md

@@ -23,6 +23,10 @@ Skills implement the workflow logic for commands. Each skill orchestrates a spec
 > **Note**: The review-code and review-pr skills include **Severity Re-Ranking**. After verification, findings are re-ranked by severity → confidence → fix complexity, related findings across files are grouped, and an executive summary is added when ≥ 5 findings. See `.claude/resources/core/review-severity-ranking.md` for full rules.
 >
 > **Note**: The review-code and review-pr skills include **Adaptive Depth**. Review depth scales automatically based on changeset size: < 50 lines → Lightweight (quick-scan), 50–500 → Standard (no change), 500+ → Deep (multi-pass with executive summary). See `.claude/resources/core/review-adaptive-depth.md` for full rules.
+>
+> **Note**: All long-running skills (execute-plan, review-code, discovery) support **Context Compaction**. When compacting mid-skill, load `.claude/resources/core/compaction-guide.md` for preserve/discard rules and the compact summary template. See `COR-CG-1` through `COR-CG-4`.
+>
+> **Note**: The discovery skill uses **Discovery Sub-Agents** for parallel codebase exploration. Three haiku sub-agents (similar features, API/data patterns, schema/types) run in parallel after reading referenced docs, returning condensed JSON findings merged into a Codebase Analysis section. See `.claude/resources/core/discovery-sub-agents.md` for full rules.
 
 ---
 
@@ -93,44 +97,68 @@ Skills implement the workflow logic for commands. Each skill orchestrates a spec
 
 | Code | Description | Source | Lines |
 |------|-------------|--------|-------|
-| SKL-EXEC-1 | Critical rules (build only at end, no DB commands) | execute-plan-skill.md | 22-95 |
-| SKL-EXEC-2 | Workflow steps 1-3 (parse, analyze complexity, present summary) | execute-plan-skill.md | 105-182 |
-| SKL-EXEC-3 | Workflow steps 4-5 (execute phases with Plan mode, update progress) | execute-plan-skill.md | 184-238 |
-| SKL-EXEC-4 | Workflow steps 6-7 (tests phase, completion/verification) | execute-plan-skill.md | 240-281 |
-| SKL-EXEC-5 | Complexity-based behavior (low, medium, high, very high) | execute-plan-skill.md | 303-332 |
-| SKL-EXEC-6 | Error handling (build failures, test failures, cancellation) | execute-plan-skill.md | 334-366 |
+| SKL-EXEC-1 | Purpose and inputs | execute-plan-skill.md | 4-100 |
+| SKL-EXEC-2 | Critical rules (build only at end, no DB commands) | execute-plan-skill.md | 18-92 |
+| SKL-EXEC-3 | Step 1: Parse the plan | execute-plan-skill.md | 103-112 |
+| SKL-EXEC-4 | Step 2: Analyze complexity and determine execution strategy | execute-plan-skill.md | 113-151 |
+| SKL-EXEC-5 | Step 3: Present execution plan summary | execute-plan-skill.md | 152-180 |
+| SKL-EXEC-6 | Step 4: Execute each phase with Plan mode | execute-plan-skill.md | 181-236 |
+| SKL-EXEC-7 | Step 5: Update progress after each phase | execute-plan-skill.md | 237-249 |
+| SKL-EXEC-8 | Step 5b: Phase-boundary context check (compaction) | execute-plan-skill.md | 250-275 |
+| SKL-EXEC-9 | Step 6: Handle tests phase | execute-plan-skill.md | 277-302 |
+| SKL-EXEC-10 | Step 7: Completion — build and test verification | execute-plan-skill.md | 303-364 |
+| SKL-EXEC-11 | Complexity-based behavior (low, medium, high, very high) | execute-plan-skill.md | 365-393 |
+| SKL-EXEC-12 | Error handling (build failures, test failures, cancellation) | execute-plan-skill.md | 395-427 |
 
 ### Review Code Skill (`review-code-skill.md`)
 
 | Code | Description | Source | Lines |
 |------|-------------|--------|-------|
-| SKL-REV-1 | Purpose and restrictions (read-only analysis) | review-code-skill.md | 8-58 |
-| SKL-REV-2 | Workflow steps 1-3 (identify files, load patterns, find similar) | review-code-skill.md | 72-130 |
-| SKL-REV-3 | Workflow steps 4-6 (analyze, pattern conflicts, generate doc) | review-code-skill.md | 131-180 |
-| SKL-REV-4 | Severity levels and conflict resolution | review-code-skill.md | 182-231 |
-| SKL-REV-5 | Finding similar implementations (search strategies) | review-code-skill.md | 233-259 |
+| SKL-REV-1 | Purpose and restrictions (read-only, allowed actions) | review-code-skill.md | 4-58 |
+| SKL-REV-2 | Step 1: Identify changed files | review-code-skill.md | 70-77 |
+| SKL-REV-3 | Step 1b: Determine review depth (adaptive depth) | review-code-skill.md | 78-97 |
+| SKL-REV-4 | Step 2: Load review patterns | review-code-skill.md | 98-107 |
+| SKL-REV-5 | Step 3: Find similar implementations in codebase | review-code-skill.md | 108-146 |
+| SKL-REV-6 | Step 4: Analyze code changes | review-code-skill.md | 147-158 |
+| SKL-REV-7 | Step 5: Pattern conflicts + 5b verify + 5c re-rank | review-code-skill.md | 159-231 |
+| SKL-REV-8 | Step 6: Generate review document | review-code-skill.md | 232-260 |
+| SKL-REV-9 | Severity levels and conflict resolution | review-code-skill.md | 252-301 |
+| SKL-REV-10 | Finding similar implementations (search strategies) | review-code-skill.md | 303-330 |
+| SKL-REV-11 | Validation checklist | review-code-skill.md | 379-392 |
 
 ### Review PR Skill (`review-pr-skill.md`)
 
 | Code | Description | Source | Lines |
 |------|-------------|--------|-------|
-| SKL-PR-1 | Purpose and restrictions (GitHub/Azure DevOps commands) | review-pr-skill.md | 8-122 |
-| SKL-PR-2 | Workflow (authenticate, fetch, analyze, generate) | review-pr-skill.md | 132-217 |
-| SKL-PR-3 | Output format template with review history | review-pr-skill.md | 219-318 |
-| SKL-PR-4 | Severity levels and fix complexity scoring | review-pr-skill.md | 320-370 |
-| SKL-PR-5 | Link format for GitHub and Azure DevOps | review-pr-skill.md | 372-420 |
+| SKL-PR-1 | Purpose and restrictions (read-only, GitHub/Azure DevOps) | review-pr-skill.md | 4-120 |
+| SKL-PR-2 | Step 0: Authenticate for PR access | review-pr-skill.md | 132-158 |
+| SKL-PR-3 | Step 1: Fetch PR information + 1b determine review depth | review-pr-skill.md | 159-184 |
+| SKL-PR-4 | Step 2: Load review patterns | review-pr-skill.md | 185-194 |
+| SKL-PR-5 | Step 3: Analyze code changes + 3b verify + 3c re-rank | review-pr-skill.md | 195-240 |
+| SKL-PR-6 | Step 4: Generate or update review document | review-pr-skill.md | 241-320 |
+| SKL-PR-7 | Output format template (findings, severity, recommendations) | review-pr-skill.md | 322-376 |
+| SKL-PR-8 | Fix complexity scoring (scale, modifiers, examples) | review-pr-skill.md | 388-426 |
+| SKL-PR-9 | Link format for GitHub and Azure DevOps | review-pr-skill.md | 428-477 |
+| SKL-PR-10 | Example finding and quick reference commands | review-pr-skill.md | 479-552 |
 
 ### Setup Skill (`setup-skill.md`)
 
 | Code | Description | Source | Lines |
 |------|-------------|--------|-------|
-| SKL-SETUP-1 | Purpose and critical approach | setup-skill.md | 8-30 |
-| SKL-SETUP-2 | Steps 1-2 (scan project structure, dependency analysis) | setup-skill.md | 34-106 |
-| SKL-SETUP-3 | Step 3 (deep code analysis, sample files, extract patterns) | setup-skill.md | 108-200 |
-| SKL-SETUP-4 | Steps 4-5 (research best practices, check existing rules) | setup-skill.md | 202-252 |
-| SKL-SETUP-5 | Step 6 (confirming questions via Plan mode) | setup-skill.md | 254-334 |
-| SKL-SETUP-6 | Step 7 (generate framework and library pattern files) | setup-skill.md | 336-493 |
-| SKL-SETUP-7 | Steps 8-11 (update core, create analysis doc, create flow folder, summary) | setup-skill.md | 595-797 |
+| SKL-SETUP-1 | Purpose and critical approach | setup-skill.md | 4-28 |
+| SKL-SETUP-2 | Step 1: Scan project structure | setup-skill.md | 31-57 |
+| SKL-SETUP-3 | Step 2: Deep dependency analysis | setup-skill.md | 58-103 |
+| SKL-SETUP-4 | Step 3: Deep code analysis | setup-skill.md | 104-199 |
+| SKL-SETUP-5 | Step 4: Research best practices | setup-skill.md | 200-222 |
+| SKL-SETUP-6 | Step 5: Check existing rules | setup-skill.md | 223-249 |
+| SKL-SETUP-7 | Step 6: Ask confirming questions (Plan mode) | setup-skill.md | 250-332 |
+| SKL-SETUP-8 | Step 7: Generate pattern files (templates + examples) | setup-skill.md | 333-574 |
+| SKL-SETUP-9 | Step 8: Update core pattern files | setup-skill.md | 575-605 |
+| SKL-SETUP-10 | Step 9: Sync generic patterns to global brain | setup-skill.md | 606-654 |
+| SKL-SETUP-11 | Step 10: Create project analysis document | setup-skill.md | 655-727 |
+| SKL-SETUP-12 | Step 11: Index documentation files | setup-skill.md | 728-816 |
+| SKL-SETUP-13 | Step 12: Create flow folder structure | setup-skill.md | 817-860 |
+| SKL-SETUP-14 | Step 13: Present setup summary | setup-skill.md | 861-955 |
 
 ### Write Tests Skill (`write-tests-skill.md`)
 
@@ -159,26 +187,56 @@ Skills implement the workflow logic for commands. Each skill orchestrates a spec
 
 | Code | Expand When |
 |------|-------------|
-| SKL-EXEC-1 | Need critical rules (build timing, DB commands) |
-| SKL-EXEC-2 | Need complexity analysis and grouping logic |
-| SKL-EXEC-3 | Need phase execution workflow with Plan mode |
-| SKL-EXEC-5 | Need complexity-based behavior details |
+| SKL-EXEC-2 | Need critical rules (build timing, DB commands) |
+| SKL-EXEC-3 | Parsing plan file structure |
+| SKL-EXEC-4 | Analyzing complexity and determining execution strategy |
+| SKL-EXEC-5 | Presenting execution plan summary to user |
+| SKL-EXEC-6 | Executing a phase with Plan mode |
+| SKL-EXEC-7 | Updating progress after a phase |
+| SKL-EXEC-8 | Compacting at phase boundaries |
+| SKL-EXEC-9 | Handling the tests phase |
+| SKL-EXEC-10 | Final build and test verification |
+| SKL-EXEC-11 | Need complexity-based behavior details |
+| SKL-EXEC-12 | Handling build/test failures or cancellation |
 
 ### Code Review
 
 | Code | Expand When |
 |------|-------------|
-| SKL-REV-2 | Need pattern loading and similar implementation search |
-| SKL-REV-4 | Need severity levels and conflict resolution |
-| SKL-PR-3 | Need PR review output template |
-| SKL-PR-5 | Need link format for GitHub/Azure DevOps |
+| SKL-REV-2 | Identifying changed files for review |
+| SKL-REV-3 | Determining review depth (adaptive) |
+| SKL-REV-4 | Loading review patterns |
+| SKL-REV-5 | Finding similar implementations in codebase |
+| SKL-REV-6 | Analyzing code changes |
+| SKL-REV-7 | Pattern conflicts, verification, and re-ranking |
+| SKL-REV-8 | Generating the review document |
+| SKL-REV-9 | Need severity levels and conflict resolution |
+| SKL-REV-10 | Need search strategies for similar code |
+| SKL-PR-2 | Authenticating for PR access |
+| SKL-PR-3 | Fetching PR info and determining depth |
+| SKL-PR-5 | Analyzing PR changes, verification, re-ranking |
+| SKL-PR-6 | Generating PR review document |
+| SKL-PR-7 | Need PR review output template |
+| SKL-PR-8 | Need fix complexity scoring |
+| SKL-PR-9 | Need link format for GitHub/Azure DevOps |
 
 ### Setup and Testing
 
 | Code | Expand When |
 |------|-------------|
-| SKL-SETUP-2 | Need dependency detection tables |
-| SKL-SETUP-6 | Need pattern file generation templates |
+| SKL-SETUP-2 | Scanning project structure |
+| SKL-SETUP-3 | Deep dependency analysis |
+| SKL-SETUP-4 | Deep code analysis |
+| SKL-SETUP-5 | Researching best practices |
+| SKL-SETUP-6 | Checking existing rules |
+| SKL-SETUP-7 | Asking confirming questions via Plan mode |
+| SKL-SETUP-8 | Generating pattern files |
+| SKL-SETUP-9 | Updating core pattern files |
+| SKL-SETUP-10 | Syncing to global brain |
+| SKL-SETUP-11 | Creating project analysis document |
+| SKL-SETUP-12 | Indexing documentation files |
+| SKL-SETUP-13 | Creating flow folder structure |
+| SKL-SETUP-14 | Presenting setup summary |
 | SKL-TEST-2 | Need coverage analysis workflow |
 | SKL-TEST-4 | Need test writing guidelines |
 
@@ -201,10 +259,10 @@ Skills implement the workflow logic for commands. Each skill orchestrates a spec
 | `/learn` | learn-skill | SKL-LRN-1 through SKL-LRN-4 |
 | `/discovery-plan` | discovery-skill | SKL-DIS-1 through SKL-DIS-4 |
 | `/create-plan` | create-plan-skill | SKL-PLN-1 through SKL-PLN-4 |
-| `/execute-plan` | execute-plan-skill | SKL-EXEC-1 through SKL-EXEC-6 |
-| `/review-code` | review-code-skill | SKL-REV-1 through SKL-REV-5 |
-| `/review-pr` | review-pr-skill | SKL-PR-1 through SKL-PR-5 |
-| `/setup` | setup-skill | SKL-SETUP-1 through SKL-SETUP-7 |
+| `/execute-plan` | execute-plan-skill | SKL-EXEC-1 through SKL-EXEC-12 |
+| `/review-code` | review-code-skill | SKL-REV-1 through SKL-REV-11 |
+| `/review-pr` | review-pr-skill | SKL-PR-1 through SKL-PR-10 |
+| `/setup` | setup-skill | SKL-SETUP-1 through SKL-SETUP-14 |
 | `/write-tests` | write-tests-skill | SKL-TEST-1 through SKL-TEST-5 |
 | `/create-contract` | create-contract-skill | SKL-CON-1 through SKL-CON-4 |
 
@@ -214,10 +272,10 @@ Skills implement the workflow logic for commands. Each skill orchestrates a spec
 
 | Skill | Lines | Sections | Complexity |
 |-------|-------|----------|------------|
-| setup-skill | 821 | 7 | Highest - deep project analysis |
-| review-pr-skill | 496 | 5 | High - multi-platform support |
-| execute-plan-skill | 388 | 6 | High - phase execution logic |
-| review-code-skill | 308 | 5 | Medium - pattern matching |
+| setup-skill | 955 | 14 | Highest - deep project analysis |
+| review-pr-skill | 552 | 10 | High - multi-platform support |
+| execute-plan-skill | 448 | 12 | High - phase execution logic |
+| review-code-skill | 392 | 11 | Medium - pattern matching |
 | discovery-skill | 295 | 4 | Medium - requirements gathering |
 | brainstorm-skill | 280 | 3 | Medium - structured exploration with interactive questions |
 | write-tests-skill | 294 | 5 | Medium - iterative testing |

package/.claude/resources/skills/discovery-skill.md

@@ -98,6 +98,47 @@ This skill is **strictly for gathering and documenting requirements**. The proce
 
 ---
 
+### Step 1b: Spawn Exploration Sub-Agents
+
+After reading referenced documents, spawn three parallel Agent sub-agents to explore the codebase. These run in parallel and return condensed findings that inform the clarifying questions in Step 2.
+
+**Actions**:
+
+1. **Prepare context summary**: Distill Step 1 findings into a brief context paragraph (feature name, key requirements, relevant technologies mentioned)
+2. **Spawn 3 sub-agents in parallel** using the Agent tool:
+   - **Similar Features** agent — finds existing code with related functionality
+   - **API/Data Patterns** agent — maps API endpoints, service patterns, data flow
+   - **Schema/Types** agent — explores type definitions, schemas, shared interfaces
+3. Each sub-agent uses `model: "haiku"` and `subagent_type: "Explore"`
+4. Each receives: feature name, context summary, and agent-specific exploration instructions
+
+See `.claude/resources/core/discovery-sub-agents.md` for prompt templates, return format schema, and full agent definitions (`COR-DSA-1`).
+
+**Spawning pattern**:
+```
+Launch in parallel:
+- Agent(model: "haiku", subagent_type: "Explore", prompt: similar_features_prompt)
+- Agent(model: "haiku", subagent_type: "Explore", prompt: api_data_prompt)
+- Agent(model: "haiku", subagent_type: "Explore", prompt: schema_types_prompt)
+```
+
+---
+
+### Step 1c: Collect and Merge Exploration Findings
+
+After all sub-agents return, process their findings:
+
+1. **Parse returns**: Extract JSON from each sub-agent response
+2. **Handle failures**: If a sub-agent returns `status: "failure"` or invalid JSON, skip its findings and continue. Log the failure but do not block discovery.
+3. **Filter**: If more than 15 total findings, remove `relevance: "low"` entries
+4. **Merge patterns**: Collect all `patterns_noticed` entries, deduplicate, and append to `flow/resources/pending-patterns.md`
+5. **Build Codebase Analysis**: Format merged findings into a `## Codebase Analysis` section (see template in `COR-DSA-2`)
+6. **Inform Step 2**: Use findings to formulate better clarifying questions — reference specific existing code when asking about patterns to follow
+
+If all sub-agents fail or return no findings, skip the Codebase Analysis section entirely. Discovery continues normally — findings are supplementary, not required.
+
+---
+
 ### Step 2: Ask Clarifying Questions
 
 Ask questions about gaps identified in documents and unclear requirements.
@@ -273,12 +314,15 @@ Create the discovery markdown file:
 
 1. Context
 2. Referenced Documents
-3. Requirements Gathered (FR, NFR, Constraints)
-4. Open Questions (all answered)
-5. Technical Considerations
-6. Proposed Approach
-7. Risks and Unknowns
-8. Next Steps
+3. Codebase Analysis (from Step 1c — omit if no findings)
+4. Requirements Gathered (FR, NFR, Constraints)
+5. Open Questions (all answered)
+6. Technical Considerations
+7. Proposed Approach
+8. Risks and Unknowns
+9. Next Steps
+
+**Codebase Analysis**: Include the merged findings from Step 1c. Use the Codebase Analysis section format from `.claude/resources/core/discovery-sub-agents.md` (`COR-DSA-2`). Omit this section if all sub-agents failed or returned no findings.
 
 **Design Context**: If UI work was confirmed during questioning, append a `## Design Context` section to the discovery document using the template from `.claude/resources/core/design-awareness.md`. Populate with extracted tokens (from screenshots), personality defaults, or existing design system values.