Files
repoctl/README.md
T
Alexander BaranovandClaude Sonnet 5 7286322c83 docs: self-host at L1 and ship the three Claude skill adapters
- Move ops/contract.yaml annotation from specification-only to l1-implemented and
  declare real content roots for repoctl source, schemas, tests and Claude adapters.
- Add repoctl-cli capability to provides[].
- Route repository.tooling.use and repository.handoff intents to the existing
  tooling-implementation KDB topic.
- Update README, AGENTS.md and CLAUDE.md to describe the implemented repoctl surface
  instead of a planned one, without claiming L2/L3/MCP capabilities that don't exist.
- Add .claude/skills/{repository-bootstrap,repository-adoption,repo-handoff}/SKILL.md,
  generated from the same stewardship.skills_content strings that ship inside every
  repoctl init bootstrap (no duplicated logic).

`repoctl validate --repo .` passes with zero findings after this change.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-24 15:00:34 +03:00

69 lines
5.0 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/research/` | исходные архитектурные исследования |
| `src/stewardship/` | реализация `repoctl` (модели, schemas, CLI) |
| `src/stewardship/schemas/` | JSON Schemas (Draft 2020-12) для всех kinds |
| `tests/` | fixtures и pytest-набор (позитивные, негативные, adoption) |
| `.claude/skills/` | три тонких Claude skill-адаптера над `repoctl` |
### Установка и запуск
```bash
uv sync
uv run repoctl validate --repo .
uv run pytest
```
`uv sync` создаёт `.venv` в корне репозитория; все команды выполняются через `uv run`.
## Как пользоваться содержимым
```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 поверх той же модели.