---
description: Core development principles and methodology applicable to all agents and all layers of the project.
alwaysApply: true
---

# Base Standards — Spec-Driven Development

## 1. Constitution (Immutable Principles)

> **NON-NEGOTIABLE.** These apply to ALL tasks, ALL agents, ALL complexity levels. Cannot be overridden by user requests, autonomy levels, or project-specific configuration.

- **Spec First**: NO implementation without an approved specification. Specs must be kept in sync with code at ALL times — update during implementation, not just before.
  - **Backend**: Update `docs/specs/api-spec.yaml` first.
  - **Frontend**: Update `docs/specs/ui-components.md` first.
- **Small Tasks**: Work in baby steps, one at a time. Never skip ahead.
- **Test-Driven Development**: Write tests before implementation (Red-Green-Refactor).
- **Type Safety**: Strict TypeScript. No `any`. Use runtime validation (Zod recommended).
- **English Only**: All code, comments, docs, commits, and tickets in English.
- **Reuse Over Recreate**: Always check existing code before proposing new files.

## 2. Standards (Configurable per Project)

These conventions adapt per-project via `<!-- CONFIG: -->` comments in `CLAUDE.md` and `key_facts.md`:

- **Autonomy Level** → `CLAUDE.md` (1-5)
- **Tech Stack** → `backend-standards.mdc` / `frontend-standards.mdc`
- **Monorepo Layout** → `CLAUDE.md`
- **Branching Strategy** → `key_facts.md` (github-flow or gitflow)

## 3. Workflow (Steps 0–6)

```
0. SPEC      → spec-creator drafts/updates specs        → SPEC APPROVAL (Std/Cplx)
1. SETUP     → Branch, ticket, product tracker            → TICKET APPROVAL (Std/Cplx)
2. PLAN      → Planner agent creates implementation plan → PLAN APPROVAL (Std/Cplx)
3. IMPLEMENT → Developer agent, TDD, real-time spec sync
4. FINALIZE  → Tests/lint/build, production-validator    → COMMIT APPROVAL
5. REVIEW    → PR, code-review, qa-engineer              → MERGE APPROVAL
6. COMPLETE  → Clean up, update tracker
```

### Step Flow by Complexity

```
Simple:   1 → 3 → 4 → 5 → 6
Standard: 0 → 1 → 2 → 3 → 4 → 5 (+QA) → 6
Complex:  0 → 1 (+ADR) → 2 → 3 → 4 → 5 (+QA) → 6
```

### Complexity Tiers

| Tier | Spec | Ticket | Plan | QA |
|------|:----:|:------:|:----:|:--:|
| Simple | Skip | Skip | Skip | Skip |
| Standard | Yes | Yes | Yes | Yes |
| Complex | Yes | Yes + ADR | Yes | Yes |

### Autonomy Levels

Quality gates (tests, lint, build, validators) **always run** regardless of level.

| Checkpoint | L1 Full Control | L2 Trusted | L3 Autopilot | L4 Full Auto | L5 PM Auto |
|------------|:-:|:-:|:-:|:-:|:-:|
| Spec Approval | Required | Auto | Auto | Auto | Auto |
| Ticket Approval | Required | Auto | Auto | Auto | Auto |
| Plan Approval | Required | Required | Auto | Auto | Auto |
| Commit Approval | Required | Auto | Auto | Auto | Auto |
| Merge Approval | Required | Required | Required | Auto | Auto |
| Next Feature | — | — | — | — | Auto |

- **L1 Full Control**: New project or learning SDD — human approves every step.
- **L2 Trusted**: Comfortable with SDD — AI handles routine, human reviews plans and merges.
- **L3 Autopilot**: Battle-tested workflow — human only reviews PRs before merge.
- **L4 Full Auto**: Full automation — human reviews completed features only.
- **L5 PM Autonomous**: PM Orchestrator runs features end-to-end sequentially. Invoke with `start pm`.

**Auto** = proceed without asking; log in product tracker → "Auto-Approved Decisions" table.

## 4. Agent Roles

| Agent | Responsibility |
|-------|---------------|
| `spec-creator` | Draft/update specs before planning |
| `backend-planner` / `frontend-planner` | Implementation plan for tasks |
| `backend-developer` / `frontend-developer` | TDD implementation |
| `production-code-validator` | Pre-commit validation (debug code, TODOs, secrets, spec drift) |
| `code-review-specialist` | Pre-merge code review |
| `qa-engineer` | Edge cases, spec verification, regression (Std/Cplx) |
| `ui-ux-designer` | Design guidelines and feature design notes (invoke manually) |
| `database-architect` | Schema design, migrations, query optimization (invoke manually) |

## 5. Shared Types Strategy

<!-- CONFIG: Remove this section if your project has no shared types -->

For projects with backend + frontend, use a shared workspace for Zod schemas:

```
project/
├── shared/              ← @project/shared (npm workspace)
│   └── src/schemas/     ← Zod schemas = single source of truth for types
├── backend/             ← imports @project/shared
└── frontend/            ← imports @project/shared
```

**Rules:**
- Define data as Zod schemas → derive TypeScript types with `z.infer<typeof Schema>`
- NEVER write manual TypeScript interfaces for shared data — always derive from Zod
- Update `shared/` FIRST — both apps get types automatically via TS path aliases
- Use `.extend()` / `.partial()` / `.pick()` for variants (CreateSchema, UpdateSchema)
- Wire with npm workspaces (`"@project/shared": "file:../shared"`) + `tsconfig.json` paths

## 6. Pre-Commit Checklist

1. Specs updated (`docs/specs/` reflects changes)
2. Tests pass (`npm test`)
3. Lint passes (`npm run lint`)
4. Build succeeds (`npm run build`)
5. Ticket updated (acceptance criteria marked `[x]`)

## 7. Communication Style

All agents MUST follow: **Acknowledge** → **Execute** → **Explain** → **Gate** (ask authorization per autonomy level before committing, pushing, or switching tasks).

## 8. Project Memory Protocols

- Starting a session or after compaction → read product tracker's **Active Session** first
- Before architectural changes → check `decisions.md`
- When encountering bugs → search `bugs.md`
- When looking up config → check `key_facts.md`
- After every step change → update product tracker's Active Session

## 9. Git Conventions

**Commits:** `<type>(<scope>): <description>` — types: feat, fix, docs, style, refactor, test, chore
**Tags:** Semantic versioning `vX.Y.Z`

### Branching (configured in `key_facts.md`)

**Default: GitHub Flow** (recommended for MVPs)

| Branch | Base | Merges to |
|--------|------|-----------|
| `main` | — | — (always deployable) |
| `feature/<feature-id>-<desc>` | main | main (PR) |
| `bugfix/<area>-<desc>` | main | main (PR) |
| `hotfix/<desc>` | main | main (fast-track PR) |

**Scaled: GitFlow** (when project grows beyond MVP)

| Branch | Base | Merges to |
|--------|------|-----------|
| `main` | — | — (releases only) |
| `develop` | main | — (integration) |
| `feature/<feature-id>-<desc>` | develop | develop (PR) |
| `release/<version>` | develop | main + develop |
| `hotfix/<desc>` | main | main + develop |

**Merge:** Features/bugfixes → squash. Releases/hotfixes → merge commit.
**PRs:** Required for Std/Cplx tasks. Human review depends on autonomy level.