Files
repoctl/AGENTS.md
T

57 lines
2.9 KiB
Markdown

# 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 currently contains specifications and runbooks. `repoctl`, executable handlers and an MCP server are planned interfaces, not implemented tools in this repository.
## 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`.
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.