CLAUDE.md@templates · diff

git:20260417.ca34447 to git:20260417.5da48f5

1 added, 0 removed. Audit A to A.

# [Project Name]

> Compile this file from your completed CRISP docs/ folder.

> This is the single source of truth Claude reads at the start of every session.

> Keep it current — update after every sprint.

---

## What this project is

_(From docs/problem-statement.md — one sentence)_

## Why it exists

_(Painkiller: what pain does it solve? For whom?)_

## Desired outcome

_(From docs/success-metrics.md — success targets, baseline, second-order effects)_

## Constraints

_(From docs/problem-statement.md — budget, time, legal, technical)_

- Budget:

- Timeline:

- Legal/Compliance:

- Technical:

## What we are building

_(Internal tool / External product. Summary of scope from docs/initial-backlog.md)_

## What we are NOT building

_(From docs/initial-backlog.md — out of scope / POST-MVP)_

## Tech stack

_(From Phase 4B tech stack proposal — pinned versions are mandatory)_

|---|---|---|---|

| | | | |

**Version rules — Claude must follow these every session:**

- Use only the versions listed above. Do not upgrade silently or assume a newer version.

- If a library's API in your training data differs from the pinned version — trust the pinned version.

- If a version conflict arises, stop and flag it. Do not resolve silently.

- Do not add dependencies not listed here without flagging it first.

## Folder structure

_(Describe key directories and what lives where)_

```

├──

└──

```

## Agents / Skills in this project

_(From Phase 4E agent map — name, responsibility, SKILL.md location)_

| Agent/Skill | Responsibility | Location |

|---|---|---|

| | | skills/[name]/SKILL.md |

## Environment Variables

> Never commit these to version control. All keys live in `.env.local` (or equivalent).

> Claude: if a required variable is missing or undefined, stop and flag it — do not proceed or hardcode a fallback.

|---|---|---|---|---|

**Rules:**

- All secrets accessed via environment variables — never hardcoded

- `.env.local` (or equivalent) is always in `.gitignore` — verify before first commit

- Server-side secrets (OAuth tokens, service role keys) never sent to client

- If a variable is missing at runtime, fail loudly with a clear error — no silent fallbacks

**`.env.local` template** _(copy this, never commit the filled version)_:

```

# [Service name]

VARIABLE_NAME=

```

## Human-in-the-loop zones

_(From docs/risk-assessment.md — where Claude must NOT act autonomously)_

## Security rules

_(Non-negotiable — Claude must follow these always)_

- Never log or expose PII

- Never commit secrets or API keys — verify `.gitignore` covers `.env*` before first commit

- All environment variables verified present before use — fail loudly if missing, never silently fallback

- **Never expose API keys or credentials client-side.** All 3rd party API calls requiring secrets must be made server-side. The client calls your server route; your server calls the 3rd party.

- Server-side secrets (Stripe, OpenAI, OAuth tokens, service role keys) must never appear in client bundles, `NEXT_PUBLIC_` vars, or mobile app source.

- **Bearer security scanner runs on every PR. Critical/High findings BLOCK merge. Do not proceed, do not merge, do not work around — fix the finding first.** Medium findings require acknowledgement before merge. Low/Info are logged only.

- Logging is mandatory for all API endpoints and background jobs. No PII in logs. No secrets in logs. See `docs/logging-spec.md`.

## Logging

_(From docs/logging-spec.md)_

- Log level in production: `INFO` (DEBUG disabled)

- Log destination:

- Alerting:

- **Sprint quality gate:** Before marking a sprint complete — confirm logging is implemented for all new endpoints and jobs, and no PII or secrets appear in logs.

## Agent Security

_(Complete this section only if an AI agent is in scope — from `docs/agent-security.md`)_

**Agent name / description:**

**Permitted actions (autonomous):**

- _(list from agent-security.md — what agent can do without approval)_

**Hard boundaries (never):**

- _(list from agent-security.md — what agent must never do)_

**Approval gates:**

| Action | Condition | Approver |

|---|---|---|

| | | |

**Data rules:**

- No PII in agent logs or reasoning traces

- No PII sent to external APIs unless documented in agent-security.md

- Agent credentials stored in environment variables only — never hardcoded

**Failure rules:**

- On failure: log the error with full context, notify [channel], hand off to human fallback

- Never fail silently — a silent agent failure is worse than a loud one

- Every agent action must produce an auditable log entry

**Reference:** `docs/agent-security.md`

## Current sprint

_(Update this at the start of each sprint)_

**Sprint:**

**Goal:**

**AI Spec:** `docs/ai-spec-[name].md`

## Open questions

_(Unresolved — Claude should flag these, not assume answers)_

---

## CRISP Output Manifest

> All project discovery and spec documents live in `docs/`.

> If a file is marked ✅ it exists and is current. If ❌ it is missing or incomplete — flag before proceeding with any work that depends on it.

### Phase 1 — Clarify

| File | Status | Notes |

|---|---|---|

| `docs/problem-statement.md` | ✅ / ❌ | |

| `docs/buy-vs-build-matrix.md` | ✅ / ❌ | |

| `docs/market-research.md` | ✅ / ❌ / N/A (internal) | |

| `docs/value-proposition-canvas.md` | ✅ / ❌ / N/A (internal) | |

| `docs/swot.md` | ✅ / ❌ / N/A (internal) | |

### Phase 2 — Results

| File | Status | Notes |

|---|---|---|

| `docs/stakeholder-register.md` | ✅ / ❌ | Impacted parties, HITL zones |

| `docs/success-metrics.md` | ✅ / ❌ | Baseline measurements, success targets, second-order effects |

### Phase 3 — Investigate

| File | Status | Notes |

|---|---|---|

| `docs/process-flow.md` | ✅ / ❌ | |

| `docs/user-journey-map.md` | ✅ / ❌ | |

| `docs/project-goals.md` | ✅ / ❌ | |

| `docs/ux-discovery.md` | ✅ / ❌ / N/A (non-UI) | |

### Phase 4 — Spec

| File | Status | Notes |

|---|---|---|

| `docs/design-system.md` | ✅ / ❌ / N/A (non-UI) | |

| `docs/ux-spec.md` | ✅ / ❌ / N/A (non-UI) | |

| `docs/initial-backlog.md` | ✅ / ❌ | MVP tags applied |

| `docs/assumptions-log.md` | ✅ / ❌ | |

| `docs/risk-assessment.md` | ✅ / ❌ | |

| `docs/mvp-prioritization.md` | ✅ / ❌ | HVLE scores + MVP line |

| `docs/sprint-plan.md` | ✅ / ❌ | |

| `docs/logging-spec.md` | ✅ / ❌ | Mandatory — log levels, destinations, PII rules |

| `docs/data-mapping.md` | ✅ / ❌ / N/A | Required if any feature extracts/transforms structured data |

| `docs/analytics-spec.md` | ✅ / ❌ / N/A (non-UI) | GA4 event map, conversion goals, PII rules |

| `docs/landing-page-brief.md` | ✅ / ❌ / N/A (internal) | Hero copy, sections, visual direction |

+ | `docs/crisp-state.json` | ✅ / ❌ | Project state contract — updated by each phase |

| `docs/decisions.md` | ✅ / ❌ | Decision log across all phases |

| `docs/agent-security.md` | ✅ / ❌ / N/A (no agent) | Agent permissions, data handling, failure modes |

| `docs/ai-spec-[sprint/feature].md` | ✅ / ❌ | One per sprint — list all below |

| `docs/ai-spec-[integration].md` | ✅ / ❌ / N/A | One per 3rd party service — list all below |

**AI Specs written:**

- [ ] `docs/ai-spec-`

**Integration specs written:**

- [ ] `docs/ai-spec-` _(service name)_