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>
This commit is contained in:
Alexander Baranov
2026-08-24 15:00:34 +03:00
co-authored by Claude Sonnet 5
parent 96d4d08230
commit 7286322c83
8 changed files with 141 additions and 12 deletions
+26 -8
View File
@@ -6,7 +6,11 @@
## Текущее состояние
Сейчас здесь находятся спецификация, руководство и adoption runbook. CLI `repoctl`, handlers и MCP server ещё не реализованы; команды в документации определяют целевой интерфейс.
Реализация достигла уровня совместимости `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.
| Точка входа | Назначение |
|---|---|
@@ -18,6 +22,20 @@
| `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`.
## Как пользоваться содержимым
@@ -37,14 +55,14 @@ flowchart LR
Репозиторий применяет собственную концепцию без декоративной унификации:
- действующие документы собраны в одном content root `docs/`, а исходное исследование отделено в `docs/research/`;
- не созданы пустые `templates/`, `schemas/`, `src/` или `ops/handlers/`;
- не объявлены исполняемые operations, поскольку handlers ещё отсутствуют;
- `src/`, `src/stewardship/schemas/` и `.claude/skills/` появились только тогда, когда за ними встал реальный код;
- `ops/handlers/` по-прежнему не создан: этот репозиторий не объявляет ни одной executable operation, поэтому L2 handler ABI остаётся отложенным;
- template lineage не записан, потому что этот repository не был создан из готового versioned template;
- будущий код добавит собственный content root тогда, когда он действительно появится.
- Plan/RunEvidence (L3), MCP server и catalog daemon намеренно не реализованы — см. "Зафиксированные ограничения" в [PLAN.md](docs/PLAN.md).
## Ближайший практический этап
1. Зафиксировать schemas и fixtures четырёх типов репозиториев.
2. Реализовать read-only `validate`, `discover`, `describe` и `context`.
3. Выполнить plan-only adoption для `Infra/LXD` и `Services/Antivirus`.
4. После пилотов реализовать `init`, `adopt` и тонкий Claude skill.
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 поверх той же модели.