Phase 01: WRD Intake

INPUT		PROCESSING		OUTPUT
`wrd-{type}-{slug}.yaml`	⮕	Input files Validate input (deterministic) Execute phase (Baron LLM) Validate output (deterministic) Validate output (Baron LLM)	⮕	`wrd_intake.json`

Overview

Baron (PM agent) receives a WRD (Work Requirements Definition) and validates it. This is Phase 1 of the 13-phase TDD workflow.

Execution Steps

Step	Name	Agent	On Failure
1	Input files	-	-
2	Validate input (deterministic)	Code	FAIL
3	Execute phase	Baron (Executor)	FAIL
4	Validate output (deterministic)	Code	FAIL
5	Evaluate output	Baron (Evaluator)	ABORT (if escalate)

Dual-Agent Model: Baron executes (Step 3), then a fresh Baron instance evaluates (Step 5). The evaluator verifies the executor's source claims.

Escalation = Abort: If Baron's evaluation escalates, the run is aborted and human review is required.

This is the entry point to the Farmerspec workflow.

Document Format

All WRD documents MUST be valid YAML files.

Requirement	Description
Format	YAML 1.2
Extension	`.yaml`
Naming	`wrd-{type}-{slug}.yaml`
Encoding	UTF-8
Validation	Baron validates against JSON Schema before acceptance

Examples: - wrd-feature-google-oauth.yaml - wrd-tech-api-pagination.yaml - wrd-bug-payment-timeout.yaml

YAML is mandatory because: - Machine-readable: Baron can parse and validate programmatically - Human-readable: Easy to write and review - Consistent: All agents use the same structured format - Tooling: Enables linters, validators, and IDE support

WRD Types

Type	Purpose	First Assignee
Feature	New capability for users	Duc (architect)
Tech	Technical improvement, refactor, infrastructure	Duc (architect)
Bug	Fix for existing functionality	Duc (architect)

Feature WRD Schema

Features are user-facing capabilities that require architectural consideration. Features must define user journeys that describe how users interact with the system.

File: wrd-feature-{slug}.yaml

User Journey ID Format

Each user journey has a unique identifier:

{DOMAIN}-{NNN}

Part	Description	Examples
`DOMAIN`	2-8 uppercase letters identifying the domain/category	`AUTH`, `USERMGT`, `PAY`, `NOTIF`, `CART`, `SEARCH`
`NNN`	3-digit sequential number within the domain	`001`, `002`, `042`

Examples: - AUTH-001 - First journey in Authentication domain - USERMGT-003 - Third journey in User Management domain - PAY-012 - Twelfth journey in Payments domain - REFUND-001 - First journey in Refunds domain

Schema

type: feature
title: string                    # Short, descriptive title
description: string              # What the feature does (user perspective)

# USER JOURNEYS - Required for features
user_journeys:
  - id: string                   # Format: {DOMAIN}-{NNN} (e.g., AUTH-001)
    title: string                # Short journey title
    actor: string                # Who performs this journey
    goal: string                 # What they want to achieve
    trigger: string              # What initiates the journey
    preconditions:               # What must be true before starting
      - string
    steps:                       # Ordered steps in the journey
      - step: integer            # Step number
        action: string           # What the user does
        system_response: string  # What the system does
    postconditions:              # What is true after completion
      - string
    exceptions:                  # Alternative/error flows
      - name: string
        trigger: string
        outcome: string

acceptance_criteria:             # List of testable conditions
  - string
  - string

scope:
  in:                            # Explicitly included
    - string
  out:                           # Explicitly excluded
    - string

priority: P0 | P1 | P2 | P3      # P0 = critical, P3 = nice to have
requested_by: string             # Who requested this
target_date: date | null         # Optional deadline

context:                         # Optional additional context
  related_features: [string]     # Links to related features
  related_journeys: [string]     # Links to related user journeys
  documents: [string]            # Links to external docs (PRD, designs, etc.)
  notes: string                  # Any additional context

Example: User Authentication Feature

type: feature

title: User Authentication with OAuth2

description: |
  Allow users to sign in using their Google or GitHub accounts instead of 
  creating a new username/password combination. This reduces friction during 
  onboarding and improves security by leveraging established identity providers.

user_journeys:
  - id: AUTH-001
    title: Sign in with Google
    actor: New or returning user
    goal: Access the application using Google credentials
    trigger: User clicks "Sign in with Google" button on login page
    preconditions:
      - User has a valid Google account
      - User is on the login page
      - User is not already authenticated
    steps:
      - step: 1
        action: User clicks "Sign in with Google" button
        system_response: System redirects to Google OAuth consent screen
      - step: 2
        action: User authenticates with Google (enters credentials if not already logged in)
        system_response: Google displays consent screen with requested permissions
      - step: 3
        action: User approves the consent request
        system_response: Google redirects back to application with authorization code
      - step: 4
        action: (automatic) System exchanges code for tokens
        system_response: System creates/updates user account and establishes session
      - step: 5
        action: (automatic) User is redirected to dashboard
        system_response: System displays personalized dashboard with user info
    postconditions:
      - User is authenticated with valid session
      - User account exists with linked Google provider
      - Session cookie is set with 7-day expiry (if "remember me") or session expiry
    exceptions:
      - name: User denies consent
        trigger: User clicks "Deny" on Google consent screen
        outcome: User is redirected to login page with message "Authentication cancelled"
      - name: Google account email already exists
        trigger: Email from Google matches existing non-OAuth account
        outcome: User is prompted to link accounts or use different sign-in method
      - name: Google service unavailable
        trigger: Google OAuth service returns error
        outcome: User sees error message with option to try again or use different method

  - id: AUTH-002
    title: Sign in with GitHub
    actor: New or returning user (typically developers)
    goal: Access the application using GitHub credentials
    trigger: User clicks "Sign in with GitHub" button on login page
    preconditions:
      - User has a valid GitHub account
      - User is on the login page
      - User is not already authenticated
    steps:
      - step: 1
        action: User clicks "Sign in with GitHub" button
        system_response: System redirects to GitHub OAuth authorization screen
      - step: 2
        action: User authenticates with GitHub
        system_response: GitHub displays authorization screen with requested scopes
      - step: 3
        action: User authorizes the application
        system_response: GitHub redirects back with authorization code
      - step: 4
        action: (automatic) System exchanges code for access token
        system_response: System creates/updates user account and establishes session
      - step: 5
        action: (automatic) User is redirected to dashboard
        system_response: System displays personalized dashboard
    postconditions:
      - User is authenticated with valid session
      - User account exists with linked GitHub provider
      - User's GitHub username is stored for display
    exceptions:
      - name: User denies authorization
        trigger: User clicks "Cancel" on GitHub authorization screen
        outcome: User is redirected to login page with cancellation message
      - name: Insufficient GitHub permissions
        trigger: User's GitHub account lacks email visibility
        outcome: User is prompted to update GitHub email settings or use different method

  - id: AUTH-003
    title: Link OAuth provider to existing account
    actor: Existing user with password-based account
    goal: Add Google or GitHub as alternative sign-in method
    trigger: User navigates to Account Settings > Connected Accounts
    preconditions:
      - User is authenticated with existing account
      - User has not already linked this OAuth provider
    steps:
      - step: 1
        action: User clicks "Connect Google" or "Connect GitHub" in settings
        system_response: System redirects to OAuth provider consent screen
      - step: 2
        action: User authenticates and approves connection
        system_response: Provider redirects back with authorization code
      - step: 3
        action: (automatic) System links provider to existing account
        system_response: System displays success message and updated connected accounts list
    postconditions:
      - OAuth provider is linked to user's account
      - User can now sign in with either method
      - Connected accounts list shows new provider
    exceptions:
      - name: OAuth email mismatch
        trigger: OAuth provider email differs from account email
        outcome: System prompts user to confirm linking despite email difference
      - name: Provider already linked to different account
        trigger: OAuth credentials are already associated with another user
        outcome: Error displayed - user must unlink from other account first

  - id: AUTH-004
    title: Sign out
    actor: Authenticated user
    goal: End current session securely
    trigger: User clicks "Sign out" button
    preconditions:
      - User is currently authenticated
    steps:
      - step: 1
        action: User clicks "Sign out" button
        system_response: System invalidates session and clears cookies
      - step: 2
        action: (automatic) User is redirected to login page
        system_response: System displays login page with "Successfully signed out" message
    postconditions:
      - Session is invalidated server-side
      - Session cookie is cleared
      - User must re-authenticate to access protected resources
    exceptions:
      - name: Session already expired
        trigger: Session timed out before sign-out clicked
        outcome: User is redirected to login page (no error shown)

acceptance_criteria:
  - User can click "Sign in with Google" and authenticate via OAuth2 [AUTH-001]
  - User can click "Sign in with GitHub" and authenticate via OAuth2 [AUTH-002]
  - New users are automatically registered on first OAuth sign-in [AUTH-001, AUTH-002]
  - Existing users can link OAuth providers to their account [AUTH-003]
  - User session persists for 7 days with "remember me" option [AUTH-001, AUTH-002]
  - Failed authentication shows clear error message [AUTH-001, AUTH-002 exceptions]
  - User can sign out and session is properly invalidated [AUTH-004]

scope:
  in:
    - Google OAuth2 integration
    - GitHub OAuth2 integration
    - Account linking for existing users
    - Session management
    - Sign out functionality
  out:
    - Other OAuth providers (Apple, Microsoft, etc.)
    - Two-factor authentication
    - Enterprise SSO/SAML
    - Password reset flow

priority: P1

requested_by: Product Team

target_date: 2026-02-15

context:
  related_features:
    - ISSUE-098 (User Profile Management)
  related_journeys:
    - USERMGT-001 (Update profile information)
    - USERMGT-002 (Change password)
  documents:
    - https://docs.google.com/document/d/xxx (PRD)
    - https://figma.com/file/xxx (Design mockups)
  notes: |
    Legal has approved the OAuth scopes we're requesting.
    We only need email and basic profile info.

Common Domain Prefixes

Prefix	Domain	Examples
`AUTH`	Authentication	Sign in, sign out, MFA
`USERMGT`	User Management	Profile, settings, preferences
`ONBOARD`	Onboarding	Registration, verification, welcome flow
`PAY`	Payments	Checkout, purchase, subscription
`REFUND`	Refunds	Request refund, process refund
`ORDER`	Orders	Place order, track order, cancel order
`CART`	Shopping Cart	Add to cart, update quantity, checkout
`SEARCH`	Search	Search products, filter results
`NOTIF`	Notifications	Email alerts, push notifications
`REPORT`	Reporting	Generate report, export data
`ADMIN`	Administration	User admin, system config
`BILLING`	Billing	Invoices, payment methods
`SUPPORT`	Support	Help tickets, chat support
`CONTENT`	Content	Create, edit, publish content
`SOCIAL`	Social	Share, comment, follow
`INTEG`	Integrations	Third-party connections

Tech WRD Schema

Tech requests are internal improvements that don't directly add user-facing features.

File: wrd-tech-{slug}.yaml

Schema

type: tech
title: string                    # Short, descriptive title
description: string              # What needs to be done and why
problem_statement: string        # Current problem or limitation
proposed_solution: string        # High-level approach
acceptance_criteria:             # List of testable conditions
  - string
  - string
scope:
  in:
    - string
  out:
    - string
priority: P0 | P1 | P2 | P3
requested_by: string
target_date: date | null
context:
  affected_services: [string]    # Services/domains impacted
  dependencies: [string]         # External dependencies
  risks: [string]                # Known risks
  notes: string

Example: Database Migration

type: tech

title: Migrate User Service from PostgreSQL to CockroachDB

description: |
  Migrate the user service database from single-node PostgreSQL to 
  CockroachDB cluster for improved scalability and multi-region support.

problem_statement: |
  Current PostgreSQL setup is a single point of failure and doesn't 
  support multi-region deployments. We're seeing increased latency 
  for users in APAC region (avg 340ms vs 45ms in US).

proposed_solution: |
  Deploy a 3-node CockroachDB cluster across us-east-1, eu-west-1, 
  and ap-southeast-1. Migrate schema and data with zero-downtime 
  using dual-write strategy.

acceptance_criteria:
  - CockroachDB cluster deployed in 3 regions
  - All user data migrated with zero data loss
  - Read latency < 100ms from all regions
  - Zero downtime during migration
  - Rollback plan tested and documented

scope:
  in:
    - User service database migration
    - Schema adaptation for CockroachDB
    - Data migration tooling
    - Monitoring and alerting updates
  out:
    - Other services' databases
    - Application code changes (beyond connection string)
    - New features

priority: P1

requested_by: Platform Team

target_date: 2026-03-01

context:
  affected_services:
    - user-service
    - auth-service (reads from user DB)
  dependencies:
    - CockroachDB license procurement (done)
    - VPC peering for multi-region (in progress)
  risks:
    - Data consistency during dual-write phase
    - CockroachDB query performance differences
    - Team unfamiliarity with CockroachDB
  notes: |
    SRE team has completed CockroachDB training.
    Staging environment already running CockroachDB for testing.

Bug WRD Schema

Bug reports describe issues with existing functionality that need to be fixed.

File: wrd-bug-{slug}.yaml

Schema

type: bug
title: string                    # Short, descriptive title
description: string              # What's happening vs what should happen
steps_to_reproduce:              # Numbered steps to reproduce
  - string
  - string
expected_behavior: string        # What should happen
actual_behavior: string          # What actually happens
severity: critical | high | medium | low
affected_users: string           # Scope of impact
affected_journeys: [string]      # Which user journeys are impacted (optional)
environment:                     # Where the bug occurs
  service: string
  version: string
  region: string | null
  browser: string | null         # For frontend bugs
acceptance_criteria:             # How we know it's fixed
  - string
reported_by: string
reported_date: date
context:
  logs: string | null            # Relevant log snippets
  screenshots: [string]          # Links to screenshots
  related_issues: [string]       # Related bugs or features
  notes: string

Example: Payment Processing Bug

type: bug

title: Duplicate Charges on Retry After Timeout

description: |
  When a payment request times out on the client side but succeeds on 
  the server, retrying the payment creates a duplicate charge.

steps_to_reproduce:
  - Add item to cart ($50 value)
  - Proceed to checkout with valid credit card
  - Simulate slow network (Chrome DevTools, slow 3G)
  - Click "Pay Now"
  - Wait for client timeout (30s)
  - See "Payment failed, please retry" message
  - Click "Retry Payment"
  - Check Stripe dashboard - two $50 charges

expected_behavior: |
  Retry should detect the original successful payment and not create 
  a duplicate charge. User should see success message.

actual_behavior: |
  Retry creates a new payment intent and charges the card again. 
  User is charged twice for the same order.

severity: critical

affected_users: |
  Approximately 0.3% of checkout attempts (based on timeout rate).
  23 duplicate charges in the last 7 days totaling $1,847.

affected_journeys:
  - PAY-001  # Checkout with credit card
  - PAY-003  # Retry failed payment

environment:
  service: payment-service
  version: 2.4.1
  region: all
  browser: all

acceptance_criteria:
  - Retry payment checks for existing successful charge before creating new one
  - Idempotency key is used for all payment requests
  - Duplicate charge scenario returns success with original transaction
  - No duplicate charges in 7-day monitoring period after fix

reported_by: Customer Support (escalated from customer complaint)

reported_date: 2026-01-10

context:
  logs: |
    2026-01-10T14:23:45Z payment-service [WARN] Payment timeout for order_id=ORD-9823
    2026-01-10T14:23:47Z payment-service [INFO] Payment succeeded: pi_3Nxxx (delayed response)
    2026-01-10T14:24:12Z payment-service [INFO] New payment created: pi_3Nyyy (retry)
  screenshots:
    - https://s3.xxx/bug-123-stripe-dashboard.png
    - https://s3.xxx/bug-123-customer-email.png
  related_issues:
    - ISSUE-087 (Payment timeout handling improvements)
  notes: |
    Finance team has refunded all affected customers.
    Stripe support confirmed idempotency keys would prevent this.

Phase Execution Steps

  wrd-{type}-{slug}.yaml
          │
          ▼
┌─────────────────────────────────────────────────────────────────┐
│  STEP 1: Input Files                                           │
└─────────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────┐
│  STEP 2: Validate Input (Deterministic)                        │
├─────────────────────────────────────────────────────────────────┤
│  ✗ FAIL → Workflow fails                                       │
└─────────────────────────────────────────────────────────────────┘
          │ ✓
          ▼
┌─────────────────────────────────────────────────────────────────┐
│  STEP 3: Execute Phase (Baron LLM)                             │
├─────────────────────────────────────────────────────────────────┤
│  ✗ FAIL → Workflow fails                                       │
└─────────────────────────────────────────────────────────────────┘
          │ ✓
          ▼
┌─────────────────────────────────────────────────────────────────┐
│  STEP 4: Validate Output (Deterministic)                       │
├─────────────────────────────────────────────────────────────────┤
│  ✗ FAIL → Workflow fails                                       │
└─────────────────────────────────────────────────────────────────┘
          │ ✓
          ▼
┌─────────────────────────────────────────────────────────────────┐
│  STEP 5: Validate Output (Baron LLM)                           │
├─────────────────────────────────────────────────────────────────┤
│  ✗ ESCALATE → Workflow aborts                                  │
│  ⚠ FLAG → Log warning, continue                                │
└─────────────────────────────────────────────────────────────────┘
          │ ✓ PASS
          ▼
    wrd_intake.json

Step 1: Input Files

File	Path
WRD Document	`data/wrds/{wrd_id}/wrd.yaml`
System Prompt	`agents/pm/missions/evaluate-wrd.md`
Feedback Production	`agents/pm/knowledge/feedback-production.md`

Allowed Tools: None (analysis-only phase)

Baron receives WRD content in the user message and produces structured output without file access.

Step 2: Validate Input (Deterministic)

Validate WRD format before calling Baron.

Validator	Checks
`WrdSchemaValidator`	Valid YAML structure
`RequiredFieldsValidator`	`type`, `title`, `description`, `acceptance_criteria`
`ValueInSetValidator`	`type` ∈ {`feature`, `tech`, `bug`}
Type-specific	See WRD Validation Rules

On failure: Workflow FAILS. No LLM call made.

Step 3: Execute Phase (Baron Executor)

Config	Value
Agent	Baron (Executor instance)
System Prompt	`agents/pm/missions/evaluate-wrd.md`
User Message	Raw WRD content
Tools	None

Baron parses WRD, validates completeness, classifies request type, and produces output with source claims.

Expected Output Schema:

{
  "status": "proceed | clarify | reject",
  "classification": "FEATURE | BUG | ENHANCEMENT | TASK",
  "result": {
    "title": "string",
    "summary": "string",
    "problemStatement": "string | null",
    "acceptanceCriteria": ["string"],
    "scope": {
      "included": ["string"],
      "excluded": ["string"]
    },
    "dependencies": ["string"],
    "nfrs": {
      "performance": "string | null",
      "security": "string | null",
      "other": "string | null"
    }
  },
  "validation": {
    "isComplete": true,
    "missingRequired": ["string"],
    "ambiguities": ["string"]
  },
  "claims": [
    {
      "outputPath": "result.title",
      "source": "input",
      "ref": "wrd.yaml#title",
      "quote": "User Authentication with OAuth2"
    },
    {
      "outputPath": "result.acceptanceCriteria[0]",
      "source": "input",
      "ref": "wrd.yaml#acceptance_criteria[0]",
      "quote": "User can click 'Sign in with Google'"
    }
  ],
  "blockers": [
    {"description": "string", "question": "string"}
  ]
}

Note: The executor does NOT produce feedback scores. Feedback is produced by the Evaluator in Step 5.

Status Decision Logic

Status	When Baron Uses It
`proceed`	WRD complete enough for blueprint creation
`clarify`	Critical info missing, questions in `blockers`
`reject`	WRD fundamentally unsuitable

Step 4: Validate Output (Deterministic)

Validator	Checks
`SchemaValidator`	Output matches `WrdIntakeOutput` schema
`RequiredFieldsValidator`	`status`, `classification`, `result.title`, `feedback.scores`
`ValueInSetValidator`	`status` ∈ {`proceed`, `clarify`, `reject`}
`ValueInSetValidator`	`classification` ∈ {`FEATURE`, `BUG`, `ENHANCEMENT`, `TASK`}

On failure: Workflow FAILS.

Step 5: Evaluate Output (Baron Evaluator)

A fresh Baron instance evaluates the executor's output by verifying source claims.

Config	Value
Agent	Baron (Evaluator instance - fresh, no memory of Step 3)
System Prompt	Baron evaluation prompt
User Message	`{phase_type, wrd, output, claims}`
Tools	None

What the evaluator does:

Verify claims: Check that each claim references a real document section
Validate quotes: Confirm quoted text exists in the referenced location
Compute attribution: Calculate sourceAttribution breakdown based on verified claims
Quality gate: Determine if output is sufficient for next phase

Expected output:

{
  "verdict": "pass | flag | escalate",
  "confidence": 0.85,
  "feedback": {
    "scores": {
      "sourceAttribution": {
        "overall": 0.92,
        "breakdown": {
          "fromInput": 0.90,
          "fromCode": 0.00,
          "fromKnowledge": 0.08,
          "fromGuardrails": 0.02,
          "ungrounded": 0.00
        }
      },
      "guardrailsCompliance": { "overall": 0.95 },
      "inputClarity": { "overall": 0.80 },
      "outputConfidence": { "overall": 0.88 }
    },
    "traceability": [ /* verified source traces */ ],
    "gaps": [ /* identified documentation gaps */ ],
    "suggestions": [ /* improvement recommendations */ ]
  },
  "issues": [],
  "escalation_reason": null
}

Verdict	Action
`pass`	Continue to Phase 2
`flag`	Log warning, continue
`escalate`	Abort - human review needed

Why fresh instance? The evaluator can't be influenced by the executor's reasoning. It only sees input + output + claims, and must independently verify.

Output File

File	Path
`wrd_intake.json`	`data/wrds/{wrd_id}/runs/{run_id}/phases/wrd_intake.json`

Next: Phase 02: Blueprint Creation

WRD Validation Rules

These rules are checked by Baron during Step 2 (phase execution):

Required Fields (All Types)

Field	Validation
`type`	Must be `feature`, `tech`, or `bug`
`title`	Non-empty, max 100 characters
`description`	Non-empty, min 50 characters
`acceptance_criteria`	At least 2 criteria
`priority` / `severity`	Valid enum value

Type-Specific Requirements

Type	Additional Required Fields
Feature	`user_journeys` (≥1), `scope.in`, `scope.out`
Tech	`problem_statement`, `proposed_solution`, `scope.in`
Bug	`steps_to_reproduce`, `expected_behavior`, `actual_behavior`, `environment.service`

User Journey Validation

Field	Validation
`id`	Pattern: `^[A-Z]{2,8}-[0-9]{3}$`
`id`	Unique within feature
`title`	Non-empty, max 80 chars
`actor`	Non-empty
`goal`	Non-empty
`steps`	At least 2 steps
`steps[].step`	Sequential from 1
`postconditions`	At least 1

File Locations

WRD documents can be submitted via:

farmerspec.wrd --input=./wrd-feature-google-oauth.yaml
farmerspec.wrd --input=./wrd-tech-db-migration.yaml
farmerspec.wrd --input=./wrd-bug-payment-timeout.yaml

Or interactively:

farmerspec.wrd --type=feature   # Prompts for required fields

Version History

Version	Date	Changes
0.1	2026-01-13	Initial schema definitions
0.2	2026-01-13	Added user journeys to feature schema with {DOMAIN}-{NNN} format
0.3	2026-01-13	Made YAML format mandatory for all intake documents
0.4	2026-01-14	Renamed to WRD (Work Requirements Definition), updated file naming
1.0	2026-01-17	Added two-layer validation, feedback structure for RL
1.1	2026-01-17	5-step model: input files, deterministic validation, LLM execution, output validation
1.2	2026-01-17	Dual-agent model: Executor produces claims, Evaluator verifies and produces feedback