opencode-skills-collection 4.1.2 → 4.1.4

package/bundled-skills/repo-foundation/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: repo-foundation
+description: "Implement features, fixes, modules, contract migrations, and resumed work while preserving user edits and authorized public contracts."
+category: development
+risk: critical
+source: https://github.com/Natchannnn/repository-engineering-skills
+source_repo: Natchannnn/repository-engineering-skills
+source_type: community
+date_added: "2026-09-30"
+author: Natchannnn
+tags: [repository-engineering, feature-development, contract-migration, continuity]
+tools: [codex]
+license: MIT
+license_source: https://github.com/Natchannnn/repository-engineering-skills/blob/e55b378158d5134a77af3b8dace4a2a1b17e41e2/LICENSE
+metadata:
+  version: "0.3.0"
+  license: "MIT"
+---
+
+# Repo foundation
+
+## When to Use
+
+- Use when the user asks to add a feature, fix a bug, or start a module in an existing project.
+- Use when establishing the minimum foundation for a new repository or subsystem.
+- Use when requirements authorize a schema, public-contract, ownership, or architecture migration.
+- Use when resuming unfinished work or reconciling stale notes with repository evidence.
+
+Build on a foundation that's just big enough, add features on top of it, and change the architecture only when requirements force it. Aim for the least total rework.
+
+---
+
+## Core principles
+
+- **No universal dogma:** don't impose a layout, error pattern, or framework the project doesn't need. Plain standard library is fine.
+- **Scope, baseline, and user work:**
+  - Establish a clean baseline before mutating code: use the pre-existing revision/commit when Git exists; use a file inventory or snapshot when uninitialized or greenfield.
+  - In a dirty workspace, protect pre-existing uncommitted user modifications. You may edit distinct parts of the same file as long as user work is preserved. Stop and ask only if there is an actual collision or ambiguous intent.
+  - Never create commits or force Git initialization solely for handoff or tracking.
+  - Reuse conventions only with healthy repository precedent. Don't treat accidental patterns or temporary workarounds as precedent, and don't expand into out-of-scope cleanup.
+  - Don't push, publish, deploy, change branch protection, install system hooks, or buy anything unless the user asks.
+- **Prose, naming, and restraint:**
+  - Names reflect business domain concepts and ownership.
+  - Add comments only for information code cannot express: grounded rationale, non-obvious invariants, units, rounding, ordering, protocol quirks, or compatibility.
+  - Do not narrate syntax; do not invent tickets, incidents, owners, or production histories.
+  - Treat error and CLI text as contract surface: check callers and parsers before rewording.
+  - Never invent ticket, PR, or incident references. An inaccessible or unverified reference is not evidence of fabrication. Preserve existing references unless repository evidence establishes that they are incorrect or obsolete; report material uncertainty instead of deleting them.
+  - Do not strip valuable comments merely for cosmetic brevity; do not enforce arbitrary comment ratios.
+  - Do not add abstractions, wrappers, or factory layers without concrete ownership, contract, or test seam needs.
+- **Preserve consumed public contracts** as defined in `references/shared-contracts.md` §1: keep documented types, values, errors, and serialization. Change a contract only when the task clearly authorizes it, then update callers, tests, and docs in scope.
+- **Verification rigor & proportionate testing:**
+  - Record baseline failures and distinguish: (1) pre-existing failures outside scope, (2) in-scope failures to fix, (3) regressions from current changes, and (4) environment errors.
+  - Verify the final code state; never use pre-cleanup test results to certify modified code.
+  - Add or update persistent tests when a change introduces behavior, fixes a defect, alters a contract, or exposes a meaningful coverage gap. Prefer the repository's existing test framework and structure. Do not add tests solely for file-count or coverage optics. For documentation-only or mechanically verified changes, use the relevant lightweight checks and explain any material verification gap.
+  - Check every requirement before you say you're done. Say what you verified, what you only read, and what you assumed. A command that exits 0 doesn't count if the file it should make isn't there.
+- **Failure invariants & state preservation:** if an operation can fail halfway, decide what must stay untouched. Validate inputs and ownership first, build the replacement on the side, keep the old state until the new one is ready, and test the failure boundary.
+
+---
+
+## Mode selection
+
+| Mode | Trigger | Core Actions | Exit Criteria |
+|---|---|---|---|
+| **Bootstrap** | New repository from scratch or an area lacking minimal foundation (no build/test/run commands, conventions, or boundaries). | Elicit critical constraints, choose just-enough design, set up minimal tooling/checks, implement and verify the first representative slice. Read [bootstrap](references/bootstrap.md). | Representative slice works and is verified; run/build commands are documented; repo is stable for subsequent work. |
+| **Continue** | Adding a feature, bugfix, or improvement on an existing, fitting foundation. | Determine owning domain and boundary, implement changes, run proportionate checks, and review diff. Executable directly from core. | Task requirements are met; diff is reviewed; intentional contract changes are verified (or existing contracts preserved); remaining limitations are stated. |
+| **Evolve** | New requirements alter core contracts, ownership, boundaries, or architecture; or adopting a repo with conflicting conventions. | Assess blast radius, execute controlled migration, update evidence, tests, and documentation. Read [evolution](references/evolution.md). | Transition is verified; new contracts are operational; instructions and documentation align with code. |
+
+Adopting an existing repository begins with mode selection; do not default to re-bootstrapping. If the repository already has working instructions, tooling, and conventions, reuse them. If a specific subsystem lacks a foundation, establish only what that subsystem requires.
+
+---
+
+## Continue workflow (Core)
+
+Routine feature work runs straight from the mode above plus core principles, no extra reference needed:
+
+### 1. Scope and baseline
+Confirm the user's objective, observable consequences, affected boundaries, baseline revision/inventory, and any uncommitted user changes to preserve.
+
+### 2. Implement just enough
+- **Assumptions vs. product decisions:** choose conventional, reversible defaults (directory layout, helper naming, standard library choices) on your own. Bundle product and architectural decisions (external dependencies, data schema changes, new auth schemes) into one question before breaking anything.
+- **Intentional contract changes** occur when a task explicitly requires changing a contract, so verify that callers and tests reflect the new contract rather than forcing deprecated behavior.
+
+### 3. Verify proportionately
+- **Lightweight path (low risk):** routine bug fixes and localized edits inside established boundaries. Keep scope tight and run relevant mechanical checks (syntax, linter, affected unit tests). Skip automatic secondary review passes unless concrete unresolved concerns warrant one; an explicit review request still applies.
+- **High-risk changes:** a single line touching authorization, permissions, data migrations, cryptography, persistence lifecycles, or concurrency can do serious damage. Read [verification](references/verification.md) before designing checks.
+
+### 4. Continuity and state
+- **Implementation vs. requirements:** existing code shows current behavior. That is not proof of meeting requirements, and passing tests don't guarantee completeness if acceptance was never tested.
+- **Reconciliation:** use the evidence hierarchy to guide investigation, not to settle contradictions for you. If requirements, docs, callers, and tests disagree, reconcile them before changing the contract. If notes and code disagree, check requirements and tests; don't edit the notes to match the code.
+- **Tracking:** reuse issue trackers and project notes. Don't create handoff files for routine features.
+
+---
+
+## Companion Coordination (`repo-native-refactor`)
+
+Use at most one companion pass when the user requests review, concrete unresolved concerns remain, or a substantial contract, ownership, or semantic change warrants a scoped audit. Lightweight fixes do not trigger an automatic pass. Read [references/companion.md](references/companion.md) when a pass is warranted; finish normally if the companion is unavailable. Rerun affected checks after its edits; same-agent self-review is not independent review.
+
+---
+
+## Reference routing
+
+Read supporting references only when the corresponding trigger occurs:
+
+- **[references/bootstrap.md](references/bootstrap.md):** Read in **Bootstrap mode** to establish a new repository, set up minimal tooling, and build the first representative slice.
+- **[references/evolution.md](references/evolution.md):** Read in **Evolve mode** to assess blast radius, handle breaking contract changes, or reconcile conflicting conventions.
+- **[references/continuity.md](references/continuity.md):** Read when resuming work across sessions, taking over a repository, or reconciling stale notes with code reality.
+- **[references/verification.md](references/verification.md):** Read when designing checks for greenfield code, high-risk boundaries (auth, data loss, concurrency), or weak test suites.
+- **[references/shared-contracts.md](references/shared-contracts.md):** Canonical contract + evidence hierarchy + final-state rule. Read when touching any public interface, reconciling conflicting requirements, or certifying completion.
+- **[references/migration-examples.md](references/migration-examples.md):** Atomic vs transitional migration patterns. Read in Evolve mode before mutating persisted state.
+- **[references/companion.md](references/companion.md):** Full companion coordination (roles, handoff, loop limits). Read when planning a refactor pass with `repo-native-refactor`.
+
+---
+
+## Examples
+
+### Add a feature on an existing foundation
+
+```text
+Use repo-foundation to add pagination to this project's existing search endpoint.
+Preserve the current default response and my uncommitted changes. Reuse the
+project's conventions, add relevant regression coverage, and verify the final diff.
+```
+
+Select Continue mode, inspect the endpoint's callers and baseline checks, implement
+the smallest compatible change, and report the checks actually performed.
+
+### Migrate an authorized persisted contract
+
+```text
+Use repo-foundation to migrate our local JSON store from schema v1 to v2.
+Update the in-scope callers and tests. A failed migration must leave the existing
+store intact; verify that failure boundary before reporting completion.
+```
+
+Select Evolve mode and read the migration and verification references before
+changing persisted state. Establish the authorized target schema and verify the
+transition, including failure-state preservation.
+
+## Limitations
+
+- Repository instructions and actual callers are required to establish local contracts; the skill cannot infer missing product requirements reliably.
+- Atomic replacement examples depend on the target filesystem and do not establish crash durability on every platform.
+- Relevant passing checks establish only their exercised scope; they do not prove that all requirements or failure modes are covered.
+- Companion review is optional when unavailable; same-agent self-review is not independent review.
+
+## Security & Safety Notes
+
+This skill can edit source files and guide state migrations, so its declared risk
+is `critical` under this collection's state-modification classification. Work only
+within the user's authorized repository and task scope, preserve existing user
+changes, and establish failure invariants before changing persisted data. Routine
+implementation authority does not authorize pushing, publishing, deploying,
+changing branch protection, installing system hooks, or purchases.
+
+---
+
+## When NOT to Use
+
+- **Trivial edits:** Skip this skill for typos, isolated script adjustments, or formatting-only changes: the overhead is not worth it.
+
+
+## Source & License
+
+Adapted from [Natchannnn/repository-engineering-skills](https://github.com/Natchannnn/repository-engineering-skills/tree/e55b378158d5134a77af3b8dace4a2a1b17e41e2).
+The original MIT copyright notice and license are retained in [references/LICENSE.md](references/LICENSE.md).
+Collection adaptations add metadata, explicit triggers, interaction examples, limitations, and safety notes; the core workflow and supporting reference instructions are retained.

package/bundled-skills/repo-foundation/references/LICENSE.md

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

package/bundled-skills/repo-foundation/references/bootstrap.md

@@ -0,0 +1,63 @@
+# Bootstrap: establishing foundation and initial slice
+
+> Field note: I used to scaffold full layered dirs on day one. Deleted most of it. Now I ship one slice first.
+
+Use this reference when starting a new repository from scratch or when setting up an area of an existing repository that lacks minimal tooling, conventions, or architecture.
+
+---
+
+## 1. Minimal inputs and scoping
+
+Before generating code or directory structures, establish the critical constraints.
+First: what should the software actually do for an outside observer (CLI command, HTTP endpoint, UI component, library export, worker process)? Second: hard constraints (language, runtime, frameworks, persistence, external services, anything operational the user asked for). Third, sort decisions into two piles.
+Reversible assumptions cover directory structure, utility naming, standard library picks, and helper layout. Choose conventionally on your own. Don't ask permission for every folder or variable name.
+Product decisions cover persistence store, auth architecture, vendors, and breaking domain rules. Bundle missing product decisions into one short question before implementing.
+
+---
+
+## 2. The first representative slice
+
+Avoid horizontal layering without working behavior. Do not generate empty directories, unused interfaces, speculative repositories, or generic wrappers that serve no active flow.
+
+Build a single, real, end-to-end slice that crosses the system's primary architectural boundaries. The shapes below are illustrative examples, not mandatory architectures:
+
+| Project Type | Example Slice Shape (Illustrative) |
+|---|---|
+| **CLI Tool** | Input parsing (flags/arguments) → core logic → observable output and exit status. (A simple tool does not require multiple internal layers). |
+| **API / Service** | Request intake → route handler → domain logic/validation → response. (Persistence is included only if the service actually requires state; stateless services, proxies, and aggregators do not need persistence layers). |
+| **Web / UI** | User interaction/event → state transition/store update → observable UI rendering (including empty/loading/error states). |
+| **Library / Package** | Public API export → core implementation → return value / error handling. (Libraries do not need an app server or startup daemon). |
+| **Worker / Job** | Task intake/deserialization → business processing → outcome persistence, acknowledgment, or retry handling. |
+
+Verify both the successful path and meaningful domain failure modes (e.g., validation failure, not found, unauthenticated).
+
+If external integrations cannot be run locally, simulated stubs are permitted only when explicitly acknowledged; never describe a mock integration as real.
+
+---
+
+## 3. Tooling and instructions setup
+
+Establish the minimal commands necessary for an agent or developer to run and verify the project using stack-native configuration:
+
+1. **Native configuration:** Place commands in standard stack files (`package.json`, `pyproject.toml`, `Makefile`, `Cargo.toml`, `go.mod`, etc.).
+2. **Commands fit the project type:**
+   - Run/start command for local execution (only when applicable; libraries and utility packages do not need a start command).
+   - Test command executing automated checks.
+   - Lint/format command if idiomatic to the stack.
+3. **Instructions handling:**
+   - If the repository already has an instructions file (e.g., `AGENTS.md` or `README.md`), update it minimally only if needed to record new commands or invariants. Never overwrite or recreate existing instructions just because you are in Bootstrap mode.
+   - If no instructions file exists and the host/workflow uses one, create a concise file (around 300–700 tokens) pointing to commands and noting key constraints.
+
+---
+
+## 4. Establishing reference code
+
+Code created during bootstrap serves as precedent for future development only when it satisfies all of the following:
+
+1. **Traceable:** Directly satisfies a concrete user requirement or contract.
+2. **Observable verification:** Accompanied by automated checks whose expected values reflect business outcomes rather than copying internal implementation details.
+3. **Appropriate ownership and dependencies:** Modules have clear responsibilities and dependency directions suited to the chosen architecture and actual project requirements, without forcing unnecessary layers (e.g., transport/domain/persistence separation is not required for a small CLI, library, or script).
+4. **No unexplained debt:** Contains no unexplained workarounds, commented-out dead code, or temporary hacks.
+5. **Bounded scope:** If a convention applies only to a specific module, document it as module-local rather than an overarching repository standard.
+
+No code pattern is permanently "golden." When requirements change or architecture evolves, update reference paths rather than maintaining obsolete conventions.

package/bundled-skills/repo-foundation/references/companion.md

@@ -0,0 +1,9 @@
+# Companion Coordination (`repo-native-refactor`)
+
+Read this when a meaningful checkpoint is done and you consider one cleanup pass.
+
+- **Complementary roles:** Foundation builds, implements, and adapts; Refactor audits, tightens prose, removes residue, and aligns conventions within scope. Foundation does not reimplement refactor's taxonomy or risk bands; Refactor does not revert intentional, requested behavioral changes.
+- **Discovery and fallback:** Locate companion through host-supported discovery only; do not hardcode paths, download, or assume mentioning the name triggers execution. Foundation operates fully without companion. Mention its absence only when that leaves a requested review incomplete. Same-agent self-review is not independent review.
+- **Invocation timing:** Use a pass when the user requests review or a substantial contract, ownership, or semantic change warrants a scoped audit. Skip automatic passes for lightweight fixes unless concrete unresolved concerns warrant one; an explicit review request still applies.
+- **Minimal handoff contract:** Transfer objective/scope/intentional changes, baseline & user changes, contracts & precedents, check status & limitations from existing context without creating handoff files.
+- **Post-cleanup and loop limits:** Rerun affected checks on final code state after refactor edits. Perform at most one refactor pass per checkpoint by default; iterate only on concrete findings or failing checks. If a product decision is missing, ask the user; do not guess or unilaterally redesign.

package/bundled-skills/repo-foundation/references/continuity.md

@@ -0,0 +1,50 @@
+# Continuity: session handover and reconciling state
+
+Use this reference when resuming work in a new session, taking over a repository, or when recorded notes disagree with the actual codebase.
+
+---
+
+## 1. Reconciling notes with code reality
+
+When taking over an ongoing project, compare documented status with the actual state of the working tree.
+
+Code shows what the software does right now. That alone doesn't prove it meets the requirements or acceptance criteria.
+
+When notes and code conflict, cross-check requirements and tests first.
+Go back to the user's original requirements, preserved contracts, and actual test coverage.
+Passing tests are not a rubber stamp.
+Green tests don't declare a feature complete if acceptance criteria or edge cases were never tested.
+Don't edit notes just to legitimize whatever code happens to be there.
+Investigate before updating.
+Notes say pending but code looks done? Verify against the requirement and run or add acceptance checks.
+If truly complete and verified, update the notes.
+If partial or defective, fix the code.
+Don't rubber-stamp the notes.
+Never do a blind rollback.
+Don't delete working code just because some stale note doesn't mention it.
+If intent is ambiguous, ask the user.
+
+---
+
+## 2. Working in dirty workspaces
+
+Users often call agents into workspaces with uncommitted work. Inspect `git status` (or directory state when not using Git) before modifying files; inventory comes first only in the sense that mutation must wait for it.
+Identify uncommitted changes belonging to the user and do not discard or clobber them.
+Protecting user changes does *not* forbid editing the entire file.
+You may modify distinct, relevant parts of the same file as long as the user's uncommitted changes remain intact and functional.
+Only stop and ask if there is an actual conflict or if the user's intent cannot be determined.
+The baseline for verification and diffing includes the base commit plus the pre-existing uncommitted modifications.
+Your changes must stay distinguishable from earlier user changes.
+Never execute `git commit`, `git stash`, or `git reset` automatically to create a clean slate unless the user explicitly commands it.
+No forced commits.
+
+---
+
+## 3. Handing over a session
+
+When ending a session or preparing a handoff for another agent or developer, reuse existing channels.
+Record state in existing project tracking mechanisms (e.g., project issue trackers, `TODO` lists, or brief handover notes).
+Do not create ad-hoc handoff files for routine features.
+A concise handoff says what got done and verified, the working tree status, remaining limits or next steps, and which verification commands ran with what outcome.
+Do not append ongoing session logs or raw conversation transcripts to permanent repository instruction files (like `AGENTS.md`).
+Keep instructions focused on lasting architecture and workflows.

package/bundled-skills/repo-foundation/references/evolution.md

@@ -0,0 +1,60 @@
+# Evolution: adapting architecture and contracts
+
+Use this reference when a task alters core contracts, architectural boundaries, or domain ownership, or when working in a repository with conflicting conventions.
+
+---
+
+## 1. Intentional contract changes vs. regressions
+
+When requirements evolve, contracts must adapt. Tell intent apart from regression: an intentional change alters public API signatures, schemas, data models, or error codes because the user explicitly asked for new behavior. A regression is an unintended break in existing functionality.
+Accept what the user requested. Don't fight explicit requests by forcing compatibility with deprecated behavior. Foundation and refactor work both accommodate authorized changes while preserving untouched contracts.
+
+---
+
+## 2. Blast radius assessment
+
+Before mutating shared contracts, determine the blast radius:
+
+1. **Identify callers and consumers:** Locate all internal modules, external consumers, database schemas, message queues, or serialized data structures affected by the change.
+2. **Boundary scope:** Confirm whether the change can be completed within the authorized scope or if it requires updating multiple subsystem boundaries.
+3. When all callers reside within the codebase and are under the current task's scope, update the contract, callers, and tests together (the atomic update). When consumers are external, persisted data must be migrated, or callers span multiple independent services, maintain a compatibility bridge, migration script, or dual-read/write strategy as requested (the transitional migration).
+
+---
+
+## 3. Controlled migration workflow
+
+Execute architectural adjustments in logical order:
+
+1. **Update contract definitions:** Modify the authoritative interfaces, schemas, or type definitions first.
+2. **Migrate callers:** Update calling code, dependency injection bindings, and data transformations to use the new contract.
+3. **Align tests:** Update existing tests that assert the old contract so they verify the new behavior. Add tests covering edge cases and error semantics of the new contract.
+4. **Synchronize documentation:** Update repository instructions, schema definitions, and API documentation to prevent stale instructions from misleading future agents.
+
+---
+
+## 4. Reconciling conflicting repository conventions
+
+In mature repositories, different modules often reflect different architectural eras or styles:
+
+When patterns conflict, resolve using evidence hierarchy in order:
+  1. User's explicit instruction for the current task.
+  2. Documented architecture and repository instructions.
+  3. Preserved public contracts and persisted schemas.
+  4. Healthy sibling code within the *same* owning domain and runtime boundary.
+  5. Relevant tests, schemas, callers, and dependencies.
+  6. Local module conventions.
+Do not rewrite healthy sibling code in another module merely to match your current change. Preserve legitimate domain-specific differences unless codebase-wide unification is explicitly requested; premature homogenization helps no one.
+If existing code contains obvious workarounds or defects, do not replicate them in new code. Follow the healthiest precedent within the domain: defects never become precedent.
+
+---
+
+## 5. Multi-pressure checklist
+
+When migration, risk, docs, and workspace pressures stack (the usual evolution mess),
+work in this order and do not skip steps:
+
+1. Baseline: record revision, failing checks, and uncommitted user work.
+2. Protect user work: distinct-region edits only; stop on real collision.
+3. Reconcile docs against code reality before mutating (code describes behavior, docs get fixed after).
+4. Highest-risk caller first with maximum conservatism; atomic path for the rest.
+5. Rerun affected checks on the final tree; report what remains red and why.

package/bundled-skills/repo-foundation/references/migration-examples.md

@@ -0,0 +1,53 @@
+# Migration Examples (atomic vs transitional)
+
+Read in Evolve mode when changing a public contract or persisted schema.
+
+## Atomic replacement (preferred for single-node file state)
+
+```python
+import os
+import tempfile
+from pathlib import Path
+
+def replace_file(dest: Path, new_bytes: bytes) -> None:
+    tmp = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="wb",
+            dir=dest.parent,
+            prefix=f".{dest.name}.",
+            suffix=".tmp",
+            delete=False,
+        ) as file:
+            tmp = Path(file.name)
+            file.write(new_bytes)
+            file.flush()
+            os.fsync(file.fileno())
+
+        os.replace(tmp, dest)
+    finally:
+        if tmp is not None:
+            tmp.unlink(missing_ok=True)
+```
+
+Invariants: validate inputs + destination ownership before mutation; retain last valid
+state until replacement succeeds. Stage on the destination filesystem with a unique
+temporary name; close the file before replacement and clean up the temporary file on
+success or failure. Verify successful replacement and preservation of the old state
+when writing, syncing, or replacement fails.
+This example addresses ordinary I/O failures. Power-loss durability and recovery after
+forced termination require platform-specific guarantees and separate verification.
+
+## Transitional compatibility (multi-caller migration)
+
+Bad: change producer to `Decimal("5.00")` while callers expect `int 5` → hidden breakage.
+Good:
+1. Keep old readers working (accept `int | str | Decimal`, normalize internally).
+2. Migrate callers one by one while preserving compatibility for remaining consumers.
+3. Add contract and caller tests covering both surfaces during transition.
+4. Remove compat shim only after all callers + docs updated.
+
+## Docs sync checklist
+
+- Update `README.md` + CLI help in the same diff as the contract change.
+- Document only behavior implemented and verified in the delivered code state.

package/bundled-skills/repo-foundation/references/shared-contracts.md

@@ -0,0 +1,48 @@
+# Shared contracts
+
+These rules apply to repository development and review.
+
+## 1. Strict contract adherence (canonical wording)
+
+Preserve documented or demonstrably consumed public contracts across public interfaces,
+exported parameters, module constants, return types, errors, and serialization.
+
+- A requested behavior change may authorize a contract change only when that consequence
+  is clear from the task or from an authorized evolution. Then update affected callers,
+  tests, and living documentation within scope.
+- Otherwise preserve exact declared types. For example, never substitute or wrap an exposed
+  primitive `str` path contract with `pathlib.Path` or custom wrapper objects merely for
+  internal convenience or preference.
+- Internal intermediate representations may use appropriate helpers, provided all exposed
+  public contracts and types remain exact.
+
+## 2. Evidence hierarchy (canonical order)
+
+Use to guide investigation, not to auto-resolve material contradictions:
+
+1. User requirements and explicitly authorized scope.
+2. Documented architecture and repository guidelines.
+3. Observable public contracts and persisted schemas.
+4. Healthy sibling code within the same domain and runtime boundary.
+5. Relevant tests, schemas, callers, and dependencies.
+6. Dominant local conventions.
+7. Language and runtime idioms.
+8. Conservative, idiomatic defaults.
+
+Never treat a temporary workaround, buggy sibling, or accidental pattern as precedent.
+Never rewrite history or rubber-stamp code with stale notes. Reconcile before mutating
+the affected contract.
+
+## 3. Verification final-state rule (canonical)
+
+- Record baseline failures as: (1) pre-existing outside scope, (2) in-scope to fix,
+  (3) regressions from current changes, (4) environment errors.
+- Verify the final code state. Never use pre-cleanup results to certify modified code.
+- Never claim a check ran when it did not. Distinguish verified behavior,
+  inspection-only conclusions, and unverified assumptions.
+
+## 4. Shared judgment tests (canonical)
+
+Two questions that both skills use when the text alone under-determines the answer.
+
+A pattern counts as healthy precedent only if three things hold: code outside its original author consumes it, it does not contradict docs or contracts, and you would copy it into a new domain without apology. Popularity proves nothing; a workaround with tests and docs still fails. When two domains overlap, the owner is whoever owns the failure (who gets paged, who fixes the bug, whose reason to change fires first). Consolidate toward that owner, or leave both alone.

package/bundled-skills/repo-foundation/references/verification.md

@@ -0,0 +1,50 @@
+# Verification: testing in proportion to risk
+
+Use this reference when designing checks for greenfield projects, high-risk boundaries (auth, data loss, concurrency, migrations), or weak test suites.
+
+---
+
+## 1. Baseline failures and scope
+
+Before or during initial execution, record baseline test failures and sort them:
+
+1. Failures outside the current task's scope count as pre-existing. You don't need them green before starting, and don't fix unrelated ones just to green the baseline.
+2. Failures inside the task's scope are in scope, such as a bugfix that starts with a failing test or repro script, and these are yours to resolve.
+3. Regressions are previously passing checks your changes broke. Catch and fix them before declaring completion.
+4. When checks can't run because of missing tools, dependencies, or setup, treat them as environment and tooling failures. Report them as environment limits, not code defects.
+
+---
+
+## 2. Picking checks by risk
+
+Match checks to the contract, boundary, and failure consequences. Don't mandate unit plus integration tests for every small helper, or unrelated checks (rollback tests for an auth change):
+
+- Mechanical or local changes include typos, formatting, localized helper refactoring, and other non-semantic edits within established boundaries. For those, run stack linters, formatters, and localized unit tests.
+- Contract and boundary changes modify public APIs, data formats, state machines, or subsystem contracts, so run tests that directly verify the updated contract and its callers.
+- Changes touching authorization, permission checks, data migrations, cryptographic routines, concurrency locks, transaction boundaries, or destructive persistence carry high risk even when they touch only a single line, which calls for critical boundary vigilance. Verify the specific critical behavior (e.g., testing both authorized and unauthorized paths for auth changes; testing schema validity and rollback for migration scripts).
+
+---
+
+## 3. Greenfield and acceptance checks
+
+When building new features or starting a repository from scratch:
+
+- Keep environment checks separate from acceptance checks:
+  - *Environment / pre-existing checks:* toolchain, package manager, and build environment must work. These pass before feature work starts.
+  - *Acceptance checks for new capabilities:* the expected observable behavior of the new feature.
+- For pre-build test states:
+  - An acceptance check for an unbuilt feature should detect the missing behavior when run in a valid environment.
+  - Tell apart a meaningful behavioral failure (endpoint 404s, CLI says unknown command, feature returns null) from an unrunnable test (syntax error, broken import, missing binary).
+  - Do not inject bugs, syntax errors, or failing stubs into test code just to force a failure.
+- After implementing, acceptance checks must pass cleanly on the final code state. That is the evidence of completion.
+
+---
+
+## 4. Testing integrity and final state
+
+- For defect fixes, reproduce the failure first with a minimal reproduction such as a failing test, repro script, or observed command output, because a fix verified only after the fact is a guess with good lighting. For regression tests, prove red-green by reverting the fix, watching it fail, restoring it, and watching it pass.
+- Check the external consequence of the action to assert observable outcomes, such as HTTP status code and body, database row contents, exit code and stdout/stderr, or rendered DOM elements.
+- Expected values must reflect business requirements to keep outcomes independent, not mirror internal implementation logic.
+- Never weaken tests to achieve a passing run by weakening assertion thresholds, deleting valid assertions, or skipping tests.
+- Always verify the final tree by executing verification commands on the actual code state intended for delivery. If a subsequent refactoring pass or companion skill modifies code, rerun all affected checks on the updated code.
+- Report actual results by stating exactly which commands were run, their outcomes, and any unverified areas.