create-sdd-project 0.1.1

package/template/.gemini/agents/frontend-developer.md

@@ -0,0 +1,31 @@
+# Frontend Developer
+
+**Role**: Frontend TDD implementation (component architecture)
+**When to Use**: Implement frontend tasks following the approved plan
+
+## Instructions
+
+Implement the task following the Implementation Plan in the ticket. Use strict TDD (Red-Green-Refactor). Follow logical order: Types > Services > Stores > Components > Pages.
+
+## Before Implementing
+
+1. Read ticket (including Spec and Implementation Plan)
+2. Read `ai-specs/specs/frontend-standards.mdc`
+3. Read `docs/specs/ui-components.md` for current UI component specs
+4. Read `docs/specs/api-spec.yaml` for API endpoints to consume
+5. Read `docs/project_notes/key_facts.md` and `bugs.md`
+
+## Documentation Updates (MANDATORY — in real time)
+
+- If adding/modifying a component → update `docs/specs/ui-components.md` BEFORE continuing
+- New environment variables → `.env.example`
+
+## Rules
+
+- ALWAYS follow TDD — write tests before implementation
+- ALWAYS follow the Implementation Plan
+- ALWAYS use explicit types (no `any`)
+- ALWAYS use `'use client'` for components with hooks
+- ALWAYS handle loading and error states
+- NEVER modify code outside the scope of the current ticket
+- ALWAYS verify implementation matches the approved spec. If deviation needed, document in sprint tracker's Active Session and ask for approval

package/template/.gemini/agents/frontend-planner.md

@@ -0,0 +1,34 @@
+# Frontend Planner
+
+**Role**: Frontend implementation planner (component architecture)
+**When to Use**: Before implementing frontend tasks — create implementation plan
+
+## Instructions
+
+Generate a detailed Implementation Plan and write it into the ticket's `## Implementation Plan` section. The plan must be detailed enough for the frontend-developer to implement autonomously.
+
+## Before Planning
+
+1. Read `docs/project_notes/key_facts.md`
+2. Read the ticket file (including `## Spec` section)
+3. Read `docs/specs/ui-components.md` for current UI component specs
+4. Read `docs/specs/api-spec.yaml` for API endpoints to consume
+5. Explore existing components, services, stores, pages
+6. Read `ai-specs/specs/frontend-standards.mdc`
+
+**Reuse over recreate.** Only propose new components when existing ones don't fit.
+
+## Output Sections
+
+- Existing Code to Reuse
+- Files to Create
+- Files to Modify
+- Implementation Order (Types > Services > Stores > Components > Pages > Tests)
+- Testing Strategy
+- Key Patterns
+
+## Rules
+
+- NEVER write implementation code — only the plan
+- ALWAYS check existing code before proposing new files
+- ALWAYS save the plan into the ticket

package/template/.gemini/agents/production-code-validator.md

@@ -0,0 +1,32 @@
+# Production Code Validator
+
+**Role**: Pre-commit code quality scanner
+**When to Use**: Before every commit — catches debug code, TODOs, secrets, hardcoded values, spec drift
+
+## Instructions
+
+Scan code systematically for issues that should never reach production:
+
+1. **Placeholder Code**: "lorem ipsum", "foo", "bar", stub implementations
+2. **TODO/FIXME**: Development notes, questions in comments
+3. **Hardcoded Values**: API keys, localhost URLs, credentials, feature flags
+4. **Debug Artifacts**: console.log, debugger statements, debug flags
+5. **Security Red Flags**: Disabled SSL, CORS *, hardcoded credentials
+6. **Error Handling**: Empty catch blocks, swallowed errors
+7. **Code Quality**: Unused imports, missing types, overly long functions
+8. **Spec Drift**: Routes not in api-spec.yaml, components not in ui-components.md, schema mismatches with Zod schemas in `shared/src/schemas/`
+
+## Output Format
+
+For each issue:
+```
+[SEVERITY: CRITICAL|HIGH|MEDIUM|LOW]
+File: <filename>
+Line: <line>
+Issue: <description>
+Recommendation: <how to fix>
+```
+
+## Summary
+
+Provide: issues by severity, production-readiness assessment (READY / NEEDS REVIEW / NOT READY), top 3 critical items.

package/template/.gemini/agents/qa-engineer.md

@@ -0,0 +1,23 @@
+# QA Engineer
+
+**Role**: QA Automation Engineer
+**When to Use**: After implementation and code review — hunt for edge cases
+
+## Instructions
+
+You assume the happy path works (checked by Developer). Hunt for edge cases, security flaws, and spec deviations. Verify implementation against `docs/specs/`.
+
+## Workflow
+
+1. Read ticket, specs (`api-spec.yaml`, `ui-components.md`), implementation code, and existing tests
+2. Identify missing test cases and spec deviations
+3. Run full test suite for regressions
+4. Create new edge-case tests (e.g., `*.edge-cases.test.ts`)
+5. Report findings (QA Verified or Issues Found)
+
+## Rules
+
+- NEVER modify implementation code — only write tests
+- ALWAYS write tests to expose bugs before reporting them
+- ALWAYS validate against spec definitions
+- ALWAYS run the full test suite to check for regressions

package/template/.gemini/agents/spec-creator.md

@@ -0,0 +1,24 @@
+# Spec Creator
+
+**Role**: Systems Analyst and API Designer
+**When to Use**: Before planning — draft or update specifications
+
+## Instructions
+
+Translate requirements into precise, standard-compliant specifications. Update global spec files AND the ticket's `## Spec` section.
+
+## Workflow
+
+1. Read the ticket or user request
+2. Read existing specs in `docs/specs/` (api-spec.yaml, ui-components.md) and `shared/src/schemas/` (if exists)
+3. Read relevant standards in `ai-specs/specs/`
+4. Propose spec changes to global files
+5. Write spec summary into ticket's `## Spec` section (Description, API Changes, Data Model Changes, UI Changes, Edge Cases)
+6. Ask for user review before finalizing
+
+## Rules
+
+- NEVER write implementation code — only specifications
+- ALWAYS follow existing patterns in spec files
+- ALWAYS update BOTH global spec files AND ticket's `## Spec` section
+- ALWAYS ask: "Does this spec look correct?"

package/template/.gemini/settings.json

@@ -0,0 +1,5 @@
+{
+  "model": "gemini-2.5-pro",
+  "temperature": 0.2,
+  "instructions": "Follow the development standards in ai-specs/specs/base-standards.mdc. Use the agent skills in .gemini/agents/ for specialized tasks."
+}

package/template/.gemini/styles/default.md

@@ -0,0 +1,19 @@
+# Default Gemini Style
+
+## Communication
+
+- Be concise and direct
+- Use English for all technical artifacts
+- Explain reasoning behind recommendations
+- Ask for user approval at checkpoints
+
+## Code Style
+
+- TypeScript with strict mode
+- Explicit types (no `any`)
+- Conventional commits for git messages
+- TDD methodology (Red-Green-Refactor)
+
+## Workflow
+
+Follow the Spec-Driven Development workflow defined in `ai-specs/specs/base-standards.mdc`.

package/template/AGENTS.md

@@ -0,0 +1,67 @@
+# AGENTS.md — Universal Project Instructions
+
+> This file is read by all AI coding tools (Claude Code, Gemini, Cursor, Copilot, Windsurf, etc.).
+> Tool-specific config goes in `CLAUDE.md` / `GEMINI.md`. Methodology goes in `ai-specs/specs/base-standards.mdc`.
+
+## Project Structure
+
+<!-- CONFIG: Adjust directories to match your monorepo layout -->
+
+```
+project/
+├── backend/     ← Backend (has its own package.json)
+├── frontend/    ← Frontend (has its own package.json)
+├── shared/      ← Shared Zod schemas (optional — see base-standards.mdc § Shared Types)
+└── docs/        ← Documentation (no package.json)
+```
+
+**Critical**: NEVER install dependencies in the root directory.
+
+| Action | Correct | Wrong |
+|--------|---------|-------|
+| Install backend dep | `cd backend && npm install pkg` | `npm install pkg` |
+| Run backend tests | `cd backend && npm test` | `npm test` |
+| Install frontend dep | `cd frontend && npm install pkg` | `npm install pkg` |
+
+## Project Memory
+
+Institutional knowledge lives in `docs/project_notes/`:
+
+- **sprint-X-tracker.md** — Sprint progress, **Active Session** (current task, next actions, open questions), completion log
+- **bugs.md** — Bug log with solutions and prevention notes
+- **decisions.md** — Architectural Decision Records (ADRs)
+- **key_facts.md** — Project configuration, ports, URLs, branching strategy
+
+## Session Recovery
+
+After context loss, new session, or context compaction — BEFORE continuing work:
+
+1. **Read sprint tracker** (`docs/project_notes/sprint-X-tracker.md`) → **Active Session** section
+2. If there is an active task → read the referenced ticket in `docs/tickets/`
+3. Respect the configured autonomy level — do NOT skip checkpoints
+
+## Anti-Patterns (Avoid)
+
+- Installing dependencies in root directory
+- Skipping approvals at configured autonomy level
+- Using `any` type without justification
+- Creating files when existing ones can be extended
+- Adding features not explicitly requested
+- Committing without updating ticket acceptance criteria
+- Forgetting to update sprint tracker's Active Session after step changes
+
+## Automated Hooks (Claude Code)
+
+The project includes pre-configured hooks in `.claude/settings.json`:
+
+- **Quick Scan** (`SubagentStop`): After `backend-developer` or `frontend-developer` finishes, a fast grep-based scan (~2s, no additional API calls) checks for `console.log`, `debugger`, `TODO/FIXME`, hardcoded secrets, and localhost references. Critical issues block; warnings are non-blocking (full review happens in Step 5).
+- **Compaction Recovery** (`SessionStart → compact`): After context compaction, injects a reminder to read the sprint tracker Active Session for context recovery.
+
+Personal notification hooks (macOS/Linux) are in `.claude/settings.local.json` — see that file for examples.
+
+## Standards References
+
+- [Base Standards](./ai-specs/specs/base-standards.mdc) — Constitution, methodology, workflow, agents
+- [Backend Standards](./ai-specs/specs/backend-standards.mdc) — Backend patterns (DDD, Express, Prisma)
+- [Frontend Standards](./ai-specs/specs/frontend-standards.mdc) — Frontend patterns (Next.js, Tailwind, Radix)
+- [Documentation Standards](./ai-specs/specs/documentation-standards.mdc) — Doc guidelines

package/template/CLAUDE.md

@@ -0,0 +1,19 @@
+<!-- See AGENTS.md for universal project instructions (structure, commands, memory, anti-patterns). -->
+<!-- See ai-specs/specs/base-standards.mdc for methodology (constitution, workflow, agents, git). -->
+
+## Claude-Specific Configuration
+
+<!-- CONFIG: Set your preferred autonomy level (1-4). See base-standards.mdc § Autonomy Levels for definitions. -->
+**Autonomy Level: 2 (Trusted)**
+
+<!-- CONFIG: Set branching strategy in docs/project_notes/key_facts.md (github-flow or gitflow) -->
+
+## Session Recovery (Claude Code)
+
+After context compaction or new session — BEFORE continuing work:
+
+1. Read sprint tracker (`docs/project_notes/sprint-X-tracker.md`) → **Active Session**
+2. If active task → read referenced ticket in `docs/tickets/`
+3. Read the active skill file (`.claude/skills/*/SKILL.md`)
+4. Do NOT proceed past any checkpoint without user confirmation (respect autonomy level)
+5. If Active Session shows a pending checkpoint, ask before continuing

package/template/GEMINI.md

@@ -0,0 +1,10 @@
+<!-- See AGENTS.md for universal project instructions (structure, commands, memory, anti-patterns). -->
+<!-- See ai-specs/specs/base-standards.mdc for methodology (constitution, workflow, agents, git). -->
+<!-- Note: Gemini agent files (.gemini/agents/) are intentionally concise. Full methodology details live in ai-specs/specs/ and AGENTS.md. -->
+
+## Gemini-Specific Configuration
+
+<!-- CONFIG: Set your preferred autonomy level (1-4). See base-standards.mdc § Autonomy Levels for definitions. -->
+**Autonomy Level: 2 (Trusted)**
+
+<!-- CONFIG: Set branching strategy in docs/project_notes/key_facts.md (github-flow or gitflow) -->

package/template/ai-specs/specs/backend-standards.mdc

@@ -0,0 +1,214 @@
+---
+description: Backend development standards, best practices, and conventions. Covers DDD architecture, API design, testing, security, and deployment patterns.
+globs: ["backend/src/**/*.ts", "backend/prisma/**/*.{prisma,ts}", "backend/jest.config.*", "backend/tsconfig.json", "backend/package.json"]
+alwaysApply: true
+---
+
+<!-- CONFIG: This file defaults to Node.js/Express/Prisma/PostgreSQL. Adjust for your stack. -->
+
+# Backend Standards
+
+## Technology Stack
+
+- **Runtime**: Node.js with TypeScript (strict mode)
+- **Framework**: Express.js
+- **ORM**: Prisma (PostgreSQL)
+- **Validation**: Zod
+- **Testing**: Jest (90% coverage threshold)
+- **Logging**: Pino (structured JSON logs)
+
+## Architecture — DDD Layered
+
+```
+backend/src/
+├── domain/                # Business logic (pure, no dependencies)
+│   ├── entities/          # Domain entities
+│   ├── errors/            # Domain-specific errors
+│   └── repositories/      # Repository interfaces
+├── application/           # Use cases and orchestration
+│   ├── services/          # Application services
+│   └── validators/        # Input validation (Zod schemas)
+├── infrastructure/        # External integrations
+│   ├── repositories/      # Prisma repository implementations
+│   ├── prismaClient.ts    # Prisma client setup
+│   └── logger.ts          # Logging utilities
+├── presentation/          # HTTP layer
+│   ├── controllers/       # Request handlers
+│   ├── routes/            # Express route definitions
+│   └── middleware/         # Express middleware
+├── index.ts               # Application entry point
+└── server.ts              # Server setup
+```
+
+### Layer Rules
+
+- **Domain**: No imports from other layers. Pure business logic.
+- **Application**: Imports from Domain only. Orchestrates use cases.
+- **Infrastructure**: Implements Domain interfaces. Prisma, external APIs.
+- **Presentation**: Imports from Application only. HTTP concerns.
+
+## Naming Conventions
+
+- **Variables/Functions**: camelCase (`findById`, `candidateId`)
+- **Classes/Interfaces**: PascalCase (`UserService`, `IUserRepository`)
+- **Constants**: UPPER_SNAKE_CASE (`MAX_PAGE_SIZE`)
+- **Files**: camelCase (`userService.ts`, `userController.ts`)
+- **Error files**: PascalCase (`UserError.ts`, `AuthError.ts`)
+
+## API Design
+
+### REST Endpoints
+```
+GET    /resource          # List (with pagination)
+GET    /resource/:id      # Get by ID
+POST   /resource          # Create
+PUT    /resource/:id      # Full update
+PATCH  /resource/:id      # Partial update
+DELETE /resource/:id      # Delete
+```
+
+### Response Format
+```json
+{
+  "success": true,
+  "data": { ... },
+  "message": "Operation completed successfully"
+}
+```
+
+### Error Response Format
+```json
+{
+  "success": false,
+  "error": {
+    "message": "Validation failed",
+    "code": "VALIDATION_ERROR",
+    "details": [...]
+  }
+}
+```
+
+### HTTP Status Codes
+- `200` Success
+- `201` Created
+- `400` Bad Request (validation errors)
+- `401` Unauthorized
+- `403` Forbidden
+- `404` Not Found
+- `409` Conflict
+- `500` Internal Server Error
+
+### Validation Endpoints Pattern
+Return HTTP 200 with `valid: false` for business validation failures (not 400). Service returns structured result objects (never throws). Only input validation errors throw → 400.
+
+## Error Handling
+
+- Custom domain error classes extending `Error`
+- Global error middleware for consistent responses
+- Never swallow errors (empty catch blocks)
+- Descriptive error messages in English
+
+```typescript
+export class NotFoundError extends Error {
+  constructor(entity: string, id: string) {
+    super(`${entity} not found with ID: ${id}`);
+    this.name = 'NotFoundError';
+  }
+}
+```
+
+## Validation
+
+- Validate all inputs at the application layer using Zod
+- Validate before executing business logic
+- Return descriptive validation errors
+
+```typescript
+import { z } from 'zod';
+
+const CreateUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2).max(100),
+  role: z.enum(['USER', 'ADMIN']),
+});
+```
+
+## Database Patterns
+
+### Prisma Best Practices
+- `schema.prisma` is the single source of truth for DB structure
+- Use descriptive migration names: `npx prisma migrate dev --name add_user_role`
+- Always use `include` when the frontend reads relation fields
+- Convert Decimal fields with `Number()` before arithmetic
+- Import enums from generated path (not the main client import)
+- `@unique` already creates an index — no need for redundant `@@index`
+
+### Repository Pattern
+```typescript
+// Domain layer — interface
+export interface IUserRepository {
+  findById(id: string): Promise<User | null>;
+  save(user: User): Promise<User>;
+}
+
+// Infrastructure layer — implementation
+export class PrismaUserRepository implements IUserRepository {
+  constructor(private prisma: PrismaClient) {}
+
+  async findById(id: string): Promise<User | null> {
+    return this.prisma.user.findUnique({ where: { id } });
+  }
+}
+```
+
+## Testing Standards
+
+### Structure (AAA Pattern)
+```typescript
+describe('UserService - findById', () => {
+  beforeEach(() => jest.clearAllMocks());
+
+  it('should return user when found', async () => {
+    // Arrange
+    const mockUser = { id: '1', name: 'Test' };
+    mockRepo.findById.mockResolvedValue(mockUser);
+
+    // Act
+    const result = await service.findById('1');
+
+    // Assert
+    expect(result).toEqual(mockUser);
+    expect(mockRepo.findById).toHaveBeenCalledWith('1');
+  });
+});
+```
+
+### Test Categories (all required)
+1. **Happy Path**: Valid inputs → expected outputs
+2. **Error Handling**: Invalid inputs, DB errors, missing data
+3. **Edge Cases**: Boundary values, null/undefined, empty data
+4. **Validation**: Input validation, business rule enforcement
+
+### Mocking
+- Mock all external dependencies (DB, services)
+- Mock repository layer in service tests
+- Mock service layer in controller tests
+- Use `jest.mock()` at top of test files
+- Clear all mocks in `beforeEach()`
+
+## Security
+
+- Validate ALL user inputs before processing
+- Never commit `.env` files or secrets
+- Validate required environment variables at startup
+- Use parameterized queries (Prisma handles this)
+- Configure CORS to allow only specific origins in production
+- Use dependency injection for testability
+
+## Performance
+
+- Use Prisma `include` instead of N+1 queries
+- Select only needed fields for large datasets
+- Use `Promise.all()` for independent parallel operations
+- Implement proper pagination for list endpoints
+- Add database indexes for frequently queried fields

package/template/ai-specs/specs/base-standards.mdc

@@ -0,0 +1,157 @@
+---
+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-4)
+- **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, sprint 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 |
+|------------|:-:|:-:|:-:|:-:|
+| Spec Approval | Required | Auto | Auto | Auto |
+| Ticket Approval | Required | Auto | Auto | Auto |
+| Plan Approval | Required | Required | Auto | Auto |
+| Commit Approval | Required | Auto | Auto | Auto |
+| Merge Approval | Required | Required | Required | Auto |
+
+- **L1 Full Control**: First sprint 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 at sprint boundaries only.
+
+**Auto** = proceed without asking; log in sprint 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) |
+| `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 sprint 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 sprint 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/sprint<N>-<task-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/sprint<N>-<task-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.