@gotgenes/pi-autoformat 0.1.0 → 4.0.3

package/.github/workflows/ci.yml

@@ -15,8 +15,6 @@ jobs:
       - uses: actions/checkout@v6
 
       - uses: pnpm/action-setup@v4
-        with:
-          version: latest
 
       - uses: actions/setup-node@v6
         with:
@@ -26,7 +24,7 @@ jobs:
       - run: pnpm install --frozen-lockfile
 
       - name: Type check
-        run: pnpm exec tsc --noEmit
+        run: pnpm run typecheck
 
       - name: Lint
         run: pnpm run lint

package/.github/workflows/release-please.yml

@@ -11,12 +11,41 @@ env:
 permissions:
   contents: write
   pull-requests: write
+  id-token: write
 
 jobs:
   release-please:
     runs-on: ubuntu-latest
     steps:
       - uses: googleapis/release-please-action@v4.4.1
+        id: release
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
           config-file: release-please-config.json
+
+      - uses: actions/checkout@v6
+        if: ${{ steps.release.outputs.release_created }}
+
+      - uses: pnpm/action-setup@v4
+        if: ${{ steps.release.outputs.release_created }}
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: "https://registry.npmjs.org"
+          cache: pnpm
+        if: ${{ steps.release.outputs.release_created }}
+
+      - run: pnpm install --frozen-lockfile
+        if: ${{ steps.release.outputs.release_created }}
+
+      - run: pnpm run lint
+        if: ${{ steps.release.outputs.release_created }}
+
+      - run: pnpm test
+        if: ${{ steps.release.outputs.release_created }}
+
+      # Trusted publishing via OIDC — no NPM_TOKEN needed.
+      # Provenance is generated automatically with trusted publishing.
+      - run: pnpm publish --no-git-checks
+        if: ${{ steps.release.outputs.release_created }}

package/.markdownlint-cli2.yaml

@@ -1,3 +1,15 @@
+# CHANGELOG.md is machine-generated by release-please. Its double blank lines
+# between sections are intentional; exclude it from linting entirely.
+ignores:
+  - "CHANGELOG.md"
+
 config:
-  default: true
-  MD013: false
+  line-length: false
+  no-duplicate-heading:
+    siblings_only: true
+  # Allow the centered logo image at the top of README.md
+  no-inline-html:
+    allowed_elements:
+      - p
+      - img
+  first-line-heading: false

package/.pi/extensions/pi-autoformat/config.json

@@ -10,14 +10,11 @@
         "biome",
         "check",
         "--write",
-        "--files-ignore-unknown=true",
-        "$FILE"
-      ],
-      "extensions": [".ts", ".json"]
+        "--files-ignore-unknown=true"
+      ]
     },
     "markdownlint-cli2": {
-      "command": ["pnpm", "exec", "markdownlint-cli2", "--fix", "$FILE"],
-      "extensions": [".md"]
+      "command": ["pnpm", "exec", "markdownlint-cli2", "--fix"]
     }
   },
   "chains": {

package/.pi/prompts/README.md

@@ -0,0 +1,59 @@
+# Project prompt templates
+
+Slash commands for this repository's issue-driven workflow. Loaded automatically by [`pi-prompt-template-model`](https://github.com/nicobailon/pi-prompt-template-model) when run from a project that contains `.pi/prompts/`.
+
+## The workflow
+
+```text
+gh issue → /plan-issue N    →   /tdd-plan [N]   →   /ship-issue N   →   /retro [N]
+            (writes plan,        (red→green→         (push, close,         (synthesize friction/
+             asks design Qs,      commit per TDD     merge release-        wins, propose small
+             commits plan)        step; lint+test;   please PR)            edits, persist to
+                                  doc commit)                              docs/retro/)
+```
+
+Each step ends at a natural review breakpoint. You can rerun any step independently.
+
+## Templates
+
+### `/plan-issue <issue-number>`
+
+Reads issue #N, gathers context (`AGENTS.md`, related plans, prerequisite issues, relevant source), surfaces 1–2 focused design questions via `ask-user` if anything is genuinely ambiguous, and writes a numbered plan to `docs/plans/NNNN-<slug>.md`. Commits the plan as `docs: plan ... (#N)`. Stops there.
+
+### `/tdd-plan [issue-number-or-path]`
+
+Loads the plan (by issue number, by path, or the most recently modified plan if no arg). For each step in the plan's "TDD Order":
+
+1. Write failing tests, confirm red.
+2. Implement, confirm green.
+3. Commit with the suggested Conventional Commits message (`feat:`, `feat!:`, etc.).
+
+Then runs the full suite + linter, updates docs (`README.md`, `docs/configuration.md`, schemas) the plan flags, and commits as `docs:`. Never edits `CHANGELOG.md` — release-please owns it.
+
+### `/ship-issue <issue-number>`
+
+Pushes, waits for CI, closes the issue with a summary built from the commit log, then merges any open release-please PR with `--rebase` and pulls the release commit. Refuses to force-push or merge a non-`CLEAN` PR.
+
+### `/retro [issue-number]`
+
+Reviews the session for friction/wins, writes `docs/retro/NNNN-<slug>.md`, surfaces per-proposal context, then uses `ask-user` to confirm small (~1–3 file) edits to `AGENTS.md` or prompts. Records what changed in a `### Changes made` subsection and commits as `docs(retro): ...`. Larger reworks are recorded as follow-ups, not landed inline.
+
+## Why three templates and not one?
+
+Each command corresponds to a different review surface:
+
+- **Plan review** — design choices, scope, TDD ordering. Easy to revise before any code is written.
+- **Code review** — the actual diff in commits, one per TDD cycle. Easy to bisect and revert.
+- **Ship review** — push, close, release. The "is this really done?" gate.
+
+Combining them would skip those gates. Splitting also lets you rerun any phase: regenerate a plan, redo TDD on the same plan, ship after a manual fixup.
+
+## Conventions assumed by these templates
+
+- `AGENTS.md` at the repo root with project priorities.
+- `docs/plans/NNNN-<slug>.md` plan layout with a "TDD Order" section.
+- Conventional Commits.
+- release-please PRs auto-opened by a GitHub Actions workflow.
+- `pnpm` test/lint scripts: `pnpm exec vitest run`, `pnpm run lint`, `pnpm run lint:fix`.
+
+These match this repo's setup (see `AGENTS.md`, `package.json`, `.github/workflows/release-please.yml`).

package/.pi/prompts/plan-issue.md

@@ -0,0 +1,64 @@
+---
+description: Read a GitHub issue, gather context, and write a numbered plan to docs/plans/
+---
+# Plan a GitHub issue
+
+Issue number: `$1`
+
+Your job is to produce a numbered implementation plan at `docs/plans/NNNN-<slug>.md` for issue #$1, then commit it. Stop after the commit. Do **not** start implementation — the next step is `/tdd-plan`.
+
+## Sync with remote (do this first)
+
+Before reading anything, make sure the working tree is up to date with the remote so the plan is written against current `main`:
+
+1. Run `git pull --ff-only`.
+2. If it fails for **any** reason — uncommitted changes, divergent history, merge conflict, network error, detached HEAD — stop immediately and report the failure to the user. Do not attempt to stash, rebase, force, or otherwise resolve.
+3. Only proceed once the pull reports a clean fast-forward (or `Already up to date.`).
+
+## Gather context (do this first, in parallel where possible)
+
+1. Run `gh issue view $1` to read the issue body and labels.
+2. Read `AGENTS.md` for project priorities, constraints, and code-style rules. Honor them in the plan.
+3. List `docs/plans/` to see numbering and style conventions (create the directory if it does not exist yet). Pick the next free `NNNN` (prefer matching the issue number when reasonable).
+4. Read every issue the body references as a prerequisite or related (`gh issue view <n>`). Note whether each is implemented yet — your plan must say what it depends on vs. defers.
+5. Open the source files most relevant to the change and skim them before writing.
+
+## Decide
+
+Before writing the plan, identify any genuinely ambiguous design choices. If there are 1–2 such choices (breaking-vs-non-breaking, result-shape change, fallback semantics, etc.), use the `ask-user` skill once to surface them with a short context summary and concrete options. Skip this step if the issue's "Proposed change" section is unambiguous.
+
+## Write the plan
+
+File: `docs/plans/NNNN-<short-slug>.md`.
+
+Start with YAML frontmatter (see `AGENTS.md` § Documentation frontmatter):
+
+```yaml
+---
+issue: $1
+issue_title: "<exact title from `gh issue view`>"
+---
+```
+
+Then the body, sections in this order:
+
+- **Problem Statement** — quote the issue's framing in your own words.
+- **Goals** — bullet list, scoped to this change.
+- **Non-Goals** — explicitly defer anything tangential (sibling issues, follow-ups).
+- **Background** — relevant existing modules/functions and how they relate.
+- **Design Overview** — dispatch model, data shapes, separation of concerns, edge cases. Include code-fenced TS types when shape changes.
+- **Module-Level Changes** — file-by-file list of what's added, changed, or removed.
+- **TDD Order** — numbered red→green→commit cycles. Each item names the test surface, what's covered, and the suggested commit message (`test:`, `feat:`, `feat!:`, `docs:`).
+- **Risks and Mitigations** — concrete risks and how the plan addresses each.
+- **Open Questions** — defer-until-needed items.
+
+If the change is breaking, say so explicitly in Goals and use `feat!:` in the suggested commit messages.
+
+## Commit
+
+```bash
+git add docs/plans/NNNN-*.md
+git commit -m "docs: plan <short summary> (#$1)"
+```
+
+Then print a 5-line summary of the plan's key decisions and stop.

package/.pi/prompts/retro.md

@@ -0,0 +1,144 @@
+---
+description: Review this session for workflow improvements and persist retro notes to docs/retro/
+deterministic:
+  run: |
+    echo "=== Recent commits ==="
+    git log --oneline -25
+    echo
+    echo "=== Existing retros ==="
+    ls docs/retro/ 2>/dev/null || echo "(docs/retro/ does not exist yet)"
+    echo
+    echo "=== Plans referenced this session ==="
+    ls -t docs/plans/ 2>/dev/null | head -5
+  handoff: always
+---
+
+# Review session and persist retro notes
+
+The user wants a retrospective on this session. Issue number (if provided): `$1`
+
+You **must** load the `ask-user` skill before proposing any changes.
+
+## Step 1 — Identify the retro file
+
+1. If `$1` is set, treat it as the issue number `N`.
+2. Otherwise, infer `N` from the most recent commit subject in the deterministic output above (look for `(#N)` at the end of `feat:`, `fix:`, or `docs:` commits). If multiple issues appear, list them and ask the user which to retro on with `ask-user`.
+3. Resolve a slug from `docs/plans/NNNN-<slug>.md` if a matching plan exists; otherwise derive a short slug from the issue title via `gh issue view N --json title -q .title`.
+4. The retro file is `docs/retro/NNNN-<slug>.md`. Create the directory if missing.
+
+## Step 2 — Synthesize observations
+
+Review what happened across this session — the user prompts, your tool calls, corrections, rework, and commits. Be specific: cite file paths, commit subjects, and concrete tool sequences. Categorize each friction point with one label:
+
+- `premature-convergence` — picked the first viable approach without exploring alternatives
+- `missing-context` — didn't check existing code, docs, conventions, or upstream specs
+- `wrong-abstraction` — operated at the wrong level (mechanical when strategy was needed, or vice versa)
+- `scope-drift` — went beyond what was asked or missed the actual ask
+- `rabbit-hole` — chased symptoms instead of questioning assumptions
+- `instruction-violation` — had clear instructions in `AGENTS.md` or the prompt but didn't follow them
+- `other` — describe
+
+For each friction point describe the **concrete impact**: time wasted, rework caused, follow-up commits needed, or "added friction but no rework."
+
+Note whether each `instruction-violation` was **self-identified** (you caught it mid-session) or **user-caught** (the user pointed it out).
+Self-identified failures usually indicate a salience tweak; user-caught failures may indicate the rule needs to be more prominent.
+
+### Bidirectional feedback
+
+Look for moments where the user could have shared context earlier, intervened with a redirecting question instead of a correction, or where their involvement was mechanical oversight rather than strategic judgment. Frame as opportunity, not criticism.
+
+### Novel wins only
+
+Record wins only if they are novel or surprising — a new pattern working for the first time, a tool proving its value, a notably clean execution. Skip routine successes.
+
+## Step 3 — Write the retro file
+
+Append (or create) `docs/retro/NNNN-<slug>.md` with this structure.
+When creating a new file, include YAML frontmatter (see `AGENTS.md` § Documentation frontmatter):
+
+```markdown
+---
+issue: N
+issue_title: "<exact title from `gh issue view N`>"
+---
+
+# Retro: #N — <issue title>
+
+## Final Retrospective (<ISO timestamp>)
+
+### Session summary
+
+2–3 sentences on what was accomplished.
+
+### Observations
+
+#### What went well
+
+- ...
+
+#### What caused friction (agent side)
+
+- `<label>` — <description>. Impact: <concrete impact>.
+
+#### What caused friction (user side)
+
+- ...
+```
+
+Wrap all code identifiers, filenames, route paths, CLI names, and any text containing underscores in backticks. Use sequential numbering in ordered lists.
+
+## Step 4 — Present highlights and proposals (before asking)
+
+Surface the synthesis as regular message text **before** invoking `ask-user`. The message must include:
+
+1. **Cross-session highlights** — 2–4 short paragraphs synthesizing dominant friction patterns and any wins worth promoting. Not a copy of the retro file — the bridge between observations and proposals.
+2. **Per-proposal context** — for each proposed change: the concrete pain (with tool-call counts or specific examples), why the proposed location is the right home, and the proposed content as a fenced block.
+3. **What you considered but did not propose** — name candidate changes you rejected and why.
+
+Candidate change locations for this repo:
+
+- `AGENTS.md` — project-wide priorities, code style, conventions.
+- `.pi/prompts/*.md` — slash-command prompt bodies.
+- `docs/configuration.md`, `README.md`, `schemas/pi-autoformat.schema.json` — keep aligned per `AGENTS.md`.
+- New skill or new prompt — only if the rule is reusable across many sessions.
+
+## Step 5 — Ask before editing
+
+Use the `ask-user` skill once to confirm which proposals to implement. The question itself stays a single sentence; the context belongs in the message above.
+
+## Step 6 — Implement approved changes (with scope discipline)
+
+The retro session is scoped to **observations and small consensus-driven adjustments**, not substantive rework. A retro commit (`docs(retro): ...`) should land the retro file plus small (~1–3 file) prompt or `AGENTS.md` adjustments the user explicitly confirmed.
+
+If a proposed change is larger — touches more than ~3 files, restructures content significantly, or rewrites a prompt's scope — record it in the retro file as a follow-up but **do not** implement it inline. Suggest the user open a GitHub issue and run `/plan-issue` on it.
+
+## Step 7 — Verbosity check before landing changes
+
+Retro-driven additions to `AGENTS.md` and prompt bodies should land as **rule + tight example**, not **rule + rationale + worked example**. The retro file is the right home for rationale and worked examples.
+
+Before landing any change, ask:
+
+1. **Rationale placement** — is the _why_ in the retro file, or has it leaked into `AGENTS.md`/prompt? If the latter, move it back and leave a one-clause justification (or a `Refs #N` pointer).
+2. **Example tightness** — can the example fit in one or two lines?
+3. **Hedging audit** — phrases like "should generally," "typically," "usually" often signal the rule isn't crisp enough. Name the exceptions or drop the hedge.
+4. **Sentence length** — sentences over ~30 words usually carry rationale that should be split out.
+
+## Step 8 — Record changes made
+
+After implementing, edit the retro file directly to append a `### Changes made` subsection under the Final Retrospective stage entry — a numbered list of changes with file paths. Do not split this into multiple sections; one coherent list per retro.
+
+## Step 9 — Commit and push
+
+1. `git add docs/retro/ AGENTS.md .pi/prompts/` (and any other touched files).
+2. Commit as `docs(retro): add retro notes for issue #N`.
+3. `git push`.
+
+If the user suggests further refinements after the commit, implement them, append to the same `### Changes made` section, and commit again. Every change made during the retro must be recorded before the session ends.
+
+## Rules
+
+- Be conservative — only propose changes clearly justified by evidence in this session.
+- Be specific — provide exact proposed text, not vague suggestions.
+- Look for removals alongside additions.
+- Don't duplicate — check whether a rule already exists in `AGENTS.md` or a prompt before adding.
+- Do not edit `CHANGELOG.md` — release-please owns it.

package/.pi/prompts/ship-issue.md

@@ -0,0 +1,77 @@
+---
+description: Push, close a GitHub issue with a summary, and merge the release-please PR
+---
+# Ship the implementation
+
+Argument: `$1` is the issue number that was just implemented.
+
+## 1. Sync with remote
+
+Before pushing, make sure local `HEAD` is current with the remote:
+
+1. Run `git pull --ff-only`.
+2. If it fails for **any** reason — uncommitted changes, divergent history, merge conflict, network error, detached HEAD — stop immediately and report the failure to the user. Do not attempt to stash, rebase, force, or otherwise resolve.
+3. Only proceed once the pull reports a clean fast-forward (or `Already up to date.`).
+
+## 2. Push
+
+- Determine the current branch (`git branch --show-current`).
+- `git push origin HEAD` (or `<branch>:<branch>`).
+- If the push is rejected as non-fast-forward, stop and report — do not force-push.
+
+## 3. Verify CI on the pushed commit
+
+- Run `gh run list --branch <branch> --limit 3` and find the run for the latest commit (`git rev-parse HEAD`).
+- If the latest run is `in_progress` or `queued`, wait (`sleep 15`) and re-check up to ~3 times.
+- If it lands `failure`, stop and report. Do not close the issue or merge anything.
+- If it lands `success`, continue.
+
+## 4. Close the issue
+
+Build the close comment from the commits since the previous release:
+
+```bash
+git log --oneline <previous-tag-or-base>..HEAD
+```
+
+The comment should include:
+
+- The commit hash that lands the change ("Implemented in `<sha>` …").
+- A short bullet list of feature/breaking commits.
+- One sentence on user-visible behavior change.
+- A note flagging any breaking change (matches `feat!:` commits).
+- If the change unblocks or partially addresses other issues, mention them.
+
+Then:
+
+```bash
+gh issue close $1 --comment "<the summary above>"
+```
+
+## 5. Merge release-please PR (if present)
+
+- `gh pr list --search "release-please" --state open` — find an open release PR for `main`.
+- If none exists, skip to step 6.
+- If one exists:
+  - `gh pr view <num> --json mergeable,mergeStateStatus,title` — confirm `MERGEABLE` and `CLEAN`.
+  - Note: release-please PRs typically have **no CI runs** because PRs created by the default `GITHUB_TOKEN` do not trigger workflows. This is expected; do not block on it.
+  - `gh pr merge <num> --rebase`.
+  - `git pull --ff-only` to pick up the release commit and any tag. If this pull fails, stop and report — same rules as step 1.
+
+If the release-please PR is in any state other than `CLEAN`/`MERGEABLE`, stop and report — let the user decide.
+
+## 6. Final report
+
+Print:
+
+- The new HEAD on `main` (`git log --oneline -1`).
+- The released version, if a release commit just landed (`git tag --points-at HEAD` or read `package.json`).
+- Issue close confirmation.
+- Anything that was skipped and why.
+
+## Constraints
+
+- Never force-push.
+- Never merge a release-please PR that is not `MERGEABLE`/`CLEAN`.
+- If CI fails, the issue stays open.
+- If multiple release-please PRs exist for the same component, stop and ask — that's a configuration issue, not a normal merge.

package/.pi/prompts/tdd-plan.md

@@ -0,0 +1,67 @@
+---
+description: Execute the TDD steps from a docs/plans/ plan as red→green→commit cycles
+---
+# Execute a plan with TDD
+
+Argument: `$1` is either a plan path, an issue number, or empty (use the most recently modified plan).
+
+## Sync with remote (do this first)
+
+Before locating or reading the plan, make sure the working tree is up to date with the remote:
+
+1. Run `git pull --ff-only`.
+2. If it fails for **any** reason — uncommitted changes, divergent history, merge conflict, network error, detached HEAD — stop immediately and report the failure to the user. Do not attempt to stash, rebase, force, or otherwise resolve.
+3. Only proceed once the pull reports a clean fast-forward (or `Already up to date.`).
+
+## Locate the plan
+
+- If `$1` looks like a path, use it.
+- If `$1` is a number, find `docs/plans/NNNN-*.md` matching that integer (issue number or plan number).
+- Otherwise, use the newest file in `docs/plans/` (by mtime).
+
+Read the plan in full before doing anything else. If "TDD Order" is missing or empty, stop and report — re-run `/plan-issue` first.
+
+## Read project rules
+
+Read `AGENTS.md`. The relevant rules for this template:
+
+- TypeScript only; avoid `any`.
+- Conventional Commits; commit at meaningful checkpoints.
+- Don't remove functionality without explicit user discussion.
+- Keep `schemas/`, `docs/configuration.md`, `README.md`, and the config loader aligned when any one of them changes.
+
+## Execute the TDD cycle
+
+For **each** step in the plan's "TDD Order", in order:
+
+1. **Red.** Write the failing tests the step describes. Run only the affected test file:
+   `pnpm exec vitest run <test-path>` and confirm failures.
+2. **Green.** Implement the minimum code to make those tests pass. Re-run the same file and confirm green.
+3. **Commit.** Use the commit message the plan suggests, or a Conventional Commits message that matches:
+   - `test:` for test-only commits (rare; usually folded into the feat).
+   - `feat:` for new behavior.
+   - `feat!:` for breaking changes the plan calls out (include a `BREAKING CHANGE:` footer).
+   - `fix:` for bug fixes.
+
+One logical change per commit. Do not bundle multiple TDD steps into one commit.
+
+If a step uncovers a problem the plan didn't anticipate (e.g. a downstream test breaks), fix it as part of the same commit and note the deviation in the commit body. If the deviation is large, stop and ask.
+
+## After the last TDD step
+
+1. Run the full suite: `pnpm exec vitest run`. Must be all green.
+2. Run the type check: `pnpm run typecheck` (`tsc --noEmit`). Must succeed — Vitest does not typecheck.
+3. Run the linter: `pnpm run lint`. If it fails, run `pnpm run lint:fix` and re-check. Commit any fixup as part of the most recent feat commit (amend) only if you haven't pushed; otherwise as a `style:` commit. The fixup must NOT land in a `docs:` commit.
+4. Update docs the plan flags: `README.md`, `docs/configuration.md`, schemas, etc. Commit as `docs: <summary>`.
+5. **Do not edit `CHANGELOG.md`** — release-please owns it and will generate entries from your Conventional Commit messages on the next release.
+
+## Summarize
+
+Print:
+
+- `git log --oneline <N>` for the commits you just made (N = number of TDD steps + docs).
+- One-line summary of behavioral change.
+- Any test-count delta.
+- Any deviations from the plan.
+
+Stop. The next step is `/ship-issue`.