repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs: plan modernize prompt

0e9cc4d12c2f75c7c380a570c545fef85b52f58c

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (1)

docs/super/plans/2026-07-13-modernize-prompt.md

Added
new file mode 100644
1 +# Modernize Prompt Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Add a project-local `/modernize` audit that fails on stale installed Pi, derives migrations from current local and remote changelogs, scans the repository, and celebrates a clean result with ASCII art.
7 +**Architecture:** A Node standard-library script performs deterministic version, changelog, package-lock, candidate, and Git file-set collection. A project skill validates candidates semantically against latest Pi docs/source and scans code. A thin prompt invokes the skill and defines output behavior.
9 +**Tech Stack:** Pi prompt templates, Agent Skills, Node 26, `node:test`, Git, npm registry, GitHub raw changelog
11 +**Roadmap:** None
13 +**Phase:** Single-plan implementation
15 +---
17 +## Task 1: Deterministic audit collector
19 +**Files:**
21 +- Create: `.pi/skills/modernize/scripts/audit.mjs`
22 +- Create: `.pi/skills/modernize/scripts/audit.test.mjs`
24 +- [ ] **Step 1: Write failing Node tests**
26 +Cover release-section parsing, migration-section extraction, keyword extraction, ordinary-note exclusion, stale installed-version rejection, semantic version ordering, malformed changelog rejection, package-lock Pi version collection, and Git file-list parsing.
28 +- [ ] **Step 2: Run tests to verify RED**
30 +Run:
32 +```bash
33 +node --test .pi/skills/modernize/scripts/audit.test.mjs
34 +```
36 +Expected: failure because `audit.mjs` does not exist.
38 +- [ ] **Step 3: Implement the collector**
40 +Implement exports for pure parsing/version functions plus a CLI that:
42 +- runs `pi --version`;
43 +- resolves the `pi` executable and installed changelog;
44 +- fetches npm latest metadata;
45 +- fetches the release-tag-pinned canonical changelog;
46 +- rejects local/latest mismatch;
47 +- reads `package-lock.json` Pi package versions;
48 +- extracts candidates newer than the oldest repo-resolved Pi package;
49 +- lists tracked and non-ignored untracked files through Git;
50 +- emits JSON only;
51 +- writes no files.
53 +- [ ] **Step 4: Run tests to verify GREEN**
55 +Run the same `node --test` command.
56 +Expected: all collector tests pass.
58 +- [ ] **Step 5: Commit**
60 +```bash
61 +git add .pi/skills/modernize/scripts/audit.mjs .pi/skills/modernize/scripts/audit.test.mjs
62 +git commit -m "feat: collect Pi migration evidence"
63 +```
65 +## Task 2: Project skill and prompt
67 +**Files:**
69 +- Create: `.pi/skills/modernize/SKILL.md`
70 +- Create: `.pi/prompts/modernize.md`
72 +- [ ] **Step 1: Create the skill**
74 +Define a read-only workflow that runs `node .pi/skills/modernize/scripts/audit.mjs`, stops on preflight failure, verifies every candidate against latest Pi docs/source, scans every returned repository file, inspects callers, and reports evidence-backed findings only.
76 +- [ ] **Step 2: Create the prompt**
78 +Register `/modernize [focus]`, require the `modernize` skill, preserve whole-repository scope, and require funny non-boxed ASCII art under 20 lines only for `MODERNIZE CLEAN`.
80 +- [ ] **Step 3: Validate discovery and formatting**
82 +Run:
84 +```bash
85 +mise run lint
86 +mise run check
87 +pi --list-models __modernize_discovery_smoke__
88 +```
90 +Inspect startup diagnostics for prompt/skill warnings.
92 +- [ ] **Step 4: Commit**
94 +```bash
95 +git add .pi/prompts/modernize.md .pi/skills/modernize/SKILL.md
96 +git commit -m "feat: add modernize prompt"
97 +```
99 +## Task 3: Experimental verification
101 +**Files:**
103 +- No repository files expected
104 +- Temporary output under `/tmp/pi-modernize-*`
106 +- [ ] **Step 1: Run collector against real sources**
108 +```bash
109 +node .pi/skills/modernize/scripts/audit.mjs > /tmp/pi-modernize-audit.json
110 +```
112 +Assert local/latest equality, both changelog sources, candidate count, resolved package versions, and repository file count with `jq`.
114 +- [ ] **Step 2: Run real Pi prompt**
116 +From the repository root, run a fresh print-mode Pi invocation with `/modernize` and capture output outside the repository.
118 +Expected: `MODERNIZE FINDINGS` with evidence-backed `path:line` entries, or `MODERNIZE CLEAN` plus ASCII art.
120 +- [ ] **Step 3: Independently verify output**
122 +Check each reported path exists and each cited migration appears in collector evidence/current Pi docs.
123 +Confirm the audit made no repository changes beyond intended prompt/skill files.
125 +- [ ] **Step 4: Run final gates**
127 +```bash
128 +mise run check
129 +mise run lint
130 +mise run test
131 +```
133 +- [ ] **Step 5: Clean temporary artifacts**
135 +Delete only `/tmp/pi-modernize-*` files created by the experiment.
137 +- [ ] **Step 6: Commit any verification-only test correction**
139 +Commit only if experimental verification exposes and fixes a prompt, skill, script, or permanent-test defect.