Skip to content

Executor Component Specification

This document specifies the implementation of the Generic Phase Executor, the worker component responsible for running Agent Skills.

1. Overview

The Executor is a Python class (GenericPhase) that wraps the Claude SDK. It is "Generic" because it has no hardcoded prompts; it loads everything at runtime from the farmerspec definitions embedded in the workspace.

References: * Interface: 02-interface.md defines the inputs (contract.yaml) and expected outputs. * Infrastructure: 06-infrastructure.md defines the environment variables and S3 paths.

2. Execution Logic

Kroki

Class Structure

class GenericPhase:
    def __init__(self, skill_path: str):
        """
        :param skill_path: Path relative to .farmerspec root 
                           (e.g., 'agents/pm/skills/validate-wrd')
        """
        self.skill_path = skill_path

    async def execute(self, input_data: dict, version: str) -> PhaseResult:
        # 1. Sync Git State (Fetch/Checkout start_sha)
        # 2. Load Contract & Prompts from .farmerspec/{self.skill_path}/
        # 3. Augment Prompt:
        #    - Parse `decision_making` from contract.yaml
        #    - Load referenced knowledge files
        #    - Append to System Prompt
        # 4. Run Agent Loop (Claude)
        # 5. Commit & Push Changes
        # 6. Sync Telemetry to S3
        # 7. Return Result with new SHA

3. Key Implementation Details

Prompt Assembly & Decision Context

The Executor is responsible for assembling the full context. It does not just blindly pass SKILL.md.

  1. Base: SKILL.md content.
  2. Context: The Executor iterates over contract.decision_making.sources:
    • If source is a file path, read it from .farmerspec/ or workspace.
    • If source is $input, inject the input data.
    • Append to the prompt under a ## Context section.
  3. Format: Executes generate-decision-prompt.py (found in .farmerspec/_shared/) to append the strict JSON schema instructions.

Tool Configuration

The Executor maps the string lists in contract.yaml to actual Claude SDK permissions.

  • "Bash": Enables the Bash tool (Agent uses this for git operations).
  • "Read": Enables file reading.
  • "Edit"/"Write": Enables file modification.

Universal Eager Sync (Telemetry)

While code state is preserved via Git Commits, detailed logs (prompts, raw responses, thinking traces) are too heavy for Git.

  1. Write all telemetry (JSONs) to local .farmercode/runs/{id}/.
  2. Execute aws s3 sync .farmercode/runs/{id}/ s3://{bucket}/runs/{id}/.
  3. Only return to Temporal after the command succeeds.

Validation Strategy

The Executor implements Deterministic Validation based on the contract.yaml schema. * Check 1: Is the response valid JSON? * Check 2: Does it have status and result? * Check 3: Does result match the outputs schema in the contract?

If validation fails, the Executor treats it as a Phase Failure.