Adopt Arcantry

Adopt Arcantry

Adopt only the information layers the project needs. Preserve project-owned content and stop when a plan reports a conflict.

Inspect

1. Read the applicable repository and private instructions.
2. Use protect-local-boundary before creating or using local state. Let it resolve absent, private, index-only, or remote-tracked .local/ status and complete the exclusion and authorization gates before continuing.
3. Run arcantry repo inspect before proposing changes.
4. Identify the active and shadowed configuration, then list each shared or private OpenSpec, changelog, and todo.txt source with its adapter, visibility, management level, and dependencies.
5. Treat .local/ as a privacy boundary and keep shared and private sources independent.

An explicit --config <path> wins. Otherwise Arcantry checks .local/arcantry.toml before arcantry.toml at each directory while walking toward the filesystem root. It uses the first match and never merges configuration files.

Initialize the repository boundary

Choose one explicit scope:

arcantry repo init --scope shared
arcantry repo init --scope private

Shared initialization manages arcantry.toml and the Arcantry section in AGENTS.md. Private initialization manages .local/arcantry.toml, .local/AGENTS.md, and the local Git exclusion. It does not create package manifests, runtime configuration, task runners, OpenSpec sources, changelogs, or todo files.

Treat AGENTS.md as a universal surface. Preserve any existing .agents/skills; do not create or modify it during adoption. Add --compat claude only when the user explicitly wants Claude imports or skill aliases. Do not copy guidance or skill bodies into branded directories.

Resolve reusable skills

Assume user-wide skills are available and do not install, update, or copy skills during normal adoption.

When a required capability is unavailable, recommend a user-wide installation and ask whether the user wants that installation or a repository-local private package under .local/skills.

When a user-wide skill exists but is not suitable for the required version or compatibility, explain the choice between updating it user-wide and creating a local override. A local installation or override is an opt-in fallback, never the default.

Configuration-free discovery recognizes openspec, .local/openspec, CHANGELOG.md, .local/CHANGELOG.md, todo.txt, and .local/todo.txt. Private skill packages live under .local/skills/<name> and remain procedural capabilities rather than project knowledge sources.

Use the same explicit scope with repo update and repo remove. Removal is limited to verified Arcantry-owned configuration and managed guidance.

Choose source responsibility

Choose ignore, observe, validate, or manage independently for each source. A shared changelog must not depend on private OpenSpec; a private changelog may depend on either scope. A configured capability does not authorize an external write.

Choose an explicit transition when structure must change:

• preserve: leave data and responsibility unchanged.
• adopt: manage an existing source in place.
• rebind: connect the role to another existing source.
• cutover: preserve earlier history and manage only a new boundary.
• migrate: convert only meaning that can be recovered without guessing.
• relocate: copy and verify a target before a separately planned deletion.

Plan and apply

1. Run arcantry repo plan --source <id> --transition <strategy> --json.
2. Review conflicts, input hashes, visibility, adapter versions, and ordered operations.
3. Apply only with explicit user authorization using arcantry repo apply --plan <path|->.
4. If an input changed after planning, inspect again and create a new plan.

Todo commands are previews unless --apply is present. When both shared and private queues exist, select the source explicitly. Do not invent workflow tags.

Verify

1. Run arcantry repo inspect again.
2. Run arcantry repo validate and, when repair guidance is useful, arcantry repo doctor.
3. Confirm private content did not enter previews, logs, tracked files, or packages.
4. Confirm unrelated project files and native build tooling remain unchanged.
5. Report applied transitions, preserved boundaries, conflicts, and checks not run.