mise.toml files are the source of truth for tools, tasks, dependencies, and orchestration.
Use an existing Mise task instead of invoking its npm script, Node script, formatter, test runner, or browser runner directly.
Root npm scripts are task implementation details.
Extension package scripts are prohibited.
Add missing automation to the appropriate mise.toml; do not create ad hoc scripts or bypass Mise.
If Mise or its project config blocks progress, report the exact failure and stop rather than working around it.
Task discovery
Run mise tasks --all to list root and extension-local tasks.
Use monorepo-root paths when referring to tasks from automation or documentation:
//:test addresses a root task.
//extensions/angel:test addresses an extension task.
//extensions/...:bench selects a task across matching extension config roots.
Task-name groups and wildcards select tasks; they do not create dependencies or ordering.
Use mise task info <task> for task details, mise tasks deps <task> for declared dependency edges, and mise run --dry-run <task> to inspect execution.
Run mise tasks validate after changing the root config.
Run mise -C extensions/<name> tasks validate after changing an extension config.
Choosing tasks
Need
Command
Install exact locked dependencies
mise run //:install
Regenerate package-lock.json
mise run //:lock
Format the repository
mise run //:fmt
Verify repository formatting and lint
mise run //:lint
Run the complete test suite once
mise run //:test
Run one extension's tests
mise run //extensions/<name>:test
Lint one extension
mise run //extensions/<name>:lint
Typecheck and statically check one extension
mise run //extensions/<name>:check
Typecheck and statically check all extensions
mise run //:check
Run property tests
mise run //:fuzz
Run all benchmarks sequentially
mise run //:bench
Run all browser E2E suites
mise run //:e2e
Run the release gate
mise run //:ci
Use mise run //:test -- extensions/<name> and mise run //:build -- <name> only when implementing a local task or diagnosing its root delegate.
Normal agent workflows should use the extension-local task names.
Root operation tasks are //:list, //:changelog, //:readme, //:demo, //:release-plan, //:release-prepare, and //:publish.
Invoke one with mise run, passing extension names after --, for example mise run //:readme -- angel.
Efficient execution
Choose the smallest task that proves the change, then run the required wider gate.
During iteration, use one extension's local lint, test, or check task.
For complete tests, run root //:test once; do not fan out all extension test wrappers into one Vitest process per extension.
For complete static validation, run root //:check once; do not fan out all extension check wrappers because each repeats repository-wide TypeScript checking.
Before pushing, run mise run //:ci.
Mise task jobs and tool workers multiply.
Set --jobs deliberately when invoking multiple independent tasks, because Vitest, Playwright, and other tools manage their own workers.
Use ::: only for independent ad hoc tasks that should run concurrently.
Task authoring
Use depends for prerequisites so Mise can deduplicate shared work and schedule independent dependencies concurrently.
Use structured task references instead of spawning nested Mise processes:
run = [{ task = "//:test", args = ["extensions/angel"] }]
A run array is sequential.
Use { tasks = ["check", "lint"] } for an explicit parallel stage inside that sequence.
Structured task references execute their own dependencies but do not appear as edges in mise tasks deps.
Use a nested mise run command only when a required CLI scheduler option, such as --jobs 1, has no structured-task equivalent.
Do not set raw = true unless a task requires stdin.
Raw tasks serialize against other tasks and disable output redaction.
CI hosting
Luci at ci.bugabinga.net auto-discovers .ci/*.kdl from the public Soft Serve repository.
Repository CI must delegate to CI=true mise run //:ci; do not duplicate gates in Luci configuration.
mise run //:ci must pass before pushing.
It runs check and lint concurrently, then test, fuzz, and E2E sequentially.
Extension engineering
Startup performance
Treat every Win32 process spawn as expensive.
Prefer native Node APIs and defer unavoidable spawns until first use.
Keep entry modules thin and lazy-load command or tool implementations.
Gate optional domain work with cheap relevance checks before imports.
Never block startup or reload on subprocess probes, broad filesystem scans, or Git status.
Abort asynchronous startup work on reload and ignore stale results.
Check executable presence through native PATH access, not version subprocesses.
Preserve registration, validation, rendering, and first-use behavior when deferring work.
Measure performance with the complete extension set on Win32 and WSL.
Tool widget rendering
Tool widgets must match Pi built-ins: compact by default, expanded details on app.tools.expand (ctrl+o by default).
Collapsed renderResult output may show status, counts, paths, IDs, and tiny bounded summaries only.
Full content, previews, snippets, verbose logs, structured bodies, and per-result lists require expanded === true.
Expansion hints must use keyHint("app.tools.expand", "to expand"); do not use legacy expandTools.
Cross-platform requirements
All extensions must work on Windows, macOS, and Linux.
Do not add OS-scoped extensions.
Do not rely on shell helpers such as which, bash, sed, grep, or /tmp when Node APIs can do the job.
If an extension uses platform tools, check availability when the extension loads.
Notify missing required tools with warning severity and missing optional tools with info severity.
Tests for platform-tool behavior must exercise the real extension or tool path with controlled fake binaries on PATH, not only mocked helpers.
Markdown style
Use one sentence per line for prose.
Keep semantic line breaks unless rewording the sentence.
Let rumdl handle Markdown structure; do not manually reflow paragraphs for visual width.
Git hooks
pre-commit runs format, lint, and test.
pre-push runs full CI.
Hooks are managed through mise generate git-pre-commit.
Reinstall them with mise generate git-pre-commit --write, then mise generate git-pre-commit --hook pre-push --task pre-push --write.
Troubleshooting
Run mise doctor when a task fails because a command is unavailable.
Common causes are missing activation, missing shims, or a mismatched tool binary name.
Markdown source
# Pi Extensions WorkspaceMonorepo for Pi extensions under `extensions/*`.
## Automation law- Mise is the only public automation interface.
- `mise.toml` files are the source of truth for tools, tasks, dependencies, and orchestration.
- Use an existing Mise task instead of invoking its npm script, Node script, formatter, test runner, or browser runner directly.
- Root npm scripts are task implementation details.
- Extension package scripts are prohibited.
- Add missing automation to the appropriate `mise.toml`; do not create ad hoc scripts or bypass Mise.
- If Mise or its project config blocks progress, report the exact failure and stop rather than working around it.
## Task discoveryRun `mise tasks --all` to list root and extension-local tasks.
Use monorepo-root paths when referring to tasks from automation or documentation:
- `//:test` addresses a root task.
- `//extensions/angel:test` addresses an extension task.
- `//extensions/...:bench` selects a task across matching extension config roots.
Task-name groups and wildcards select tasks; they do not create dependencies or ordering.
Use `mise task info <task>` for task details, `mise tasks deps <task>` for declared dependency edges, and `mise run --dry-run <task>` to inspect execution.
Run `mise tasks validate` after changing the root config.
Run `mise -C extensions/<name> tasks validate` after changing an extension config.
## Choosing tasks| Need | Command |
| --- | --- |
| Install exact locked dependencies | `mise run //:install` |
| Regenerate `package-lock.json` | `mise run //:lock` |
| Format the repository | `mise run //:fmt` |
| Verify repository formatting and lint | `mise run //:lint` |
| Run the complete test suite once | `mise run //:test` |
| Run one extension's tests | `mise run //extensions/<name>:test` |
| Lint one extension | `mise run //extensions/<name>:lint` |
| Typecheck and statically check one extension | `mise run //extensions/<name>:check` |
| Typecheck and statically check all extensions | `mise run //:check` |
| Run property tests | `mise run //:fuzz` |
| Run all benchmarks sequentially | `mise run //:bench` |
| Run all browser E2E suites | `mise run //:e2e` |
| Run the release gate | `mise run //:ci` |
Use `mise run //:test -- extensions/<name>` and `mise run //:build -- <name>` only when implementing a local task or diagnosing its root delegate.
Normal agent workflows should use the extension-local task names.
Root operation tasks are `//:list`, `//:changelog`, `//:readme`, `//:demo`, `//:release-plan`, `//:release-prepare`, and `//:publish`.
Invoke one with `mise run`, passing extension names after `--`, for example `mise run //:readme -- angel`.
## Efficient executionChoose the smallest task that proves the change, then run the required wider gate.
- During iteration, use one extension's local `lint`, `test`, or `check` task.
- For complete tests, run root `//:test` once; do not fan out all extension `test` wrappers into one Vitest process per extension.
- For complete static validation, run root `//:check` once; do not fan out all extension `check` wrappers because each repeats repository-wide TypeScript checking.
- Before pushing, run `mise run //:ci`.
Mise task jobs and tool workers multiply.
Set `--jobs` deliberately when invoking multiple independent tasks, because Vitest, Playwright, and other tools manage their own workers.
Use `:::` only for independent ad hoc tasks that should run concurrently.
## Task authoringUse `depends` for prerequisites so Mise can deduplicate shared work and schedule independent dependencies concurrently.
Use structured task references instead of spawning nested Mise processes:
```tomlrun = [{ task = "//:test", args = ["extensions/angel"] }]
```
A `run` array is sequential.
Use `{ tasks = ["check", "lint"] }` for an explicit parallel stage inside that sequence.
Structured task references execute their own dependencies but do not appear as edges in `mise tasks deps`.
Use a nested `mise run` command only when a required CLI scheduler option, such as `--jobs 1`, has no structured-task equivalent.
Do not set `raw = true` unless a task requires stdin.
Raw tasks serialize against other tasks and disable output redaction.
## CI hostingLuci at `ci.bugabinga.net` auto-discovers `.ci/*.kdl` from the public Soft Serve repository.
Repository CI must delegate to `CI=true mise run //:ci`; do not duplicate gates in Luci configuration.
**`mise run //:ci` must pass before pushing.**
It runs check and lint concurrently, then test, fuzz, and E2E sequentially.
## Extension engineering### Startup performance- Treat every Win32 process spawn as expensive.
- Prefer native Node APIs and defer unavoidable spawns until first use.
- Keep entry modules thin and lazy-load command or tool implementations.
- Gate optional domain work with cheap relevance checks before imports.
- Never block startup or reload on subprocess probes, broad filesystem scans, or Git status.
- Abort asynchronous startup work on reload and ignore stale results.
- Check executable presence through native `PATH` access, not version subprocesses.
- Preserve registration, validation, rendering, and first-use behavior when deferring work.
- Measure performance with the complete extension set on Win32 and WSL.
### Tool widget renderingTool widgets must match Pi built-ins: compact by default, expanded details on `app.tools.expand` (`ctrl+o` by default).
Collapsed `renderResult` output may show status, counts, paths, IDs, and tiny bounded summaries only.
Full content, previews, snippets, verbose logs, structured bodies, and per-result lists require `expanded === true`.
Expansion hints must use `keyHint("app.tools.expand", "to expand")`; do not use legacy `expandTools`.
### Cross-platform requirementsAll extensions must work on Windows, macOS, and Linux.
Do not add OS-scoped extensions.
Do not rely on shell helpers such as `which`, `bash`, `sed`, `grep`, or `/tmp` when Node APIs can do the job.
If an extension uses platform tools, check availability when the extension loads.
Notify missing required tools with warning severity and missing optional tools with info severity.
Tests for platform-tool behavior must exercise the real extension or tool path with controlled fake binaries on `PATH`, not only mocked helpers.
## Markdown styleUse one sentence per line for prose.
Keep semantic line breaks unless rewording the sentence.
Let `rumdl` handle Markdown structure; do not manually reflow paragraphs for visual width.
## Git hooks- `pre-commit` runs format, lint, and test.
- `pre-push` runs full CI.
Hooks are managed through `mise generate git-pre-commit`.
Reinstall them with `mise generate git-pre-commit --write`, then `mise generate git-pre-commit --hook pre-push --task pre-push --write`.
## TroubleshootingRun `mise doctor` when a task fails because a command is unavailable.
Common causes are missing activation, missing shims, or a mismatched tool binary name.