Complete Guide

Prerequisites

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

Required

Recommended

Installation

Install Farmwork globally via npm:

npm install -g farmwork

Verify the installation:

farmwork --version

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

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/
│   ├── settings.local.json   # Skill activation hook
│   ├── skills/               # 6 auto-activating workflows
│   │   ├── farm-audit/
│   │   ├── farm-inspect/
│   │   ├── garden/
│   │   ├── research/
│   │   ├── production/
│   │   └── market/
│   ├── agents/               # 13 specialized agents
│   │   ├── the-farmer.md
│   │   ├── code-quality.md
│   │   ├── security-auditor.md
│   │   └── ... (10 more)
│   └── commands/             # 2 slash commands
│       ├── push.md
│       └── office.md
├── _AUDIT/                   # 8 living audit documents
│   ├── FARMHOUSE.md
│   ├── GARDEN.md
│   ├── COMPOST.md
│   └── ... (5 more)
├── _OFFICE/                  # Product strategy
│   ├── GREENFIELD.md
│   └── BROWNFIELD.md
├── _PLANS/                   # Implementation plans
├── _RESEARCH/                # Research documents
└── justfile                  # Navigation commands

Init Options

Verification

After initialization, verify your setup with the doctor command:

farmwork doctor

The doctor checks:

• Core Files — CLAUDE.md, AGENTS.md present
• Skills — All 6 skills installed correctly
• Agents — All 13 agents installed correctly
• Commands — /push and /office configured
• Audit System — _AUDIT/ directory and files
• Office System — _OFFICE/ directory and files
• Research System — _RESEARCH/ directory exists
• Navigation — justfile present
• Issue Tracking — Beads configuration (if installed)
• Security — .gitignore includes sensitive paths

Farmwork Doctor

Core Files       ✓ All present
Skills           ✓ 6/6 installed
Agents           ✓ 13/13 installed
Commands         ✓ 2/2 configured
Audit System     ✓ Healthy
Office System    ✓ Configured
Research         ✓ Directory exists
Navigation       ✓ justfile present
Issue Tracking   ✓ Beads configured
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:

> open the farm

✓ Running farm audit...
✓ Updating FARMHOUSE.md...
✓ Checking idea garden...
✓ Reviewing research freshness...

Farm Status:
- Ideas: 0 fresh, 0 wilting
- Research: 0 documents
- Issues: 0 open
- Health: All systems nominal

Step 2: Set Up Strategy (Optional)

If this is a new project, run the office command to set up your product strategy:

> /office

Welcome to the Office Setup Wizard!
Let's define your product vision...

Step 3: Start Working

Now you're ready to use Farmwork naturally:

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

# Research before planning
> let's research authentication patterns

# 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 "open the farm" to audit systems
3. Review any wilting ideas or stale research
4. Check beads issues for today's work

During Development

1. Work on beads issues systematically
2. Capture new ideas as they arise
3. Research unfamiliar topics before planning
4. 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

Natural Language Skills

Slash Commands

Troubleshooting

Skills Not Activating

If skills don't activate when you speak naturally:

1. Check that .claude/settings.local.json exists
2. Verify it contains the UserPromptSubmit hook
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