repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

docs: move automation procedures into an on-demand skill

4378b5953335a2d38b5b24dc42bbe42eb5fab192

Oliver Jan Krylow <oliver@bugabinga.net> ·

SSH signature · not checked

Browse filesCompare with HEAD

Changed files (2)

.pi/skills/pi-ext-automation/SKILL.md

Added
new file mode 100644
1 +---
2 +name: pi-ext-automation
3 +description: "Use when authoring or editing pi-ext Mise tasks and mise.toml, inspecting task definitions or dependency edges, reinstalling Git hooks, or diagnosing a failing or missing Mise task in this repository."
4 +---
6 +# pi-ext automation
8 +Mise is the only public automation interface here.
9 +This skill holds the how-to; `.system/RULES.md` holds the binding law.
11 +## Task inventory
13 +Root tasks:
15 +| Task | Purpose |
16 +|---|---|
17 +| `//:install` | Install exact locked dependencies |
18 +| `//:lock` | Regenerate the lockfile |
19 +| `//:fmt` | Format the repository |
20 +| `//:lint` | Verify formatting and lint |
21 +| `//:test` | Run the complete test suite once |
22 +| `//:check` | Typecheck and statically validate all extensions |
23 +| `//:bench` | Run all extension benchmarks sequentially |
24 +| `//:e2e` | Run all browser acceptance suites |
25 +| `//:ci` | Complete release gate |
26 +| `//:list`, `//:changelog`, `//:readme`, `//:release-plan`, `//:release-prepare`, `//:publish` | Repository operations |
28 +Extension tasks: `//extensions/<name>:test`, `//extensions/<name>:lint`, `//extensions/<name>:check`.
30 +## Inspection
32 +- `mise tasks --all` lists root and extension-local tasks.
33 +- `mise task info <task>` shows one definition.
34 +- `mise tasks deps <task>` shows dependency edges.
35 +- `mise run --dry-run <task>` shows execution without running it.
36 +- `mise tasks validate` after changing root configuration.
37 +- `mise -C extensions/<name> tasks validate` after changing extension-local configuration.
39 +## Authoring
41 +- Use task dependencies for prerequisites so Mise can deduplicate and schedule shared work.
42 +- Prefer structured task references over command strings that spawn nested Mise processes.
43 +- Treat a task `run` array as sequential execution.
44 +- Use a structured task group for an explicitly parallel stage.
45 +- Spawn nested Mise only when a required scheduler option has no structured-task equivalent.
46 +- Do not enable raw task mode unless the task requires standard input.
47 +- Set Mise job counts deliberately when tasks invoke tools that manage their own workers.
48 +- Use `:::` only for independent ad hoc tasks that should run concurrently.
50 +## Git hooks
52 +Pre-commit and pre-push run only `check` and `lint`.
54 +- Reinstall pre-commit: `mise generate git-pre-commit --write`
55 +- Reinstall pre-push: `mise generate git-pre-commit --hook pre-push --task pre-push --write`
57 +## Troubleshooting
59 +- Run `mise doctor` when a task fails because a command is unavailable.
60 +- Check missing activation, missing shims, and mismatched tool binary names first.
61 +- A stale shim can shadow a real binary; `mise which <bin>` reports whether Mise owns it.

.system/RULES.md

Modified
4 4 # RULES
6 6 ## Automation law
8 8 - Use Mise as the only public automation interface.
9 9 - Treat `mise.toml` files as the source of truth for tools, tasks, dependencies, and orchestration.
10 -- Use an existing Mise task instead of invoking its npm script, Node script, formatter, test runner, or browser runner directly.
11 -- Keep root npm scripts as task implementation details.
12 -- Do not add extension package scripts.
10 +- Use an existing Mise task instead of its npm script, Node script, formatter, test runner, or browser runner.
11 +- Keep root npm scripts as task implementation details, and add no extension package scripts.
13 12 - Add missing automation to the appropriate `mise.toml`.
14 13 - Stop and report the exact failure when Mise or its project configuration blocks progress.
16 -## Task discovery
18 -- Run `mise tasks --all` to list root and extension-local tasks.
19 -- Address root tasks as `//:<task>` and extension tasks as `//extensions/<name>:<task>`.
20 -- Use `mise task info <task>` for details, `mise tasks deps <task>` for dependency edges, and `mise run --dry-run <task>` to inspect execution.
21 -- Run `mise tasks validate` after changing root Mise configuration.
22 -- Run `mise -C extensions/<name> tasks validate` after changing extension-local Mise configuration.
24 15 ## Task selection
26 -- Use `mise run //:install` to install exact locked dependencies.
27 -- Use `mise run //:lock` to regenerate the lockfile.
28 -- Use `mise run //:fmt` to format the repository.
29 -- Use `mise run //:lint` to verify repository formatting and lint.
30 -- Use `mise run //:test` to run the complete test suite once.
31 -- Use `mise run //extensions/<name>:test` to test one extension.
32 -- Use `mise run //extensions/<name>:lint` to lint one extension.
33 -- Use `mise run //extensions/<name>:check` to check one extension.
34 -- Use `mise run //:check` to check all extensions once.
35 -- Use `mise run //:bench` to run all extension benchmarks sequentially.
36 -- Use `mise run //:e2e` to run all browser acceptance suites.
37 -- Use `mise run //:ci` only for the complete release gate.
38 -- Use the root `list`, `changelog`, `readme`, `release-plan`, `release-prepare`, and `publish` tasks for repository operations.
40 -## Efficient execution
42 -- Choose the smallest task that proves the change.
43 -- During iteration, use the affected extension's local `lint`, `test`, or `check` task.
44 -- Stop after the smallest affected tasks pass.
45 -- Run `//:ci`, `//:e2e`, or unrelated suites only when the human explicitly requests that exact wider gate.
46 -- Do not treat commits, merges, or generic verification requests as requests for wider gates.
47 -- For complete tests, run root `//:test` once instead of expanding every extension test wrapper.
48 -- For complete static validation, run root `//:check` once instead of expanding every extension check wrapper.
49 -- Set Mise job counts deliberately when tasks invoke tools that manage their own workers.
50 -- Use `:::` only for independent ad hoc tasks that should run concurrently.
52 -## Task authoring
54 -- Use task dependencies for prerequisites so Mise can deduplicate and schedule shared work.
55 -- Prefer structured task references over command strings that spawn nested Mise processes.
56 -- Treat a task `run` array as sequential execution.
57 -- Use a structured task group for an explicitly parallel stage.
58 -- Spawn nested Mise only when a required scheduler option has no structured-task equivalent.
59 -- Do not enable raw task mode unless the task requires standard input.
17 +- Run `mise tasks --all` to list tasks; address them as `//:<task>` and `//extensions/<name>:<task>`.
18 +- Choose the smallest task that proves the change, and stop once it passes.
19 +- During iteration, use the affected extension's `lint`, `test`, or `check`.
20 +- For complete verification, run root `//:test` or `//:check` once instead of expanding per-extension wrappers.
21 +- Run `//:ci`, `//:e2e`, or unrelated suites only when the human requests that exact wider gate.
22 +- Do not treat commits, merges, or generic verification requests as wider-gate requests.
23 +- Validate Mise configuration after changing it: `mise tasks validate`, or `mise -C extensions/<name> tasks validate`.
24 +- Load the `pi-ext-automation` skill before authoring tasks, editing `mise.toml`, reinstalling hooks, or diagnosing Mise failures.
61 26 ## Repository safety
63 -- Preserve unrelated dirty work.
64 -- Do not delete noisy research, cache, or untracked files unless explicitly requested.
65 -- Never print decrypted secrets.
66 -- Never run privileged, root, or elevated commands.
28 +- Preserve unrelated dirty work, and do not delete noisy research, cache, or untracked files unless asked.
29 +- Never print secrets, and never run privileged commands.
68 31 ## CI
70 -- Keep repository CI definitions under `.ci/*.kdl` for Luci discovery.
71 -- Delegate CI execution to `CI=true mise run //:ci` instead of duplicating repository gates in Luci configuration.
72 -- Full CI runs on Luci after pushing.
73 -- Run full CI locally only when explicitly requested.
33 +- Keep repository CI definitions under `.ci/*.kdl` and delegate execution to `CI=true mise run //:ci`.
34 +- Full CI runs on Luci after pushing; run it locally only when explicitly requested.
75 36 ## Git hooks
77 -- Keep pre-commit limited to `check` and `lint`.
78 -- Keep pre-push limited to `check` and `lint`.
38 +- Keep pre-commit and pre-push limited to `check` and `lint`.
79 39 - Manage hooks through `mise generate git-pre-commit`.
80 -- Reinstall pre-commit with `mise generate git-pre-commit --write`.
81 -- Reinstall pre-push with `mise generate git-pre-commit --hook pre-push --task pre-push --write`.
83 41 ## Markdown
85 43 - Write one sentence per line.
86 44 - Preserve semantic line breaks.
87 45 - Let rumdl handle Markdown structure instead of manually reflowing prose.
89 -## Troubleshooting
91 -- Run `mise doctor` when a task fails because a command is unavailable.
92 -- Treat missing activation, missing shims, and mismatched tool binary names as the common first checks.