Repo foundation

Repository Foundation guides feature work, bug fixes, new modules and authorized architecture or schema migrations toward the smallest foundation that fits. It aims to minimize total rework without imposing a universal layout, framework or error pattern. Standard-library solutions are acceptable. Existing healthy conventions guide implementation; accidental workarounds are not precedent for wider cleanup.

Select Bootstrap for a new repository or subsystem lacking minimal tooling, conventions and boundaries. Establish critical constraints, a just-enough design, run/build commands and a verified representative slice. Select Continue for work on a fitting existing foundation: establish scope, implement the change, verify it and review the diff. Select Evolve when requirements change contracts, ownership or architecture: assess the affected scope and execute a controlled, verified migration. Adopting an existing repository starts with mode selection rather than automatic rebuilding.

Use it for a feature, defect fix, subsystem start, authorized migration or resumption where stale notes must be reconciled with repository evidence. Skip it for typos, formatting-only work and isolated script adjustments. It cannot infer missing product requirements from code alone. Passing checks establish only the cases they exercise, and atomic replacement examples do not guarantee crash durability on every filesystem.

Start with the objective, observable consequences, affected boundaries, repository instructions, actual callers and a baseline revision. Without Git, use an inventory or snapshot. Preserve pre-existing uncommitted changes, including when editing a separate part of the same file; ask only for an actual collision or ambiguous intent. Do not initialize Git or create commits solely for tracking or handoff.

Implementation preserves consumed public types, values, errors and serialization. An explicitly authorized contract change updates callers, tests and documentation in scope. Check CLI consumers before rewording error text. Domain names should express ownership. Comments retain useful rationale, invariants, units, rounding, ordering and protocol details rather than narrating syntax. Do not invent tickets, incidents, owners or production histories. Preserve existing references unless repository evidence shows they are wrong or obsolete; an inaccessible reference is uncertainty rather than proof of fabrication.

Choose conventional reversible implementation defaults independently. Bundle material product and architectural decisions, such as dependencies, schemas and authentication, before breaking existing behavior. Avoid wrappers, factories and abstractions without a concrete ownership, contract or test-seam need.

Verify the final code after every cleanup. Distinguish pre-existing failures, in-scope failures, new regressions and environment errors. Persistent tests are warranted for behavior changes, defects, contract changes and meaningful coverage gaps; reuse the existing framework. Documentation and mechanically checked work use proportionate lightweight verification. A successful exit is insufficient when the expected artifact is absent. Report verified requirements, assumptions and gaps distinctly.

Operations that may fail midway need explicit preservation invariants: validate inputs and ownership, prepare a replacement separately, retain the old state until ready and exercise failure boundaries. High-risk authorization, permission, migration, cryptographic, persistence and concurrency work requires the verification reference, even for a small diff.

Supporting references cover bootstrap, evolution, continuity, shared contracts, verification and migration examples. Read them when their triggers apply. Reuse existing trackers and notes instead of creating routine handoff files. Reconcile conflicting requirements, callers, tests and documentation rather than merely updating notes to match code.

A repo-native-refactor companion pass is limited to one when requested or justified by unresolved concerns or substantial contract, ownership or semantic changes. Same-agent review is not independent review; finish normally if the companion is unavailable and rerun checks after edits. Repository-edit authority does not authorize pushing, publishing, deployment, branch-protection changes, system hooks or purchases.

One supplied request example is:

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.

The skill is adapted from repository-engineering-skills and retains its MIT license notice.