Complete Guide

Prerequisites

Before installing Farmwork, ensure you have the following tools installed:

Required

Installation

Install Farmwork globally via npm:

npm install -g farmwork

Verify the installation:

farmwork --version

You should see the current version number (e.g., 2.0.0).

Initialization

Navigate to your project directory and run the interactive setup wizard:

cd your-project
farmwork init

What Gets Created

The init command creates the complete Farmwork structure:

your-project/
├── CLAUDE.md                 # Main instructions (lean)
├── AGENTS.md                 # Generic AI guide
├── .claude/
│   ├── commands/             # 7 slash commands
│   │   ├── audit.md
│   │   ├── inspect.md
│   │   ├── add-idea.md
│   │   ├── new-ideas.md
│   │   ├── compost.md
│   │   ├── plan-idea.md
│   │   └── push.md
│   └── agents/               # 4 specialized agents
│       ├── the-farmer.md
│       ├── code-reviewer.md
│       ├── code-cleaner.md
│       └── idea-gardener.md
├── _AUDIT/                   # 3 living audit documents
│   ├── FARMHOUSE.md
│   ├── GARDEN.md
│   └── COMPOST.md
└── _PLANS/                   # Implementation plans

Init Options

Verification

After initialization, verify your setup with the doctor command:

farmwork doctor

The doctor checks:

• Core Files — CLAUDE.md, AGENTS.md present
• Commands — All seven commands installed
• Agents — All 4 agents installed correctly
• Audit System — _AUDIT/ directory and files
• Security — .gitignore includes sensitive paths

Farmwork Doctor

Core Files       ✓ All present
Commands         ✓ 7/7 installed
Agents           ✓ 4/4 installed
Audit System     ✓ Healthy
Security         ✓ .gitignore updated

All systems healthy!

Check Status

For a quick metrics overview, use status:

farmwork status

First Session

With Farmwork installed, start Claude Code and run your first commands:

claude

Step 1: Open the Farm

Start every session by opening the farm:

> /audit

✓ Running farm audit...
✓ Updating FARMHOUSE.md...
✓ Checking idea garden...

Farm Status:
- Ideas: 0 fresh, 0 wilting
- Health: All systems nominal

Step 2: Start Working

Now you're ready to use Farmwork naturally:

# Capture an idea
> I have an idea for dark mode support

# Create a plan
> make a plan for user authentication

# Implement when ready
> let's implement user authentication

# Push when done
> /push

Daily Workflow

A typical Farmwork development session follows this pattern:

Morning Routine

1. Start Claude Code
2. Say /audit to audit systems
3. Review any wilting ideas in the garden
4. Check today's plan in _PLANS/

During Development

1. Work through the plan's steps systematically
2. Capture new ideas as they arise
3. Create plans before implementing features

Before Pushing

1. Use /push to run quality gates
2. Fix any lint, test, or build failures
3. Review the generated commit message
4. Confirm the push

Command Reference

CLI Commands

The Commands

Only /push touches git. /audit and /inspect report and update audit documents, but never commit.

Troubleshooting

A Command Doesn't Appear

If a command is missing from the / picker:

1. Verify the file exists in .claude/commands/
2. Check the file has valid YAML frontmatter with a description
3. Restart Claude Code after making changes

Doctor Reports Missing Files

If doctor reports missing components:

1. Run farmwork init to create missing files
2. Use farmwork init --force to recreate all files

/push Failing

If /push fails at a quality gate:

1. Read the error message carefully
2. Fix the reported issue (lint, test, or build)
3. Run /push again