251 lines
8.9 KiB
Markdown
251 lines
8.9 KiB
Markdown
# 🏭 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
|
|
```
|