The Build Plan

Code Rules: The Constraint System

AI agents follow rules. But they only follow rules they can read. The constraint system is a set of files, checked into the repo, that every agent reads before writing code. Without these files, each agent session invents its own conventions.

There are two types of rule files: RULES.md (for the codebase) and CLAUDE.md or equivalent (for the AI agent's behavior).

RULES.md: Per-Package Constraints

Every package in the monorepo has its own RULES.md. The root RULES.md defines global constraints. Package-level files define local constraints. The agent reads both before working in that package.

What Makes a Good Rule

Every rule must be a testable assertion. Not "keep things organized" but "apps import from packages, never from other apps." The first is a suggestion. The second can be verified by a linter, an import restriction, or an architectural fitness test.

# Root Rules

## Import Boundaries
- Apps import from packages, never from other apps.
- packages/api is the sole bridge to infrastructure.
  Apps never import packages/db directly.
- packages/ui owns all shared UI components.
  No component is defined in an app directory.
- packages/ai is the sole LLM gateway.
  No app calls OpenAI/Anthropic directly.

## Tenant Isolation
- Every table with user data has a workspace_id column.
- Every query uses workspaceDb(workspaceId), never the raw db.
- Every tRPC mutation validates the resource belongs to
  the current workspace before modifying it.

## Naming Conventions
- Database tables: snake_case plural (issues, projects, cycles)
- TypeScript types: PascalCase (Issue, Project, Cycle)
- tRPC routers: camelCase (issue.list, issue.create)
- File names: kebab-case (issue-list.tsx, create-issue.ts)
- CSS tokens: kebab-case with double-dash (--color-accent)

## Testing
- No shallow assertions: toBeDefined(), toBeTruthy(),
  toBeFalsy() are banned as standalone assertions.
- Every async test uses expect.assertions(N).
- Every DB test verifies state with an independent query.
- Every new table has a tenant isolation test.

# Database Package Rules

## Migrations
- Migrations are forward-only. No down migrations.
- If a migration needs reverting, write a new forward
  migration that undoes the change.

## Schema
- Every table has: id (uuid), workspace_id (uuid),
  created_at (timestamptz), updated_at (timestamptz).
- Use timestamptz, never timestamp (timezone-naive).
- Soft delete: use archived_at (timestamptz), never
  delete rows.

## RLS
- Every new table must have an RLS policy:
  workspace_id = current_setting('app.workspace_id')::uuid
- RLS is enabled on the table, not just defined.

Agent Instruction Files

Agent instruction files (CLAUDE.md for Claude Code, .cursorrules for Cursor, etc.) tell the AI agent how to behave in this specific project. They are different from code rules: code rules constrain what the code does, agent instructions constrain how the agent works.

What Agent Instructions Cover

• Read before working: Which files to read before modifying any file in this directory.
• Commands to use: Which test runner, linter, and build tool to use. The exact commands.
• Patterns to follow: "When creating a new tRPC router, follow the pattern in packages/api/src/routers/issue.ts."
• What never to do: "Never use any type. Never use console.log (use the logger package). Never install packages without checking the allow-list."

Tiered Structure

Agent instructions are tiered: root-level for global behavior, directory-level for package-specific behavior. The agent reads both, with local instructions overriding global ones for that directory.

# Repository structure of agent instructions
.claude/           or equivalent for your agent
  CLAUDE.md        Root: global behavior, commands, project overview

packages/db/
  CLAUDE.md        DB-specific: migration workflow, schema conventions

packages/api/
  CLAUDE.md        API-specific: router patterns, error handling

packages/ui/
  CLAUDE.md        UI-specific: component structure, token usage, accessibility

The Master PRD Index

The Master PRD Index is the complete roadmap. Every feature is a named unit with an ID, milestone assignment, category, dependencies, and test pair. This is the document that answers: "What do I build next?"

Structure

The index is organized by milestone. Each milestone has a name, a theme, and a list of units. Each unit has:

Sequencing Strategy

The build order follows three principles:

1. Backend before frontend. The API must exist before the UI can consume it. Backend units create tables, routers, and business logic. Frontend units create components that call those routers.

2. Core before periphery. Auth and workspace management before features. CRUD before advanced views. Data model before reporting.

3. Integration test + consolidation per milestone. Every milestone ends with cross-unit integration tests and a refactoring pass. This prevents technical debt from compounding across milestones.

What You Leave With

This completes the foundation layer. You now have: product definition (Part 1), infrastructure decisions (Part 2), visual language (Part 3), and build plan (Part 4). Everything a PRD needs to reference exists. Part 5 begins the building phase: writing PRDs that AI agents can execute.