pi-dev 0.1.2 → 0.1.4

package/README.md

@@ -1,30 +1,51 @@
 # pi-dev
 
-> An autonomous engineering skill framework for the [pi](https://github.com/badlogic/pi) runtime.
+> **Three slash commands. One finished outcome. Zero ceremony.**
 >
-> Built on the shoulders of [Matt Pocock's skills](https://github.com/mattpocock/skills) — the structure, vocabulary, and underlying engineering discipline are his. This package layers a **single entry point**, a **strict migration gate**, and **per-project preferences** on top so the skills can run end-to-end inside the pi runtime without ceremony.
+> An autonomous engineering skill framework for the [pi](https://github.com/badlogic/pi) runtime — built on [Matt Pocock's skills](https://github.com/mattpocock/skills), wrapped in a single entry point, a strict migration gate, and three-layer preferences so the agent runs end-to-end without interrupting you.
 
-## What this gives you
+```bash
+npx pi-dev@latest install
+```
+
+That is the whole setup. From here on you talk to the agent, not to a tool palette.
+
+---
+
+## The pitch
+
+Most AI engineering setups give you a drawer full of commands and ask you to remember which one to use, when, and in what order. After a week you stop opening the drawer.
 
-After one install and one onboarding, your interaction with the agent collapses to **three commands**:
+`pi-dev` collapses the drawer into **three commands** and lets the agent decide the rest:
 
 ```
-/do       — do the engineering work end-to-end
-/taste    — view or update your engineering preferences
-/where    — recall prior pi sessions for this cwd
+/do      — do the engineering work end-to-end
+/taste   — view or update your engineering preferences
+/where   — recall prior pi sessions for this cwd
 ```
 
-That is the whole interface. Everything else (`/diagnose`, `/tdd`, `/to-prd`, `/to-issues`, `/triage`, `/grill-with-docs`, `/improve-codebase-architecture`, `/zoom-out`, `/recon-with-vision`, `/migrate`, `/setup`) is invoked automatically by `/do` based on intent and scope.
+Behind `/do` sit eleven specialist skills — `diagnose`, `tdd`, `to-prd`, `to-issues`, `triage`, `grill-with-docs`, `improve-codebase-architecture`, `zoom-out`, `recon-with-vision`, `migrate`, `setup` — chained automatically based on intent (`feature` / `bug` / `perf` / `refactor` / `recon` / `docs` / `triage`) and scope (`nano` / `small` / `medium` / `large`).
+
+You ask. It classifies. It executes. It reports.
+
+## What you actually get
+
+- **One request → one finished outcome.** `/do` runs the right chain to completion: write the PRD, file the slice issues with proper labels, drive TDD per slice, boot the app locally to verify, commit, open the PR.
+- **Preferences as decisions, not prompts.** Anything answered in your global / project / package `preferences.md` is settled. The agent never re-asks. Set `auto-pr=true` once and pushes happen; set `interrupt-on-ambiguity=low` and the agent picks a sensible default and reports it instead of stopping.
+- **A migration gate that won't let you cheat.** `/do` refuses to touch an un-migrated repo. `/migrate` audits `AGENTS.md`, `CLAUDE.md`, scoped agent dirs, handoff systems, and ADR layouts; archives the noise; stamps a marker; and on every re-entry runs drift probes so banned conventions can't sneak back in.
+- **No handoff files. Ever.** State of work lives in three places only — code (git), the issue tracker, and merged preferences. No `docs/handoff/`, no `.scratch/flow/`, no SESSION_*.md littering your repo.
+- **Local-live verification the agent owns.** A one-time playbook captures how to boot your stack. From then on the agent boots it, drives it, and quotes the evidence in the summary. You are not the test runner.
+- **Vertical-slice issues with AI disclaimers baked in.** `/to-issues` produces independently-grabbable tickets — each with acceptance criteria, allowed-touch-set, and out-of-scope — and the disclaimer required by `/triage` lands on every one.
 
 ## Install
 
-Requires Node ≥ 20 and the pi runtime.
+Requires Node ≥ 20 and the [pi runtime](https://github.com/badlogic/pi).
 
 ```bash
 # Install the skills + seed your global preferences
 npx pi-dev@latest install
 
-# Later: refresh skills only (keeps your preferences)
+# Refresh skills only (keeps your preferences as-is)
 npx pi-dev@latest update
 
 # See what's installed
@@ -34,47 +55,65 @@ npx pi-dev list
 npx pi-dev doctor
 ```
 
-What `install` does:
-
-- Copies the skill folders to `~/.pi/agent/skills/` (the directory the pi runtime reads).
-- Seeds `~/.pi/agent/preferences.md` with sensible global defaults — only if you do not already have one.
+`install` copies the skill folders to `~/.pi/agent/skills/` (where the pi runtime looks) and seeds `~/.pi/agent/preferences.md` only if you don't already have one.
+`update` refreshes skill folders but leaves your preferences alone unless you pass `--include-prefs`.
 
-What `update` does:
-
-- Refreshes the skill folders.
-- **Does not** overwrite your global preferences. Pass `--include-prefs` if you want to re-seed.
-
-## How it works
+## How `/do` actually flows
 
 ```
-[ /do ]  ──►  bootstrap
-              ├─ migration gate (refuses to run on un-migrated repos)
-              ├─ load merged preferences (global → project → package)
-              ├─ classify intent + scope from the user's message
-              └─ execute the right chain of skills, end-to-end
+[ /do <your request> ]
+        │
+        ▼
+   bootstrap
+        ├─ load merged preferences (global → project → package)
+        ├─ check migration marker  ──► if missing, hand off to /migrate
+        ├─ taboo lint (handoff drift, banned labels)
+        ▼
+   classify intent + scope
+        ▼
+   execute the matching chain
+        ├─ feature × small    →  (zoom-out?) → tdd → (improve-codebase-architecture?)
+        ├─ feature × large    →  zoom-out → grill-with-docs → to-prd → to-issues → triage → tdd per slice → improve-codebase-architecture
+        ├─ bug × any          →  diagnose → tdd (regression) → improve-codebase-architecture
+        ├─ recon × any        →  recon-with-vision → (to-prd / to-issues)
+        └─ … (full table in skills/do/SKILL.md)
+        ▼
+   live-verify locally (agent boots and drives the stack)
+        ▼
+   side effects per prefs (commit, push, open PR, file issues, label)
+        ▼
+   one-screen final summary
 ```
 
-The first time you run `/do` in a new repo, the gate will trigger:
+The first time you run `/do` in a new repo, the migration gate fires:
 
-1. **`/migrate`** — audits `AGENTS.md` / `CLAUDE.md` / handoff systems / context-and-ADR layouts, normalises them, and stamps a migration marker.
-2. **`/setup`** — scaffolds `docs/agents/{issue-tracker,triage-labels,domain}.md` if needed.
-3. **`/taste`** (onboarding mode) — auto-detects project signals, asks at most a handful of questions where the project diverges from your global preferences, writes `docs/agents/preferences.md`.
+1. **`/migrate`** normalises `AGENTS.md`, archives handoff systems, locks them out via `.gitignore`, stamps the marker.
+2. **`/setup`** scaffolds `docs/agents/{issue-tracker,triage-labels,domain}.md`.
+3. **`/taste`** auto-detects project signals, asks only where the project diverges from your global preferences, writes `docs/agents/preferences.md`.
 
-After that one-time onboarding, `/do` runs without interruption. Side effects (issue creation, label application, commits, PRs) follow your `auto-*` preferences literally.
+After that, `/do` runs uninterrupted.
 
-## Preferences in three layers
+## Preferences: three layers, last write wins
 
 ```
-~/.pi/agent/preferences.md            # global — your engineering taste
-docs/agents/preferences.md            # project — overrides for this repo
-packages/<pkg>/preferences.md         # package — overrides for this subtree (optional)
+~/.pi/agent/preferences.md            # global   — your engineering taste
+docs/agents/preferences.md            # project  — overrides for this repo
+packages/<pkg>/preferences.md         # package  — overrides for this subtree (optional)
 ```
 
-Skills merge them in order; last write wins per key. You can edit any of these files directly. `/taste` is just a guided way to do the same thing.
+Skills merge in that order. Edit any layer directly, or use `/taste` for a guided pass. The keys that move the needle most:
+
+| key | what it controls |
+| --- | --- |
+| `interrupt-on-ambiguity` | how willing the agent is to ask vs. pick a default and report it |
+| `change-budget` | how big a chunk a single `/do` run is allowed to swallow |
+| `auto-create-issues` / `auto-apply-labels` | whether tracker side-effects happen automatically |
+| `auto-commit-per-slice` / `auto-pr` | how aggressively work lands on `main` |
+| `local-live-policy` / `ops-live-policy` | when the agent boots locally vs. probes prod |
 
 ## What's a skill?
 
-Each skill is a directory with a `SKILL.md`. The pi runtime reads the directory name and the skill's frontmatter to expose it as `/<name>`. The contents are pure Markdown — instructions for the agent, not code. That is the whole framework.
+A directory with a `SKILL.md`. That's the whole format. The pi runtime reads the directory name and the markdown frontmatter and exposes the skill as `/<name>`. No code, no plugin API — just instructions for the agent, version-controlled like any other prose.
 
 ## Credits
 
@@ -82,12 +121,12 @@ The engineering discipline encoded here — `tdd`, `diagnose`, `to-prd`, `to-iss
 
 This package adds:
 
-- `do` — a one-shot orchestrator that picks the right chain
-- `migrate` — a strict gate that normalises any repo into the canonical shape
-- `taste` — three-layer preferences with project-aware onboarding
-- `where` — pi-session recall for multi-session work
+- **`do`** — a one-shot orchestrator that picks the right chain
+- **`migrate`** — a strict gate that normalises any repo into the canonical shape and probes for drift on every re-entry
+- **`taste`** — three-layer preferences with project-aware onboarding
+- **`where`** — pi-session recall for multi-session work
 
-If you find these skills useful, support the upstream:
+If these skills earn their keep for you, please support the upstream:
 
 - Matt Pocock — https://www.mattpocock.com
 - pi runtime — https://github.com/badlogic/pi
@@ -96,21 +135,15 @@ If you find these skills useful, support the upstream:
 
 Versioning, changelog, tagging, and npm publishing are fully automated:
 
-1. Land changes on `main` using **Conventional Commits** (`feat:`, `fix:`,
-   `perf:`, `refactor:`, `docs:`, `chore:`, etc.).
-2. [release-please](https://github.com/googleapis/release-please) opens or
-   updates a **Release PR** that bumps the version and writes `CHANGELOG.md`.
-3. Merge the Release PR. release-please tags the commit and creates a GitHub
-   Release.
-4. The `Release` workflow rebuilds, retests, and runs `npm publish --access
-   public` automatically.
+1. Land changes on `main` using **Conventional Commits** (`feat:`, `fix:`, `perf:`, `refactor:`, `docs:`, `chore:`).
+2. [release-please](https://github.com/googleapis/release-please) opens or updates a **Release PR** that bumps the version and writes `CHANGELOG.md`.
+3. Merge the Release PR. release-please tags the commit and creates a GitHub Release.
+4. The `Release` workflow rebuilds, retests, and runs `npm publish --access public` automatically.
 
 Required one-time setup (maintainer):
 
-- Add an `NPM_TOKEN` repository secret with a granular publish token from
-  npmjs.com (Read and write, 2FA bypass enabled).
-- If you flip the repo to public later, add `--provenance` to the publish
-  command in `.github/workflows/release.yml` for sigstore attestation.
+- Add an `NPM_TOKEN` repository secret with a granular publish token from npmjs.com (read + write, 2FA bypass enabled).
+- If the repo becomes public, add `--provenance` to the publish command in `.github/workflows/release.yml` for sigstore attestation.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-dev",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "An autonomous engineering skill framework for the pi runtime — built on Matt Pocock's skills.",
   "type": "module",
   "bin": {

package/skills/do/SKILL.md

@@ -40,6 +40,15 @@ The point: **one request → one finished outcome**, with as few user interrupti
 - Read docs/agents/{issue-tracker,triage-labels,domain}.md.
 - If GitHub is the tracker, run a 2-second readiness check (gh auth status, repo accessible). On fail, halt with fix commands.
 - If any preferences file's last-updated > 90 days, append a one-line refresh hint to the final summary.
+- **Taboo lint (1-shot, non-blocking).** After prefs are merged, run a quick drift probe and surface findings in the final summary (do not halt the flow):
+  ```bash
+  # handoff paths that the migration forbade
+  find docs/handoff .scratch/flow .handoff -type f 2>/dev/null | head
+  # post-migration commits that look like handoff writes
+  marker_date=$(grep -oE 'migrated: [0-9-]+' docs/agents/preferences.md 2>/dev/null | awk '{print $2}')
+  [ -n "$marker_date" ] && git log --since="$marker_date" --oneline --grep='handoff\|SESSION_' | head
+  ```
+  Any hit → add a "taboo drift" line to the final summary recommending `/migrate` re-run. Findings are advisory at this stage; `/migrate` owns the cleanup.
 - If the user's request hints at continuation ("이어서", "지난번", "where were we", "다시 시작"), invoke `/where` (optional). Otherwise skip it — the migration-enforced state-of-work channels (code / issues / prefs) are usually enough.
 ```
 

package/skills/migrate/SKILL.md

@@ -180,7 +180,14 @@ Wait for user OK. Show exact text being preserved or translated if user asks.
 
 In order:
 
-1. **Backup**: `mv` everything in ARCHIVE to `.archive/<date>-pre-migration/`. Add `.archive/` to `.gitignore` if not present.
+1. **Backup + handoff lockout**: `mv` everything in ARCHIVE to `.archive/$(date -u +%Y-%m-%d)-pre-migration/`. Add `.archive/` to `.gitignore` if not present. **Also append handoff-path lockouts** to `.gitignore` so they cannot silently come back:
+   ```
+   # post-migration: handoff systems are forbidden (see docs/agents/preferences.md taboos)
+   docs/handoff/
+   .scratch/flow/
+   .handoff/
+   ```
+   If the repo already gitignores these for a different reason, leave them — the rule still holds.
 2. **Setup docs**: invoke `/setup` if any of `docs/agents/{issue-tracker,triage-labels,domain}.md` missing.
 3. **Rewrite AGENTS.md** with the canonical skeleton:
    ```markdown
@@ -208,10 +215,12 @@ In order:
    ```
 4. **Sub-AGENTS.md**: if scoped `<subdir>/AGENTS.md` exists, leave it but strip duplicated process docs; preserve only hard rules specific to that subtree.
 5. **Onboard preferences**: invoke `/taste` in onboarding mode.
-6. **Mark migrated**: append to `docs/agents/preferences.md`:
-   ```
-   <!-- migrated: <ISO-date> by `/migrate` -->
+6. **Mark migrated**: append to `docs/agents/preferences.md` using the real current ISO date (shell-resolved, never hand-typed):
+   ```bash
+   printf '\n<!-- migrated: %s by `/migrate` -->\n' "$(date -u +%Y-%m-%d)" \
+     >> docs/agents/preferences.md
    ```
+   The marker literal must read `<!-- migrated: YYYY-MM-DD by \`/migrate\` -->`. Do not paste a future or rounded date — `/do`'s 90-day staleness check relies on this being accurate.
 7. **Print summary**: counts of preserved / translated / archived / written, plus any FYI items needing manual review.
 
 ### 6. Idempotency
@@ -220,6 +229,23 @@ This skill is safe to re-run. On second run:
 - If marker present and no drift detected → print "already migrated, no changes" and exit.
 - If drift detected (new handoff files appeared, AGENTS.md got a generic process section bolted on, etc.) → present a diff for those drifts only.
 
+**Drift probes** (run all on re-entry, regardless of marker):
+
+```bash
+# 1. handoff paths resurrected since migration
+find docs/handoff .scratch/flow .handoff -type f 2>/dev/null | head
+
+# 2. handoff-style commits after the migration marker
+marker_date=$(grep -oE 'migrated: [0-9-]+' docs/agents/preferences.md | awk '{print $2}')
+[ -n "$marker_date" ] && git log --since="$marker_date" --oneline --grep='handoff\|SESSION_' || true
+
+# 3. taboo labels still alive on the tracker (GitHub example)
+gh label list --json name --jq '.[].name' 2>/dev/null \
+  | grep -E '^(retro-action-item|process-audit|handoff)$' || true
+```
+
+Any non-empty output → surface as drift in the plan and offer to clean up (delete files, rename commits is N/A, archive labels via `gh label delete` after confirming zero usage). Do not silently ignore.
+
 ## When migration cannot proceed
 
 - User refuses to delete a competing rule file (CLAUDE.md vs AGENTS.md both alive) → migration stops, `/do` stays blocked. The decision must be made.

package/skills/to-issues/SKILL.md

@@ -55,7 +55,11 @@ For each approved slice, publish a new issue to the issue tracker. Use the issue
 
 Publish issues in dependency order (blockers first) so you can reference real issue identifiers in the "Blocked by" field.
 
+**Every issue body MUST start with the AI disclaimer** (same wording as `/triage`). This is a hard requirement — no exceptions, including auto-generated slices. After writing the body, grep your own draft for the disclaimer string; if missing, do not publish.
+
 <issue-template>
+> *This was generated by AI during triage.*
+
 ## Parent
 
 A reference to the parent issue on the issue tracker (if the source was an existing issue, otherwise omit this section).
@@ -78,4 +82,28 @@ Or "None - can start immediately" if no blockers.
 
 </issue-template>
 
+**Publishing pattern (GitHub).** Use `--body-file -` with a heredoc, never inline `--body "..."`, so the disclaimer and markdown structure survive shell quoting verbatim:
+
+```bash
+gh issue create \
+  --title "[Slice N] <title>" \
+  --label needs-triage \
+  --body-file - <<'EOF'
+> *This was generated by AI during triage.*
+
+## Parent
+#<parent>
+
+## What to build
+...
+EOF
+```
+
+After creation, immediately verify the disclaimer landed:
+
+```bash
+gh issue view <n> --json body --jq '.body' | head -1 | grep -q 'generated by AI' \
+  || echo "FAIL: disclaimer missing on #<n>"
+```
+
 Do NOT close or modify any parent issue.