anchors init

Configure the project (anchors.yaml) through questions and answers.

Scans the project deterministically (without AI), proposes a
Structure, and confirms/adjusts it with you through questions — arriving at a correct
anchors.yaml. The bulk is inferred; the questions cover only the human decisions
(co-location, layer granularity, and which guides govern which tags).

Usage

anchors init [flags]

Flags

Flag	Default	What it does
--artifacts		anchor kinds of the project (spec,feature,test,…)
--colocation		derived files next to the code
--contributing	true	seed CONTRIBUTING.md when the project has none
--defaults		with –non-interactive and no answers: accept the defaults inferred from disk
--gates	true	seed the default gates (informational)
--governs		governs rule: GUIDE=tag1,tag2 (repeatable)
--header	true	seed guides/HEADER_GUIDE.md
--labels		labels that mark the Anchors cards (required in github mode)
--layers		code directories to treat as layers
--non-interactive		no TUI: with no answers, emit the questions as JSON; with answers in flags, apply them
--repo		repository owner/name (required in github mode)
--root	.	project root
--workflow		where the work queue lives: local|manual|github (manual: like local, and no command writes an issue on its own)

Setup and artifacts — family

Commands of the same family — what tells each apart:

Command	What it does
anchors init	Configure the project (anchors.yaml) through questions and answers
anchors new	Emit the skeleton of an artifact (spec, feature, test, plan…) per the ruler
anchors code	Generate a unique identity code for a new unit
anchors guide	Print the Anchors guides for AI agents
anchors docs	Compile the documentation from the templates in doct/
anchors install-hooks	Install the git pre-commit that runs the gates over staged files
anchors migrate	Bring the Anchors files up to the current format
anchors settings	This agent’s LOCAL configuration — what is its own, not the project’s
anchors touch	Bump updated_at in the @anchors header of the files that changed

---

---

---

---

---

Starting a new project or onboarding an existing codebase into Anchors begins with anchors init. It reads the project as it is and asks only the decisions that are yours.

---

1. Project Initialization (anchors init)

# Interactive setup
anchors init

# For an agent or a script: first the questions, as JSON…
anchors init --non-interactive
# …then the answers, as flags
anchors init --non-interactive --artifacts=spec,feature,test,code --colocation
# or accept every default inferred from disk
anchors init --non-interactive --defaults

anchors init:

1. Proposes no structure. Anchors does not care how your folders are arranged — only that the layers are kept apart. Every folder that holds code is a candidate layer, named after the folder, and you keep the ones that are layers. Layer kinds such as entry points, use cases, domain, repositories, infrastructure, presentation are given as illustration, never as a layout to move files into.
2. Reads the language as dialect. The family comes from the manifest at the root (go.mod, package.json, pyproject.toml…) or the most frequent extension, and the test naming from your own test files (*_test.go, *.spec.ts, test_*.py…). It is written to dialect.family, so the gates read your tests and comments from the first check.
3. Seeds the gates related to your layers — a gate is seeded when a declared layer is of a kind it measures and the fields it presupposes are declared. The rest of the catalog that covers your layers is listed by anchors doctor.
4. Seeds CONTRIBUTING.md from the configuration it writes: the order of the work (spec → feature → test → code), the declared layers, the daily commands and which gates bar a commit. A CONTRIBUTING.md you already have is never touched; the section that would be added is shown instead.
5. Seeds the header guide and writes anchors.yaml.

When it seeds gates with run:, it also says how to write a gate step that does more than call one tool: in the project’s language (go run ./tools/gates <gate>, node tools/gates.mjs <gate>, python -m tools.gates <gate>), not in shell — a shell script breaks on the platform.

Flag	What it answers
--artifacts	the anchor kinds the project uses (spec,feature,test,code,guide,plan)
--layers	the code folders to keep as layers
--colocation	the spec, feature and test sit beside the code
--gates	seed the default gates (true)
--header	seed the header guide (true)
--contributing	seed CONTRIBUTING.md when the project has none (true)
--workflow, --repo, --labels	where the work queue lives: local, manual or github
--governs GUIDE=tag1,tag2	which tags a guide governs

---

2. Scaffolding Artifacts (anchors new)

Generate an artifact with its @anchors header and identity already resolved. --out is mandatory: the artifact is born next to the unit it describes.

# A spec gets a new unique code
anchors new spec Invoice --out src/billing/invoice.spec.md

# A feature or a test gets a ref to the spec
anchors new feature Invoice --out src/billing/invoice.feature --code INVCE

# The sections a kind offers, and its presets
anchors new spec --list-sections

---

3. Git Hooks (anchors install-hooks)

anchors install-hooks

Installs the pre-commit that runs the gates over what is staged, so a commit that fails a blocking gate does not land.