Skip to content

Farmerspec Interface Definition

This document defines the Data Contract between the Farmerspec repository and the Farmercode system. This is the interface that the Executor loads at runtime.

1. Skill Structure

Each skill must adhere to this file structure:

agents/{agent}/skills/{skill}/
├── SKILL.md                      # The Base Prompt
├── contract.yaml                 # The Configuration & Schema
└── generate-decision-prompt.py   # Symlink to agents/_shared/generate-decision-prompt.py

All shared logic, including the response format generator, resides in: agents/_shared/generate-decision-prompt.py

2. The Contract (contract.yaml)

This YAML file is the single source of truth for the skill's capabilities and expected inputs/outputs. The Executor is invoked using the absolute or relative path to this skill directory (e.g., agents/pm/skills/validate-wrd), ensuring unambiguous resolution regardless of agent grouping.

name: validate-wrd
agent: pm
description: Validate WRD completeness

# 1. Inputs: What the Workflow passes to the Executor
inputs:
  wrd_content:
    type: string
    required: true

# 2. Outputs: The JSON schema the Agent MUST produce
outputs:
  status:
    type: enum
    values: [proceed, needs_clarification, rejected]
  result:
    type: object
    required: [title, classification]

# 3. Execution Config: Runtime settings
config:
  model: opus
  cwd: $PROJECT_ROOT  # See "Path Resolution" in Infrastructure spec
  tools:
    allowed: [Read, Bash]  # Maps to Claude SDK tools
    disallowed: [Edit, Write]

# 4. Decision Sources: For RL traceability
decision_making:
  sources:
    knowledge:
      - ../../../_shared/farmer1st-mission.md
    wrd: $input

3. Prompt Assembly

The final System Prompt passed to the Agent is constructed dynamically:

  1. Base: Content of SKILL.md.
  2. Response Format: Generated by executing generate-decision-prompt.py (which reads contract.yaml).

Universal Response Format

All agents, regardless of skill, return this JSON structure:

{
  "status": "proceed",
  "result": { ... },  // Validated against contract.outputs.result
  "blockers": [],
  "feedback": {
    "on_input": { "gaps": [], "suggestions": [] },
    "on_agent": {
      "decisions": [
        {
          "decision": "Decided X",
          "source": "knowledge",
          "reference": "mission.md",
          "confidence": 0.9
        }
      ]
    }
  }
}

4. Versioning

  • Deployment: farmerspec is deployed via Git Tags.
  • Runtime: The Workflow requests a specific tag (e.g., v1.2.0).
  • Execution: The Worker fetches that specific tag to ensure 100% reproducibility of prompts and schemas.