# 🏭 GooseFactory

**AI Agent Factory Command Center** — A human-in-the-loop pipeline management system built on top of [Goose](https://github.com/block/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

```bash
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

```bash
# 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

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

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

---

## Development Workflow

### Day-to-day

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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`](./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
```