diff --git a/.claude/skills/repo-handoff/SKILL.md b/.claude/skills/repo-handoff/SKILL.md new file mode 100644 index 0000000..2908281 --- /dev/null +++ b/.claude/skills/repo-handoff/SKILL.md @@ -0,0 +1,19 @@ +--- +name: repo-handoff +description: Produce a minimal, intent-scoped context handoff for a repository using repoctl context. Use when another agent, session or teammate needs just enough context to work on one task in a repository. +--- + +# repo-handoff + +Thin wrapper around `repoctl context`. Do not read the full repository or the full KDB +by hand when this skill applies — let `repoctl` perform the selection. + +## Procedure + +1. Turn the user's request into an `intent` id (e.g. `container.deploy`, + `repository.adopt`), not a literal command. +2. Run `repoctl context --repo --intent --output json`. +3. If the bundle looks incomplete, retry with `--include-related` or `--materialize` + and an explicit `--budget-bytes`. +4. Hand the resulting `ContextBundle` (and any `warnings`) to the requester instead of + pasting raw repository files. diff --git a/.claude/skills/repository-adoption/SKILL.md b/.claude/skills/repository-adoption/SKILL.md new file mode 100644 index 0000000..c1fa76d --- /dev/null +++ b/.claude/skills/repository-adoption/SKILL.md @@ -0,0 +1,27 @@ +--- +name: repository-adoption +description: Assess and adopt an existing repository into Repository Stewardship using repoctl adopt. Use when connecting an existing, non-templated repository without moving its domain content. +--- + +# repository-adoption + +Thin wrapper around `repoctl adopt`. The canonical procedure is +`docs/adoption-runbook.md`; this skill only collects missing decisions, calls the CLI +with machine output, and explains findings. It must not duplicate the runbook logic. + +## Procedure + +1. Run `repoctl adopt --repo --mode assess --output json` (read-only). +2. Present the classification, detected content roots, and any `questions` that need + owner confirmation. +3. Run `repoctl adopt --repo --mode plan --output json` once open questions are + resolved. This is still read-only and returns an `AdoptionPlan` with a `planHash`. +4. Show the full plan (files created, patched managed blocks, preserved paths, + forbidden changes) before asking for approval. +5. Only after explicit approval, run + `repoctl adopt --repo --mode apply --plan --approve `. +6. Run `repoctl adopt --repo --mode verify --output json` and report the + `AdoptionReport`, including any `unresolvedFindings`. + +Default strategy is `overlay`. Only use `--strategy normalize --recipe +documents-to-content-root` when the owner explicitly asks to reorganize root documents. diff --git a/.claude/skills/repository-bootstrap/SKILL.md b/.claude/skills/repository-bootstrap/SKILL.md new file mode 100644 index 0000000..0aa0b2f --- /dev/null +++ b/.claude/skills/repository-bootstrap/SKILL.md @@ -0,0 +1,23 @@ +--- +name: repository-bootstrap +description: Bootstrap a new repository into Repository Stewardship using repoctl init. Use when creating a new repository or scaffolding ops/contract.yaml, kdb/kdb.yaml and agent entrypoints from scratch. +--- + +# repository-bootstrap + +Thin wrapper around `repoctl init`. Do not reimplement classification, template +rendering or validation here — call the CLI and explain its output. + +## Procedure + +1. Collect the missing decisions from the user: repository type + (`infrastructure-config` | `service-config` | `software` | `project`), `metadata.name`, + `title`, `owners`, `lifecycle`. +2. Run `repoctl init --repo --answers --output json` to obtain a + `BootstrapPlan` (this performs no writes). +3. Show the user the planned files and the `planHash`. +4. Only after explicit approval, run + `repoctl init --repo --apply --plan --approve `. +5. Report the resulting `repoctl validate --repo ` findings. + +Never invent files outside the plan and never skip the approval step. diff --git a/AGENTS.md b/AGENTS.md index 6d2e509..79376ca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,10 @@ This repository defines Repository Stewardship: harness-neutral contracts, knowledge routing, templates and adoption practices for managing Git repositories with humans and AI agents. -It currently contains specifications and runbooks. `repoctl`, executable handlers and an MCP server are planned interfaces, not implemented tools in this repository. +It now ships an L1 implementation: the `repoctl` CLI (Python package +`repository-stewardship`, module `stewardship`, run via `uv run repoctl`) implements +`config`, `validate`, `discover`, `describe`, `context`, `init` and `adopt`. Executable +`ops/handlers/`, the L2 handler ABI and an MCP server remain planned, not implemented. ## Start here @@ -12,6 +15,8 @@ It currently contains specifications and runbooks. `repoctl`, executable handler 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 --output json` over reading + whole documents by hand once the CLI is available in your environment. Do not load every design document by default. diff --git a/CLAUDE.md b/CLAUDE.md index e8fa693..bf9d7bc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,4 +7,4 @@ - Treat `kdb/kdb.yaml` as the routing index, not as a request to read every linked document. - For bootstrap or adoption work, produce assessment and proposed diff before writing. - Ask only for decisions that cannot be established from repository evidence, such as ambiguous ownership or source-of-truth conflicts. -- Do not invoke future `repoctl` commands as if they already exist; follow the documented procedure manually until the CLI is implemented. +- `repoctl` is implemented at L1 (`uv run repoctl ...`); prefer it over manually re-deriving `validate`/`discover`/`describe`/`context`/`init`/`adopt` logic. Only fall back to the documented runbook procedure by hand when `repoctl` is unavailable in the current environment. Do not claim `apply`/`verify` operations, an ABI, or MCP exist beyond what `docs/PLAN.md` "Зафиксированные ограничения" allows. diff --git a/README.md b/README.md index de6b5da..b2a36a3 100644 --- a/README.md +++ b/README.md @@ -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 поверх той же модели. diff --git a/kdb/kdb.yaml b/kdb/kdb.yaml index f4c6ac3..b8efa4b 100644 --- a/kdb/kdb.yaml +++ b/kdb/kdb.yaml @@ -104,7 +104,9 @@ spec: intents: - repository.tooling.implement - repository.tooling.test + - repository.tooling.use - repository.adapter.create + - repository.handoff keywords: - repoctl - parser diff --git a/ops/contract.yaml b/ops/contract.yaml index da47b54..e445df5 100644 --- a/ops/contract.yaml +++ b/ops/contract.yaml @@ -10,9 +10,9 @@ metadata: role: standards-and-templates annotations: stewardship.corsus.ru/bootstrap-mode: self-hosted - stewardship.corsus.ru/implementation-status: specification-only + stewardship.corsus.ru/implementation-status: l1-implemented spec: - summary: Standards, templates and adoption guidance for AI-assisted repository management + summary: Standards, templates and the repoctl L1 CLI for AI-assisted repository management repository: type: project lifecycle: active @@ -38,6 +38,38 @@ spec: writePolicy: managed selector: "**/*.md" format: text/markdown + - id: repoctl-source + role: source + path: src/stewardship + kind: directory + authority: source + writePolicy: managed + selector: "**/*.py" + format: text/x-python + - id: repoctl-schemas-and-templates + role: schemas + path: src/stewardship/schemas + kind: directory + authority: source + writePolicy: managed + selector: "**/*.schema.json" + format: application/schema+json + - id: repoctl-tests + role: tests + path: tests + kind: directory + authority: source + writePolicy: managed + selector: "**/*.py" + format: text/x-python + - id: claude-adapters + role: agent-adapters + path: .claude/skills + kind: directory + authority: source + writePolicy: managed + selector: "**/SKILL.md" + format: text/markdown provides: - id: stewardship-model capability: repository.stewardship-model @@ -45,3 +77,6 @@ spec: - id: adoption-procedure capability: repository.adoption-procedure summary: Safe overlay procedure for bringing existing repositories into the model + - id: repoctl-cli + capability: repository.tooling.repoctl + summary: repoctl L1 CLI implementing validate, discover, describe, context, init and adopt