---
name: adopt-the-repo
description: Use when adding Kobold to a repository. Convert its instructions into skills and playbooks, either by minimizing the root instruction files or by leaving those files alone, and ask which bounds fit what the files already say.
metadata:
  group: setup
---

# Adopt the repo

## The choice

When `.claude-plugin/plugin.json` names `kobold-codex`, say so
and stop. This skill does not convert the plugin into a target.

Ask which path to use, unless `.kobold/adopt.yaml` already
records one.

Full converts the sources. Each instruction file keeps the why
and loses the what and the how. Each root instruction file that
remains points at the `kobold-codex` plugin and at the project
skill root. The why stays in sentences. A procedure or a subject
fact does not remain under that pointer.

Shadow converts the sources into skills and playbooks. Leave the
instruction files as they are. The converted files stay out of
the project repository. When the skill root has no tracked files,
the hide choice in The local repo covers the skill root and the
playbook directory. When the root already has tracked files, the
hide choice covers each new skill directory and each new playbook
file, and the root stays visible.

The record is `.kobold/adopt.yaml` at the repository root. It
names `mode`, `skill-root`, `playbooks`, `plans`, `specs`,
`plans-tracked`, `specs-tracked`, `requirements`, `hide`, and
`config-repo`.
`mode` is `full` or `shadow`. `hide` is `gitignore` or `exclude`,
and it is omitted when every Kobold path is tracked.
`config-repo` is the path of the local repository, and it is
omitted when the user declines one. The adopt record is tracked
with the project when every Kobold path it names is tracked.
When any of those paths stays out, the record stays out with
them.

On the full path, suggest `.kobold/bounds.yaml` as the bounds
layer. The sources are team instructions. On the shadow path,
suggest `.kobold/bounds.local.yaml`. The user can name the other
writable layer. `set-the-bounds` writes the file. This skill
writes no bounds key.

## The sources

Read instruction files and skills. Leave the rest of the
repository's Markdown unread. A README, a contributing guide, and
a doc are sources only when the user names them.

Instruction file names, at the repository root and in
subdirectories, are `AGENTS.md`, `AGENT.md`, `Agents.md`,
`CLAUDE.md`, `Claude.md`, `CLAUDE.local.md`, `.claude/CLAUDE.md`,
and `.claude/CLAUDE.local.md`. Also read every Markdown file
placed directly in `.grok/rules/`, `.claude/rules/`, or
`.cursor/rules/`. A session skips an instruction file that git is
ignoring, including a file matched from `.git/info/exclude`. On
the shadow path, the converted what and how go in a skill or a
playbook, not in one of those files.

Skill files are `SKILL.md` under a directory the project already
uses for skills a session loads. Command files are Markdown files
placed directly in a `commands/` directory beside such a skill
root. Those files are sources too.

A skill directory the project already has is the skill root. When
several exist, ask which one receives the converted skills. When
none exist, ask, and offer `.claude/skills/` and
`.agents/skills/`. `.claude/skills/` is a directory sessions on
both hosts already read. `.agents/skills/` is the host-neutral
name. The playbook directory is `playbooks` beside that skills
directory.

## The move

Split each source by job.

Why explains a constraint: the purpose, and the reason a rule
exists. On the full path it stays in that instruction file. On
the shadow path it stays where it was. The instruction file is
not edited, and the why is not copied into a second always-on
file.

What is a fact, a table, or a rule about a subject. It becomes a
skill, grouped with the other facts for that subject.

How is an ordered procedure for a kind of task. It becomes a
playbook. A procedure that only makes sense inside one subject
stays in that subject's skill.

Group by subject. A subject is the thing the paragraphs are
about. Do not make a skill per heading. Do not make a skill whose
body is one sentence when that sentence belongs with a subject
already being written.

A project skill is one directory under the skill root with one
`SKILL.md`. The description is one physical line and says when
the skill applies. The wording is original and follows
`kobold-codex`. The file names no host tool. These files are not
skills in this plugin, and they do not bump this plugin's
version.

Group the project skills by this plugin's phases: ground,
investigate, plan, build, review, ship, session, learn, write, and
setup. A skill that fits none takes a group named for its subject.
The skill directories stay one level under the skill root, so a
project needs no layout of its own. Name each
skill's group when you report what was written. When the project
keeps a list of its skills, the groups are its headings.

A project playbook is a Markdown file in the playbook directory.
It has a title and headings. The text under a heading is the
procedure. It has no frontmatter. The files in the plugin
playbook directory stay the files for the task kinds they already
name. A project playbook does not reuse one of those names.

On the full path, every instruction file that had a why keeps
that why, rewritten in the same voice, plus one pointer. The
pointer says this repository uses Kobold Codex, and it names the
skill root. Put that pointer in each root instruction file that
remains, so a session that reads any one of them still finds
Kobold. Delete an instruction file that has no why left. When
that deletion would remove the last root instruction file, keep
one root file and let the pointer be its body. When the
repository had both `AGENTS.md` and `CLAUDE.md`, minimize both.
When it had neither, An empty tree creates `AGENTS.md` and does
not also create `CLAUDE.md`. A command file is an ordered
procedure. It becomes a playbook, unless that procedure only
makes sense inside one subject, in which case it stays in that
subject's skill. On the full path the command file becomes a
one-line pointer at the playbook or the skill that received it.
On the shadow path, command files stay as they are.

A sentence that sets a bound stays in the source until The bounds
has recorded the suggestion. After the user accepts a key, the
full path does not also leave that sentence in the instruction
file as a second copy of the key. The sentence's why can stay.
The value lives in the bounds file `set-the-bounds` writes.

Show the file map before writing. The map names each source, each
skill or playbook it will become, and each instruction file the
full path will edit. Write after the user accepts the map. The
choice of path is part of that acceptance.

When the user marks plans or specs tracked, leave that directory
visible to the project repository. When the directory is empty
and tracked, add a `.gitkeep` so the folder stays in git. A local
directory is created on disk and hidden by The local repo, with
no `.gitkeep`.

The plan directory is the one `write-the-plan` would use. The
spec directory is the one the project already uses for design
specs. When the project has neither, the paths are `docs/plans/`
and `docs/specs/`. A config repo keeps those paths and holds the
local files behind the symlinks in The local repo. When a
directory already has tracked files, record it as tracked and
do not ask. Ask only when the directory is absent or untracked.
Suggest tracked for plans, because `commit-plans` defaults to
`ask` and a plan is how the next session finds the work. Suggest
tracked for specs, because `commit-specs` defaults to `ask` and a
spec is the record of a decision.

## The requirements

Ask where the project's requirements live: nowhere yet, in Markdown
files, or in a requirements tracker. When a tracked directory of
requirement files already exists, record it and do not ask. The
`specs` key is the directory for design specs, the records of
decisions. It never names requirements. When the repository's
`specs` path holds requirements, say so and suggest moving that
path to `requirements`.

The `requirements` key is a mapping. `source` is `markdown` or
`tracker`. For `markdown`, `path` is the directory, `specs` when
the user names none, and `tracked` is `true` or `false`. For
`tracker`, `url` is the tracker's base address, `project` is the
project key, and `token-env` is the neutral name of the
environment variable that holds the token. `token-env` is required
for a tracker. The record holds that name and never the token; each
agent exports its own credential under it. `transport`
is optional and defaults to `[mcp, rest]`. `mcp-url` defaults to
`<url>/mcp`, and `openapi` defaults to `/api/openapi.json`. The
tracker source creates no directory. The key is omitted when the project
has no requirements. `kobold-codex` says how a session reads them.

## The bounds

After the sources are read, and in the same question set as the
path and the skill root, show a table. The columns are the key,
the suggested value, the file and the sentence that suggested it,
and the value that applies if this repository writes nothing.

Suggest a key only when a sentence is about the action that key
controls. `model` and `model-fast` are the exception below.

A file that forbids commits outright suggests `commit: never`. A
file that says to commit without asking suggests `commit: auto`.
Anything softer, including commits that depend on the branch,
suggests `commit: ask`. The same three values apply to `push`,
`commit-plans`, and `commit-specs`, using the sentences about
those actions.

Always opening a pull request suggests `pull-request: auto`.
Opening one only when asked suggests `pull-request: ask`. Never
opening one suggests `pull-request: never`. A ban on merge
suggests `merge: never`. Merge only when asked suggests
`merge: ask`. A ban on rewriting the remote suggests
`force-push: never`. A rewrite only when asked suggests
`force-push: ask`.

Work that continues through publish while the user is away
suggests `unattended: through-publish`. Stopping at the plan
suggests `unattended: stop-at-plan`. Editing and checking
without publishing suggests `unattended: safe-steps`. A ban on
other agents suggests `subagents: deny`. Permission to start
them without an ask suggests `subagents: allow`. A sentence that
still requires an ask suggests `subagents: ask`. The same three
readings apply to `browser`, `shell-network`, `github-write`,
and `worktrees`.

The suggestions for `model` and `model-fast` come from the host
this session runs on. Name models from the list that host offers.
Suggest the strongest for `model`, and a faster, cheaper one for
`model-fast`. The source column names the host's list. When the
session cannot read that list, the two rows show no suggestion,
and the reply says so. A source sentence that names a model is
shown beside the host's suggestion. Ask which value.

A branch policy the keys cannot express is not a suggestion. It
stays a skill or a playbook, and the reply names the sentence.
Two sentences that suggest different values for one key are both
shown. Ask which value. A key with no sentence, other than the two
model keys, has no suggestion. Its row shows the inherited value.

Ask which layer, with the suggestion from The choice, and which
keys to write. For `model` and `model-fast`, suggest
`.kobold/bounds.local.yaml`, because a name one host offers may
not exist on the other. The user can name the committed layer
instead. Then `set-the-bounds` writes only the keys the user
named, on the layer they named for each, at the project root.
When the user names no keys, write no project bounds file. That
includes a user who keeps the inherited values.

## The rigor level

Suggest how much review the project needs, from a fixed scale:

- `standard`: a break is an inconvenience.
- `elevated`: a break costs users data, money, or time they cannot
  get back.
- `safety-critical`: a break can harm a person, or a safety class
  or a regulation governs the project's failures.

For the suggestion, read the README and the other docs at the
repository root, and the instruction files The sources read. Do
not read deeper into the tree. Those docs inform the level only.
They stay out of The move.

Suggest the level the read supports, and name the sentences it
rests on. A source that names harm to a person or a safety class
suggests `safety-critical`. A source that names a regulation, a
certification, or an audit suggests at least `elevated`. When
nothing points higher, or there is nothing to read, suggest
`standard` and say so.

Ask which level, in the same question set as The bounds. The
user's answer is the level. Write nothing for the level before
that answer.

The level lives in the `project-review` skill, on its own line.
Bounds hold what a session may do. The level is a review rule. A
project with no `project-review` skill is at `standard`.

## The review skill

The confirmed level decides the suggestion for the `project-review`
skill under the skill root. It is the skill `review-the-diff`
reads.

At `standard`, suggest no `project-review` skill. When a source
states review rules, such as paths a review skips, suggest the
skill with those rules and the level.

At `elevated`, suggest the skill with the level, what blocks the
merge, a nit cap of ten, and reviewers for `stress-the-change`.

At `safety-critical`, suggest the same parts with a nit cap of
five, and a line that gives every finding three verifiers.

Each reviewer names a goal to break the change, the paths it
covers, and what blocks the merge for it. Propose a reviewer for a
failure the sources show the project can have, and name the
sentence behind it. Do not add what a regulation requires beyond
what the source says. The user keeps, edits, or drops each part.

Review rules a source already states land in this skill, as the
what for the subject of review. The skill goes in the file map, and
it is written only when the user accepts the map. When the project
already has a `project-review` skill, leave it, and show the
suggestion beside it.

## The local repo

When the user keeps the specs out of the project repository, ask
two more questions before writing. Ask the same two questions
when the specs are tracked and another Kobold path is staying
out, so the choice is made once for every path this run keeps out
of the project. When every Kobold path is tracked, skip this
section.

The first question is how the project repository should leave
those paths alone. Gitignore puts the patterns in the project's
ignore file. That file is committed with the project, so the team
receives the patterns. Git exclude puts the patterns in
`.git/info/exclude` for this clone. That file stays in the clone.
It is not a commit in the project.

One answer covers every path this run is keeping out. The paths
are the local spec directory, the local plan directory, the
shadow skill root or the new skill directories, the shadow
playbook paths, `.kobold/adopt.yaml` when the record stays out,
and the config repo directory when one is created. Append a
pattern when that path is not already ignored. Gitignore creates
the ignore file when the repository has none. Exclude appends to
`.git/info/exclude`. Do not write the same pattern in both
places. Do not add `.kobold/bounds.local.yaml`. Do not add
`.kobold/trail.md`. A path that is already tracked is not hidden.
This skill does not untrack it.

The second question is whether a separate git repository should
keep the history of the skills and the config. Suggest
`.kobold/local` as its root. The user can name another directory.
That directory is the repository root. The same hide choice
covers it. A decline leaves the local files in place in the
project tree, hidden and without their own history.

The config repo tracks the Kobold files this run is keeping out
of the project: local specs, local plans, local skills, local
playbooks, and the adopt record. Skills that the project
repository tracks stay there. The config repo has its own root
so its bounds file is not the project's bounds file.

A session loads skills from a scanned skill root. When the skills
live in the config repo and the skill root has no tracked files,
that root is one relative symlink to `<config-repo>/skills`, and
the playbook directory is one relative symlink to
`<config-repo>/playbooks`. The hide choice covers both symlinks.
When the skill root already has tracked files, leave that root
and the playbook directory in the project. Each new skill
directory is a relative symlink to its directory under
`<config-repo>/skills`. Each new playbook file is a relative
symlink to its file under `<config-repo>/playbooks`. The hide
choice covers those new paths and leaves the existing directories
visible. The recorded skill root and the recorded playbook
directory stay those project paths. The recorded plan directory
stays the path `write-the-plan` would use. The recorded spec
directory stays the path the project already uses for design
specs. When a config repo holds the local plans, that project
path is a relative symlink to `<config-repo>/plans`. When a
config repo holds the local specs, that project path is a
relative symlink to `<config-repo>/specs`. The hide choice covers
those symlinks. `write-the-plan` then writes through the plan
path it already discovers, and the file lands in the config repo.
The adopt record that sessions read stays `.kobold/adopt.yaml`.
When the record lives in the config repo, that path is a relative
symlink to `<config-repo>/adopt.yaml`, and the hide choice covers
the symlink.

The config repo starts with `git init` in its root. Do not add a
remote unless the user names one.

Its bounds are a second table, for that repository only. The
project's bounds do not govern it. Its bounds do not govern the
project. The user config file still sits behind both
repositories. A key written in the config repo replaces the user
config value for that repo only. Suggest `commit: auto`, because
the repo exists to record local history. Suggest
`commit-specs: auto` when the specs live there. Suggest
`commit-plans: auto` when the plans live there. Suggest
`push: never`, `pull-request: never`, `merge: never`, and
`force-push: never`. Leave every other key with no suggestion
and show the inherited value. Do not copy a suggestion that came
from the project's instruction files into this table.

Ask which of those keys to write. Suggest the committed layer of
the config repo, `.kobold/bounds.yaml` at the config repo root.
`set-the-bounds` writes only the keys the user named, at that
root. When the user names no keys, write no bounds file in the
config repo.

After that write, the first commits in the config repo follow
`set-the-bounds` at the config repo root. Resolve `commit`,
`commit-plans`, and `commit-specs` there. Name each key, the
value, and the layer. `commit` stages the work and leaves plans
and specs to their own keys. Each set that is `auto` is its own
commit. Each set that is `ask` is offered on its own. Each set
that is `never` stays unstaged. The project's keys are not the
keys for these commits. Do not push the config repo during setup
unless the user named a remote and the `push` key resolved at
the config repo root allows it.

## An empty tree

When the read finds no instruction files and no skills, skip The
move's conversion. Still ask the path, the skill root, the bounds
table, the rigor level, the plans and specs question, and The
local repo when a path will stay out of the project.

Create the skill root, the playbook directory, the plan
directory, and the spec directory. A path the config repo holds
is a real directory inside that repo, and the project path is
the relative symlink The local repo names. A path it does not
hold is a real directory in the project. Apply the hide choice.
Write `.kobold/adopt.yaml`.

On the full path, create `AGENTS.md` at the repository root. Its
body is the pointer, unless the user supplies a why sentence, in
which case the why comes first and the pointer follows. Do not
invent a product purpose. On the shadow path, create no
instruction file.

The bounds table on an empty tree has no file sentences. Every
row other than `model` and `model-fast` shows the inherited value
and no suggestion. The two model rows show the host's suggestions.
Writing still waits for keys the user names.

## The same repo

A second run reads `.kobold/adopt.yaml`. The recorded path, the
hide choice, and the config repo stay. Ask again only when the
user names a different path, a different hide choice, or a config
repo after declining one. Read the sources again. Leave a skill
or a playbook whose source would produce the same file. The rigor
level in `project-review` stays, and a project with no such skill
stays at `standard`. Ask the level again only when the read
suggests a different one or the user names one. Convert
a source that changed. On the shadow path, do not write
instruction files on the second run either. A new local file goes
into the config repo when one is recorded, and that commit
resolves `commit`, `commit-plans`, and `commit-specs` at the
config repo root. An empty tree that now has
the folders and the record is done. Name those files.

The choice stops before the questions when this repository is the
`kobold-codex` plugin. A second run stops there too.