ctx-init

---
name: ctx-init
description: Initialize AGENTS.md + CLAUDE.md + rules/ in a code repo (fresh mode). Triggers on "/ctx-init", "init context", "scaffold AGENTS.md", or when user asks to set up project context in a new repo.
---

# ctx-init — context initialization in a repo

Creates the `ctx` structure in the current repo:
- `AGENTS.md` from template with frontmatter (all `@`-imports are relative `@./rules/...`)
- `CLAUDE.md` with `@AGENTS.md` import
- `rules/` with copies of shared plugin rules (`language`, `dates`, `git`, `no-secrets`, `no-public-names`) **plus** project-specific stubs (`stack`, `testing`, `boundaries`, `focus`)

Both shared rules and templates exist in two language variants: `en/` (English) and `ru/` (Russian). The user picks one at init time. Shared rules are copied rather than imported via `$PLUGIN_ROOT` because Claude Code **does not expand** env variables in project-level `@`-imports (and this is needed for cross-agent compatibility: Codex/Gemini/Cursor all read the same `AGENTS.md`).

## Input (ask the user before running)

1. **project** — short name (e.g. `MYAPP`, `API`, `DOCS`).
2. **description** — one line describing the project topic.
3. **language** — `en` or `ru` (default `en`). Determines the language of `AGENTS.md` headers, the 5 shared rule files (`language`, `dates`, `git`, `no-secrets`, `no-public-names`), and the 4 project stubs (`stack`, `testing`, `boundaries`, `focus`).

## Procedure

**Pre-flight checks:**
1. `pwd` must be the root of the repo being initialized.
2. If `AGENTS.md` already exists — **stop and tell the user** that migration is not supported. Ask the user to rename the old file manually (`mv AGENTS.md AGENTS.md.legacy`) and call `ctx-init` again.

**Actions** (replace `<LANG>` with the chosen `en` or `ru`). Resolve the plugin root first — `CLAUDE_PLUGIN_ROOT` can be empty under Codex:

```bash
PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-<installed-plugin-root>}"
```

`ctx-lint` parses frontmatter with PyYAML. If `python3 -c 'import yaml'` fails, run the commands below as `uv run --with pyyaml python3 …` (or install it: `python3 -m pip install pyyaml`).

1. Copy `$PLUGIN_ROOT/templates/<LANG>/AGENTS.md.template` to `./AGENTS.md`.
2. Substitute `{{PROJECT}}`, `{{DESCRIPTION}}` via `sed`.
3. Copy `$PLUGIN_ROOT/templates/<LANG>/CLAUDE.md.template` to `./CLAUDE.md`.
4. Create `./rules/`.
5. Copy **shared rules**: `$PLUGIN_ROOT/rules/<LANG>/*.md` to `./rules/`.
6. Copy **project stubs**: `$PLUGIN_ROOT/templates/<LANG>/stubs-repo-rules/*.md` to `./rules/` (without overwriting shared files).
7. Run `python3 $PLUGIN_ROOT/lib/ctx-lint.py <repo>` — verify all `@`-imports resolve (0 errors).
8. Show the user what was created, and ask them to fill in `stack.md`, `testing.md`, `boundaries.md`, `focus.md` inside the project `rules` directory.
9. Do not commit automatically — user reviews and commits themselves.

## Example invocation

```
User: /ctx-init
Agent: "Ready to initialize context. Answer 3 questions:
  1. project name (MYAPP/API/DOCS/...)?
  2. description (short project topic)?
  3. language for rules and AGENTS.md headers (en/ru, default en)?"
```

After answers — executes steps 1–7 and shows the diff.

• SKILL.md 3 KB
• agents/openai.yaml 1 KB