`init` writes .claude/skills/*/SKILL.md into every new repository from the constants in skills_content, so each skill exists twice: once as the copy this repository uses, once as the copy it ships. Editing one and not the other went unnoticed by validate and by every test. It had already happened. The shipped repository-adoption skill still told its reader to use `--strategy normalize --recipe documents-to-content-root` -- an operation the CLI does not offer and CLAUDE.md forbids claiming -- and said nothing about the owner requirement or acknowledged findings. Every repository bootstrapped since would have received that copy. Sync both, and add a test that compares each shipped skill against the checked-in one so the next divergence fails instead of shipping. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Repository Stewardship
Этот репозиторий разрабатывает стандарт и будущий инструментарий для единообразной работы с Git-репозиториями при помощи людей и любых AI-агентов.
Основная идея: каждый репозиторий сам сообщает, что он содержит, где лежит его реальный результат, какие знания нужны для конкретной задачи и какие действия допустимы. Claude является основным агентом, но модель не зависит от Claude, LLM, skill format или MCP.
Текущее состояние
Реализация достигла уровня совместимости L1: CLI repoctl (repository-stewardship
Python-пакет, модуль stewardship) реализует validate, discover, describe,
context, init и adopt как read-only-by-default команды с plan-then-apply
approval для любых записей. ops/handlers/, execution runner и MCP server остаются
отложенными: этот репозиторий не объявляет ни одной executable operation.
| Точка входа | Назначение |
|---|---|
ops/contract.yaml |
машиночитаемый паспорт этого репозитория |
kdb/kdb.yaml |
маршрутизация знаний по intent |
CLAUDE.md |
основная точка входа Claude |
AGENTS.md |
переносимые инструкции для агентов |
docs/specification.md |
нормативная спецификация |
docs/guide.md |
объяснение модели для человека |
docs/adoption-runbook.md |
перевод существующих репозиториев на стандарт |
docs/repoctl.md |
руководство по repoctl для человека: установка, команды, коды возврата |
docs/research/ |
исходные архитектурные исследования |
src/stewardship/ |
реализация repoctl (модели, schemas, CLI) |
src/stewardship/schemas/ |
JSON Schemas (Draft 2020-12) для всех kinds |
tests/ |
unit pytest-набор (позитивные, негативные, adoption fixtures) |
tests-universal/ |
spec-driven CLI-контрактный набор, независимый от реализации |
.claude/skills/ |
три тонких Claude skill-адаптера над repoctl |
Установка и запуск
uv sync
uv run repoctl validate --repo .
uv run pytest
uv run pytest tests-universal
uv sync создаёт .venv в корне репозитория; все команды выполняются через uv run. tests-universal — отдельный набор: он вызывает repoctl только как внешний процесс и сверяется исключительно с docs/specification.md, поэтому им можно проверить любую совместимую реализацию, а не только эту. Практическое руководство по самому CLI — в docs/repoctl.md.
Как пользоваться содержимым
flowchart LR
TASK["Задача"] --> CONTRACT["ops/contract.yaml"]
CONTRACT --> KDB["kdb/kdb.yaml"]
KDB --> TOPIC["Тема по exact intent"]
TOPIC --> SECTIONS["Только нужные документы и разделы"]
SECTIONS --> RESULT["Решение или proposed change"]
Для понимания модели начните с руководства. Для реализации форматов используйте спецификацию. Для подключения существующего репозитория следуйте adoption runbook.
Почему структура минимальна
Репозиторий применяет собственную концепцию без декоративной унификации:
- действующие документы собраны в одном content root
docs/, а исходное исследование отделено вdocs/research/; src/,src/stewardship/schemas/и.claude/skills/появились только тогда, когда за ними встал реальный код;ops/handlers/по-прежнему не создан: этот репозиторий не объявляет ни одной executable operation, поэтому L2 handler ABI остаётся отложенным;- template lineage не записан, потому что этот repository не был создан из готового versioned template;
- Plan/RunEvidence (L3), MCP server и catalog daemon намеренно не реализованы — см. "Зафиксированные ограничения" в PLAN.md.
Ближайший практический этап
- Провести реальные
assess/planpilots дляInfra/LXDиServices/Antivirus(read-only, безapply). - Собрать метрики time-to-context на нескольких повторяемых сценариях (см. guide.md, раздел 19).
- Зафиксировать L2 handler ABI и только затем добавить
inspect/diff/plan/verify/applyoperations. - Только после L2 рассматривать MCP adapter поверх той же модели.