Project Conventions
Announce at start: "I'm using claude-engineer:project-conventions to set up the repo's house style."
Folder contract
_private/ - UNCOMMITTED working area: drafts, screenshots, scratch notes, research. Add to .gitignore.docs/ - COMMITTED non-code: docs/plan/* (the plan), docs/decisions.md, architecture, runbooks, API docs..claude-engineer/ - durable state (see claude-engineer:project-memory). Commit memory.md/progress.md; ignore quality-gate-status.json.- code - the monorepo (
apps/, packages/, services/, libs/; see claude-engineer:monorepo-and-tooling).
Phase 0 setup (create a task per item)
git init (if not a repo). Create .gitignore covering _private/, .claude-engineer/quality-gate-status.json, node_modules, .venv, build dirs, .env*.- Create
_private/ and docs/ (with docs/plan/).
- Generate a root
CLAUDE.md capturing: the stack, the iron laws (plan-gated, CX-first, services-in-docker/app-native, the four quality gates), how to run things, and where state lives. This is the project's standing instruction file.
- Initialize the conventions registry at
docs/conventions.md - the house style the agent must reuse instead of reinventing: naming, error handling, API response shape, folder patterns, and a UI pattern registry (component + token usage; generalize the design system's DESIGN.md into reusable patterns). Append to it whenever a new pattern is established.
- Write
docs/recommended-mcps.md from templates/recommended-mcps.md and tell the user which MCPs to install with their own keys.
MCP policy (BYO keys)
Claude-Engineer references MCP servers; it never bundles secrets. Users install with their own keys via each provider's command. See templates/recommended-mcps.md for Playwright, Chrome DevTools, 21st.dev Magic, and designmd (getdesign.md).
Red flags - STOP
- Committing screenshots/scratch to git → those belong in
_private/.
- Inventing a new pattern that contradicts
docs/conventions.md → reuse the house style or update the registry deliberately.
- Secrets or API keys written into committed files → never; use
.env* (git-ignored) and document required vars.
1---2name: project-conventions3description: Use when setting up a new project's repository conventions and house style, the _private vs docs vs code layout, .gitignore, CLAUDE.md, the conventions/pattern registry, and the recommended MCP setup. Run early (Phase 0) and consult when introducing new patterns.4---56# Project Conventions78**Announce at start:** "I'm using claude-engineer:project-conventions to set up the repo's house style."910## Folder contract11- **`_private/`** - UNCOMMITTED working area: drafts, screenshots, scratch notes, research. Add to `.gitignore`.12- **`docs/`** - COMMITTED non-code: `docs/plan/*` (the plan), `docs/decisions.md`, architecture, runbooks, API docs.13- **`.claude-engineer/`** - durable state (see `claude-engineer:project-memory`). Commit `memory.md`/`progress.md`; ignore `quality-gate-status.json`.14- **code** - the monorepo (`apps/`, `packages/`, `services/`, `libs/`; see `claude-engineer:monorepo-and-tooling`).1516## Phase 0 setup (create a task per item)171. `git init` (if not a repo). Create `.gitignore` covering `_private/`, `.claude-engineer/quality-gate-status.json`, `node_modules`, `.venv`, build dirs, `.env*`.182. Create `_private/` and `docs/` (with `docs/plan/`).193. Generate a **root `CLAUDE.md`** capturing: the stack, the iron laws (plan-gated, CX-first, services-in-docker/app-native, the four quality gates), how to run things, and where state lives. This is the project's standing instruction file.204. Initialize the **conventions registry** at `docs/conventions.md` - the house style the agent must reuse instead of reinventing: naming, error handling, API response shape, folder patterns, and a UI pattern registry (component + token usage; generalize the design system's DESIGN.md into reusable patterns). Append to it whenever a new pattern is established.215. Write **`docs/recommended-mcps.md`** from `templates/recommended-mcps.md` and tell the user which MCPs to install with their own keys.2223## MCP policy (BYO keys)24Claude-Engineer **references** MCP servers; it never bundles secrets. Users install with their own keys via each provider's command. See `templates/recommended-mcps.md` for Playwright, Chrome DevTools, 21st.dev Magic, and designmd (getdesign.md).2526## Red flags - STOP27- Committing screenshots/scratch to git → those belong in `_private/`.28- Inventing a new pattern that contradicts `docs/conventions.md` → reuse the house style or update the registry deliberately.29- Secrets or API keys written into committed files → never; use `.env*` (git-ignored) and document required vars.
martian56