# Tooling Claude reference

## Overview

The claude stack installs the `.claude/` workflow directory into a project. State docs are seeds, written once and never overwritten by tooling. `CLAUDE.md` is a seed, filled in per project after init.

## Structure

```plaintext
.claude/
├── CLAUDE.md          ← seeded. Project context and rules, auto-loaded by Claude Code each session
├── tasks/             ← seeded then gitignored. One file per task plus a generated index.md, local scratch only. `archive/` holds the tasks that shipped.
├── REQUIREMENTS.md    ← seeded. Project goals, non-goals, MVP scope
├── ARCHITECTURE.md    ← seeded. Technical design decisions and open questions
├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
├── wireframes/        ← seeded. Per-surface ASCII layouts. `index.md` is the discovery anchor; `<surface>.md` files hold the sketches and behavior bullets.
├── diagrams/          ← seeded. Per-kind Mermaid views. `index.md` is the discovery anchor. `<kind>.md` files hold one diagram each, grouped by the `category` frontmatter field.
├── GOV.md             ← retired. Removed by `aitk gov sync` if present from a prior install
├── settings.json      ← seeded. Project-level Claude Code config (PreToolUse and PostToolUse hooks). User-level config installed separately via `aitk claude setup`.
├── plans/             ← execution detail for multi-step tasks, gitignored. `feature-*.md` entries swept by claude-docs into `archive/`.
├── review/            ← gitignored, one subfolder per producer. `branch/` for claude-review, `feedback/` for aitk feedback, `memory/` for claude-memory-review with its own `archive/`, `design/` for aitk design render.
├── .tmp/              ← ephemeral scratch space, gitignored
└── memory/            ← session facts no context entry owns, gitignored. `index.md` regenerated by a hook.
```

## Upgrading from a single-file board

A project installed before the board became a folder still holds `.claude/TASKS.md`. Nothing migrates it. `aitk claude init` seeds an empty `.claude/tasks/index.md` beside it and leaves the old file untouched, so every skill reads the empty catalog while the real board sits unreferenced.

Convert by hand, once per project:

1. Split each `###` block into `.claude/tasks/vXX.Y-<slug>.md`, adding the `title` and `description` frontmatter the tasks standard requires, which `aitk standards tasks` prints. Compare each new file against the block it came from rather than checking that every block landed somewhere.
2. Run `aitk indexes regen --no-stage --root . .claude/tasks/<any-task>.md` to build the catalog.
3. Delete `.claude/TASKS.md`, and swap its `.gitignore` entry for `.claude/tasks/`.

## Upgrading a hand-appended memory index

A project installed before the memory folder gained a generated index still holds `.claude/memory/MEMORY.md`, and its entries still carry `name` and `type` frontmatter. Nothing migrates it. `claude-memory-capture` stops appending rows once the new seed lands, so the old file freezes at whatever it held while the folder keeps growing past it.

Convert by hand, once per project:

1. Rewrite each entry's `name` key to `title` and its `type` key to a sentence-case `category`, quoting any `description` that opens with a backtick or a colon so the frontmatter parses.
2. Replace `MEMORY.md` with an `index.md` carrying `title` and `subtitle` frontmatter and nothing else.
3. Run `aitk indexes regen --no-stage --root . .claude/memory/index.md` to build the catalog, and compare its entry count against the file count before deleting anything.

## Upgrading from a single-file diagram set

A project installed before the diagram surface became a folder still holds `.claude/DIAGRAMS.md`. Unlike the board, this one migrates itself. The `claude-diagram` skill reads the flat file when `.claude/diagrams/` holds no entries, splits it by kind into the folder, and reports what it wrote. The old file stays on disk so the split can be compared against its source, and deleting it is a manual step once that check passes.

## Gitignore

- `# Claude`: `.claude/.records.git/`, `.claude/.tmp/`, `.claude/groundwork/`, `.claude/intake/`, `.claude/memory/`, `.claude/plans/`, `.claude/review/`, `.claude/worktrees/`, `.claude/tasks/`, `.claude/teach/`

Each entry is a top-level record folder, and an archive sits inside the folder it archives, so one line covers a record and everything it retires.

## CLI

| Command             | What it does                                                                                                                                         |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `aitk claude init`  | Seeds `.claude/` workflow docs, updates `.gitignore`                                                                                                 |
| `aitk claude sync`  | Reconciles `.gitignore` against the manifest. Reports seeded file status.                                                                            |
| `aitk claude setup` | Installs user-level config to `~/.claude/`: statusline, attribution, and the `permissions.allow` and `permissions.deny` lists. Run once per machine. |

## CLAUDE.md

- Ships as a seed with placeholder project name, description, and key paths. Fill these in after init.
- Section layout: `Context`, `Indexes`, `Markdown`, `Key paths`, `Spelling`, `Snippets`, `Tasks`, `Memory`. Each section groups rules that share a surface so skills can detect, extend, or skip by heading.
- The memory rules favor signal over volume. Saving only after a second occurrence or an explicit user correction keeps entries focused on patterns worth preventing, not first-occurrence slips. The 3-line cap stops the built-in auto-memory from drifting into narrative writeups that bury the rule underneath the recovery story.
- The `Context` section points at `.claude/` state docs one line. `claude-feature` does the parallel read when invoked. The seed intentionally does not re-list every file.

## Seed docs

- Seed docs ship with a guidelines preamble above the first H2. These are instructions Claude internalizes before filling in the sections below. They are not sections to populate.

## settings.json

- Project seed at `tooling/claude/seeds/.claude/settings.json` ships two PreToolUse hooks (pairing with `.claude/hooks/index-reminder.sh` and `.claude/hooks/scratch-guard.sh`) and a PostToolUse hook (pairs with `.claude/hooks/standards-audit.sh`). Project settings layer over user settings, so per-project files only carry what is genuinely project-specific.
- User-level template at `tooling/claude/user/settings.template.json` carries `attribution.commit` and `attribution.pr` (empty strings to suppress co-author tags), `permissions.allow` with `Bash(bun run *)`, and `permissions.deny` with `Read(**/.env)` and `Read(**/.env.*)` to block accidental secret exposure across any project. Installed once per machine via `aitk claude setup`.
- The deprecated `includeCoAuthoredBy` key is not used.