pi-feature-dev 1.1.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.1.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": {
@@ -16,10 +16,8 @@
     "access": "public"
   },
   "keywords": [
-    "pi-package",
-    "pi",
-    "pi-coding-agent",
     "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.