Files
Alexander BaranovandClaude Opus 5 c80d39cc73 feat(skills): install the agent skills into any repository
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>
2026-08-26 14:35:38 +03:00

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.