---
name: ctxfr-init
description: Initialize, adopt, or refresh ctxfr context for Codex or Claude. Use when the user asks to scaffold ctxfr, create CLAUDE.md or AGENTS.md, adopt existing project guidance, or the equivalent of /ctxfr-init.
---

# ctxfr Init

Use the requested path as the target, or the current directory if none is provided. Non-git directories are supported.

New ctxfr projects use `docs/`, `docs/adr/`, `docs/decisions.md`, `agents/`, and `templates/` as the authored Markdown surface. Do not create canonical specs, ADRs, decisions, agents, or cache state under `.ctxfr/`.

If `ctxfr` is not found, tell the user: `The ctxfr binary is not installed. Run cmake --build build && cmake --install build from the ctxfr repo.`

## 1. Detect Context

Run `ctxfr env <target>` and use the resulting project root and git status. Survey the target for:

- `CLAUDE.md`
- `AGENTS.md`
- `docs/`, `docs/adr/`, `docs/decisions.md`
- `agents/`
- `templates/`
- legacy `.ctxfr/` content to import or leave untouched
- language and build files
- whether the target is a scoped subdirectory

Prefer keeping `AGENTS.md` and `CLAUDE.md` equivalent. A symlink is acceptable when the platform and repo policy support it.

## 2. Branch by State

- Fresh: no constitution and no current docs layout; create constitutions and scaffold the current layout.
- Adopt: constitution exists but docs layout is incomplete; extract detailed docs, decisions, agent guidance, and glossary terms into the current layout, then rewrite the constitution with confirmation.
- Legacy import: `.ctxfr/` exists; inventory it and propose moving artifacts to `docs/`, `docs/adr/`, `docs/decisions.md`, and `agents/` without deleting legacy files unless the user approves.
- Refresh: current layout exists; fill missing templates, keep constitutions local-only, reconcile decisions, and flag inline docs that should become specs.

When both `CLAUDE.md` and `AGENTS.md` are present, keep them aligned. If one is a symlink to the other, edit the target.

## 3. Ensure Structure

Ensure these files exist without overwriting populated files:

```text
CLAUDE.md
AGENTS.md
docs/
  decisions.md
  context-infrastructure.md
  context-metrics.md
  glossary.md
  adr/
agents/
templates/
  spec.md
  adr.md
  agent.md
```

## 4. Create Initial Specs

Identify the top 3-5 important subsystems. For each, create a stub spec under `docs/` with name, one-line description, and File Coverage. Do not add ctxfr jump tables to `CLAUDE.md` or `AGENTS.md`; installed ctxfr agents should use retrieval commands instead. Run `ctxfr cache snapshot <spec-path>`.

## 5. Report

Report path, scope type, git status, created files, extracted content, legacy import notes, stub specs, and next steps. Ask for confirmation before any adoption or refresh that rewrites existing constitution content.