Project: <PROJECT_NAME>

Stack: <STACK> Status: <STATUS>

Replace the three placeholders above after cloning. Everything below is ready to use.

Project Identity

What this project does: [One sentence. What problem does it solve for whom?]

What it does NOT do: [Explicit scope boundary — prevents feature creep]

Primary consumers: [Who uses this? Internal team / external users / downstream systems]

Critical Rules

1. Plan before coding. Use /plan for anything non-trivial. Coding without a plan produces code that solves the wrong problem correctly.
2. For complex tasks, invoke @tech-lead first. It decomposes the task, identifies required agents, and parallelizes independent work. Don't route multi-domain problems to a single agent.
3. For vague requests, invoke @product-manager first. No implementation starts without testable acceptance criteria.
4. ADR for architectural decisions. If a decision is hard to reverse, or future engineers will wonder why it was made, use /adr. The code does not explain the tradeoffs.
5. No redundant comments. Comments explain WHY — constraints, workarounds, non-obvious invariants. Comments that restate what the code does are noise and will be flagged in review.
6. Tests before merging. New behavior requires tests. Refactoring requires existing tests. No exceptions.
7. English in code, commits, and comments. This codebase is public-facing. All identifiers, commit messages, and inline comments must be in English.

Architecture

• Full diagram: docs/architecture.md
• Knowledge graph (read before broad searches): graphify-out/GRAPH_REPORT.md
• Decision log: docs/adr/
• Current session state: CONTEXT.md

[Add project-specific architecture notes here — key modules, data flow, critical paths]

Conventions

Language / runtime: [e.g., Python 3.12, Node 20, TypeScript strict] Package management: [e.g., pip + uv, npm, poetry] Formatting: [e.g., ruff + black for Python, prettier for TS/JSON/YAML] Linting: [e.g., ruff, eslint]

Branch naming:

• feat/<ticket>-<short-description>
• fix/<ticket>-<description>
• hotfix/<ticket>-<description> (production only)
• docs/<description>

Commit style: Conventional Commits — see .claude/skills/commit-style/SKILL.md

PR requirements:

• Self-reviewed before requesting review
• No 🔴 BLOCKER issues from code-reviewer
• Tests added for new behavior
• CHANGELOG.md updated if user-facing change
• ADR created if architectural decision was made

Active Subagents

Use these agents proactively. They are specialized and will produce better output than asking the general Claude session.

Leadership Layer (start here for complex work)

Execution Layer

Quality & Meta Layer

Second Brain

Obsidian vault: ~/vault/projects/<project-name>/

• Session logs: synced by /sync-vault
• Decision copies: decisions/ (mirrors docs/adr/)

Setup guide: docs/obsidian-vault-setup.md

Local Development

• Run just init for first-time setup (installs deps, pre-commit hooks, builds Graphify graph)
• Run just format before committing — also runs automatically via pre-commit hooks
• Run just lint to check all linters without auto-fixing
• Run just health to invoke tech-debt-hunter and generate a codebase health report
• Pre-commit hooks enforce: formatting (ruff/prettier/sqlfluff), no secrets (gitleaks), Conventional Commits (commitlint), markdown consistency (markdownlint)

Tool Usage Rules

1. Before broad file searches → read graphify-out/GRAPH_REPORT.md for architecture context.
2. For "where is X defined?" → graphify query "X" is faster and smarter than grep.
3. For cross-module relationships → graphify path "ModuleA" "ModuleB" or graphify explain "concept".
4. After modifying source files → run graphify update . to keep the graph current.
5. For SQL questions → apply the sql-review skill before proposing changes.
6. Read before editing. Always read a file before modifying it. Never assume structure.