pi-feature-dev 1.0.0 → 1.2.0

package/README.md

@@ -1,13 +1,17 @@
 # pi-feature-dev
 
-Pi-native guided feature development workflow.
+Portable guided feature development workflow, packaged as a Pi skill.
 
-This package adapts a Claude Code-style feature development workflow to Pi using Pi packages and tools:
+The skill describes a tool-agnostic process for non-trivial feature work:
 
-- `pi-subagents` for scout/planner/worker/reviewer fanout
-- `@juicesharp/rpiv-todo` for phase tracking
-- `@juicesharp/rpiv-ask-user-question` for structured choices
-- optional `context-mode`, `pi-web-access`, and `pi-intercom` for large-output handling, web/code research, and session coordination
+- clarify requirements before coding
+- explore the existing codebase before design
+- compare implementation approaches and get approval
+- implement with one writer
+- review the diff from multiple perspectives
+- validate and summarize results
+
+It does not require specific task-tracking, question, delegation, or review tools. If the current environment provides equivalent capabilities, use them; otherwise follow the same workflow directly in chat and with normal code tools.
 
 ## Install
 
@@ -35,27 +39,13 @@ If installing for a project, run from that project and use Pi's local install fl
 pi install -l ~/Projects/pi-feature-dev
 ```
 
-## Required companion packages
-
-This workflow expects these Pi tools to be available:
-
-```bash
-pi install npm:pi-subagents
-pi install npm:@juicesharp/rpiv-todo
-pi install npm:@juicesharp/rpiv-ask-user-question
-```
-
-Recommended optional packages:
+## Optional companion packages
 
-```bash
-pi install npm:context-mode
-pi install npm:pi-web-access
-pi install npm:pi-intercom
-```
+No companion package is required. Optional Pi packages can improve specific parts of the workflow, such as progress tracking, structured choices, delegation, large-output handling, web/code research, or session coordination.
 
 ## Usage
 
-Skill command:
+Skill command in Pi:
 
 ```text
 /skill:feature-dev Add OAuth login with Google and GitHub
@@ -67,18 +57,20 @@ Natural language also works when Pi's skill matcher triggers:
 Use feature-dev to implement API rate limiting.
 ```
 
-This package is intentionally skill-only. It does not provide a `/feature-dev` prompt template shortcut; use `/skill:feature-dev` for explicit invocation.
+The `skills/feature-dev/SKILL.md` file is portable markdown and can be adapted for other coding assistant environments.
+
+This package is intentionally skill-only. It does not provide a `/feature-dev` prompt template shortcut; use `/skill:feature-dev` for explicit Pi invocation.
 
 ## What it does
 
-The skill guides Pi through a seven-phase process:
+The skill guides a coding assistant through a seven-phase process:
 
-1. Discovery — understand the feature and create todos
-2. Codebase exploration — inspect relevant code and patterns, optionally with parallel subagents
+1. Discovery — understand the feature and establish lightweight progress tracking
+2. Codebase exploration — inspect relevant code and patterns, optionally with read-only helper passes
 3. Clarifying questions — resolve ambiguity before design
 4. Architecture design — compare minimal, clean, and pragmatic approaches
 5. Implementation — only after approval, with a single writer
-6. Quality review — parallel fresh-context reviewers inspect the diff
+6. Quality review — inspect the diff from correctness, validation, and maintainability perspectives
 7. Validation and summary — run focused checks and summarize changes
 
 ## Package contents
@@ -91,8 +83,6 @@ pi-feature-dev/
         └── SKILL.md
 ```
 
-The package intentionally does **not** ship custom subagent definitions. It uses the built-in roles from `pi-subagents` (`scout`, `context-builder`, `planner`, `worker`, `reviewer`, `researcher`, `oracle`) so it stays small and tracks improvements in that package.
-
 ## Release
 
 Releases are automated with GitHub Actions and semantic-release.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-feature-dev",
-  "version": "1.0.0",
-  "description": "Pi-native guided feature development workflow using subagents, todos, clarification questions, implementation, and review loops.",
+  "version": "1.2.0",
+  "description": "Portable guided feature development workflow for coding assistants, packaged as a Pi skill.",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -16,11 +16,9 @@
     "access": "public"
   },
   "keywords": [
-    "pi-package",
-    "pi",
-    "pi-coding-agent",
     "feature-development",
-    "subagents",
+    "coding-assistants",
+    "workflow",
     "skills"
   ],
   "files": [

package/skills/feature-dev/SKILL.md

@@ -1,47 +1,29 @@
 ---
 name: feature-dev
-description: Structured feature development workflow for Pi. Use for non-trivial feature work requiring codebase exploration, clarification, architecture trade-offs, implementation approval, subagent review, and final summary.
-compatibility: "Pi. Best with pi-subagents, @juicesharp/rpiv-todo, and @juicesharp/rpiv-ask-user-question installed; optional context-mode, pi-web-access, and pi-intercom improve the workflow."
+description: Structured feature development workflow for coding assistants. Use for non-trivial feature work requiring codebase exploration, clarification, architecture trade-offs, implementation approval, review, and final summary.
+compatibility: "Portable across coding assistant environments. Optional task tracking, structured-question, delegation, search, and browser tools can improve the workflow, but are not required."
 ---
 
-# Feature Dev for Pi
+# Feature Dev
 
-Run a guided, Pi-native feature development workflow. This skill replaces the Claude Code `feature-dev` command/agents with Pi tools:
+Run a guided, tool-agnostic feature development workflow. Adapt each step to the capabilities of the current environment:
 
-- `todo` for phase/progress tracking
-- `subagent` from `pi-subagents` for scout/planner/worker/reviewer fanout
-- `ask_user_question` for structured decisions and multiple-choice clarification
-- `web_search`, `code_search`, and `fetch_content` for external context when needed
-- `intercom` only when coordinating with separate live Pi sessions or subagent escalations
+- Track phase/progress state with any available planning mechanism, or keep a concise written checklist in chat.
+- Ask clarification and decision questions in normal chat; use structured-choice UI/tools only if available.
+- Use search, documentation, browser, or repository tools for external context when needed.
+- For broad work, optionally delegate read-only exploration, planning, or review to independent helpers if the environment supports it.
 
-This skill is for the parent/orchestrator session. Child subagents should receive concrete role-specific tasks; do not ask child agents to run this workflow or spawn their own subagents.
+This workflow is for the main orchestrating session. Keep responsibilities clear: one writer owns file edits, while any optional helpers stay read-only unless the user explicitly approves a different handoff.
 
 ## Operating Rules
 
 1. **Clarify before coding.** Do not implement until scope, acceptance criteria, constraints, and non-goals are clear enough.
 2. **Explore before designing.** Inspect relevant existing code and patterns before proposing architecture.
 3. **Ask before implementation.** Present the preferred architecture and wait for explicit user approval before editing.
-4. **Keep writes single-threaded.** Use the parent session or one `worker` subagent as the writer. Never run parallel writers in the same checkout.
-5. **Review after implementation.** Use fresh-context reviewers to inspect the diff, synthesize findings, then apply only approved/worthwhile fixes.
-6. **Use available tools only.** If a recommended tool is unavailable, continue with the closest Pi-native alternative and state the fallback briefly.
-7. **For large outputs.** If context-mode tools are available, use them for test/build/log/git output. Otherwise run focused commands and summarize concise output.
-
-Before executing any subagent, call `subagent({ action: "list" })` and only use executable/non-disabled agents from the result.
-
-## Recommended Agent Mapping
-
-Use built-in `pi-subagents` roles by default:
-
-| Need | Pi role |
-| --- | --- |
-| Codebase exploration | `scout` or `context-builder` |
-| Architecture planning | `planner` |
-| Implementation handoff | `worker` |
-| Quality review | `reviewer` |
-| External evidence | `researcher` |
-| Decision consistency/advisory review | `oracle` |
-
-Do not create custom agents unless the user explicitly wants persistent role overrides. This package intentionally works with built-in Pi subagents.
+4. **Keep writes single-threaded.** Use the main session or one dedicated writer. Never run parallel writers in the same checkout.
+5. **Review after implementation.** Inspect the diff from fresh perspectives, synthesize findings, then apply only approved/worthwhile fixes.
+6. **Use available tools only.** If a recommended capability is unavailable, continue with the closest alternative and state the fallback briefly.
+7. **For large outputs.** Use any available large-output/log-processing tools. Otherwise run focused commands and summarize concise output.
 
 ## Workflow
 
@@ -51,51 +33,30 @@ Goal: understand what needs to be built.
 
 Actions:
 
-1. Create phase todos with `todo` for Discovery, Exploration, Clarification, Architecture, Implementation, Review, and Summary/Validation. Keep exactly one todo `in_progress` at a time.
+1. Establish lightweight phase tracking for Discovery, Exploration, Clarification, Architecture, Implementation, Review, and Summary/Validation. Keep exactly one phase active at a time when your environment supports explicit progress state.
 2. If the feature request is unclear, ask concise questions before doing deep work:
    - What problem should this solve?
    - What should the user-visible behavior be?
    - What constraints, deadlines, compatibility requirements, or non-goals matter?
 3. Summarize your understanding and call out assumptions.
 
-Use `ask_user_question` only for questions with 2-4 clear choices. For open-ended requirements, ask normally in chat.
+Use structured-choice prompts only for questions with 2-4 clear choices. For open-ended requirements, ask normally in chat.
 
 ### Phase 2 — Codebase Exploration
 
 Goal: understand relevant code and project patterns at high and low levels.
 
-Default subagent fanout for non-trivial features:
-
-```ts
-subagent({
-  action: "list"
-})
-
-subagent({
-  tasks: [
-    {
-      agent: "scout",
-      task: "Find features similar to <feature> and trace their implementation. Return key entry points, data flow, conventions, risks, and 5-10 essential files to read. Do not edit files."
-    },
-    {
-      agent: "context-builder",
-      task: "Map the architecture, abstractions, module boundaries, and integration points relevant to <feature>. Return file:line references and 5-10 essential files to read. Do not edit files."
-    },
-    {
-      agent: "scout",
-      task: "Identify tests, validation patterns, UI/API patterns, configuration, and extension points relevant to <feature>. Return concrete files and gaps. Do not edit files."
-    }
-  ],
-  concurrency: 3,
-  context: "fresh"
-})
-```
+For non-trivial features, perform these read-only exploration passes. Use independent helpers only if available; otherwise do the passes yourself:
 
-Adapt the tasks to the project. Use two agents for medium work; three for broad features. Skip subagents for trivial single-file changes, but still inspect relevant files yourself.
+1. Find features similar to the requested feature and trace their implementation. Return key entry points, data flow, conventions, risks, and 5-10 essential files to read.
+2. Map architecture, abstractions, module boundaries, and integration points relevant to the feature. Return file:line references and 5-10 essential files to read.
+3. Identify tests, validation patterns, UI/API patterns, configuration, and extension points relevant to the feature. Return concrete files and gaps.
 
-After subagents return:
+Use two passes for medium work; three for broad features. Skip delegation for trivial single-file changes, but still inspect relevant files yourself.
 
-1. Read the essential files they identified.
+After exploration:
+
+1. Read the essential files identified.
 2. Follow imports/callers/tests/config as needed.
 3. Present a concise findings summary: similar patterns, relevant files, likely integration points, risks, and unknowns.
 
@@ -114,7 +75,7 @@ Review the feature request plus exploration findings. Identify gaps in:
 - tests and validation expectations
 - rollout/feature flags/documentation needs
 
-Ask all necessary questions in one organized batch. Use `ask_user_question` for structured decisions; otherwise ask a numbered free-form list. Wait for answers before architecture design.
+Ask all necessary questions in one organized batch. Use structured-choice prompts for discrete decisions when available; otherwise ask a numbered free-form list. Wait for answers before architecture design.
 
 If the user says “whatever you think is best,” state your recommendation and get explicit confirmation unless the decision is low-risk and reversible.
 
@@ -122,28 +83,18 @@ If the user says “whatever you think is best,” state your recommendation and
 
 Goal: compare viable implementation approaches and get approval.
 
-For complex work, run 2-3 planning passes with different trade-off lenses:
-
-```ts
-subagent({
-  tasks: [
-    {
-      agent: "planner",
-      task: "Design a minimal-change implementation for <feature> using the exploration findings and clarified requirements below. Include files to change, build sequence, risks, validation. Do not edit files.\n\n<context>..."
-    },
-    {
-      agent: "planner",
-      task: "Design a clean-architecture implementation for <feature> prioritizing maintainability and testability. Include files to change, build sequence, risks, validation. Do not edit files.\n\n<context>..."
-    },
-    {
-      agent: "planner",
-      task: "Design a pragmatic balanced implementation for <feature>. Include files to change, build sequence, risks, validation. Do not edit files.\n\n<context>..."
-    }
-  ],
-  concurrency: 3,
-  context: "fresh"
-})
-```
+For complex work, run 2-3 planning passes with different trade-off lenses. These can be separate self-review passes or delegated read-only planning if available:
+
+1. **Minimal-change implementation** — smallest safe diff using existing patterns.
+2. **Clean-architecture implementation** — prioritize maintainability, testability, and clear boundaries.
+3. **Pragmatic balanced implementation** — balance implementation cost, maintainability, and risk.
+
+Each pass should include:
+
+- files to change
+- build sequence
+- risks and trade-offs
+- validation plan
 
 Then synthesize:
 
@@ -153,7 +104,7 @@ Then synthesize:
 - your recommendation and reasoning
 - validation plan
 
-Ask the user which approach to use. `ask_user_question` is ideal here with options like Minimal, Pragmatic, Clean.
+Ask the user which approach to use. A structured choice is helpful when available, with options like Minimal, Pragmatic, Clean.
 
 ### Phase 5 — Implementation
 
@@ -163,16 +114,33 @@ Do not start without explicit approval.
 
 Implementation options:
 
-- **Parent writes directly** for small/medium scoped changes where you already have enough context.
-- **One `worker` subagent** for larger changes after approval. Provide a complete handoff: requirements, chosen approach, files/areas, non-goals, acceptance criteria, validation, and escalation rules.
+- **Main session writes directly** for small/medium scoped changes where enough context is already available.
+- **One dedicated writer** for larger changes after approval, if the environment supports handoff. Provide requirements, chosen approach, files/areas, non-goals, acceptance criteria, validation, and escalation rules.
+
+Writer handoff shape:
+
+```text
+Implement the approved <feature> plan.
+
+Clarified requirements:
+- ...
+
+Chosen approach:
+- ...
+
+Likely files/areas:
+- ...
 
-Worker handoff shape:
+Non-goals:
+- ...
 
-```ts
-subagent({
-  agent: "worker",
-  task: "Implement the approved <feature> plan.\n\nClarified requirements:\n- ...\n\nChosen approach:\n- ...\n\nLikely files/areas:\n- ...\n\nNon-goals:\n- ...\n\nAcceptance criteria:\n- ...\n\nValidation expected:\n- ...\n\nUse one writer thread only. Ask before unapproved product, API, or architecture changes. Summarize files changed and validation results."
-})
+Acceptance criteria:
+- ...
+
+Validation expected:
+- ...
+
+Use one writer thread only. Ask before unapproved product, API, or architecture changes. Summarize files changed and validation results.
 ```
 
 During implementation:
@@ -180,37 +148,22 @@ During implementation:
 1. Follow existing patterns discovered earlier.
 2. Keep changes focused on the approved scope.
 3. Add or update tests when appropriate.
-4. Update todos as each implementation subtask finishes.
+4. Update progress tracking as each implementation subtask finishes when such tracking is available.
 5. If a new major decision appears, stop and ask.
 
 ### Phase 6 — Quality Review
 
 Goal: catch correctness, test, and maintainability issues.
 
-After implementation, review the current diff. Default parallel review:
-
-```ts
-subagent({
-  tasks: [
-    {
-      agent: "reviewer",
-      task: "Review the current diff for correctness, regressions, edge cases, and security issues. Inspect changed files directly. Do not edit files. Report only evidence-backed issues with file/line references."
-    },
-    {
-      agent: "reviewer",
-      task: "Review the current diff for tests and validation quality. Inspect changed files directly. Do not edit files. Report missing high-value tests or broken validation with file/line references."
-    },
-    {
-      agent: "reviewer",
-      task: "Review the current diff for simplicity, DRYness, maintainability, and project convention fit. Inspect changed files directly. Do not edit files. Report only important issues with file/line references."
-    }
-  ],
-  concurrency: 3,
-  context: "fresh"
-})
-```
+After implementation, review the current diff. For non-trivial changes, inspect it from these independent perspectives yourself or with read-only review helpers if available:
+
+1. Correctness, regressions, edge cases, and security.
+2. Tests and validation quality.
+3. Simplicity, maintainability, duplication, and project convention fit.
+
+Each review perspective should inspect changed files directly and report only evidence-backed issues with file/line references.
 
-Synthesize reviewer output into:
+Synthesize review output into:
 
 - blockers / must-fix now
 - fixes worth doing now
@@ -226,8 +179,8 @@ Goal: prove the feature is complete and document outcomes.
 Actions:
 
 1. Run focused validation: tests, typecheck, lint, build, or manual checks appropriate to the project.
-2. If validation fails, keep the current todo `in_progress`, explain the blocker, and fix or ask for direction.
-3. When validation passes or the user accepts known limitations, mark todos complete.
+2. If validation fails, keep the current phase active, explain the blocker, and fix or ask for direction.
+3. When validation passes or the user accepts known limitations, mark the workflow complete in whatever progress tracking is available.
 4. Summarize:
    - what was built
    - key decisions made

package/skills/plan-make/SKILL.md

@@ -0,0 +1,196 @@
+---
+name: plan-make
+description: Create structured implementation plans in docs/plans/ for feature work, bug fixes, refactors, migrations, or unclear implementation requests. Use when the user asks to make an implementation plan, planning document, task checklist, or staged coding plan before implementation.
+---
+
+# Implementation Plan Creation
+
+Create an implementation plan in `docs/plans/YYYYMMDD-title.md` after focused discovery and user-guided scope decisions.
+
+## Workflow
+
+1. Parse the user's request to identify the likely intent: feature development, bug fix, refactor, migration, or generic exploration.
+2. Gather context before asking questions. Inspect relevant files, project structure, tests, recent status, and existing patterns.
+3. Present a concise context summary, including likely affected areas and any uncertainty.
+4. Ask focused questions one at a time. Prefer multiple-choice questions with a recommended option when the answer can be bounded.
+5. If there are multiple viable implementation paths, present 2-3 approaches with trade-offs and recommend one. Ask the user to choose before writing the plan. Skip this only when the path is obvious or the user already specified the approach.
+6. Preserve enough context in the plan for an isolated reviewer to understand the request, decisions, assumptions, and non-goals without hidden conversation context.
+7. Create the plan file under `docs/plans/` using the current date and a short slug.
+8. After creating the plan, ask the user whether to review, start implementation, or stop after the plan.
+
+## Project Guidance Discovery
+
+Read relevant project guidance when present:
+- `AGENTS.md`
+- `CLAUDE.md`
+- nearby README or contributor docs
+
+Use these files to identify conventions, preferred libraries, test expectations, and existing workflow rules. Limit context loading to guidance relevant to the requested change.
+
+## Discovery Guidance
+
+For feature development:
+
+- Locate related code, patterns, and nearby tests.
+- Identify affected components, dependencies, and user-facing surfaces.
+
+For bug fixing:
+
+- Look for failing tests, logs, stack traces, reproduction clues, and likely owner code.
+- Check recent changes in the problem area when available.
+
+For refactors and migrations:
+
+- Identify all affected files and integration points.
+- Check current test coverage and compatibility requirements.
+
+For generic or unclear requests:
+
+- Check `git status`, top-level structure, package metadata, and primary language/framework.
+- Infer the likely goal from current work, but state uncertainty explicitly.
+
+## Question Flow
+
+Ask only what is needed to make the plan accurate. Use one question per turn.
+
+Typical sequence:
+
+1. Main goal.
+2. Scope or affected components.
+3. Constraints or non-goals.
+4. Testing preference: TDD or regular code-first with tests in each task.
+5. Short plan title.
+
+Do not ask all five if discovery already answers some of them.
+
+## Approach Selection
+
+When alternatives are useful, present them conversationally:
+
+```markdown
+I see three approaches:
+
+**Option A: [name]** (recommended)
+- How it works: ...
+- Pros: ...
+- Cons: ...
+
+**Option B: [name]**
+- How it works: ...
+- Pros: ...
+- Cons: ...
+
+Which direction do you prefer?
+```
+
+If repeated code is involved, explicitly compare duplication versus abstraction and ask when both are reasonable.
+
+## Plan Template
+
+Use this structure and adapt it to the project:
+
+```markdown
+# [Plan Title]
+
+## Overview
+- Clear description of the feature/change.
+- Problem it solves and key benefits.
+- How it integrates with the existing system.
+
+## Context
+- Files/components involved: [list from discovery]
+- Related patterns found: [patterns discovered]
+- Dependencies identified: [dependencies]
+
+## Review Handoff
+- Original request: [user's requested outcome]
+- Key decisions made during planning: [brief bullets]
+- Explicit non-goals: [if any]
+- Open questions or assumptions: [if any]
+
+## Development Approach
+- Testing approach: [TDD / Regular]
+- Complete each task fully before moving to the next.
+- Make small, focused changes.
+- Every code-change task must include new or updated tests.
+- All tests for a task must pass before starting the next task.
+- Update this plan when scope changes during implementation.
+
+## Testing Strategy
+- Unit tests required for every code-change task.
+- E2E tests required for UI flows when the project has an E2E setup.
+- Cover success, error, and edge cases.
+
+## Progress Tracking
+- Mark completed items with `[x]` immediately when done.
+- Add newly discovered tasks with `+` prefix.
+- Document blockers with `BLOCKED:` prefix.
+- Keep the plan in sync with actual work.
+
+## What Goes Where
+- Implementation Steps: tasks achievable within this codebase.
+- Post-Completion: manual or external-system work, without checkboxes.
+
+## Implementation Steps
+
+### Task 1: [specific name]
+**Files:**
+- Create: `exact/path/to/new_file`
+- Modify: `exact/path/to/existing_file`
+
+- [ ] [specific code action with file reference]
+- [ ] [specific test action for success cases]
+- [ ] [specific test action for error/edge cases]
+- [ ] Run relevant tests and confirm they pass before next task.
+
+### Task N-1: Verify Acceptance Criteria
+- [ ] Verify all Overview requirements are implemented.
+- [ ] Verify edge cases are handled.
+- [ ] Run full test suite: `[command]`
+- [ ] Run E2E tests if applicable: `[command]`
+
+### Task N: Final Documentation
+- [ ] Update README or project docs if needed.
+- [ ] Update agent/project instructions if new patterns were discovered.
+- [ ] Move this plan to `docs/plans/completed/`.
+
+## Technical Details
+- Data structures and changes.
+- Parameters and formats.
+- Processing flow.
+
+## Post-Completion
+Items requiring manual intervention or external systems.
+
+**Manual verification**:
+- [scenario]
+
+**External system updates**:
+- [system/configuration/integration]
+```
+
+## Execution Rules
+
+If the user chooses to start implementation from the plan:
+
+1. Complete one task at a time.
+2. Write or update tests in the same task as the code change.
+3. Run the relevant test command before moving to the next task.
+4. Mark task checkboxes as soon as work is completed.
+5. If tests fail, fix failures before proceeding.
+6. If a task cannot fully pass until a later task, still write the test, note the dependency in the plan, and revisit it when the dependent task completes.
+7. On completion, run the final verification commands and move the plan to `docs/plans/completed/`.
+
+## Next Step Prompt
+
+After creating the file, tell the user:
+
+```text
+Created plan: docs/plans/YYYYMMDD-title.md
+```
+
+Then ask what to do next. Offer options such as:
+
+- Review the plan.
+- Start implementation.
+- Stop after the plan.

package/skills/plan-review/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: plan-review
+description: Review implementation plans before execution. Use after a plan is created or when the user asks to validate a plan for correctness, scope, over-engineering, missing tests, unclear tasks, or project-convention fit. Reviews plan files such as docs/plans/*.md or a user-provided plan path. Prefer isolated read-only review when the host and policy support subagents, fresh-context workers, or review-only agents.
+---
+
+
+You are an expert plan reviewer specializing in validating implementation plans before execution. Your role is to ensure plans solve the stated problem correctly, avoid over-engineering, include proper testing, and follow project conventions.
+
+**CRITICAL: READ-ONLY. Never modify files, only analyze and report findings.**
+
+**CRITICAL: Every finding MUST include `[plan-review]` tag and reference specific plan sections.**
+
+## Isolation Protocol
+
+Prefer an isolated reviewer when the host agent and active policy support subagents, fresh-context workers, review-only agents, or equivalent delegation.
+
+Give the isolated reviewer only:
+- The plan path or plan text
+- The original user request, if available
+- The repository root
+- Any explicit review focus from the user
+
+Do not pass the plan creator's hidden reasoning, conclusions, intended fixes, confidence claims, or prior review commentary.
+
+If isolated review is unavailable, perform a local read-only review. Treat prior planning context as untrusted, reload the plan and relevant project files from disk, and judge the plan against the repository and the original request.
+
+## Expected Plan Contract
+
+A good implementation plan should include:
+- The problem being solved
+- Relevant files, systems, or workflows
+- Project context and existing patterns
+- A development approach
+- Ordered implementation tasks
+- Per-task code actions
+- Per-task test actions
+- Verification commands
+- Acceptance criteria or final validation
+- Explicit non-goals or post-completion work when relevant
+
+If the plan was created by `plan-make`, also check that it follows the expected structure from that skill, but do not require loading `plan-make` to perform this review.
+
+Key rules for implementation tasks:
+- Each task = one logical unit (one function, one endpoint, one component, one migration step, etc.)
+- Use specific descriptive names, not generic "[Core Logic]" or "[Implementation]"
+- Aim for ~5 checkboxes per task (more is OK if logically atomic)
+- Each code-change task MUST include writing/updating tests before moving to the next task
+- Tests are separate checklist items, not bundled with implementation
+- Relevant tests must be run and pass before moving to the next task
+
+## Review Workflow
+
+### Step 1: Locate Plan File
+
+1. If the user provided a plan path, review that plan
+2. Check `docs/plans/` for plan files (exclude `completed/` subdirectory)
+3. If multiple plans exist and context is unclear, list available plans and ask user which to review
+4. If no plans found, inform user and ask for plan location
+
+### Step 2: Load Project Context
+
+Read relevant project guidance when present:
+- `AGENTS.md`
+- `CLAUDE.md`
+- nearby README or contributor docs
+
+Then:
+1. Check for existing code patterns the plan should follow
+2. Understand the codebase structure relevant to the plan
+3. Limit context loading to files relevant to the plan's scope
+
+### Step 3: Analyze Plan
+
+**Review Checklist:**
+
+#### Problem Definition (Critical)
+- Plan clearly states what problem is being solved
+- Problem description is specific, not vague
+- Success criteria are implicit or explicit
+
+#### Solution Correctness (Critical)
+- Proposed solution actually addresses the stated problem
+- No missing steps that would leave problem unsolved
+- Edge cases considered
+
+#### Scope Assessment (Important)
+- Scope is appropriate - not too broad, not too narrow
+- No scope creep (unrelated features bundled in)
+- Dependencies between tasks are logical
+
+#### Over-Engineering Detection (Critical)
+Patterns to detect:
+- Unnecessary abstractions
+- Premature generalization
+- Pattern abuse (using design patterns where simple code suffices)
+- Features "just in case" (YAGNI violations)
+- Excessive layering
+- Complex where simple would work
+
+#### Testing Requirements (Critical)
+Per expected plan contract:
+- Every code-change task includes test writing as separate checklist items
+- Tests for success AND error cases specified
+- Relevant test commands are listed and must pass before the next task
+- Test locations specified (path to test file)
+
+#### Maintainability (Important)
+- Solution will produce readable, maintainable code
+- Follows project conventions from loaded project instructions
+- No clever solutions where clear would work
+- Appropriate decomposition
+
+#### Task Granularity (Important)
+- Tasks are one logical unit (not multiple features bundled)
+- Specific names, not generic like "[Core Logic]"
+- Approximately 5 checkboxes per task (more OK if atomic)
+- Clear progression from task to task
+
+#### Convention Adherence (Important)
+- Follows naming conventions from loaded project instructions
+- Matches existing code patterns in the project
+- Uses project's preferred libraries/approaches
+- Comment style matches project rules
+- Aligns with user-provided custom rules (if loaded above)
+
+## Output Format
+
+```
+## Plan Review: [plan-filename]
+
+### Summary
+Brief assessment of plan quality (2-3 sentences)
+
+### Critical Issues
+Issues that would cause the plan to fail or produce incorrect results.
+
+1. [plan-review] **Section: Implementation Steps > Task 2** (severity: critical)
+   - Issue: Task bundles multiple unrelated features (user auth + logging)
+   - Impact: Will create tangled code, harder to test and review
+   - Fix: Split into Task 2a (user auth) and Task 2b (logging)
+
+### Important Issues
+Issues affecting quality or maintainability.
+
+1. [plan-review] **Section: Technical Details** (severity: important)
+   - Issue: Proposes custom validation library when project uses go-playground/validator
+   - Impact: Inconsistent with existing codebase patterns
+   - Fix: Use existing validator with custom rules
+
+### Minor Issues
+Suggestions for improvement.
+
+1. [plan-review] **Section: Overview** (severity: minor)
+   - Issue: Success criteria not explicitly stated
+   - Fix: Add "Acceptance Criteria" subsection
+
+### Over-Engineering Concerns
+Specific patterns detected that add unnecessary complexity:
+
+- [plan-review] **Task 4**: Proposes interface for single implementation - defer abstraction until needed
+- [plan-review] **Technical Details**: Custom error type hierarchy when simple wrapped errors suffice
+
+### Testing Coverage Assessment
+- Tasks with proper test requirements: X/Y
+- Missing test specifications: [list tasks]
+- Test-first (TDD) compliance: [yes/partial/no]
+
+### Verdict
+**[APPROVE / APPROVE WITH NOTES / NEEDS REVISION]**
+
+[If NEEDS REVISION]:
+Priority fixes before implementation:
+1. [most critical fix]
+2. [second priority]
+3. [third priority]
+```
+
+## Key Principles
+
+1. **Solve the actual problem** - Plans must address the stated problem, not adjacent issues
+2. **YAGNI ruthlessly** - Flag anything "for future flexibility" without current need
+3. **Tests are mandatory** - Every code-change task must include test requirements
+4. **Match existing patterns** - New code should look like it belongs in the codebase
+5. **Simple over clever** - Prefer straightforward solutions
+6. **Ask when unclear** - If plan context is ambiguous, ask user rather than guess
+
+## When NOT to Flag
+
+- Reasonable abstractions that solve real problems
+- Testing infrastructure that the plan will actually use
+- Complexity that's inherent to the problem domain
+- Patterns that match existing codebase conventions
+
+## Confidence Scoring
+
+Rate severity as:
+- **Critical**: Would cause plan failure or major issues
+- **Important**: Affects quality but plan could work
+- **Minor**: Suggestions for polish
+
+Only report issues you're confident about. If unsure whether something is over-engineering, note it as a question rather than a finding.