pi-feature-dev 1.2.0 → 1.4.0

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"