pi-baton 0.2.2

package/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning.
+
+## [0.2.2] - 2026-06-13
+
+### Added
+
+- Live Baton run widget above the editor during `/baton:run`, showing workflow, brief, active step, agent, judgment, and step checklist.
+- Footer status line (`baton: implement`, `baton: review`, etc.) while a run is in progress.
+
+## [0.2.1] - 2026-06-13
+
+### Fixed
+
+- Ship builtin `worker` and `reviewer` subagent definitions so `default-review-loop` runs without pre-created `.pi/agents/` files.
+- Validate required workflow agents during `/baton:start` and `/baton:run` with clearer missing-agent errors.
+
+## [0.2.0] - 2026-06-13
+
+### Added
+
+- `/baton:new`, `/baton:start`, `/baton:run`, and `/baton:status` command surface.
+- Builtin `default-review-loop` workflow with `worker` / `reviewer` / `worker` agent mapping.
+- YAML workflow discovery, inline validation, scaffold generation, and run persistence under `.pi/baton/`.
+- Isolated subagent step execution with structured handoff, review contract enforcement, and per-step model routing.
+
+## [0.1.2] - 2026-06-04
+
+### Changed
+
+- README and `docs/template-checklist.md` now follow the Pi OSS minimal-docs policy: `docs/` is optional, with explicit post-generation cleanup for template bootstrap docs.
+- Template bootstrap docs (`github-template.md`, `repository-settings.md`, `typescript.md`) are labeled for delete-or-merge after setup.
+
+## [0.1.1] - 2026-06-01
+
+### Changed
+
+- Publish workflow now supports npm publishing on merged package version bumps in addition to tags, releases, and manual dispatch.
+- Publish workflow now installs a current npm CLI so npm Trusted Publishing OIDC is supported.
+- CI and publish workflow commands no longer include literal trailing `\\n` text.
+
+## [0.1.0] - YYYY-MM-DD
+
+### Added
+
+- Initial Pi package template.
+- Example extension, Agent Skill, prompt, and theme.
+- CI and npm Trusted Publishing workflow.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YOUR_NAME
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# Pi Baton
+
+[![CI](https://github.com/eiei114/pi-baton/actions/workflows/ci.yml/badge.svg)](https://github.com/eiei114/pi-baton/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/pi-baton.svg)](https://www.npmjs.com/package/pi-baton)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Pi package](https://img.shields.io/badge/pi-package-purple.svg)](https://pi.dev/packages)
+
+> Run YAML-defined review loops in Pi with per-step model switching and isolated step context.
+
+## What this is
+
+Pi Baton is a Pi-native workflow baton runner. Define `implement → review → fix` loops in YAML, and let Pi Baton execute them with automatic baton handoff between isolated subagent steps.
+
+- **Per-step model switching** — fast model for implement, strong model for review
+- **Isolated step context** — no shared conversation pollution between steps
+- **Structured review contract** — `accept`/`reject` with mandatory findings or acceptance notes
+- **Live progress widget** — see which step is running, its agent, and judgment in real time
+
+## Install
+
+```bash
+pi install npm:pi-baton
+```
+
+Project-local:
+
+```bash
+pi install npm:pi-baton -l
+```
+
+GitHub:
+
+```bash
+pi install git:github.com/eiei114/pi-baton
+```
+
+## Quick start
+
+```txt
+/baton:new        create a workflow scaffold
+/baton:start      choose workflow + task brief → idle run
+/baton:run        execute run to terminal state (with live widget)
+/baton:status     show the active run summary
+```
+
+The builtin `Default Review Loop` workflow (implement → review → fix) works out of the box — no agent setup required.
+
+## Prerequisites
+
+Pi Baton ships builtin `worker` and `reviewer` subagents under `agents/`. They work with your current Pi model.
+
+To override with custom agents, place `.md` files under:
+
+```
+.pi/agents/worker.md
+.pi/agents/reviewer.md
+```
+
+Discovery order: project `.pi/agents/` → user `~/.pi/agent/agents/` → pi-baton builtin.
+
+## Workflow authoring
+
+```txt
+/baton:new
+```
+
+Pick a name and a scaffold from `default-review-loop` is written to `.pi/baton/workflows/` and opened in editor. The scaffold includes `<your-fast-model>` / `<your-strong-model>` placeholders for step-level model overrides.
+
+### Workflow YAML reference
+
+```yaml
+name: My Review Loop
+iteration_cap: 5
+steps:
+  implement:
+    agent: worker
+    model: openai/gpt-5.4        # optional: fast model
+    prompt: work prompt
+    next: review
+  review:
+    agent: reviewer
+    model: anthropic/claude-opus-4-5  # optional: strong model
+    prompt: review prompt
+    on_accept: _complete         # or a step name
+    on_reject: fix
+  fix:
+    agent: worker
+    model: openai/gpt-5.4
+    prompt: fix prompt
+    next: review
+```
+
+- `on_accept: _complete` ends the run.
+- `iteration_cap` prevents infinite review loops — the run fails at the cap.
+- Review agents must return `accept`/`reject` with findings or acceptance notes.
+
+## Package contents
+
+| Path | Purpose |
+|---|---|
+| `extensions/` | 4 slash-command entrypoint (`/baton:new`, `/baton:start`, `/baton:run`, `/baton:status`) |
+| `lib/` | Workflow parser, run engine, subagent runner, review contract, UI widget |
+| `agents/` | Builtin `worker` and `reviewer` subagent definitions |
+| `workflows/` | Builtin `default-review-loop.yaml` |
+| `docs/` | Release docs |
+
+## Development
+
+```bash
+npm install
+npm run ci
+```
+
+## License
+
+MIT

package/agents/reviewer.md

@@ -0,0 +1,15 @@
+---
+name: reviewer
+description: Baton review subagent for structured accept/reject judgments
+tools: read, grep, find, ls, bash
+---
+
+You are the reviewer step agent in a Pi Baton review loop.
+
+Review the implementation against the task brief. Bash is for read-only inspection only (`git diff`, `git log`, `git show`).
+
+Return a structured judgment using the JSON contract in the task prompt:
+- `accept` requires a non-empty `acceptanceNote`
+- `reject` requires non-empty `findings`
+
+Be specific and actionable. Include file paths and line numbers when possible.

package/agents/worker.md

@@ -0,0 +1,12 @@
+---
+name: worker
+description: General-purpose Baton implement/fix subagent with repository tool access
+---
+
+You are the worker step agent in a Pi Baton review loop.
+
+Work autonomously in an isolated context. Use repository tools to implement or fix the assigned task.
+
+Keep changes focused. Prefer small, reviewable diffs.
+
+When finished, follow the workflow JSON contract in the task prompt.

package/docs/examples.md

@@ -0,0 +1,49 @@
+# Examples
+
+This template ships one minimal example for each Pi package resource type.
+
+## Extension
+
+`extensions/hello.ts` registers:
+
+- `/template-hello`
+- a small session status indicator
+
+Try it with:
+
+```bash
+pi -e .
+```
+
+Then run:
+
+```txt
+/template-hello YourName
+```
+
+## Agent Skill
+
+`skills/example-skill/SKILL.md` demonstrates a minimal Agent Skill.
+
+Replace it with your real workflow instructions.
+
+## Prompt template
+
+`prompts/example.md` demonstrates a tiny prompt template with one variable.
+
+## Theme
+
+`themes/example-theme.json` is a placeholder theme. Replace it or remove `themes/` if your package does not ship themes.
+
+## Typed custom tool
+
+`extensions/index.ts` registers:
+
+- `/template-info`
+- `template_greet` custom tool
+
+The tool demonstrates:
+
+- TypeBox object parameters
+- a string enum schema via `StringEnum`
+- shared logic imported from `lib/greeting.ts`

package/docs/github-template.md

@@ -0,0 +1,63 @@
+# GitHub Template Repository
+
+> **Template bootstrap doc.** Use while setting up a new repo from this template. Delete this file or merge any project-specific steps into README / Vault notes once setup is done, unless it still adds maintainer value.
+
+## Recommended development flow
+
+After generating a repo from this template, use this default order:
+
+```txt
+Vault notes -> PRD -> Issues -> implement -> ci/check -> release -> save learnings
+```
+
+In practice:
+
+1. Create Vault notes under `4_Project/<ProjectName>/`.
+2. Add `CONTEXT.md`, `README.md`, `ROADMAP.md`, `Docs/`, `Issues/`, and `Progress/`.
+3. Write the PRD in `Docs/`.
+4. Split approved issue files into `Issues/`.
+5. Implement in the OSS repo created from this template.
+6. Run CI and package checks before release.
+7. Save release notes and follow-up decisions back to the Vault project.
+
+Enable template mode on the source repository:
+
+```txt
+GitHub repo → Settings → General → Template repository
+```
+
+Create a public repository from the template:
+
+```bash
+gh repo create OWNER/new-pi-extension \
+  --public \
+  --template OWNER/pi-extension-template \
+  --clone
+```
+
+Create a private repository from the template:
+
+```bash
+gh repo create OWNER/new-pi-extension \
+  --private \
+  --template OWNER/pi-extension-template \
+  --clone
+```
+
+Include all branches if needed:
+
+```bash
+gh repo create OWNER/new-pi-extension \
+  --public \
+  --template OWNER/pi-extension-template \
+  --include-all-branches \
+  --clone
+```
+
+After creation:
+
+```bash
+cd new-pi-extension
+npm install
+npm run ci
+```\n

package/docs/release.md

@@ -0,0 +1,57 @@
+# Release
+
+This package uses npm Trusted Publishing with GitHub Actions OIDC.
+
+Do not add `NPM_TOKEN` or long-lived npm tokens to GitHub Secrets.
+
+## One-time npm setup
+
+On npmjs.com, configure Trusted Publishing for this package:
+
+- Publisher: GitHub Actions
+- Repository: this GitHub repository
+- Workflow filename: `publish.yml`
+
+## Publish
+
+```bash
+npm version patch
+git push
+```
+
+On `main`, `.github/workflows/auto-release.yml` checks `package.json` version. If `v<version>` does not exist yet, it creates the tag, creates the GitHub Release, then explicitly dispatches `.github/workflows/publish.yml` for that tag.
+
+The `v*.*.*` tag also triggers `.github/workflows/publish.yml`, which runs CI and publishes to npm when tags are pushed manually.
+Publishing also runs when a GitHub Release is published, and can be run manually from GitHub Actions with `workflow_dispatch`.
+
+The workflow skips `name@version` if that exact package version already exists on npm.
+
+## Workflow guardrail
+
+Do not ship a new Pi OSS package or version bump with only `package.json` changes.
+The repository must include the release workflow pair:
+
+- `.github/workflows/auto-release.yml` creates `v<version>` tags and GitHub Releases from `main` version bumps.
+- `.github/workflows/publish.yml` publishes to npm through Trusted Publishing.
+
+Important: tags or releases created by `GITHUB_TOKEN` do not reliably fan out into another workflow through normal `push.tags` or `release.published` triggers. The template keeps publishing reliable by having `auto-release.yml` explicitly dispatch `publish.yml` after creating the tag/release. If you change the release flow, keep one explicit handoff path: `workflow_dispatch` from auto-release, `repository_dispatch`, or `workflow_run` on the auto-release workflow.
+
+## GitHub Actions requirements
+
+- `permissions: id-token: write`
+- `permissions: actions: write` on auto-release so it can dispatch `publish.yml`
+- `auto-release.yml` must call `gh workflow run publish.yml --ref "$TAG" -f ref="$TAG"`, or `publish.yml` must have an equivalent explicit handoff trigger such as `workflow_run`
+- GitHub-hosted runner
+- Node.js 24, so the release job uses a current npm CLI for Trusted Publishing
+- No `NPM_TOKEN`
+- `npm publish` from the configured workflow file
+
+## First release checklist
+
+- [ ] `package.json` name is final
+- [ ] `repository.url` points to the real GitHub repository
+- [ ] npm Trusted Publisher is configured
+- [ ] `npm run ci` passes
+- [ ] `npm pack --dry-run` contains only intended files
+- [ ] CHANGELOG.md has the release date
+

package/docs/repository-settings.md

@@ -0,0 +1,43 @@
+# Repository Settings
+
+> **Template bootstrap doc.** Use while configuring GitHub About, topics, and branch protection after generating a repo. Delete this file or merge needed settings into README once setup is done, unless it still adds maintainer value.
+
+Use this file after creating a real repository from the template.
+
+## GitHub About
+
+Suggested fields:
+
+- Description: one-line pitch for the Pi package
+- Website: npm package URL or project docs URL
+- Topics:
+  - `pi`
+  - `pi-package`
+  - `agent-skill`
+  - `typescript`
+
+## Template mode
+
+If this repository itself should be reusable as a template:
+
+```txt
+Settings → General → Template repository
+```
+
+## Branch protection
+
+Recommended for public packages:
+
+- Require pull request before merging
+- Require status checks to pass
+- Require `CI` workflow
+- Block force pushes on the default branch
+
+## npm package page
+
+After first publish:
+
+- Confirm README renders correctly
+- Confirm package provenance appears
+- Confirm package contents are intentional
+- Add npm URL to GitHub About and README

package/docs/template-checklist.md

@@ -0,0 +1,140 @@
+# Template Setup Checklist
+
+このテンプレートから新しい Pi 拡張OSSを作った後に埋めること。
+
+## Recommended flow
+
+- [ ] Vault project notes を `4_Project/<ProjectName>/` に作る
+- [ ] `CONTEXT.md` / `README.md` / `ROADMAP.md` / `Docs/` / `Issues/` / `Progress/` を揃える
+- [ ] PRD を `4_Project/<ProjectName>/Docs/` に置く
+- [ ] approved issue を `4_Project/<ProjectName>/Issues/` に切る
+- [ ] OSS repo 側で実装する
+- [ ] `npm run ci` / `npm test` / `npm pack --dry-run` を通す
+- [ ] release 後に Vault へ learnings / release notes を戻す
+
+## Repository
+
+- [ ] GitHub repository name を決める
+- [ ] GitHub About 欄を書く
+- [ ] GitHub topics を設定する
+  - [ ] `pi`
+  - [ ] `pi-package`
+  - [ ] `agent-skill`
+  - [ ] `typescript`
+- [ ] GitHub Settingsで `Template repository` をONにする
+- [ ] Repository URL を `package.json` に反映する
+- [ ] README の `OWNER/REPO` を実リポジトリに置き換える
+
+## Package metadata
+
+- [ ] `package.json` の `name` を変更する
+- [ ] `description` を書く
+- [ ] `author` を入れる
+- [ ] `repository.url` を埋める
+- [ ] `bugs.url` を埋める
+- [ ] `homepage` を埋める
+- [ ] `keywords` を見直す
+- [ ] `LICENSE` の年・名前を更新する
+
+## README placeholders
+
+- [ ] `PACKAGE_DISPLAY_NAME` を置き換える
+- [ ] `PACKAGE_NAME` を置き換える
+- [ ] `OWNER/REPO` を置き換える
+- [ ] one-line pitch を書く
+- [ ] feature list を書く
+- [ ] quick start command を実コマンドにする
+- [ ] npm URL を確認する
+- [ ] GitHub URL を確認する
+
+## Pi package manifest
+
+- [ ] `pi.extensions` に公開する拡張だけを残す
+- [ ] `pi.skills` に公開する skill だけを残す
+- [ ] 不要なら `prompts/` を消す
+- [ ] 不要なら `themes/` を消す
+- [ ] サンプル名を実名に変える
+
+## Documentation
+
+`docs/` は固定6ファイル必須ではない。README を正とし、価値がある doc だけ残す。
+
+### Required root files (public)
+
+- [ ] `README.md` — GitHub/npm の入口。Install / Quick start / Release / Security を含める
+- [ ] `LICENSE`
+- [ ] `SECURITY.md`
+- [ ] `CHANGELOG.md`
+- [ ] Release 手順が README と workflow で明確（Trusted Publishing 設定含む）
+
+### Recommended public docs (keep when useful)
+
+- [ ] `docs/examples.md` — 例が README に載り切らないとき
+- [ ] `docs/release.md` — Trusted Publishing や release 手順の詳細が README だけでは足りないとき
+- [ ] `docs/usage.md` — 使い方が README に載り切らないとき（必要なら新規作成）
+
+### Optional maintainer docs
+
+- [ ] `docs/template-checklist.md` — このファイル。成熟 repo では README からの主ナビにしない。不要なら削除可
+
+### Post-generation cleanup (delete or merge template setup docs)
+
+テンプレート生成直後の bootstrap 用。プロジェクト固有の価値がなければ削除し、必要な内容は README / `docs/release.md` / `docs/examples.md` に統合する。
+
+- [ ] `docs/github-template.md` を削除するか、固有の手順だけ README / Vault に移す
+- [ ] `docs/repository-settings.md` を削除するか、About/topics など必要分だけ README に移す
+- [ ] `docs/typescript.md` を削除するか、TypeScript 方針は README Development に要約する
+- [ ] README の Docs 節から、削除したファイルへのリンクを外す
+- [ ] `package.json` の `files` から、削除した `docs/` パスを外す（残す doc だけ明示する）
+
+## TypeScript
+
+- [ ] `extensions/index.ts` を実装に合わせて更新する
+- [ ] `extensions/hello.ts` が不要なら削除する
+- [ ] 共通ロジックを `lib/` に切り出す
+- [ ] `strict: true` を維持する
+- [ ] custom tool parameters は TypeBox schema で定義する
+- [ ] string choices は `StringEnum` helper を使う
+- [ ] runtime dependency は `dependencies`、Pi提供packageは `peerDependencies` に置く
+- [ ] `package.json.files` に公開対象だけを入れる
+- [ ] 詳細はセットアップ中だけ `docs/typescript.md` を参照し、不要なら post-generation cleanup で削除
+
+## GitHub Template repo
+
+- [ ] `gh repo create --template OWNER/pi-extension-template` で作成できることを確認する
+- [ ] public/privateどちらの作成例もdocsに載せる（`docs/github-template.md` を残す場合）
+
+## CI / Release
+
+- [ ] `npm run ci` が通る
+- [ ] `npm pack --dry-run` が通る
+- [ ] npm Trusted Publishing を設定する
+- [ ] npm Trusted Publisher の workflow filename が `publish.yml` になっている
+- [ ] `NPM_TOKEN` を使っていないことを確認する
+- [ ] `auto-release.yml` が `main` の version bump から tag/release を作ることを確認する
+- [ ] `publish.yml` が `workflow_dispatch` と `release.published` に対応していることを確認する
+- [ ] 初回リリースで npm provenance が付いているか確認する
+
+### Workflow handoff guard
+
+- [ ] `.github/workflows/auto-release.yml` exists before first release
+- [ ] `.github/workflows/publish.yml` exists before first release
+- [ ] `auto-release.yml` has `permissions: actions: write` and `contents: write`
+- [ ] `publish.yml` has `permissions: id-token: write` for npm Trusted Publishing
+- [ ] Auto release explicitly hands off to publish: `gh workflow run publish.yml --ref "$TAG" -f ref="$TAG"`, or `publish.yml` has an equivalent `workflow_run` / `repository_dispatch` trigger
+- [ ] Do not rely only on `push.tags` or `release.published` when the tag/release is created by `GITHUB_TOKEN`; that can leave npm unchanged after merge
+
+## npm page
+
+- [ ] npm package URL を README に追加する
+- [ ] npm description が適切に表示されるか確認する
+- [ ] provenance が付いているか確認する
+- [ ] 不要なファイルが package に含まれていないか確認する（`npm pack --dry-run` で `docs/` の残し方も確認）
+
+## Before first release
+
+- [ ] サンプルコードを実機 Pi でロードする
+- [ ] `pi install git:github.com/OWNER/REPO` を試す
+- [ ] `pi -e .` を試す
+- [ ] README のコマンドがコピペで動くか確認する
+- [ ] CHANGELOG に `0.1.0` を書く

package/docs/typescript.md

@@ -0,0 +1,77 @@
+# TypeScript Guide
+
+> **Template bootstrap doc.** Use while learning this template's TypeScript layout and dependency rules. Delete this file or summarize the policies you keep in README Development once setup is done, unless it still adds maintainer value.
+
+This is a TypeScript-first Pi package template.
+
+## Layout
+
+```txt
+extensions/*.ts      Pi extension entrypoints
+lib/*.ts             Shared TypeScript helpers
+skills/*/SKILL.md    Agent Skills
+prompts/*.md         Prompt templates
+themes/*.json        Themes
+tests/*.test.mjs     Smoke tests
+tests/*.test.ts      Optional TypeScript tests if you add a TS test runner
+```
+
+Pi loads TypeScript extensions directly, so no build step is required for normal use.
+
+## Strict mode
+
+`tsconfig.json` keeps `strict: true`. Prefer fixing types over loosening compiler options.
+
+## Extension entrypoints
+
+Two entrypoint styles are shown:
+
+- `extensions/hello.ts`: single-file extension
+- `extensions/index.ts`: index-style extension that imports shared code from `lib/`
+
+For larger packages, keep entrypoints thin and put reusable logic in `lib/`.
+
+## TypeBox schemas
+
+Use TypeBox schemas for custom tool parameters.
+
+```ts
+import { Type } from "typebox";
+
+const parameters = Type.Object({
+  name: Type.String({ description: "Name to greet" }),
+});
+```
+
+## String enums
+
+For string choices, use the local `StringEnum` helper from `lib/schema.ts`.
+
+```ts
+import { StringEnum } from "../lib/schema.ts";
+
+const mode = StringEnum(["short", "friendly"], {
+  description: "Greeting style",
+});
+```
+
+This emits a JSON Schema `enum`, which is friendlier to model providers than a union of string literals.
+
+## Runtime dependencies vs peer dependencies
+
+Pi bundles core packages for extension authors. Keep Pi-provided packages as `peerDependencies` and also install them as `devDependencies` for local typechecking.
+
+Use `peerDependencies` for:
+
+- `@earendil-works/pi-coding-agent`
+- `@earendil-works/pi-ai`
+- `@earendil-works/pi-tui`
+- `typebox`
+
+Use `dependencies` for runtime packages your extension imports that Pi does not provide.
+
+Use `devDependencies` for local-only tools such as TypeScript, test runners, and linters.
+
+## Package contents
+
+Control npm package contents with `package.json` `files`. Prefer this over `.npmignore` so the published package stays explicit.