pi-dev 0.1.3 → 0.1.5

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.3",
+  "version": "0.1.5",
   "description": "An autonomous engineering skill framework for the pi runtime — built on Matt Pocock's skills.",
   "type": "module",
   "bin": {

package/skills/do/SKILL.md

@@ -14,10 +14,16 @@ The point: **one request → one finished outcome**, with as few user interrupti
 1. **Migration gate (strict).** If `docs/agents/preferences.md` does not contain the `<!-- migrated: ... -->` marker, **stop** and invoke `/migrate`. Do not run any engineering work on un-migrated repos. The user makes the migration decision; the skill executes it. No partial-migration shortcuts.
 2. **Read preferences (3 layers).** Merge global (`~/.pi/agent/preferences.md`) → project (`docs/agents/preferences.md`) → package (`packages/<pkg>/preferences.md` if a single package is targeted). If global is missing, warn once and use built-in defaults from `/taste`.
 3. **Treat preferences as decisions.** Any choice the merged prefs answer is **decided**. Do not re-ask.
-4. **Keep going.** When something would normally cause a halt (ambiguous classification, scope creep beyond `change-budget`, missing follow-up), **expand and surface in the final summary** instead of stopping mid-flow. Halt only when:
+4. **Keep going. Never hand the flow back between phases.** When something would normally cause a halt (ambiguous classification, scope creep beyond `change-budget`, missing follow-up), **expand and surface in the final summary** instead of stopping mid-flow. Specifically:
+   - Do **not** ask the user "shall I proceed to the next phase?", "want me to continue?", "should I do X next?", or any equivalent. The chain is decided in Step 3 and runs to completion.
+   - Do **not** end your turn between phases. A phase's terminal predicate passing is the cue to immediately print the next phase's status line and start it, in the same turn.
+   - Confirmation-shaped questions are only legal via the **Ambiguity protocol** (one decision the prefs genuinely cannot answer) or the **Failure protocol** (terminal predicate failed twice).
+
+   Halt only when:
    - migration gate fails, OR
    - GitHub gate fails (when GitHub is the tracker), OR
    - a phase's terminal predicate fails twice and the failure cannot be characterised, OR
+   - the Ambiguity protocol fires (preferences truly silent on a one-shot decision), OR
    - user interrupts.
 5. **No handoff files.** State of work lives in three places only: **code (git), issue tracker, merged preferences**. Do not create `.scratch/flow/`, `docs/handoff/`, or any session-log file. Phase outputs are remembered in-context; persistent decisions are committed to code or filed as issues.
 6. **Side-effect gates respect prefs literally.** `auto-create-issues`, `auto-apply-labels`, `auto-commit-per-slice`, `auto-pr` follow merged prefs without reinterpretation.
@@ -99,15 +105,31 @@ If measured scope exceeds `change-budget` (e.g. `module` budget vs `cross-packag
 
 ### Step 4 — Execute the chain
 
-For each phase:
+Before running any phase, **print the planned chain once** so the user can see the runway:
+
+```
+[flow plan] intent=<x> scope=<y> chain: phase1 → phase2 → … → phaseM
+```
+
+Then for each phase:
 
-1. Print status line.
+1. Print status line `[flow N/M] <phase> — <one-sentence what>`.
 2. Run the phase. Use merged prefs to make every taste decision the phase exposes.
 3. Check the terminal predicate. If fail, retry once with explicit diagnosis. If fail again, halt with reason.
-4. Continue.
+4. **Transition without asking.** The instant the terminal predicate passes, print the *next* phase's status line on the very next line and start executing it, in the same turn. No "next, I'll do X" preamble. No "shall I continue?". No turn end.
 
 **No handoff writes.** Pass state in-context only.
 
+**Anti-patterns to detect in your own output before sending** (if you catch any of these mid-draft while phases remain, delete and replace with the next phase's status line):
+
+- "Want me to proceed with <next phase>?"
+- "Shall I continue to <next phase>?"
+- "Ready to move on to <next phase>?"
+- "Let me know if you want me to <next phase>."
+- Ending the turn after a phase summary when N < M.
+
+The only place a wrap-up belongs is **Step 7 — Final summary**, after the last phase has met its terminal predicate.
+
 ### Step 5 — Live verification
 
 Driven by **two separate prefs keys**:
@@ -139,15 +161,29 @@ If a side-effect was skipped because prefs said so, list it in the final summary
 
 ### Step 7 — Final summary
 
-One screen:
+Reached only after the **last** phase in the chain has met its terminal predicate (or the Failure protocol fired). One screen:
 
-- intent / scope / chain executed
+- intent / scope / chain executed (all N/M status lines accounted for)
 - diffs (files touched)
 - side effects done (issue URLs, commit SHAs, branch name, PR URL)
 - side effects deferred (with reason and the exact command to do them)
 - expansions (scope went beyond budget, ambiguous decisions made with rationale)
 - prefs refresh hint if stale
 
+The summary's **last line** must be one of these two terminators, so the user can tell at a glance whether the flow is done:
+
+```
+chain complete — no further action.
+```
+
+or
+
+```
+follow-up: <one-line description> — run `<exact command>`.
+```
+
+If you emitted anything that looks like a wrap-up ("All set!", "Done.", "Let me know if...") without one of those two terminators, you ended early. Reopen the chain at the missed phase.
+
 ## Phase contracts (terminal predicates)
 
 | phase                              | done when…                                                                              |