pi-feature-dev 1.2.0 → 1.3.0

package/README.md

@@ -1,8 +1,9 @@
 # pi-feature-dev
 
-Portable guided feature development workflow, packaged as a Pi skill.
+Portable coding-agent workflows, packaged as Pi skills.
 
-The skill describes a tool-agnostic process for non-trivial feature work:
+The `feature-dev` skill describes a tool-agnostic process for non-trivial
+feature work:
 
 - clarify requirements before coding
 - explore the existing codebase before design
@@ -13,6 +14,11 @@ The skill describes a tool-agnostic process for non-trivial feature work:
 
 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.
 
+The `plan-exec` skill executes implementation plan files task by task with
+isolated workers, Git task commits, internal reviews, finalize, and a portable
+run summary. It is portable across host agents that provide fresh-context
+isolated workers and Git access.
+
 ## Install
 
 From npm:
@@ -43,6 +49,14 @@ pi install -l ~/Projects/pi-feature-dev
 
 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.
 
+## Credits
+
+The original Claude Code skills and workflows that informed these portable
+versions came from:
+
+- [umputun/cc-thingz](https://github.com/umputun/cc-thingz)
+- [anthropics/claude-code feature-dev plugin](https://github.com/anthropics/claude-code/tree/main/plugins/feature-dev)
+
 ## Usage
 
 Skill command in Pi:
@@ -59,11 +73,17 @@ Use feature-dev to implement API rate limiting.
 
 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.
+Run a plan with `plan-exec`:
+
+```text
+/skill:plan-exec docs/plans/20260518-example.md
+```
+
+This package is intentionally skill-only. It does not provide prompt template shortcuts; use `/skill:<name>` for explicit Pi invocation.
 
-## What it does
+## Feature-dev workflow
 
-The skill guides a coding assistant through a seven-phase process:
+The `feature-dev` skill guides a coding assistant through a seven-phase process:
 
 1. Discovery — understand the feature and establish lightweight progress tracking
 2. Codebase exploration — inspect relevant code and patterns, optionally with read-only helper passes
@@ -79,7 +99,15 @@ The skill guides a coding assistant through a seven-phase process:
 pi-feature-dev/
 ├── package.json
 └── skills/
-    └── feature-dev/
+    ├── feature-dev/
+    │   └── SKILL.md
+    ├── plan-exec/
+    │   ├── SKILL.md
+    │   ├── references/
+    │   └── scripts/
+    ├── plan-make/
+    │   └── SKILL.md
+    └── plan-review/
         └── SKILL.md
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-feature-dev",
-  "version": "1.2.0",
-  "description": "Portable guided feature development workflow for coding assistants, packaged as a Pi skill.",
+  "version": "1.3.0",
+  "description": "Portable coding-agent workflows packaged as skills.",
   "license": "MIT",
   "type": "module",
   "repository": {
@@ -17,6 +17,7 @@
   },
   "keywords": [
     "feature-development",
+    "plan-execution",
     "coding-assistants",
     "workflow",
     "skills"

package/skills/plan-exec/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: plan-exec
+description: Execute implementation plan files task by task with isolated workers, task commits, internal reviews, finalize, and a portable run summary.
+compatibility: "Portable across coding assistant environments that support fresh-context isolated workers, repository file access, shell commands, and Git commits. If isolated workers are unavailable, stop instead of running inline."
+---
+
+# Plan Exec
+
+Execute a plan file one task section at a time. The main session is the
+orchestrator. Implementation, fixing, finalization, and summary work happens in
+fresh-context isolated workers.
+
+This skill is agent-agnostic, but not lowest-common-denominator. It requires a
+host agent that can launch isolated workers with repository access.
+
+## Required Capabilities
+
+Before starting, verify that the current host agent supports all required
+capabilities:
+
+- Read and edit files in the repository.
+- Run shell commands in the repository.
+- Launch fresh-context isolated workers.
+- Give implementation and fixer workers write authority.
+- Give review and summary workers read-only authority.
+- Commit selected files with Git.
+
+If any required capability is missing, stop and explain which capability is not
+available. Do not perform implementation work in the main orchestrating session.
+
+## Compatibility Boundaries
+
+- Git only. Stop if the current directory is not inside a Git repository.
+- In-place execution only. Do not create Git worktrees.
+- No prompt overrides. Always use the bundled prompt and reviewer files shipped
+  inside this skill.
+- No custom rules loading. Follow the host agent, user, and repository
+  instructions that are already in effect.
+- No external review tools. All reviews are performed by isolated workers in the
+  current host agent.
+- Do not push, open pull requests, or move the plan file unless the plan itself
+  explicitly requires it.
+
+## Arguments
+
+- Optional plan path. If omitted, choose from `docs/plans/`.
+
+## Bundled Files
+
+Set `PLAN_EXEC_ROOT` to the absolute path of the directory containing this
+`SKILL.md`. Read bundled files directly from:
+
+- `PLAN_EXEC_ROOT/references/prompts/task.md`
+- `PLAN_EXEC_ROOT/references/prompts/review.md`
+- `PLAN_EXEC_ROOT/references/prompts/fixer.md`
+- `PLAN_EXEC_ROOT/references/prompts/finalizer.md`
+- `PLAN_EXEC_ROOT/references/prompts/stats.md`
+- `PLAN_EXEC_ROOT/references/agents/*.txt`
+- `PLAN_EXEC_ROOT/scripts/*.sh`
+
+After reading a bundled prompt, replace all placeholders before passing it to a
+worker:
+
+- `PLAN_FILE_PATH`
+- `PROGRESS_FILE_PATH`
+- `DEFAULT_BRANCH`
+- `PLAN_EXEC_ROOT`
+- `FINDINGS_LIST` when using the fixer prompt
+- `REVIEW_PHASE` when using the review playbook
+
+## Process
+
+### Step 1. Resolve Plan File
+
+If a plan path was provided, use it. Otherwise, list markdown files in
+`docs/plans/`, excluding `docs/plans/completed/`.
+
+- If exactly one plan is found, use it.
+- If multiple plans are found, ask the user to choose one.
+- If no plan is found, stop and ask for a plan path.
+
+Read the plan file. Count all `### Task N:` and `### Iteration N:` sections so
+the run has a visible scope.
+
+Determine the default branch:
+
+```bash
+bash PLAN_EXEC_ROOT/scripts/detect-branch.sh
+```
+
+Capture the result as `DEFAULT_BRANCH`.
+
+### Step 2. Create Or Update Progress Tracking
+
+Use any host-provided task/progress UI when available. Otherwise keep a concise
+checklist in chat. Track one item per plan task plus these fixed phases:
+
+- Review phase 1: comprehensive and critical re-checks
+- Review phase 2: code smells
+- Review phase 3: critical only
+- Finalize
+- Run summary
+
+### Step 3. Create Or Reuse Feature Branch
+
+Run in the current checkout only. Do not create or enter a worktree.
+
+Create a feature branch when currently on the default branch, or keep using the
+current branch when already on a non-default branch:
+
+```bash
+bash PLAN_EXEC_ROOT/scripts/create-branch.sh PLAN_FILE_PATH
+```
+
+The script derives a branch name from the plan filename by stripping a leading
+date prefix. Capture the branch name it prints.
+
+### Step 4. Initialize Progress File
+
+Create a progress file in `/tmp` using the plan filename stem, for example
+`/tmp/progress-fix-issues.txt`:
+
+```bash
+bash PLAN_EXEC_ROOT/scripts/init-progress.sh /tmp/progress-<plan-name>.txt PLAN_FILE_PATH <branch-name>
+```
+
+Report the full progress file path to the user.
+
+After initialization, append only through:
+
+```bash
+bash PLAN_EXEC_ROOT/scripts/append-progress.sh PROGRESS_FILE_PATH "message"
+```
+
+or by piping multiline content into that script.
+
+### Step 5. Task Loop
+
+Repeat until no unchecked checkboxes remain in any `### Task N:` or
+`### Iteration N:` section.
+
+1. Re-read the plan file. Workers may have modified it.
+2. Find the first task or iteration section containing `[ ]`.
+3. If no such section exists, continue to review phase 1.
+4. Announce the task to the user before launching the worker:
+
+   ```text
+   --- Task N: <title> ---
+   - [ ] <unchecked item>
+   - [ ] <unchecked item>
+   ```
+
+5. Spawn one isolated implementation worker with the bundled `task.md` prompt.
+   Substitute `PLAN_FILE_PATH`, `PROGRESS_FILE_PATH`, and `PLAN_EXEC_ROOT`.
+6. After the worker returns, re-read the plan file and verify that the task
+   section has no remaining `[ ]` items.
+7. If the task is complete, report `Task N completed` and continue.
+8. If the task still has unchecked items, retry with a fresh isolated worker up
+   to `task_retries` times. Default `task_retries` is `1` if the host or user did
+   not configure it.
+9. If all retries fail, stop and report the failure.
+
+The only success signal is the plan file state. Do not rely on the worker's
+final message alone.
+
+Orchestrator constraints:
+
+- Do not implement code yourself.
+- Do not debug or fix worker failures yourself.
+- If a worker leaves compiler errors, test failures, or incomplete checkboxes,
+  retry with a fresh worker and include the failure details in the prompt.
+- Do not modify the plan file yourself; implementation workers own plan
+  checkbox updates.
+
+Maximum task loop iterations: 50. If reached, stop and report the safety limit.
+
+### Step 6. Review Phase 1 - Comprehensive Then Critical Re-Checks
+
+Report:
+
+```text
+--- Review phase 1: comprehensive ---
+```
+
+Loop up to `review_iterations` times. Default `review_iterations` is `5` if the
+host or user did not configure it.
+
+For iteration 1, use `REVIEW_PHASE=comprehensive` in the bundled `review.md`
+playbook. It launches five read-only review workers:
+
+- quality
+- implementation
+- testing
+- simplification
+- documentation
+
+For iteration 2 and later, report:
+
+```text
+--- Review phase 1: critical re-check (iteration N) ---
+```
+
+Use `REVIEW_PHASE=critical`. It launches two read-only review workers:
+
+- quality
+- implementation
+
+Parallel review workers are preferred when the host supports parallel isolated
+workers. If parallel launch is unavailable, run the review workers sequentially,
+but they must still be isolated read-only workers.
+
+Collect the complete output from all review workers. Do not summarize, filter,
+verify, dismiss, or reclassify findings. Log the collected findings to the
+progress file, then pass the full unedited finding list to a fixer worker using
+the bundled `fixer.md` prompt.
+
+If all review workers report no issues, report `Review phase 1: clean` and move
+to review phase 2.
+
+After the fixer returns, show its `FIXES:` section to the user, report
+`Review phase 1: iteration N fixes applied`, and loop back for a re-check.
+
+If `review_iterations` is reached with issues still found, report
+`Review phase 1: max iterations reached, moving on` and continue.
+
+### Step 7. Review Phase 2 - Code Smells
+
+Report:
+
+```text
+--- Review phase 2: code smells analysis ---
+```
+
+Run one read-only isolated worker with
+`PLAN_EXEC_ROOT/references/agents/smells.txt`.
+
+The smells worker must inspect the diff against `DEFAULT_BRANCH`, read changed
+files for context, and report only problems.
+
+If no issues are found, report `Smells analysis: clean` and continue.
+
+If issues are found, log the full output to the progress file and launch a fixer
+worker with the bundled `fixer.md` prompt. Pass the full smells output as
+`FINDINGS_LIST`. Show the fixer's `FIXES:` section when it returns.
+
+### Step 8. Review Phase 3 - Critical Only
+
+Report:
+
+```text
+--- Review phase 3: critical/major only ---
+```
+
+Use the bundled `review.md` playbook with `REVIEW_PHASE=critical` for one final
+single pass. Launch the quality and implementation read-only workers. Pass any
+critical or major findings to a fixer worker. Ignore minor findings in this
+phase.
+
+If neither worker reports critical or major findings, report
+`Review phase 3: clean`.
+
+### Step 9. Finalize
+
+Check `finalize_enabled`. Default is `true` if the host or user did not
+configure it. If false, skip this step.
+
+Report:
+
+```text
+--- Finalize: rebase and clean up commits ---
+```
+
+Spawn one isolated finalizer worker with the bundled `finalizer.md` prompt.
+Substitute `DEFAULT_BRANCH`, `PLAN_FILE_PATH`, `PROGRESS_FILE_PATH`, and
+`PLAN_EXEC_ROOT`.
+
+Finalize is best-effort. If rebase or commit cleanup fails, the finalizer must
+leave the branch in a coherent state and report the issue. Do not block the run
+only because commit cleanup was not possible.
+
+### Step 10. Portable Run Summary
+
+Spawn one read-only isolated summary worker with the bundled `stats.md` prompt.
+Substitute `DEFAULT_BRANCH`, `PLAN_FILE_PATH`, and `PROGRESS_FILE_PATH`.
+
+The summary worker reads only the plan file, progress file, and Git state. It
+must not read host-specific telemetry logs or token accounting files.
+
+Show the summary worker's full markdown output to the user.
+
+If the summary worker fails, report the failure but do not block completion.
+
+### Step 11. Completion
+
+Append completion to the progress file:
+
+```bash
+bash PLAN_EXEC_ROOT/scripts/append-progress.sh PROGRESS_FILE_PATH "completed"
+```
+
+Report:
+
+```text
+All N tasks completed, reviews passed, branch finalized
+```
+
+Do not push, create a pull request, or move the plan file unless the user or the
+plan explicitly asked for that.
+
+## Key Rules
+
+- The main session is the orchestrator.
+- Isolated workers do implementation, fixes, finalization, reviews, and summary.
+- Each implementation worker handles exactly one task section.
+- Each implementation or fixer worker must commit its own changes before
+  reporting success.
+- The plan file is the source of truth for task completion.
+- The progress file carries context between phases.
+- Review findings are passed in full to fixer workers.
+- All prompts come from the bundled prompt set.
+- Git worktrees, prompt overrides, custom rules loading, Mercurial support, and
+  external review tools are out of scope.

package/skills/plan-exec/references/agents/documentation.txt

@@ -0,0 +1,55 @@
+Review code changes and identify missing documentation updates.
+
+## README.md (Human Documentation)
+
+Check if changes require README updates:
+
+Must document:
+- New features or capabilities
+- New CLI flags or command-line options
+- New API endpoints or interfaces
+- New configuration options
+- Changed behavior that affects users
+- New dependencies or system requirements
+- Breaking changes
+
+Skip:
+- Internal refactoring with no user-visible changes
+- Bug fixes that restore documented behavior
+- Test additions
+- Code style changes
+
+## Agent and Project Guidance
+
+Check if changes require updates to repository guidance files such as AGENTS.md,
+CLAUDE.md, CONTRIBUTING.md, developer docs, or local conventions docs:
+
+Must document:
+- New architectural patterns discovered/established
+- New conventions or coding standards
+- New build/test commands
+- New libraries or tools integrated
+- Project structure changes
+- Workflow changes
+- Non-obvious debugging techniques
+
+Skip:
+- Standard code additions following existing patterns
+- Simple bug fixes
+- Test additions using existing patterns
+
+## Plan Files
+
+If changes relate to an existing plan:
+- Mark completed items as done
+- Update plan status if needed
+- Note which plan items this change addresses
+
+## What to Report
+
+For each gap:
+- Missing: what needs to be documented
+- Section: where in the documentation it should go
+- Suggested content: draft text or outline
+
+Report problems only - no positive observations.

package/skills/plan-exec/references/agents/implementation.txt

@@ -0,0 +1,26 @@
+Review whether the implementation achieves the stated goal/requirement.
+
+## Core Review Responsibilities
+
+1. Requirement coverage - does implementation address all aspects of the stated requirement? Are there edge cases or scenarios not handled?
+
+2. Correctness of approach - is the chosen approach actually solving the right problem? Could it fail to achieve the goal in certain conditions?
+
+3. Wiring and integration - is everything connected properly? Are new components registered, routes added, handlers wired, configs updated?
+
+4. Completeness - are there missing pieces that would prevent the feature from working? Missing imports, unimplemented interfaces, incomplete migrations?
+
+5. Logic flow - does data flow correctly from input to output? Are transformations correct? Is state managed properly?
+
+6. Edge cases - are boundary conditions handled? Empty inputs, null values, concurrent access, error paths?
+
+## What to Report
+
+For each issue found:
+- Issue: clear description of what's wrong
+- Impact: how this prevents achieving the goal
+- Location: file and line reference
+- Fix: what needs to be added or changed
+
+Focus on correctness of approach, not code style.
+Report problems only - no positive observations.

package/skills/plan-exec/references/agents/quality.txt

@@ -0,0 +1,37 @@
+Review code for bugs, security issues, and quality problems.
+
+## Correctness Review
+
+1. Logic errors - off-by-one errors, incorrect conditionals, wrong operators
+2. Edge cases - empty inputs, nil/null values, boundary conditions, concurrent access
+3. Error handling - all errors checked, appropriate error wrapping, no silent failures
+4. Resource management - proper cleanup, no leaks, correct resource release
+5. Concurrency issues - race conditions, deadlocks, thread/coroutine leaks
+6. Data integrity - validation, sanitization, consistent state management
+
+## Security Analysis
+
+1. Input validation - all user inputs validated and sanitized
+2. Authentication/authorization - proper checks in place
+3. Injection vulnerabilities - SQL, command, path traversal
+4. Secret exposure - no hardcoded credentials or keys
+5. Information disclosure - error messages, logs, debug info
+
+## Simplicity Assessment
+
+1. Direct solutions first - if simple approach works, don't use complex pattern
+2. No enterprise patterns for simple problems - avoid factories, builders for straightforward code
+3. Question every abstraction - each interface/abstraction must solve real problem
+4. No scope creep - changes solve only the stated problem
+5. No premature optimization - unless addressing proven bottlenecks
+
+## What to Report
+
+For each issue:
+- Location: exact file path and line number
+- Issue: clear description
+- Impact: how this affects the code
+- Fix: specific suggestion
+
+Focus on defects that would cause runtime failures, security vulnerabilities, or maintainability problems.
+Report problems only - no positive observations.

package/skills/plan-exec/references/agents/simplification.txt

@@ -0,0 +1,54 @@
+Detect over-engineered and overcomplicated code - code that works but is more complex than necessary.
+
+## Excessive Abstraction Layers
+
+- Wrapper adds nothing - method just calls another method with same signature
+- Factory for single implementation - factory pattern when only one concrete type exists
+- Interface on producer side - interface defined where implemented, not where consumed
+- Layer cake anti-pattern - handler -> service -> repository when each just passes through
+- DTO/Mapper overkill - multiple types representing same data with conversion functions
+
+## Premature Generalization
+
+- Generic solution for specific problem - event bus for one event type
+- Config objects for 2-3 options - options pattern when direct parameters suffice
+- Plugin architecture for fixed functionality - extension points nothing extends
+- Overloaded struct - one type handling all variations with many optional fields
+
+## Unnecessary Indirection
+
+- Pass-through wrappers - methods that only delegate to dependencies
+- Excessive method chaining - builder pattern for simple constructions
+- Interface wrapping primitives - custom types for standard library types
+- Middleware stacking - multiple middlewares that could be one
+
+## Future-Proofing Excess
+
+- Unused extension points - hooks, callbacks, plugins with no callers
+- Versioned internal APIs - v1/v2 when only one version used
+- Feature flags for permanent decisions - flags always on/off
+
+## Unnecessary Fallbacks
+
+- Fallback that never triggers - default path conditions never met
+- Legacy mode kept just in case - old code path always disabled
+- Dual implementations - old + new logic when old has no callers
+- Silent fallbacks hiding problems - catching errors and falling back instead of failing fast
+
+## Premature Optimization
+
+- Caching rarely-accessed data - cache for data read once at startup
+- Custom data structures - complex structures when arrays/maps work
+- Worker pools for occasional tasks - pooling for operations/hour
+- Connection pooling overkill - complex pooling for single connection
+
+## What to Report
+
+For each finding:
+- Location: file and line reference
+- Pattern: which over-engineering pattern detected
+- Problem: why this adds unnecessary complexity
+- Simplification: what simpler code would look like
+- Effort: trivial/small/medium/large
+
+Report problems only - no positive observations.

package/skills/plan-exec/references/agents/smells.txt

@@ -0,0 +1,43 @@
+Review code for style consistency, convention adherence, and code smells.
+
+## Project Convention Check
+
+1. Read repository guidance files when present, such as AGENTS.md, CLAUDE.md, CONTRIBUTING.md, README.md, or local docs, to understand project rules
+2. Read any documentation files referenced by those guidance files (coding standards, style guides)
+3. Check if changed code follows the established conventions
+
+## Style Consistency
+
+1. Naming conventions - do new names follow the same patterns as existing code?
+2. Code organization - is new code structured like existing code in the same package/module?
+3. Import ordering - does it match the rest of the project?
+4. Comment style - do comments follow project conventions?
+5. Error handling patterns - does error handling match the project's established patterns?
+6. Logging patterns - are log calls consistent with the rest of the codebase?
+
+## Code Smells
+
+1. Dead code - unused functions, variables, imports, parameters
+2. Duplicated logic - copy-paste code that should be consolidated
+3. Long functions - functions doing too many things
+4. Deep nesting - excessive if/else or loop nesting
+5. Magic numbers/strings - unexplained literal values
+6. Inconsistent abstraction levels - mixing high and low level operations
+
+## Anti-patterns
+
+1. God objects - types with too many responsibilities
+2. Shotgun surgery - one change requires touching many unrelated files
+3. Feature envy - code that uses another module's data more than its own
+4. Primitive obsession - using primitives where a domain type would be clearer
+
+## What to Report
+
+For each finding:
+- Location: file and line reference
+- Issue: what's inconsistent or smelly
+- Convention: what the project convention is (cite CLAUDE.md or existing code as evidence)
+- Fix: specific suggestion to align with conventions
+
+Report problems only - no positive observations.
+Focus on consistency with existing code, not personal preferences.

package/skills/plan-exec/references/agents/testing.txt

@@ -0,0 +1,51 @@
+Review test coverage and quality.
+
+## Test Existence and Coverage
+
+1. Missing tests - new code paths without corresponding tests
+2. Untested error paths - error conditions not verified
+3. Coverage gaps - functions or branches without test coverage
+4. Integration test needs - system boundaries requiring integration tests
+
+## Test Quality
+
+1. Tests verify behavior, not implementation details
+2. Each test is independent, can run in any order
+3. Descriptive test names that explain what is being tested
+4. Both success and error paths tested
+5. Edge cases and boundary conditions covered
+
+## Fake Test Detection
+
+Watch for tests that don't actually verify code:
+- Tests that always pass regardless of code changes
+- Tests checking hardcoded values instead of actual output
+- Tests verifying mock behavior instead of code using the mock
+- Ignored errors with _ or empty error checks
+- Conditional assertions that always pass
+- Commented out failing test cases
+
+## Test Independence
+
+1. No shared mutable state between tests
+2. Proper setup and teardown
+3. No order dependencies between tests
+4. Resources properly cleaned up
+
+## Edge Case Coverage
+
+1. Empty inputs and collections
+2. Null/nil values
+3. Boundary values (zero, max, min)
+4. Concurrent access scenarios
+5. Timeout and cancellation handling
+
+## What to Report
+
+For each finding:
+- Location: test file and function
+- Issue: what's wrong with the test
+- Impact: what bugs could slip through
+- Fix: how to improve the test
+
+Report problems only - no positive observations.

package/skills/plan-exec/references/prompts/finalizer.md

@@ -0,0 +1,57 @@
+# Finalizer worker prompt
+
+Use this prompt after all reviews pass. Replace `DEFAULT_BRANCH`,
+`PLAN_FILE_PATH`, `PROGRESS_FILE_PATH`, and `PLAN_EXEC_ROOT` before launch.
+
+```text
+Post-completion finalize step. Organize the branch for merge.
+
+Plan file: PLAN_FILE_PATH
+Default branch: DEFAULT_BRANCH
+Progress file: PROGRESS_FILE_PATH
+
+STEP 1 - REBASE:
+- Run `git fetch origin`.
+- If `origin/DEFAULT_BRANCH` exists, rebase onto it:
+  `git rebase origin/DEFAULT_BRANCH`
+- Otherwise, rebase onto the local default branch:
+  `git rebase DEFAULT_BRANCH`
+- If conflicts occur, resolve them and continue when safe.
+- If rebase cannot be completed safely, abort with `git rebase --abort`, report
+  the issue, and continue to the report step.
+
+STEP 2 - CLEAN UP COMMITS:
+- Inspect commits with `git log --oneline DEFAULT_BRANCH..HEAD`.
+- If there are 5 or more commits, squash related fix commits into their parent
+  feature commits when this can be done safely.
+- Keep meaningful boundaries: feature task commits separate from review-fix
+  commits.
+- If safe non-interactive cleanup is not practical, leave commits as-is and
+  report why.
+
+STEP 3 - VERIFY:
+- Run validation commands from the plan file.
+- If the plan does not list exact commands, infer the narrowest relevant
+  validation commands from the repository.
+- If validation fails, fix and re-run when the fix is clearly within scope.
+
+STEP 4 - LOG PROGRESS:
+- Append:
+  `bash PLAN_EXEC_ROOT/scripts/append-progress.sh PROGRESS_FILE_PATH "finalize: completed"`
+- Then pipe details:
+  `printf '%s\n' "- rebase: <success/failed/skipped>" "- commits before: <N>, after: <M>" "- squashed: <list or none>" "- validation: <passed/failed>" | bash PLAN_EXEC_ROOT/scripts/append-progress.sh PROGRESS_FILE_PATH`
+- Use only `append-progress.sh` for writing to the progress file.
+
+STEP 5 - PLAN DEVIATION ANALYSIS:
+- Read PROGRESS_FILE_PATH in full.
+- Compare it against PLAN_FILE_PATH.
+- Report deviations from the original plan, obstacles or blockers, incomplete
+  delivery, cut corners, or review findings that went beyond the original plan.
+
+STEP 6 - REPORT:
+Report what was done: number of commits before and after, whether rebase
+succeeded, validation results, and plan deviation analysis.
+
+This step is best-effort. If rebase or commit cleanup fails, explain why and
+leave the branch in a coherent state.
+```

package/skills/plan-exec/references/prompts/fixer.md

@@ -0,0 +1,58 @@
+# Fixer worker prompt
+
+Use this prompt after collecting review findings. Replace `PLAN_FILE_PATH`,
+`PROGRESS_FILE_PATH`, `PLAN_EXEC_ROOT`, and `FINDINGS_LIST` before launch.
+
+```text
+Code review found the following issues. Verify and fix them.
+
+Plan file: PLAN_FILE_PATH
+Progress file: PROGRESS_FILE_PATH
+
+FINDINGS:
+FINDINGS_LIST
+
+STEP 1 - VERIFY:
+For each finding, read the actual code at the specified file and line. Inspect
+enough surrounding context to understand the issue. Classify each finding as:
+- CONFIRMED: real issue, fix it.
+- FALSE POSITIVE: does not exist, is already mitigated, or is outside the
+  changed behavior.
+
+STEP 2 - FIX:
+- Fix all confirmed issues.
+- Add or update tests when the finding is about behavior, correctness, or a
+  regression risk.
+- Keep fixes scoped to the reported issues.
+
+STEP 3 - VALIDATE:
+- Run the build, test, lint, typecheck, or validation commands from
+  PLAN_FILE_PATH.
+- If the plan does not list exact commands, infer the narrowest relevant
+  validation commands from the repository.
+- If anything fails, fix it and re-run validation.
+- Never commit broken code.
+
+STEP 4 - COMMIT:
+- Commit fixes only after validation passes:
+  `bash PLAN_EXEC_ROOT/scripts/stage-and-commit.sh "fix: address code review findings" <changed-files>`
+- List every changed file explicitly.
+- If all findings are false positives and no files changed, do not create an
+  empty commit.
+
+STEP 5 - LOG PROGRESS:
+- Pipe details:
+  `printf '%s\n' "- confirmed: <list>" "- false positives: <list>" "- fixes: <what changed>" "- validation: <what passed>" | bash PLAN_EXEC_ROOT/scripts/append-progress.sh PROGRESS_FILE_PATH`
+- Use only `append-progress.sh` for writing to the progress file. Do not write to
+  the progress file directly.
+
+STEP 6 - REPORT:
+Your final response must include a structured summary starting with `FIXES:` on
+its own line, followed by one line per fix or false positive:
+
+FIXES:
+- fixed: <file>:<line> - <what was fixed>
+- false positive: <description> - <why discarded>
+
+This report is shown to the user. Be specific about what changed.
+```

package/skills/plan-exec/references/prompts/progress-file.md

@@ -0,0 +1,73 @@
+# Progress file
+
+The orchestrator maintains a progress file at `/tmp/progress-<plan-name>.txt`,
+derived from the plan filename stem. The file carries context across task,
+review, fixer, finalizer, and summary phases.
+
+## When to write
+
+Use `PLAN_EXEC_ROOT/scripts/append-progress.sh` for all appends. Do not write
+directly to the progress file.
+
+At start, `init-progress.sh` writes:
+
+```text
+# progress
+Plan: <plan-file-path>
+Branch: <branch-name>
+Started: <timestamp>
+---
+```
+
+After each task completes:
+
+```text
+[task] Task N: <title> - completed
+```
+
+After each task fails:
+
+```text
+[task] Task N: <title> - FAILED (retry N)
+```
+
+Before each review phase:
+
+```text
+--- review phase N: <type> ---
+```
+
+After review workers return, before the fixer:
+
+```text
+[review] phase N iteration M findings:
+<full worker output>
+```
+
+After a fixer completes:
+
+```text
+[fixer] phase N iteration M:
+<fixer report>
+```
+
+After finalize:
+
+```text
+[finalize]
+<finalizer report>
+```
+
+At completion:
+
+```text
+---
+Completed: <timestamp>
+```
+
+## How to pass it
+
+- Pass the progress file path to task, fixer, finalizer, and summary workers.
+- Review workers may read the progress file for context, but must remain
+  read-only.
+- The summary worker uses it to derive portable run statistics.

package/skills/plan-exec/references/prompts/review.md

@@ -0,0 +1,104 @@
+# Internal review playbook
+
+This file is a playbook for the main orchestrator session, not a worker prompt.
+Replace `DEFAULT_BRANCH`, `PLAN_FILE_PATH`, `PROGRESS_FILE_PATH`,
+`PLAN_EXEC_ROOT`, and `REVIEW_PHASE`, then follow the instructions from the main
+session.
+
+All review work must be done by isolated read-only workers. If the host supports
+parallel isolated workers, launch all workers for the phase together. If parallel
+launch is unavailable, run the workers sequentially. Do not review or fix issues
+in the orchestrator session.
+
+Each review worker prompt must start with this preamble:
+
+```text
+CRITICAL: You are a READ-ONLY reviewer. Do not run git stash, git checkout, git
+reset, git commit, or any command that modifies the working tree. Other workers
+may run in parallel. Only use read-only commands such as git diff, git log, git
+show, and file reads.
+
+Run `git diff DEFAULT_BRANCH...HEAD` to see the full branch diff. Read the
+actual source files for context; do not review from the diff alone.
+
+The plan file at PLAN_FILE_PATH describes the goal and requirements.
+The progress file at PROGRESS_FILE_PATH describes previous task and fix work.
+Re-evaluate findings independently. Previous fixes may be incomplete.
+
+Tag every finding with severity:
+- CRITICAL: crash, data loss, security vulnerability, race condition, or broken
+  core behavior.
+- MAJOR: real correctness issue, missing critical error handling, broken
+  contract, or incomplete requirement.
+- MINOR: style, documentation drift, convention mismatch, simplification, or
+  optional improvement.
+
+Format each finding on its own line:
+`SEVERITY: file:line - description`
+
+Report problems only. If you find no issues, report exactly:
+`NO ISSUES FOUND`
+```
+
+## Comprehensive Mode
+
+Used when `REVIEW_PHASE` is `comprehensive`.
+
+Launch five read-only workers using these bundled reviewer files:
+
+- `PLAN_EXEC_ROOT/references/agents/quality.txt`
+- `PLAN_EXEC_ROOT/references/agents/implementation.txt`
+- `PLAN_EXEC_ROOT/references/agents/testing.txt`
+- `PLAN_EXEC_ROOT/references/agents/simplification.txt`
+- `PLAN_EXEC_ROOT/references/agents/documentation.txt`
+
+For each worker, prepend the read-only preamble above to the corresponding
+reviewer file content.
+
+After all workers return, produce a strict finding report:
+
+- Group findings by severity in this order: `CRITICAL`, `MAJOR`, `MINOR`.
+- Use a heading per severity: `### CRITICAL`, `### MAJOR`, `### MINOR`.
+- Skip severity headings with zero findings.
+- Under each heading, use exactly:
+  `- <reviewer-name>: <file:line> - <description>`
+- Preserve reviewer attribution: `quality`, `implementation`, `testing`,
+  `simplification`, or `documentation`.
+- If two reviewers report the same file, line, and issue, merge into one bullet
+  and join reviewer names with `+`.
+- Do not verify, fix, dismiss, or rewrite findings.
+- Omit reviewers that found nothing.
+- After the bullet list, emit:
+  `Total: <N> findings (<C> critical, <M> major, <m> minor)`
+
+If all workers report `NO ISSUES FOUND`, emit exactly:
+
+```text
+Comprehensive review: clean - no findings.
+```
+
+## Critical-Only Mode
+
+Used when `REVIEW_PHASE` is `critical`.
+
+Launch two read-only workers using these bundled reviewer files:
+
+- `PLAN_EXEC_ROOT/references/agents/quality.txt`
+- `PLAN_EXEC_ROOT/references/agents/implementation.txt`
+
+For each worker, prepend the read-only preamble above plus this additional
+instruction:
+
+```text
+Report only CRITICAL and MAJOR issues. Ignore MINOR findings, style concerns,
+optional improvements, documentation nits, and simplification opportunities.
+```
+
+After both workers return, produce the same strict finding report as
+comprehensive mode, but include only `CRITICAL` and `MAJOR` sections.
+
+If neither worker reports critical or major findings, emit exactly:
+
+```text
+Critical review: clean - no critical/major findings.
+```

package/skills/plan-exec/references/prompts/stats.md

@@ -0,0 +1,82 @@
+# Portable run summary prompt
+
+Use this for the read-only summary worker after finalize completes. Replace
+`DEFAULT_BRANCH`, `PLAN_FILE_PATH`, and `PROGRESS_FILE_PATH` before launch.
+
+```text
+You are a read-only summary worker for a plan-exec run that just finished.
+Produce a concise markdown summary from the plan file, progress file, and Git
+state only.
+
+Plan file: PLAN_FILE_PATH
+Progress file: PROGRESS_FILE_PATH
+Default branch: DEFAULT_BRANCH
+
+READ-ONLY CONSTRAINTS:
+- Do not modify files.
+- Do not edit the plan.
+- Do not commit.
+- Do not read host-specific telemetry logs, token logs, session JSONL files, or
+  assistant-internal metadata.
+
+STEP 1 - READ RUN STATE:
+- Read PLAN_FILE_PATH.
+- Read PROGRESS_FILE_PATH if it exists.
+- Determine the current branch with `git branch --show-current`.
+
+STEP 2 - PLAN PROGRESS:
+- Count completed and remaining checkboxes in task or iteration sections.
+- Identify the final run state from the progress file when possible:
+  completed, max-iterations-hit, aborted, or unknown.
+- Count implementation task entries in the progress file when possible.
+- Count review and fixer iterations in the progress file when possible.
+
+STEP 3 - GIT STATS:
+Run read-only Git commands:
+- `git diff --shortstat DEFAULT_BRANCH...HEAD`
+- `git diff --stat DEFAULT_BRANCH...HEAD`
+- `git log --oneline DEFAULT_BRANCH..HEAD`
+
+If those commands fail because DEFAULT_BRANCH is unavailable, retry against
+`origin/DEFAULT_BRANCH` when it exists. If both fail, report `n/a`.
+
+STEP 4 - OUTPUT:
+Emit only this markdown report. Keep it compact.
+
+## Run summary
+
+**Branch:** <current branch>  
+**Plan:** PLAN_FILE_PATH  
+**Final state:** <completed | max-iterations-hit | aborted | unknown>
+
+### Plan progress
+
+- Task sections complete: <N>/<M>
+- Remaining unchecked items: <N>
+- Implementation task runs: <N or n/a>
+
+### Review and fixes
+
+- Review phase 1 iterations: <N or n/a>
+- Smells review: <clean | fixed | findings | n/a>
+- Critical review: <clean | fixed | findings | n/a>
+- Fixer runs: <N or n/a>
+
+### Branch changes
+
+- Commits on branch: <N or n/a>
+- Diff shortstat: <shortstat or n/a>
+
+Top files by churn:
+- <file> <stats>
+- <file> <stats>
+- <file> <stats>
+
+### Notable
+
+- Rebase/finalize: <summary or n/a>
+- Validation: <summary or n/a>
+- Deviations/blockers: <summary or n/a>
+
+If a section has no data, write `n/a` rather than inventing numbers.
+```

package/skills/plan-exec/references/prompts/task.md

@@ -0,0 +1,57 @@
+# Task worker prompt
+
+Use this prompt when spawning each implementation worker. Replace
+`PLAN_FILE_PATH`, `PROGRESS_FILE_PATH`, and `PLAN_EXEC_ROOT` before launch.
+
+```text
+Read the plan file at PLAN_FILE_PATH. Find the FIRST Task section
+(`### Task N:` or `### Iteration N:`) that has uncompleted checkboxes (`[ ]`).
+
+If a task section has `[ ]` checkboxes you cannot complete because they require
+manual testing, deployment verification, credentials, or external systems, mark
+them `[x]` with a note like `[x] manual test (skipped - not automatable)` and
+continue.
+
+CRITICAL CONSTRAINT: Complete ONE task section per worker run.
+A task section is a `### Task N:` or `### Iteration N:` heading with all
+checkboxes underneath it. Complete all checkboxes in that section, then stop.
+Do not continue to the next section.
+
+STEP 1 - IMPLEMENT:
+- Read the plan's Overview, Context, Review Handoff, Development Approach,
+  Testing Strategy, and Technical Details sections when present.
+- Implement all items in the current task section.
+- Write or update tests for the implementation.
+
+STEP 2 - VALIDATE:
+- Run the test, lint, typecheck, build, or validation commands specified in the
+  plan.
+- If the plan does not list exact commands, infer the narrowest relevant
+  validation commands from the repository.
+- Fix any failures and repeat validation until it passes.
+
+STEP 3 - COMPLETE:
+- Edit PLAN_FILE_PATH and change `[ ]` to `[x]` for every checkbox you completed
+  in the current task section.
+- If all task sections are complete and higher-level success criteria checkboxes
+  are now satisfied, mark those `[x]` too.
+- Commit all changed files with:
+  `bash PLAN_EXEC_ROOT/scripts/stage-and-commit.sh "feat: <brief task description>" file1 file2 ...`
+- List every changed file explicitly, including source files, tests, and the plan
+  file.
+
+STEP 4 - LOG PROGRESS:
+- Append a header:
+  `bash PLAN_EXEC_ROOT/scripts/append-progress.sh PROGRESS_FILE_PATH "task N: <title>"`
+- Then pipe details:
+  `printf '%s\n' "- modified: <files>" "- implemented: <what was done>" "- tests: <what tests were added or why skipped>" "- validation: <what commands passed>" | bash PLAN_EXEC_ROOT/scripts/append-progress.sh PROGRESS_FILE_PATH`
+- Use only `append-progress.sh` for writing to the progress file. Do not write to
+  the progress file directly.
+
+STOP after committing and logging progress.
+
+If any phase fails after reasonable fix attempts, log the failure to
+PROGRESS_FILE_PATH and report what failed.
+
+One task section per run. After commit and progress log, stop.
+```

package/skills/plan-exec/scripts/append-progress.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# append to the progress file with timestamp
+# usage: append-progress.sh <progress-file> [message]
+# if message is provided, appends single timestamped line
+# if no message, reads stdin and appends all lines (for multi-line content)
+
+set -e
+
+if [ $# -lt 1 ]; then
+    echo "error: usage: append-progress.sh <file> [message]" >&2
+    exit 1
+fi
+
+file="$1"
+shift
+
+if [ $# -gt 0 ]; then
+    # single line with timestamp
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" >> "$file"
+else
+    # multi-line from stdin
+    cat >> "$file"
+fi

package/skills/plan-exec/scripts/create-branch.sh

@@ -0,0 +1,46 @@
+#!/bin/bash
+# create a feature branch from a plan file name if currently on the default branch
+# usage: create-branch.sh <plan-file-path>
+# exits 0 if a branch was created or an existing feature branch is already active
+# outputs the branch name to stdout
+#
+# strips leading YYYYMMDD- or YYYY-MM-DD- date prefixes from branch names
+
+set -e
+
+if [ -z "${1:-}" ]; then
+    echo "error: plan file path required" >&2
+    exit 1
+fi
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+    echo "error: not a git repository" >&2
+    exit 1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+derive_branch_name() {
+    local name
+    name=$(basename "$1" .md)
+    name=$(echo "$name" | sed 's/^[0-9]\{4\}-\{0,1\}[0-9]\{2\}-\{0,1\}[0-9]\{2\}-//')
+    echo "$name"
+}
+
+current_branch=$(git branch --show-current)
+default_branch=$(bash "$SCRIPT_DIR/detect-branch.sh")
+
+if [ -n "$current_branch" ] && [ "$current_branch" != "$default_branch" ]; then
+    echo "$current_branch"
+    exit 0
+fi
+
+branch_name=$(derive_branch_name "$1")
+
+if git show-ref --verify --quiet "refs/heads/$branch_name" 2>/dev/null; then
+    git checkout "$branch_name"
+else
+    git checkout -b "$branch_name"
+fi
+
+echo "$branch_name"

package/skills/plan-exec/scripts/detect-branch.sh

@@ -0,0 +1,32 @@
+#!/bin/bash
+# detect the default branch name of the current Git repository
+# outputs the branch name to stdout
+# avoids network calls when possible
+
+set -e
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+    echo "error: not a git repository" >&2
+    exit 1
+fi
+
+branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+
+if [ -z "$branch" ]; then
+    for candidate in main master trunk develop; do
+        if git show-ref --verify --quiet "refs/heads/$candidate" 2>/dev/null; then
+            branch="$candidate"
+            break
+        fi
+    done
+fi
+
+if [ -z "$branch" ]; then
+    branch=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | sed 's/.*: //')
+fi
+
+if [ -z "$branch" ]; then
+    branch="main"
+fi
+
+echo "$branch"

package/skills/plan-exec/scripts/init-progress.sh

@@ -0,0 +1,24 @@
+#!/bin/bash
+# initialize the progress file with a header
+# usage: init-progress.sh <progress-file> <plan-path> <branch-name>
+
+set -e
+
+file="$1"
+plan="$2"
+branch="$3"
+
+if [ -z "$file" ] || [ -z "$plan" ] || [ -z "$branch" ]; then
+    echo "error: usage: init-progress.sh <progress-file> <plan-path> <branch-name>" >&2
+    exit 1
+fi
+
+cat > "$file" <<EOF
+# progress
+Plan: $plan
+Branch: $branch
+Started: $(date '+%Y-%m-%d %H:%M:%S')
+---
+EOF
+
+echo "$file"

package/skills/plan-exec/scripts/stage-and-commit.sh

@@ -0,0 +1,21 @@
+#!/bin/bash
+# stage explicit files and commit with a message
+# usage: stage-and-commit.sh <message> <file1> [file2 ...]
+
+set -e
+
+if [ $# -lt 2 ]; then
+    echo "error: usage: stage-and-commit.sh <message> <file1> [file2 ...]" >&2
+    exit 1
+fi
+
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+    echo "error: not a git repository" >&2
+    exit 1
+fi
+
+msg="$1"
+shift
+
+git add -- "$@"
+git commit -m "$msg"