Skip to content
Skills Library
Programming · Automation

init

/init

Bring a repository under CLM. Sets up its tooling with clm init and proposes its first spec graph, drafted from a short conversation for a new project or recovered from the code for an existing one. Use when the user wants to adopt CLM in a repository without specs/SPEC.md.

Repository
clm ↗
Licence
MIT
Last repository change
13.11.2026

Assessment and security

80/ 100Class: good
Format9 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content31 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Bring a repository under CLM. Sets up its tooling with clm init and proposes its first spec graph, drafted from a short conversation for a new project or recovered from the code for an existing one. Use when the user wants to adopt CLM in a repository without specs/SPEC.md.

Original author description

Bring a repository under CLM. Sets up its tooling with clm init and proposes its first spec graph, drafted from a short conversation for a new project or recovered from the code for an existing one. Use when the user wants to adopt CLM in a repository without specs/SPEC.md.

How it works

SKILL.md has no level-two headings · 35 lines, 3,125 words

SKILL.md preview
---
description: Bring a repository under CLM. Sets up its tooling with clm init and proposes its first spec graph, drafted from a short conversation for a new project or recovered from the code for an existing one. Use when the user wants to adopt CLM in a repository without specs/SPEC.md.
---

# Bring a repository under CLM

Set the repository up for CLM, then propose its first spec graph as one spec branch that needs the human's approval (`init-cli-and-skill`). `clm init` writes what is the same for every project; this skill holds the conversation and the drafting.

1. Look at the repository: `git rev-parse --show-toplevel` (CLM needs a git repository; if there is none, tell the user and stop), `git ls-files`, and whether `specs/SPEC.md` exists. If it does, the repository is already under CLM: tell the user so and suggest `/clm:propose` for what comes next, without running `clm init`. The repository **has code** when `git ls-files` lists source files.
2. Hold a short onboarding conversation. Run `clm superpowers brainstorming` and follow the skill at the path it prints, one question at a time, to learn:
   - what the project is about: who it is for and what it does;
   - what a person can do with it: its first capabilities;
   - what must always hold, and what it must never do: its architectural constraints;
   - the language and stack.

   For a repository with code, read its README and manifests first and ask only what they don't answer. The skill's design doc becomes the init change's `change.md` body (step 6). Never write under `docs/superpowers/`, never hand over to `writing-plans`, and don't invoke the installed `superpowers:brainstorming` skill. If `clm superpowers` fails, tell the user and ask the four questions yourself.
   Before running `clm init`, tell the human that a lockfile counts in full toward its component's code size until `.gitattributes` marks it `linguist-generated` or `linguist-vendored` (`check/node-size`), so an unmarked one can make a component read as oversized when it isn't. Propose, for the human to confirm, one line `<name> linguist-generated` in the repository's root `.gitattributes` for each lockfile name that needs one, the name written bare so it marks a file of that name at any depth: for a repository with code, the name of each tracked lockfile that `git check-attr linguist-generated linguist-vendored` reports neither `set` nor `true`; for a new project, the lockfiles the stack's package managers will write, such as `Cargo.lock`, `package-lock.json` or `uv.lock`. On a yes, write the lines before running `clm init`, so `.gitattributes` is among the files the bootstrap commit holds and `clm init`'s root component covers it; on a no, write nothing.
3. Run `clm init --lang <language>` with one `--lang` per language of the stack, adding `--no-detectors` when the repository has code, so its existing dead code doesn't fail `clm check` before the components' builds clean it up. Tell the user what it writes: `clm.toml`, `scripts/clm-check.sh` and, where missing, `ARCHITECTURE.md`, `CAPABILITIES.md`, `specs/SPEC.md` and `CLAUDE.md`. With code, the root component in `specs/SPEC.md` holds `paths` for those files and lists the rest of the code under `outside`, the code no component owns yet. Once `clm init` has written `scripts/clm-check.sh`, tell the human that CLM builds several components at once on one machine, so the project's tests, and its check script with any server the script starts, must pass while other runs of them overlap (`tests-run-concurrently`): no fixed port, no fixed path outside the checkout and the system's temporary directory, and no server or database shared between two runs (a shared database is what to look for). A port or path that must be known in advance is keyed on `CLM_SLOT`, the number CLM gives each build and its checks.
   Once `clm init` has written `clm.toml`, ask the human whether the project has tests too slow to run on every land (`verify-after-land`). On a yes, ask which command runs them, where they run (`local` on the developers' machines; `pipeline` in the host's pipeline, which then records the result itself and needs the right to push `clm/ledger/*`; or `import`, where the pipeline only reports and `clm verify` reads its runs) and which triggers to use (`change-done`, `queue-drained`, `work-done`, `every`), recommending `change-done`. Then replace the commented `[verify]` section of `clm.toml` with those settings, keep those tests out of `[land] check`, and, for `pipeline` and `import`, say what the host's pipeline must run, naming `clm guide ci-and-deployment`. On a no, leave the section commented.
   Once `clm init` has written `clm.toml`, tell the human that each CLM build runs in a fresh worktree inside the main checkout with nothing installed, and that its tests must run against that worktree's own code and dependencies, never the main checkout's (`tests-run-in-their-own-tree`): a toolchain whose lookup walks up the parent directories, or an environment the checkouts share, would otherwise find the main checkout's packages or source. So the project declares in `clm.toml`'s `[build] setup` the command that makes a fresh worktree ready to run its tests, which `clm setup` runs before a build's first test run. For a repository with code, work out from the project's toolchains and how its tests find their dependencies whether a fresh worktree needs such a command, propose one for the human to confirm, and write it into `clm.toml` when they agree before the bootstrap commit, which then holds it as it holds the `[verify]` settings, never on the spec branch: `clm init` puts `clm.toml` in the root component's `paths`, so an edit to it on the spec branch makes that branch `mixed`.
   Once `clm init` has written `scripts/clm-check.sh`, tell the human that a land whose code was already checked runs only `clm check` and the tests whose `clm:reads <glob>` markers match a file the branch changes, so every test that reads a file of the repository's own tree (not a fixture's) at `ARCHITECTURE.md`, `CAPABILITIES.md`, `CLAUDE.md`, `README.md` or a file under `specs/`, `changes/`, `backlog/` or `docs/`, or that reads the repository's own `clm.toml`, holds such a marker, usually a comment, whose glob matches each such path it reads; an unmarked one lets a spec branch that breaks it land and leaves `main` failing every later code land's check (`land-checks-stay-fast`). For a repository with code, look through the existing tests for ones that read such paths and add each one's markers in the bootstrap commit, whether or not step 4 moves any CI steps there, never on the spec branch, whose code paths would make it `mixed`.
4. For a repository with code, list its existing CI workflows: GitHub's under `.github/workflows/` and Azure Pipelines' (`azure-pipelines.yml`, and pipeline YAML the repository holds elsewhere, such as under `.azure-pipelines/`). `clm land` lands a branch on the checks it runs here, `scripts/clm-check.sh` before `clm check`, so a test that only a workflow runs could fail and the branch still land. Before changing anything, warn the human: name each workflow, which of its build and test steps move into `scripts/clm-check.sh`, and that the workflow is then removed (for a pipeline that also deploys, only its build-and-test stages). Deploy, release and scheduled workflows and pipelines stay (`deploy-is-downstream`). Tell the human, too, that the host's required checks or build-validation branch policies stop being the gate once `clm land` lands; that the identity running `clm land` must be allowed to push a protected `main` (on Azure DevOps, `Bypass policies when pushing`); and, for each deploy workflow or pipeline triggered by a push to `main` with no path filter, that spec-only lands (`specs/`, `changes/`, `backlog/`) trigger it too, so suggest a path filter. Never change a branch policy, a protection rule or a pipeline's settings on the host: those are the human's. Once they agree, move the steps into `scripts/clm-check.sh` (keep it runnable with `bash`, `set -euo pipefail`), delete those workflows (for a pipeline that also deploys, edit out only its build-and-test stages instead), and run the script once to see it pass. These are code files, so they go in the bootstrap commit, before the spec branch is cut, never on the spec branch, whose code paths would make it `mixed`. Before committing, take out of the root's `outside` in `specs/SPEC.md` any glob that no longer matches a file, such as `.github/**` once its workflows are gone, so the bootstrap commit passes `clm check`. Keep the list of what moved for `## Intent` (step 6).
5. Stop for the bootstrap. Make the bootstrap commit on `main` with everything so far, then show the human `clm init`'s `Next steps (yours):` lines verbatim. The guard blocks you from pushing to `main` (`guard-blocks-push-to-main`), so the human pushes this one commit to `main` themselves, then does the other steps; once they say it's done, and when the repository has an `origin`, run `git fetch origin` and check that `origin/main` has `clm.toml` or `scripts/clm-check.sh`. With no `origin` there is nothing to check.
6. Cut the spec branch in a worktree of its own (`session-worktrees`), never switching the checkout you started in: run `git worktree add .claude/worktrees/<YYYYMMDD>-init -b spec/<YYYYMMDD>-init origin/main` (with no `origin`, from `main`), change into `.claude/worktrees/<YYYYMMDD>-init`, and do all later work there. Write `changes/<YYYYMMDD>-init/change.md` with `status: proposed` and a body that starts with `## Intent`, then the onboarding's design doc. Under `## Intent`, besides what the change does, list the workflows step 4 removed and what moved into `scripts/clm-check.sh`, what stays `outside`, and, with code, that the detectors are off until the root component's build.

   Draft the human layers directly in the spec branch, not as deltas: add the project's architectural constraints to `ARCHITECTURE.md`'s `## Constraints`, each a `### Constraint: <slug>` with SHALL or MUST and a scenario, and a few capabilities to `CAPABILITIES.md`'s `## Capabilities`, each a `### Capability: <slug>` with one sentence of what a person can do, a `#### Why` and a scenario, from the conversation or, with code, from what the code does for its users, adding either section at the end of a file `clm init` kept that lacks it (the format is in `clm guide spec-format`); keep the component map in the root component's Design, never in `ARCHITECTURE.md`; give each architectural constraint an `#### Enforced by` block naming the rules of the drafted components that enforce it, or an `#### Untested` block saying why no program can check it, or both for an entry that is part mechanism and part judgement (`human-layer-proof`); unlike the layers, draft the component `capability`, `specs/capability/SPEC.md`, as a delta with `create: true` like the other components' below, with no requirements of its own, whose Design names the project's public boundary and the harness its capability tests drive, and whose `paths` hold those tests and no other component's files, putting it in the component map with the other components (with code, in the map `clm survey --components` checks); and say in `change.md` that the `capability` component's build proves the capabilities with tests citing `req:capability/<slug>@<version>`. An `#### Enforced by` block names, for a property of every file, the whole-tree check that reads them all, and, for a choke point, the one path plus each blocked bypass; a test never cites an architectural constraint, which is current when every rule its block names is current, and `clm check` fails an entry with neither block (`check/unenforced`). A capability is proven by a test of the component `capability` at the project's public boundary, deterministic, with what lies beyond the boundary (a model, the network) stubbed.

   Before drafting the component map, explain the graph's shape to the human in a few sentences (`first-graph-teaches-shape`): a component is the unit one build session holds, its spec and its code, so it is sized to that; a component splits along seams, by nesting the carved-out part as its child; plumbing that several components copy becomes a shared component; and a component over its size budget is a visible state, not an error. Point them at `clm guide shaping-the-graph` for the rest, and draft the map by those rules. Then draw the spec graph:
   - **A new project:** draft it from the conversation. Choose a few components, each with a one-line responsibility, and list them in the component map in the root component's Design. Write one `deltas/<component>.md` per component with `component: <id>` and `create: true` in its frontmatter, and the sections `## Frontmatter` (a yaml fence with `title`, `status: unbuilt`, `owners`, `depends_on`, `paths` and `serves`), `## Contract`, `## Design` and `## ADDED Requirements`, each requirement with at least one scenario. Write the root component's delta (its ID as `clm status` lists it) with `## MODIFIED Contract` and `## MODIFIED Design`, their bases from `clm hashes <root>`. Each component's `serves` names the capability and architecture entries its rules serve, and a rule whose purpose differs from its component's gets a `#### Serves` block (`- <id>` lines) that replaces the component's list for it: once either layer holds an entry, `clm check` fails a rule that serves nothing (`check/untraced`), so draft the layers' entries before the components'.
   - **A repository with code** (`brownfield-survey`): first ask the human whether to adopt all of the code now or one part first (`incremental-adoption`). Say the trade-off: one part makes a smaller first review and a change that finishes once that part's tests cite its requirements, while the code left `outside` every component has no requirements, so no test proves it to CLM and nothing reports its drift until a later change gives it a component; each later change widens the graph by adding a component and taking its globs out of the root's `outside`. Then build the component map. Run `clm survey` and draft a component map from it and the docs: components with `paths`, `depends_on` and a line of responsibility each, with an entry for the root component holding the `paths` `clm init` gave it, and the part left for later, when the human chose one, as the map's `outside` globs, written as a YAML file `{ components: [{ id, paths, depends_on }], outside: [<glob>] }` outside the repository's tracked files. Run `clm survey --components <file>` and revise the map until it reports nothing. Then show the human the map (components, paths, dependencies, responsibilities, and what stays `outside`) and revise it until they agree: boundaries are the costliest thing to get wrong and the cheapest to fix now. Only then fill each component with its own subagent, launched with the `Agent` tool or the agent harness's own subagent tool and `model: "sonnet"` (`model-per-launch`): give it the component's `paths`, its dependencies' one-line responsibilities, the architectural constraints and the test-ownership rules below, nothing else, and ask it to write that component's delta (`create: true`) with its Contract, Design and requirements, and its `serves`, as for a new project. Give each component the tests that prove it with `tests` globs, by directory or by a file-name pattern, and never list test files one by one, so that a test file added later is owned (`components-own-their-tests`); give a component whose tests import the product's entry point or a shared test harness a `test_depends_on` naming the component that holds it, rather than giving the whole suite to one component; keep the shared harness (fixtures, helpers, a test app factory) in a component of its own; prefer directory globs in `paths` too, so a file added later beside a component's files is owned; and where one existing test file tests several components, give it to one of them and record a `kind: deferred` backlog item on this spec branch for splitting it, naming the file and the components. Requirements describe what the code does today, not what it should. Each bug it finds becomes a `backlog/<slug>.md` item of kind `bug` with `origin` the change, not a requirement. Look through the check script and the tests for a fixed port, a fixed path outside the checkout and the system's temporary directory, and a server or database shared between runs, and once the component map exists record each you find on this spec branch as a `bug` backlog item whose body names `tests-run-concurrently` and whose `components` name the component whose `paths` hold the fix, as you record the other bugs you find. Add the components to the component map in the root component's Design, and write the root component's delta as for a new project, with a `## MODIFIED Frontmatter` that sets `outside` to the map's `outside` globs, or to `[]` when all of the code is adopted, replacing the top-level entries `clm init` wrote. In `change.md`, say that the components' builds prove each requirement with versioned markers, by citing `req:<component>/<slug>@<version>` in existing tests or writing new ones, and remove the dead code in their components, and that the root component's build adds the detectors to `clm.toml` (the `[[detectors]]` that `clm init --lang` writes without `--no-detectors`).
7. Carry the change on with `propose`'s steps (`skills/propose/SKILL.md` in this plugin), from running `clm check` to `clm land`: `clm apply`, commit, `clm rebase` until its last line is `rebase ok` (read its outcome from that line, never from its exit code), `clm gate` (its first line is `spec review`, since the change edits `ARCHITECTURE.md` and `CAPABILITIES.md`), the builder check, the pull request with `clm pr open`, the human's approval in this conversation with `clm approve`, `clm land`, then removing the worktree and `clm wrap-up`. Pass each `left <path>: ...` line `clm wrap-up` prints to the human as it stands, a build's worktree it couldn't remove, which doesn't make the wrap-up incomplete, and leave the directory, and any command the line names, to them.
8. Before opening the pull request, review the session for CLM defects not yet reported (`defect-reports`): anything CLM itself (its CLI, gate rules, plugin, skills or method) would have to change so it doesn't happen again, not your own mistakes that CLM caught or you fixed. Report each with `clm defect --title <title> [--component <component>]...`, the report on stdin, describing only the process, never the project's files, code, specs or output, and list them under `## CLM defects` in the pull request body.
9. End with a summary: what landed, what is still open and who it waits on, and that `/clm:build` builds the first graph. Point the human at `clm guide using-clm` for the workflows and at `clm guide how-it-works` for how a change flows and where decisions go.

Run `clm agent-harness` before your first launch (`skills-follow-agent-harness`), and apply it at steps 6 and 7: it says what this session's agent harness can do. Where `subagents` is `no`, draft each component in this session itself, one at a time, instead of launching a subagent for it. Where `model-choice` is `no`, launch with this session's own model instead of naming `sonnet`. Where `confirm` is `no`, the guard can't make the human confirm `clm approve`: after the human's yes, have them run `clm approve` in their own terminal.

Never push `main` by any means but `clm land`, except that the human pushes the bootstrap commit themselves (step 5). Run `clm approve` only after the human says yes in this conversation, and only through the guard's confirmation where `confirm` is `yes`, or by the human in their own terminal where it is `no`: never route around the guard or ask another tool to do it. Only a human approves the first spec graph (`humans-review-intent`).

Versions

RepositoryScoreLicence
This page · clunny/clm80MIT
CodaColaLight/nightmill100Apache-2.0
userKael/rastro100MIT
elalfner/relevo100MIT
abatyuk/okf100MIT
duronext/jig100MIT
sh5623/e2e-rail100MIT
Calvin-LLC/skills100MIT
arxdsilva/ai-loops100MIT

Database snapshot: 13.11.2026 · package version 557023b738ca (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 80upgrade
    Bring a project up to date with the clm it runs, taking the migrations clm upgrade lists and landing them. Use when clm says a migration is pending or the human asks to upgrade the project.
  • 84propose
    Turn an intent into one CLM spec branch and land it. Use when the user wants to add or change behaviour, record a design decision, or reshape the specs in a repository with specs/SPEC.md.
  • 90specsmith-init
    Scaffolds the Specsmith specs/ structure into the current project — copies the specs/ README and the spec/plan/tasks templates from the installed plugin into the project root so prompt-grill and the spec-driven flow have a local home. Use when the user installs Specsmith and…
  • 90kelly-clm
    Lightweight contract lifecycle management App-in-Skill (Busabase App-in-Skill) for contract inventory, lifecycle status, owners, obligations, renewal notices, and simple approval reminders. Use when the user invokes $kelly-clm or /kelly-clm, mentions CLM, contract lifecycle…
  • 100adopt
    Brings an existing website or codebase into the studio: detects the stack, proposes project.yaml values, maps existing docs and code, and proposes the stage. Use when the user has an existing site, repo or partial project and wants to use the studio on it (brownfield).
  • 100spec-init
    Initialize a specification system for a project from scratch. Analyzes the codebase to identify architectural layers, domains, boundaries, and key decisions, then generates the initial set of specs (META.md, INDEX.md, domain specs, contracts, architecture docs, ADR template; a…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.