Files
repoctl/README.md
T
Alexander Baranov 4fbe56d81f docs: add human-facing repoctl guide in Russian, route it via KDB
docs/repoctl.md walks a human through what repoctl is, the install-once
/ invoke-from-other-repositories model (folding in the framing already
present on the sibling codex/repoctl-l1 branch's docs/repoctl.md), each
command with real sample output, the exit-code table, and troubleshooting.
docs/specification.md stays the normative machine reference.

kdb/kdb.yaml routes the new document into the tooling-implementation
topic; README.md links it and documents running tests-universal.
2026-08-24 15:42:48 +03:00

72 lines
5.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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` |
### Установка и запуск
```bash
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](docs/repoctl.md).
## Как пользоваться содержимым
```mermaid
flowchart LR
TASK["Задача"] --> CONTRACT["ops/contract.yaml"]
CONTRACT --> KDB["kdb/kdb.yaml"]
KDB --> TOPIC["Тема по exact intent"]
TOPIC --> SECTIONS["Только нужные документы и разделы"]
SECTIONS --> RESULT["Решение или proposed change"]
```
Для понимания модели начните с [руководства](docs/guide.md). Для реализации форматов используйте [спецификацию](docs/specification.md). Для подключения существующего репозитория следуйте [adoption runbook](docs/adoption-runbook.md).
## Почему структура минимальна
Репозиторий применяет собственную концепцию без декоративной унификации:
- действующие документы собраны в одном 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](docs/PLAN.md).
## Ближайший практический этап
1. Провести реальные `assess`/`plan` pilots для `Infra/LXD` и `Services/Antivirus` (read-only, без `apply`).
2. Собрать метрики time-to-context на нескольких повторяемых сценариях (см. guide.md, раздел 19).
3. Зафиксировать L2 handler ABI и только затем добавить `inspect`/`diff`/`plan`/`verify`/`apply` operations.
4. Только после L2 рассматривать MCP adapter поверх той же модели.