Repo Foundation

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

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.