Gene: [Name]
  Clear, specific identifier

Context: [Why this rule exists]
  The reasoning behind the decision

Rule: [The actual decision]
  The explicit constraint or pattern

Constraints: [What this affects or limits]
  Which other genes or strands this impacts

Example: [Real-world application]
  How this looks in practice

Executor: [Human | AI | Hybrid]
  Who executes this gene in practice

AI Scope: [Allowed actions / Prohibited actions]
  What the AI may automate vs. must not do

Review: [None | Spot-check | 100% sign-off]
  Human oversight required for outputs

Data: [Approved data sources / scopes]
  What data the executor (AI/Human) may access

Audit: [Log spec]
  How outputs, prompts, and decisions are recorded

Tests: [Acceptance criteria]
  Small set of checks that prove compliance

Gene: Brand Voice - Person
Context: We want to feel direct and personal, not corporate
Rule: Always write in second person ("you"), never third person ("users" or "customers")
Constraints:
  - Applies to all product copy, docs, and marketing
  - Sales emails can use first person ("we") when appropriate
Example:
  ✅ "Your data is encrypted"
  ❌ "User data is encrypted"
Executor: Hybrid
AI Scope:
  - May rewrite drafts into second person
  - Must not publish without human spot-check for key pages
Review: Spot-check
Data: Public brand guide + approved copy corpus
Audit: Store diffs of AI rewrites with author + timestamp
Tests:
  - 10-sample monthly audit shows ≥95% second-person compliance

Gene: Feature Scope - Power Users First
Context: We're building for experts, not beginners. Depth matters more than ease.
Rule: New features must provide value to power users. If a feature is "nice for beginners but not useful for experts," we don't build it.
Constraints:
  - Onboarding features are the exception
  - If experts would turn it off, don't ship it
Example:
  ✅ Advanced filters, keyboard shortcuts, batch actions
  ❌ Tooltips explaining basic concepts
Executor: Human
AI Scope:
  - May suggest features based on usage data
  - Must not decide scope without human approval
Review: 100% sign-off for new features
Data: User research, usage metrics
Audit: Feature approval tickets retained 12 months
Tests:
  - User testing shows power users benefit clearly

Gene: Button Hierarchy
Context: Consistent visual weight prevents decision paralysis
Rule:
  - Primary button: Solid, brand color, for main action
  - Secondary button: Outline, brand color, for alternate action
  - Tertiary button: Text only, for low-priority actions
  - Max one primary button per screen section
Constraints:
  - Destructive actions use tertiary with red text
  - Loading states maintain button type (primary stays primary)
Example:
  In a modal:
    - "Save" = Primary
    - "Cancel" = Tertiary
Executor: AI
AI Scope:
  - May enforce button styles via linting
  - Must not change button hierarchy without review
Review: None for style enforcement, Human for hierarchy changes
Data: UI component library
Audit: CI logs for linting violations
Tests:
  - CI fails if button hierarchy rules are violated

Gene: Error Handling - Inline First
Context: Errors should appear where the problem is, not as interruptions
Rule:
  - Form errors: Inline, next to the field
  - Action errors: Toast notification, bottom-right
  - System errors: Modal, only when action cannot continue
Constraints:
  - Never use alert() or browser dialogs
  - Errors must be dismissable (except blocking modals)
Example:
  - Email validation fails → red text below field
  - Network request fails → toast: "Connection lost. Retrying..."
Executor: AI
AI Scope:
  - May lint PRs and auto-comment when rules are violated
  - May open autofix PRs for copy-only or placement changes
Review: None for lint comments, Human merge for autofix PRs
Data: UI codebase + component library
Audit: CI logs of violations and autofix PRs
Tests:
  - CI blocks merge if violations > 0

Gene: API Response Format
Context: Consistent API responses simplify client code and reduce bugs
Rule: All API endpoints return JSON:API format
  {
    data: {...},
    meta: {...},
    errors: [...]
  }
Constraints:
  - No direct status codes in response body
  - Use HTTP status codes correctly (200, 400, 500)
  - Errors always as array, even if single error
Example:
  Success: { data: { id: 1, name: "..." }, meta: { timestamp: ... } }
  Error: { errors: [{ status: 400, detail: "Invalid email" }] }
Executor: Hybrid
AI Scope:
  - May enforce via schema checks and code mods
  - Must not accept breaking changes without ticket + approval
Review: 100% sign-off for schema changes
Data: API repo + contract tests
Audit: Contract test artifacts retained 12 months
Tests:
  - Contract tests pass across all endpoints

Gene: PII Access Control
Context: Privacy is non-negotiable, access must be auditable
Rule: Personally Identifiable Information (PII) only accessible by:
  - Backend services with explicit need
  - Admin users with 2FA enabled
  - All access logged to audit table
Constraints:
  - Frontend never receives raw PII (emails, addresses, etc.)
  - Use masked/hashed versions for display
  - Logs stored for 2 years minimum
Example:
  - Admin sees: "john.doe@example.com"
  - Frontend sees: "j****e@example.com"
Executor: Human
AI Scope:
  - May not access or process PII
  - May scan for compliance and report issues
Review: 100% sign-off for access changes
Data: User data access logs
Audit: Access logs retained 2 years
Tests:
  - Regular audits show no unauthorized PII access

Gene: AI Disclosure
Context: Users must know when they're talking to AI vs. human
Rule: Always disclose AI-generated responses with visual indicator:
  - Avatar labeled "AI"
  - Subtle badge on message card
  - Disclaimer on first AI message in thread
Constraints:
  - Never pretend AI is human
  - Even when AI is 99% accurate
Example:
  AI message includes: "✨ AI-generated response"
Executor: AI
AI Scope:
  - May generate and send AI disclosures
  - Must not disable or obscure disclosure
Review: None
Data: N/A
Audit: Log all AI-generated messages
Tests:
  - 100% of AI messages include disclosure

Gene: Meeting-Free Days
Context: Deep work requires uninterrupted blocks
Rule: No internal meetings on Tuesdays and Thursdays
Constraints:
  - Applies to all teams
  - External meetings (customers, investors) allowed
  - Exceptions require CEO approval
Example:
  - Monday: Planning meeting
  - Tuesday: Deep work
  - Wednesday: Sync meetings
  - Thursday: Deep work
  - Friday: Retros, demos
Executor: Human
AI Scope:
  - May suggest agenda items or action points
  - Must not schedule or cancel meetings
Review: None
Data: Team calendars
Audit: Meeting logs
Tests:
  - Calendar audit shows no internal meetings on off days

Gene: Discount Approval Matrix
Context: Prevent margin erosion while giving reps flexibility
Rule:
  - 0-10% discount: Rep decides
  - 11-15% discount: Sales Manager approval
  - 16-20% discount: VP Sales approval
  - >20% discount: CEO approval + written justification
Constraints:
  - Discounts apply to annual contracts only
  - No stacking multiple discounts
Example:
  - $10k deal, 12% discount → Sales Manager approval required
Executor: Human
AI Scope:
  - May suggest discounts based on deal size and history
  - Must not approve discounts over 10% without manager
Review: Spot-check for large discounts
Data: Sales data, discount history
Audit: Discount approval logs
Tests:
  - 100% of discounts over 10% have manager approval

Gene: Model Selection by Use Case
Context: Different models for different needs, optimize for cost/performance
Rule:
  - Reasoning tasks (complex decisions): Claude Sonnet
  - Speed tasks (autocomplete, suggestions): GPT-4o
  - Embeddings: OpenAI text-embedding-3-small
Constraints:
  - Never use o1 for production (too slow)
  - Switch models based on latency SLAs
Example:
  - Code review analysis → Claude Sonnet
  - Search query expansion → GPT-4o
Executor: AI
AI Scope:
  - May select and switch models based on task
  - Must not use deprecated or unapproved models
Review: None
Data: Model registry
Audit: Model usage logs
Tests:
  - 100% of tasks use approved models

Gene: Authentication Method
Context: Passwords are a security risk and support burden
Rule: OAuth only. No password-based auth.
  - Supported providers: Google, GitHub, Microsoft
  - Magic links for email-only users
Constraints:
  - No "forgot password" flows
  - No password storage, no bcrypt, no complexity rules
Example:
  - Login page shows: "Sign in with Google/GitHub/Microsoft"
  - Email-only option sends magic link
Executor: Human
AI Scope:
  - May not create exceptions or temporary backdoors
  - May scan for violations and open issues
Review: 100% sign-off for auth changes
Data: Auth config + infra code
Audit: Security review tickets mandatory
Tests:
  - Pen tests confirm zero password paths

Gene: AI Assignment & Guardrails
Context: Avoid misuse of AI; keep humans in charge of high-risk areas
Rule:
  - Tag each gene with Executor = Human | AI | Hybrid
  - AI may automate reversible, testable tasks only
  - Human sign-off required for legal, HR, security, pricing, or irreversible commits
Constraints:
  - AI cannot approve contracts, grant prod access, or override security policies
  - AI must operate within approved tools and data scopes
Example:
  - AI drafts an SOW → Human must approve before sending
Executor: Human
AI Scope:
  - Generate drafts, validations, alerts; no final approvals
Review: 100% sign-off for outputs affecting customers or prod
Data: Only approved, non-PII corp data unless DPO-approved
Audit: Store prompts/outputs for 90 days; link to tickets
Tests:
  - Random weekly audit of 20 AI outputs → 0 critical violations

Old: "Use REST APIs"
New: "Use GraphQL for client-server, REST for service-service"

Parent: "Brand colors for interactive elements"
Child: "Hover states darken brand color by 10%"

Deprecated: "Support IE11"
Reason: <1% of users, too much maintenance cost