// Introduction

What is Farmwork?

An opinionated framework for organizing AI-assisted development workflows. The farming metaphor makes complex workflows memorable.

Phrase Commands

Natural language triggers for complex workflows. Say "open the farm" to audit systems, "close the farm" to push to production.

Living Audits

Self-updating documentation that tracks project health. Security, performance, accessibility, and code quality audits that stay current.

Agentic Harness

Specialized AI agents for code review, security analysis, and performance optimization. Each agent has a focused role and defined tools.

✓ Issue Tracking
✓ Plan-First Development
✓ Quality Gates
// Workflow Commands

Phrase Commands

The farming metaphor makes workflows memorable and fun. Just speak naturally to Claude.

🌾 "open the farm"

Audit your systems and update FARMHOUSE.md with current metrics. Run this at the start of each session.

Audit Metrics
🐄 "count the herd"

Full code inspection + dry run. Runs code review, cleanup, performance, security, and accessibility checks without pushing.

Review Security Quality
🛒 "go to market"

i18n translation scan + accessibility audit. Ensure your app is ready for a global audience.

i18n Accessibility
🚜 "close the farm"

Push to production. Runs lint, test, build, then commits and pushes with all quality gates passed.

Deploy CI/CD

Plan Phrases

"make a plan for..." Create implementation plan in _PLANS/
"let's implement..." Load plan, create Epic + issues, start work
// Architecture

Project Structure

A clean, opinionated folder structure that keeps your AI-assisted project organized. 

your-project/
├── CLAUDE.md              # AI instructions + phrase commands
├── .claude/               # Claude Code configuration
│   ├── agents/            # 10 specialized subagents
│   │   ├── the-farmer.md
│   │   ├── code-reviewer.md
│   │   ├── security-auditor.md
│   │   ├── performance-auditor.md
│   │   ├── code-smell-auditor.md
│   │   ├── accessibility-auditor.md
│   │   ├── unused-code-cleaner.md
│   │   ├── code-cleaner.md
│   │   ├── i18n-locale-translator.md
│   │   └── storybook-maintainer.md
│   └── commands/          # User-invocable skills
│       └── push.md
├── _AUDIT/                # Living audit documents
│   ├── FARMHOUSE.md        # Framework command center
│   ├── SECURITY.md         # Security posture
│   ├── PERFORMANCE.md      # Performance metrics
│   ├── ACCESSIBILITY.md    # WCAG 2.1 compliance
│   ├── CODE_QUALITY.md     # Code quality tracking
│   └── TESTS.md            # Test coverage
├── _PLANS/                # Implementation plans
├── .beads/                # Issue tracking
└── justfile              # Navigation commands

Living Documents

_AUDIT/ files are living documents. Update them, don't delete them. Only track open items and include audit history.

Issue-First Workflow

Always create beads issues before starting work. This provides full visibility and historical record of changes.

// Dependencies

Required Tools

Claude Code

AI coding assistant

npm i -g @anthropic/claude-code

Beads

Local issue tracking

cargo install beads

Just

Command runner

brew install just

Node.js

Runtime environment

nvm install 22
// AI Agents

10 Specialized Agents

Each agent has a focused role, defined tools, and specific instructions. Automatically created by farmwork init.

the-farmer

haiku

Audit and update FARMHOUSE.md metrics

code-reviewer

sonnet

Quality & security code review

security-auditor

sonnet

OWASP vulnerability scanning

performance-auditor

sonnet

Memory leaks, re-renders, anti-patterns

code-smell-auditor

sonnet

DRY violations, complexity, naming

accessibility-auditor

sonnet

WCAG 2.1 compliance, alt text, contrast

unused-code-cleaner

haiku

Detect and remove dead code

code-cleaner

haiku

Remove comments and console.logs

i18n-locale-translator

sonnet

Translate UI text to locales

storybook-maintainer

sonnet

Create/update Storybook stories

/

Slash Commands

/push Clean, stage, lint, test, build, commit, push, and update metrics (11 steps)
// Farmwork CLI

Command Line Interface

Install globally via npm and use these commands to manage your Farmwork setup.

farmwork init

Interactive setup wizard. Creates all folders, agents, commands, and audit files.

Creates:
  • CLAUDE.md
  • .claude/agents/ (10 agents)
  • .claude/commands/push.md
  • _AUDIT/ (6 audit files)
  • _PLANS/
  • justfile
-f, --force Overwrite existing files
farmwork status

Display Farmwork status and metrics for your project.

Shows:
  • Component counts
  • Issue tracking status
  • FARMHOUSE score
  • Project metrics
farmwork doctor

Diagnose your Farmwork setup and check for issues.

Checks:
  • Core files & agents
  • Audit system
  • Navigation (justfile)
  • Issue tracking (beads)
  • Security (.gitignore)
// Getting Started

Quick Start

Get up and running in under a minute with the Farmwork CLI.

01

Install Farmwork

bash 
npm install -g farmwork
02

Initialize Your Project

Run the interactive setup wizard in your project directory.

bash 
cd your-project
farmwork init
03

Verify Setup

Check that everything is configured correctly.

bash 
farmwork doctor
farmwork status
04

Start Farming

Open Claude Code and speak your first phrase command.

terminal 
$ claude

Claude Code v1.0.0
Ready to assist...

> open the farm

✓ Auditing systems...
✓ Updating FARMHOUSE.md...
✓ Farm is open!
// Recommendations

Best Practices

1

Issue-First Development

Claude automatically creates beads issues and epics before starting work. Check your progress anytime, and context persists across sessions.

2

Plan Before Implement

Say "make a plan for X", review, then "let's implement X". Claude creates beads issues from the plan and works through them as todos.

3

Regular Audits

Run "open the farm" regularly to keep FARMHOUSE.md current and track project health.

4

Living Documents

Claude keeps _AUDIT/ files updated automatically. Check them anytime to track security, performance, and code quality progress.