repository-harness: Skill for Codex

Onboard Repository

Turn an unfamiliar repository into a verified map for future work. Treat the repository as the system of record. Separate facts from gaps and suggestions.

Safety Contract

The first pass is always inspection and proposal only, even when the worktree is writable.

• Read every applicable AGENTS.md before inspecting deeper files.
• Capture the initial Git root, revision, branch, status, and worktree list.
• Preserve all pre-existing tracked and untracked changes.
• In the initial boundary capture, before deeper repository inspection, record pre-state existence or safe hashes for relevant ignored state such as .env.local, dependency directories, and managed repository state. Never print secret contents. If an initial baseline was missed, report pre/post equivalence as Unknown; a later sample cannot reconstruct it.
• Treat ignore rules and managed-state manifests as part of the boundary, not deeper inspection. Read them before fixing the baseline, enumerate every relevant ignored database, sidecar, dependency, environment, build, and managed-state path they reveal, and record each one explicitly. For ignored directories, use a content-sensitive per-file hash inventory; a filenames- only hash does not prove that contents stayed unchanged.
• Use only read-only discovery commands. Do not install dependencies, start services, invoke migrations, create caches or state, or edit files.
• Use task-prefixed shell variable names. In zsh, never assign to special names such as path, status, pipestatus, commands, or their uppercase system counterparts; corrupting the inspection shell invalidates later baselines.
• Do not create temporary files inside or outside the repository. Compare via stdout and non-materializing pipelines; if a comparison requires a file, report that limitation instead of creating one.
• Do not use shell heredocs or here-strings; shells may materialize them as temporary files. Use quoted python3 -c/node -e programs, stdin pipes, or ordinary read-only commands instead.
• When a runtime manager is relevant, capture its observable project, service, volume, and process state in the initial boundary batch. If the manager is unavailable, state that runtime pre/post equivalence is Unknown. Proving that no runtime command was issued does not prove runtime state was unchanged.
• Before invoking a repository-local binary, verify that its path exists and is executable. If absent, record the command as unavailable; do not invoke, install, rebuild, or substitute it.
• Do not turn code, tests, configuration, conventions, or guesses into product intent. They can prove present behavior, not missing normative policy.
• Stop when authority is absent or materially different interpretations remain.
• End by comparing Git status and diff with the captured initial state.