CLAUDE.md@templates git:20260423.96a5b2cA

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

# [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)_

| Layer | Tool | Pinned version | Notes |
|---|---|---|---|
| | | | |
| **Harness** | _(e.g. Claude Code, open-source framework)_ | | Open source: Yes/No — Memory ownership: Client/Provider |

**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.

| Variable | Purpose | Where to get it | Required? | Sprint introduced |
|---|---|---|---|---|
| | | | Yes / No | |

**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.


## Testing Rules

> These rules apply to every sprint. No exceptions.

- **Write unit tests for every function and feature in scope** before marking the sprint done. Tests are not optional and not a post-sprint task — they ship with the feature.
- **Run the full test suite before every commit.** If any test fails — stop. Fix the failure before committing. Do not commit broken tests. Do not skip tests.
- **After every test run, append an entry to `docs/test-log.md`** using the format in `templates/test-log.md`:
  - Sprint name, date, run trigger (commit / pre-push / manual)
  - Each test: plain-English description of what was tested + ✅ / ❌
  - For any failure: what failed, what was wrong, what fix was applied, re-run result
- **Test descriptions must be plain English** — written so a non-technical client can read the log and understand what the system does and whether it's working. Not "test_fn_returns_200" — "Slack notification sends when HeyReach campaign receives a reply".
- Pre-fill test requirements from the **success conditions** in `docs/process-flow.md` (one test per process step) and the **acceptance criteria** in the sprint's AI Spec.

**Test log location:** `docs/test-log.md`


## 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` | ✅ / ❌ | Incl. success condition per step |
| `docs/user-journey-map.md` | ✅ / ❌ | |
| `docs/project-goals.md` | ✅ / ❌ | |
| `docs/integration-map.md` | ✅ / ❌ | Every external system — direction, trigger, data in/out, format |
| `docs/data-flow.md` | ✅ / ❌ | Full system pipe in plain language — client signed off |
| `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 |
| `docs/test-log.md` | ✅ / ❌ | Running test record — appended after every run across all sprints |

**AI Specs written:**
- [ ] `docs/ai-spec-` 
- [ ] `docs/ai-spec-` 

**Integration specs written:**
- [ ] `docs/ai-spec-` _(service name)_
- [ ] `docs/ai-spec-` _(service name)_