Product Agents Monorepo

A turborepo containing multiple AI agents for product development tasks. The most complete agent today is the PRD (Product Requirements Document) agent, which includes:

• Backend HTTP API (TypeScript/Node)
• Frontend (Next.js 14)

This README covers end-to-end local setup, environment configuration, required API keys, and run commands.

Technical Requirements

• Node.js >= 18
• npm >= 10
• macOS/Linux/WSL recommended
• Port availability: 3000 (frontend), 3001 (backend)

Included tooling (already managed via workspaces):

• Turbo (turborepo)
• TypeScript
• ESLint
• npm workspaces (pnpm/yarn not required)

Repository Structure

apps/
├─ api/                    # Thin HTTP/SSE server backed by @product-agents/product-agent

frontend/
├─ product-agent/          # Next.js UI and proxy API routes

packages/
├─ product-agent/          # Deep agent orchestrator core
├─ skills/prd/             # PRD skill pack (analyzers, section writers)
├─ shared/*                # Agent core, model compatibility, PRD schemas, UI kit, etc.
└─ (other agent scaffolds)

Deep Agent Architecture (high level flow)

┌────────────────┐      HTTPS/SSE       ┌─────────────────────────┐       Skill packs / shared libs
│  Frontend UI   │ ───────────────────▶ │        apps/api         │ ─────────────────────────────────▶ @product-agents/skills-prd
│ (Next.js 14)   │ ◀─────────────────── │  (thin controller host) │ ◀─────────────────────────────────▶ @product-agents/shared/*
└────────────────┘    streaming events  └─────────────────────────┘
                                │
                                │ invokes
                                ▼
                      ┌───────────────────────────┐
                      │ packages/product-agent    │
                      │ (planner → execute graph) │
                      └───────────────────────────┘

• frontend/product-agent only speaks to the thin API (start/run/stream).
• apps/api loads product-agent.config.ts, registers skill packs, and proxies progress events.
• packages/product-agent composes planners, skill runners, verifiers, workspace DAO, and subagents.
• packages/skills/prd + packages/shared/* provide the analyzers, section writers, and schemas consumed by the controller.

Environment Variables and API Keys

The project integrates with OpenRouter for AI models. You need an OpenRouter API Key.

Where to obtain: Create an account and key at openrouter.ai (do not commit your key).

Recommended local setup files:

• Backend: apps/api/.env
• Frontend: frontend/product-agent/.env.local

Required/optional variables by component:

Backend HTTP API (apps/api/.env)

• OPENROUTER_API_KEY: REQUIRED unless passed per-request in settings
• PRODUCT_AGENT_API_HOST: Optional, default 0.0.0.0
• PRODUCT_AGENT_API_PORT: Optional, default 3001
• PRD_AGENT_CHANGE_WORKER_TEMPERATURE: Optional, tuning edit worker
• Any overrides supported by product-agent.config.ts (model, temperature, skill packs, workspace paths, etc.)

Frontend (frontend/product-agent/.env.local)

• PRD_AGENT_URL: REQUIRED, e.g. http://localhost:3001
• OPENROUTER_API_KEY: Optional (server-side fetch for models)
• YOUR_SITE_URL: Optional, used as HTTP-Referer for OpenRouter models API
• YOUR_SITE_NAME: Optional, used as X-Title for OpenRouter models API
• NEXT_PUBLIC_OPENROUTER_API_KEY: Optional, if you want a client-side default (avoid exposing secrets in prod)

Security notes:

• Do not commit real API keys. .env* files are gitignored.
• Keys can also be supplied per-request in payloads if preferred.

Configuration & Overrides

• Source of truth: packages/product-agent/src/config/product-agent.config.ts
• Defaults: loadProductAgentConfig() loads runtime/workspace/skills/telemetry defaults (model, retries, storage root, enabled skill packs, log level).
• Env overrides (server-wide):

Scope	Environment variable	Description
Runtime	PRODUCT_AGENT_MODEL, PRODUCT_AGENT_TEMPERATURE, PRODUCT_AGENT_MAX_OUTPUT_TOKENS, PRODUCT_AGENT_ALLOW_STREAMING, PRODUCT_AGENT_FALLBACK_MODEL, PRODUCT_AGENT_RETRY_ATTEMPTS, PRODUCT_AGENT_RETRY_BACKOFF_MS	Define default model + sampling + retry behaviour.
Workspace	PRODUCT_AGENT_WORKSPACE_ROOT, PRODUCT_AGENT_WORKSPACE_PERSIST, PRODUCT_AGENT_WORKSPACE_RETENTION_DAYS, PRODUCT_AGENT_WORKSPACE_TEMP_SUBDIR	Control filesystem storage path/retention.
Skills	PRODUCT_AGENT_SKILL_PACKS, PRODUCT_AGENT_ALLOW_DYNAMIC_SKILLS	Choose skill packs and whether per-run overrides are allowed.
Telemetry	PRODUCT_AGENT_TELEMETRY_STREAM, PRODUCT_AGENT_TELEMETRY_METRICS, PRODUCT_AGENT_TELEMETRY_LOG_LEVEL, PRODUCT_AGENT_TELEMETRY_THROTTLE_MS	Toggle streaming + metrics + logging detail.

• API overrides (per run): model, temperature, maxOutputTokens, skillPackId, additionalSkillPacks, workspaceRoot, logLevel — validated against ProductAgentApiOverrideSchema.
• Backend host overrides: PRODUCT_AGENT_API_HOST, PRODUCT_AGENT_API_PORT live in apps/api/.env alongside OPENROUTER_API_KEY.
• See docs/deep-agent-refactor/phase5-changelog.md for a concise summary of the API/env deltas introduced during Phase 5.

Install

From repository root:

npm install

ℹ️ This repo is configured for npm workspaces only. pnpm/yarn workspace commands are unsupported in this environment.

Running Locally (recommended dev flow)

Use two terminals: one for the backend HTTP API and one for the frontend.

1. Start the Backend HTTP API

cd apps/api
# Create and populate .env with your keys/settings (see above)
npm run dev        # watch mode
# or npm run start # runs the built server
# => listens on http://0.0.0.0:3001 by default

2. Start the Frontend (Next.js)

cd frontend/product-agent
# Create .env.local with at least:
# PRD_AGENT_URL=http://localhost:3001
# (Optionally OPENROUTER_API_KEY, YOUR_SITE_URL, YOUR_SITE_NAME)
npm run dev
# => http://localhost:3000

Alternative: run dev scripts via turborepo

• From root: npm run dev starts all available dev scripts (e.g., the frontend). Start apps/api separately so it can stream logs clearly.

Backend HTTP API

Default base URL: http://localhost:3001

Key endpoints (JSON):

• GET /health — agent info, defaults, capabilities
• POST /prd — create a PRD
• POST /prd/edit — edit an existing PRD
• POST /prd/sections — generate specific sections
• POST /prd/section/:name — update one section by name
• Streaming variants: /prd/stream, /prd/edit/stream, /prd/sections/stream, /prd/section/:name/stream (Server-Sent Events)

Notes:

• The backend requires an OpenRouter API key either via OPENROUTER_API_KEY env or in request settings.apiKey.
• Default model: anthropic/claude-3-7-sonnet (capability-filtered in frontend).

Example: Create a PRD (non-streaming)

curl -X POST http://localhost:3001/prd \
  -H 'Content-Type: application/json' \
  -d '{
    "message": "Create a PRD for a mobile habit tracker app",
    "settings": {
      "model": "anthropic/claude-3-7-sonnet",
      "temperature": 0.3,
      "maxTokens": 8000
      // "apiKey": "sk-or-..."  // optional override per request
    }
  }'

Frontend App

Default URL: http://localhost:3000

• UI provides chat, settings panel, and model selection.
• Next.js API routes proxy to the backend at PRD_AGENT_URL.
• /api/models fetches model metadata from OpenRouter (requires API key server-side or x-api-key header).

Ensure PRD_AGENT_URL points to your running backend, and set OPENROUTER_API_KEY (optional) to list models server-side.

Workspace Scripts

Root (turborepo):

• npm run dev — turbo run dev (frontend only by default)
• npm run build — turbo run build for all packages
• npm run test — turbo run test (runs every workspace’s test suite)
• npm run lint — turbo run lint (runs every workspace’s lint task)
• npm run lint:fix — turbo run lint:fix (applies auto-fixes where available)
• npm run clean — clean build outputs

Validating changes locally:

• Run npm run lint from the repo root to execute all lint jobs; use npm run lint:fix to apply safe fixes.
• Run npm run test from the repo root to execute the full workspace test matrix.
• To validate a single package, scope the turbo run: e.g. npx turbo run lint --filter=frontend/product-agent or npx turbo run test --filter=packages/product-agent.

Core workspaces:

• apps/api: npm run dev, npm run build, npm run start
• packages/product-agent: npm run build, npm run test
• frontend/product-agent: npm run dev, npm run build, npm run start, npm run lint

Thin API Server

cd apps/api
npm run build
npm run start
# or npm run dev for watch mode

Troubleshooting

• 404s from frontend API: Confirm PRD_AGENT_URL is set in frontend/product-agent/.env.local.
• Backend errors about missing API key: Set OPENROUTER_API_KEY in apps/api/.env or pass settings.apiKey in requests.
• Port conflicts: Change PRD_AGENT_HTTP_PORT or Next.js port (PORT) as needed.
• Model list empty: Ensure OPENROUTER_API_KEY is set for frontend server-side or provide x-api-key header to /api/models.

Notes

• This repo uses capability filtering to show models compatible with the agent’s requirements (e.g., structured output, streaming).
• Do not expose secrets to the browser. Prefer server-side env vars or per-request headers.