Skip to content

Farmercode System Architecture

This document defines the high-level architecture, operating modes, and data flow of the Farmercode system. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et ismod nulla. Curabitur feugiat, tortor non consequat finibus, usto purus auctor.

1. Core Concept

Farmercode is a Temporal-based workflow system that orchestrates multi-agent software development phases. It separates the Mode (the rules of the workload) from the Environment (the execution and persistence logic).

Kroki

2. Agent Roles

Farmercode uses functional roles to distinguish between creator and validator behaviors. These roles are code-named to ensure consistency across the monorepo:

  • Duc (The Creator): Responsible for implementation, creation of blueprints, and writing code. Focuses on fulfillment.
  • Baron (The Validator): Responsible for review, validation, and enforcement of standards. Acts as the "Human-in-the-Loop" proxy or escalation gate.

An Agent (e.g., architect) can perform multiple skills, often alternating between Duc and Baron roles depending on the workflow phase.

3. Operating Modes

Live Mode (Production)

Target: farmer1st-stack (Monorepo) * Purpose: Production feature development. * Human-in-the-Loop: Uses GitHub Issues for transparency and "Baron" escalation gates. * Flow: 1. Workflow creates a Parent Issue ("WRD"). 2. Each Activity Group (e.g., Blueprint) gets a Sub-issue. 3. Agents post comments and commits. 4. Escalation: Workflow sleeps (await_signal) until a human comments.

RL Mode (Training)

Target: farmer1st-stack-rl (Sandbox Fork) * Purpose: Autonomous data collection for agent training. * Batch Execution: Parallel runs using Git Worktrees. * Flow: 1. Workflow prepares a Scenario (e.g., "greenfield_iac" - deletes Terraform to force rebuild). 2. Agents execute phases silently (no GitHub Issues). 3. Escalation: Workflow Flags and Terminates immediately (valuable negative data).

3. Data Flow & Storage

Farmercode uses a Split Storage strategy to prevent git bloat.

Data Type Storage Location Purpose
Code Git Version control, diffs, merge requests.
Telemetry S3 (Primary) Heavy JSON logs (prompts, responses), debug data.

Universal Eager Sync: The Executor writes telemetry to a local folder and blocks until it is successfully synced to S3. This ensures data is safe even if the worker crashes immediately after execution.

4. Component Map

  1. Farmerspec (farmerspec): Immutable source of truth for Agent Skills (SKILL.md, contract.yaml).
  2. Farmercode (farmercode): The Control Plane.
    • Workflow: Temporal Python code defining the sequence.
    • Executor: Generic runtime for invoking Claude SDK.
    • GitHub Middleware: GitHub Webhook listener for Live Mode signals.
  3. Target Repos:
    • farmer1st-stack: Production code.
    • farmer1st-stack-rl: Training sandbox.