clawdbot-workspace/goosefactory/README.md

🏭 GooseFactory

AI Agent Factory Command Center — A human-in-the-loop pipeline management system built on top of Goose, designed to orchestrate MCP server production at scale.

GooseFactory gives you a decision queue, approval gates, and a learning system that gets smarter with every review.

---

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    GooseFactory Monorepo                         │
│                                                                 │
│  ┌──────────────┐   ┌───────────────┐   ┌──────────────────┐  │
│  │  @gf/desktop  │   │   @gf/api     │   │  @gf/mcp-server  │  │
│  │  (Goose Fork) │◄──│  (Hono:4000)  │◄──│  (11 tools)      │  │
│  │  Electron+React│  │  REST + WS    │   │  6 resources     │  │
│  │  Decision UI  │   │  PostgreSQL   │   │  4 prompts       │  │
│  └──────┬───────┘   │  Redis Events │   └──────────────────┘  │
│         │            └──────┬────────┘                          │
│         │                   │                                   │
│  ┌──────▼───────┐   ┌──────▼────────┐   ┌──────────────────┐  │
│  │  @gf/modals   │   │ @gf/learning  │   │   @gf/shared     │  │
│  │  25 HITL      │──▶│  Feedback     │   │   Types          │  │
│  │  Modal UIs    │   │  Pipeline     │   │   Constants      │  │
│  │  (HTML/CSS/JS)│   │  Calibration  │   │   Zod Schemas    │  │
│  └──────────────┘   │  Memory Files │   └──────────────────┘  │
│                      └──────────────┘                           │
└─────────────────────────────────────────────────────────────────┘
         │                    │
    ┌────▼────┐         ┌────▼────┐
    │PostgreSQL│         │  Redis  │
    │  :5432   │         │  :6379  │
    └─────────┘         └─────────┘

Pipeline Stages

Every MCP server flows through 8 stages. Stages marked ★ are human gates requiring approval:

📥 Intake → 🏗️ Scaffolding → 🔨 Building → 🧪 Testing → 👁️ Review ★ → 🚀 Staging ★ → 🌍 Production ★ → ✅ Published

Packages

Package	Description	Port
@goosefactory/shared	Shared TypeScript types, constants, Zod schemas	—
@goosefactory/api	Hono REST API + WebSocket server	4000
@goosefactory/mcp-server	MCP server with 11 tools, 6 resources, 4 prompts	stdio
@goosefactory/modals	25 HITL modal UIs (self-contained HTML)	3334
@goosefactory/learning	Feedback processing, calibration, memory files	—
packages/desktop	Forked Goose desktop app (Electron + React + Rust)	—

---

Prerequisites

• Node.js ≥ 20 + npm ≥ 10
• Docker + Docker Compose (for PostgreSQL and Redis)
• Rust (only needed for the desktop app)

Quick Start

1. Clone and bootstrap

cd goosefactory
./scripts/first-boot.sh

This will:

1. ✅ Check prerequisites
2. ✅ Copy .env.example → .env
3. ✅ npm install all workspaces
4. ✅ Build @goosefactory/shared
5. ✅ Start PostgreSQL + Redis via Docker
6. ✅ Initialize database schema
7. ✅ Seed data from MCP command center (if available)

2. Start development

# Start everything (API + MCP + Learning)
npm run dev

# Or start individual services
npm run dev:api        # API server on port 4000
npm run dev:mcp        # MCP server (stdio)
npm run dev:learning   # Learning pipeline
npm run dev:modals     # Modal preview on port 3334

3. Verify

# Health check
curl http://localhost:4000/health

# View API info
curl http://localhost:4000/

---

Development Workflow

Day-to-day

# Start infrastructure
npm run dev:infra

# Start all services
npm run dev

# Type-check across all packages
npm run typecheck

# Build everything
npm run build

Working with the shared package

# After modifying shared types:
npm run build:shared

# Other packages auto-import from @goosefactory/shared:
import type { Pipeline, Task } from "@goosefactory/shared";
import { KANBAN_STAGES, DEFAULT_SLA } from "@goosefactory/shared";
import { FeedbackEventSchema } from "@goosefactory/shared/schemas";

Database

# Start/stop infrastructure
npm run dev:infra
npm run dev:infra:stop

# Re-seed from factory state
npm run db:seed

# Access PostgreSQL directly
docker exec -it goosefactory-postgres psql -U goosefactory -d goosefactory

Testing

# Run all tests
npm test

# Run integration tests
npx tsx tests/integration/modal-to-learning.test.ts

---

Environment Variables

Copy .env.example to .env and configure:

Variable	Default	Description
DATABASE_URL	postgresql://goosefactory:goosefactory_dev@localhost:5432/goosefactory	PostgreSQL connection
REDIS_URL	redis://localhost:6379	Redis connection
FACTORY_API_PORT	4000	API server port
JWT_SECRET	—	JWT signing secret (set in production!)
FACTORY_MCP_TRANSPORT	stdio	MCP transport (stdio or sse)
FACTORY_API_URL	http://localhost:4000/v1	API URL for MCP server
FEEDBACK_STORAGE_PATH	~/.config/goose/factory/feedback	Feedback JSONL storage
MEMORY_FILES_PATH	~/.config/goose/factory/memory	Learning memory files

---

MCP Tools

The MCP server exposes 11 tools for operating the factory:

Tool	Description
factory_get_pending_tasks	Decision inbox — what needs attention
factory_approve_task	Approve a task, advance pipeline
factory_reject_task	Reject with feedback, trigger rework
factory_get_pipeline_status	Pipeline state and progress
factory_advance_stage	Manually advance a pipeline stage
factory_assign_priority	Change priority, recalculate SLA
factory_get_blockers	What's stuck and why
factory_run_tests	Trigger test suite
factory_deploy	Deploy to staging/production
factory_search	Search across all entities
factory_create_pipeline	Create a new MCP server pipeline

---

HITL Modals

25 interactive modals for collecting human feedback:

Category	Modals
Binary Decision	Traffic Light, Decision Tree, Hot Take
Batch Review	Tinder Swipe, Speed Round
Multi-Dimensional	Report Card, Judge's Scorecard
Comparison	Side-by-Side, Before/After, Ranking Arena
Subjective	Thermometer, Quick Pulse, Emoji Scale, Mood Ring
Estimation	Priority Poker, Crystal Ball
High Stakes	Mission Briefing
Verification	Checklist Ceremony
Triage	War Room
Retrospective	Retrospective

Each modal is a self-contained HTML file that communicates via postMessage, and feeds into the learning pipeline.

---

Contracts

All inter-package contracts are defined in CONTRACTS.md. This is the single source of truth. If implementation differs from CONTRACTS.md, the implementation is wrong.

---

Project Structure

goosefactory/
├── CONTRACTS.md              # Canonical interface contracts
├── README.md                 # This file
├── package.json              # Monorepo root (npm workspaces)
├── .env.example              # Environment template
├── packages/
│   ├── shared/               # Types, constants, schemas
│   ├── api/                  # REST API + WebSocket (Hono)
│   ├── mcp-server/           # MCP server (11 tools)
│   ├── modals/               # 25 HITL modal UIs
│   ├── learning/             # Feedback processing pipeline
│   └── desktop/              # Forked Goose (Electron + React)
├── infra/
│   └── docker/               # Docker Compose + init SQL
├── scripts/
│   ├── first-boot.sh         # First-time setup
│   └── seed-from-factory.ts  # Import from MCP command center
└── tests/
    └── integration/          # Cross-package integration tests