CLAUDE.md@template git:20260917.1002ee5B

Immutable. This exact content is served forever at /api/v1/blob/d122fac1670df222.

# CLAUDE.md

> **This is a template.** Copy it to the root of your project and fill in the
> bracketed `<…>` placeholders. Delete sections that don't apply and add rows to
> the documentation map for your own domains. The structure is the contract the
> agentic workflow skills read at runtime — keep the map honest and they adapt to
> your project automatically.

Guidance for AI coding agents working in this repository.

**Always read the relevant documentation before changing code.**

---

## Documentation map

The single most important table: it tells an agent *which doc owns what*, so it
reads the right context before acting. Delete rows you don't have; add rows for
your domains.

| Task | Required docs |
|---|---|
| Any code change | `docs/architecture/ARCHITECTURE.md` |
| New feature / planning / sequencing | `docs/features/ROADMAP.md`, `docs/features/_TEMPLATE/SPEC.md` |
| Feature design — capability & integration closure | `docs/CAPABILITIES.md` *(the capability inventory: roles + cross-cutting subsystems; extended whenever a feature introduces one)* |
| A fix | `docs/fix/_TEMPLATE/SPEC.md`, `docs/fix/README.md` |
| Integrating an external provider | `docs/providers/<provider>.md` |
| SEO / metadata / structured data | `docs/frontend/SEO.md` *(optional)* |
| i18n / translations / locales | `docs/frontend/I18N.md` *(optional)* |
| Accessibility | `docs/frontend/ACCESSIBILITY.md` *(optional)* |
| Copy / UX messaging | `docs/frontend/COPYWRITING.md` *(optional)* |
| UI / visual system | `docs/frontend/DESIGN.md` *(optional)* |
| Brand identity / voice | `docs/brand/BRAND.md` |
| Domain / business rules | `docs/domain/*`, `docs/business/*` |
| Legal / compliance | `docs/legal/*` |
| Session journal / resuming work | `docs/LOGS.md` *(written by `/log-session` + the `.claude/` hooks)* |
| Frozen repository knowledge | `docs/workflow/REPOSITORY_STATE.md` *(written by discovery/resolution; consumed by workflow roles)* |
| Architectural constraints | `docs/architecture/ARCHITECTURAL_INVARIANTS.md` *(optional; explicit rules that architectural changes must preserve)* |
| Generated developer docs | the `Docs site` block below *(read by `/generate-docs`)* |

## Docs site *(optional — uncomment and fill to enable `/generate-docs`)*

<!--
- format: starlight | docusaurus | markdown
- content-dir: src/content/docs/
- build: npx astro check   # or `none`
- map: npm run docs:graph  # a script emitting a nodes[]/edges[] JSON via
                           # deterministic tooling (dependency-cruiser, madge,
                           # TypeDoc, tree-sitter, LSP…); or `none`
-->

---

## Workflow conventions (the skills read this)

The single source of truth for what every agentic-workflow skill does first and
always honors — **referenced** by the skills instead of restated in each one.

**Discovery (always first).** Before acting, read: this guide + the **documentation
map** above, the **roadmap** (`docs/features/ROADMAP.md`), and the template(s) or
recent artifacts for the task at hand. Never assume paths or formats; if a doc is
missing, say so and fall back to these conventions rather than guessing.

**Normalized Repository State.** When `docs/workflow/REPOSITORY_STATE.md` exists,
consume its frozen, evidence-backed facts and accepted decisions before
rediscovering them. Keep facts, planned work, documentation, and inference
separate. A missing fact may be inspected directly; conflicting evidence becomes
a contradiction for `/resolve-repository-state`, never a silent overwrite.

**Architectural invariants.** When the documentation map declares
`docs/architecture/ARCHITECTURAL_INVARIANTS.md` (or an equivalent path), classify
each applicable rule as preserved, violated, introduced, or changed before
designing, planning, implementing, reviewing, or auditing a change. A violation
or new/changed rule requires an explicit architectural decision; a feature SPEC,
implementation, or passing test cannot silently authorize it. If no invariant
document exists, record that no project invariants are declared and continue.

**Forge (issue/PR tracker):** `<GitHub (gh) | GitLab (glab) | other CLI>` — the
CLI the skills use for issues and PRs. Skill examples are written with `gh`; when
this project declares a different forge, run the equivalent command with its CLI.
The auto-close convention (`Closes #N` in the PR/MR body) must hold either way.

**Forge bodies are Markdown, not shell — never hand-escape them.** An issue, PR,
or comment body renders as Markdown: backticks, `*`, `_`, `#`, `|` are
formatting, **not** shell syntax, so **never put a `\` before them**. A stray
`\` renders literally (`` \`code\` `` instead of `` `code` ``) — the most common
forge-formatting bug. Always **write the body to a file** (plain Markdown, real
backticks, zero backslashes) and pass **`--body-file <path>`**
(`gh issue create --body-file`, `gh pr create --body-file`,
`gh issue comment --body-file`, or the forge's equivalent) — **never** an inline
`--body "…"` or a quoted `<<'EOF'` heredoc, both of which mangle backticks or
preserve the stray `\`. A bare non-Markdown one-liner (e.g. `Closes #12`) may
stay inline. Verify after: `gh issue view <n> --json body` shows backticks
rendering, no literal `` \` ``.

**Notation — forge numbers vs workflow numbers.** Two independent number spaces
run side by side in this workflow and must never be confused:

- **`#N` is a forge number** — a GitHub/GitLab issue or PR. In a forge, issues
  and PRs share one sequence, so `#N` is always exactly one object, never two.
  When the distinction matters, write **`issue #N`** or **`PR #N`**, or link it.
- **Feature numbers carry no `#`.** Write **`feature 12`** (or plain `12` inside
  a roadmap/feature context) — never `#12`. A roadmap row number is a workflow
  identifier; the forge has its own object at that number.
- **Fix units are forge-backed.** A fix is named by the issue that tracks it —
  **`fix #157`**, folder `docs/fix/157-<topic>/`. So `fix #52` and `feature 52`
  are two different things and the noun is what separates them.
- **Ambiguity is a defect, not a style choice.** A sentence that mixes both
  spaces (`merging #12 unblocks 05 and 07`) gets rewritten with the nouns
  (`merging issue #12 unblocks features 05 and 07`). When a feature and an issue
  share a number, the noun is mandatory.

**Git workflow:** `<branches | worktrees>` — how parallel work is handled.
**`branches`** (default): plain feature/fix branches via `git switch -c`, **one
active unit at a time**, sequential — slower, but the working tree is always the
unit you're on. **`worktrees`**: parallel units in separate checkouts — only if
your agent/tooling manages worktrees. Every skill that creates a branch honors
this line; with `branches` declared, no skill may create a worktree.

**Agent safety hooks:** `<Claude Code | Cursor | Copilot | OpenCode | none>`.
When enabled, repository adapters call `.agentic-workflow/hooks/guard-command.sh`
before shell/read tools. Direct environment dumps, `.env` reads, and merge
commands are blocked. Automated merge is available only inside an active
`ship-roadmap --fullauto` attempt through the transient wrapper; never grant an
agent-wide or session-persistent merge permission. Hooks are defense-in-depth —
forge branch protection/rulesets remain required.

**Hard rules (always honored).**
- **Branch & PR:** never work on `main`; one PR per unit against `main`; never
  stack — see [PR & branch workflow](#pr--branch-workflow).
- **Gate before commit:** the verification gate (type-check + tests + build) is
  green — see [Commands](#commands).
- **Docs language:** every committed artifact (issues, PRs, commits, SPECs,
  docs) in `<your docs language>`, whatever language the work was requested
  in. Precedence: an explicit instruction in the prompt > this line > English.
  **The conversation language never decides** — a request made in Spanish
  still produces artifacts in the declared language.
- **Evidence over reflex:** verify claims against the code (counts, repro,
  thresholds) and cite paths; don't assert from assumption.
- **Track, don't inline:** deferred work becomes a tracked issue / known-issue,
  never silently implemented.
- Plus this project's [Hard rules](#hard-rules) and [Architecture](#architecture)
  invariants.

**Question protocol (when a skill must ask the user to decide).** Only ask when the
answer materially changes the artifact — make routine choices silently and record
them. Each question states: **what** is being decided; its **scope** (files,
behavior, consumers affected); its **criticality** (critical / high / medium /
low); and each **option** with pros and cons separately, recommendation flagged.

---

## Commands

Fill in your project's real commands. The agentic workflow refers to the
**verification gate** generically; define it once here.

```bash
<dev command>        # run locally
<build command>      # production build
<test command>       # test suite

# Verification gate (must pass before every commit):
<type-check> && <test> && <build>
```

## Performance commands *(optional — filled by `init-workspace`; read by `review-perf`)*

When declared, the workflow's performance review **runs** these and cites real
numbers instead of estimating from the diff. Use `none` explicitly for a slot
the project doesn't have; delete the block only if none apply.

```
- bench: <command | none>            # e.g. vitest bench, bun run bench.ts
- profile: <command | none>          # e.g. node --cpu-prof <entry>
- complexity-lint: <command | none>  # e.g. the linter's complexity ruleset
- noise-band: ±5%                    # deltas inside the band are not findings
```

---

## Architecture

This project's architecture is documented in `docs/architecture/ARCHITECTURE.md`.
The workflow is **architecture-agnostic** — it does not assume any particular
pattern (layered, hexagonal, clean, modular monolith, MVC, …). Record *your*
chosen pattern, its layers/modules, and the **dependency-direction rules** that
must never be violated in that doc. Put long-lived cross-cutting rules in
`docs/architecture/ARCHITECTURAL_INVARIANTS.md` when applicable; the skills will
respect both documents.

State the invariants explicitly there (e.g. "module X must not import module Y",
"business logic stays out of the UI layer"). Reference them from SPECs.

---

## Hard rules

Generic, stack-independent guardrails. Add your own.

- **Dependencies:** justify every new dependency; prefer the platform/standard
  library; pin versions. Avoid redundant libraries that duplicate existing ones.
- **Honesty to the user:** never hide real limitations of the product (limits,
  reductions, restrictions). Disclose them in the UI/output.
- **Secrets:** never commit secrets; read them from the environment/secret store.
- **Docs language:** all committed artifacts in `<your docs language>`,
  regardless of the language the work was requested in.

---

## Testing philosophy

Prefer integration and architecture tests over heavy mocking and
snapshot-heavy testing. Test behavior, not implementation detail. State the
required test layer for a change in its SPEC.

---

## Naming conventions

| Type | Convention |
|---|---|
| Source files | `<e.g. kebab-case>` |
| Components / classes | `<e.g. PascalCase>` |
| Directories | `<e.g. kebab-case>` |

---

## Feature workflow

Features are planned before they are coded. Flow:

1. `SPEC.md` (from `docs/features/_TEMPLATE/SPEC.md`)
2. `PLAN.md`
3. `TASKS.md`
4. execution by phase (one phase per commit, gate-verified)
5. hardening
6. verification & review
7. PR

Phases are labelled **`P1, P2, …`** ("phases") everywhere — `PLAN.md`, `TASKS.md`,
`progress.md`, commits — never `S1`/"Steps". The label is `execute-phase`'s
argument (`execute-phase NN P2`), so it must stay uniform.

**One phase = one session.** Never execute two phases in one conversation on a
non-frontier model — models degrade over long horizons, and a fresh session per
phase is what preserves the cheap-execution guarantee. With `/loop`, this is
already how the batch shape re-invokes per phase; without it, re-invoke
`execute-phase` by hand for each phase in a fresh conversation.

Start a new feature by copying `docs/features/_TEMPLATE/SPEC.md` to
`docs/features/<NN>-<slug>/SPEC.md` and registering it in
`docs/features/ROADMAP.md` (the source of truth for numbering, order, and
dependencies).

**Fix-now fold ledger.** Step 6 (verification & review) writes fix-now
findings from `review-change`/`audit-pr` to `docs/features/<NN>-<slug>/review-findings.md`
(fixed schema `| id | file:line | axis | severity | class | route | folded |`,
`folded` starting `no`) — the same ledger for both, deduped by `file:line`+axis;
`execute-phase`'s fold cycle ticks each folded row `folded: yes`. Fixes use the
same convention at `docs/fix/<n>-<topic>/review-findings.md`.

## Fix workflow

A fix is lighter than a feature: only a `SPEC.md` (from
`docs/fix/_TEMPLATE/SPEC.md`), registered in `docs/fix/README.md`, no planning
artifacts. Every fix has a tracked issue; its PR closes it.

---

## Session log

`docs/LOGS.md` is an append-only journal of working sessions — the *why* and the
*what-next* that git history doesn't record. Two ways it's written, both
optional:

- **`/log-session`** (manual, rich) — summary, decisions, next step. Run it
  before `/clear` or before closing for the day.
- **`.claude/` hooks** (automatic, free) — append a mechanical entry on `/clear`
  and exit; an opt-in hook re-injects the last entry to resume context. Copy
  `.claude/settings.json.example` to enable; see `.claude/README.md`.

**Context hygiene rule:** end of a unit or phase → `/log-session` then a NEW
conversation, never compact — compaction re-reads the whole transcript with
the current session model, right when the context is most expensive to
re-read; a fresh conversation is ~free because this SPEC/TASKS/progress + the
session log already are the persistent memory. Compact only mid-phase, for
unpersisted state you can't afford to lose, and prefer committing WIP + a
`progress.md` note instead. Details: `docs/workflow/FEATURE_WORKFLOW.md` →
*Context hygiene & cost*.

---

## PR & branch workflow

- **One PR per unit of work, always against `main`.** Each PR must be
  independently mergeable: it passes the verification gate and delivers
  standalone value.
- **Never work on `main` directly.** Create a branch first
  (`feat/<NN>-<slug>` or `fix/<n>-<topic>`).
- **Never stack PRs.** A PR's base is always `main`. If a feature is too large,
  split it into independently shippable slices — never by internal phases.

## Commit format

```txt
feat(<area>): <summary>
fix(<area>): <summary>
chore(<area>): <summary>
```

---

## Skills

This project uses the agentic workflow skills
([`gtrabanco/agentic-workflow`](https://github.com/gtrabanco/agentic-workflow)),
installed with:

```sh
npx skills add gtrabanco/agentic-workflow
```

They discover this project's docs (the map above) at runtime and drive the
feature/issue workflow. When repeated searches or doc lookups recur, create a
project-specific skill to capture the knowledge instead of re-deriving it.

---

## MCP servers

List the MCP servers this project relies on and what each is for. Prefer their
documentation over ad-hoc web searches.

| Server | Purpose |
|---|---|
| `<name>` | `<what it provides>` |