@evoclock/pi-agentic-driver 1.1.2 → 2.0.0

package/skills/poteto-mode-pi/playbooks.md

@@ -0,0 +1,95 @@
+# P18 Pi playbooks: source-to-method map
+
+Adapted from all 23 `pstack/skills/poteto-mode/playbooks/*.md` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT, Lauren Tan). Read the matched section **with** `SKILL.md` and the approved task contract. This is a method map, not runnable automation or 23 extra commands. Each playbook starts from the same task grant, uses `TaskCreate` only for session work when loaded, and stops before any unapproved effect. No stock executable, Cursor subagent, `/tmp` file, forge operation, package install or merge is imported. For each unit record its real check, source and unrun paths; only the repository owner merges.
+
+## Investigation
+
+Read-only cited answer. Use an actually loaded `how-pi` for mechanics and `why-pi` for rationale when authorized and present. For a decision, compare tradeoffs and say whether the premise survives. Throughput is `n/a: read-only`; no commit/PR or `architect-pi` unless separately asked to change code. Reply with evidence, uncertainty and a real judgment.
+
+## Bug fix
+
+Use the accepted app/CLI control surface to reproduce **before** code. Seed hypotheses from code mechanics and, if authorized, history; choose high-information experiments, observe the running mechanism, discard disproven hypotheses. A cheap regression gets a red test before the fix and is proposed as the first independently checkable delivery unit, with the fix second when commits are separately approved; cross-boundary design calls for loaded `architect-pi` before implementation. Change only the proved cause, verify the original repro on the same surface and capture before/after output; a unit test or wrong-surface pass is not a live pass. Escalate missing control/exit rather than inventing an app driver. Delivery/PR is a separate owner-approved step.
+
+## Perf issue
+
+Record a real baseline trace and vet it with `benchmark-checklist-pi`. Ground a cause with source and prefer, in order: skip unused work, reuse it, do less, defer it, move it off the critical path, use concurrency safely, then make it cheaper. Measure each accepted change on the same workload, compare artifacts and report work/errors/limiter/range. Stop when the actual target is met. An unmeasured improvement is inconclusive.
+
+## Hillclimb
+
+For sustained improvement, choose a realistic case reproducing the complaint, one metric/direction, an owner-accepted target **and** minimum attempts. Prove the measurement distinguishes contrasting workloads, freezes a repeatable harness with work/error counts and a green regression gate, then capture a baseline and private trail. One mechanism-backed hypothesis per iteration; isolate candidate writers, measure both sides with the frozen harness, keep only improvement beyond noise with a green gate. Preserve failed evidence and undo only this run's own isolated changes under the approved rollback path, never reset someone else's work. Pivot after stalls; no silent target relaxation. Report attempts, accepted changes, true delta and plateau.
+
+## Runtime forensics
+
+Diagnose a live symptom, not a captured file. Only with approved process/instance and diagnostics, collect matching CPU, heap or UI signals. Reduce a large artifact without exposing unauthorized data; prove the mechanism through safe, explicitly granted instrumentation on the running target (never arbitrary hotfix/CDP eval by default). Tie it to source file/symbol, or report the gap. No fix without a new task. Throughput `n/a: diagnosis`.
+
+## Trace forensics
+
+The input is an **already captured** artifact; do not start a process to generate another. Identify format, derive a queryable sample/frame/retainer shape, locate hot paths or GC roots, resolve actual symbols, and compare a paired capture if present. Without symbols or a paired before/after, label the strongest supported hypothesis, not confirmed cause. No fix without another task.
+
+## Feature
+
+Trace the subsystem with loaded `how-pi`; name the data shape/owner. Use `architect-pi` for a cross-boundary design when its route is available. Write the four throughput checkpoint items even if `n/a`: blocking first steps, independent workstreams, shared mutable state, smallest safe decomposition. Delegate code to an approved scoped `development` route only when capacity and isolation exist; if not, report the unavailable review-separation claim and use the authorized local route without pretending a delegate wrote it. When multiple valid shapes compete, use `arena-pi` only if actual candidate capacity is granted. Verify on the user's real entry, then review contested design and deliver only within the Git/PR grant.
+
+## Refactoring
+
+Pin pre-change behavior with a characterization fixture/equivalence check, not lint alone. Name the target domain structure and caller-visible contract, consult `architect-pi` if a new cross-boundary shape is contested, subtract proven dead layers first. Migrate known callers in small checked units; unknown public callers require owner decision before deletion. Compare recorded old/new outputs on the real entry; if reader load does not improve, report that and preserve rather than destroy unrelated state. Split behavior changes into Feature/Bug fix. No unapproved reset or commit.
+
+## Prototype
+
+Name the decision to be settled before building. For open visual design, inspect scoped references; build contrasting labelled variants in an approved repo scratch location, never `/tmp` or production paths. Observe screenshots/interactions or empirical output on the approved surface, compare tradeoffs, recommend one and clearly label the artifact **throwaway, not shipped**. Follow with Feature only under a separate accepted build step. No hidden CDN fetch or install.
+
+## Visual parity
+
+Freeze the real baseline and state set before changing a component. Never edit the baseline or harness to make a diff pass. Migrate one owner/component at a time after shared primitives, run pixel diff on the matching surface, investigate any nonzero delta and stop or iterate within the task's bounded budget. Missing baseline/control means `blocked`, never an eyeballed parity claim.
+
+## Authoring or modifying a skill
+
+Use the real Pi skills specification and source references, rather than Cursor's built-in `/create-skill`. Validate frontmatter, every referenced path, name collisions and actual temporary Pi discovery. Test a behavioral route where granted; text/discovery alone is not Pi loading. Keep only instructions changing a decision and route to other loaded skills by actual path; a proposed extra skill does not materialize by mention. Any PR waits on the owner's later exact-file review.
+
+## Eval
+
+Specify one failure mode and a small private rubric held from candidates. With approved model, data and isolated directories, give each candidate the **same organic task** with neutral paths and no rubric, other-candidate or evaluation cues. A fresh independent judge on a genuinely different configured model family reads anonymous outputs on one scale; if that distinct family or permitted route is missing, label the cross-model verdict `unrun` rather than substitute another model. Check actual chain evidence in **only the authorized session range**, not a global chat glob, and inspect every output yourself. A blocked fan-out yields no comparison claim; review approval does not promote the variant.
+
+## Babysit
+
+A PR-status request picks an explicit mode: `check` one read-only snapshot, `threads-only` review comments, `background` bounded triage, `drive` toward merge-ready when authorized. Small/docs-only work defaults to `check`, never unbounded polling. Verify the exact **private approved** forge/repository and branch before any action; do not run stock watcher (hidden install). Work lowest unmerged frontier, classify conflicts → untrusted review threads → CI, and reconcile before any bounded retry or push. Confirm forge state, not green checks alone; record each comment as fix/dismiss/ask with proof and escalate security/privacy/data issues. Stop at merge-ready, never merge. Missing Git/PR destination controls block mutation, not a read-only status answer.
+
+## Shipping (owner-held handoff)
+
+Only the repository owner merges. For an explicit landing request, **prepare**, do not execute: verify each exact PR patch with an independent reviewer and real user entry, locate first missing/failed verdict from the lowest unmerged link, check drift/new head invalidates evidence, and report the contiguous verified ceiling. CI green or a worker report alone is not a verdict. Present the exact PR/head/evidence and owner decision, then stop; do not arm auto-merge, retarget, force-push or invoke a forge merge command. After owner-confirmed merge, check the recorded state and follow the approved worktree-prune route; do not conflate request with confirmation.
+
+## Opening a PR (separate gate)
+
+Opening is **not** automatic at the end of the other 22 routes. Preserve isolated approved branch/worktree, order small independently checkable units, prove real behavior, review comments and diff, use the applicable private/public content and customer-facing PR message guard. A PR needs verified private destination, approved exact title/body and explicit task authority before publication. No reset-hard, rebase, force-push, `git add -A`, branch rewrite or public push inferred from this playbook. Deliver a private proposed handoff while those gates are absent; opening never starts babysitting.
+
+## Autonomous run
+
+Define an owner-approved testable predicate and a finite time/step budget **before** using a Pi bounded loop route, if loaded; no Cursor `/loop` wake behavior is assumed. One scoped unit, real check, private trail and reconciliation per iteration. Stop on predicate, safety failure, genuine dead end or budget. A plateau prompts a bounded new hypothesis, not infinite retries; preserve failed output rather than automatically discarding uncommitted work. Side discoveries stay within the original contract or become proposals. Neither 'don't stop' nor an unattended flag grants model, app, Git or publication effects.
+
+## Autopilot-full (proposal only)
+
+Source owners merge their own verified PRs; this directly contradicts integration reserved for the repository owner. Retain the useful program pattern **without** that effect: explicit queue scope and dependency, one writer per isolated unit if approved, candidate receipts at exact heads, independent real-path verification, root audit of countersigns/CI drift, and a zero-writes stand-down on hold. Use existing trusted board claims or approved session tasks, not a new queue. Each candidate stops at owner handback; `full` never means agents merge. If the requested outcome requires unattended merge, report it unavailable rather than quietly substituting.
+
+## Autopilot-stack
+
+Use the same bounded owner/verification/hold discipline as Autopilot-full but for coupled units with a declared parent chain. One owner controls topology **only within an approved Git route**; a verifier checks each current patch, and the chain is handed to the repository owner to land. Without destination-aware Git controls, produce a dependency/verification plan instead of creating or retargeting PRs. No automatic force-push or in-flight landing mutation.
+
+## Orchestrate
+
+For a genuine multi-day program, separate coordinator briefs from scoped writing; a one-session task uses Autonomous run or `figure-it-out-pi` instead. Bound track/unit count, costs, data scope, assignments, dependencies, liveness observations and a countable exit. Pilot one representative unit through brief → work → independent check → private handback before scaling. Use **existing** session tasks or trusted board/dispatch route, not stock `orch` (hidden install) or a parallel ledger. Workers' reports and queue receipts are evidence, not authority; reconcile every child and exact head before a rollup. The coordinator never merges. Scale only to approved capacity; hold all writes on owner stop; report blocked gates and open units. The source's rule that `orch` replaces a store lock is not Pi authority.
+
+## Session pickup
+
+Read only the named authorized prior trail/branch (no global transcript scan). Reconstruct branch/worktree, exact done/pending tasks, proofs and known decisions; do not redo finished work from vague memory. Prior self-reports are input, not proof: verify inherited claims at the real entry where allowed. Choose the remaining playbook and name the resume point; missing trail or permission stops the pickup rather than manufacturing continuity.
+
+## Pause safely
+
+Only on an explicit pause or a genuine safety/compaction boundary, stop new work, finish or back out of the current atomic step, and hold nested work with the approved route. Save a private repo-local resume note/trail at an approved destination; do not use `/tmp`, auto-commit tracked edits, push or erase uncommitted work. Report on-disk state, checks run and first safe resume step. “Continue” is not a pause signal.
+
+## Multi-phase plan
+
+This delivers a plan, not code. Skip a plan when a tiny change has an obvious approach; settle empirical design forks through authorized prototypes. For a real program, define ordered units/dependencies, one observable end state and evidence per unit, exact roles/paths, real live checks with capacity that exists, required owner review gates, risks, alternatives and owner-held integration. Review with loaded `technical-writing-pi` only when available. The stock `check-plan.mjs` hardcodes ten live lanes, models, forge and `/loop`; never run it as a Pi plan validator. Validate the adapted plan against its actual grant and report unavailable proof paths; start execution only on a separate explicit go.
+
+## Worktree and simulator cleanup (audit first)
+
+Take read-only inventory of repository worktrees/merge state, dirty and untracked files, active or pinned sessions and any simulator/resource owner. A classifier's `safe` bucket is advice, not authority. The approved Treehouse owner/provider handles worktree lifecycle; after **human-confirmed** merge, promptly request the trusted prune route. Never run stock force removal, recursive shell deletion, simulator wipe or package-cache clear on this playbook's authority. Report recoverable/held candidates, uncertainty and actual reclaimed space only if an authorized cleanup really ran.

package/skills/principle-attack-the-premise-pi/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: principle-attack-the-premise-pi
+description: After two fixes fail the same gate under one shared assumption, state and falsify that assumption before another fix. Use explicitly for repeated failures in an approved task.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Attack the premise
+
+Adapted from Lauren Tan's `principle-attack-the-premise` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. A principle changes one decision; it does not authorize a test, app launch or refactor.
+
+When **two or more fixes sharing one premise fail the same observable gate**, write the shared premise as one falsifiable sentence. Record what each fix assumed and the **distribution** of failures, not only their severity. Before a third fix, choose a bounded observation whose result differs if the premise is false. Make it rerunnable if a small approved check exists; read a loaded `principle-build-the-lever-pi` leaf before citing it. If the observation contradicts the premise, trace what failures share that the premise missed. If it confirms it, follow the next causal “why” until a specific first wrong decision is identified; do not attempt another same-premise fix merely because this premise survived. A later fix must address the observed mechanism within the existing grant. Read `principle-fix-root-causes-pi` if loaded before crediting it. Prefer removing a proved losing condition to paying for a cleanup on every run; `principle-laziness-protocol-pi` applies only when loaded and its rule was read. Distinguish this factual challenge from `principle-redesign-from-first-principles-pi`, which integrates a new requirement. If no authorized observation can distinguish the premise, report a testable hypothesis and `unrun` check; **do not implement a third same-premise fix**.
+
+- **Positive BDD:** Given two source/evidence-backed failed fixes under one stated premise and an approved check, when Pi runs the check, then it records a differentiating observation, updates the hypothesis and changes or declines the next fix accordingly.
+- **Refusal BDD:** Given no shared premise, no observed same-gate failures or no grant to run the differentiating check, when another same-premise fix is proposed, then cite the two actual failed attempts if they exist, name the absent evidence, mark the test `unrun` and do not invent a failure, proof, worker or permission.
+
+Temporary Pi skill discovery is not the premise test.

package/skills/principle-boundary-discipline-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-boundary-discipline-pi
+description: Place validation and error handling at real CLI, config, network or external API boundaries, while keeping trusted domain logic simple. Use explicitly when shaping an approved adapter or validation change.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Boundary discipline
+
+Adapted from Lauren Tan's `principle-boundary-discipline` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. This is a code-organization method, **not** a claim that types or a lease enforce runtime containment.
+
+First draw the **actual** boundary: CLI arguments, config reads, external API responses, network messages, file formats or another outside input. At entry, validate and narrow into a domain value or reject with an actionable error. Expose domain concepts rather than passing raw transport/storage/framework types into the public domain API. Keep general mechanism internal, special-purpose policy at the edge, and the framework shell thin. Within code that receives genuinely validated domain values, remove redundant re-validation and keep business transforms and scoring pure where possible. Ask at each guard, “Is this crossing a real boundary **now**?” and at each framework-heavy function, “Can a pure function do the domain work?” Validate config when parsed, not deep inside its consumers.
+
+**Trust is conditional:** prove all relevant external entry points actually parse the value before removing a guard. Types, compiler checks and function-local assumptions do not establish authority, safe filesystem paths or protection from malicious outside data. Do not strip a load-bearing safety check or soften a denial in the name of reducing noise. Handle invalid input at the real entry and test both an accepted domain value and a rejected outside value before calling the reshape safe. Unknown call paths or insufficient edit grant leave the existing check intact with an evidence gap.
+
+- **Positive BDD:** Given an approved adapter and identified untrusted entry, when Pi traces calls and tests valid/invalid input at that entry, then parse-time errors and a pure domain path replace proved redundant inside guards without weakening the outside denial.
+- **Refusal BDD:** Given an unverified caller, external input still reaching the inner function or a safety guard without equivalent boundary proof, when a deletion is proposed, then retain it and mark the proposed simplification `blocked`/`unrun`; do not assume a type is containment.
+
+This skill file does not drive an app or prove a boundary by itself.

package/skills/principle-build-the-lever-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-build-the-lever-pi
+description: For approved non-trivial edits, analysis or verification, including one-off work, build the smallest safe rerunnable tool and prove it against a hand-done unit. Use explicitly when a lever makes work checkable.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Build the lever
+
+Adapted from Lauren Tan's `principle-build-the-lever` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. This is a default **decision** for non-trivial work, not an install, filesystem or worker grant.
+
+Do the first approved unit by hand to discover the actual recipe. Before authoring a new script, function or command, search `pipeline_output/codebase_inventory.jsonl` when this repo has it and inspect prior art; if absent, use authorized code search. State why an existing tool cannot do the work. Choose the smallest rerunnable artifact: a codemod for scoped edits, generator for repeated files, query for analysis, a deterministic check for proof, or a delegate skill with recipe, success/negative check and do-not-touch fence. Keep the contract outside delegates' write scope, give each worker exact allowed files and forbidden effects, and name the loaded role/capacity if workers are needed. A deterministic lever beats hand-applied fan-out: do not delegate units a safe script can cover in one pass.
+
+Run the lever on the first **approved** unit and compare its output byte-for-byte or against named expected observable values from the hand-done result, including a rerun for duplicate/partial effects and one refusal case. Then expand only to the granted paths; a script must not hide an install or cleanup. Give the reviewer the artifact and real output. If the task is only a couple of obvious edits, explicitly decline the lever with the reason; if an existing tool already suffices, reuse it rather than author a duplicate. If the principle is claimed as **applied**, name the actual new or reused executable/check/delegate instruction artifact and its rerun; a plan alone is not a file or a run. Durable private evidence can be committed only under the owner-approved Git scope. This differs from `principle-encode-lessons-in-structure-pi`, which makes recurring errors structurally impossible, and `principle-prove-it-works-pi`, which verifies the finished user result; read those actual loaded leaves before citing them.
+
+- **Positive BDD:** Given non-trivial authorized work, even a one-off, when Pi compares a hand unit with a safe rerunnable scoped lever and repeats it, then the output agrees, the artifact is reviewable and the work can be checked again without a manual replay.
+- **Refusal BDD:** Given no authorized write/runtime, an already adequate tool or a couple of obvious edits visible at a glance, when new automation is considered, then reuse or decline it with the reason and `blocked`/`unrun` where applicable, without hidden package install, unapproved fan-out or fabricated rerun evidence.
+
+A discovered Pi skill is not an executable lever test.

package/skills/principle-encode-lessons-in-structure-pi/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: principle-encode-lessons-in-structure-pi
+description: When an approved team repeats an instruction or correction, make the rule enforceable in structure if possible; keep a prominent example if judgment is irreducible. Use explicitly for a proved repeated failure.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Encode lessons in structure
+
+Adapted from Lauren Tan's `principle-encode-lessons-in-structure` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. Unlike `principle-build-the-lever-pi`, which builds a rerunnable work artifact, this method makes a **repeated rule** hard to violate in future work.
+
+When the same instruction needs writing twice or a correction recurs, cite the observed occurrences and name the failure class. Look for the **smallest** authorized structural enforcement point in the actual repo: a domain shape, metadata flag, lint, type, runtime boundary check or test/script. Reuse existing checks before writing another. Make an approved historical bad case fail with an actionable message, then a correct case pass, and verify the actual entry where the rule matters. Do not add global hooks or hooks that intercept unrelated commands for a speculative recurrence. If a structural fix fully handles the issue, **use it alone**, not a redundant instruction alongside it; the text was the symptom. If judgment cannot be encoded without false positives or a missing product choice, make the instruction prominent, add one concrete failure example and say why no mechanical enforcement is safe. Work within the authorized paths; a principle does not approve hook installation, CI mutation, a broad history scan or a new board card.
+
+- **Positive BDD:** Given two evidenced instances of a repeated error and an approved enforcement seam, when Pi adds the smallest reusable structural check and exercises old-bad and correct inputs at the real entry, then the bad path fails, the good path passes, and no duplicate rule text is needed.
+- **Refusal BDD:** Given a single anecdote, an uncertain rule or no grant for hooks/CI/runtime effects, when structural enforcement is considered, then leave the app unchanged, name the missing proof/grant and offer only a bounded judgement instruction with a real example when warranted; mark an unrun enforcement check `unrun`.
+
+An independently reviewed draft skill is not a deployed guardrail.

package/skills/principle-exhaust-the-design-space-pi/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: principle-exhaust-the-design-space-pi
+description: For a novel UI interaction, architectural fork or feel-dependent product choice with no precedent, compare two or three approved prototypes side by side before committing to a design. Use explicitly for an empirical design fork.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Exhaust the design space
+
+Adapted from Lauren Tan's `principle-exhaust-the-design-space` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. A design claim, a three-option prose list or an AI vote is not a prototype. Look for a codebase precedent first and avoid ceremony when an established solution applies.
+
+When an interaction, architecture or product experience has a genuine unsettled fork, name the observable decision, constraints and approved scratch location. Build **two or three different small, isolated prototypes** that can answer the fork cheaply; they are throwaway evidence, not production code. Compare side by side on the **same authorized surface** with actual observations: working interaction, screenshots for visual choices, behavior or timing for architectural ones. State tradeoffs and recommend the best fit against the user's experience, then ask for an owner decision only where the preference is irreducible. Do not install dependencies, fetch CDN scripts, launch an app, spawn candidates or share a mutable instance merely because this principle names prototypes. If no real prototype route is granted, present the proposed experiment and mark the comparison `unrun`; do not claim a winner from prose alone. Subsequent production implementation belongs to a separately accepted Feature/`architect-pi` route, not this throwaway choice.
+
+- **Positive BDD:** Given a novel approved design fork and safe target, when Pi builds two or three isolated variants and observes them side by side on the same surface, then it recommends a choice with cited comparative artifacts before production code is committed.
+- **Refusal BDD:** Given a known precedent, no safe app/target, shared instance conflict or no scratch/effect grant, when a prototype would cross that boundary, then reuse precedent or mark comparison `blocked`/`unrun`, with no fabricated screenshots, hidden install or automatic feature merge.
+
+Temporary Pi discovery does not prove a prototype comparison.

package/skills/principle-experience-first-pi/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: principle-experience-first-pi
+description: For an approved product, UX or feature-scope tradeoff, prefer the core user experience over implementation convenience and explain impact for users and maintainers. Use explicitly before choosing what to ship.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Experience first
+
+Adapted from Lauren Tan's `principle-experience-first` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. The live `SKILL.md` blob was unchanged from the preserved source pin in the approved census; the installed source body was inspected. A preference for delight is **not** authority to expand a product brief or skip a needed safety check.
+
+When implementation convenience conflicts with the experience that the accepted task serves, name **who consumes the result**: the end user of a UI, the colleague importing a library/internal API, and the engineer who maintains it. Ask what each notices on the real path. Justify every feature, option and control against the central workflow. Prefer fewer polished features to many rough ones, and attend to transitions, alignment, spacing, feedback and error states **when that surface is in scope**. For an unsettled feel-dependent design, use loaded `principle-exhaust-the-design-space-pi` only with authorized prototypes and actual side-by-side observations; otherwise label it a proposed experiment. Foundational thinking chooses the **sequence** of work; experience first chooses the **target**. Neither permits an unapproved redesign. Measure or observe the user-visible tradeoff when safe; report absent app evidence as `unrun`, not delight proved by opinion.
+
+- **Positive BDD:** Given an approved UX or API scope tradeoff with a real user path, when Pi compares a simpler polished core against extra features or developer convenience on that path, then it names which consumers benefit, what was actually observed and the owner-approved choice.
+- **Refusal BDD:** Given no approved product direction, usable target or safe verification surface, when a 'delight' recommendation would widen scope or claim success, then keep the accepted brief, mark the comparison `blocked`/`unrun` and ask for the needed owner call without changing behavior.
+
+This principle file is not a user-experience test or product decision by itself.

package/skills/principle-explain-the-number-pi/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-explain-the-number-pi
+description: Challenge a measured speedup, regression, throughput, latency or eval score before trusting or reporting it. Use explicitly when a number drives an approved decision.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Explain the number
+
+Adapted from Lauren Tan's `principle-explain-the-number` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. A proposed measurement is not authority to launch a benchmark, profile a host, change settings, consume private trial data or publish a claim. `principle-prove-it-works` checks whether an output is real; this principle asks **why the measured magnitude is plausible**.
+
+Before using a number, state the claim, unit, measured work, configuration, comparison, run count and spread. Ask **why not double?** Name the limiting resource or code path using an authorized profile or system counters **observed during a run**, then map the bottleneck to source. Include the load generator: if it saturates first, the tested service is not the demonstrated limiter. A guess based on reading code is not measured limiter evidence. If no authorized measurement exists, label the claimed difference **inconclusive** and the observation `unrun`, rather than inventing a ceiling.
+
+List plausible alternative explanations and rule each out with evidence: errors or timeouts; skipped, lazy or cached work; the target code never executing or its output never consumed; one side left at default settings; noisy trials; or a component too small to affect the user-visible total. Compare the time saved with the changed piece's former share of the full path. A saving larger than that piece took is a measurement problem to investigate, not a speedup to celebrate. Keep the run count, range/spread, observed limiter, units, error/work counts and private evidence pointer beside the number. Do not silently drop failed trials.
+
+For a **performance** claim, use the full reviewed `benchmark-checklist-pi` only when actually loaded; otherwise check its seven source questions directly before a comparison or mark the unanswered questions `unrun`. A single authorized run may be called a **one-run ballpark** only when the user explicitly asks for one and both error and completed-work checks pass; it cannot choose a winner. For an **eval** claim, establish that every trial actually did the task, check whether the gap holds across trials and across **only approved** model routes when a cross-model comparison is in scope, and explain why the scenario matters to users. Never add providers, workers, data reads or repeated trials from this principle alone.
+
+- **Positive BDD:** Given an approved comparable performance or eval measurement with real run evidence, when Pi tests the proposed number against limiter observations, alternative explanations, run count, spread and task relevance, then it reports a supported scoped claim or an explicit inconclusive result with cited evidence.
+- **Refusal BDD:** Given missing run count, spread, measured limiter, proof that work completed, comparable configuration or permission to observe, when asked to trust or publish a number, then call the claim `inconclusive` and the missing check `blocked`/`unrun`; do not launch a profiler, invent trials or present a one-run ballpark as a winner.
+
+This reviewed method has not measured a workload or validated a live Pi journey merely because Pi can discover its file.

package/skills/principle-fix-root-causes-pi/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-fix-root-causes-pi
+description: During an approved bug investigation, trace a reproduced symptom to the first wrong decision and correct that decision rather than hiding the failure. Use explicitly before choosing a fix.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Fix root causes
+
+Adapted from Lauren Tan's `principle-fix-root-causes` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. This principle selects the **kind of fix**; the existing `diagnosing-bugs` skill owns the authorized red-capable reproduction and feedback loop. Neither skill grants an app launch, history scan, worker, edit or retry beyond the task contract.
+
+Reproduce the exact symptom at an approved seam **before** forming a cause or changing code. Trace the observed state and error backward, asking “why?” until the answer is the first wrong code decision, not another consequence. If the chain is unclear, use scoped instrumentation to inspect the **actual** state; do not guess from a later stack frame. For a failure that appears after restart, inspect approved persisted config, caches, locks and serialized state first, while respecting data access. State the falsifiable cause and show what observation would contradict it.
+
+Ask whether the state at the failure is **legitimate**. If it can correctly occur, handle it at the code that broke: that guard can be the root-cause fix. If the state must never occur, trace its producer and repair that producer; a catch, retry, clamped value, discarded state or local guard that merely masks the producer is not a fix. Preserve the red-capable behavior check, fix the cause within approved scope, and observe both the minimized check and original scenario turn green. Look for other reachable instances of the **same proved fault** inside the approved paths and verify the repaired pattern; unknown/out-of-scope callers stay reported, not silently rewritten.
+
+If a workaround needs a paragraph-long comment, challenge the workaround rather than writing an explanation for broken behavior. If the decisive fact was hard to uncover, **propose** a cheap always-on signal at the appropriate boundary, with prior-art and effect checks; do not install a global hook or telemetry from this principle. Record genuine negative cases where the new guard must still reject invalid input. An unrun repro, green-only test or changed mock is not evidence of a root-cause fix.
+
+- **Positive BDD:** Given a reproduced approved failure and a red-capable behavioral check, when Pi traces backward to a proved first wrong decision, then an in-scope cause fix (including a legitimate-state handler when appropriate) turns the minimized and original paths green and checks the same fault pattern without hiding errors.
+- **Refusal BDD:** Given no authorized reproduction, inaccessible persisted data, uncertain state legitimacy or an out-of-scope producer, when a masking guard or retry is proposed, then leave that change `blocked`/`unrun`, name the missing observation or grant and do not claim root-cause resolution or sweep other repositories.
+
+Pi discovering this file is not a reproduced bug, an applied fix or a live Pi test.

package/skills/principle-foundational-thinking-pi/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-foundational-thinking-pi
+description: Before approved stateful code, choose domain data shapes, access patterns, shared-state ownership and useful scaffolding so later features stay simple. Use explicitly for a foundational implementation choice.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Foundational thinking
+
+Adapted from Lauren Tan's unchanged `principle-foundational-thinking` body at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. Structural decisions protect future options; local code decisions protect simplicity. This principle does not authorize a redesign, deletion, CI change, worker, commit or broad refactor.
+
+**Shape before logic.** For an approved change, identify the core domain types and data structures first. Trace actual access and update patterns, then choose the shape that serves dominant paths; do not build a generic framework around a hypothetical use. Let types and data models converge, but do not DRY every repeated line: three clear similar statements can beat a premature abstraction. Prefer explicit code, with behavior and edge-case checks instead of line-count targets. If source evidence does not identify the dominant path, record the uncertainty and hold an irreversible shape choice.
+
+**Ownership before sharing.** Name every actor that can mutate each shared state and ask what happens if another actor modifies it concurrently. If the answer is not “nothing”, isolate state/ownership before choosing serialization, a lock or a retry; a Treehouse lease, type or test is not containment. Verify the real concurrent boundary only with an approved test surface; otherwise mark that check `unrun` and do not assert race freedom.
+
+**Sequence for option value.** Examine proved dead code before adding scaffolding, but delete only inside a separately approved scope with caller and compatibility evidence. Put a small shared type, test seam or CI/lint foundation first only when it demonstrably helps the later authorized phases and prior art cannot serve; do not change global CI from this principle alone. Preserve red-capable tests before fixes. Make each approved increment a coherent abstraction or a deepening of one that exists, rather than scattering special cases among callers. Keep any separately authorized commits single-purpose; a draft method never commits by itself. Contrast this with the experience-first principle: foundation selects **when** to build, user experience selects **what** the accepted task serves; read a loaded leaf before citing it as applied.
+
+- **Positive BDD:** Given an approved stateful feature with traced access patterns and concurrent actors, when Pi chooses a core data shape and state owner before feature logic, then a small verifiable unit handles actual dominant and edge paths without distributed special cases or unproved sharing.
+- **Refusal BDD:** Given unknown callers, unmeasured usage, no concurrency check, no deletion/CI grant or an adequate existing foundation, when a new abstraction or scaffold is proposed, then preserve current behavior, mark missing checks `blocked`/`unrun` and do not delete code, alter CI or claim safe concurrency.
+
+Skill discovery does not prove a new data shape, test a race or register a Pi resource.

package/skills/principle-guard-the-context-window-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-guard-the-context-window-pi
+description: When an approved investigation risks oversized outputs, long files or repeated reads, cap each phase and preserve useful evidence without exhausting Pi context. Use explicitly for a large scoped investigation.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Guard the context window
+
+Adapted from the **pinned live** Lauren Tan `principle-guard-the-context-window` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). The live body is shorter than the older installed source: it specifies sizing phases, scope and turn budgets, not a mandatory subagent fan-out or inlining rule. Read `../how/WORKFLOW_BOUNDARIES.md`. Context overflow can degrade reasoning, create compression artifacts and halt work; reducing output volume must not conceal a decisive failure.
+
+When a task will inspect many files, long outputs or repeated evidence, split its **approved scope** into small phases. Before each phase name the question, a bounded file/range list, expected output size, turn/resource budget and what evidence would stop or change the search. Prefer an existing indexed code search for leads if loaded; read only the relevant exact source/ranges for the claim, with stable path/revision pointers. Keep a concise main-thread summary of decisions, contrary evidence and unresolved questions; retain complete raw evidence only in an approved private destination when the task requires it. A summary is not a substitute for checking a load-bearing exact artifact. If output is truncated, fetch a bounded continuation or label the gap; never assert the missing portion was reviewed.
+
+Account for tool, provider and worker costs before requesting a large fan-out. Delegation is **optional**, not the pinned live skill's requirement: only an owner-approved role, data route, capacity and Pi worker tool can delegate an exact read-only slice. Without these, inspect sequentially within budget or stop and request a narrower range; do not silently swap models, search unrelated chats or spill private data to an external summarizer. At each checkpoint revise the next phase from observed evidence, not from volume alone. If essential files or a real check exceed the approved budget, mark the affected conclusion `blocked`/`unrun` and ask for a scoped decision instead of compressing away the gap.
+
+- **Positive BDD:** Given an approved many-file investigation with sufficient budget, when Pi plans bounded ranges and summarizes only verified relevant evidence at each checkpoint, then a reviewer can follow exact paths and contrary findings without raw output flooding the session.
+- **Refusal BDD:** Given missing file/data scope, truncation, worker grant or remaining budget, when a conclusion needs unseen content, then mark it `blocked`/`unrun`, preserve the uncertainty and avoid unapproved fan-out, provider fallback or fabricated completeness.
+
+A discoverable Pi skill is not an executed investigation or a proof that its important files were read.

package/skills/principle-laziness-protocol-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-laziness-protocol-pi
+description: For an approved refactor or proposed new layer, consolidate repeated decisions and choose the smallest behavior-preserving change. Use explicitly before expanding a diff.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Laziness protocol
+
+Adapted from the **pinned live** Lauren Tan `principle-laziness-protocol` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. The live body has only two rules: consolidate decisions and minimize the diff. The older installed source has extra flat-hierarchy and signal-threading advice; do not turn those older thresholds into mandatory Pi rules. Shorter code is a goal only after behavior, compatibility and safety remain intact; line count is a diagnostic, not a veto.
+
+For an approved change, find each place that makes **the same choice**. If these are truly one policy decision, choose the actual owner and compute it once there; pass the result as a simple flag to consumers that need it, instead of duplicating the choice. First check prior art, callers, inputs and effects to avoid creating a new global singleton or leaking policy across a trust boundary. If the decisions have different owners or timing, keep them separate and explain why.
+
+Compare the smallest edit that solves the observed problem with a proposed abstraction, layer or boilerplate. Favor a narrowly scoped reuse or proved deletion over added coordination, but delete only if the task grants it and the real callers/negative paths have been checked. Verify the accepted behavior and the case that must still be rejected at the actual authorized entry. A smaller diff that hides an error, drops an approved feature or weakens a guard fails this principle. Do not remove comments, tests, checks, or evidence just to reduce a count; record why the retained code exists. No automatic commit, PR or merge follows.
+
+- **Positive BDD:** Given an approved refactor with repeated equivalent decisions and an observable behavior test, when Pi centralizes the choice at its proved owner and makes the smallest permitted edit, then the real accepted and rejected paths keep their behavior with less duplicated decision logic.
+- **Refusal BDD:** Given distinct policy owners, unknown callers, no approved deletion/test surface or a safety guard without replacement proof, when a short diff would erase needed behavior, then leave it intact, mark the risky step `blocked`/`unrun` and explain the missing evidence instead of applying a line-count rule.
+
+Pi discovery is not a verified refactor or permission to delete code.

package/skills/principle-make-operations-idempotent-pi/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-make-operations-idempotent-pi
+description: Design an approved state-mutating command or lifecycle step to converge across duplicate runs and crashes by reconciling actual state. Use explicitly before a retriable effect.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Make operations idempotent
+
+Adapted from Lauren Tan's `principle-make-operations-idempotent` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. A convergent design is **not** permission to retry, replay a remote effect, clean another run's files or assume an owner-approved effect grant. This principle applies to commands, lifecycle steps and processing loops that may stop or repeat.
+
+For each proposed state mutation, name the target end state and the actual state it can observe after a partial run. Ask “what if it runs twice?” and “what if the prior run stopped after **each** observable write, claim or send?” Derive each next step from **current state versus desired state**, not from a previous run's intent. Apply only the proved difference, then re-read the real boundary to check convergence. Identify the operation's stable identity and owner; do not turn a transient marker or worker receipt into proof an outside effect did or did not occur.
+
+For every artifact left behind (lock, temporary file, partial record or claimed job), specify evidence of liveness/ownership and a staleness decision valid at **all possible crash points**. Prefer an atomic publish of a prepared file or content comparison when that matches the actual filesystem contract, rather than assuming creation order is authoritative. A marker that cannot be judged after restart requires reconciliation or an explicit hold, not automatic cleanup. An ambiguous network send, shared process or committed external action is **uncertain**, not safe to send again merely because a local record is missing. Reconcile it using an approved read-only target query and explicit idempotency contract, or stop for the owner.
+
+Under an approved isolated test seam, check a normal run, immediate duplicate, and controlled stop/restart at the reachable transition boundaries; require the same final observable state, no extra externally visible effect and no run-owned residue without a supported recovery path. Never inject crashes, repeat real sends or reset shared resources without a separate data/effect/safe-exit grant. If a step's result depends on ambiguous partial state, add a scoped reconciliation step or report the gap as `blocked`/`unrun`, not an invented exactly-once guarantee.
+
+- **Positive BDD:** Given an approved stateful operation, stable identity, observable end state and authorized isolated interruption seam, when Pi compares current with desired state across a normal run, duplicate and partial-run recovery, then all converge to the same observed result with no duplicate external effect or orphaned run-owned state.
+- **Refusal BDD:** Given an ambiguous prior send, unjudgeable stale marker, shared owner or absent crash-test grant, when repetition or cleanup is proposed, then hold the effect `blocked`/`unrun`, name the reconciliation evidence needed and do not replay, delete or claim convergence from a receipt.
+
+This draft skill is not proof of crash recovery, a real duplicate-safe effect or Pi loading.

package/skills/principle-migrate-callers-then-delete-legacy-apis-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-migrate-callers-then-delete-legacy-apis-pi
+description: For an approved internal API replacement without external compatibility obligations, migrate every proved caller and remove the old entry in the same scoped wave. Use explicitly before retaining a legacy adapter.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Migrate callers, then delete legacy APIs
+
+Adapted from Lauren Tan's **pinned live** `principle-migrate-callers-then-delete-legacy-apis` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. The current source is shorter than the older installed version: its description favors a same-wave internal migration over compatibility layers, while its body specifies new-contract tests and three applicability conditions. Do not treat the older source's “delete immediately” wording as a blanket authority to remove a public API.
+
+Apply only after the owner accepts the new internal contract, no external users require the old path, and the project can absorb a coordinated break as part of an approved simplification/refactor. Identify the old API's **actual** callers and compatibility boundary with code search, public/exported surface review and authorized consumers. The absence of local references alone does not prove external users absent. If a consumer or owner is unknown, hold deletion and name the missing check; a code comment or deprecation label is not proof.
+
+Within the accepted wave and file scope, update each proved caller to the new API. Update behavioral tests to assert the new contract, preserve regression/negative cases, and remove only tests that protect **solely** the obsolete implementation details. Run the relevant authorized tests and check real entry points before removing the old internal path; observe whether all approved callers resolve and no needed behavior vanished. If callers cannot be migrated together, report the partial migration and an owner-held bridge decision rather than inventing a permanent compatibility adapter. Delete the old path only with its own explicit edit grant and proved compatibility boundary; an unrun caller path or failing check blocks that step. No automatic public breaking change, PR or merge.
+
+- **Positive BDD:** Given an owner-approved internal replacement with an inventoried closed caller set and no external compatibility dependency, when Pi migrates all scoped callers and tests the new contract at their real entries, then the authorized old entry is removed in the same verified wave without a dual-path implementation or lost negative behavior.
+- **Refusal BDD:** Given unknown/public consumers, an incomplete caller inventory, no deletion grant or failing/unrun compatibility checks, when old-path removal is proposed, then retain the path and label deletion `blocked`/`unrun`; do not delete behavior tests or treat a search miss as proof no one calls it.
+
+This text is not evidence that a migration, test run or Pi resource loading occurred.

package/skills/principle-minimize-reader-load-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-minimize-reader-load-pi
+description: For an approved hard-to-trace code change, reduce the layers and mutable state a reader must track without erasing useful boundaries. Use explicitly during a scoped maintainability review.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Minimize reader load
+
+Adapted from Lauren Tan's `principle-minimize-reader-load` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. Reader load has **two independent axes**: layers between a question and its answer, and hidden/mutable state a reader must hold. A flat module with many globals can be as hard as many pass-through adapters. LOC, cyclomatic complexity and an architecture label are proxies, not automatic rejection thresholds. This is the human counterpart of `principle-guard-the-context-window-pi` **only when that actual Pi leaf is loaded**.
+
+Pick an approved concrete reader question: “Where does this value come from?” and “What can change it?” Trace from the actual entry through each layer and owner. Use the source's **under-30-second new-reader test** as a diagnostic, not as an invented hard gate: show the question, observed path and what made it hard. Inspect all relevant callers and external boundaries before proposing to collapse a one-caller wrapper, an adapter with no second implementation, or an unnecessary speculative/pass-through layer. Keep a layer that genuinely changes abstraction, compresses a broad interface into a meaningful decision, or owns a security/error boundary. A layer with identical methods and arguments but no added invariant is a candidate to inline only when the task grants the edit and caller/behavior checks prove equivalence.
+
+Trace mutable state separately: favor returns over mutation and local values over fields, fields over module state and module state over globals when that ordering actually serves ownership. Derive a value instead of synchronizing copies if the real update path permits it. State an invariant once at the validated boundary rather than duplicating its explanation in each consumer; do not remove a guard while outside callers can still bypass validation. Before adding a layer or state, explain how it saves at least as much reader work elsewhere; if not, keep the simpler path. Verify the original behavior and failure/invalid-input path at the authorized real entry after an edit. If no edit or runtime grant exists, give the traced map and an unrun simplification proposal, not a claim that maintainability improved.
+
+- **Positive BDD:** Given an approved change with a traced reader question, caller map and behavior seam, when Pi removes proved pass-through indirection or reduces mutable scope, then a reader can follow the actual owner/change path more directly and real valid/invalid behavior remains unchanged.
+- **Refusal BDD:** Given unknown callers, an unverified validation/security boundary, a layer that hides necessary policy or no edit/check grant, when an inlining or state reduction is proposed, then retain the boundary and mark the candidate `blocked`/`unrun`; do not trade a safety invariant for fewer lines.
+
+Skill discovery or source inspection alone is not a real reader study, applied simplification or the Pi session-loaded route.

package/skills/principle-model-the-domain-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-model-the-domain-pi
+description: When approved stateful logic adds branching or repeats shape assumptions, choose a data structure that expresses valid domain states and ownership. Use explicitly before another lifecycle branch.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Model the domain
+
+Adapted from Lauren Tan's `principle-model-the-domain` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. A domain structure should remove invalid representable states, duplicated rules or scattered lifecycle branches, not merely add an abstraction. Types do not validate untrusted runtime input or grant a migration outside approved scope.
+
+Before adding another `if` branch, synced boolean or phase-specific copy of a rule, identify the **real domain invariant**, legal transitions, writers and reads at the approved entry. Trace the existing shape across authorized callers. Choose the smallest structure that fits actual access: a state machine for phases, a typed/discriminated model for variants, a map/lookup for repeated decisions, a reducer or command/event model for mutations, a small module owning one body of domain knowledge, or a queue/cache/index/graph/tree/normalized collection only where observed access justifies it. These are candidates, not a checklist or automatic registry. If none fits, first list what must never occur and how the data is read, then design to encode that. Organize by **domain ownership**, not merely by execution order (load → validate → transform → save), which can repeat the same rules in each phase.
+
+Compare the proposed structure against the existing boring code: does it actually remove branches, duplicated rules, invalid states or lifecycle risk without hiding a needed security boundary? An already clear, local and stable shape should stay. Validate outside data at its actual entry; prove callers and valid/invalid transitions before removing runtime guards. Check an authorized behavior seam with one accepted transition and one illegal state/transition, including persistence/restart if that is part of the granted domain. Do not equate a type declaration, mock or state-diagram sketch with runtime proof. If the edit/migration grant or real check is missing, offer an evidenced design only and mark implementation/test `blocked`/`unrun`.
+
+- **Positive BDD:** Given an approved stateful change with repeated shape assumptions and a reachable real input path, when Pi models the domain's legal transitions in the smallest justified structure, then approved accepted and rejected transitions preserve observable behavior while invalid combinations and scattered duplicate decisions are reduced.
+- **Refusal BDD:** Given a stable clear shape, an unverified external caller, an untrusted entry lacking runtime validation or no migration/check grant, when a new registry/type or guard deletion is proposed, then retain the existing behavior, label the unsafe step `blocked`/`unrun` and do not claim that types alone enforce the boundary.
+
+This skill's existence is not a real state-machine test, a migration or the Pi session registration.

package/skills/principle-never-block-on-the-human-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-never-block-on-the-human-pi
+description: When an approved task has routine reversible choices, keep making scoped progress and show the result instead of requesting approval for each small step. Use explicitly when a question would stall execution.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Never block on the human
+
+Adapted from Lauren Tan's `principle-never-block-on-the-human` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. The human supplies product direction and the actual task contract; this principle cannot turn a missing grant into permission. Reversibility means a scoped change can be reviewed and corrected, not that a private-data read, network effect or cleanup becomes harmless.
+
+Within an accepted goal, paths, data/effect route and stopping point, choose routine reversible implementation details yourself: write scoped code or notes, split already approved session work into verifiable units, run permitted local checks and show the result with a reason. Do not interrupt the owner with “should I do X?” for every ordinary edit. Keep the smallest safe exit and a falsifiable check in view. If a local observation shows a problem, record the actual failure in the approved private trail and correct it in the next **authorized** unit; no automatic background scheduler, new board card, silent replay or speculative fix follows from “self-healing”.
+
+Separate owner-held direction from execution. Ask for a decision when acceptance/product behavior changes, scope or access is missing, a safety constraint conflicts, a negative check fails without a permitted correction, or an action is irreversible (force push, production deletion, external message) and lacks its own exact approval. Continue independent reversible work **within the grant** while that choice waits; do not make the owner-held choice by default. If no safe independent unit remains, stop with the precise blocker and evidence, rather than mislabelling an unrun path done. Even when a push or PR is expressly authorized, verify its specific destination and outgoing content; no merge is implied.
+
+- **Positive BDD:** Given an approved task with several ordinary reversible units and a defined stop, when Pi makes a scoped implementation choice, checks it and presents its result without repeated permission requests, then accepted work advances and genuine owner decisions remain explicit.
+- **Refusal BDD:** Given missing product direction, data/effect access, safe exit or approval for an irreversible act, when the next step needs that boundary, then do only independent approved work or mark it `blocked`/`unrun`; do not force-push, delete, send, merge or invent authority from this principle.
+
+Reading this skill does not authorize unattended execution, the Pi session registration or a completed user journey.

package/skills/principle-outcome-oriented-execution-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-outcome-oriented-execution-pi
+description: For an approved phased rewrite or migration, aim for a verifiable final architecture rather than accumulating temporary compatibility layers. Use explicitly when planning accepted transition checkpoints.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Outcome-oriented execution
+
+Adapted from Lauren Tan's unchanged `principle-outcome-oriented-execution` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. This is a planning and sequencing principle, not permission to break a deployed service, public API, shared branch or another user's workflow. An incomplete migration must not be presented as verified product functionality.
+
+For an **approved planned rewrite or migration**, name the desired final architecture and its real, observable completion predicate. Break the work into declared phases with owner-approved paths, safe exit and checks. State precisely **where temporary breakage is acceptable**, who owns that surface, how it will be observed, and when it must be resolved. Prefer a reversible, isolated intermediate state that reaches the end state over a throwaway compatibility layer that may outlive the transition. End-state integrity takes precedence over keeping every internal interim step green **only within the explicitly accepted boundary**. An undeclared runtime, customer or security failure is not a planned transition.
+
+Keep high-signal checks on actively touched code during each phase, recording which checks intentionally remain red and why, rather than deleting the tests or changing the oracle. At each boundary inspect the actual changed artifact and fix unexpected breakage before the next unit. At plan completion require the **full relevant static and real runtime/user-path checks** before declaring the migration done. If no approved runtime entry or safe target exists, report completion `blocked`/`unrun` even when unit checks pass; do not paper over this with an adapter or self-report. A safety guard, external compatibility contract or owner-held merge/push gate is not expendable merely because the target design is simpler.
+
+- **Positive BDD:** Given an approved phased migration with a declared isolated breakage window and actual final-state checks, when Pi sequences changes toward the target and checks each affected boundary, then the final static and runtime observations satisfy the initial predicate without leftover temporary compatibility code.
+- **Refusal BDD:** Given undeclared breakage, a shared/public path, missing owner direction, safe exit or runtime check, when a phase would disrupt that surface or claim completion, then retain the existing contract, mark the affected phase `blocked`/`unrun` and do not merge, disable tests or claim the intended outcome.
+
+Explicit Pi discovery is not a completed migration, live runtime proof or the Pi session skill registration.

package/skills/principle-prove-it-works-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-prove-it-works-pi
+description: Before declaring an approved task done, check the actual output, value or feature at its real entry rather than trusting proxies or an agent report. Use explicitly for a completion claim.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Prove it works
+
+Adapted from Lauren Tan's `principle-prove-it-works` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. This is the direct-artifact completion rule, not permission to start an app, instrument a host, install a verifier, write to an unapproved evidence location or mark a task done. The existing `verify-journey` skill details user-facing BDD drives when that method is actually loaded and the target/effects are approved.
+
+Before saying done, name the **real output** and the owner's observable pass/fail predicate. Check that output directly at the approved entry: inspect the actual changed value or Git diff, exercise the real feature if its target is granted, and check process liveness at the process rather than a derived status. A file mtime, fresh-looking output, cached screenshot, passing compile, worker receipt or self-report is a lead, not the result. Compare the observed value to an independent expected value, not to the same algorithm's echo. When verification fails or passes implausibly easily, first challenge the observation method and make sure the check reached the target; then diagnose the product if the measurement seam is sound. Record both consequential accepted and refusal paths where the task requires them.
+
+Where an approved, deterministic check is practical, prefer a rerunnable script or existing harness over a one-off eyeball: inspect inventory/prior art before new code, run it against a known good and bad case if possible, and retain its exact output as a reviewable private artifact. **Do not author a script merely to assert its own output**, hide an install, or run effects outside the task. Keep evidence visible to the owner. Commit a check/evidence artifact only for large or complex work where an audit trail is warranted **and the Git scope is separately approved**; ordinary verification does not self-commit. If a real target or effect grant is absent, show what source/static checks ran and label the live claim `blocked`/`unrun`, not verified.
+
+- **Positive BDD:** Given an approved completed task, real target and independent expected result, when Pi observes the actual output or user-path behavior and rechecks it through a meaningful rerunnable seam, then the completion claim cites the exact artifact and successful accepted/refusal observations rather than proxies.
+- **Refusal BDD:** Given only a compile, fixture, cached view, receipt, inaccessible real entry or unapproved effect, when completion is requested, then identify the missing direct check, mark the real path `blocked`/`unrun` and do not invent a pass, run an app, commit evidence or declare owner acceptance.
+
+A source-inspected or discoverable skill is not a live Pi verification journey.

package/skills/principle-redesign-from-first-principles-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-redesign-from-first-principles-pi
+description: When an approved new requirement changes an existing design invariant, reason from that requirement as if it had been foundational and propagate its consequences. Use explicitly before an architectural bolt-on.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Redesign from first principles
+
+Adapted from Lauren Tan's `principle-redesign-from-first-principles` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. A redesign thought experiment does **not** grant a broad rewrite, public-document edit, worker fan-out or a new owner decision. Distinguish this from challenging a failed assumption: here an **accepted new requirement** changes the intended design.
+
+Read the affected design, entry points, callers and contracts **within the granted repository/data range**. State the original invariant, the new accepted requirement and their conflict. Ask: “If this new requirement had been foundational, what design would we choose?” Compare the resulting domain shape, ownership and boundary to a local bolt-on and to the current design; name what the existing design already does well. Trace the chosen change through all relevant **approved** references: types, code, tests, documentation, examples and rationale/decision sections. Do not update public docs with private rationale or silently widen the approved file scope. If an affected reference is inaccessible, name it and hold the affected completion claim rather than assert full propagation.
+
+Think through the whole resulting shape and its compatibility/one-way-door costs **before editing**, then implement only owner-approved small, independently checkable increments toward it. Keep behavior-level checks for both the accepted requirement and existing supported paths; a speculative rewrite that merely relocates code is not a first-principles outcome. Where the task settles only a design proposal, stop at that proposal with evidence and owner-held choices. If no grant covers a needed migration, do not bolt on an unsafe interim adapter or claim the final design already exists; mark that phase `blocked`/`unrun`.
+
+- **Positive BDD:** Given an owner-accepted new requirement that changes a proved invariant and accessible affected references, when Pi compares a from-scratch design with a bolt-on and propagates the chosen scoped design in verifiable increments, then approved tests and real entry observations support both the new behavior and retained compatibility without divergent assumptions.
+- **Refusal BDD:** Given no accepted design direction, incomplete affected-file access, missing edit/runtime scope or an unapproved public documentation path, when a broad redesign or completion claim is proposed, then provide only an evidence-backed design option, mark affected work `blocked`/`unrun` and leave owner-held choices intact.
+
+A reviewed principle draft does not mean a production redesign, deployment or live Pi test happened.

package/skills/principle-separate-before-serializing-shared-state-pi/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-separate-before-serializing-shared-state-pi
+description: When approved concurrent actors may write one file, branch, key or object, separate their write ownership before choosing a lock. Use explicitly when diagnosing shared-state races.
+disable-model-invocation: true
+license: MIT; see ../how/LICENSE
+---
+
+# Separate before serializing shared state
+
+Adapted from Lauren Tan's `principle-separate-before-serializing-shared-state` at `cursor/plugins@99743e9c151c8537cbbf1f98bb38f34ef3368453` (MIT). Read `../how/WORKFLOW_BOUNDARIES.md`. Instructions like “don't both write” are not synchronization. A Treehouse lease reserves a worktree, not process containment or exclusive ownership of an external state object; a reviewed principle grants no lock installation, worker fan-out or mutation of a trusted shared writer.
+
+Map the actual concurrent actors and the mutable objects they read/write: files, branches, keys, API definitions, database records and task state. Identify each writer, the canonical owner and a plausible interleaving. First ask whether the actors **need the same object** or merely publish independent facts. If facts are independent, give each actor an owned file, key, branch or state directory and combine only at an approved read/reporting boundary. Two actors writing different fields of one `state.json` still share one mutation target; independent `indexer-state.json` and `metrics-state.json` do not. Verify ownership and merge semantics, not just distinct filenames.
+
+Only if one shared write target is a proved domain invariant, choose a **structural** serialization mechanism appropriate to the actual store: exclusive owner/single-writer actor, ordered phases, lockfiles with robust stale-owner handling, or atomic compare-and-swap where supported. Before adding a lock, state why ownership separation fails, how the real process/store makes exclusion enforceable, what happens after a crash, and how competing writes are rejected. Do not duplicate or bypass a trusted board writer/claim service with a local lock or convention. Test an approved conflicting interleaving and recovery at the real boundary, including that the loser cannot silently overwrite the winner; if no safe concurrent test is granted, label the concurrency conclusion `unrun` instead of asserting isolation.
+
+- **Positive BDD:** Given two approved actors writing related state, when Pi gives independent facts separate write targets and merges at a read boundary, or serializes a proved canonical target using its actual trusted owner, then controlled concurrent writes retain both intended facts without a lost update.
+- **Refusal BDD:** Given unknown writer ownership, an unproven need to share, a lease mistaken for a lock or no grant for a concurrent test, when a shared mutable write is proposed, then hold that change `blocked`/`unrun`; do not rely on agent instructions, blindly add locks or claim race freedom.
+
+Skill discovery is not a concurrent write test or proof of process isolation.