// Introduction

What is Farmwork?

A framework grounded in field-tested codebase maintenance rules—using systematic, AI-assisted workflows to keep software high quality and shippable.

Farmwork

Commands

Auto-activating workflows that respond to natural phrases. Say /audit to audit systems, /push to ship to production.

Living Audits

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

Agentic Harness

Four focused AI agents cover code review (quality, security, performance, accessibility), cleanup, farm audits, and idea management. Each has a defined role and tool set.

✓ Issue Tracking
✓ Plan-First Development
✓ Quality Gates
// Explicit Workflows

Seven Commands

Everything Farmwork does is a slash command. Type / to see them all - nothing fires on its own, and each one does exactly one thing.

Farmwork
🌾 /audit

Refresh FARMHOUSE.md metrics and age the Idea Garden - wilting at 45 days, composted at 60. Run it at the start of a session.

Audit Metrics
🐄 /inspect

Everything /audit does, plus the code-reviewer agent across quality, security, performance and accessibility, plus a dry run of lint, test and build. Reports only - changes nothing.

Review Security Quality

The Idea Garden

/add-idea Plant a new idea in GARDEN.md, dated so it can age
/new-ideas Generate 10 ideas from GARDEN + COMPOST context, plant the keepers
/compost Retire an idea to COMPOST.md - with a reason, so it stays retired
/plan-idea Graduate an idea into a real plan in _PLANS/

Shipping

/push Clean, run the quality gates, commit, push, refresh metrics
// Architecture

Project Structure

Two files and three directories. Everything Farmwork adds to a repo lives in one of them - nothing is hidden in config.

Farmwork 
your-project/
├── CLAUDE.md                 # Lean instructions, points at the commands
├── AGENTS.md                 # Same, for Codex / Gemini / anything else
├── .claude/
│   ├── commands/             # The seven workflows
│   │   ├── audit.md          # /audit
│   │   ├── inspect.md        # /inspect
│   │   ├── add-idea.md       # /add-idea
│   │   ├── new-ideas.md      # /new-ideas
│   │   ├── compost.md        # /compost
│   │   ├── plan-idea.md      # /plan-idea
│   │   └── push.md           # /push
│   └── agents/               # Four subagents the commands call
│       ├── the-farmer.md     # Metrics + FARMHOUSE.md
│       ├── code-reviewer.md  # Quality, security, perf, a11y
│       ├── code-cleaner.md   # Comments and console.logs
│       └── idea-gardener.md  # GARDEN + COMPOST
├── _AUDIT/                   # Living documents - updated, never deleted
│   ├── FARMHOUSE.md          # Metrics, score, audit history
│   ├── GARDEN.md             # Ideas, dated so they can age
│   └── COMPOST.md            # Retired ideas, with reasons
└── _PLANS/                   # One file per feature, written before code

Living Documents

_AUDIT/ files are updated, not replaced. They carry audit history, so you can see how the project's health moved rather than only where it landed.

Plan Before Code

/plan-idea writes to _PLANS/ and then stops to ask. Planning and immediately implementing defeats the point of having planned.

Any Agent Harness

Commands are plain markdown. Claude Code reads them natively, Codex runs them from ~/.codex/prompts/, and everything else follows AGENTS.md.

Nothing Implicit

Seven commands, each doing one thing. Type / to see them all - nothing fires on its own, and nothing hides behind a phrase you had to read the docs to learn.

// Subagents

Four Specialized Agents

Commands say what should happen; agents do it. Each has one role, its own tool allowlist, and a command that calls it. Subagents require Claude Code - other tools read the same agent files and do the work inline.

Farmwork

the-farmer

Counts commands, agents, tests and plans, ages the Idea Garden, and rewrites FARMHOUSE.md with a fresh score and a history row.

Called by /audit/inspect/push

code-reviewer

One comprehensive pass - quality, security, performance, code smells and basic accessibility - reported inline by severity. Writes nothing.

Called by /inspect

code-cleaner

Strips comments and console.logs before a push, keeping JSDoc, lint directives, and console.error, warn and info.

Called by /push

idea-gardener

Owns the idea lifecycle across GARDEN.md and COMPOST.md - planting, brainstorming, and retiring ideas with the reason attached.

Called by /add-idea/new-ideas/compost
// Farmwork CLI

Command Line Interface

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

Farmwork
farmwork init

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

Creates:
  • CLAUDE.md + AGENTS.md
  • .claude/commands/ (7 commands)
  • .claude/agents/ (4 agents)
  • _AUDIT/ (3 audit files)
  • _PLANS/
-f, --force Overwrite existing files
farmwork status

Display Farmwork status and metrics for your project.

Shows:
  • Component counts
  • Idea garden status
  • FARMHOUSE score
  • Project metrics
farmwork doctor

Diagnose your Farmwork setup and check for issues.

Checks:
  • Core files & CLAUDE.md
  • Commands & agents
  • Audit system
  • Security (.gitignore)
// The Operator

One Level Above the Farm

Farmwork manages one repo. When you have a dozen, the expensive question stops being "what do I do here?" and becomes "which one has something rotting in it?" The Operator answers that in one command.

/operator 
── Products ────────────────────────────────────
  DoTheseTasks         ████████░░  81%  main       3 uncommitted
  MakeThisVSL          ██████░░░░  62%  feat/hooks 2 unpushed
  OpenPaw              ██████████ 100%  main       clean

── Tools ───────────────────────────────────────
  Farmwork             ███████░░░  74%  main       clean
  FarmFactory                           main       behind 4, no CLAUDE.md

Suggestions
  1. DoTheseTasks has 3 uncommitted files — commit or stash before they rot.
  2. MakeThisVSL: feat/hooks is 2 commits ahead and unpushed.
  3. FarmFactory has no CLAUDE.md — run `npx farmwork init` to set it up.
Groups of farms

Every repo is a farm; farms live in groups with a title, description, and folder path. Simple enough to scan, structured enough to be useful.

Sweeps:
  • Uncommitted & unpushed work
  • Branch and upstream drift
  • Stale registry paths
  • Farms missing CLAUDE.md
Checklists over the API

Reads and writes FarmFactory checklists directly - view progress, complete items, or skip what never applied to that farm.

Safe by design:
  • Idempotent writes, never toggles
  • Asks before changing state
  • Skips leave the denominator honest
  • Works offline for the git sweep
Installed globally

Not a per-project install. One script puts it in both Claude Code and Codex, so /operator works the same in either.

Lands in:
  • ~/.claude/skills/operator/
  • ~/.claude/commands/operator.md
  • ~/.codex/prompts/operator.md
  • ~/.operator/config.json
./install.sh Node 18+, zero dependencies
// 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 type / to see every command.

terminal 
$ claude

Claude Code
Ready to assist...

> /audit

✓ Counting commands, agents, tests, plans
✓ Tending the Idea Garden
✓ FARMHOUSE.md updated — 8.4/10
Farmwork
// Recommendations

Best Practices

1

Capture Ideas as They Come

Say /add-idea to plant it in GARDEN.md. Use /new-ideas whenever you want fresh inspiration.

2

Plan Before Implement

Say "make a plan for X", review it, then "let's implement X" as todos. Plans stay lightweight and reviewable before code gets written.

3

Regular Audits

Run /audit for a quick check or /inspect for a deep inspection to keep FARMHOUSE.md current.

4

Living Documents

Claude keeps _AUDIT/ files updated automatically. Check FARMHOUSE.md anytime to track project health.

// Requirements

What You Need

Node 18+ and an AI coding agent. That's the whole list - Farmwork has no external CLI dependencies, no issue tracker, and no service to sign up for.

An AI agent harness

Claude Code Full support - commands and subagents both run natively
Codex Copy .claude/commands/*.md into ~/.codex/prompts/
Anything else Point it at AGENTS.md and it follows the same command files

And Node

node 18+ Only needed to run npx farmwork init