# CLAUDE.md -- {{PROJECT_NAME}}

This is the main project brain. Claude Code reads this at the start of every session.
Keep it accurate and up to date -- it directly affects the quality of every pipeline run.

---

## Vault Search (USE THIS)

```bash
python3 {{VAULT_ROOT}}/vault-search.py "your query here"
python3 {{VAULT_ROOT}}/vault-search.py "your query" --top 10
```

Use vault search to FIND context (searches by meaning, not keywords). Use Read when you know the exact file.

---

## Project Summary

**Name:** {{PROJECT_NAME}}
**GitHub:** {{GITHUB_URL}}
**What it does:** <!-- Describe the project in 1-3 sentences -->
**Current version:** 0.1.0
**Status:** <!-- e.g., Pre-development, Active development, Beta, Production -->

---

## Tech Stack (Key Technologies)

<!-- Fill in your actual tech stack -->

| Layer           | Technology      | Version   | Notes                              |
|-----------------|-----------------|-----------|-------------------------------------|
| Language        |                 |           |                                     |
| Framework       |                 |           |                                     |
| Backend/Auth    |                 |           |                                     |
| Database        |                 |           |                                     |
| Hosting         |                 |           |                                     |

---

## Conventions & Patterns

### Where Things Live
<!-- Document your project's directory structure conventions -->
<!-- Example: -->
<!-- - Route pages: `/app/` -->
<!-- - Components: `/components/` -->
<!-- - API calls: `/lib/api.ts` -->
<!-- - Types: `/types/` -->
<!-- - Utilities: `/lib/utils.ts` -->

### Patterns We Always Use
- All async functions have explicit error handling
- No hardcoded API keys (always environment variables)
- No `console.log` in committed code
- No force push to any branch
<!-- Add your project-specific patterns below -->

### Patterns We Never Use
<!-- List anti-patterns for your project -->
<!-- Example: -->
<!-- - No `any` type in TypeScript -->
<!-- - No inline styles with hardcoded colors -->

---

## Compaction

Use `/compact` at natural breakpoints (60% context, not 90%). What must survive:
current session number, pipeline stage, files modified this session, active blockers,
and any commitments made to the user. Save important state to `.session/state.md`
before compacting.

---

## Environment Variables

<!-- List required env vars (never commit actual values) -->
Required in `.env` (never commit -- see `.env.example`):
```
# YOUR_API_KEY, YOUR_SECRET, DATABASE_URL, etc.
```

---

## Current Status

<!-- Keep this section brief and current -->
**Done:**
- <!-- List completed milestones -->

**In Progress:**
- [ ] <!-- Current work items -->

**Up Next:**
- [ ] <!-- Prioritized backlog -->

---

## Session Closeout Checklist

**When ending a session -- run `/closeout` or complete every step below. Do NOT skip any step.**

1. Write handoff document to `handoffs/HANDOFF_SESSION_[N]_[YYYY-MM-DD].md`
2. Update session log -- add entry at TOP of `docs/status/SESSION_LOG.md`
3. Log any blockers (skip if none)
4. Update `CLAUDE.md` status section + any changed docs
5. Commit & push to GitHub (if code/data changed)
6. Include commit hashes in handoff
7. Write continuation prompt (in handoff + present to user)
8. Give verbal summary of what was done, what's pending, what's next

**Shortcut:** Type `/closeout` to run the full protocol as a guided skill.

---

## Pipeline & Commands

Pipeline: RESEARCHER -> ADVISOR -> ARCHITECT -> DESIGNER -> [APPROVAL] -> BUILDER -> TESTER -> DESIGNER (post-build) -> CRITIC -> DEBUGGER -> REFACTOR -> REVIEWER

| Command | What It Does |
|---------|-------------|
| `/startup` | Daily briefing with status, priorities, crash recovery check |
| `/pipeline [task]` | Run the full agent pipeline for a task |
| `/briefing` | Generate a plain-language status briefing |
| `/closeout` | Full session closeout protocol |
| `/quality-gate` | Run typecheck, lint, and tests |
| `/context` | Show current session state |
| `/experiment` | Run a structured experiment in .lab/ |
| `/backup` | Backup workspace to local or cloud storage |
| `/dashboard-update` | Update project dashboard with current metrics |
| `/retrospective` | Self-evaluation after pipeline run |

- **Agents:** `.claude/agents/` (12 agents)
- **Skills:** `.claude/skills/` (10 skills)
- **Hooks:** `.claude/hooks/` (13 hooks)
- **Learning system:** `agent-learnings/` (PATTERNS, MISTAKES, DECISIONS, IMPROVEMENTS, METRICS)
- Before acting on a learning file entry, verify cited files still exist and the pattern still applies. Entries can become stale.

---

## Git Quick Reference

**GitHub:** {{GITHUB_URL}}
**Primary branch:** `develop` | **Production branch:** `main`

Commit protocol: (1) `git status` + `git diff`, (2) verify no secrets staged, (3) stage specific files, (4) descriptive commit message, (5) push to working branch.