farmwork 1.0.0

package/README.md

@@ -0,0 +1,180 @@
+# Farmwork
+
+> Agentic development harness for AI-assisted projects
+
+Farmwork is a framework that transforms AI coding assistants from reactive tools into proactive development partners. The name is a play on "framework" - because building software should feel like tending a well-organized farm.
+
+## Installation
+
+```bash
+npm install -g farmwork
+```
+
+Or run directly with npx:
+
+```bash
+npx farmwork init
+```
+
+## Quick Start
+
+```bash
+# Initialize in your project
+cd your-project
+farmwork init
+
+# Check your setup
+farmwork doctor
+
+# View framework status
+farmwork status
+```
+
+## Commands
+
+### `farmwork init`
+
+Initialize the Farmwork framework in your current directory. Runs an interactive setup wizard to configure your project for any tech stack.
+
+```bash
+farmwork init                    # Interactive setup wizard
+farmwork init -f                 # Force overwrite existing files
+```
+
+**Options:**
+- `-f, --force` - Overwrite existing files
+
+**Storybook Support:**
+If you enable Storybook (for React/Vue projects), the wizard will also ask for:
+- Storybook URL (e.g., storybook.yoursite.com)
+- Netlify Auth Token (for deployment)
+- Netlify Site ID
+- Password protection preference (recommended)
+
+**Creates:**
+- `CLAUDE.md` - Main instructions and phrase commands
+- `.claude/` - Claude Code configuration directory
+  - `settings.json` - Project settings
+  - `agents/` - Specialized subagents
+  - `commands/` - User-invocable skills
+- `_AUDIT/` - Living audit documents
+  - `FARMHOUSE.md` - Framework command center
+- `_PLANS/` - Implementation plans directory
+- `justfile` - Navigation and task commands
+
+### `farmwork add <type> <name>`
+
+Add a new component to your Farmwork setup.
+
+```bash
+farmwork add agent code-reviewer     # Add a new agent
+farmwork add command deploy          # Add a new command
+farmwork add audit performance       # Add a new audit document
+```
+
+**Types:**
+- `agent` - Creates `.claude/agents/<name>.md`
+- `command` - Creates `.claude/commands/<name>.md`
+- `audit` - Creates `_AUDIT/<NAME>.md`
+
+### `farmwork status`
+
+Display Farmwork status and metrics.
+
+```bash
+farmwork status
+```
+
+**Shows:**
+- Component counts (agents, commands, audits, plans)
+- Issue tracking status (if beads is configured)
+- FARMHOUSE score and open items
+- Configuration file status
+- Project metrics (tests, stories)
+
+### `farmwork doctor`
+
+Check your Farmwork setup and diagnose issues.
+
+```bash
+farmwork doctor
+```
+
+**Checks:**
+- Core files (CLAUDE.md, .claude/, settings)
+- Agents and commands configuration
+- Audit system (_AUDIT/, FARMHOUSE.md, _PLANS/)
+- Navigation (justfile, just command)
+- Issue tracking (beads)
+- Security (.gitignore settings)
+
+## The Farmwork Method
+
+### Core Concepts
+
+1. **FARMHOUSE.md** - Central command for tracking framework metrics
+2. **Phrase Commands** - Natural language triggers for workflows
+3. **Agents** - Specialized AI subagents for specific tasks
+4. **Commands** - User-invocable skills (triggered with `/command`)
+5. **Issue Tracking** - Using beads (`bd`) for full visibility
+6. **Living Audits** - Documents that track ongoing concerns
+
+### Phrase Commands
+
+**Farmwork Phrases** (Development Workflow):
+- `till the land` - Audit systems, update metrics
+- `inspect the farm` - Full inspection (code review, performance, security, quality)
+- `go to market` - i18n translation check
+- `harvest crops` - Full push workflow
+
+**Plan Phrases**:
+- `make a plan for...` - Create implementation plan
+- `let's implement...` - Execute plan with issue tracking
+
+### Recommended Workflow
+
+1. **Start Session**: Run `till the land` to audit current state
+2. **Plan Work**: Use `make a plan for...` for new features
+3. **Implement**: Use `let's implement...` to execute with tracking
+4. **Quality Check**: Run `inspect the farm`
+5. **Ship**: Run `harvest crops` to push changes
+
+## Directory Structure
+
+```
+your-project/
+├── CLAUDE.md           # Main instructions & phrase commands
+├── .claude/            # Claude Code configuration
+│   ├── settings.json   # Project settings
+│   ├── agents/         # Specialized subagents
+│   │   ├── code-reviewer.md
+│   │   ├── security-auditor.md
+│   │   └── ...
+│   └── commands/       # User-invocable skills
+│       ├── push.md
+│       └── ...
+├── _AUDIT/             # Living audit documents
+│   ├── FARMHOUSE.md    # Framework command center
+│   ├── SECURITY.md
+│   ├── PERFORMANCE.md
+│   └── ...
+├── _PLANS/             # Implementation plans
+│   └── FEATURE_NAME.md
+├── .beads/             # Issue tracking (optional)
+└── justfile            # Navigation commands
+```
+
+## Requirements
+
+- Node.js 18+
+- [just](https://github.com/casey/just) (recommended for navigation)
+- [beads](https://github.com/steveyegge/beads) (optional, for issue tracking)
+
+## License
+
+MIT
+
+## Links
+
+- [Farmwork Documentation](https://farmwork.wynter.ai)
+- [GitHub Repository](https://github.com/wynterjones/farmwork)

package/bin/farmwork.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { program } from 'commander';
+import { init } from '../src/init.js';
+import { add } from '../src/add.js';
+import { status } from '../src/status.js';
+import { doctor } from '../src/doctor.js';
+import chalk from 'chalk';
+
+const VERSION = '1.0.0';
+
+console.log(chalk.green(`
+╔═════════════════════════════════════╗
+║      🌾 Farmwork CLI v${VERSION}        ║
+╚═════════════════════════════════════╝
+`));
+
+program
+  .name('farmwork')
+  .description('Farmwork - Agentic development harness for AI-assisted projects')
+  .version(VERSION);
+
+program
+  .command('init')
+  .description('Initialize Farmwork in current directory')
+  .option('-f, --force', 'Overwrite existing files')
+  .action(init);
+
+program
+  .command('add <type> <name>')
+  .description('Add a component (agent, command, audit)')
+  .action(add);
+
+program
+  .command('status')
+  .description('Show Farmwork status and metrics')
+  .action(status);
+
+program
+  .command('doctor')
+  .description('Check Farmwork setup and diagnose issues')
+  .action(doctor);
+
+program.parse();

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "farmwork",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Farmwork - Agentic development harness for AI-assisted projects",
+  "main": "src/index.js",
+  "bin": {
+    "farmwork": "./bin/farmwork.js"
+  },
+  "scripts": {
+    "test": "node --test",
+    "lint": "eslint src/"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "claude",
+    "development",
+    "workflow",
+    "automation",
+    "agentic"
+  ],
+  "author": "Wynter Jones",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "inquirer": "^9.2.12",
+    "ora": "^8.0.1",
+    "fs-extra": "^11.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wynterjones/farmwork"
+  },
+  "homepage": "https://farmwork.wynter.ai"
+}

package/src/add.js

@@ -0,0 +1,194 @@
+import fs from "fs-extra";
+import path from "path";
+import chalk from "chalk";
+import ora from "ora";
+
+const TEMPLATES = {
+  agent: (name, description) => `# ${name} Agent
+
+> ${description}
+
+## Purpose
+
+[Describe what this agent does and when to use it]
+
+## Triggers
+
+This agent is launched via the Task tool with \`subagent_type="${name}"\`.
+
+## Workflow
+
+1. [First step]
+2. [Second step]
+3. [Third step]
+
+## Output
+
+[Describe what the agent returns or produces]
+
+## Examples
+
+\`\`\`
+# Example usage
+Task tool with subagent_type="${name}"
+Prompt: "[Example prompt]"
+\`\`\`
+`,
+
+  command: (
+    name,
+    description,
+  ) => `# ${name.charAt(0).toUpperCase() + name.slice(1)} Command
+
+${description}
+
+## Workflow
+
+Execute these steps in order. **Stop immediately if any step fails.**
+
+### Step 1: [First Step]
+
+\`\`\`bash
+# Command to run
+\`\`\`
+
+### Step 2: [Second Step]
+
+\`\`\`bash
+# Command to run
+\`\`\`
+
+### Step 3: Report Results
+
+Show a summary of what was accomplished.
+`,
+
+  audit: (name) => `# ${name.charAt(0).toUpperCase() + name.slice(1)} Audit
+
+> [One-line description of this audit area]
+
+**Last Updated:** ${new Date().toISOString().split("T")[0]}
+**Score:** 0.0/10
+**Status:** 0 open items
+
+---
+
+## How to get 10/10
+
+[One paragraph explaining what perfect looks like for this area]
+
+---
+
+## Constraints
+
+| Constraint | Reason | Impact |
+|------------|--------|--------|
+| [Constraint 1] | [Why] | [What happens] |
+
+---
+
+## Open Items
+
+_None currently_
+
+---
+
+## [Area-Specific Section]
+
+[Content specific to this audit area]
+
+---
+
+## Audit History
+
+| Date | Changes |
+|------|---------|
+| ${new Date().toISOString().split("T")[0]} | Initial audit document |
+`,
+};
+
+export async function add(type, name, options) {
+  const cwd = process.cwd();
+  const spinner = ora();
+
+  const validTypes = ["agent", "command", "audit"];
+  if (!validTypes.includes(type)) {
+    console.log(chalk.red(`\n❌ Invalid type: ${type}`));
+    console.log(chalk.gray(`   Valid types: ${validTypes.join(", ")}`));
+    return;
+  }
+
+  if (!name) {
+    console.log(chalk.red("\n❌ Name is required"));
+    console.log(chalk.gray(`   Usage: produce add ${type} <name>`));
+    return;
+  }
+
+  const claudeDir = path.join(cwd, ".claude");
+  if (!fs.existsSync(claudeDir)) {
+    console.log(chalk.red("\n❌ Farmwork not initialized"));
+    console.log(chalk.gray("   Run: produce init"));
+    return;
+  }
+
+  spinner.start(`Adding ${type}: ${name}`);
+
+  try {
+    let filePath;
+    let content;
+    let description = options?.description || `[Description for ${name}]`;
+
+    switch (type) {
+      case "agent":
+        filePath = path.join(claudeDir, "agents", `${name}.md`);
+        content = TEMPLATES.agent(name, description);
+        break;
+
+      case "command":
+        filePath = path.join(claudeDir, "commands", `${name}.md`);
+        content = TEMPLATES.command(name, description);
+        break;
+
+      case "audit":
+        const auditDir = path.join(cwd, "_AUDIT");
+        if (!fs.existsSync(auditDir)) {
+          fs.mkdirSync(auditDir, { recursive: true });
+        }
+        filePath = path.join(auditDir, `${name.toUpperCase()}.md`);
+        content = TEMPLATES.audit(name);
+        break;
+    }
+
+    if (fs.existsSync(filePath)) {
+      spinner.fail(`${type} already exists: ${name}`);
+      console.log(chalk.gray(`   File: ${filePath}`));
+      return;
+    }
+
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    fs.writeFileSync(filePath, content);
+    spinner.succeed(`Added ${type}: ${name}`);
+
+    console.log(chalk.gray(`\n   File: ${filePath}`));
+    console.log(chalk.cyan(`\n   Edit the file to customize the ${type}.`));
+
+    if (type === "agent") {
+      console.log(
+        chalk.gray(`\n   Launch with: Task tool, subagent_type="${name}"`),
+      );
+    } else if (type === "command") {
+      console.log(chalk.gray(`\n   Invoke with: /${name}`));
+    } else if (type === "audit") {
+      console.log(
+        chalk.gray(`\n   Update FARMHOUSE.md to reference this audit.`),
+      );
+    }
+  } catch (error) {
+    spinner.fail(`Failed to add ${type}`);
+    console.log(chalk.red(`   ${error.message}`));
+  }
+}

package/src/doctor.js

@@ -0,0 +1,244 @@
+import fs from "fs-extra";
+import path from "path";
+import chalk from "chalk";
+import { execSync } from "child_process";
+
+function checkExists(filePath, description) {
+  const exists = fs.existsSync(filePath);
+  return {
+    passed: exists,
+    message: description,
+    details: exists ? null : `Missing: ${filePath}`,
+  };
+}
+
+function checkCommand(command, description) {
+  try {
+    execSync(`which ${command}`, { encoding: "utf8", stdio: "pipe" });
+    return { passed: true, message: description, details: null };
+  } catch {
+    return {
+      passed: false,
+      message: description,
+      details: `Command not found: ${command}`,
+    };
+  }
+}
+
+function checkDirectoryNotEmpty(dir, description) {
+  if (!fs.existsSync(dir)) {
+    return {
+      passed: false,
+      message: description,
+      details: `Directory missing: ${dir}`,
+    };
+  }
+  const files = fs.readdirSync(dir);
+  const hasContent = files.length > 0;
+  return {
+    passed: hasContent,
+    message: description,
+    details: hasContent ? null : `Directory empty: ${dir}`,
+  };
+}
+
+function checkClaudeMdSections(claudeMdPath) {
+  if (!fs.existsSync(claudeMdPath)) {
+    return {
+      passed: false,
+      message: "CLAUDE.md has required sections",
+      details: "File missing",
+    };
+  }
+
+  const content = fs.readFileSync(claudeMdPath, "utf8");
+  const requiredSections = [
+    "Phrase Commands",
+    "Issue Tracking",
+    "Claude Code Commands",
+  ];
+
+  const missing = requiredSections.filter(
+    (section) => !content.includes(section),
+  );
+
+  return {
+    passed: missing.length === 0,
+    message: "CLAUDE.md has required sections",
+    details:
+      missing.length > 0 ? `Missing sections: ${missing.join(", ")}` : null,
+  };
+}
+
+function checkFarmhouseFormat(farmhousePath) {
+  if (!fs.existsSync(farmhousePath)) {
+    return {
+      passed: false,
+      message: "FARMHOUSE.md follows format",
+      details: "File missing",
+    };
+  }
+
+  const content = fs.readFileSync(farmhousePath, "utf8");
+  const requiredFields = ["**Last Updated:**", "**Score:**", "**Status:**"];
+
+  const missing = requiredFields.filter((field) => !content.includes(field));
+
+  return {
+    passed: missing.length === 0,
+    message: "FARMHOUSE.md follows format",
+    details:
+      missing.length > 0 ? `Missing fields: ${missing.join(", ")}` : null,
+  };
+}
+
+function checkGitignore(cwd) {
+  const gitignorePath = path.join(cwd, ".gitignore");
+  if (!fs.existsSync(gitignorePath)) {
+    return {
+      passed: false,
+      message: ".gitignore includes local settings",
+      details: "File missing",
+    };
+  }
+
+  const content = fs.readFileSync(gitignorePath, "utf8");
+  const hasLocalSettings = content.includes("settings.local.json");
+
+  return {
+    passed: hasLocalSettings,
+    message: ".gitignore includes local settings",
+    details: hasLocalSettings ? null : "Add: .claude/settings.local.json",
+  };
+}
+
+export async function doctor() {
+  const cwd = process.cwd();
+
+  console.log(chalk.cyan("\n🩺 Farmwork Doctor\n"));
+  console.log(chalk.gray("Checking your Farmwork setup...\n"));
+
+  const checks = [];
+
+  checks.push({ category: "Core Files", items: [] });
+  checks[0].items.push(
+    checkExists(path.join(cwd, "CLAUDE.md"), "CLAUDE.md exists"),
+  );
+  checks[0].items.push(
+    checkExists(path.join(cwd, ".claude"), ".claude/ directory exists"),
+  );
+  checks[0].items.push(
+    checkExists(
+      path.join(cwd, ".claude", "settings.json"),
+      "settings.json exists",
+    ),
+  );
+  checks[0].items.push(checkClaudeMdSections(path.join(cwd, "CLAUDE.md")));
+
+  checks.push({ category: "Agents & Commands", items: [] });
+  checks[1].items.push(
+    checkDirectoryNotEmpty(
+      path.join(cwd, ".claude", "agents"),
+      "Has agents defined",
+    ),
+  );
+  checks[1].items.push(
+    checkDirectoryNotEmpty(
+      path.join(cwd, ".claude", "commands"),
+      "Has commands defined",
+    ),
+  );
+
+  checks.push({ category: "Audit System", items: [] });
+  checks[2].items.push(
+    checkExists(path.join(cwd, "_AUDIT"), "_AUDIT/ directory exists"),
+  );
+  checks[2].items.push(
+    checkExists(
+      path.join(cwd, "_AUDIT", "FARMHOUSE.md"),
+      "FARMHOUSE.md exists",
+    ),
+  );
+  checks[2].items.push(
+    checkFarmhouseFormat(path.join(cwd, "_AUDIT", "FARMHOUSE.md")),
+  );
+  checks[2].items.push(
+    checkExists(path.join(cwd, "_PLANS"), "_PLANS/ directory exists"),
+  );
+
+  checks.push({ category: "Navigation", items: [] });
+  checks[3].items.push(
+    checkExists(path.join(cwd, "justfile"), "justfile exists"),
+  );
+  checks[3].items.push(checkCommand("just", "just command available"));
+
+  checks.push({ category: "Issue Tracking", items: [] });
+  checks[4].items.push(
+    checkExists(path.join(cwd, ".beads"), ".beads/ directory exists"),
+  );
+  checks[4].items.push(checkCommand("bd", "bd (beads) command available"));
+
+  checks.push({ category: "Security", items: [] });
+  checks[5].items.push(checkGitignore(cwd));
+
+  let totalPassed = 0;
+  let totalFailed = 0;
+  let totalWarnings = 0;
+
+  for (const category of checks) {
+    console.log(chalk.bold(`${category.category}`));
+
+    for (const check of category.items) {
+      if (check.passed) {
+        console.log(chalk.green(`  🌱 ${check.message}`));
+        totalPassed++;
+      } else {
+        if (check.message.includes("beads") || check.message.includes("bd ")) {
+          console.log(chalk.yellow(`  🍋 ${check.message}`));
+          if (check.details) console.log(chalk.gray(`    ${check.details}`));
+          totalWarnings++;
+        } else {
+          console.log(chalk.red(`  🍂 ${check.message}`));
+          if (check.details) console.log(chalk.gray(`    ${check.details}`));
+          totalFailed++;
+        }
+      }
+    }
+    console.log();
+  }
+
+  console.log(chalk.bold("Summary"));
+  console.log(chalk.green(`  🌱 ${totalPassed} passed`));
+  if (totalWarnings > 0) {
+    console.log(chalk.yellow(`  🍋 ${totalWarnings} warnings (optional)`));
+  }
+  if (totalFailed > 0) {
+    console.log(chalk.red(`  🍂 ${totalFailed} failed`));
+  }
+
+  const health =
+    totalFailed === 0
+      ? totalWarnings === 0
+        ? "Excellent"
+        : "Good"
+      : totalFailed <= 2
+        ? "Needs Attention"
+        : "Critical";
+
+  const healthColor =
+    health === "Excellent"
+      ? chalk.green
+      : health === "Good"
+        ? chalk.cyan
+        : health === "Needs Attention"
+          ? chalk.yellow
+          : chalk.red;
+
+  console.log(`\n${chalk.bold("Health:")} ${healthColor(health)}`);
+
+  if (totalFailed > 0) {
+    console.log(chalk.gray("\nRun `farmwork init` to fix missing components."));
+  }
+
+  console.log();
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { init } from './init.js';
+export { add } from './add.js';
+export { status } from './status.js';
+export { doctor } from './doctor.js';