sweagent 0.0.1 → 0.0.3

package/README.md

@@ -1,10 +1,10 @@
 <p align="center">
   <h1 align="center">sweagent</h1>
   <p align="center">
-    <strong>A multi-provider AI software engineering agent framework with tool calling.</strong>
+    <strong>The Deep Thinking layer that makes Cursor, Claude Code, and Codex 10x more effective.</strong>
   </p>
   <p align="center">
-    Build intelligent agents that execute tools and integrate with OpenAI, Anthropic, and Google. TypeScript-first, type-safe tools, subagent orchestration, and MCP support.
+    Deep, multi-stage reasoning before a single line of code is written. Domain-specialized agent pipelines generate structured blueprints -- requirements, data models, API contracts, auth flows, and architecture specs -- through iterative LLM calls and sub-agent decomposition. Hand the result to your coding agent.
   </p>
 </p>
 
@@ -16,13 +16,20 @@
 </p>
 
 <p align="center">
-  <a href="#what-is-sweagent">What is sweagent?</a> •
+  <a href="#the-problem">The Problem</a> •
+  <a href="#use-with-cursor-claude-code-and-codex">Use with Coding Agents</a> •
   <a href="#why-sweagent">Why sweagent?</a> •
+  <a href="#deep-reasoning-philosophy">Deep Reasoning</a> •
+  <a href="#how-it-works">How It Works</a> •
+  <a href="#features">Features</a> •
+  <a href="#planning-pipeline">Planning Pipeline</a> •
+  <a href="#full-pipeline">Full Pipeline</a> •
+  <a href="#domain-agent-modules">Modules</a> •
+  <a href="#getting-started">Getting Started</a> •
   <a href="#installation">Installation</a> •
-  <a href="#getting-started-tutorial">Tutorial</a> •
   <a href="#architecture">Architecture</a> •
   <a href="#api-reference">API Reference</a> •
-  <a href="#production-modules">Modules</a> •
+  <a href="#reference">Reference</a> •
   <a href="#examples">Examples</a> •
   <a href="#contributing">Contributing</a>
 </p>
@@ -31,165 +38,828 @@
 
 ## Table of Contents
 
-- [What is sweagent?](#what-is-sweagent)
+- [The Problem](#the-problem)
+- [Use with Cursor, Claude Code, and Codex](#use-with-cursor-claude-code-and-codex)
 - [Why sweagent?](#why-sweagent)
+- [Deep Reasoning Philosophy](#deep-reasoning-philosophy)
+- [How It Works](#how-it-works)
 - [Features](#features)
+- [Planning Pipeline](#planning-pipeline)
+- [Full Pipeline](#full-pipeline)
+- [Domain Agent Modules](#domain-agent-modules)
+- [Getting Started](#getting-started)
 - [Installation](#installation)
-- [Getting Started Tutorial](#getting-started-tutorial)
 - [Architecture](#architecture)
-- [Engineering Deep Dive](#engineering-deep-dive)
 - [API Reference](#api-reference)
-- [Production Modules](#production-modules)
+- [Reference](#reference)
 - [Examples](#examples)
-- [Configuration Reference](#configuration-reference)
-- [FAQ](#faq)
-- [Troubleshooting](#troubleshooting)
 - [Contributing](#contributing)
 - [License](#license)
 
 ---
 
-## What is sweagent?
+## The Problem
 
-**sweagent** is a multi-provider AI software engineering agent framework for TypeScript and Node.js. It gives you a single, consistent API to build agents that call tools, delegate to subagents, and run across OpenAI, Anthropic, and Google—with no provider lock-in.
+AI coding agents -- Cursor, Claude Code, Codex -- are powerful executors, but they fail at planning. Hand one a vague requirement and it guesses a tech stack, skips data modeling, forgets auth, and produces half-finished code. Enterprise teams need the same rigor from AI that they expect from senior engineers: structured discovery, explicit requirements, deliberate design, and traceable decisions.
 
-The framework is built around three pillars: **models** (unified provider abstraction), **tools** (Zod-validated, type-safe tool definitions), and **agents** (an iterative loop that invokes the model, executes tool calls, and feeds results back until the task is done). You can add **subagents** so a parent agent delegates subtasks to specialized child agents, and plug in **MCP** (Model Context Protocol) servers for external capabilities. Production-ready modules like **DB Designer** (MongoDB schema from natural language) and **React Builder** (frontend config from GraphQL) show how to orchestrate tools and subagents for real workflows.
+**Without sweagent**, a coding agent receives `"build a task manager"` and immediately starts writing code:
 
-Whether you are prototyping a coding assistant or shipping a multi-step AI pipeline, sweagent keeps the same mental model: create a model, define tools, run an agent. All provider SDKs are included; set your API keys and go.
+- Picks a random framework (maybe Express, maybe Fastify, who knows)
+- Invents a database schema on the fly, misses relationships
+- Forgets authentication entirely
+- Skips error handling and edge cases
+- Produces something that sort-of runs but needs a rewrite
+
+**With sweagent**, the coding agent receives a structured blueprint before writing a single line:
+
+- **11-section markdown plan** with tech stack, data models, API routes, auth flow, implementation order, edge cases, and testing checklist
+- **Structured JSON requirements** with actors, user flows, stories, and module breakdowns
+- **Database schemas** with exact field types, relationships, indexes, and validation rules
+- **API contracts** with endpoints, methods, request/response shapes, and auth requirements
+- **Frontend architecture** with pages, components, routing, and state management
+
+Each pipeline walks through structured stages -- discovery, analysis, design, synthesis -- not a single LLM call. The result is a professional-grade artifact that a coding agent can execute step-by-step, or that a human architect can review and approve.
 
 ```typescript
-import { createModel, runAgent, defineTool } from 'sweagent';
-import { z } from 'zod';
+import { runPlanningAgent } from 'sweagent';
 
-const model = createModel({ provider: 'openai', model: 'gpt-4o-mini' });
-const greetTool = defineTool({
-  name: 'greet',
-  description: 'Greet someone',
-  input: z.object({ name: z.string() }),
-  handler: async ({ name }) => ({ message: `Hello, ${name}!` }),
+const result = await runPlanningAgent({
+  input: 'Task manager app with user auth, task CRUD, assignments, and a dashboard',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
 });
 
-const result = await runAgent({
-  model,
-  tools: [greetTool],
-  systemPrompt: 'You are a helpful assistant.',
-  input: 'Greet Alice',
+console.log('Plan is implementation-ready. Hand it to your coding agent.');
+console.log(result.output); // Full markdown blueprint
+```
+
+TypeScript-first, built on the Vercel AI SDK, ships with all provider SDKs (OpenAI, Anthropic, Google). Set your API keys and go.
+
+---
+
+## Use with Cursor, Claude Code, and Codex
+
+Coding agents are powerful executors -- but they build faster and better when they start from a structured plan instead of a vague prompt. sweagent generates the blueprints; your coding agent implements them.
+
+```mermaid
+flowchart LR
+  Requirement["Your idea"] --> sweagent["sweagent"]
+  sweagent --> Plan["plan.md / JSON spec"]
+  Plan --> Cursor["Cursor"]
+  Plan --> ClaudeCode["Claude Code"]
+  Plan --> Codex["Codex"]
+  Cursor --> Code["Production code"]
+  ClaudeCode --> Code
+  Codex --> Code
+```
+
+### With Cursor
+
+Generate a plan, save it to your project, and reference it in Cursor chat or `.cursor/rules/`:
+
+```typescript
+import { runPlanningAgent } from 'sweagent';
+import { writeFileSync } from 'fs';
+
+const result = await runPlanningAgent({
+  input: 'E-commerce with users, products, cart, checkout, admin dashboard',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
 });
-console.log(result.output);
+
+writeFileSync('plan.md', result.output);
+// Open plan.md in Cursor and say: "Implement this plan step by step"
+// Or copy plan.md to .cursor/rules/ so every agent session uses it as context
+```
+
+### With Claude Code
+
+Generate a plan and save it as `CLAUDE.md` or a reference file. Claude Code automatically reads `CLAUDE.md` for project context:
+
+```typescript
+import { runPlanningAgent } from 'sweagent';
+import { writeFileSync } from 'fs';
+
+const result = await runPlanningAgent({
+  input: 'SaaS dashboard with multi-tenancy, billing, and analytics',
+  model: { provider: 'anthropic', model: 'claude-sonnet-4-20250514' },
+});
+
+// Option 1: Save as CLAUDE.md for automatic context
+writeFileSync('CLAUDE.md', `# Implementation Plan\n\n${result.output}`);
+
+// Option 2: Save as plan.md and reference it
+writeFileSync('plan.md', result.output);
+// Then tell Claude Code: "Read plan.md and implement phase 1"
+```
+
+### With Codex
+
+Codex works best with structured, machine-readable specs. Use the Requirement Gatherer or Data Modeler for JSON output:
+
+```typescript
+import { runRequirementGathererAgent } from 'sweagent';
+import { writeFileSync } from 'fs';
+
+const result = await runRequirementGathererAgent({
+  input: 'Task manager with teams, Kanban boards, and time tracking',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+  maxIterations: 15,
+});
+
+// Structured JSON with actors, flows, stories, modules, DB schema, API design
+writeFileSync('requirements.json', result.output);
+// Feed requirements.json to Codex as context for implementation
 ```
 
+### Why this works
+
+Without sweagent, a coding agent receives "build a task manager" and immediately starts guessing. With sweagent, it receives:
+
+- **11-section markdown plan** with tech stack, data models, API routes, auth flow, implementation order, edge cases, and testing checklist
+- **Structured JSON requirements** with actors, user flows, stories, and module breakdowns
+- **Database schemas** with exact field types, relationships, indexes, and validation rules
+- **API contracts** with endpoints, methods, request/response shapes, and auth requirements
+- **Frontend architecture** with pages, components, routing, and state management
+
+The coding agent stops guessing and starts executing a professional-grade blueprint.
+
 ---
 
 ## Why sweagent?
 
-Long-running AI agents face a core challenge: they work in discrete sessions, and each new session starts with no memory of the last. That leads to agents trying to do too much in one go (and leaving half-finished work), or declaring the job done too early. We designed sweagent so you can build **effective harnesses** for such agents.
+### 1. Domain-specialized agents, not generic wrappers
+
+Each module is a self-contained agent pipeline purpose-built for its domain. The Data Modeler doesn't reuse the Planning Agent's prompts -- it has its own `entity-analyzer` and `schema-refiner` sub-agents, its own tools (`design_schema`, `validate_data_model`), and its own output schema. The React Builder has a `graphql-analyzer` and `config-validator`. Every domain gets the specialized treatment it deserves.
+
+### 2. Multi-stage pipelines with structured outputs
+
+Every domain agent progresses through deliberate stages -- discovery, requirements, design, synthesis -- with dedicated LLM calls at each step. The Planning pipeline makes 8+ sequential LLM calls across 4 stages. The Requirement Gatherer produces structured JSON with actors, user flows, stories, and module breakdowns. No single-shot prompt engineering; each stage builds on the last and produces traceable, reviewable intermediate results.
+
+### 3. Sub-agent orchestration for complex domains
+
+When a domain is too complex for a single agent, sweagent delegates to specialized sub-agents. The Data Modeler orchestrator spawns an `entity-analyzer` to extract entities and relationships, then a `schema-refiner` to normalize and validate the schema. The React Builder uses a `graphql-analyzer` to parse the schema and a `config-validator` to verify the output. Sub-agents run in isolation with their own context, tools, and models -- then return condensed results to the orchestrator.
+
+### 4. Enterprise-quality output, not bullet points
 
-The design follows a two-fold pattern. First, **initializer-style setup**: scaffold the environment with clear artifacts—feature lists, progress files, init scripts—so every run knows what “done” looks like and what’s left to do. Second, **incremental coding agents**: each session is prompted to make bounded progress, then leave the codebase in a clean, documented state (e.g. via commits and progress updates). That way the next session can read git history and progress files, get its bearings quickly, and continue without re-discovering the project.
+Plans include tech stack decisions, data models with field-level detail, API routes with request/response shapes, phased implementation order, edge cases, and testing checklists. Requirement documents include actors with permissions, user flows with steps, user stories with acceptance criteria, and module breakdowns with CRUD operations. DB schemas include field types, relationships, indexes, and validation rules. These are blueprints, not summaries.
 
-sweagent’s architecture reflects this. **Modular tools** let you split capabilities into small, testable units. **Subagent delegation** lets a parent agent hand off analysis or refinement to specialized children. **Structured orchestration prompts** (as in the DB Designer and React Builder modules) spell out when to analyze, when to generate, and when to validate. **Typed schemas** (Zod everywhere) keep tool inputs and outputs predictable and safe. Under the hood, we use a **provider adapter** over the Vercel AI SDK so you can swap OpenAI, Anthropic, or Google without changing your agent code, and a **layered error hierarchy** so failures are easy to trace and handle.
+### 5. Provider-agnostic model layer
+
+Your agent code stays the same whether you're using GPT-4o, Claude, or Gemini. One `createModel()` call, one interface, zero provider lock-in. Switch models in config, not in code.
+
+### 6. Incremental progress across sessions
+
+Long-running agents fail when they lose context. sweagent encodes patterns for structured progress tracking: feature lists with pass/fail status, progress files, and clean-state principles so each session picks up exactly where the last one left off.
 
 ---
 
-## Features
+## Deep Reasoning Philosophy
 
-| Feature | Description |
-|--------|-------------|
-| **Multi-Provider** | Unified API for OpenAI (GPT-4o), Anthropic (Claude), and Google (Gemini). One codebase, switch providers via config. |
-| **Type-Safe Tools** | Define tools with Zod schemas; full type inference and validation before execution. |
-| **Agent Framework** | Iterative agent loop with tool calling, step callbacks, and configurable max iterations. |
-| **Subagent Orchestration** | Parent agents delegate to child agents via tools; optional tool inheritance and isolated models. |
-| **MCP Protocol** | Connect to Model Context Protocol servers over HTTP or stdio. Lazy connection, typed tool invocation. |
-| **Production Modules** | DB Designer (MongoDB schema from requirements), React Builder (frontend config from GraphQL). |
-| **Vision** | Image inputs supported via `model.generateVision()` for vision-capable models. |
-| **Zero Extra Deps** | All provider SDKs included; set API keys and run. |
+Coding agents generate code fast. But speed without depth produces fragile, incomplete software. sweagent applies deep reasoning -- structured, multi-stage, decomposed -- so your coding agent receives a blueprint that has been thoroughly worked through before implementation begins.
+
+### Multi-Stage Reasoning
+
+sweagent never produces one-shot answers. The Planning Agent progresses through four deliberate stages -- discovery, requirements, design, synthesis -- with dedicated LLM calls at each step. Each stage consumes the output of the previous one, building context incrementally rather than cramming everything into a single prompt. Requirements inform design decisions, design decisions shape API contracts, and API contracts feed the implementation order.
+
+```mermaid
+flowchart LR
+  Input["Requirement"] --> Discovery["Discovery"]
+  Discovery --> Requirements["Requirements"]
+  Requirements --> SubReq1["entity-analyzer"]
+  Requirements --> SubReq2["page-planner"]
+  Requirements --> SubReq3["flow-designer"]
+  SubReq1 --> Design["Design"]
+  SubReq2 --> Design
+  SubReq3 --> Design
+  Design --> SubDes1["endpoint-analyzer"]
+  Design --> SubDes2["contract-designer"]
+  SubDes1 --> Synthesis["Synthesis"]
+  SubDes2 --> Synthesis
+  Synthesis --> Output["Blueprint"]
+```
+
+### Sub-Agent Decomposition
+
+When a domain is too complex for a single agent, sweagent delegates to specialized sub-agents that run in isolation with their own context, tools, and models. The Data Modeler spawns an `entity-analyzer` to extract entities, a `relationship-mapper` for cardinality, and a `schema-refiner` to normalize the result. The React Builder uses a `graphql-analyzer` to parse schema structure and a `config-validator` to check the output. Each sub-agent returns condensed results to its orchestrator, keeping context windows focused and reasoning sharp.
+
+### Inference-Time Depth
+
+Unlike single-prompt planning tools, sweagent deliberately spends more inference-time compute for higher-quality output. The Planning Agent alone makes 12+ LLM calls across 4 stages and 7 sub-agents. The Data Modeler adds 3 more sub-agent calls. The full pipeline chains 7+ domain agents end-to-end, each with its own multi-call pipeline. This is not a design accident -- more structured reasoning steps produce measurably better blueprints than a single large prompt, the same way a senior engineer produces better architecture by working through each layer separately rather than designing everything at once.
 
 ---
 
-## Installation
+## How It Works
 
-### Step 1: Prerequisites
+sweagent is not a single agent. It is a system of domain-specialized agent pipelines organized across the full software planning lifecycle. Each module can run independently, or you can chain them into a full-stack specification pipeline.
 
-- **Node.js** >= 18.0.0  
-- **npm** >= 8.0.0 (or yarn, pnpm, bun)
+```mermaid
+flowchart TB
+  subgraph input [Your Idea]
+    Idea["Natural language requirement"]
+  end
 
-### Step 2: Install the package
+  subgraph discovery [Discovery Layer]
+    ReqGatherer["Requirement Gatherer"]
+    Planning["Planning Agent"]
+  end
 
-**Using the package in your project:**
+  subgraph bridge [Bridge]
+    FromReqs["from-requirements"]
+  end
 
-```bash
-npm install sweagent
+  subgraph specialists [Specialist Architects]
+    DataModeler["Data Modeler"]
+    ApiDesigner["API Designer"]
+    AuthDesigner["Auth Designer"]
+    BackendArch["Backend Architect"]
+    FrontendArch["Frontend Architect"]
+  end
+
+  subgraph builders [Framework Builders]
+    ExpressBuilder["Express Builder"]
+    ApolloBuilder["Apollo Builder"]
+    ReactBuilder["React Builder"]
+    NextjsBuilder["Next.js Builder"]
+  end
+
+  subgraph execution [Execution]
+    ExecPlanner["Execution Planner"]
+    CodingAgent["Cursor / Claude Code / Codex"]
+  end
+
+  Idea --> ReqGatherer
+  Idea --> Planning
+  ReqGatherer -->|"FinalRequirement JSON"| FromReqs
+  FromReqs -->|"PlanningContext"| Planning
+  ReqGatherer --> DataModeler
+  DataModeler --> ApiDesigner
+  ApiDesigner --> AuthDesigner
+  AuthDesigner --> BackendArch
+  ApiDesigner --> FrontendArch
+  BackendArch -->|"Express selected"| ExpressBuilder
+  BackendArch -->|"Apollo selected"| ApolloBuilder
+  FrontendArch -->|"React selected"| ReactBuilder
+  FrontendArch -->|"Next.js selected"| NextjsBuilder
+  Planning --> ExecPlanner
+  ExecPlanner --> CodingAgent
+  builders --> CodingAgent
+  specialists --> CodingAgent
 ```
 
-Or with yarn, pnpm, or bun:
+### Three usage modes
 
-```bash
-yarn add sweagent
-pnpm add sweagent
-bun add sweagent
+**1. Quick plan** -- Planning Agent standalone. One call, one markdown plan. Best for getting a coding agent started fast.
+
+**2. Structured requirements** -- Requirement Gatherer produces typed JSON (actors, flows, stories, modules, database, API). Feed the JSON to specialist modules (Data Modeler, API Designer, etc.) for detailed specs per layer. Use `runPlanningFromRequirements` to bridge requirement-gatherer output into the planning pipeline, skipping redundant discovery stages.
+
+**3. Full pipeline** -- Chain all agents together. Each agent's output feeds the next: requirements -> data model -> API design -> auth -> backend architecture -> frontend architecture. Save all specs and hand the directory to your coding agent.
+
+---
+
+## Features
+
+| Feature                     | Description                                                                                                                                                                                                                                                       |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Domain Agent Modules**    | Planning, Requirement Gatherer, Data Modeler, API Designer, Auth Designer, Backend Architect, Express Builder, Apollo Builder, Frontend Architect, React Builder, Next.js Builder, Execution Planner, and Hello World template -- each a self-contained pipeline. |
+| **Multi-Stage Pipelines**   | Every domain agent progresses through structured stages (discovery, requirements, design, synthesis) with dedicated LLM calls at each step. No single-shot prompts.                                                                                               |
+| **Sub-Agent Orchestration** | Complex domains delegate to specialized sub-agents (`entity-analyzer`, `schema-refiner`, `graphql-analyzer`, `config-validator`) that run in isolation and return condensed results.                                                                              |
+| **Structured Outputs**      | Requirements as typed JSON (actors, flows, stories, modules). DB schemas with field-level detail. Frontend configs with pages, hooks, and branding. Plans with 11 sections.                                                                                       |
+| **Multi-Provider Models**   | Unified API for OpenAI, Anthropic, and Google. One `createModel()` call, zero provider lock-in.                                                                                                                                                                   |
+| **Type-Safe Tools**         | Define tools with Zod schemas; full type inference and validation before execution. Minimal, workflow-oriented tool sets.                                                                                                                                         |
+| **Agent Framework**         | Iterative agent loop with tool calling, step callbacks, and configurable max iterations.                                                                                                                                                                          |
+| **MCP Protocol**            | Connect to Model Context Protocol servers over HTTP or stdio. Lazy connection, typed tool invocation.                                                                                                                                                             |
+| **Vision**                  | Image inputs via `model.generateVision()` for vision-capable models.                                                                                                                                                                                              |
+| **Zero Extra Deps**         | All provider SDKs (OpenAI, Anthropic, Google) included. Set API keys and run.                                                                                                                                                                                     |
+
+---
+
+## Planning Pipeline
+
+The planning module is the centerpiece for AI coding agents. It turns a natural-language project description into a structured, implementation-ready markdown plan through four stages.
+
+### How it works
+
+```mermaid
+flowchart LR
+  Input["User Requirement"] --> Discovery["Discovery"]
+  Discovery --> Requirements["Requirements"]
+  Requirements --> Design["Design"]
+  Design --> Synthesis["Synthesis"]
+  Synthesis --> Output["plan.md"]
 ```
 
-All AI provider SDKs (OpenAI, Anthropic, Google) are included; no extra packages are required.
+### Stages
 
-**Contributing from source:**
+| Stage            | What it produces                                   | Sections                                                            |
+| ---------------- | -------------------------------------------------- | ------------------------------------------------------------------- |
+| **Discovery**    | Understands the project, asks clarifying questions | Project overview                                                    |
+| **Requirements** | 4 sequential LLM calls to flesh out the spec       | Tech stack, feature decisions, data models, pages/routes, auth flow |
+| **Design**       | 2 sequential LLM calls for technical design        | API routes, implementation details                                  |
+| **Synthesis**    | Assembles the final plan                           | Implementation order, edge cases, testing checklist                 |
 
-```bash
-git clone https://github.com/sijeeshmiziha/sweagent.git
-cd sweagent
-npm install
+### Output
+
+The plan is a markdown document with these sections:
+
+- **Overview** -- project scope and goals
+- **Tech Stack** -- languages, frameworks, database, auth approach
+- **Feature Decisions** -- what to build and what to defer
+- **Data Models** -- schemas, relationships, fields
+- **Pages and Routes** -- frontend structure
+- **Authentication Flow** -- auth strategy and implementation
+- **API Routes** -- endpoints, methods, request/response shapes
+- **Implementation Details** -- architecture decisions, file structure
+- **Execution Plan** -- phased implementation order
+- **Edge Cases** -- error handling, boundary conditions
+- **Testing Checklist** -- what to verify at each phase
+
+### Two modes
+
+**One-shot mode** -- pass a requirement, get a plan:
+
+```typescript
+import { runPlanningAgent } from 'sweagent';
+
+const result = await runPlanningAgent({
+  input: 'Fitness app with workouts, nutrition tracking, and social features',
+  model: { provider: 'anthropic', model: 'claude-sonnet-4-20250514' },
+});
+console.log(result.output); // Full plan markdown
 ```
 
-### Step 3: Environment setup
+**Interactive chat mode** -- multi-turn conversation where you refine the plan:
 
-Create a `.env` file in your project root (or export variables in your shell):
+```typescript
+import { processPlanningChat } from 'sweagent';
+import type { PlanningContext } from 'sweagent';
 
-```bash
-# At least one provider API key is required
-OPENAI_API_KEY=sk-...
-ANTHROPIC_API_KEY=sk-ant-...
-GOOGLE_GENERATIVE_AI_API_KEY=...
+let context: PlanningContext | null = null;
+
+// Turn 1: describe the project
+const turn1 = await processPlanningChat('Build a task manager with teams', context, {
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+});
+context = turn1.context;
+console.log(turn1.message); // Assistant asks clarifying questions
+console.log(turn1.pendingQuestions); // ["What auth provider?", ...]
+
+// Turn 2: answer and advance
+const turn2 = await processPlanningChat('Use NextAuth with GitHub OAuth', context, {
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+});
+context = turn2.context;
+
+// Continue until turn.planMarkdown is set (plan complete)
 ```
 
-### Step 4: Verify installation
+### Requirements to plan (the bridge)
 
-Run the hello-world example to confirm everything works.
+When you already have structured requirements from the Requirement Gatherer, `runPlanningFromRequirements` converts the `FinalRequirement` JSON into a `PlanningContext` pre-filled at the design stage, skipping the redundant discovery and requirements stages:
 
-**If you installed the package:** create a file `test-agent.mjs` (or `test-agent.ts` with tsx):
+```typescript
+import { runRequirementGathererAgent, runPlanningFromRequirements } from 'sweagent';
 
-```javascript
-import { createModel, runAgent, helloWorldTool } from 'sweagent';
-const model = createModel({ provider: 'openai', model: 'gpt-4o-mini' });
-const result = await runAgent({
+const model = { provider: 'openai', model: 'gpt-4o-mini' } as const;
+
+// Step 1: Gather structured requirements (actors, flows, stories, modules, DB)
+const reqResult = await runRequirementGathererAgent({
+  input: 'Task manager with teams, Kanban boards, and time tracking',
   model,
-  tools: [helloWorldTool],
-  systemPrompt: 'You are helpful.',
-  input: 'Say hello',
+  maxIterations: 15,
 });
-console.log(result.output);
+
+// Step 2: Convert requirements into a planning context and generate the plan
+// Skips discovery + requirements stages; begins at design
+const planResult = await runPlanningFromRequirements({
+  requirement: JSON.parse(reqResult.output),
+  model,
+});
+
+console.log(planResult.output); // Full implementation plan as markdown
 ```
 
-Run it with `node --env-file=.env test-agent.mjs` (or `npx tsx --env-file=.env test-agent.ts`).
+---
+
+## Full Pipeline
 
-**If you cloned the repo:**
+Chain multiple agents together to go from a vague idea to implementation-ready specs for every layer of your stack. Each agent's output feeds the next.
 
-```bash
-npm run example -- examples/hello-world/01-hello-world.ts
+```typescript
+import {
+  runRequirementGathererAgent,
+  runDataModelerAgent,
+  runApiDesignerAgent,
+  runAuthDesignerAgent,
+  runBackendArchitectAgent,
+  runFrontendArchitectAgent,
+  runExecutionPlannerAgent,
+} from 'sweagent';
+import { writeFileSync } from 'fs';
+
+const model = { provider: 'openai', model: 'gpt-4o-mini' } as const;
+
+// Step 1: Gather structured requirements
+const requirements = await runRequirementGathererAgent({
+  input: 'Project management SaaS with teams, Kanban boards, time tracking, and billing',
+  model,
+  maxIterations: 15,
+});
+
+// Step 2: Design the data model from requirements
+const dataModel = await runDataModelerAgent({
+  input: `Design a data model based on these requirements:\n${requirements.output}`,
+  model,
+  maxIterations: 15,
+});
+
+// Step 3: Design the API from the data model
+const apiDesign = await runApiDesignerAgent({
+  input: `Design REST API for this data model:\n${dataModel.output}`,
+  model,
+  maxIterations: 15,
+});
+
+// Step 4: Design auth from the requirements and API
+const authDesign = await runAuthDesignerAgent({
+  input: `Design auth for this project:\nRequirements: ${requirements.output}\nAPI: ${apiDesign.output}`,
+  model,
+  maxIterations: 15,
+});
+
+// Step 5: Plan backend architecture
+const backendDesign = await runBackendArchitectAgent({
+  input: `Design backend:\nData model: ${dataModel.output}\nAPI: ${apiDesign.output}\nAuth: ${authDesign.output}`,
+  model,
+  maxIterations: 15,
+});
+
+// Step 6: Plan frontend architecture
+const frontendDesign = await runFrontendArchitectAgent({
+  input: `Design frontend:\nAPI: ${apiDesign.output}\nRequirements: ${requirements.output}`,
+  model,
+  maxIterations: 15,
+});
+
+// Save all specs for your coding agent
+writeFileSync('specs/requirements.json', requirements.output);
+writeFileSync('specs/data-model.json', dataModel.output);
+writeFileSync('specs/api-design.json', apiDesign.output);
+writeFileSync('specs/auth-design.json', authDesign.output);
+writeFileSync('specs/backend-design.json', backendDesign.output);
+writeFileSync('specs/frontend-design.json', frontendDesign.output);
+
+// Now hand the specs/ directory to Cursor, Claude Code, or Codex
+// "Implement the backend using specs/backend-design.json and specs/data-model.json"
 ```
 
+You can also run individual agents standalone -- each works independently with natural-language input. The pipeline approach gives you maximum control over each design decision.
+
 ---
 
-## Getting Started Tutorial
+## Domain Agent Modules
+
+Each module is a self-contained domain agent with its own orchestrator, pipeline stages, tools, sub-agents, and output format. All are exported from the main package.
+
+| Stage               | Agent                         | Sub-Agents                                                 | Output                                            |
+| ------------------- | ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------- |
+| **Planning**        | `runPlanningAgent`            | --                                                         | Implementation-ready markdown plan (11 sections)  |
+| **Requirements**    | `runRequirementGathererAgent` | --                                                         | Structured JSON (actors, flows, stories, modules) |
+| **Data Modeling**   | `runDataModelerAgent`         | `entity-analyzer`, `relationship-mapper`, `schema-refiner` | MongoDB/PostgreSQL schemas                        |
+| **API Design**      | `runApiDesignerAgent`         | `endpoint-analyzer`, `contract-designer`                   | REST and/or GraphQL API design                    |
+| **Auth Design**     | `runAuthDesignerAgent`        | `security-analyzer`, `flow-designer`                       | Auth strategy, flows, middleware, RBAC            |
+| **Backend Arch.**   | `runBackendArchitectAgent`    | `framework-selector`, `service-planner`                    | Backend architecture (Express/Apollo)             |
+| **Express Builder** | `runExpressBuilderAgent`      | `route-generator`, `middleware-configurator`               | Express.js REST API config                        |
+| **Apollo Builder**  | `runApolloBuilderAgent`       | `schema-generator`, `resolver-planner`                     | Apollo GraphQL subgraph config                    |
+| **Frontend Arch.**  | `runFrontendArchitectAgent`   | `page-planner`, `component-analyzer`, `framework-selector` | Frontend architecture (React/Next.js)             |
+| **React Builder**   | `runReactBuilderAgent`        | `graphql-analyzer`, `config-validator`                     | React + Vite app config from GraphQL              |
+| **Next.js Builder** | `runNextjsBuilderAgent`       | `route-planner`, `api-route-generator`                     | Next.js App Router config                         |
+| **Execution Plan**  | `runExecutionPlannerAgent`    | `edge-case-analyzer`, `testing-strategist`                 | Phased implementation plan                        |
+| **Hello World**     | `runAgent` + `helloWorldTool` | --                                                         | Template module for custom agents                 |
 
-Progress from a simple model call to a full agent with tools and subagents.
+---
 
-### Level 1: Model invocation
+### Planning Agent
+
+Turns a natural-language project description into an implementation-ready markdown plan through 4 stages and 12+ LLM calls. Covers tech stack, data models, API routes, implementation order, edge cases, and testing checklists.
+
+| Attribute         | Detail                                                                  |
+| ----------------- | ----------------------------------------------------------------------- |
+| **Stages**        | Discovery, Requirements (4 LLM calls), Design (2 LLM calls), Synthesis  |
+| **Sub-Agents**    | --                                                                      |
+| **Tools**         | -- (pipeline stages, not tool-based)                                    |
+| **Output Format** | Markdown plan (11 sections)                                             |
+| **Modes**         | One-shot (`runPlanningAgent`), interactive chat (`processPlanningChat`) |
+
+```typescript
+import { runPlanningAgent } from 'sweagent';
+
+const result = await runPlanningAgent({
+  input: 'E-commerce: users, orders, products. Admins manage products.',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+});
+console.log(result.output); // Full markdown blueprint
+```
 
-Create a model and get a completion:
+See [Planning Pipeline](#planning-pipeline) for stage-by-stage details.
+
+---
+
+### Requirement Gatherer Agent
+
+Produces structured JSON requirements -- not prose. Unlike the Planning module (markdown output), the Requirement Gatherer extracts typed data that downstream systems can consume programmatically.
+
+| Attribute         | Detail                                                                                |
+| ----------------- | ------------------------------------------------------------------------------------- |
+| **Stages**        | Discovery, Requirements, Design, Synthesis                                            |
+| **Sub-Agents**    | --                                                                                    |
+| **Tools**         | Stage-specific tools                                                                  |
+| **Output Format** | Structured JSON                                                                       |
+| **Schemas**       | Actors, User Flows, User Stories, Modules, Database Design, API Design                |
+| **Modes**         | One-shot (`runRequirementGathererAgent`), interactive chat (`processRequirementChat`) |
+
+**Output structure:** Actors (with permissions), User Flows (step-by-step sequences), User Stories (with acceptance criteria), Modules (with CRUD operations), Database Design (schemas, relationships), API Design (REST/GraphQL endpoints).
+
+```typescript
+import { runRequirementGathererAgent } from 'sweagent';
+
+const result = await runRequirementGathererAgent({
+  input: 'Project management tool with teams and Kanban boards',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+  maxIterations: 15,
+});
+// result.output: structured JSON with actors, flows, stories, modules
+```
+
+---
+
+### Data Modeler Agent
+
+Designs data models for MongoDB or PostgreSQL with entities, fields, indexes, and relationships. Uses three sub-agents for entity analysis, relationship mapping, and schema refinement.
+
+| Attribute         | Detail                                                                       |
+| ----------------- | ---------------------------------------------------------------------------- |
+| **Pattern**       | Orchestrator with sub-agents                                                 |
+| **Sub-Agents**    | `entity-analyzer`, `relationship-mapper`, `schema-refiner`                   |
+| **Tools**         | `design_schema`, `design_schema_pro`, `refine_schema`, `validate_data_model` |
+| **Output Format** | Data model JSON (entities, fields, indexes, relationships)                   |
+| **Databases**     | MongoDB, PostgreSQL                                                          |
+
+```typescript
+import { runDataModelerAgent } from 'sweagent';
+
+const result = await runDataModelerAgent({
+  input: 'SaaS platform with organizations, users, projects, and billing',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+  maxIterations: 15,
+});
+// result.output: DataModelDesign JSON with entities, fields, indexes, relationships
+```
+
+---
+
+### API Designer Agent
+
+Designs REST and/or GraphQL APIs from data models, producing endpoint definitions with request/response contracts, auth requirements, and operation details.
+
+| Attribute         | Detail                                                                                                  |
+| ----------------- | ------------------------------------------------------------------------------------------------------- |
+| **Pattern**       | Orchestrator with sub-agents                                                                            |
+| **Sub-Agents**    | `endpoint-analyzer` (derives endpoints from data model), `contract-designer` (designs request/response) |
+| **Tools**         | `design_api`, `design_api_pro`, `validate_api`                                                          |
+| **Output Format** | API design JSON (REST endpoints and/or GraphQL operations)                                              |
+
+```typescript
+import { runApiDesignerAgent } from 'sweagent';
+
+const result = await runApiDesignerAgent({
+  input: 'Design REST API for a task manager with users, projects, and tasks',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+  maxIterations: 15,
+});
+// result.output: ApiDesign JSON with REST endpoints and/or GraphQL operations
+```
+
+---
+
+### Auth Designer Agent
+
+Designs authentication and authorization systems with strategies, flows, middleware, roles, and security policies.
+
+| Attribute         | Detail                                                                                     |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| **Pattern**       | Orchestrator with sub-agents                                                               |
+| **Sub-Agents**    | `security-analyzer` (analyzes security requirements), `flow-designer` (designs auth flows) |
+| **Tools**         | `design_auth`, `validate_auth`                                                             |
+| **Output Format** | Auth design JSON (strategy, flows, middleware, roles, policies)                            |
+
+```typescript
+import { runAuthDesignerAgent } from 'sweagent';
+
+const result = await runAuthDesignerAgent({
+  input: 'JWT auth with email/password, Google OAuth, role-based access (admin, member)',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+  maxIterations: 15,
+});
+// result.output: AuthDesign JSON with strategy, flows, middleware, roles, policies
+```
+
+---
+
+### Backend Architect Agent
+
+Plans backend architecture including framework selection, services, middleware, routes, and folder structure. Routes to Express Builder or Apollo Builder based on framework choice.
+
+| Attribute         | Detail                                                                          |
+| ----------------- | ------------------------------------------------------------------------------- |
+| **Pattern**       | Orchestrator with sub-agents                                                    |
+| **Sub-Agents**    | `framework-selector`, `service-planner`                                         |
+| **Tools**         | `design_backend`, `validate_backend`                                            |
+| **Output Format** | Backend design JSON (framework, services, middleware, routes, folder structure) |
+| **Frameworks**    | Express, Apollo, or both                                                        |
+
+```typescript
+import { runBackendArchitectAgent } from 'sweagent';
+
+const result = await runBackendArchitectAgent({
+  input: 'REST API backend with user auth, CRUD operations, and file uploads',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+  maxIterations: 15,
+});
+// result.output: BackendDesign JSON with framework, services, middleware, routes
+```
+
+---
+
+### Express Builder Agent
+
+Generates Express.js REST API configuration with routers, models, middleware, and environment variables.
+
+| Attribute         | Detail                                                      |
+| ----------------- | ----------------------------------------------------------- |
+| **Pattern**       | Orchestrator with sub-agents                                |
+| **Sub-Agents**    | `route-generator`, `middleware-configurator`                |
+| **Tools**         | `generate_express`, `scaffold_express`, `validate_express`  |
+| **Output Format** | Express config JSON (routers, models, middleware, env vars) |
+
+```typescript
+import { runExpressBuilderAgent } from 'sweagent';
+
+const result = await runExpressBuilderAgent({
+  input: 'Express API for e-commerce with products, orders, and user auth',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+  maxIterations: 15,
+});
+// result.output: ExpressConfig JSON with routers, models, middleware, env vars
+```
+
+---
+
+### Apollo Builder Agent
+
+Generates Apollo GraphQL subgraph configuration with modules, types, resolvers, datasources, and Federation v2 support.
+
+| Attribute         | Detail                                                                |
+| ----------------- | --------------------------------------------------------------------- |
+| **Pattern**       | Orchestrator with sub-agents                                          |
+| **Sub-Agents**    | `schema-generator`, `resolver-planner`                                |
+| **Tools**         | `generate_subgraph`, `scaffold_subgraph`, `validate_subgraph`         |
+| **Output Format** | Apollo subgraph config JSON (modules, types, operations, datasources) |
+
+```typescript
+import { runApolloBuilderAgent } from 'sweagent';
+
+const result = await runApolloBuilderAgent({
+  input: 'Apollo subgraph for a task manager with users, projects, and tasks',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+  maxIterations: 15,
+});
+// result.output: SubgraphConfig JSON with modules, types, operations, datasources
+```
+
+---
+
+### Frontend Architect Agent
+
+Plans frontend architecture including pages, components, routing, and state management. Routes to React Builder or Next.js Builder based on framework selection.
+
+| Attribute         | Detail                                                              |
+| ----------------- | ------------------------------------------------------------------- |
+| **Pattern**       | Orchestrator with sub-agents                                        |
+| **Sub-Agents**    | `page-planner`, `component-analyzer`, `framework-selector`          |
+| **Output Format** | Frontend design JSON (pages, components, state management, routing) |
+| **Frameworks**    | React + Vite, Next.js                                               |
+
+```typescript
+import { runFrontendArchitectAgent } from 'sweagent';
+
+const result = await runFrontendArchitectAgent({
+  input: 'Dashboard app with analytics, settings, and user management pages',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+  maxIterations: 15,
+});
+// result.output: FrontendDesign JSON with pages, components, state management, routing
+```
+
+---
+
+### React Builder Agent
+
+Generates complete frontend application configuration from a GraphQL schema. A `graphql-analyzer` sub-agent parses the schema structure, and a `config-validator` sub-agent verifies the output. Produces app config, modules, pages, fields, and API hooks.
+
+| Attribute         | Detail                                                                                                      |
+| ----------------- | ----------------------------------------------------------------------------------------------------------- |
+| **Pattern**       | Orchestrator with sub-agents                                                                                |
+| **Sub-Agents**    | `graphql-analyzer` (parses GraphQL schema structure), `config-validator` (validates frontend config output) |
+| **Tools**         | `generate_frontend`, `generate_feature_breakdown`, `validate_frontend_config`                               |
+| **Output Format** | React app config JSON (app, modules, pages, fields, API hooks, branding)                                    |
+| **Schemas**       | App config, User config, Page config, Field config, Branding                                                |
+
+```typescript
+import { runReactBuilderAgent } from 'sweagent';
+
+const result = await runReactBuilderAgent({
+  input: 'GraphQL schema: type User { id: ID! name: String! } type Task { ... }',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+  maxIterations: 15,
+});
+// result.output: frontend config JSON with pages, fields, hooks, branding
+```
+
+---
+
+### Next.js Builder Agent
+
+Generates Next.js App Router configuration with pages, layouts, API routes, server actions, and middleware.
+
+| Attribute         | Detail                                                                       |
+| ----------------- | ---------------------------------------------------------------------------- |
+| **Pattern**       | Orchestrator with sub-agents                                                 |
+| **Sub-Agents**    | `route-planner`, `api-route-generator`                                       |
+| **Tools**         | `generate_nextjs`, `validate_nextjs`                                         |
+| **Output Format** | Next.js config JSON (pages, layouts, API routes, server actions, middleware) |
+
+```typescript
+import { runNextjsBuilderAgent } from 'sweagent';
+
+const result = await runNextjsBuilderAgent({
+  input: 'Next.js app for project management with teams, tasks, and dashboards',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+  maxIterations: 15,
+});
+// result.output: NextjsConfig JSON with pages, layouts, API routes, server actions
+```
+
+---
+
+### Execution Planner Agent
+
+Creates phased implementation execution plans from plan sections, with edge case analysis and testing checklists.
+
+| Attribute         | Detail                                                                                  |
+| ----------------- | --------------------------------------------------------------------------------------- |
+| **Pattern**       | Orchestrator with sub-agents                                                            |
+| **Sub-Agents**    | `edge-case-analyzer`, `testing-strategist`                                              |
+| **Tools**         | `create_execution_plan`, `validate_execution_plan`                                      |
+| **Output Format** | Execution plan JSON (phases, edge cases, testing checklist, security/performance notes) |
+
+```typescript
+import { runExecutionPlannerAgent } from 'sweagent';
+
+const result = await runExecutionPlannerAgent({
+  input: 'Create execution plan for the task manager project',
+  model: { provider: 'openai', model: 'gpt-4o-mini' },
+  maxIterations: 15,
+});
+// result.output: ExecutionPlan JSON with phases, edge cases, testing checklist
+```
+
+---
+
+### Hello World (Template)
+
+Minimal example module with a single greeting tool. Use as a starting point when building your own domain agent module.
+
+```typescript
+import { createModel, runAgent, helloWorldTool } from 'sweagent';
+
+const result = await runAgent({
+  model: createModel({ provider: 'openai', model: 'gpt-4o-mini' }),
+  tools: [helloWorldTool],
+  systemPrompt: 'You are helpful.',
+  input: 'Say hello',
+});
+```
+
+---
+
+## Getting Started
+
+### Level 1: Model invocation
 
 ```typescript
 import { createModel } from 'sweagent';
 
 const model = createModel({
-  provider: 'openai',
+  provider: 'openai', // 'openai' | 'anthropic' | 'google'
   model: 'gpt-4o-mini',
   temperature: 0.7,
 });
@@ -200,9 +870,7 @@ const response = await model.invoke([
 console.log(response.text);
 ```
 
-### Level 2: Custom tools
-
-Define a type-safe tool with Zod:
+### Level 2: Define tools
 
 ```typescript
 import { defineTool } from 'sweagent';
@@ -223,8 +891,6 @@ const calculatorTool = defineTool({
 
 ### Level 3: Agent loop
 
-Run an agent that can call your tools:
-
 ```typescript
 import { runAgent, createModel, defineTool, createToolSet } from 'sweagent';
 import { z } from 'zod';
@@ -249,10 +915,16 @@ console.log(result.output);
 
 ### Level 4: Subagents
 
-Define subagents and expose them as tools to a parent agent:
-
 ```typescript
-import { defineSubagent, createSubagentToolSet, runAgent, createModel, createToolSet } from 'sweagent';
+import {
+  defineSubagent,
+  createSubagentToolSet,
+  runAgent,
+  createModel,
+  createToolSet,
+} from 'sweagent';
+
+const model = createModel({ provider: 'openai', model: 'gpt-4o-mini' });
 
 const researcher = defineSubagent({
   name: 'researcher',
@@ -260,7 +932,7 @@ const researcher = defineSubagent({
   systemPrompt: 'You are a researcher. Answer concisely.',
 });
 const subagentTools = createSubagentToolSet([researcher], { parentModel: model });
-const tools = createToolSet({ ...otherTools, ...subagentTools });
+const tools = createToolSet({ ...subagentTools });
 
 const result = await runAgent({
   model,
@@ -271,25 +943,23 @@ const result = await runAgent({
 });
 ```
 
-### Level 5: Production module (DB Designer)
+### Level 5: Planning pipeline
 
-Use the DB Designer orchestrator to generate a MongoDB schema from natural language:
+Generate an implementation plan for a coding agent:
 
 ```typescript
-import { runDbDesignerAgent } from 'sweagent';
+import { runPlanningAgent } from 'sweagent';
 
-const result = await runDbDesignerAgent({
-  input: 'E-commerce: users, orders, products. Admins manage products. Users place orders and have a profile.',
+const result = await runPlanningAgent({
+  input: 'E-commerce site: users, products, cart, checkout, admin dashboard',
   model: { provider: 'openai', model: 'gpt-4o-mini' },
-  maxIterations: 15,
 });
-console.log(result.output);
+
+console.log(result.output); // Full markdown blueprint
 ```
 
 ### Level 6: MCP integration
 
-Extend `BaseMcpClient` to call MCP tools (e.g. HTTP or stdio server):
-
 ```typescript
 import { BaseMcpClient } from 'sweagent';
 
@@ -303,6 +973,64 @@ const result = await client.callTool('tool_name', { arg: 'value' });
 
 ---
 
+## Installation
+
+### Prerequisites
+
+- **Node.js** >= 18.0.0
+- **npm** >= 8.0.0 (or yarn, pnpm, bun)
+
+### Install
+
+```bash
+npm install sweagent
+```
+
+Or with yarn, pnpm, or bun:
+
+```bash
+yarn add sweagent
+pnpm add sweagent
+bun add sweagent
+```
+
+All AI provider SDKs (OpenAI, Anthropic, Google) are included; no extra packages needed.
+
+### From source
+
+```bash
+git clone https://github.com/sijeeshmiziha/sweagent.git
+cd sweagent
+npm install
+```
+
+### Environment setup
+
+Create a `.env` file in your project root:
+
+```bash
+# At least one provider API key is required
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_GENERATIVE_AI_API_KEY=...
+```
+
+### Verify
+
+```bash
+# If installed as a package
+echo 'import { createModel, runAgent, helloWorldTool } from "sweagent";
+const model = createModel({ provider: "openai", model: "gpt-4o-mini" });
+const result = await runAgent({ model, tools: [helloWorldTool], systemPrompt: "You are helpful.", input: "Say hello" });
+console.log(result.output);' > test.mjs
+node --env-file=.env test.mjs
+
+# If cloned from source
+npm run example -- examples/hello-world/01-hello-world.ts
+```
+
+---
+
 ## Architecture
 
 ### System overview
@@ -310,37 +1038,86 @@ const result = await client.callTool('tool_name', { arg: 'value' });
 ```mermaid
 graph TB
   subgraph Client[Client Application]
-    App[Your App]
+    App["Your App / Cursor / Claude Code / Codex"]
   end
 
-  subgraph Sweagent[sweagent]
-    Models[Models]
-    Tools[Tools]
-    Agents[Agent Loop]
-    Subagents[Subagents]
-    Modules[DB Designer, React Builder]
+  subgraph DomainAgents[Domain Agent Modules]
+    Planning["Planning"]
+    ReqGatherer["Requirement Gatherer"]
+    DataModeler["Data Modeler"]
+    ApiDesigner["API Designer"]
+    AuthDesigner["Auth Designer"]
+    BackendArch["Backend Architect"]
+    ExpressBuilder["Express Builder"]
+    ApolloBuilder["Apollo Builder"]
+    FrontendArch["Frontend Architect"]
+    ReactBuilder["React Builder"]
+    NextjsBuilder["Next.js Builder"]
+    ExecPlanner["Execution Planner"]
+  end
+
+  subgraph Framework[Shared Framework]
+    Models["Model Abstraction"]
+    ToolFW["Tool Framework"]
+    AgentLoop["Agent Loop"]
+    SubAgentOrch["Sub-Agent Orchestration"]
+    MCP["MCP Protocol"]
   end
 
   subgraph Providers[AI Providers]
-    OpenAI[OpenAI]
-    Anthropic[Anthropic]
-    Google[Google]
+    OpenAI["OpenAI"]
+    Anthropic["Anthropic"]
+    Google["Google"]
   end
 
-  App --> Models
-  App --> Tools
-  App --> Agents
-  App --> Modules
-  Agents --> Models
-  Agents --> Tools
-  Agents --> Subagents
-  Modules --> Agents
-  Models --> OpenAI
-  Models --> Anthropic
-  Models --> Google
+  App --> DomainAgents
+  DomainAgents --> Framework
+  Framework --> Providers
 ```
 
-### Agent execution flow
+### Domain agent pipeline flow
+
+Each domain agent follows a structured pipeline. The Planning Agent is representative:
+
+```mermaid
+flowchart LR
+  Input["User Requirement"] --> Discovery["Discovery Stage"]
+  Discovery --> Requirements["Requirements Stage"]
+  Requirements --> Design["Design Stage"]
+  Design --> Synthesis["Synthesis Stage"]
+  Synthesis --> Plan["Structured Output"]
+  Plan --> Validate["LLM Validator"]
+  Validate --> Output["Validated Result"]
+```
+
+### Orchestrator with sub-agents
+
+Domain agents like Data Modeler and React Builder delegate to specialized sub-agents:
+
+```mermaid
+sequenceDiagram
+  participant User
+  participant Orchestrator
+  participant Model
+  participant Tools
+  participant SubAgent1 as entity-analyzer
+  participant SubAgent2 as schema-refiner
+
+  User->>Orchestrator: Natural-language requirement
+  Orchestrator->>Model: Messages + Domain Tools
+  Model-->>Orchestrator: Tool call design_database
+  Orchestrator->>Tools: Execute design_database
+  Tools-->>Orchestrator: Initial schema
+  Orchestrator->>SubAgent1: Analyze entities and relationships
+  SubAgent1-->>Orchestrator: Structured entity analysis
+  Orchestrator->>SubAgent2: Refine and validate schema
+  SubAgent2-->>Orchestrator: Validated schema
+  Orchestrator->>Model: Compile final output
+  Model-->>Orchestrator: Final result
+  Orchestrator-->>User: Production-grade schema
+```
+
+### Agent execution loop
 
 ```mermaid
 sequenceDiagram
@@ -363,80 +1140,44 @@ sequenceDiagram
   end
 ```
 
-### Subagent delegation
-
-```mermaid
-sequenceDiagram
-  participant User
-  participant ParentAgent
-  participant ParentModel
-  participant SubagentTool
-  participant ChildAgent
-  participant ChildModel
-
-  User->>ParentAgent: Input
-  ParentAgent->>ParentModel: Messages + Tools (incl. subagent_*)
-  ParentModel-->>ParentAgent: Tool call subagent_researcher
-  ParentAgent->>SubagentTool: Execute prompt
-  SubagentTool->>ChildAgent: runAgent(systemPrompt, prompt)
-  ChildAgent->>ChildModel: Messages
-  ChildModel-->>ChildAgent: Response
-  ChildAgent-->>SubagentTool: output
-  SubagentTool-->>ParentAgent: Tool result
-  ParentAgent->>ParentModel: Append tool result, continue
-```
-
-### Module orchestrator (DB Designer)
-
-```mermaid
-flowchart LR
-  Input[User Requirement] --> Analyze[entity-analyzer subagent]
-  Analyze --> Design[design_database tool]
-  Design --> Refine[schema-refiner subagent]
-  Refine --> Validate[validate_schema tool]
-  Validate --> Output[Schema JSON]
-```
-
----
-
-## Engineering Deep Dive
+### Engineering Deep Dive
 
-### Problem decomposition: long-running agents
+#### The problem: long-running coding agents
 
-Agents that work across many steps or sessions tend to fail in two ways: they either try to do too much in one shot (and leave partial, undocumented work), or they assume the project is done too early. To make progress across sessions, each run needs a way to **get up to speed** quickly and to **leave a clean state** for the next run. That implies structured artifacts: feature lists, progress files, and clear prompts that say “do one thing, then commit and document.”
+Coding agents that work across many steps or sessions fail in two ways: they try to do too much in one shot (leaving partial, undocumented work), or they declare the job done too early. Each new session starts with no memory of the last. To make progress across sessions, each run needs a way to get up to speed quickly and leave a clean state for the next run.
 
-### Incremental progress pattern
+#### Incremental progress pattern
 
-We structure agents so that each session does **bounded work**: one feature or one clear subtask. The agent is prompted to update a progress file and to commit (or at least document) what it did. The next session reads progress and git history, chooses the next unfinished item, and continues. That avoids “one-shotting” the whole project and reduces the chance of the agent declaring victory prematurely.
+Each session does bounded work: one feature or one clear subtask. The agent updates a progress file and commits what it did. The next session reads progress and git history, chooses the next unfinished item, and continues. This avoids one-shotting the whole project and reduces premature completion.
 
-### Feature list approach
+#### Feature list approach
 
-A structured list of requirements (e.g. in JSON) with a status per item gives the agent a clear definition of “done.” Agents are instructed to only mark items passing after verification. That keeps scope explicit and makes it easier to resume across context windows.
+A structured list of requirements (e.g. in JSON) with a status per item gives the agent a clear definition of "done." Agents only mark items passing after verification, keeping scope explicit and making it easy to resume across context windows.
 
-### Clean state principle
+#### Clean state principle
 
-Every session should end with code that is buildable, documented, and easy to continue from. In practice that means: no half-implemented features left broken, no stray debug code, and clear commit messages or progress notes. The framework doesn’t enforce this by itself; the orchestration prompts (e.g. in DB Designer and React Builder) encode these expectations.
+Every session should end with code that is buildable, documented, and easy to continue from. No half-implemented features, no stray debug code, clear commit messages or progress notes. The orchestration prompts in production modules encode these expectations.
 
-### Error hierarchy design
+### Provider adapter pattern
 
-Errors are organized so you can handle them by type and preserve cause chains:
+Models are created via `createModel({ provider, model, ... })`. A shared AI SDK adapter wraps the Vercel AI SDK's `generateText` and normalizes messages, tool schemas, and responses. Each provider has a thin factory that passes the correct `LanguageModel` into this adapter. Provider-specific logic stays in one place; everything else is provider-agnostic.
 
-- **LibraryError** – base for all library errors
-- **ModelError** – model invocation failures (provider, API key, etc.)
-- **ToolError** – tool execution or “tool not found”
-- **ValidationError** – schema validation failures
-- **AgentError** – agent hit max iterations without finishing
-- **SubagentError** – subagent configuration or execution failure
+### Tool execution safety
 
-Each can wrap a `cause`. Use try/catch and `instanceof` to branch on the right level.
+Inputs are validated with Zod before any tool runs. Invalid input produces a **ToolError** with the parse error; the handler is never called with bad data. Handler errors are caught and rethrown as **ToolError** with the original error as cause. The agent loop receives structured tool results (including error payloads) so the model can see failures and retry or adjust.
 
-### Provider adapter pattern
+### Error hierarchy
 
-Models are created via `createModel({ provider, model, ... })`. Under the hood, a shared **AI SDK adapter** (`createAIModel`) wraps the Vercel AI SDK’s `generateText` and normalizes messages, tool schemas, and responses. Each provider (OpenAI, Anthropic, Google) has a thin factory that passes the correct `LanguageModel` into this adapter. That keeps provider-specific logic in one place and keeps the rest of the stack provider-agnostic.
+| Class               | When                                             |
+| ------------------- | ------------------------------------------------ |
+| **LibraryError**    | Base; all others extend it.                      |
+| **ModelError**      | Model creation or invoke failed.                 |
+| **ToolError**       | Tool not found or tool execution failed.         |
+| **ValidationError** | Zod validation failed.                           |
+| **AgentError**      | Agent reached max iterations without completing. |
+| **SubagentError**   | Subagent config or run failed.                   |
 
-### Tool execution safety
-
-Before any tool runs, inputs are validated with Zod. Invalid input produces a **ToolError** with the parse error; the handler is never called with bad data. Handler errors are caught and rethrown as **ToolError** with the original error as cause. The agent loop receives structured tool results (including error payloads) so the model can see failures and retry or adjust.
+All accept an optional `cause` for chaining.
 
 ---
 
@@ -446,16 +1187,16 @@ All public APIs are exported from the main package: `import { ... } from 'sweage
 
 ### Models
 
-**createModel(config)** – Create a model instance for the given provider.
+**createModel(config)** -- Create a model instance.
 
 ```typescript
 import { createModel } from 'sweagent';
 
 const model = createModel({
   provider: 'openai' | 'anthropic' | 'google',
-  model: string,            // e.g. 'gpt-4o', 'gpt-4o-mini', 'claude-3-5-sonnet-20241022'
-  apiKey?: string,          // Uses env var by default (OPENAI_API_KEY, etc.)
-  temperature?: number,     // 0–2, default varies by provider
+  model: string,            // e.g. 'gpt-4o', 'claude-sonnet-4-20250514'
+  apiKey?: string,          // Uses env var by default
+  temperature?: number,
   maxOutputTokens?: number,
   baseUrl?: string,
 });
@@ -466,11 +1207,11 @@ const response = await model.invoke(messages, { tools });
 
 **Supported models (examples):**
 
-| Provider  | Models |
-| --------- | ------ |
-| OpenAI    | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` |
-| Anthropic | `claude-3-5-sonnet-20241022`, `claude-3-opus-20240229` |
-| Google    | `gemini-1.5-pro`, `gemini-1.5-flash` |
+| Provider  | Models                                               |
+| --------- | ---------------------------------------------------- |
+| OpenAI    | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo`               |
+| Anthropic | `claude-sonnet-4-20250514`, `claude-3-opus-20240229` |
+| Google    | `gemini-1.5-pro`, `gemini-1.5-flash`                 |
 
 **Vision:** `model.generateVision(prompt, images, options)` for image inputs.
 
@@ -478,7 +1219,7 @@ const response = await model.invoke(messages, { tools });
 
 ### Tools
 
-**defineTool(config)** – Define a type-safe tool with Zod schema and handler.
+**defineTool(config)** -- Define a type-safe tool with Zod schema and handler.
 
 ```typescript
 import { defineTool } from 'sweagent';
@@ -492,21 +1233,21 @@ const tool = defineTool({
 });
 ```
 
-**createToolSet(tools)** – Build a record of tools for the agent (key = tool name).
+**createToolSet(tools)** -- Build a record of tools for the agent (key = tool name).
 
-**getTool(toolSet, name)** / **getTools(toolSet)** – Look up one or all tools.
+**getTool(toolSet, name)** / **getTools(toolSet)** -- Look up one or all tools.
 
-**executeTool(tool, input, options)** – Run a single tool with input.
+**executeTool(tool, input, options)** -- Run a single tool with input.
 
-**executeToolByName(toolSet, name, input, options)** – Run by name; throws if tool missing.
+**executeToolByName(toolSet, name, input, options)** -- Run by name; throws if tool missing.
 
-**zodToJsonSchema(schema)** – Convert a Zod schema to JSON Schema (e.g. for MCP).
+**zodToJsonSchema(schema)** -- Convert a Zod schema to JSON Schema (e.g. for MCP).
 
 ---
 
 ### Agents
 
-**runAgent(config)** – Run the agent loop until the model returns no tool calls or max iterations is reached.
+**runAgent(config)** -- Run the agent loop until the model returns no tool calls or max iterations is reached.
 
 ```typescript
 import { runAgent } from 'sweagent';
@@ -523,15 +1264,11 @@ const result = await runAgent({
 // result: { output, steps, totalUsage, messages }
 ```
 
-**AgentStep** – `{ iteration, content?, toolCalls?, toolResults?, usage? }`.
-
-**AgentResult** – `{ output, steps, totalUsage?, messages }`.
-
 ---
 
 ### Subagents
 
-**defineSubagent(config)** – Define a subagent (name must be kebab-case).
+**defineSubagent(config)** -- Define a subagent (name must be kebab-case).
 
 ```typescript
 import { defineSubagent } from 'sweagent';
@@ -548,165 +1285,181 @@ const def = defineSubagent({
 });
 ```
 
-**runSubagent(definition, input, options)** – Run the subagent in isolation.
-
-**createSubagentTool(definition, options)** – Expose one subagent as a tool (input: `{ prompt }`).
-
-**createSubagentToolSet(definitions, options)** – Build a record of subagent tools (`subagent_<name>`).
+**runSubagent(definition, input, options)** -- Run the subagent in isolation.
 
----
-
-### MCP
-
-**BaseMcpClient** – Base class for MCP clients. Lazy connection, `callTool(name, args)` for invocation.
+**createSubagentTool(definition, options)** -- Expose one subagent as a tool.
 
-**BaseMcpClient.resolveConfig(options, resolveOpts)** – Build config from options and env (e.g. `MCP_URL`, `MCP_COMMAND`, `MCP_ARGS`).
-
-**Transports** – HTTP and stdio transports are used internally; extend `BaseMcpClient` and pass config with `url` or `command` + `args`.
+**createSubagentToolSet(definitions, options)** -- Build a record of subagent tools (`subagent_<name>`).
 
 ---
 
-### Errors
+### Planning
 
-| Class | When |
-| ----- | ---- |
-| **LibraryError** | Base; all others extend it. |
-| **ModelError** | Model creation or invoke failed. |
-| **ToolError** | Tool not found or tool execution failed. |
-| **ValidationError** | Zod validation failed. |
-| **AgentError** | Agent reached max iterations without completing. |
-| **SubagentError** | Subagent config or run failed. |
+**runPlanningAgent(config)** -- One-shot mode: single input, auto-advances through all stages, returns plan markdown.
 
-All accept an optional `cause` for chaining.
+```typescript
+import { runPlanningAgent } from 'sweagent';
 
----
+const result = await runPlanningAgent({
+  input: string,
+  model?: ModelConfig,
+  maxIterations?: number,
+  onStep?: (step: AgentStep) => void,
+  logger?: Logger,
+});
+// result: AgentResult { output, steps, totalUsage, messages }
+```
 
-## Production Modules
+**processPlanningChat(userMessage, context, config)** -- Multi-turn chat mode. Pass `null` context on the first turn.
 
-### DB Designer
+```typescript
+import { processPlanningChat } from 'sweagent';
 
-Generates MongoDB-style project schemas (modules, fields, relationships) from natural language requirements.
+const result = await processPlanningChat(userMessage, context, {
+  model?: ModelConfig,
+  maxIterations?: number,
+  onStep?: (step: AgentStep) => void,
+  logger?: Logger,
+});
+// result: PlanChatTurnResult { message, context, pendingQuestions, planMarkdown }
+```
 
-**Tools:** `design_database`, `design_database_pro`, `redesign_database`, `validate_schema`  
-**Subagents:** `entity-analyzer` (structured analysis), `schema-refiner` (refinement/validation)
+**runPlanningFromRequirements(config)** -- Convert requirement-gatherer output to a plan, skipping redundant stages.
 
 ```typescript
-import { runDbDesignerAgent } from 'sweagent';
+import { runPlanningFromRequirements } from 'sweagent';
 
-const result = await runDbDesignerAgent({
-  input: 'E-commerce: users, orders, products. Admins manage products.',
-  model: { provider: 'openai', model: 'gpt-4o-mini' },
-  maxIterations: 15,
-  onStep: step => console.log(step),
+const result = await runPlanningFromRequirements({
+  requirement: FinalRequirement,  // JSON from requirement-gatherer
+  model?: ModelConfig,
+  onStep?: (step: AgentStep) => void,
+  logger?: Logger,
 });
-console.log(result.output);
+// result: AgentResult { output (plan markdown), steps, totalUsage, messages }
 ```
 
-### React Builder
+**assemblePlan(projectName, sections)** -- Assemble `PlanSections` into a single markdown string.
 
-Generates frontend application config (app, modules, pages, fields, API hooks) from a GraphQL schema.
+**writePlanToFile(markdown, outputPath)** -- Write plan markdown to a file.
 
-**Tools:** `generate_frontend`, `generate_feature_breakdown`, `validate_frontend_config`  
-**Subagents:** `graphql-analyzer`, `config-validator`
+**PlanningContextBuilder** -- Fluent builder for `PlanningContext`:
 
 ```typescript
-import { runReactBuilderAgent } from 'sweagent';
+import { createPlanningContextBuilder } from 'sweagent';
 
-const result = await runReactBuilderAgent({
-  input: 'GraphQL schema: type User { id: ID! name: String } ...',
-  model: { provider: 'openai', model: 'gpt-4o-mini' },
-  maxIterations: 15,
-});
-console.log(result.output);
+const context = createPlanningContextBuilder()
+  .withStage('requirements')
+  .withProjectDescription('Task manager app')
+  .withSections({ overview: '## Overview\n...' })
+  .build();
 ```
 
 ---
 
-## Examples
+### MCP
 
-The [examples directory](./examples/README.md) contains runnable scripts. Use the interactive launcher or run a file directly:
+**BaseMcpClient** -- Base class for MCP clients. Lazy connection, `callTool(name, args)` for invocation.
 
-```bash
-# Interactive launcher (pick folder and example, then provide inputs)
-npm run example:interactive
-
-# Run a specific example (from repo root)
-npm run example -- examples/core/01-basic-model.ts
-npm run example -- examples/hello-world/01-hello-world.ts
-npm run example -- examples/db-designer/01-db-designer-agent.ts
-npm run example -- examples/react-builder/01-react-builder-agent.ts
-```
-
-| Group | Examples | Description |
-| ----- | -------- | ----------- |
-| **Core** | 01 Basic Model, 02 All Providers, 03 Tool Calling, 04 Multi-Tool Agent, 05 Subagents | Models, tools, agents, subagents |
-| **Hello World** | 01 Hello World | Minimal agent with greeting tool |
-| **DB Designer** | 01 DB Designer Agent | MongoDB schema from natural language |
-| **React Builder** | 01 React Builder Agent | Frontend config from GraphQL |
+**BaseMcpClient.resolveConfig(options, resolveOpts)** -- Build config from options and env (e.g. `MCP_URL`, `MCP_COMMAND`, `MCP_ARGS`).
 
 ---
 
-## Configuration Reference
+### Errors
 
-### Environment variables
+| Class               | When                                             |
+| ------------------- | ------------------------------------------------ |
+| **LibraryError**    | Base; all others extend it.                      |
+| **ModelError**      | Model creation or invoke failed.                 |
+| **ToolError**       | Tool not found or tool execution failed.         |
+| **ValidationError** | Zod validation failed.                           |
+| **AgentError**      | Agent reached max iterations without completing. |
+| **SubagentError**   | Subagent config or run failed.                   |
+
+All accept an optional `cause` for chaining.
 
-| Variable | Purpose |
-| -------- | ------- |
-| `OPENAI_API_KEY` | OpenAI API key |
-| `ANTHROPIC_API_KEY` | Anthropic API key |
-| `GOOGLE_GENERATIVE_AI_API_KEY` | Google AI API key |
-| `MCP_URL` / `MCP_COMMAND` / `MCP_ARGS` | MCP client (when using `resolveConfig`) |
+---
 
-For examples: `PROVIDER`, `MODEL`, `AGENT_INPUT`, `REQUIREMENT`, `MAX_ITERATIONS` are used by example scripts.
+## Reference
 
-### ModelConfig
+### Environment variables
 
-`provider`, `model`, `apiKey?`, `temperature?`, `maxOutputTokens?`, `baseUrl?`
+| Variable                               | Purpose                                                        |
+| -------------------------------------- | -------------------------------------------------------------- |
+| `OPENAI_API_KEY`                       | OpenAI API key                                                 |
+| `ANTHROPIC_API_KEY`                    | Anthropic API key                                              |
+| `GOOGLE_GENERATIVE_AI_API_KEY`         | Google AI API key                                              |
+| `MCP_URL` / `MCP_COMMAND` / `MCP_ARGS` | MCP client (when using `resolveConfig`)                        |
+| `PROVIDER`                             | Default provider for examples                                  |
+| `MODEL`                                | Default model for examples                                     |
+| `REQUIREMENT`                          | Project requirement for planning/requirement-gatherer examples |
+| `MAX_ITERATIONS`                       | Max agent iterations for examples                              |
 
-### AgentConfig
+### Config types
 
-`model`, `tools`, `systemPrompt`, `input`, `maxIterations?`, `onStep?`
+- **ModelConfig** -- `provider`, `model`, `apiKey?`, `temperature?`, `maxOutputTokens?`, `baseUrl?`
+- **AgentConfig** -- `model`, `tools`, `systemPrompt`, `input`, `maxIterations?`, `onStep?`
+- **PlanningAgentConfig** -- `input`, `model?`, `maxIterations?`, `onStep?`, `logger?`
+- **PlanFromRequirementsConfig** -- `requirement`, `model?`, `onStep?`, `logger?`
 
----
+### FAQ
 
-## FAQ
+**Which AI provider should I use?**
+All work well. Choose by existing infrastructure and pricing. The API is the same regardless of provider.
 
-**Which AI provider should I use?**  
-All work well. Choose by existing infra and pricing. The API is the same.
+**Can I use this with Claude Code / Codex / Cursor?**
+Yes -- this is the primary use case. See [Use with Cursor, Claude Code, and Codex](#use-with-cursor-claude-code-and-codex) for detailed integration guides with code examples. In short: generate a plan or structured spec with sweagent, save it to a file, and reference it in your coding agent. For Cursor, save to `.cursor/rules/` or paste into chat. For Claude Code, save as `CLAUDE.md` or reference with `@plan.md`. For Codex, feed the structured JSON as context.
 
-**How do I handle rate limits?**  
+**How do I handle rate limits?**
 sweagent has no built-in rate limiting. Use a retry library (e.g. `p-retry`) around `model.invoke` or `runAgent` if needed.
 
-**Can I use sweagent in the browser?**  
+**Can I use sweagent in the browser?**
 Target is Node.js. For browsers, proxy API calls through your backend and keep keys server-side.
 
-**How do I add a new provider?**  
-Implement a factory that returns a model conforming to the internal `Model` interface (e.g. via `createAIModel` and the provider’s AI SDK binding) and register it in `createModel`.
+**How do I add a new provider?**
+Implement a factory that returns a model conforming to the internal `Model` interface (e.g. via `createAIModel` and the provider's AI SDK binding) and register it in `createModel`.
 
----
+### Troubleshooting
 
-## Troubleshooting
+**API key errors** -- Ensure the key is set: `echo $OPENAI_API_KEY` (or the relevant env var). If using `.env`, load it: `tsx --env-file=.env your-script.ts` or `node --env-file=.env your-script.js`.
 
-### API key errors
+**Model not found** -- Use the exact model id for the provider (e.g. `gpt-4o-mini`, `claude-sonnet-4-20250514`). Confirm your account has access to that model.
 
-**Invalid API key / Authentication failed**
+**Agent hits max iterations** -- Increase `maxIterations` or simplify the task. Check that tools return clear, parseable results so the model can decide the next step.
 
-- Ensure the key is set: `echo $OPENAI_API_KEY` (or the relevant env var).
-- If using `.env`, load it: `tsx --env-file=.env your-script.ts` or `node --env-file=.env your-script.js`.
+**Tool not found** -- Tools must be in the same object passed to `runAgent` under the name the model uses (e.g. `createToolSet({ calculator: calculatorTool })` means the model calls `calculator`).
 
-### Model not found
+---
 
-- Use the exact model id for the provider (e.g. `gpt-4o-mini`, `claude-3-5-sonnet-20241022`).
-- Confirm your account has access to that model.
+## Examples
 
-### Agent hits max iterations
+The [examples directory](./examples/) contains runnable scripts organized by domain agent. Use the interactive launcher or run a file directly:
 
-- Increase `maxIterations` or simplify the task.
-- Check that tools return clear, parseable results so the model can decide the next step.
+```bash
+# Interactive launcher -- pick a domain agent, then an example
+npm run example:interactive
 
-### Tool not found
+# Run a specific domain agent example
+npm run example -- examples/planning/01-planning-agent.ts
+npm run example -- examples/data-modeler/01-data-modeler-agent.ts
+npm run example -- examples/react-builder/01-react-builder-agent.ts
+```
 
-- Tools must be in the same object passed to `runAgent` under the name the model uses (e.g. `createToolSet({ calculator: calculatorTool })` → model calls `calculator`).
+| Domain Agent             | Examples                                              | What it produces                                                         |
+| ------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------ |
+| **Planning**             | 01 Planning Agent                                     | Implementation-ready markdown plan through 4-stage pipeline              |
+| **Requirement Gatherer** | 01 Requirement Gatherer Agent                         | Structured JSON requirements (actors, flows, stories, modules)           |
+| **Data Modeler**         | 01 Data Modeler Agent                                 | MongoDB/PostgreSQL data model with entities, fields, indexes             |
+| **API Designer**         | 01 API Designer Agent                                 | REST/GraphQL API design with endpoints and contracts                     |
+| **Auth Designer**        | 01 Auth Designer Agent                                | Auth strategy, flows, middleware, roles, and policies                    |
+| **Backend Architect**    | 01 Backend Architect Agent                            | Backend architecture with framework selection and services               |
+| **Express Builder**      | 01 Express Builder Agent                              | Express.js config with routers, models, and middleware                   |
+| **Apollo Builder**       | 01 Apollo Builder Agent                               | Apollo GraphQL subgraph config with types and resolvers                  |
+| **Frontend Architect**   | 01 Frontend Architect Agent                           | Frontend architecture with pages, components, and routing                |
+| **React Builder**        | 01 React Builder Agent                                | Frontend config via `graphql-analyzer` and `config-validator` sub-agents |
+| **Next.js Builder**      | 01 Next.js Builder Agent                              | Next.js App Router config with pages, layouts, and API routes            |
+| **Execution Planner**    | 01 Execution Planner Agent                            | Phased implementation plan with edge cases and testing checklist         |
+| **Core Framework**       | 01-05: Model, Providers, Tools, Multi-Tool, Subagents | Models, tools, agent loop, sub-agent delegation                          |
+| **Hello World**          | 01 Hello World                                        | Minimal agent with greeting tool (module template)                       |
 
 ---
 
@@ -727,29 +1480,23 @@ npm run lint
 npm run build
 ```
 
-| Command | Description |
-| ------- | ----------- |
-| `npm run dev` | Watch build |
-| `npm test` | Unit tests |
-| `npm run test:integration` | Integration tests |
-| `npm run test:all` | All tests |
-| `npm run lint` / `npm run lint:fix` | ESLint |
-| `npm run typecheck` | TypeScript |
-| `npm run build` | Production build |
+| Command                             | Description       |
+| ----------------------------------- | ----------------- |
+| `npm run dev`                       | Watch build       |
+| `npm test`                          | Unit tests        |
+| `npm run test:integration`          | Integration tests |
+| `npm run test:all`                  | All tests         |
+| `npm run lint` / `npm run lint:fix` | ESLint            |
+| `npm run typecheck`                 | TypeScript        |
+| `npm run build`                     | Production build  |
 
 **Support**
 
-- [GitHub Issues](https://github.com/sijeeshmiziha/sweagent/issues) – Bugs and features  
-- [GitHub Discussions](https://github.com/sijeeshmiziha/sweagent/discussions) – Questions
+- [GitHub Issues](https://github.com/sijeeshmiziha/sweagent/issues) -- Bugs and features
+- [GitHub Discussions](https://github.com/sijeeshmiziha/sweagent/discussions) -- Questions
 
 ---
 
 ## License
 
-MIT License – see [LICENSE](LICENSE) for details.
-
----
-
-<p align="center">
-  Made with ❤️ by the CompilersLab team!
-</p>
+MIT License -- see [LICENSE](LICENSE) for details.