Skip to content

Farmer Code Constitution

This constitution defines the principles, standards, and governance for Farmer Code projects. Implementation-specific details (tooling, patterns, commands) are in agent knowledge files.

Core Principles

I. Test-First Development (NON-NEGOTIABLE)

Rule: Tests MUST be written before implementation code. No exceptions.

  • Tests are designed and approved BEFORE any code is written
  • Tests MUST fail initially (red phase)
  • Implementation proceeds only to make tests pass (green phase)
  • Red-Green-Refactor cycle is strictly enforced

Rationale: Test-first development ensures code meets requirements, reduces defects, provides living documentation, and enables confident refactoring.

II. Specification-Driven Development

Rule: All features MUST have approved specifications before implementation begins.

  • User scenarios define what to build (spec.md)
  • Architecture defines how it fits together (architecture.md)
  • Placement defines where to build (placement.md)
  • Test plans define verification criteria

Rationale: Specifications prevent miscommunication, enable parallel work, and ensure stakeholder alignment.

III. Independent User Stories

Rule: User stories MUST be independently implementable, testable, and deliverable.

  • Each user story has explicit priority (P1, P2, P3...)
  • Stories can be implemented in isolation
  • MVP is achievable with P1 stories alone

Rationale: Independent stories enable incremental delivery and risk mitigation.

IV. Human Approval Gates

Rule: Four mandatory human approval gates MUST be passed before merge.

Gate What Who Approves
Gate 1 Specifications & Architecture Tech Human
Gate 2 Test Design Tech Human
Gate 3 Implementation Tech Human
Gate 4 Code Review & Merge Tech Human

Rationale: Human oversight ensures alignment with business goals and catches issues AI agents cannot evaluate.

V. Simplicity and YAGNI

Rule: Implement only what is needed. Complexity MUST be justified.

  • Start with simplest solution that meets requirements
  • Additional complexity requires documented justification
  • Premature abstraction is prohibited
  • Future requirements do not justify current complexity

Rationale: Simple code is maintainable, debuggable, and adaptable.

VI. Thin Client Architecture (NON-NEGOTIABLE)

Rule: ALL business logic, validation, and intelligence MUST reside in the backend.

Prohibited in Clients: - ❌ Business rule validation - ❌ Calculations or transformations - ❌ Authorization decisions - ❌ Workflow logic or state machines

Allowed in Clients: - ✅ Form input validation (format only) - ✅ UI state (modals, tabs) - ✅ Display formatting - ✅ Client-side routing

Rationale: Thin client architecture enables multiple client implementations and centralizes business logic.

VII. Security-First Development

Rule: Security is a habit, not a feature.

Required: - Secrets in environment variables (never in code) - All inputs validated - No raw SQL (use ORM) - Passwords hashed (never plaintext)

Prohibited: - ❌ Secrets in version control - ❌ eval() or exec() functions - ❌ Unvalidated user input in queries

Rationale: Security habits prevent future vulnerabilities.

Technology Stack

High-level technology choices. Implementation details are in agent knowledge files.

Backend

  • Language: Python 3.11+
  • Framework: FastAPI
  • ORM: SQLAlchemy 2.0+ (async)
  • Validation: Pydantic v2
  • Database: PostgreSQL (prod), SQLite (local dev)

Frontend

  • Language: TypeScript 5.0+
  • Framework: React 18+
  • Build: Vite
  • Styling: Tailwind CSS + shadcn/ui
  • State: TanStack Query (server), Zustand (client)

Infrastructure

  • Containers: Docker
  • Orchestration: Kubernetes (EKS)
  • IaC: Terraform
  • CI/CD: GitHub Actions

Monorepo

  • Build System: Turborepo
  • Package Manager: pnpm (frontend), uv (backend)

For implementation details (commands, patterns, file structures), see agent knowledge files: - Dede: agents/dede/knowledge/ - Dali: agents/dali/knowledge/ - Gus: agents/gus/knowledge/ - Duc: agents/duc/knowledge/

Quality Standards

Testing Requirements

  • Contract tests for all public interfaces
  • Integration tests for user journeys
  • Backend: pytest with 80% coverage for new code
  • Frontend: Vitest (unit), Playwright (E2E)
  • Tests MUST fail before implementation

Code Review Standards

  • Implementation MUST match approved specs
  • All tests MUST pass
  • Type errors are blocking
  • Linting violations MUST be fixed

Documentation Requirements

  • All features have spec.md, architecture.md, placement.md
  • User journeys documented and linked to E2E tests
  • API endpoints documented with OpenAPI
  • Module READMEs required

Performance Standards

  • API response: p95 < 200ms for CRUD
  • Frontend: Core Web Vitals passing
  • Build: Incremental < 10s with Turborepo

Versioning and Change Control

Conventional Commits (REQUIRED)

<type>(<scope>): <description>

Types: feat, fix, docs, style, refactor, test, chore
Breaking: Add ! after type (e.g., feat!: change API)

Semantic Versioning

  • MAJOR: Breaking changes
  • MINOR: New features (backward compatible)
  • PATCH: Bug fixes

CI/CD Requirements

Required Checks (all must pass)

  • Linting
  • Type checking
  • Unit tests
  • Integration tests
  • E2E tests

Branch Protection

  • Main branch protected (no direct pushes)
  • Required reviews: At least 1 approval
  • Required status checks: CI must pass

Monorepo Structure

farmer-code/
├── apps/
│   ├── api/              # Backend (Python/FastAPI)
│   └── web/              # Frontend (Vite/React)
├── packages/             # Shared code
├── infra/
│   ├── k8s/              # Kubernetes manifests
│   └── terraform/        # IaC
├── docs/                 # Documentation
├── specs/                # Feature specifications
└── .farmerspec/          # Farmerspec working directory

Workspace Rules

  • Apps MUST NOT depend on other apps
  • Apps MAY depend on packages
  • Shared code MUST live in packages

Governance

Amendment Process

  1. Proposed changes documented with rationale
  2. Impact analyzed
  3. Version bumped per semantic versioning
  4. Dependent artifacts updated

Versioning Rules

  • MAJOR: Backward incompatible governance changes
  • MINOR: New principles or material expansions
  • PATCH: Clarifications, wording improvements

Compliance Enforcement

  • All PRs MUST pass constitution compliance
  • CI/CD enforces linting, type checking, tests
  • Human reviewers verify compliance at each gate

Version: 2.0.0 | Ratified: 2026-01-12

Change from v1: Implementation details moved to agent knowledge files for better maintainability.