A field report from bootstrapping Services/Vault: ~20 CLI calls produced
three productive writes, and four of those calls were deliberate failures
sent only to discover a vocabulary.
The worst of it was self-inflicted and new. `repoctl skills install` is the
documented way to make the bootstrap skill reachable, and it writes the
three skill files -- which `init` then reported as INIT_PATH_COLLISION and
redirected to `adopt`. Every skill-driven bootstrap of an empty repository
was pushed onto the adoption path. The collision check exists to protect
content the tool did not author, and identical bytes are nothing to
protect: a path already holding exactly what the plan would write is no
longer a collision, at plan time or at write time, while a file whose
content differs still is. `init` reports only the files it actually wrote.
`--lifecycle` advertised no choices, so its vocabulary was reachable only
by sending a wrong value and reading the refusal; it now carries `choices`
like `--type` does.
`--answers-template` prints a commented answers file naming every key, its
allowed values and its default. The answers keys are not the flag names
(`--type` sets `repositoryType`) and nothing printed the mapping. It lists
`summary` and `namespace` too, which are cheap to answer once and otherwise
survive as generated placeholders in the contract.
`--repo .` proposed the name `adopted-repository`: `Path(".").name` is the
empty string, so the ordinary way to name the current repository fell
through to the generic fallback. Resolve before deriving.
Both skills gained what the report had to discover by hand: that `--plan`
already unwraps a saved result envelope, and that sibling repositories are
where a naming convention comes from.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
1.8 KiB
1.8 KiB
name, description
| name | description |
|---|---|
| repository-adoption | 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
- Run
repoctl adopt --repo <path> --mode assess --output json(read-only). - Present the classification, detected content roots, and any
questionsthat need owner confirmation. - Run
repoctl adopt --repo <path> --mode plan --owner <owner> --output jsononce open questions are resolved. This is still read-only and returns anAdoptionPlanwith aplanHash.planrefuses without a confirmed owner, and refuses whileassessleft an error-severity finding; an owner who accepts one lists it underacknowledgedFindings(with areason) in the--answersfile. - Show the full plan (files created, patched managed blocks, preserved paths, forbidden changes) before asking for approval.
- Only after explicit approval, run
repoctl adopt --repo <path> --mode apply --plan <plan-file> --approve <planHash>.--planaccepts the file exactly as--output json > plan.jsonwrote it: the result envelope is unwrapped for you, so do not strip it down todataby hand. - Run
repoctl adopt --repo <path> --mode verify --output jsonand report theAdoptionReport, including anyunresolvedFindings.
The only implemented strategy is overlay. Normalization recipes are specified in the
runbook but not implemented, and the CLI does not offer them: do not describe
--strategy normalize or --recipe as available.