Files
repoctl/AGENTS.md
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

3.2 KiB

Repository instructions

Purpose

This repository defines Repository Stewardship: harness-neutral contracts, knowledge routing, templates and adoption practices for managing Git repositories with humans and AI agents.

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

  1. Read ops/contract.yaml to identify the repository and authoritative content roots.
  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.

Authority order

  • docs/specification.md is normative for fields, invariants and compatibility.
  • docs/adoption-runbook.md is the canonical procedure for existing repositories.
  • docs/guide.md explains the same model for people.
  • docs/research/ preserves earlier research and alternatives; it is not the current contract.

If documents disagree, follow this order and record the discrepancy instead of silently merging meanings.

Repository boundaries

  • Keep domain-neutral standards here.
  • Do not copy LXD, Docker, Antivirus or other domain handlers into this repository.
  • Skills and MCP adapters must remain thin interfaces over the same model and future repoctl behavior.
  • Do not claim an operation exists until a canonical handler and validation path exist.
  • Keep canonical long-form documents under docs/; use deeper nesting only for a distinct authority class such as docs/research/.

Editing rules

  • Keep YAML examples machine-parseable.
  • Use stewardship.corsus.ru/v1alpha1; do not introduce an alternative API group without a versioned migration.
  • Keep Claude as the primary agent while preserving portable instructions in this file.
  • A normative schema change must update affected examples, the human guide, KDB routing and adoption rules in the same change.
  • Use Mermaid for architecture and workflow diagrams.
  • Preserve unrelated user changes and do not modify other repositories unless the task explicitly includes them.
  • Never place secrets, private keys, tokens or live credentials in contracts, KDB, examples or evidence.

Validation before completion

  • Parse Markdown frontmatter and every fenced YAML block.
  • Validate ops/contract.yaml and kdb/kdb.yaml as YAML resources.
  • Check KDB topic-to-document references and repo-relative paths.
  • Check local Markdown links and balanced code fences.
  • Statically check Mermaid block headers; render them when a Mermaid renderer is available.
  • Confirm changed paths match the requested scope.

Self-hosting rule

This repository should follow its own standard only where that adds discovery, safety or maintainability. Avoid placeholder directories, fake handlers, fictional capabilities and duplicated documentation created only for visual symmetry.