The stewardship skills were written by exactly one code path: `init`, which
only runs on a new repository. Adopting an existing one starts from the
repository-adoption skill, and nothing could put that skill there -- so the
entry point to the procedure depended on the operator already having it
from somewhere else. Services/Monitoring carries three domain skills of its
own and no stewardship skill; `adopt` lists `.claude/skills` among its
collision paths and installs nothing.
repoctl skills install --repo . # travels with the repository
repoctl skills install --global # follows the operator everywhere
repoctl skills status --repo .
Scope is stated, never guessed: the two answers differ in who ends up with
the skills, and neither is the obvious default.
No plan and no approval hash. That discipline protects a repository's own
content; this writes only tool-owned files, in a fixed subdirectory, whose
content is fully determined by the installed version. The house rule it
does keep is that a write never destroys what it did not author: a skill
whose content differs is reported as SKILLS_MODIFIED and left alone until
`--force` says otherwise, and the check covers every skill before the first
byte is written, so a refusal leaves nothing half-updated.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
67 lines
3.5 KiB
Markdown
67 lines
3.5 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 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 <path>` (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 <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.
|