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:
co-authored by
Claude Sonnet 5
parent
96d4d08230
commit
7286322c83
@@ -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 <name-or-path> --intent <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.
|
||||
@@ -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 <path> --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 <path> --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 <path> --mode apply --plan <plan-file> --approve <planHash>`.
|
||||
6. Run `repoctl adopt --repo <path> --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.
|
||||
@@ -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 <path> --answers <answers-file> --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 <path> --apply --plan <plan-file> --approve <planHash>`.
|
||||
5. Report the resulting `repoctl validate --repo <path>` findings.
|
||||
|
||||
Never invent files outside the plan and never skip the approval step.
|
||||
@@ -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 <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.
|
||||
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 поверх той же модели.
|
||||
|
||||
@@ -104,7 +104,9 @@ spec:
|
||||
intents:
|
||||
- repository.tooling.implement
|
||||
- repository.tooling.test
|
||||
- repository.tooling.use
|
||||
- repository.adapter.create
|
||||
- repository.handoff
|
||||
keywords:
|
||||
- repoctl
|
||||
- parser
|
||||
|
||||
+37
-2
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user