prizmkit 1.1.1 → 1.1.4

package/bundled/skills/refactor-pipeline-launcher/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: "refactor-pipeline-launcher"
+description: "Launch and manage the refactor pipeline from within an AI CLI session. Start pipeline in background, monitor logs, check status, stop pipeline. Use this skill whenever the user wants to start refactoring, run the refactor pipeline, check refactor progress, retry refactors, or stop the pipeline. Trigger on: 'run refactor pipeline', 'start refactoring', 'refactor pipeline status', 'stop refactor pipeline', 'retry refactor', 'launch refactor pipeline'. (project)"
+---
+
+# Refactor Pipeline Launcher
+
+Launch the autonomous refactor pipeline from within an AI CLI conversation. The pipeline runs as a fully detached background process -- closing the AI CLI session does NOT stop the pipeline.
+
+### Execution Mode
+
+Three execution modes are available. The user chooses one before configuring other options:
+
+1. **Foreground** (recommended) — `dev-pipeline/run-refactor.sh run`. Visible output, direct error feedback, no orphaned processes.
+2. **Background daemon** — `dev-pipeline/launch-refactor-daemon.sh`. Runs fully detached, survives AI CLI session closure.
+3. **Manual** — Display the assembled command(s) only. Do not execute anything. User runs them on their own.
+
+### When to Use
+
+**Start pipeline** -- User says:
+- "run refactor pipeline", "start refactoring", "launch refactor pipeline"
+- "execute refactor list", "refactor all", "start refactoring tasks"
+- After refactor-planner completes: "refactor it", "start refactoring from the list"
+
+**Check status** -- User says:
+- "refactor pipeline status", "refactor progress", "check refactoring"
+- "how's the refactoring going", "refactor status"
+
+**Stop pipeline** -- User says:
+- "stop refactor pipeline", "stop refactoring", "halt refactor", "pause refactoring"
+
+**Show logs** -- User says:
+- "refactor logs", "show refactor logs", "what's being refactored"
+- "view refactor logs"
+
+**Retry single refactor** -- User says:
+- "retry R-001", "retry this refactor", "re-run R-001"
+
+**Do NOT use this skill when:**
+- User wants to plan refactoring (use `refactor-planner` instead)
+- User wants a single interactive refactor in current session (use `refactor-workflow` — but note it will delegate back here for batch execution)
+- User wants to implement features (use `feature-pipeline-launcher`)
+
+### Prerequisites
+
+Before any action, validate:
+
+1. **refactor pipeline exists**: Confirm `dev-pipeline/launch-refactor-daemon.sh` and `dev-pipeline/run-refactor.sh` are present and executable
+2. **For start**: `refactor-list.json` must exist in project root (or user-specified path)
+3. **Dependencies**: `jq`, `python3`, AI CLI (`cbc` or `claude`) must be in PATH
+4. **Python version**: Requires Python 3.8+ for dev-pipeline scripts
+
+Quick check:
+```bash
+command -v jq && command -v python3 && (command -v cbc || command -v claude) && echo "All dependencies OK"
+```
+
+If `refactor-list.json` is missing, inform user:
+> "No refactor-list.json found. Run the `refactor-planner` skill first to generate one, or provide a path to your refactor list."
+
+### Workflow
+
+Detect user intent from their message, then follow the corresponding workflow:
+
+---
+
+#### Intent A: Start Pipeline
+
+1. **Check prerequisites**:
+   ```bash
+   ls refactor-list.json 2>/dev/null && echo "Found" || echo "Missing"
+   ```
+
+2. **Check not already running**:
+   ```bash
+   dev-pipeline/launch-refactor-daemon.sh status 2>/dev/null
+   ```
+   If running, inform user and ask: "Refactor pipeline is already running. Want to restart it, check status, or view logs?"
+
+3. **Show refactor summary** (so user knows what will be refactored):
+   ```bash
+   python3 -c "
+   import json
+   with open('refactor-list.json') as f:
+       data = json.load(f)
+   refactors = data.get('refactors', [])
+   print(f'Total refactor tasks: {len(refactors)}')
+   type_counts = {}
+   for r in refactors:
+       t = r.get('type', 'unknown')
+       type_counts[t] = type_counts.get(t, 0) + 1
+   if type_counts:
+       print(f'By type: {dict(sorted(type_counts.items()))}')
+   print()
+   priority_order = {'critical': 0, 'high': 1, 'medium': 2, 'low': 3}
+   refactors_sorted = sorted(refactors, key=lambda r: (priority_order.get(r.get('priority', 'medium'), 2), r.get('id', '')))
+   for r in refactors_sorted:
+       print(f\"  {r['id']}: [{r.get('priority','medium').upper()}] [{r.get('type','?')}] {r.get('title', 'untitled')}\")
+   "
+   ```
+   If pipeline state already exists, use the status command instead:
+   ```bash
+   python3 dev-pipeline/scripts/update-refactor-status.py \
+     --refactor-list refactor-list.json \
+     --state-dir dev-pipeline/refactor-state \
+     --action status 2>/dev/null
+   ```
+
+4. **Run preflight checks** (behavior-preservation baseline):
+
+   Before refactoring, verify the codebase is in a clean, testable state:
+   ```bash
+   # Check git working tree is clean
+   git status --porcelain | head -5
+   # Run existing test suite to establish baseline
+   npm test 2>&1 | tail -20 || echo "Test command failed or not configured"
+   ```
+
+   If git working tree is dirty, warn the user:
+   > "Working tree has uncommitted changes. It's recommended to commit or stash changes before starting refactoring so each refactor task has a clean baseline. Continue anyway?"
+
+   If test baseline fails, warn the user:
+   > "Test suite is not passing. Refactoring relies on tests to verify behavior preservation. Fix failing tests before starting the refactor pipeline, or continue at your own risk."
+
+   Wait for user confirmation before proceeding.
+
+5. **Ask execution mode** (first user decision):
+
+   Present the three modes and ask the user to choose:
+   - **(1) Foreground** (recommended) — pipeline runs in the current session via `run-refactor.sh run`. Visible output and direct error feedback.
+   - **(2) Background daemon** — pipeline runs fully detached via `launch-refactor-daemon.sh`. Survives AI CLI session closure.
+   - **(3) Manual** — display the final assembled commands only. Do not execute anything. User runs them on their own.
+
+6. **Ask configuration options** ⚠️ MANDATORY INTERACTIVE STEP — applies to ALL execution modes (Foreground, Background, AND Manual). You MUST ask the user to configure options and WAIT for their response BEFORE proceeding to step 7. Do NOT skip this step or merge it with step 7.
+
+   Use `AskUserQuestion` to present the following configuration choices. Each question is a separate selectable option:
+
+   **Question 1 — Verbose logging** (multiSelect: false):
+   - On (default) — Detailed AI session logs including tool calls and subagent activity
+   - Off — Minimal logging
+
+   **Question 2 — Max retries** (multiSelect: false):
+   - 3 (default)
+   - 1
+   - 5
+
+   **Question 3 — Session timeout** (multiSelect: false):
+   - None (default) — No timeout
+   - 30 min — `SESSION_TIMEOUT=1800`
+   - 1 hour — `SESSION_TIMEOUT=3600`
+   - 2 hours — `SESSION_TIMEOUT=7200`
+
+   **Question 4 — Strict behavior check** (multiSelect: false):
+   - On (default) — Run full test suite after each refactor task to verify behavior preservation
+   - Off — Skip post-task test verification (faster but riskier)
+
+   Note: Refactor filter defaults to all refactor items (by priority order). If the user selects "Other" on any option, handle their custom input.
+
+   **Environment variable mapping** (for translating user responses → env vars):
+
+   | Config choice | Environment variable |
+   |-----------|---------------------|
+   | Verbose: On | `VERBOSE=1` |
+   | Verbose: Off | `VERBOSE=0` |
+   | Max retries: N | `MAX_RETRIES=N` |
+   | Timeout: value | `SESSION_TIMEOUT=<seconds>` |
+   | Strict behavior: On | `STRICT_BEHAVIOR_CHECK=1` |
+   | Strict behavior: Off | `STRICT_BEHAVIOR_CHECK=0` |
+
+   ⚠️ STOP HERE and wait for user response before continuing to step 7.
+
+7. **Show final command**: After user confirms configuration in step 6, assemble the complete command from execution mode + user-confirmed configuration, and present it to the user.
+
+   **Foreground command:**
+   ```bash
+   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 dev-pipeline/run-refactor.sh run refactor-list.json
+   ```
+   With all options:
+   ```bash
+   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5 SESSION_TIMEOUT=3600 \
+     dev-pipeline/run-refactor.sh run refactor-list.json
+   ```
+
+   **Background daemon command:**
+   ```bash
+   dev-pipeline/launch-refactor-daemon.sh start refactor-list.json --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1"
+   ```
+   With all options:
+   ```bash
+   dev-pipeline/launch-refactor-daemon.sh start refactor-list.json \
+     --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 MAX_RETRIES=5"
+   ```
+
+   **Manual mode**: Print the assembled command(s) and **stop here**. Do not execute anything. Do not proceed to step 8.
+   ```
+   # To run in foreground:
+   VERBOSE=1 STRICT_BEHAVIOR_CHECK=1 dev-pipeline/run-refactor.sh run refactor-list.json
+
+   # To run in background (detached):
+   dev-pipeline/launch-refactor-daemon.sh start refactor-list.json --env "VERBOSE=1 STRICT_BEHAVIOR_CHECK=1"
+
+   # To check status:
+   dev-pipeline/run-refactor.sh status refactor-list.json
+   ```
+
+8. **Confirm and launch** (Foreground and Background only — Manual mode ends at step 7):
+
+   Ask: "Ready to launch the refactor pipeline with the above command?"
+
+   After user confirms, execute the command from step 7.
+
+9. **Post-launch** (depends on execution mode):
+
+   **If foreground**: Pipeline runs to completion in the terminal. After it finishes:
+   - Summarize results: total refactors, succeeded, failed, skipped
+   - If all succeeded: each refactor session has already run `prizmkit-retrospective` internally. Ask user what's next.
+   - If some failed: show failed refactor IDs and suggest `retry-refactor.sh <R-XXX>` or `reset-refactor.sh <R-XXX> --clean --run`
+
+   **If background daemon**:
+   1. Verify launch:
+      ```bash
+      dev-pipeline/launch-refactor-daemon.sh status
+      ```
+   2. Start log monitoring — Use the Bash tool with `run_in_background: true`:
+      ```bash
+      tail -f dev-pipeline/refactor-state/pipeline-daemon.log
+      ```
+   3. Report to user:
+      - Pipeline PID
+      - Log file location
+      - "You can ask me 'refactor status' or 'show refactor logs' at any time"
+      - "Closing this session will NOT stop the pipeline"
+
+---
+
+#### Intent B: Check Status
+
+1. **Check daemon status**:
+   ```bash
+   dev-pipeline/launch-refactor-daemon.sh status
+   ```
+
+2. **Show refactor-level progress**:
+   ```bash
+   python3 dev-pipeline/scripts/update-refactor-status.py \
+     --refactor-list refactor-list.json \
+     --state-dir dev-pipeline/refactor-state \
+     --action status
+   ```
+
+3. **Show recent log activity** (last 20 lines):
+   ```bash
+   tail -20 dev-pipeline/refactor-state/pipeline-daemon.log
+   ```
+
+4. **Summarize** to user: total refactors, completed, in-progress, failed, pending.
+
+---
+
+#### Intent C: Stop Pipeline
+
+1. **Stop the daemon**:
+   ```bash
+   dev-pipeline/launch-refactor-daemon.sh stop
+   ```
+
+2. **Verify stopped**:
+   ```bash
+   dev-pipeline/launch-refactor-daemon.sh status 2>/dev/null || true
+   ```
+
+3. **Inform user**: "Refactor pipeline stopped. State is preserved -- you can resume later with 'start refactoring' and it will pick up where it left off."
+
+---
+
+#### Intent D: Show Logs
+
+1. **Check if running**:
+   ```bash
+   dev-pipeline/launch-refactor-daemon.sh status 2>/dev/null
+   ```
+
+2. **If running** -- Start live tail with Bash tool `run_in_background: true`:
+   ```bash
+   tail -f dev-pipeline/refactor-state/pipeline-daemon.log
+   ```
+
+3. **If not running** -- Show last 50 lines:
+   ```bash
+   tail -50 dev-pipeline/refactor-state/pipeline-daemon.log
+   ```
+
+4. **For per-refactor session logs** (when user asks about a specific refactor):
+   ```bash
+   # Check refactor status for last session ID
+   cat dev-pipeline/refactor-state/refactors/<REFACTOR_ID>/status.json 2>/dev/null
+   # Then tail that refactor's session log
+   tail -100 dev-pipeline/refactor-state/refactors/<REFACTOR_ID>/sessions/<SESSION_ID>/logs/session.log
+   ```
+
+---
+
+#### Intent E: Retry Single Refactor
+
+When user says "retry R-001":
+
+```bash
+dev-pipeline/retry-refactor.sh R-001 refactor-list.json
+```
+
+When user says "clean retry R-001" or "retry R-001 from scratch":
+
+```bash
+dev-pipeline/reset-refactor.sh R-001 --clean --run refactor-list.json
+```
+
+Environment variables (optional):
+```bash
+SESSION_TIMEOUT=3600 STRICT_BEHAVIOR_CHECK=1 dev-pipeline/retry-refactor.sh R-001 refactor-list.json
+```
+
+Notes:
+- `retry-refactor.sh` runs exactly one refactor session and exits.
+- `reset-refactor.sh --clean --run` clears the refactor state before retrying (fresh start).
+- Keep pipeline daemon mode for main run management (`launch-refactor-daemon.sh`).
+
+---
+
+### Error Handling
+
+| Error | Action |
+|-------|--------|
+| `refactor-list.json` not found | Tell user to run `refactor-planner` skill first |
+| Circular dependencies in refactor list | Fix dependency graph in `refactor-list.json` before launching |
+| Test baseline failing | Fix failing tests before starting refactoring -- behavior preservation requires a green baseline |
+| `jq` not installed | Suggest: `brew install jq` |
+| `cbc`/`claude` not in PATH | Check AI CLI installation |
+| Refactor pipeline already running | Show status, ask if user wants to stop and restart |
+| PID file stale (process dead) | `launch-refactor-daemon.sh` auto-cleans, retry start |
+| Launch failed (process died immediately) | Show last 20 lines of log: `tail -20 dev-pipeline/refactor-state/pipeline-daemon.log` |
+| Refactor stuck/blocked | Use `retry-refactor.sh <R-XXX>` to retry; use `reset-refactor.sh <R-XXX> --clean --run` for fresh start |
+| All refactors blocked/failed | Show status, suggest recovery: `dev-pipeline/reset-refactor.sh <R-XXX> --clean --run refactor-list.json` |
+| Permission denied on script | Run `chmod +x dev-pipeline/launch-refactor-daemon.sh dev-pipeline/run-refactor.sh` |
+
+### Integration Notes
+
+- **After refactor-planner**: This is the natural next step. When user finishes refactor planning and has `refactor-list.json`, suggest launching the refactor pipeline.
+- **Session independence**: The pipeline runs completely detached. User can close the AI CLI session, open a new session later, and use this skill to check progress or stop the pipeline.
+- **Single instance**: Only one refactor pipeline can run at a time. The PID file prevents duplicates.
+- **Pipeline coexistence**: Refactor pipeline uses `refactor-state/` separate from `state/` (features) and `bugfix-state/` (bugs), so all three pipelines can run simultaneously without conflict.
+- **State preservation**: Stopping and restarting the pipeline resumes from where it left off -- completed refactors are not re-run.
+- **HANDOFF**: After pipeline completes all refactors, each session has already run `prizmkit-retrospective` internally. Ask user what's next.