# Repository instructions ## Purpose This repository defines Repository Stewardship: harness-neutral contracts, knowledge routing, templates and adoption practices for managing Git repositories with humans and AI agents. It now ships an L1 implementation: the `repoctl` CLI (Python package `repository-stewardship`, module `stewardship`, run via `uv run repoctl`) implements `config`, `skills`, `validate`, `discover`, `describe`, `context`, `init` and `adopt`. Executable `ops/handlers/`, the L2 handler ABI and an MCP server remain planned, not implemented. To work with another repository, put the skills where its agent looks first: `uv run repoctl skills install --repo ` (or `--global` once, for every repository). Adoption then starts from the `repository-adoption` skill. ## Start here 1. Read `ops/contract.yaml` to identify the repository and authoritative content roots. 2. Read the small index in `kdb/kdb.yaml`. 3. Match the task to an exact topic intent. 4. Open only the documents and headings named by that topic's `data.readHints`. 5. Prefer `uv run repoctl context --repo . --intent --output json` over reading whole documents by hand once the CLI is available in your environment. Do not load every design document by default. ## Authority order - `docs/specification.md` is normative for fields, invariants and compatibility. - `docs/adoption-runbook.md` is the canonical procedure for existing repositories. - `docs/guide.md` explains the same model for people. - `docs/research/` preserves earlier research and alternatives; it is not the current contract. If documents disagree, follow this order and record the discrepancy instead of silently merging meanings. ## Repository boundaries - Keep domain-neutral standards here. - Do not copy LXD, Docker, Antivirus or other domain handlers into this repository. - Skills and MCP adapters must remain thin interfaces over the same model and future `repoctl` behavior. - Do not claim an operation exists until a canonical handler and validation path exist. - Keep canonical long-form documents under `docs/`; use deeper nesting only for a distinct authority class such as `docs/research/`. ## Editing rules - Keep YAML examples machine-parseable. - Use `stewardship.corsus.ru/v1alpha1`; do not introduce an alternative API group without a versioned migration. - Keep Claude as the primary agent while preserving portable instructions in this file. - A normative schema change must update affected examples, the human guide, KDB routing and adoption rules in the same change. - Use Mermaid for architecture and workflow diagrams. - Preserve unrelated user changes and do not modify other repositories unless the task explicitly includes them. - Never place secrets, private keys, tokens or live credentials in contracts, KDB, examples or evidence. ## Validation before completion - Parse Markdown frontmatter and every fenced YAML block. - Validate `ops/contract.yaml` and `kdb/kdb.yaml` as YAML resources. - Check KDB topic-to-document references and repo-relative paths. - Check local Markdown links and balanced code fences. - Statically check Mermaid block headers; render them when a Mermaid renderer is available. - Confirm changed paths match the requested scope. ## Self-hosting rule This repository should follow its own standard only where that adds discovery, safety or maintainability. Avoid placeholder directories, fake handlers, fictional capabilities and duplicated documentation created only for visual symmetry.