ultimate-pi 0.18.1 → 0.19.1

package/.pi/skills/engineering/complexity-control/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: complexity-control
+description: Reduce accidental complexity while preserving essential behavior. Use when code becomes hard to reason about, branches multiply, abstractions feel premature, or a simple feature is spreading across many files. Focuses on explicitness, concept deduplication, and avoiding clever generic designs.
+---
+
+# Complexity Control
+
+Use this skill to make the simplest correct change.
+
+## Distinguish complexity types
+
+- Essential complexity: required by the domain, correctness, scale, security, or compatibility.
+- Accidental complexity: introduced by unclear structure, duplication, premature abstraction, hidden state, or over-generalization.
+
+## Workflow
+
+1. State the problem in one sentence.
+2. Identify the minimum concepts needed to solve it.
+3. Remove duplicate representations of the same concept.
+4. Prefer straightforward control flow over clever indirection.
+5. Add abstraction only after it clarifies repeated behavior or protects a real boundary.
+6. Document unavoidable complexity near the code that needs it.
+7. Verify that the final code has fewer paths a maintainer must simulate mentally.
+
+## Warning signs
+
+- Generic names with no domain meaning.
+- Configuration that controls unrelated behaviors.
+- Multiple sources of truth.
+- Deep nesting or long chains of callbacks/handlers/coordinators.
+- Abstraction introduced for a single use without a clear boundary.

package/.pi/skills/engineering/defensive-programming/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: defensive-programming
+description: Add robustness at trust boundaries and failure-prone code paths. Use when handling external input, persistence, IO, configuration, user data, inter-process calls, events, commands, or invariants. Guides validation, explicit failures, diagnostics, and invalid-state prevention.
+---
+
+# Defensive Programming
+
+Use this skill when code must survive bad inputs, partial failures, or violated assumptions.
+
+## Boundary checks
+
+Validate at trust boundaries:
+
+- user or caller input
+- configuration and environment
+- serialized data
+- storage reads
+- network/process responses
+- event/message payloads
+- plugin or extension inputs
+
+## Workflow
+
+1. Identify trusted and untrusted data.
+2. State required invariants and preconditions.
+3. Normalize or reject invalid input at the boundary.
+4. Fail explicitly with useful diagnostics.
+5. Preserve causal context while avoiding secret leakage.
+6. Make invalid states unrepresentable where practical.
+7. Add tests for malformed, missing, boundary, and contradictory inputs.
+
+## Guidelines
+
+- Do not silently coerce ambiguous data.
+- Do not swallow errors without observability.
+- Distinguish programmer errors from recoverable runtime errors.
+- Prefer clear guard clauses over deeply nested defensive logic.
+- Keep validation close to where trust changes.

package/.pi/skills/engineering/dependency-management/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: dependency-management
+description: Prevent dependency sprawl and risky coupling to third-party or shared code. Use when adding, upgrading, replacing, or wrapping dependencies, libraries, tools, plugins, shared utilities, or platform services. Encourages reuse, isolation, compatibility checks, and lockfile discipline.
+---
+
+# Dependency Management
+
+Use this skill before introducing or changing a dependency.
+
+## Decision workflow
+
+1. Check whether the project already has an equivalent dependency or local utility.
+2. Decide whether the task needs a dependency or simple local code is safer.
+3. Evaluate maintenance, license, security, size, compatibility, and operational risk.
+4. Isolate third-party APIs behind a local boundary when they affect core code.
+5. Keep dependency updates scoped and explain lockfile changes.
+6. Add tests around behavior that depends on external packages or services.
+
+## Guidelines
+
+- Do not add dependencies for trivial transformations.
+- Avoid leaking vendor-specific types across domain or public boundaries.
+- Prefer stable, actively maintained dependencies already accepted by the project.
+- Treat major upgrades as behavior-risk changes.
+- Document why the dependency is needed when the choice is non-obvious.
+
+## Verification
+
+Run dependency-aware checks available in the project: install/lockfile validation, tests, build, security audit, or compatibility checks as appropriate to risk.

package/.pi/skills/engineering/domain-modeling/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: domain-modeling
+description: Model business rules and domain concepts clearly. Use when adding features with domain behavior, invariants, workflows, policies, state transitions, commands, queries, or user/business terminology. Helps agents place rules correctly and avoid data-bag implementations.
+---
+
+# Domain Modeling
+
+Use this skill when correctness depends on business meaning, not just data movement.
+
+## Workflow
+
+1. Extract domain language from requirements, existing code, tests, and docs.
+2. Identify core concepts, actors, actions, policies, and invariants.
+3. Distinguish commands that change state from queries that observe state.
+4. Place invariants in the domain/core path, not only in UI or transport boundaries.
+5. Represent meaningful values explicitly rather than passing ambiguous primitives everywhere.
+6. Keep persistence and transport concerns separate from domain decisions.
+7. Test domain rules directly where possible.
+
+## Modeling prompts
+
+- What must always be true?
+- What state transitions are allowed or forbidden?
+- Who is allowed to perform this action?
+- What terms does the business use for this concept?
+- Is this a rule, a calculation, a workflow, or mere data storage?
+
+## Avoid
+
+- Anemic data containers when behavior has rules.
+- Duplicating the same rule in multiple adapters.
+- Naming domain concepts after technical implementation details.

package/.pi/skills/engineering/error-handling/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: error-handling
+description: Design predictable, debuggable error behavior. Use when adding or changing failure paths, retries, validation, IO, service calls, event handling, command handling, or user-facing errors. Classifies errors, preserves causes, avoids secret leaks, and separates internal diagnostics from external messages.
+---
+
+# Error Handling
+
+Use this skill when a change can fail or when existing failure behavior is unclear.
+
+## Error classes
+
+Classify failures before coding:
+
+- validation: caller supplied invalid data
+- domain: business invariant rejected the action
+- authorization: actor lacks permission
+- not found/conflict: state does not match expectation
+- infrastructure: storage, network, filesystem, process, or dependency failed
+- transient: retry may succeed
+- programmer: bug or violated internal invariant
+- unknown: unexpected and should be surfaced with diagnostics
+
+## Workflow
+
+1. Identify who needs to act on the error: caller, user, operator, or developer.
+2. Choose error shape consistent with the codebase.
+3. Preserve cause/context for diagnostics.
+4. Expose only safe, actionable messages externally.
+5. Retry only if the operation is safe or idempotent.
+6. Add tests for expected failure paths.
+
+## Avoid
+
+- Catch-all handlers that hide defects.
+- Retrying non-idempotent operations without safeguards.
+- Logging secrets or private data.
+- Returning success with partial hidden failure.

package/.pi/skills/engineering/legacy-code-seams/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: legacy-code-seams
+description: Safely change hard-to-test legacy code. Use when code has hidden side effects, weak tests, global state, large routines, unclear ownership, or risky dependencies. Focuses on seams, characterization tests, dependency isolation, and avoiding clean rewrites.
+---
+
+# Legacy Code Seams
+
+Use this skill to modify legacy code without destabilizing unknown behavior.
+
+## Principles
+
+- Preserve current behavior until a deliberate behavior change is requested.
+- Add tests around observed behavior before restructuring.
+- Introduce seams at dependency boundaries rather than rewriting internals first.
+- Prefer wrapping, extracting, and adapting over large replacement.
+
+## Workflow
+
+1. Identify the change point and affected behavior.
+2. Find seams: parameters, interfaces, facades, adapters, configuration, entrypoints, or file/module boundaries.
+3. Add characterization tests for the behavior you will touch.
+4. Isolate hard dependencies such as time, randomness, storage, network, process state, or environment.
+5. Make the requested change through the seam.
+6. Keep legacy compatibility until callers and tests prove it can be removed.
+
+## Avoid
+
+- Large rewrites justified only by code quality.
+- Changing multiple responsibilities while fixing one bug.
+- Deleting strange behavior without proving it is unused.
+- Assuming undocumented behavior is accidental.
+
+## Verification
+
+Use regression tests, golden examples, focused integration checks, and diff review to prove intended behavior changed and adjacent behavior stayed stable.

package/.pi/skills/engineering/naming-and-intent/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: naming-and-intent
+description: Improve readability through precise names and explicit intent. Use when adding functions, modules, variables, commands, events, errors, tests, or docs. Encourages domain vocabulary, side-effect clarity, consistency, and avoiding vague helper/manager/data names.
+---
+
+# Naming and Intent
+
+Use this skill when names carry meaning for future maintainers.
+
+## Naming rules
+
+- Prefer domain vocabulary already used by the project.
+- Name by purpose and behavior, not implementation accident.
+- Make side effects visible in command/action names.
+- Use consistent terms for the same concept.
+- Avoid vague names such as manager, helper, util, data, info, item, or handler unless the surrounding code gives them precise meaning.
+- Do not rename broadly unless the task is a rename/refactor and verification is available.
+
+## Workflow
+
+1. Identify the concept's role in the domain or system.
+2. Search nearby code/docs for existing vocabulary.
+3. Pick names that distinguish similar concepts.
+4. Ensure tests describe behavior, not implementation detail.
+5. Re-read changed code as a sentence: intent should be clear without comments.
+
+## Comments
+
+Use comments to explain non-obvious why, invariants, tradeoffs, and constraints. Do not comment what the code already states clearly.

package/.pi/skills/engineering/refactoring-safe-evolution/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: refactoring-safe-evolution
+description: Refactor code without changing observable behavior. Use when improving structure, extracting abstractions, simplifying code, or modernizing internals while preserving existing contracts. Guides characterization, small mechanical steps, reversible edits, and verification after each phase.
+---
+
+# Refactoring for Safe Evolution
+
+Use this skill when the goal is better structure, not new behavior.
+
+## Preconditions
+
+- Identify the observable behavior that must remain unchanged.
+- Identify public contracts, persistence formats, events, commands, and integration points.
+- If behavior is unclear, add characterization tests before changing structure.
+
+## Workflow
+
+1. State the refactoring goal and explicit non-behavioral scope.
+2. Capture current behavior with existing tests, characterization tests, or executable examples.
+3. Make one mechanical transformation at a time: extract, rename, move, inline, split, or isolate.
+4. Keep old and new paths equivalent during transitions when possible.
+5. Run targeted checks after each meaningful step.
+6. Remove temporary compatibility code only after callers are migrated and verified.
+
+## Safe transformations
+
+- Extract pure logic from side-effecting code.
+- Move code behind an existing interface/facade.
+- Rename with all call sites updated atomically.
+- Split large routines by responsibility.
+- Replace duplicated logic with a single well-named concept.
+
+## Stop conditions
+
+Stop and ask or report risk if the refactor requires contract changes, data migration, broad formatting, new dependencies, or behavior you cannot characterize.

package/.pi/skills/engineering/routine-function-design/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: routine-function-design
+description: Design clear routines, functions, methods, or procedures. Use when adding or restructuring executable units. Guides single purpose, parameter discipline, pre/postconditions, command-query separation, nesting control, and side-effect clarity in a language-agnostic way.
+---
+
+# Routine / Function Design
+
+Use this skill when creating or changing a callable unit.
+
+## Design checklist
+
+- One clear purpose.
+- Name communicates the result or action.
+- Parameters are minimal and cohesive.
+- Preconditions and postconditions are explicit or obvious.
+- Side effects are intentional and visible.
+- Return shape is predictable.
+- Error behavior matches caller expectations.
+- Nesting and branching stay readable.
+
+## Workflow
+
+1. Decide whether the routine is a command, query, calculation, policy, coordinator, or adapter call.
+2. Keep pure calculations separate from IO and mutation where practical.
+3. Pass cohesive concepts instead of long unrelated parameter lists.
+4. Extract nested decision logic only when the extracted name adds meaning.
+5. Test edge cases around boundaries and invariants.
+
+## Avoid
+
+- Boolean flags that create multiple hidden behaviors.
+- Hidden reliance on global or ambient state.
+- Routines that both decide policy and perform unrelated IO.
+- Clever compression that obscures intent.

package/.pi/skills/engineering/small-change-discipline/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: small-change-discipline
+description: Keep coding-agent edits surgical and reversible. Use when implementing any code change, bug fix, refactor, or cleanup where scope control matters. Enforces inspect-before-edit, minimal diffs, existing style preservation, unrelated-issue isolation, and targeted verification.
+---
+
+# Small Change Discipline
+
+Use this skill to keep implementation work narrow, understandable, and safe.
+
+## Operating rules
+
+1. Restate the requested behavior and the exact files/areas likely affected.
+2. Inspect existing code before editing. Do not infer conventions from memory.
+3. Change the fewest files and smallest code regions that satisfy the request.
+4. Preserve existing naming, formatting, layering, and error-handling style unless the task requires changing them.
+5. Do not mix feature work, refactoring, formatting, dependency updates, and cleanup in one change unless explicitly requested.
+6. If you discover unrelated defects, report them separately instead of fixing them opportunistically.
+7. Prefer targeted verification over broad slow checks unless risk requires broader coverage.
+
+## Workflow
+
+1. Identify the requested outcome and non-goals.
+2. Locate the smallest existing extension point.
+3. Make the minimal implementation change.
+4. Add or update only tests/docs directly tied to the behavior.
+5. Review the diff for accidental broadening.
+6. Run the narrowest useful checks.
+
+## Self-check
+
+- Did I edit only files needed for the request?
+- Did I preserve existing public contracts unless asked to change them?
+- Did I avoid drive-by cleanup?
+- Can each changed line be explained by the user request?
+- Did verification match the risk of the change?

package/.pi/skills/lsp-navigation/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: lsp-navigation
+description: Navigate code with IDE features and run proactive LSP diagnostics on files/folders/batches. Use as PRIMARY for code intelligence and type/error checks.
+---
+
+# LSP Navigation and Diagnostics
+
+Use `lsp_navigation` as **PRIMARY** for code intelligence. Use `lsp_diagnostics` as **PRIMARY** for proactive type/error checks on files, folders, or explicit batches. Do NOT use grep/glob/ast-grep first for code intelligence or diagnostics.
+
+**Requires:** `--lens-lsp` flag
+
+## When to Use Diagnostics
+
+Use `lsp_diagnostics` before builds/tests or after touching several files:
+
+| Need                        | Tool call                                                                  |
+| --------------------------- | -------------------------------------------------------------------------- |
+| Check one file              | `lsp_diagnostics({ filePath: "src/file.ts" })`                             |
+| Check a folder              | `lsp_diagnostics({ filePath: "src/", severity: "error" })`                 |
+| Check exact touched files   | `lsp_diagnostics({ filePaths: ["src/a.ts", "src/b.ts"], concurrency: 8 })` |
+| Give slow servers more time | `lsp_diagnostics({ filePaths: files, waitMs: 2000 })`                      |
+| Show warnings too           | `lsp_diagnostics({ filePaths: files, severity: "all" })`                   |
+
+Prefer explicit `filePaths` batches after multi-file edits: they are bounded-concurrency and avoid unrelated directory noise.
+
+## When to Use Navigation (Code Intelligence)
+
+| Question                                | Operation                                | Parameters                                                                    |
+| --------------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------- |
+| "Where is this defined?"                | `definition`                             | filePath, line, character                                                     |
+| "Find all usages"                       | `references`                             | filePath, line, character                                                     |
+| "What type is this?"                    | `hover`                                  | filePath, line, character                                                     |
+| "Show call signature here"              | `signatureHelp`                          | filePath, line, character (at call-site args)                                 |
+| "What symbols in this file?"            | `documentSymbol`                         | filePath                                                                      |
+| "Find symbol across project"            | `workspaceSymbol`                        | query + **filePath strongly recommended**                                     |
+| "What quick fixes are available?"       | `codeAction`                             | filePath, line, character, endLine, endCharacter                              |
+| "Rename symbol safely"                  | `rename`                                 | filePath, line, character, newName                                            |
+| "Who implements this interface?"        | `implementation`                         | filePath, line, character                                                     |
+| "Who calls this function?"              | `prepareCallHierarchy` → `incomingCalls` | filePath, line, character                                                     |
+| "What does this function call?"         | `prepareCallHierarchy` → `outgoingCalls` | filePath, line, character                                                     |
+| "Show tracked LSP diagnostics snapshot" | `workspaceDiagnostics`                   | optional filePath (snapshot only; prefer `lsp_diagnostics` for active checks) |
+
+## Operational Guidance (From Field Tests)
+
+- Always pass `filePath` for `workspaceSymbol` when possible. Unscoped queries are best-effort and often empty.
+- For `references`, prefer querying from the definition site for broader cross-file coverage; usage-site queries can be partial.
+- Use `signatureHelp` only at call-site argument positions; declaration positions often return empty.
+- Treat `workspaceDiagnostics` as tracked push snapshot (`publishDiagnostics`), not protocol pull `workspace/diagnostic` coverage. Prefer `lsp_diagnostics` when you need an active file/folder/batch check.
+- For `codeAction`, separate `quickfix` from generic refactors (for example "Move to new file"). Do not treat generic refactors as error fixes.
+- `prepareCallHierarchy` is server-capability dependent; if unsupported, skip incoming/outgoing calls.
+- If TypeScript returns `No Project` on `workspaceSymbol`, retry after opening the scoped file context.
+
+## Call Hierarchy Pattern
+
+```typescript
+// Step 1: Prepare (get the callable item)
+const items = await lsp_navigation({
+  operation: "prepareCallHierarchy",
+  filePath: "src/api.ts",
+  line: 42,
+  character: 10,
+});
+
+// Step 2: Get callers (who calls this function)
+const callers = await lsp_navigation({
+  operation: "incomingCalls",
+  callHierarchyItem: items[0],
+});
+
+// Step 2: Get callees (what this function calls)
+const callees = await lsp_navigation({
+  operation: "outgoingCalls",
+  callHierarchyItem: items[0],
+});
+```
+
+## When NOT to Use LSP
+
+| Task                        | Use Instead       | Why                         |
+| --------------------------- | ----------------- | --------------------------- |
+| Active type/error checks    | `lsp_diagnostics` | Diagnostics, not navigation |
+| Find patterns (console.log) | `ast_grep_search` | Pattern matching            |
+| Find text/TODOs             | `grep`            | Text search                 |
+| Find files by name          | `glob`            | File discovery              |
+| Read file content           | `read`            | Direct access               |
+
+## Golden Rule
+
+**Code intelligence → `lsp_navigation` first. Type/error validation → `lsp_diagnostics` first. Text/pattern search → grep/ast-grep.**

package/.pi/skills/quality/code-review-self-check/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: code-review-self-check
+description: Perform a final agent self-review before reporting completion. Use after any code edit, refactor, test change, config change, or docs update. Checks diff scope, behavior alignment, edge cases, tests, security/privacy, naming, and unverified risks.
+---
+
+# Code Review Self-Check
+
+Use this skill before final response on code-writing tasks.
+
+## Review workflow
+
+1. Inspect the diff, not just memory of edits.
+2. Re-read the original request and compare it to changed behavior.
+3. Check that no unrelated files or formatting churn were introduced.
+4. Check public contracts, data formats, and error behavior.
+5. Check edge cases and failure paths.
+6. Check names and structure against nearby conventions.
+7. Check tests: they should assert behavior that matters and fail for the old bug/change when applicable.
+8. Check logs/errors for secret or private data exposure.
+9. Run or explain the most relevant verification.
+10. Report residual risk honestly.
+
+## Final response fields
+
+- changed files
+- why changed
+- verification run
+- known risks or follow-ups
+
+## Red flags
+
+- The implementation is larger than the request.
+- Tests only assert mocks or snapshots without behavior.
+- The code handles success but not failure.
+- A new dependency or contract change is unexplained.

package/.pi/skills/quality/privacy-data-handling/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: privacy-data-handling
+description: Handle personal, sensitive, or customer data safely. Use when adding storage, logs, analytics, exports, imports, integrations, telemetry, search indexes, AI context, or user-facing data flows. Focuses on minimization, retention, access, deletion, and safe observability.
+---
+
+# Privacy and Data Handling
+
+Use this skill when code touches data that may identify, describe, or affect people, customers, tenants, organizations, or secrets.
+
+## Workflow
+
+1. Classify data: public, internal, sensitive, personal, secret, regulated, or tenant-scoped.
+2. Minimize collection, storage, logging, and propagation.
+3. Keep access checks close to reads and writes.
+4. Avoid placing sensitive data in logs, errors, metrics labels, analytics, caches, prompts, or filenames.
+5. Define retention, deletion, and export implications when adding storage.
+6. Redact or aggregate data used for observability.
+7. Add tests for tenant isolation, access denial, and redaction where relevant.
+
+## Review questions
+
+- Who can read this data now?
+- Where else does this data flow?
+- Can it be deleted or corrected if needed?
+- Is sensitive data copied into long-lived artifacts?
+- Does the final response expose private values?

package/.pi/skills/quality/security-review/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: security-review
+description: Run a lightweight security pass on code changes. Use when touching authentication, authorization, input handling, files, paths, commands, network calls, serialization, storage, secrets, dependencies, or user-controlled data. Focuses on trust boundaries and common vulnerability classes.
+---
+
+# Security Review
+
+Use this skill whenever a change crosses a trust boundary.
+
+## Checklist
+
+- Authentication: is the actor known when required?
+- Authorization: is the actor allowed to perform this action on this resource?
+- Input validation: is untrusted input constrained before use?
+- Injection: are queries, commands, paths, templates, and expressions safely constructed?
+- Secrets: are credentials never logged, committed, exposed, or returned?
+- Sensitive data: is private data minimized and protected?
+- Deserialization/parsing: are formats constrained and failures explicit?
+- Filesystem/process/network: are paths, arguments, redirects, and destinations controlled?
+- Dependencies: does the change introduce known vulnerable or unnecessary packages?
+
+## Workflow
+
+1. Identify trust boundaries and attacker-controlled values.
+2. Trace those values to sensitive sinks.
+3. Add validation, authorization, escaping, or isolation at the right layer.
+4. Add abuse-case tests for important risks.
+5. Report any security assumption that remains unverified.
+
+## Avoid
+
+- Relying only on client-side checks.
+- Logging full request bodies or tokens.
+- Treating internal callers as inherently safe when data originated outside.

package/.pi/skills/quality/test-strategy/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: test-strategy
+description: Choose the right test level for a code change. Use when adding features, fixing bugs, refactoring, changing contracts, or improving coverage. Guides unit, integration, contract, characterization, regression, property, and end-to-end test selection without assuming a specific tool or runtime.
+---
+
+# Test Strategy
+
+Use this skill to add useful tests rather than merely more tests.
+
+## Choose test type by risk
+
+- Unit test: pure logic, calculations, policies, branching, invariants.
+- Integration test: storage, filesystem, network, process, or platform/runtime boundary.
+- Contract test: public API, command, event, plugin, module facade, or service boundary.
+- Characterization test: existing unclear behavior before legacy changes.
+- Regression test: bug fix that must not reappear.
+- End-to-end test: critical user journey or cross-boundary behavior not covered otherwise.
+- Property or generative test: broad input space with stable invariants.
+
+## Workflow
+
+1. Identify the behavior that must be proven.
+2. Pick the lowest test level that gives confidence.
+3. Test public behavior and invariants, not incidental implementation details.
+4. Include edge cases: empty, missing, invalid, boundary, duplicate, reordered, and failure paths where relevant.
+5. Ensure tests fail for the bug/change before relying on them.
+6. Keep tests deterministic and readable.
+
+## Avoid
+
+- Snapshot/golden tests that hide important intent.
+- Mock-heavy tests that only verify implementation choreography.
+- Broad end-to-end tests for simple pure logic.

package/.pi/skills/quality/testability-design/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: testability-design
+description: Reshape code so important behavior can be tested simply. Use when code is hard to test due to IO, time, randomness, globals, hidden dependencies, side effects, or platform/runtime coupling. Separates pure logic from effects and introduces stable seams.
+---
+
+# Testability Design
+
+Use this skill when verification is difficult because the design hides seams.
+
+## Workflow
+
+1. Identify behavior worth testing separately from the mechanism that triggers it.
+2. Move pure decisions/calculations away from IO and mutation where practical.
+3. Inject or pass volatile dependencies such as clocks, randomness, environment, storage, network, and external processes.
+4. Replace ambient/global state with explicit inputs or narrow adapters where safe.
+5. Expose behavior through a stable public seam rather than private internals.
+6. Keep tests close to the level of the behavior being guaranteed.
+
+## Good seams
+
+- boundary adapters
+- domain services or policies
+- command/query handlers
+- parser/serializer boundaries
+- workflow step interfaces
+- configuration providers
+- repository/storage ports
+
+## Avoid
+
+- Making private implementation public only for tests.
+- Adding test-only branches to production logic.
+- Over-abstracting every dependency before a real testability problem exists.

package/.pi/skills/systems/concurrency-safety/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: concurrency-safety
+description: Prevent race conditions and unsafe shared-state behavior. Use when modifying async work, parallel execution, queues, locks, caches, background jobs, shared mutable state, transactions, event handlers, or distributed coordination. Emphasizes idempotency, ordering, isolation, and deterministic tests.
+---
+
+# Concurrency Safety
+
+Use this skill when operations may overlap, reorder, duplicate, or observe stale state.
+
+## Workflow
+
+1. Identify shared mutable state and who can access it concurrently.
+2. Identify ordering assumptions and whether they are guaranteed.
+3. Check for duplicate, delayed, retried, or out-of-order execution.
+4. Use appropriate isolation: immutability, ownership, lock, transaction, compare-and-set, queue serialization, or idempotency key.
+5. Keep critical sections small and failure-safe.
+6. Ensure cleanup/release happens on error paths.
+7. Add tests or simulations for duplicate and interleaved operations where practical.
+
+## Review questions
+
+- Can two callers perform this action at once?
+- Can this message/job/event be processed twice?
+- Can a stale read overwrite newer state?
+- Is the operation atomic from the user's perspective?
+- Is there a deadlock, starvation, or resource leak risk?
+
+## Avoid
+
+- Assuming single-thread/process execution unless enforced.
+- Using time sleeps as correctness guarantees.
+- Global mutable state without ownership rules.