sweagent 0.0.2 → 0.0.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +1086 -1021
  2. package/dist/index.cjs +912 -1019
  3. package/dist/index.cjs.map +1 -1
  4. package/dist/index.d.cts +526 -955
  5. package/dist/index.d.ts +526 -955
  6. package/dist/index.js +912 -1019
  7. package/dist/index.js.map +1 -1
  8. package/dist/stdio.d.ts +2 -0
  9. package/dist/stdio.js +1514 -0
  10. package/dist/stdio.js.map +1 -0
  11. package/package.json +9 -3
package/README.md CHANGED
@@ -1,10 +1,10 @@
1
1
  <p align="center">
2
2
  <h1 align="center">sweagent</h1>
3
3
  <p align="center">
4
- <strong>The planning layer that makes Cursor, Claude Code, and Codex 10x more effective.</strong>
4
+ <strong>The Deep Thinking layer that makes Cursor, Claude Code, and Codex 10x more effective.</strong>
5
5
  </p>
6
6
  <p align="center">
7
- 14 domain-specialized AI agent pipelines — Planning, Requirements, Data Modeling, API Design, Auth, Backend, Frontend, and more — each with dedicated orchestrators, sub-agents, and structured outputs. Generate implementation-ready blueprints, then hand them to your coding agent.
7
+ 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.
8
8
  </p>
9
9
  </p>
10
10
 
@@ -16,15 +16,21 @@
16
16
  </p>
17
17
 
18
18
  <p align="center">
19
- <a href="#what-is-sweagent">What is sweagent?</a> •
19
+ <a href="#the-problem">The Problem</a> •
20
20
  <a href="#use-with-cursor-claude-code-and-codex">Use with Coding Agents</a> •
21
- <a href="#domain-agents">Domain Agents</a> •
21
+ <a href="#why-sweagent">Why sweagent?</a> •
22
+ <a href="#deep-reasoning-philosophy">Deep Reasoning</a> •
23
+ <a href="#how-it-works">How It Works</a> •
24
+ <a href="#features">Features</a> •
25
+ <a href="#planning-pipeline">Planning Pipeline</a> •
22
26
  <a href="#full-pipeline">Full Pipeline</a> •
23
- <a href="#installation">Installation</a> •
27
+ <a href="#domain-agent-modules">Modules</a> •
24
28
  <a href="#getting-started">Getting Started</a> •
29
+ <a href="#installation">Installation</a> •
30
+ <a href="#mcp-server">MCP Server</a> •
25
31
  <a href="#architecture">Architecture</a> •
26
32
  <a href="#api-reference">API Reference</a> •
27
- <a href="#domain-agent-modules">Modules</a> •
33
+ <a href="#reference">Reference</a> •
28
34
  <a href="#examples">Examples</a> •
29
35
  <a href="#contributing">Contributing</a>
30
36
  </p>
@@ -33,65 +39,59 @@
33
39
 
34
40
  ## Table of Contents
35
41
 
36
- - [What is sweagent?](#what-is-sweagent)
42
+ - [The Problem](#the-problem)
37
43
  - [Use with Cursor, Claude Code, and Codex](#use-with-cursor-claude-code-and-codex)
38
44
  - [Why sweagent?](#why-sweagent)
39
- - [Domain Agents](#domain-agents)
40
- - [Full Pipeline](#full-pipeline)
41
- - [Planning Pipeline](#planning-pipeline)
45
+ - [Deep Reasoning Philosophy](#deep-reasoning-philosophy)
46
+ - [How It Works](#how-it-works)
42
47
  - [Features](#features)
43
- - [Installation](#installation)
48
+ - [Planning Pipeline](#planning-pipeline)
49
+ - [Full Pipeline](#full-pipeline)
50
+ - [Domain Agent Modules](#domain-agent-modules)
44
51
  - [Getting Started](#getting-started)
52
+ - [Installation](#installation)
53
+ - [MCP Server](#mcp-server)
45
54
  - [Architecture](#architecture)
46
55
  - [API Reference](#api-reference)
47
- - [Domain Agent Modules](#domain-agent-modules)
56
+ - [Reference](#reference)
48
57
  - [Examples](#examples)
49
- - [Configuration Reference](#configuration-reference)
50
- - [FAQ](#faq)
51
- - [Troubleshooting](#troubleshooting)
52
58
  - [Contributing](#contributing)
53
59
  - [License](#license)
54
60
 
55
61
  ---
56
62
 
57
- ## What is sweagent?
63
+ ## The Problem
58
64
 
59
- AI coding agents -- Claude Code, Codex, Cursor -- 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.
65
+ 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.
60
66
 
61
- **sweagent** is a library of **14 domain-specialized AI agent pipelines** that handle every stage of software planning at professional quality. Each domain -- planning, requirements, data modeling, API design, auth, backend, frontend -- gets its own **orchestrator agent** with dedicated **sub-agents**, **tools**, and **multi-stage pipelines** that produce structured, reviewable outputs.
67
+ **Without sweagent**, a coding agent receives `"build a task manager"` and immediately starts writing code:
62
68
 
63
- | Stage | Agent | Sub-Agents | Output |
64
- | ------------------- | ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------- |
65
- | **Planning** | `runPlanningAgent` | -- | Implementation-ready markdown plan (11 sections) |
66
- | **Requirements** | `runRequirementGathererAgent` | -- | Structured JSON (actors, flows, stories, modules) |
67
- | **Data Modeling** | `runDataModelerAgent` | `entity-analyzer`, `relationship-mapper`, `schema-refiner` | MongoDB/PostgreSQL schemas |
68
- | **DB Design** | `runDbDesignerAgent` | `entity-analyzer`, `schema-refiner` | MongoDB schemas with RBAC permissions |
69
- | **API Design** | `runApiDesignerAgent` | `endpoint-analyzer`, `contract-designer` | REST and/or GraphQL API design |
70
- | **Auth Design** | `runAuthDesignerAgent` | `security-analyzer`, `flow-designer` | Auth strategy, flows, middleware, RBAC |
71
- | **Backend Arch.** | `runBackendArchitectAgent` | `framework-selector`, `service-planner` | Backend architecture (Express/Apollo) |
72
- | **Express Builder** | `runExpressBuilderAgent` | `route-generator`, `middleware-configurator` | Express.js REST API config |
73
- | **Apollo Builder** | `runApolloBuilderAgent` | `schema-generator`, `resolver-planner` | Apollo GraphQL subgraph config |
74
- | **Frontend Arch.** | `runFrontendArchitectAgent` | `page-planner`, `component-analyzer` | Frontend architecture (React/Next.js) |
75
- | **React Builder** | `runReactBuilderAgent` | `graphql-analyzer`, `config-validator` | React + Vite app config from GraphQL |
76
- | **Next.js Builder** | `runNextjsBuilderAgent` | `route-planner`, `api-route-generator` | Next.js App Router config |
77
- | **Execution Plan** | `runExecutionPlannerAgent` | `edge-case-analyzer`, `testing-strategist` | Phased implementation plan |
78
- | **Hello World** | `runHelloWorldAgent` | -- | Template module for custom agents |
69
+ - Picks a random framework (maybe Express, maybe Fastify, who knows)
70
+ - Invents a database schema on the fly, misses relationships
71
+ - Forgets authentication entirely
72
+ - Skips error handling and edge cases
73
+ - Produces something that sort-of runs but needs a rewrite
74
+
75
+ **With sweagent**, the coding agent receives a structured blueprint before writing a single line:
76
+
77
+ - **11-section markdown plan** with tech stack, data models, API routes, auth flow, implementation order, edge cases, and testing checklist
78
+ - **Structured JSON requirements** with actors, user flows, stories, and module breakdowns
79
+ - **Database schemas** with exact field types, relationships, indexes, and validation rules
80
+ - **API contracts** with endpoints, methods, request/response shapes, and auth requirements
81
+ - **Frontend architecture** with pages, components, routing, and state management
79
82
 
80
83
  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.
81
84
 
82
85
  ```typescript
83
- import { runPlanningWithResult } from 'sweagent';
86
+ import { runPlanningAgent } from 'sweagent';
84
87
 
85
- // Generate an implementation-ready plan -- validated by an LLM judge
86
- const { planning, plan } = await runPlanningWithResult({
88
+ const result = await runPlanningAgent({
87
89
  input: 'Task manager app with user auth, task CRUD, assignments, and a dashboard',
88
90
  model: { provider: 'openai', model: 'gpt-4o-mini' },
89
91
  });
90
92
 
91
- if (planning) {
92
- console.log('Plan is implementation-ready. Hand it to your coding agent.');
93
- console.log(plan); // Full markdown blueprint
94
- }
93
+ console.log('Plan is implementation-ready. Hand it to your coding agent.');
94
+ console.log(result.output); // Full markdown blueprint
95
95
  ```
96
96
 
97
97
  TypeScript-first, built on the Vercel AI SDK, ships with all provider SDKs (OpenAI, Anthropic, Google). Set your API keys and go.
@@ -100,89 +100,99 @@ TypeScript-first, built on the Vercel AI SDK, ships with all provider SDKs (Open
100
100
 
101
101
  ## Use with Cursor, Claude Code, and Codex
102
102
 
103
- 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.
103
+ sweagent is an MCP server. Install it once, add one config to your IDE, and all 13 domain agents are available directly in your chat -- planning, requirements, data modeling, API design, auth, architecture, and more. No scripts, no code, no file juggling.
104
104
 
105
105
  ```mermaid
106
106
  flowchart LR
107
- Requirement["Your idea"] --> sweagent["sweagent"]
108
- sweagent --> Plan["plan.md / JSON spec"]
109
- Plan --> Cursor["Cursor"]
110
- Plan --> ClaudeCode["Claude Code"]
111
- Plan --> Codex["Codex"]
112
- Cursor --> Code["Production code"]
113
- ClaudeCode --> Code
114
- Codex --> Code
107
+ You["You type a prompt"] -->|"MCP"| Server["sweagent"]
108
+ Server --> Plan["plan"]
109
+ Server --> Req["gather_requirements"]
110
+ Server --> Data["design_data_model"]
111
+ Server --> Api["design_api"]
112
+ Server --> More["... 9 more tools"]
113
+ Plan --> Agent["Your coding agent implements it"]
114
+ Req --> Agent
115
+ Data --> Agent
116
+ Api --> Agent
117
+ More --> Agent
115
118
  ```
116
119
 
117
- ### With Cursor
120
+ ### 1. Install
118
121
 
119
- Generate a plan, save it to your project, and reference it in Cursor chat or `.cursor/rules/`:
122
+ ```bash
123
+ npm install -g sweagent
124
+ ```
120
125
 
121
- ```typescript
122
- import { runPlanningWithResult } from 'sweagent';
123
- import { writeFileSync } from 'fs';
126
+ ### 2. Add the config for your IDE
124
127
 
125
- const { planning, plan } = await runPlanningWithResult({
126
- input: 'E-commerce with users, products, cart, checkout, admin dashboard',
127
- model: { provider: 'openai', model: 'gpt-4o-mini' },
128
- });
128
+ **Cursor** -- create `.cursor/mcp.json` in your project root:
129
129
 
130
- writeFileSync('plan.md', plan);
131
- // Open plan.md in Cursor and say: "Implement this plan step by step"
132
- // Or copy plan.md to .cursor/rules/ so every agent session uses it as context
130
+ ```json
131
+ {
132
+ "mcpServers": {
133
+ "sweagent": {
134
+ "command": "sweagent",
135
+ "env": { "OPENAI_API_KEY": "your-openai-api-key" }
136
+ }
137
+ }
138
+ }
133
139
  ```
134
140
 
135
- ### With Claude Code
136
-
137
- Generate a plan and save it as `CLAUDE.md` or a reference file. Claude Code automatically reads `CLAUDE.md` for project context:
138
-
139
- ```typescript
140
- import { runPlanningWithResult } from 'sweagent';
141
- import { writeFileSync } from 'fs';
141
+ **VS Code (Copilot)** -- create `.vscode/mcp.json` in your project root:
142
142
 
143
- const { plan } = await runPlanningWithResult({
144
- input: 'SaaS dashboard with multi-tenancy, billing, and analytics',
145
- model: { provider: 'anthropic', model: 'claude-sonnet-4-20250514' },
146
- });
143
+ ```json
144
+ {
145
+ "servers": {
146
+ "sweagent": {
147
+ "command": "sweagent",
148
+ "env": { "OPENAI_API_KEY": "your-openai-api-key" }
149
+ }
150
+ }
151
+ }
152
+ ```
147
153
 
148
- // Option 1: Save as CLAUDE.md for automatic context
149
- writeFileSync('CLAUDE.md', `# Implementation Plan\n\n${plan}`);
154
+ **Windsurf** -- edit `~/.codeium/windsurf/mcp_config.json`:
150
155
 
151
- // Option 2: Save as plan.md and reference it
152
- writeFileSync('plan.md', plan);
153
- // Then tell Claude Code: "Read plan.md and implement phase 1"
156
+ ```json
157
+ {
158
+ "mcpServers": {
159
+ "sweagent": {
160
+ "command": "sweagent",
161
+ "env": { "OPENAI_API_KEY": "your-openai-api-key" }
162
+ }
163
+ }
164
+ }
154
165
  ```
155
166
 
156
- ### With Codex
167
+ **Claude Desktop** -- edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
157
168
 
158
- Codex works best with structured, machine-readable specs. Use the Requirement Gatherer or Data Modeler for JSON output:
169
+ ```json
170
+ {
171
+ "mcpServers": {
172
+ "sweagent": {
173
+ "command": "sweagent",
174
+ "env": { "OPENAI_API_KEY": "your-openai-api-key" }
175
+ }
176
+ }
177
+ }
178
+ ```
159
179
 
160
- ```typescript
161
- import { runRequirementGathererAgent } from 'sweagent';
162
- import { writeFileSync } from 'fs';
180
+ > **Don't want a global install?** Replace `"command": "sweagent"` with `"command": "npx"` and add `"args": ["-y", "sweagent"]`. See [MCP Server](#mcp-server) for all options including from-source setup.
163
181
 
164
- const result = await runRequirementGathererAgent({
165
- input: 'Task manager with teams, Kanban boards, and time tracking',
166
- model: { provider: 'openai', model: 'gpt-4o-mini' },
167
- maxIterations: 15,
168
- });
182
+ ### 3. Restart your IDE and start prompting
169
183
 
170
- // Structured JSON with actors, flows, stories, modules, DB schema, API design
171
- writeFileSync('requirements.json', result.output);
172
- // Feed requirements.json to Codex as context for implementation
173
- ```
184
+ Open the chat and try:
174
185
 
175
- ### Why this works
186
+ - _"Use the plan tool to plan a task manager app with teams, Kanban boards, and time tracking."_
187
+ - _"Use the gather_requirements tool to extract structured requirements for an e-commerce platform."_
188
+ - _"Use the design_data_model tool to design a PostgreSQL schema for a SaaS billing system."_
176
189
 
177
- Without sweagent, a coding agent receives "build a task manager" and immediately starts guessing. With sweagent, it receives:
190
+ The agent calls sweagent, gets back a structured blueprint, and can immediately start implementing it.
178
191
 
179
- - **11-section markdown plan** with tech stack, data models, API routes, auth flow, implementation order, edge cases, and testing checklist
180
- - **Structured JSON requirements** with actors, user flows, stories, and module breakdowns
181
- - **Database schemas** with exact field types, relationships, indexes, and validation rules
182
- - **API contracts** with endpoints, methods, request/response shapes, and auth requirements
183
- - **Frontend architecture** with pages, components, routing, and state management
192
+ ### Full reference
184
193
 
185
- The coding agent stops guessing and starts executing a professional-grade blueprint.
194
+ - [MCP Server](#mcp-server) -- all 13 tools, input parameters, multi-provider setup, troubleshooting
195
+ - [Getting Started](#getting-started) and [Full Pipeline](#full-pipeline) -- programmatic API for scripted pipelines, CI, or chaining multiple agents in code
186
196
 
187
197
  ---
188
198
 
@@ -190,7 +200,7 @@ The coding agent stops guessing and starts executing a professional-grade bluepr
190
200
 
191
201
  ### 1. Domain-specialized agents, not generic wrappers
192
202
 
193
- Each module is a self-contained agent pipeline purpose-built for its domain. The DB Designer doesn't reuse the Planning Agent's prompts -- it has its own `entity-analyzer` and `schema-refiner` sub-agents, its own tools (`design_database`, `validate_schema`), and its own output schema. The React Builder has a `graphql-analyzer` and `config-validator`. Every domain gets the specialized treatment it deserves.
203
+ 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.
194
204
 
195
205
  ### 2. Multi-stage pipelines with structured outputs
196
206
 
@@ -198,7 +208,7 @@ Every domain agent progresses through deliberate stages -- discovery, requiremen
198
208
 
199
209
  ### 3. Sub-agent orchestration for complex domains
200
210
 
201
- When a domain is too complex for a single agent, sweagent delegates to specialized sub-agents. The DB Designer 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.
211
+ 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.
202
212
 
203
213
  ### 4. Enterprise-quality output, not bullet points
204
214
 
@@ -214,571 +224,641 @@ Long-running agents fail when they lose context. sweagent encodes patterns for s
214
224
 
215
225
  ---
216
226
 
217
- ## Domain Agents
227
+ ## Deep Reasoning Philosophy
228
+
229
+ 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.
218
230
 
219
- sweagent ships with 14 domain agent modules organized across the full software planning pipeline. Each is a complete pipeline with its own orchestrator, tools, sub-agents, and output format.
231
+ ### Multi-Stage Reasoning
232
+
233
+ 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.
220
234
 
221
235
  ```mermaid
222
236
  flowchart LR
223
- subgraph discovery [Discovery and Planning]
224
- Planning["Planning"]
237
+ Input["Requirement"] --> Discovery["Discovery"]
238
+ Discovery --> Requirements["Requirements"]
239
+ Requirements --> SubReq1["entity-analyzer"]
240
+ Requirements --> SubReq2["page-planner"]
241
+ Requirements --> SubReq3["flow-designer"]
242
+ SubReq1 --> Design["Design"]
243
+ SubReq2 --> Design
244
+ SubReq3 --> Design
245
+ Design --> SubDes1["endpoint-analyzer"]
246
+ Design --> SubDes2["contract-designer"]
247
+ SubDes1 --> Synthesis["Synthesis"]
248
+ SubDes2 --> Synthesis
249
+ Synthesis --> Output["Blueprint"]
250
+ ```
251
+
252
+ ### Sub-Agent Decomposition
253
+
254
+ 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.
255
+
256
+ ### Inference-Time Depth
257
+
258
+ 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.
259
+
260
+ ---
261
+
262
+ ## How It Works
263
+
264
+ 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.
265
+
266
+ ```mermaid
267
+ flowchart TB
268
+ subgraph input [Your Idea]
269
+ Idea["Natural language requirement"]
270
+ end
271
+
272
+ subgraph discovery [Discovery Layer]
225
273
  ReqGatherer["Requirement Gatherer"]
226
- ExecPlanner["Execution Planner"]
274
+ Planning["Planning Agent"]
227
275
  end
228
276
 
229
- subgraph data [Data Layer]
230
- DataModeler["Data Modeler"]
231
- DbDesigner["DB Designer"]
277
+ subgraph bridge [Bridge]
278
+ FromReqs["from-requirements"]
232
279
  end
233
280
 
234
- subgraph api [API Layer]
281
+ subgraph specialists [Specialist Architects]
282
+ DataModeler["Data Modeler"]
235
283
  ApiDesigner["API Designer"]
236
284
  AuthDesigner["Auth Designer"]
285
+ BackendArch["Backend Architect"]
286
+ FrontendArch["Frontend Architect"]
237
287
  end
238
288
 
239
- subgraph backend [Backend]
240
- BackendArch["Backend Architect"]
289
+ subgraph builders [Framework Builders]
241
290
  ExpressBuilder["Express Builder"]
242
291
  ApolloBuilder["Apollo Builder"]
243
- end
244
-
245
- subgraph frontend [Frontend]
246
- FrontendArch["Frontend Architect"]
247
292
  ReactBuilder["React Builder"]
248
293
  NextjsBuilder["Next.js Builder"]
249
294
  end
250
295
 
296
+ subgraph execution [Execution]
297
+ ExecPlanner["Execution Planner"]
298
+ CodingAgent["Cursor / Claude Code / Codex"]
299
+ end
300
+
301
+ Idea --> ReqGatherer
302
+ Idea --> Planning
303
+ ReqGatherer -->|"FinalRequirement JSON"| FromReqs
304
+ FromReqs -->|"PlanningContext"| Planning
251
305
  ReqGatherer --> DataModeler
252
- ReqGatherer --> DbDesigner
253
306
  DataModeler --> ApiDesigner
254
- DbDesigner --> ApiDesigner
255
307
  ApiDesigner --> AuthDesigner
256
308
  AuthDesigner --> BackendArch
257
- BackendArch --> ExpressBuilder
258
- BackendArch --> ApolloBuilder
259
309
  ApiDesigner --> FrontendArch
260
- FrontendArch --> ReactBuilder
261
- FrontendArch --> NextjsBuilder
310
+ BackendArch -->|"Express selected"| ExpressBuilder
311
+ BackendArch -->|"Apollo selected"| ApolloBuilder
312
+ FrontendArch -->|"React selected"| ReactBuilder
313
+ FrontendArch -->|"Next.js selected"| NextjsBuilder
262
314
  Planning --> ExecPlanner
315
+ ExecPlanner --> CodingAgent
316
+ builders --> CodingAgent
317
+ specialists --> CodingAgent
263
318
  ```
264
319
 
265
- ### Planning Agent
266
-
267
- Turns a natural-language project description into an implementation-ready markdown plan through 4 stages and 8+ LLM calls. Covers tech stack, data models, API routes, implementation order, edge cases, and testing checklists. Optional LLM validation judges completeness.
320
+ ### Three usage modes
268
321
 
269
- ```typescript
270
- import { runPlanningWithResult } from 'sweagent';
322
+ **1. Quick plan** -- Planning Agent standalone. One call, one markdown plan. Best for getting a coding agent started fast.
271
323
 
272
- const { planning, plan } = await runPlanningWithResult({
273
- input: 'E-commerce: users, products, cart, checkout, admin dashboard',
274
- model: { provider: 'openai', model: 'gpt-4o-mini' },
275
- });
276
- // planning === true means the plan passed all validation criteria
277
- // plan is the full markdown blueprint
278
- ```
324
+ **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.
279
325
 
280
- **Stages:** Discovery, Requirements (4 LLM calls), Design (2 LLM calls), Synthesis | **Output:** Markdown | **Modes:** One-shot, validated, interactive chat
326
+ **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.
281
327
 
282
328
  ---
283
329
 
284
- ### Requirement Gatherer Agent
285
-
286
- Produces structured JSON requirements -- not prose. Extracts actors with permissions, user flows with step-by-step sequences, user stories with acceptance criteria, and module breakdowns with CRUD operations, database schemas, and API designs.
287
-
288
- ```typescript
289
- import { runRequirementGathererAgent } from 'sweagent';
290
-
291
- const result = await runRequirementGathererAgent({
292
- input: 'Project management tool with teams, Kanban boards, and time tracking',
293
- model: { provider: 'openai', model: 'gpt-4o-mini' },
294
- maxIterations: 15,
295
- });
296
- // result.output contains structured JSON: actors, flows, stories, modules
297
- ```
330
+ ## Features
298
331
 
299
- **Stages:** Discovery, Requirements, Design, Synthesis | **Output:** Structured JSON | **Schemas:** Actors, Flows, Stories, Modules, Database, API
332
+ | Feature | Description |
333
+ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
334
+ | **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. |
335
+ | **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. |
336
+ | **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. |
337
+ | **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. |
338
+ | **Multi-Provider Models** | Unified API for OpenAI, Anthropic, and Google. One `createModel()` call, zero provider lock-in. |
339
+ | **Type-Safe Tools** | Define tools with Zod schemas; full type inference and validation before execution. Minimal, workflow-oriented tool sets. |
340
+ | **Agent Framework** | Iterative agent loop with tool calling, step callbacks, and configurable max iterations. |
341
+ | **MCP Protocol** | Connect to Model Context Protocol servers over HTTP or stdio. Lazy connection, typed tool invocation. |
342
+ | **Vision** | Image inputs via `model.generateVision()` for vision-capable models. |
343
+ | **Zero Extra Deps** | All provider SDKs (OpenAI, Anthropic, Google) included. Set API keys and run. |
300
344
 
301
345
  ---
302
346
 
303
- ### DB Designer Agent
347
+ ## Planning Pipeline
304
348
 
305
- An orchestrator agent that delegates to specialized sub-agents for entity analysis and schema refinement. Produces MongoDB-style schemas with modules, fields, relationships, indexes, and validation rules.
349
+ 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.
306
350
 
307
- ```typescript
308
- import { runDbDesignerAgent } from 'sweagent';
351
+ ### How it works
309
352
 
310
- const result = await runDbDesignerAgent({
311
- input: 'E-commerce: users, orders, products. Admins manage products.',
312
- model: { provider: 'openai', model: 'gpt-4o-mini' },
313
- maxIterations: 15,
314
- });
315
- // result.output contains the full database schema
353
+ ```mermaid
354
+ flowchart LR
355
+ Input["User Requirement"] --> Discovery["Discovery"]
356
+ Discovery --> Requirements["Requirements"]
357
+ Requirements --> Design["Design"]
358
+ Design --> Synthesis["Synthesis"]
359
+ Synthesis --> Output["plan.md"]
316
360
  ```
317
361
 
318
- **Sub-agents:** `entity-analyzer` (extracts entities and relationships), `schema-refiner` (normalizes and validates) | **Tools:** `design_database`, `design_database_pro`, `redesign_database`, `validate_schema` | **Output:** MongoDB schema JSON
319
-
320
- ---
321
-
322
- ### React Builder Agent
323
-
324
- 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.
362
+ ### Stages
325
363
 
326
- ```typescript
327
- import { runReactBuilderAgent } from 'sweagent';
364
+ | Stage | What it produces | Sections |
365
+ | ---------------- | -------------------------------------------------- | ------------------------------------------------------------------- |
366
+ | **Discovery** | Understands the project, asks clarifying questions | Project overview |
367
+ | **Requirements** | 4 sequential LLM calls to flesh out the spec | Tech stack, feature decisions, data models, pages/routes, auth flow |
368
+ | **Design** | 2 sequential LLM calls for technical design | API routes, implementation details |
369
+ | **Synthesis** | Assembles the final plan | Implementation order, edge cases, testing checklist |
328
370
 
329
- const result = await runReactBuilderAgent({
330
- input: 'GraphQL schema: type User { id: ID! name: String! } type Task { ... }',
331
- model: { provider: 'openai', model: 'gpt-4o-mini' },
332
- maxIterations: 15,
333
- });
334
- // result.output contains frontend config JSON
335
- ```
371
+ ### Output
336
372
 
337
- **Sub-agents:** `graphql-analyzer` (schema parsing), `config-validator` (output verification) | **Tools:** `generate_frontend`, `generate_feature_breakdown`, `validate_frontend_config` | **Output:** React app config JSON
373
+ The plan is a markdown document with these sections:
338
374
 
339
- ---
375
+ - **Overview** -- project scope and goals
376
+ - **Tech Stack** -- languages, frameworks, database, auth approach
377
+ - **Feature Decisions** -- what to build and what to defer
378
+ - **Data Models** -- schemas, relationships, fields
379
+ - **Pages and Routes** -- frontend structure
380
+ - **Authentication Flow** -- auth strategy and implementation
381
+ - **API Routes** -- endpoints, methods, request/response shapes
382
+ - **Implementation Details** -- architecture decisions, file structure
383
+ - **Execution Plan** -- phased implementation order
384
+ - **Edge Cases** -- error handling, boundary conditions
385
+ - **Testing Checklist** -- what to verify at each phase
340
386
 
341
- ### Data Modeler Agent
387
+ ### Two modes
342
388
 
343
- 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.
389
+ **One-shot mode** -- pass a requirement, get a plan:
344
390
 
345
391
  ```typescript
346
- import { runDataModelerAgent } from 'sweagent';
392
+ import { runPlanningAgent } from 'sweagent';
347
393
 
348
- const result = await runDataModelerAgent({
349
- input: 'SaaS platform with organizations, users, projects, and billing',
350
- model: { provider: 'openai', model: 'gpt-4o-mini' },
351
- maxIterations: 15,
394
+ const result = await runPlanningAgent({
395
+ input: 'Fitness app with workouts, nutrition tracking, and social features',
396
+ model: { provider: 'anthropic', model: 'claude-sonnet-4-20250514' },
352
397
  });
353
- // result.output: DataModelDesign JSON with entities, fields, indexes, relationships
398
+ console.log(result.output); // Full plan markdown
354
399
  ```
355
400
 
356
- **Sub-agents:** `entity-analyzer`, `relationship-mapper`, `schema-refiner` | **Tools:** `design_schema`, `design_schema_pro`, `refine_schema`, `validate_data_model` | **Output:** Data model JSON (MongoDB or PostgreSQL)
357
-
358
- ---
359
-
360
- ### API Designer Agent
361
-
362
- Designs REST and/or GraphQL APIs from data models, producing endpoint definitions with request/response contracts, auth requirements, and operation details.
401
+ **Interactive chat mode** -- multi-turn conversation where you refine the plan:
363
402
 
364
403
  ```typescript
365
- import { runApiDesignerAgent } from 'sweagent';
404
+ import { processPlanningChat } from 'sweagent';
405
+ import type { PlanningContext } from 'sweagent';
366
406
 
367
- const result = await runApiDesignerAgent({
368
- input: 'Design REST API for a task manager with users, projects, and tasks',
407
+ let context: PlanningContext | null = null;
408
+
409
+ // Turn 1: describe the project
410
+ const turn1 = await processPlanningChat('Build a task manager with teams', context, {
369
411
  model: { provider: 'openai', model: 'gpt-4o-mini' },
370
- maxIterations: 15,
371
412
  });
372
- // result.output: ApiDesign JSON with REST endpoints and/or GraphQL operations
373
- ```
413
+ context = turn1.context;
414
+ console.log(turn1.message); // Assistant asks clarifying questions
415
+ console.log(turn1.pendingQuestions); // ["What auth provider?", ...]
374
416
 
375
- **Sub-agents:** `endpoint-analyzer`, `contract-designer` | **Tools:** `design_api`, `design_api_pro`, `validate_api` | **Output:** API design JSON (REST/GraphQL)
417
+ // Turn 2: answer and advance
418
+ const turn2 = await processPlanningChat('Use NextAuth with GitHub OAuth', context, {
419
+ model: { provider: 'openai', model: 'gpt-4o-mini' },
420
+ });
421
+ context = turn2.context;
376
422
 
377
- ---
423
+ // Continue until turn.planMarkdown is set (plan complete)
424
+ ```
378
425
 
379
- ### Auth Designer Agent
426
+ ### Requirements to plan (the bridge)
380
427
 
381
- Designs authentication and authorization systems with strategies, flows, middleware, roles, and security policies.
428
+ 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:
382
429
 
383
430
  ```typescript
384
- import { runAuthDesignerAgent } from 'sweagent';
431
+ import { runRequirementGathererAgent, runPlanningFromRequirements } from 'sweagent';
385
432
 
386
- const result = await runAuthDesignerAgent({
387
- input: 'JWT auth with email/password, Google OAuth, role-based access (admin, member)',
388
- model: { provider: 'openai', model: 'gpt-4o-mini' },
433
+ const model = { provider: 'openai', model: 'gpt-4o-mini' } as const;
434
+
435
+ // Step 1: Gather structured requirements (actors, flows, stories, modules, DB)
436
+ const reqResult = await runRequirementGathererAgent({
437
+ input: 'Task manager with teams, Kanban boards, and time tracking',
438
+ model,
389
439
  maxIterations: 15,
390
440
  });
391
- // result.output: AuthDesign JSON with strategy, flows, middleware, roles, policies
392
- ```
393
441
 
394
- **Sub-agents:** `security-analyzer`, `flow-designer` | **Tools:** `design_auth`, `validate_auth` | **Output:** Auth design JSON
442
+ // Step 2: Convert requirements into a planning context and generate the plan
443
+ // Skips discovery + requirements stages; begins at design
444
+ const planResult = await runPlanningFromRequirements({
445
+ requirement: JSON.parse(reqResult.output),
446
+ model,
447
+ });
448
+
449
+ console.log(planResult.output); // Full implementation plan as markdown
450
+ ```
395
451
 
396
452
  ---
397
453
 
398
- ### Frontend Architect Agent
454
+ ## Full Pipeline
399
455
 
400
- Plans frontend architecture including pages, components, routing, and state management. Routes to React Builder or Next.js Builder based on framework selection.
456
+ 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.
401
457
 
402
458
  ```typescript
403
- import { runFrontendArchitectAgent } from 'sweagent';
459
+ import {
460
+ runRequirementGathererAgent,
461
+ runDataModelerAgent,
462
+ runApiDesignerAgent,
463
+ runAuthDesignerAgent,
464
+ runBackendArchitectAgent,
465
+ runFrontendArchitectAgent,
466
+ runExecutionPlannerAgent,
467
+ } from 'sweagent';
468
+ import { writeFileSync } from 'fs';
404
469
 
405
- const result = await runFrontendArchitectAgent({
406
- input: 'Dashboard app with analytics, settings, and user management pages',
407
- model: { provider: 'openai', model: 'gpt-4o-mini' },
470
+ const model = { provider: 'openai', model: 'gpt-4o-mini' } as const;
471
+
472
+ // Step 1: Gather structured requirements
473
+ const requirements = await runRequirementGathererAgent({
474
+ input: 'Project management SaaS with teams, Kanban boards, time tracking, and billing',
475
+ model,
408
476
  maxIterations: 15,
409
477
  });
410
- // result.output: FrontendDesign JSON with pages, components, state management, routing
411
- ```
412
-
413
- **Sub-agents:** `page-planner`, `component-analyzer`, `framework-selector` | **Output:** Frontend design JSON
414
-
415
- ---
416
478
 
417
- ### Backend Architect Agent
418
-
419
- Plans backend architecture including framework selection, services, middleware, routes, and folder structure. Routes to Express Builder or Apollo Builder based on framework choice.
420
-
421
- ```typescript
422
- import { runBackendArchitectAgent } from 'sweagent';
423
-
424
- const result = await runBackendArchitectAgent({
425
- input: 'REST API backend with user auth, CRUD operations, and file uploads',
426
- model: { provider: 'openai', model: 'gpt-4o-mini' },
479
+ // Step 2: Design the data model from requirements
480
+ const dataModel = await runDataModelerAgent({
481
+ input: `Design a data model based on these requirements:\n${requirements.output}`,
482
+ model,
427
483
  maxIterations: 15,
428
484
  });
429
- // result.output: BackendDesign JSON with framework, services, middleware, routes
430
- ```
431
485
 
432
- **Sub-agents:** `framework-selector`, `service-planner` | **Tools:** `design_backend`, `validate_backend` | **Output:** Backend design JSON
433
-
434
- ---
435
-
436
- ### Express Builder Agent
486
+ // Step 3: Design the API from the data model
487
+ const apiDesign = await runApiDesignerAgent({
488
+ input: `Design REST API for this data model:\n${dataModel.output}`,
489
+ model,
490
+ maxIterations: 15,
491
+ });
437
492
 
438
- Generates Express.js REST API configuration with routers, models, middleware, and environment variables.
493
+ // Step 4: Design auth from the requirements and API
494
+ const authDesign = await runAuthDesignerAgent({
495
+ input: `Design auth for this project:\nRequirements: ${requirements.output}\nAPI: ${apiDesign.output}`,
496
+ model,
497
+ maxIterations: 15,
498
+ });
439
499
 
440
- ```typescript
441
- import { runExpressBuilderAgent } from 'sweagent';
500
+ // Step 5: Plan backend architecture
501
+ const backendDesign = await runBackendArchitectAgent({
502
+ input: `Design backend:\nData model: ${dataModel.output}\nAPI: ${apiDesign.output}\nAuth: ${authDesign.output}`,
503
+ model,
504
+ maxIterations: 15,
505
+ });
442
506
 
443
- const result = await runExpressBuilderAgent({
444
- input: 'Express API for e-commerce with products, orders, and user auth',
445
- model: { provider: 'openai', model: 'gpt-4o-mini' },
507
+ // Step 6: Plan frontend architecture
508
+ const frontendDesign = await runFrontendArchitectAgent({
509
+ input: `Design frontend:\nAPI: ${apiDesign.output}\nRequirements: ${requirements.output}`,
510
+ model,
446
511
  maxIterations: 15,
447
512
  });
448
- // result.output: ExpressConfig JSON with routers, models, middleware, env vars
513
+
514
+ // Save all specs for your coding agent
515
+ writeFileSync('specs/requirements.json', requirements.output);
516
+ writeFileSync('specs/data-model.json', dataModel.output);
517
+ writeFileSync('specs/api-design.json', apiDesign.output);
518
+ writeFileSync('specs/auth-design.json', authDesign.output);
519
+ writeFileSync('specs/backend-design.json', backendDesign.output);
520
+ writeFileSync('specs/frontend-design.json', frontendDesign.output);
521
+
522
+ // Now hand the specs/ directory to Cursor, Claude Code, or Codex
523
+ // "Implement the backend using specs/backend-design.json and specs/data-model.json"
449
524
  ```
450
525
 
451
- **Sub-agents:** `route-generator`, `middleware-configurator` | **Tools:** `generate_express`, `scaffold_express`, `validate_express` | **Output:** Express config JSON
526
+ 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.
452
527
 
453
528
  ---
454
529
 
455
- ### Apollo Builder Agent
530
+ ## Domain Agent Modules
456
531
 
457
- Generates Apollo GraphQL subgraph configuration with modules, types, resolvers, datasources, and Federation v2 support.
532
+ 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.
533
+
534
+ | Stage | Agent | Sub-Agents | Output |
535
+ | ------------------- | ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------- |
536
+ | **Planning** | `runPlanningAgent` | -- | Implementation-ready markdown plan (11 sections) |
537
+ | **Requirements** | `runRequirementGathererAgent` | -- | Structured JSON (actors, flows, stories, modules) |
538
+ | **Data Modeling** | `runDataModelerAgent` | `entity-analyzer`, `relationship-mapper`, `schema-refiner` | MongoDB/PostgreSQL schemas |
539
+ | **API Design** | `runApiDesignerAgent` | `endpoint-analyzer`, `contract-designer` | REST and/or GraphQL API design |
540
+ | **Auth Design** | `runAuthDesignerAgent` | `security-analyzer`, `flow-designer` | Auth strategy, flows, middleware, RBAC |
541
+ | **Backend Arch.** | `runBackendArchitectAgent` | `framework-selector`, `service-planner` | Backend architecture (Express/Apollo) |
542
+ | **Express Builder** | `runExpressBuilderAgent` | `route-generator`, `middleware-configurator` | Express.js REST API config |
543
+ | **Apollo Builder** | `runApolloBuilderAgent` | `schema-generator`, `resolver-planner` | Apollo GraphQL subgraph config |
544
+ | **Frontend Arch.** | `runFrontendArchitectAgent` | `page-planner`, `component-analyzer`, `framework-selector` | Frontend architecture (React/Next.js) |
545
+ | **React Builder** | `runReactBuilderAgent` | `graphql-analyzer`, `config-validator` | React + Vite app config from GraphQL |
546
+ | **Next.js Builder** | `runNextjsBuilderAgent` | `route-planner`, `api-route-generator` | Next.js App Router config |
547
+ | **Execution Plan** | `runExecutionPlannerAgent` | `edge-case-analyzer`, `testing-strategist` | Phased implementation plan |
548
+ | **Hello World** | `runAgent` + `helloWorldTool` | -- | Template module for custom agents |
549
+
550
+ ---
551
+
552
+ ### Planning Agent
553
+
554
+ 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.
555
+
556
+ | Attribute | Detail |
557
+ | ----------------- | ----------------------------------------------------------------------- |
558
+ | **Stages** | Discovery, Requirements (4 LLM calls), Design (2 LLM calls), Synthesis |
559
+ | **Sub-Agents** | -- |
560
+ | **Tools** | -- (pipeline stages, not tool-based) |
561
+ | **Output Format** | Markdown plan (11 sections) |
562
+ | **Modes** | One-shot (`runPlanningAgent`), interactive chat (`processPlanningChat`) |
458
563
 
459
564
  ```typescript
460
- import { runApolloBuilderAgent } from 'sweagent';
565
+ import { runPlanningAgent } from 'sweagent';
461
566
 
462
- const result = await runApolloBuilderAgent({
463
- input: 'Apollo subgraph for a task manager with users, projects, and tasks',
567
+ const result = await runPlanningAgent({
568
+ input: 'E-commerce: users, orders, products. Admins manage products.',
464
569
  model: { provider: 'openai', model: 'gpt-4o-mini' },
465
- maxIterations: 15,
466
570
  });
467
- // result.output: SubgraphConfig JSON with modules, types, operations, datasources
571
+ console.log(result.output); // Full markdown blueprint
468
572
  ```
469
573
 
470
- **Sub-agents:** `schema-generator`, `resolver-planner` | **Tools:** `generate_subgraph`, `scaffold_subgraph`, `validate_subgraph` | **Output:** Apollo subgraph config JSON
574
+ See [Planning Pipeline](#planning-pipeline) for stage-by-stage details.
471
575
 
472
576
  ---
473
577
 
474
- ### Next.js Builder Agent
578
+ ### Requirement Gatherer Agent
475
579
 
476
- Generates Next.js App Router configuration with pages, layouts, API routes, server actions, and middleware.
580
+ Produces structured JSON requirements -- not prose. Unlike the Planning module (markdown output), the Requirement Gatherer extracts typed data that downstream systems can consume programmatically.
581
+
582
+ | Attribute | Detail |
583
+ | ----------------- | ------------------------------------------------------------------------------------- |
584
+ | **Stages** | Discovery, Requirements, Design, Synthesis |
585
+ | **Sub-Agents** | -- |
586
+ | **Tools** | Stage-specific tools |
587
+ | **Output Format** | Structured JSON |
588
+ | **Schemas** | Actors, User Flows, User Stories, Modules, Database Design, API Design |
589
+ | **Modes** | One-shot (`runRequirementGathererAgent`), interactive chat (`processRequirementChat`) |
590
+
591
+ **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).
477
592
 
478
593
  ```typescript
479
- import { runNextjsBuilderAgent } from 'sweagent';
594
+ import { runRequirementGathererAgent } from 'sweagent';
480
595
 
481
- const result = await runNextjsBuilderAgent({
482
- input: 'Next.js app for project management with teams, tasks, and dashboards',
596
+ const result = await runRequirementGathererAgent({
597
+ input: 'Project management tool with teams and Kanban boards',
483
598
  model: { provider: 'openai', model: 'gpt-4o-mini' },
484
599
  maxIterations: 15,
485
600
  });
486
- // result.output: NextjsConfig JSON with pages, layouts, API routes, server actions
601
+ // result.output: structured JSON with actors, flows, stories, modules
487
602
  ```
488
603
 
489
- **Sub-agents:** `route-planner`, `api-route-generator` | **Tools:** `generate_nextjs`, `validate_nextjs` | **Output:** Next.js config JSON
490
-
491
604
  ---
492
605
 
493
- ### Execution Planner Agent
606
+ ### Data Modeler Agent
494
607
 
495
- Creates phased implementation execution plans from plan sections, with edge case analysis and testing checklists.
608
+ 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.
609
+
610
+ | Attribute | Detail |
611
+ | ----------------- | ---------------------------------------------------------------------------- |
612
+ | **Pattern** | Orchestrator with sub-agents |
613
+ | **Sub-Agents** | `entity-analyzer`, `relationship-mapper`, `schema-refiner` |
614
+ | **Tools** | `design_schema`, `design_schema_pro`, `refine_schema`, `validate_data_model` |
615
+ | **Output Format** | Data model JSON (entities, fields, indexes, relationships) |
616
+ | **Databases** | MongoDB, PostgreSQL |
496
617
 
497
618
  ```typescript
498
- import { runExecutionPlannerAgent } from 'sweagent';
619
+ import { runDataModelerAgent } from 'sweagent';
499
620
 
500
- const result = await runExecutionPlannerAgent({
501
- input: 'Create execution plan for the task manager project',
621
+ const result = await runDataModelerAgent({
622
+ input: 'SaaS platform with organizations, users, projects, and billing',
502
623
  model: { provider: 'openai', model: 'gpt-4o-mini' },
503
624
  maxIterations: 15,
504
625
  });
505
- // result.output: ExecutionPlan JSON with phases, edge cases, testing checklist
626
+ // result.output: DataModelDesign JSON with entities, fields, indexes, relationships
506
627
  ```
507
628
 
508
- **Sub-agents:** `edge-case-analyzer`, `testing-strategist` | **Tools:** `create_execution_plan`, `validate_execution_plan` | **Output:** Execution plan JSON
509
-
510
629
  ---
511
630
 
512
- ### Hello World (Template)
631
+ ### API Designer Agent
513
632
 
514
- Minimal example module with a single greeting tool. Use as a starting point when building your own domain agent module.
633
+ Designs REST and/or GraphQL APIs from data models, producing endpoint definitions with request/response contracts, auth requirements, and operation details.
634
+
635
+ | Attribute | Detail |
636
+ | ----------------- | ------------------------------------------------------------------------------------------------------- |
637
+ | **Pattern** | Orchestrator with sub-agents |
638
+ | **Sub-Agents** | `endpoint-analyzer` (derives endpoints from data model), `contract-designer` (designs request/response) |
639
+ | **Tools** | `design_api`, `design_api_pro`, `validate_api` |
640
+ | **Output Format** | API design JSON (REST endpoints and/or GraphQL operations) |
515
641
 
516
642
  ```typescript
517
- import { createModel, runAgent, helloWorldTool } from 'sweagent';
643
+ import { runApiDesignerAgent } from 'sweagent';
518
644
 
519
- const result = await runAgent({
520
- model: createModel({ provider: 'openai', model: 'gpt-4o-mini' }),
521
- tools: [helloWorldTool],
522
- systemPrompt: 'You are helpful.',
523
- input: 'Say hello',
645
+ const result = await runApiDesignerAgent({
646
+ input: 'Design REST API for a task manager with users, projects, and tasks',
647
+ model: { provider: 'openai', model: 'gpt-4o-mini' },
648
+ maxIterations: 15,
524
649
  });
650
+ // result.output: ApiDesign JSON with REST endpoints and/or GraphQL operations
525
651
  ```
526
652
 
527
653
  ---
528
654
 
529
- ## Planning Pipeline
530
-
531
- 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.
532
-
533
- ### How it works
655
+ ### Auth Designer Agent
534
656
 
535
- ```mermaid
536
- flowchart LR
537
- Input["User Requirement"] --> Discovery["Discovery"]
538
- Discovery --> Requirements["Requirements"]
539
- Requirements --> Design["Design"]
540
- Design --> Synthesis["Synthesis"]
541
- Synthesis --> Plan["plan.md"]
542
- Plan --> Validate["LLM Validator"]
543
- Validate --> Output["planning: bool, plan: string"]
544
- ```
657
+ Designs authentication and authorization systems with strategies, flows, middleware, roles, and security policies.
545
658
 
546
- ### Stages
659
+ | Attribute | Detail |
660
+ | ----------------- | ------------------------------------------------------------------------------------------ |
661
+ | **Pattern** | Orchestrator with sub-agents |
662
+ | **Sub-Agents** | `security-analyzer` (analyzes security requirements), `flow-designer` (designs auth flows) |
663
+ | **Tools** | `design_auth`, `validate_auth` |
664
+ | **Output Format** | Auth design JSON (strategy, flows, middleware, roles, policies) |
547
665
 
548
- | Stage | What it produces | Sections |
549
- | ---------------- | -------------------------------------------------- | ------------------------------------------------------------------- |
550
- | **Discovery** | Understands the project, asks clarifying questions | Project overview |
551
- | **Requirements** | 4 sequential LLM calls to flesh out the spec | Tech stack, feature decisions, data models, pages/routes, auth flow |
552
- | **Design** | 2 sequential LLM calls for technical design | API routes, implementation details |
553
- | **Synthesis** | Assembles the final plan | Implementation order, edge cases, testing checklist |
666
+ ```typescript
667
+ import { runAuthDesignerAgent } from 'sweagent';
554
668
 
555
- ### Output
669
+ const result = await runAuthDesignerAgent({
670
+ input: 'JWT auth with email/password, Google OAuth, role-based access (admin, member)',
671
+ model: { provider: 'openai', model: 'gpt-4o-mini' },
672
+ maxIterations: 15,
673
+ });
674
+ // result.output: AuthDesign JSON with strategy, flows, middleware, roles, policies
675
+ ```
556
676
 
557
- The plan is a markdown document with these sections:
677
+ ---
558
678
 
559
- - **Overview** — project scope and goals
560
- - **Tech Stack** — languages, frameworks, database, auth approach
561
- - **Feature Decisions** — what to build and what to defer
562
- - **Data Models** — schemas, relationships, fields
563
- - **Pages and Routes** — frontend structure
564
- - **Authentication Flow** — auth strategy and implementation
565
- - **API Routes** — endpoints, methods, request/response shapes
566
- - **Implementation Details** — architecture decisions, file structure
567
- - **Execution Plan** — phased implementation order
568
- - **Edge Cases** — error handling, boundary conditions
569
- - **Testing Checklist** — what to verify at each phase
679
+ ### Backend Architect Agent
570
680
 
571
- ### Two modes
681
+ Plans backend architecture including framework selection, services, middleware, routes, and folder structure. Routes to Express Builder or Apollo Builder based on framework choice.
572
682
 
573
- **One-shot mode** — pass a requirement, get a plan:
683
+ | Attribute | Detail |
684
+ | ----------------- | ------------------------------------------------------------------------------- |
685
+ | **Pattern** | Orchestrator with sub-agents |
686
+ | **Sub-Agents** | `framework-selector`, `service-planner` |
687
+ | **Tools** | `design_backend`, `validate_backend` |
688
+ | **Output Format** | Backend design JSON (framework, services, middleware, routes, folder structure) |
689
+ | **Frameworks** | Express, Apollo, or both |
574
690
 
575
691
  ```typescript
576
- import { runPlanningAgent } from 'sweagent';
692
+ import { runBackendArchitectAgent } from 'sweagent';
577
693
 
578
- const result = await runPlanningAgent({
579
- input: 'Fitness app with workouts, nutrition tracking, and social features',
580
- model: { provider: 'anthropic', model: 'claude-sonnet-4-20250514' },
694
+ const result = await runBackendArchitectAgent({
695
+ input: 'REST API backend with user auth, CRUD operations, and file uploads',
696
+ model: { provider: 'openai', model: 'gpt-4o-mini' },
697
+ maxIterations: 15,
581
698
  });
582
- console.log(result.output); // Full plan markdown
699
+ // result.output: BackendDesign JSON with framework, services, middleware, routes
583
700
  ```
584
701
 
585
- **With validation** — run the plan through an LLM judge that checks completeness:
702
+ ---
586
703
 
587
- ```typescript
588
- import { runPlanningWithResult } from 'sweagent';
704
+ ### Express Builder Agent
589
705
 
590
- const { planning, plan } = await runPlanningWithResult({
591
- input: 'Fitness app with workouts, nutrition tracking, and social features',
592
- model: { provider: 'openai', model: 'gpt-4o-mini' },
593
- });
594
- // planning === true means the plan passed all validation criteria
595
- ```
706
+ Generates Express.js REST API configuration with routers, models, middleware, and environment variables.
596
707
 
597
- **Interactive chat mode** — multi-turn conversation where you refine the plan:
708
+ | Attribute | Detail |
709
+ | ----------------- | ----------------------------------------------------------- |
710
+ | **Pattern** | Orchestrator with sub-agents |
711
+ | **Sub-Agents** | `route-generator`, `middleware-configurator` |
712
+ | **Tools** | `generate_express`, `scaffold_express`, `validate_express` |
713
+ | **Output Format** | Express config JSON (routers, models, middleware, env vars) |
598
714
 
599
715
  ```typescript
600
- import { processPlanningChat } from 'sweagent';
601
- import type { PlanningContext } from 'sweagent';
602
-
603
- let context: PlanningContext | null = null;
604
-
605
- // Turn 1: describe the project
606
- const turn1 = await processPlanningChat('Build a task manager with teams', context, {
607
- model: { provider: 'openai', model: 'gpt-4o-mini' },
608
- });
609
- context = turn1.context;
610
- console.log(turn1.message); // Assistant asks clarifying questions
611
- console.log(turn1.pendingQuestions); // ["What auth provider?", ...]
716
+ import { runExpressBuilderAgent } from 'sweagent';
612
717
 
613
- // Turn 2: answer and advance
614
- const turn2 = await processPlanningChat('Use NextAuth with GitHub OAuth', context, {
718
+ const result = await runExpressBuilderAgent({
719
+ input: 'Express API for e-commerce with products, orders, and user auth',
615
720
  model: { provider: 'openai', model: 'gpt-4o-mini' },
721
+ maxIterations: 15,
616
722
  });
617
- context = turn2.context;
618
-
619
- // Continue until turn.planMarkdown is set (plan complete)
723
+ // result.output: ExpressConfig JSON with routers, models, middleware, env vars
620
724
  ```
621
725
 
622
- ### Validation criteria
726
+ ---
623
727
 
624
- The LLM validator (`validatePlanForCodingAgent`) checks that the plan includes:
728
+ ### Apollo Builder Agent
625
729
 
626
- 1. Clear project overview and scope
627
- 2. Tech stack specified (languages, frameworks, database, auth)
628
- 3. Implementation order or phased steps
629
- 4. Concrete actionable steps (files, routes, APIs, or models)
630
- 5. Data model, authentication, and API surface addressed
730
+ Generates Apollo GraphQL subgraph configuration with modules, types, resolvers, datasources, and Federation v2 support.
631
731
 
632
- ---
732
+ | Attribute | Detail |
733
+ | ----------------- | --------------------------------------------------------------------- |
734
+ | **Pattern** | Orchestrator with sub-agents |
735
+ | **Sub-Agents** | `schema-generator`, `resolver-planner` |
736
+ | **Tools** | `generate_subgraph`, `scaffold_subgraph`, `validate_subgraph` |
737
+ | **Output Format** | Apollo subgraph config JSON (modules, types, operations, datasources) |
633
738
 
634
- ## Full Pipeline
739
+ ```typescript
740
+ import { runApolloBuilderAgent } from 'sweagent';
635
741
 
636
- 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.
637
-
638
- ```typescript
639
- import {
640
- runRequirementGathererAgent,
641
- runDataModelerAgent,
642
- runApiDesignerAgent,
643
- runAuthDesignerAgent,
644
- runBackendArchitectAgent,
645
- runFrontendArchitectAgent,
646
- runExecutionPlannerAgent,
647
- } from 'sweagent';
648
- import { writeFileSync } from 'fs';
649
-
650
- const model = { provider: 'openai', model: 'gpt-4o-mini' } as const;
651
-
652
- // Step 1: Gather structured requirements
653
- const requirements = await runRequirementGathererAgent({
654
- input: 'Project management SaaS with teams, Kanban boards, time tracking, and billing',
655
- model,
742
+ const result = await runApolloBuilderAgent({
743
+ input: 'Apollo subgraph for a task manager with users, projects, and tasks',
744
+ model: { provider: 'openai', model: 'gpt-4o-mini' },
656
745
  maxIterations: 15,
657
746
  });
747
+ // result.output: SubgraphConfig JSON with modules, types, operations, datasources
748
+ ```
658
749
 
659
- // Step 2: Design the data model from requirements
660
- const dataModel = await runDataModelerAgent({
661
- input: `Design a data model based on these requirements:\n${requirements.output}`,
662
- model,
663
- maxIterations: 15,
664
- });
750
+ ---
665
751
 
666
- // Step 3: Design the API from the data model
667
- const apiDesign = await runApiDesignerAgent({
668
- input: `Design REST API for this data model:\n${dataModel.output}`,
669
- model,
670
- maxIterations: 15,
671
- });
752
+ ### Frontend Architect Agent
672
753
 
673
- // Step 4: Design auth from the requirements and API
674
- const authDesign = await runAuthDesignerAgent({
675
- input: `Design auth for this project:\nRequirements: ${requirements.output}\nAPI: ${apiDesign.output}`,
676
- model,
677
- maxIterations: 15,
678
- });
754
+ Plans frontend architecture including pages, components, routing, and state management. Routes to React Builder or Next.js Builder based on framework selection.
679
755
 
680
- // Step 5: Plan backend architecture
681
- const backendDesign = await runBackendArchitectAgent({
682
- input: `Design backend:\nData model: ${dataModel.output}\nAPI: ${apiDesign.output}\nAuth: ${authDesign.output}`,
683
- model,
684
- maxIterations: 15,
685
- });
756
+ | Attribute | Detail |
757
+ | ----------------- | ------------------------------------------------------------------- |
758
+ | **Pattern** | Orchestrator with sub-agents |
759
+ | **Sub-Agents** | `page-planner`, `component-analyzer`, `framework-selector` |
760
+ | **Output Format** | Frontend design JSON (pages, components, state management, routing) |
761
+ | **Frameworks** | React + Vite, Next.js |
686
762
 
687
- // Step 6: Plan frontend architecture
688
- const frontendDesign = await runFrontendArchitectAgent({
689
- input: `Design frontend:\nAPI: ${apiDesign.output}\nRequirements: ${requirements.output}`,
690
- model,
763
+ ```typescript
764
+ import { runFrontendArchitectAgent } from 'sweagent';
765
+
766
+ const result = await runFrontendArchitectAgent({
767
+ input: 'Dashboard app with analytics, settings, and user management pages',
768
+ model: { provider: 'openai', model: 'gpt-4o-mini' },
691
769
  maxIterations: 15,
692
770
  });
771
+ // result.output: FrontendDesign JSON with pages, components, state management, routing
772
+ ```
693
773
 
694
- // Save all specs for your coding agent
695
- writeFileSync('specs/requirements.json', requirements.output);
696
- writeFileSync('specs/data-model.json', dataModel.output);
697
- writeFileSync('specs/api-design.json', apiDesign.output);
698
- writeFileSync('specs/auth-design.json', authDesign.output);
699
- writeFileSync('specs/backend-design.json', backendDesign.output);
700
- writeFileSync('specs/frontend-design.json', frontendDesign.output);
774
+ ---
701
775
 
702
- // Now hand the specs/ directory to Cursor, Claude Code, or Codex
703
- // "Implement the backend using specs/backend-design.json and specs/data-model.json"
704
- ```
776
+ ### React Builder Agent
705
777
 
706
- 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.
778
+ 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.
707
779
 
708
- ---
780
+ | Attribute | Detail |
781
+ | ----------------- | ----------------------------------------------------------------------------------------------------------- |
782
+ | **Pattern** | Orchestrator with sub-agents |
783
+ | **Sub-Agents** | `graphql-analyzer` (parses GraphQL schema structure), `config-validator` (validates frontend config output) |
784
+ | **Tools** | `generate_frontend`, `generate_feature_breakdown`, `validate_frontend_config` |
785
+ | **Output Format** | React app config JSON (app, modules, pages, fields, API hooks, branding) |
786
+ | **Schemas** | App config, User config, Page config, Field config, Branding |
709
787
 
710
- ## Features
788
+ ```typescript
789
+ import { runReactBuilderAgent } from 'sweagent';
711
790
 
712
- | Feature | Description |
713
- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
714
- | **14 Domain Agent Modules** | Planning, Requirement Gatherer, Data Modeler, DB Designer, 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. |
715
- | **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. |
716
- | **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. |
717
- | **Plan Validation** | LLM-based judge validates that planning output meets all criteria for a coding agent to start implementing. |
718
- | **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. |
719
- | **Multi-Provider Models** | Unified API for OpenAI, Anthropic, and Google. One `createModel()` call, zero provider lock-in. |
720
- | **Type-Safe Tools** | Define tools with Zod schemas; full type inference and validation before execution. Minimal, workflow-oriented tool sets. |
721
- | **Agent Framework** | Iterative agent loop with tool calling, step callbacks, and configurable max iterations. |
722
- | **MCP Protocol** | Connect to Model Context Protocol servers over HTTP or stdio. Lazy connection, typed tool invocation. |
723
- | **Vision** | Image inputs via `model.generateVision()` for vision-capable models. |
724
- | **Zero Extra Deps** | All provider SDKs (OpenAI, Anthropic, Google) included. Set API keys and run. |
791
+ const result = await runReactBuilderAgent({
792
+ input: 'GraphQL schema: type User { id: ID! name: String! } type Task { ... }',
793
+ model: { provider: 'openai', model: 'gpt-4o-mini' },
794
+ maxIterations: 15,
795
+ });
796
+ // result.output: frontend config JSON with pages, fields, hooks, branding
797
+ ```
725
798
 
726
799
  ---
727
800
 
728
- ## Installation
801
+ ### Next.js Builder Agent
729
802
 
730
- ### Prerequisites
803
+ Generates Next.js App Router configuration with pages, layouts, API routes, server actions, and middleware.
731
804
 
732
- - **Node.js** >= 18.0.0
733
- - **npm** >= 8.0.0 (or yarn, pnpm, bun)
805
+ | Attribute | Detail |
806
+ | ----------------- | ---------------------------------------------------------------------------- |
807
+ | **Pattern** | Orchestrator with sub-agents |
808
+ | **Sub-Agents** | `route-planner`, `api-route-generator` |
809
+ | **Tools** | `generate_nextjs`, `validate_nextjs` |
810
+ | **Output Format** | Next.js config JSON (pages, layouts, API routes, server actions, middleware) |
734
811
 
735
- ### Install
812
+ ```typescript
813
+ import { runNextjsBuilderAgent } from 'sweagent';
736
814
 
737
- ```bash
738
- npm install sweagent
815
+ const result = await runNextjsBuilderAgent({
816
+ input: 'Next.js app for project management with teams, tasks, and dashboards',
817
+ model: { provider: 'openai', model: 'gpt-4o-mini' },
818
+ maxIterations: 15,
819
+ });
820
+ // result.output: NextjsConfig JSON with pages, layouts, API routes, server actions
739
821
  ```
740
822
 
741
- Or with yarn, pnpm, or bun:
823
+ ---
742
824
 
743
- ```bash
744
- yarn add sweagent
745
- pnpm add sweagent
746
- bun add sweagent
747
- ```
825
+ ### Execution Planner Agent
748
826
 
749
- All AI provider SDKs (OpenAI, Anthropic, Google) are included; no extra packages needed.
827
+ Creates phased implementation execution plans from plan sections, with edge case analysis and testing checklists.
750
828
 
751
- ### From source
829
+ | Attribute | Detail |
830
+ | ----------------- | --------------------------------------------------------------------------------------- |
831
+ | **Pattern** | Orchestrator with sub-agents |
832
+ | **Sub-Agents** | `edge-case-analyzer`, `testing-strategist` |
833
+ | **Tools** | `create_execution_plan`, `validate_execution_plan` |
834
+ | **Output Format** | Execution plan JSON (phases, edge cases, testing checklist, security/performance notes) |
752
835
 
753
- ```bash
754
- git clone https://github.com/sijeeshmiziha/sweagent.git
755
- cd sweagent
756
- npm install
757
- ```
836
+ ```typescript
837
+ import { runExecutionPlannerAgent } from 'sweagent';
758
838
 
759
- ### Environment setup
839
+ const result = await runExecutionPlannerAgent({
840
+ input: 'Create execution plan for the task manager project',
841
+ model: { provider: 'openai', model: 'gpt-4o-mini' },
842
+ maxIterations: 15,
843
+ });
844
+ // result.output: ExecutionPlan JSON with phases, edge cases, testing checklist
845
+ ```
760
846
 
761
- Create a `.env` file in your project root:
847
+ ---
762
848
 
763
- ```bash
764
- # At least one provider API key is required
765
- OPENAI_API_KEY=sk-...
766
- ANTHROPIC_API_KEY=sk-ant-...
767
- GOOGLE_GENERATIVE_AI_API_KEY=...
768
- ```
849
+ ### Hello World (Template)
769
850
 
770
- ### Verify
851
+ Minimal example module with a single greeting tool. Use as a starting point when building your own domain agent module.
771
852
 
772
- ```bash
773
- # If installed as a package
774
- echo 'import { createModel, runAgent, helloWorldTool } from "sweagent";
775
- const model = createModel({ provider: "openai", model: "gpt-4o-mini" });
776
- const result = await runAgent({ model, tools: [helloWorldTool], systemPrompt: "You are helpful.", input: "Say hello" });
777
- console.log(result.output);' > test.mjs
778
- node --env-file=.env test.mjs
853
+ ```typescript
854
+ import { createModel, runAgent, helloWorldTool } from 'sweagent';
779
855
 
780
- # If cloned from source
781
- npm run example -- examples/hello-world/01-hello-world.ts
856
+ const result = await runAgent({
857
+ model: createModel({ provider: 'openai', model: 'gpt-4o-mini' }),
858
+ tools: [helloWorldTool],
859
+ systemPrompt: 'You are helpful.',
860
+ input: 'Say hello',
861
+ });
782
862
  ```
783
863
 
784
864
  ---
@@ -880,15 +960,14 @@ const result = await runAgent({
880
960
  Generate an implementation plan for a coding agent:
881
961
 
882
962
  ```typescript
883
- import { runPlanningWithResult } from 'sweagent';
963
+ import { runPlanningAgent } from 'sweagent';
884
964
 
885
- const { planning, plan } = await runPlanningWithResult({
965
+ const result = await runPlanningAgent({
886
966
  input: 'E-commerce site: users, products, cart, checkout, admin dashboard',
887
967
  model: { provider: 'openai', model: 'gpt-4o-mini' },
888
968
  });
889
969
 
890
- console.log('Ready for coding agent:', planning);
891
- console.log(plan);
970
+ console.log(result.output); // Full markdown blueprint
892
971
  ```
893
972
 
894
973
  ### Level 6: MCP integration
@@ -906,730 +985,709 @@ const result = await client.callTool('tool_name', { arg: 'value' });
906
985
 
907
986
  ---
908
987
 
909
- ## Architecture
988
+ ## Installation
910
989
 
911
- ### System overview
990
+ ### Prerequisites
912
991
 
913
- ```mermaid
914
- graph TB
915
- subgraph Client[Client Application]
916
- App["Your App / Cursor / Claude Code / Codex"]
917
- end
992
+ - **Node.js** >= 18.0.0
993
+ - **npm** >= 8.0.0 (or yarn, pnpm, bun)
918
994
 
919
- subgraph DomainAgents[Domain Agent Modules]
920
- Planning["Planning"]
921
- ReqGatherer["Requirement Gatherer"]
922
- DataModeler["Data Modeler"]
923
- DbDesigner["DB Designer"]
924
- ApiDesigner["API Designer"]
925
- AuthDesigner["Auth Designer"]
926
- BackendArch["Backend Architect"]
927
- ExpressBuilder["Express Builder"]
928
- ApolloBuilder["Apollo Builder"]
929
- FrontendArch["Frontend Architect"]
930
- ReactBuilder["React Builder"]
931
- NextjsBuilder["Next.js Builder"]
932
- ExecPlanner["Execution Planner"]
933
- end
995
+ ### Install
934
996
 
935
- subgraph Framework[Shared Framework]
936
- Models["Model Abstraction"]
937
- ToolFW["Tool Framework"]
938
- AgentLoop["Agent Loop"]
939
- SubAgentOrch["Sub-Agent Orchestration"]
940
- MCP["MCP Protocol"]
941
- end
997
+ ```bash
998
+ npm install sweagent
999
+ ```
942
1000
 
943
- subgraph Providers[AI Providers]
944
- OpenAI["OpenAI"]
945
- Anthropic["Anthropic"]
946
- Google["Google"]
947
- end
1001
+ Or with yarn, pnpm, or bun:
948
1002
 
949
- App --> DomainAgents
950
- DomainAgents --> Framework
951
- Framework --> Providers
1003
+ ```bash
1004
+ yarn add sweagent
1005
+ pnpm add sweagent
1006
+ bun add sweagent
952
1007
  ```
953
1008
 
954
- ### Domain agent pipeline flow
1009
+ All AI provider SDKs (OpenAI, Anthropic, Google) are included; no extra packages needed.
955
1010
 
956
- Each domain agent follows a structured pipeline. The Planning Agent is representative:
1011
+ ### From source
957
1012
 
958
- ```mermaid
959
- flowchart LR
960
- Input["User Requirement"] --> Discovery["Discovery Stage"]
961
- Discovery --> Requirements["Requirements Stage"]
962
- Requirements --> Design["Design Stage"]
963
- Design --> Synthesis["Synthesis Stage"]
964
- Synthesis --> Plan["Structured Output"]
965
- Plan --> Validate["LLM Validator"]
966
- Validate --> Output["Validated Result"]
1013
+ ```bash
1014
+ git clone https://github.com/sijeeshmiziha/sweagent.git
1015
+ cd sweagent
1016
+ npm install
967
1017
  ```
968
1018
 
969
- ### Orchestrator with sub-agents
1019
+ ### Environment setup
970
1020
 
971
- Domain agents like DB Designer and React Builder delegate to specialized sub-agents:
1021
+ Create a `.env` file in your project root:
972
1022
 
973
- ```mermaid
974
- sequenceDiagram
975
- participant User
976
- participant Orchestrator
977
- participant Model
978
- participant Tools
979
- participant SubAgent1 as entity-analyzer
980
- participant SubAgent2 as schema-refiner
981
-
982
- User->>Orchestrator: Natural-language requirement
983
- Orchestrator->>Model: Messages + Domain Tools
984
- Model-->>Orchestrator: Tool call design_database
985
- Orchestrator->>Tools: Execute design_database
986
- Tools-->>Orchestrator: Initial schema
987
- Orchestrator->>SubAgent1: Analyze entities and relationships
988
- SubAgent1-->>Orchestrator: Structured entity analysis
989
- Orchestrator->>SubAgent2: Refine and validate schema
990
- SubAgent2-->>Orchestrator: Validated schema
991
- Orchestrator->>Model: Compile final output
992
- Model-->>Orchestrator: Final result
993
- Orchestrator-->>User: Production-grade schema
1023
+ ```bash
1024
+ # At least one provider API key is required
1025
+ OPENAI_API_KEY=sk-...
1026
+ ANTHROPIC_API_KEY=sk-ant-...
1027
+ GOOGLE_GENERATIVE_AI_API_KEY=...
994
1028
  ```
995
1029
 
996
- ### Agent execution loop
1030
+ ### Verify
997
1031
 
998
- ```mermaid
999
- sequenceDiagram
1000
- participant User
1001
- participant Agent
1002
- participant Model
1003
- participant Tools
1032
+ ```bash
1033
+ # If installed as a package
1034
+ echo 'import { createModel, runAgent, helloWorldTool } from "sweagent";
1035
+ const model = createModel({ provider: "openai", model: "gpt-4o-mini" });
1036
+ const result = await runAgent({ model, tools: [helloWorldTool], systemPrompt: "You are helpful.", input: "Say hello" });
1037
+ console.log(result.output);' > test.mjs
1038
+ node --env-file=.env test.mjs
1004
1039
 
1005
- User->>Agent: Input + Tools + System Prompt
1006
- loop Until Complete or Max Iterations
1007
- Agent->>Model: Messages + Tool Schemas
1008
- Model-->>Agent: Response (Text or Tool Calls)
1009
- alt Tool Calls Present
1010
- Agent->>Tools: Execute Tool Calls
1011
- Tools-->>Agent: Tool Results
1012
- Agent->>Agent: Append Results to Messages
1013
- else Final Answer
1014
- Agent-->>User: Output + Steps + Usage
1015
- end
1016
- end
1040
+ # If cloned from source
1041
+ npm run example -- examples/hello-world/01-hello-world.ts
1017
1042
  ```
1018
1043
 
1019
1044
  ---
1020
1045
 
1021
- ## Engineering Deep Dive
1046
+ ## MCP Server
1022
1047
 
1023
- ### The problem: long-running coding agents
1048
+ sweagent is also a **Model Context Protocol (MCP) server**. Install it once and every MCP-compatible IDE or tool -- Cursor, VS Code, Windsurf, Claude Desktop, and more -- can call any of the 13 domain agents directly from the chat interface. No wrapper scripts, no code to write.
1024
1049
 
1025
- 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.
1050
+ ```mermaid
1051
+ flowchart LR
1052
+ IDE["Cursor / VS Code / Windsurf / Claude Desktop"] -->|"MCP stdio"| Server["sweagent MCP Server"]
1053
+ Server --> Plan["plan"]
1054
+ Server --> Req["gather_requirements"]
1055
+ Server --> Data["design_data_model"]
1056
+ Server --> Api["design_api"]
1057
+ Server --> Auth["design_auth"]
1058
+ Server --> More["... 8 more tools"]
1059
+ ```
1026
1060
 
1027
- ### Incremental progress pattern
1061
+ ### Quick Start
1028
1062
 
1029
- 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.
1063
+ **1. Install sweagent from npm:**
1030
1064
 
1031
- ### Feature list approach
1065
+ ```bash
1066
+ npm install -g sweagent
1067
+ ```
1032
1068
 
1033
- 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.
1069
+ This installs the `sweagent` command globally on your machine. Requires Node.js >= 18.
1034
1070
 
1035
- ### Clean state principle
1071
+ **2. Set your API key:**
1036
1072
 
1037
- 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.
1073
+ You need at least one AI provider API key. Export it in your shell or pass it via the IDE config (shown below):
1038
1074
 
1039
- ### Error hierarchy
1075
+ ```bash
1076
+ export OPENAI_API_KEY=sk-...
1077
+ # or ANTHROPIC_API_KEY, or GOOGLE_GENERATIVE_AI_API_KEY
1078
+ ```
1040
1079
 
1041
- | Class | When |
1042
- | ------------------- | ------------------------------------------------ |
1043
- | **LibraryError** | Base; all others extend it. |
1044
- | **ModelError** | Model creation or invoke failed. |
1045
- | **ToolError** | Tool not found or tool execution failed. |
1046
- | **ValidationError** | Zod validation failed. |
1047
- | **AgentError** | Agent reached max iterations without completing. |
1048
- | **SubagentError** | Subagent config or run failed. |
1080
+ **3. Add the config to your IDE** (pick your IDE below) **and restart.**
1049
1081
 
1050
- All accept an optional `cause` for chaining.
1082
+ **4. Verify** -- ask the chat agent: _"Use the hello_world tool to test the sweagent server."_
1051
1083
 
1052
- ### Provider adapter pattern
1084
+ > **No global install?** You can skip step 1 and use `npx -y sweagent` instead. The IDE configs below show both options.
1053
1085
 
1054
- 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.
1086
+ ### How it runs
1055
1087
 
1056
- ### Tool execution safety
1088
+ The MCP server communicates over **stdio**. Your IDE starts it automatically -- you do not run these commands yourself. Under the hood, the IDE runs one of:
1057
1089
 
1058
- 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.
1090
+ ```bash
1091
+ # If you installed globally (npm install -g sweagent)
1092
+ sweagent
1059
1093
 
1060
- ---
1094
+ # If you prefer npx (no install needed, downloads on first use)
1095
+ npx -y sweagent
1061
1096
 
1062
- ## API Reference
1097
+ # If you cloned the repo and built from source
1098
+ node --env-file=.env dist/stdio.js
1099
+ ```
1063
1100
 
1064
- All public APIs are exported from the main package: `import { ... } from 'sweagent'`.
1101
+ ### Setup with Cursor
1065
1102
 
1066
- ### Models
1103
+ Create `.cursor/mcp.json` in your project root:
1067
1104
 
1068
- **createModel(config)** — Create a model instance.
1105
+ **Option A -- Global install (recommended):**
1069
1106
 
1070
- ```typescript
1071
- import { createModel } from 'sweagent';
1107
+ ```json
1108
+ {
1109
+ "mcpServers": {
1110
+ "sweagent": {
1111
+ "command": "sweagent",
1112
+ "env": {
1113
+ "OPENAI_API_KEY": "your-openai-api-key"
1114
+ }
1115
+ }
1116
+ }
1117
+ }
1118
+ ```
1072
1119
 
1073
- const model = createModel({
1074
- provider: 'openai' | 'anthropic' | 'google',
1075
- model: string, // e.g. 'gpt-4o', 'claude-sonnet-4-20250514'
1076
- apiKey?: string, // Uses env var by default
1077
- temperature?: number,
1078
- maxOutputTokens?: number,
1079
- baseUrl?: string,
1080
- });
1120
+ **Option B -- npx (no install needed):**
1081
1121
 
1082
- const response = await model.invoke(messages, { tools });
1083
- // response: { text, toolCalls, usage, finishReason }
1122
+ ```json
1123
+ {
1124
+ "mcpServers": {
1125
+ "sweagent": {
1126
+ "command": "npx",
1127
+ "args": ["-y", "sweagent"],
1128
+ "env": {
1129
+ "OPENAI_API_KEY": "your-openai-api-key"
1130
+ }
1131
+ }
1132
+ }
1133
+ }
1084
1134
  ```
1085
1135
 
1086
- **Supported models (examples):**
1087
-
1088
- | Provider | Models |
1089
- | --------- | ---------------------------------------------------- |
1090
- | OpenAI | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` |
1091
- | Anthropic | `claude-sonnet-4-20250514`, `claude-3-opus-20240229` |
1092
- | Google | `gemini-1.5-pro`, `gemini-1.5-flash` |
1136
+ **Option C -- From source (local clone):**
1093
1137
 
1094
- **Vision:** `model.generateVision(prompt, images, options)` for image inputs.
1138
+ ```json
1139
+ {
1140
+ "mcpServers": {
1141
+ "sweagent": {
1142
+ "command": "node",
1143
+ "args": ["--env-file=.env", "dist/stdio.js"]
1144
+ }
1145
+ }
1146
+ }
1147
+ ```
1095
1148
 
1096
- ---
1149
+ Cursor auto-discovers `.cursor/mcp.json`. After saving, restart Cursor or reload the window. The sweagent tools appear in the Cursor chat tool list.
1097
1150
 
1098
- ### Tools
1151
+ ### Setup with VS Code (GitHub Copilot)
1099
1152
 
1100
- **defineTool(config)** — Define a type-safe tool with Zod schema and handler.
1153
+ Create `.vscode/mcp.json` in your project root:
1101
1154
 
1102
- ```typescript
1103
- import { defineTool } from 'sweagent';
1104
- import { z } from 'zod';
1155
+ **Option A -- Global install:**
1105
1156
 
1106
- const tool = defineTool({
1107
- name: 'my_tool',
1108
- description: 'What the tool does',
1109
- input: z.object({ key: z.string() }),
1110
- handler: async (parsed, context) => ({ result: parsed.key }),
1111
- });
1157
+ ```json
1158
+ {
1159
+ "servers": {
1160
+ "sweagent": {
1161
+ "command": "sweagent",
1162
+ "env": {
1163
+ "OPENAI_API_KEY": "your-openai-api-key"
1164
+ }
1165
+ }
1166
+ }
1167
+ }
1112
1168
  ```
1113
1169
 
1114
- **createToolSet(tools)** — Build a record of tools for the agent (key = tool name).
1170
+ **Option B -- npx:**
1115
1171
 
1116
- **getTool(toolSet, name)** / **getTools(toolSet)** — Look up one or all tools.
1117
-
1118
- **executeTool(tool, input, options)** — Run a single tool with input.
1119
-
1120
- **executeToolByName(toolSet, name, input, options)** — Run by name; throws if tool missing.
1172
+ ```json
1173
+ {
1174
+ "servers": {
1175
+ "sweagent": {
1176
+ "command": "npx",
1177
+ "args": ["-y", "sweagent"],
1178
+ "env": {
1179
+ "OPENAI_API_KEY": "your-openai-api-key"
1180
+ }
1181
+ }
1182
+ }
1183
+ }
1184
+ ```
1121
1185
 
1122
- **zodToJsonSchema(schema)** — Convert a Zod schema to JSON Schema (e.g. for MCP).
1186
+ VS Code discovers MCP servers from `.vscode/mcp.json` automatically. You can also configure servers globally via **MCP: Open User Configuration** in the Command Palette. After saving, open the Copilot chat panel -- the sweagent tools are available to the agent.
1123
1187
 
1124
- ---
1188
+ ### Setup with Windsurf
1125
1189
 
1126
- ### Agents
1190
+ Edit (or create) the Windsurf MCP config file at `~/.codeium/windsurf/mcp_config.json`:
1127
1191
 
1128
- **runAgent(config)** — Run the agent loop until the model returns no tool calls or max iterations is reached.
1192
+ **Option A -- Global install:**
1129
1193
 
1130
- ```typescript
1131
- import { runAgent } from 'sweagent';
1194
+ ```json
1195
+ {
1196
+ "mcpServers": {
1197
+ "sweagent": {
1198
+ "command": "sweagent",
1199
+ "env": {
1200
+ "OPENAI_API_KEY": "your-openai-api-key"
1201
+ }
1202
+ }
1203
+ }
1204
+ }
1205
+ ```
1132
1206
 
1133
- const result = await runAgent({
1134
- model,
1135
- tools: createToolSet({ ... }),
1136
- systemPrompt: string,
1137
- input: string,
1138
- maxIterations?: number, // default 10
1139
- onStep?: (step: AgentStep) => void,
1140
- });
1207
+ **Option B -- npx:**
1141
1208
 
1142
- // result: { output, steps, totalUsage, messages }
1209
+ ```json
1210
+ {
1211
+ "mcpServers": {
1212
+ "sweagent": {
1213
+ "command": "npx",
1214
+ "args": ["-y", "sweagent"],
1215
+ "env": {
1216
+ "OPENAI_API_KEY": "your-openai-api-key"
1217
+ }
1218
+ }
1219
+ }
1220
+ }
1143
1221
  ```
1144
1222
 
1145
- ---
1223
+ Restart Windsurf after saving. The sweagent tools appear in the Cascade chat.
1146
1224
 
1147
- ### Subagents
1225
+ ### Setup with Claude Desktop
1148
1226
 
1149
- **defineSubagent(config)** — Define a subagent (name must be kebab-case).
1227
+ Edit the Claude Desktop config file:
1150
1228
 
1151
- ```typescript
1152
- import { defineSubagent } from 'sweagent';
1229
+ - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
1230
+ - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
1153
1231
 
1154
- const def = defineSubagent({
1155
- name: 'my-subagent',
1156
- description: 'What this subagent does',
1157
- systemPrompt: '...',
1158
- tools?: Record<string, Tool>,
1159
- model?: ModelConfig,
1160
- maxIterations?: number,
1161
- disallowedTools?: string[],
1162
- onStep?: (step) => void,
1163
- });
1232
+ **Option A -- Global install:**
1233
+
1234
+ ```json
1235
+ {
1236
+ "mcpServers": {
1237
+ "sweagent": {
1238
+ "command": "sweagent",
1239
+ "env": {
1240
+ "OPENAI_API_KEY": "your-openai-api-key"
1241
+ }
1242
+ }
1243
+ }
1244
+ }
1164
1245
  ```
1165
1246
 
1166
- **runSubagent(definition, input, options)** — Run the subagent in isolation.
1247
+ **Option B -- npx:**
1167
1248
 
1168
- **createSubagentTool(definition, options)** — Expose one subagent as a tool.
1249
+ ```json
1250
+ {
1251
+ "mcpServers": {
1252
+ "sweagent": {
1253
+ "command": "npx",
1254
+ "args": ["-y", "sweagent"],
1255
+ "env": {
1256
+ "OPENAI_API_KEY": "your-openai-api-key"
1257
+ }
1258
+ }
1259
+ }
1260
+ }
1261
+ ```
1169
1262
 
1170
- **createSubagentToolSet(definitions, options)** — Build a record of subagent tools (`subagent_<name>`).
1263
+ Restart Claude Desktop after saving. The sweagent tools appear in the tool list (hammer icon) in a new conversation.
1171
1264
 
1172
- ---
1265
+ ### Available Tools
1173
1266
 
1174
- ### Planning
1267
+ All 13 domain agents are exposed as MCP tools:
1175
1268
 
1176
- **runPlanningAgent(config)** — One-shot mode: single input, auto-advances through all stages, returns plan markdown.
1269
+ | Tool | Description |
1270
+ | --------------------- | ----------------------------------------------------------------------------------------------------- |
1271
+ | `plan` | Generate a full software plan (discovery, requirements, design, synthesis) from a project description |
1272
+ | `gather_requirements` | Extract structured requirements (actors, flows, stories, modules) from a project description |
1273
+ | `design_data_model` | Design a database schema (MongoDB or PostgreSQL) with entities, relations, and indexes |
1274
+ | `design_api` | Design REST or GraphQL API contracts (endpoints, request/response schemas) from requirements |
1275
+ | `design_auth` | Design authentication and authorization strategy (providers, roles, permissions, flows) |
1276
+ | `architect_backend` | Design backend architecture (folder structure, services, middleware, deployment) |
1277
+ | `architect_frontend` | Design frontend architecture (components, state management, routing, styling) |
1278
+ | `build_express` | Generate Express.js REST API configuration and boilerplate from an API design |
1279
+ | `build_apollo` | Generate Apollo GraphQL subgraph configuration and resolvers from an API design |
1280
+ | `build_react` | Generate React + Vite application configuration and components from a GraphQL schema |
1281
+ | `build_nextjs` | Generate Next.js App Router configuration and pages from requirements |
1282
+ | `plan_execution` | Create a phased execution plan with edge-case analysis and testing strategy |
1283
+ | `hello_world` | Test agent that greets users -- use to verify the MCP server is working |
1177
1284
 
1178
- ```typescript
1179
- import { runPlanningAgent } from 'sweagent';
1285
+ ### Tool Input Parameters
1180
1286
 
1181
- const result = await runPlanningAgent({
1182
- input: string,
1183
- model?: ModelConfig,
1184
- maxIterations?: number,
1185
- onStep?: (step: AgentStep) => void,
1186
- logger?: Logger,
1187
- });
1188
- // result: AgentResult { output, steps, totalUsage, messages }
1189
- ```
1287
+ Every tool accepts the same input shape:
1190
1288
 
1191
- **runPlanningWithResult(config)** — Runs the planning agent then validates the output with an LLM judge.
1289
+ | Parameter | Type | Required | Description |
1290
+ | ------------- | ------------------------------------- | -------- | -------------------------------------------------------------------------------------- |
1291
+ | `input` | `string` | Yes | Natural language description of what to build or design |
1292
+ | `provider` | `"openai" \| "anthropic" \| "google"` | No | LLM provider (defaults to `openai`) |
1293
+ | `model` | `string` | No | Model name, e.g. `gpt-4o-mini`, `claude-sonnet-4-20250514` (defaults to `gpt-4o-mini`) |
1294
+ | `temperature` | `number` (0--1) | No | Sampling temperature |
1192
1295
 
1193
- ```typescript
1194
- import { runPlanningWithResult } from 'sweagent';
1296
+ ### Verify the Server
1195
1297
 
1196
- const result = await runPlanningWithResult({
1197
- input: string,
1198
- model?: ModelConfig,
1199
- logger?: Logger,
1200
- });
1201
- // result: { planning: boolean, plan: string }
1202
- ```
1298
+ After configuring your IDE, verify the connection by asking the chat agent:
1203
1299
 
1204
- **processPlanningChat(userMessage, context, config)** — Multi-turn chat mode. Pass `null` context on the first turn.
1300
+ > Use the hello_world tool to verify the sweagent MCP server is working.
1205
1301
 
1206
- ```typescript
1207
- import { processPlanningChat } from 'sweagent';
1302
+ If the server is running correctly, the agent will call the `hello_world` tool and return a greeting.
1208
1303
 
1209
- const result = await processPlanningChat(userMessage, context, {
1210
- model?: ModelConfig,
1211
- maxIterations?: number,
1212
- onStep?: (step: AgentStep) => void,
1213
- logger?: Logger,
1214
- });
1215
- // result: PlanChatTurnResult { message, context, pendingQuestions, planMarkdown }
1216
- ```
1304
+ ### Using Multiple Providers
1217
1305
 
1218
- **validatePlanForCodingAgent(planMarkdown, model, logger)** — LLM-based validation. Returns `{ valid: boolean, feedback?: string }`.
1306
+ Pass `provider` and `model` to any tool call to override the default (OpenAI gpt-4o-mini). Make sure the corresponding API key is set in the `env` block of your MCP config:
1219
1307
 
1220
- **assemblePlan(projectName, sections)** — Assemble `PlanSections` into a single markdown string.
1308
+ ```json
1309
+ {
1310
+ "mcpServers": {
1311
+ "sweagent": {
1312
+ "command": "npx",
1313
+ "args": ["-y", "sweagent"],
1314
+ "env": {
1315
+ "OPENAI_API_KEY": "your-openai-api-key",
1316
+ "ANTHROPIC_API_KEY": "your-anthropic-api-key",
1317
+ "GOOGLE_GENERATIVE_AI_API_KEY": "your-google-api-key"
1318
+ }
1319
+ }
1320
+ }
1321
+ }
1322
+ ```
1221
1323
 
1222
- **writePlanToFile(markdown, outputPath)** — Write plan markdown to a file.
1324
+ Then tell the agent which provider to use:
1223
1325
 
1224
- **PlanningContextBuilder** — Fluent builder for `PlanningContext`:
1326
+ > Use the plan tool with provider "anthropic" and model "claude-sonnet-4-20250514" to plan a task manager app with teams, Kanban boards, and time tracking.
1225
1327
 
1226
- ```typescript
1227
- import { createPlanningContextBuilder } from 'sweagent';
1328
+ ### Troubleshooting MCP
1228
1329
 
1229
- const context = createPlanningContextBuilder()
1230
- .withStage('requirements')
1231
- .withProjectDescription('Task manager app')
1232
- .withSections({ overview: '## Overview\n...' })
1233
- .build();
1234
- ```
1235
-
1236
- ---
1330
+ **Server not appearing in tool list** -- Restart your IDE after saving the config file. Check that the config file is in the correct location for your IDE.
1237
1331
 
1238
- ### MCP
1332
+ **API key errors** -- Make sure the API key is set in the `env` block of your MCP config, not just in a `.env` file (unless you are using the `--env-file` flag with the node command).
1239
1333
 
1240
- **BaseMcpClient** — Base class for MCP clients. Lazy connection, `callTool(name, args)` for invocation.
1334
+ **npx timeout or failure** -- Run `npx sweagent` manually in a terminal to check for errors. Make sure Node.js >= 18 is installed.
1241
1335
 
1242
- **BaseMcpClient.resolveConfig(options, resolveOpts)** — Build config from options and env (e.g. `MCP_URL`, `MCP_COMMAND`, `MCP_ARGS`).
1336
+ **Tool returns an error** -- The MCP server catches errors and returns them as text. Check that the `input` parameter contains a meaningful project description, not an empty string.
1243
1337
 
1244
1338
  ---
1245
1339
 
1246
- ### Errors
1340
+ ## Architecture
1247
1341
 
1248
- | Class | When |
1249
- | ------------------- | ------------------------------------------------ |
1250
- | **LibraryError** | Base; all others extend it. |
1251
- | **ModelError** | Model creation or invoke failed. |
1252
- | **ToolError** | Tool not found or tool execution failed. |
1253
- | **ValidationError** | Zod validation failed. |
1254
- | **AgentError** | Agent reached max iterations without completing. |
1255
- | **SubagentError** | Subagent config or run failed. |
1342
+ ### System overview
1256
1343
 
1257
- All accept an optional `cause` for chaining.
1344
+ ```mermaid
1345
+ graph TB
1346
+ subgraph Client[Client Application]
1347
+ App["Your App / Cursor / Claude Code / Codex"]
1348
+ end
1258
1349
 
1259
- ---
1350
+ subgraph DomainAgents[Domain Agent Modules]
1351
+ Planning["Planning"]
1352
+ ReqGatherer["Requirement Gatherer"]
1353
+ DataModeler["Data Modeler"]
1354
+ ApiDesigner["API Designer"]
1355
+ AuthDesigner["Auth Designer"]
1356
+ BackendArch["Backend Architect"]
1357
+ ExpressBuilder["Express Builder"]
1358
+ ApolloBuilder["Apollo Builder"]
1359
+ FrontendArch["Frontend Architect"]
1360
+ ReactBuilder["React Builder"]
1361
+ NextjsBuilder["Next.js Builder"]
1362
+ ExecPlanner["Execution Planner"]
1363
+ end
1260
1364
 
1261
- ## Domain Agent Modules
1365
+ subgraph Framework[Shared Framework]
1366
+ Models["Model Abstraction"]
1367
+ ToolFW["Tool Framework"]
1368
+ AgentLoop["Agent Loop"]
1369
+ SubAgentOrch["Sub-Agent Orchestration"]
1370
+ MCP["MCP Protocol"]
1371
+ end
1262
1372
 
1263
- 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.
1373
+ subgraph Providers[AI Providers]
1374
+ OpenAI["OpenAI"]
1375
+ Anthropic["Anthropic"]
1376
+ Google["Google"]
1377
+ end
1264
1378
 
1265
- ### Planning
1379
+ App --> DomainAgents
1380
+ DomainAgents --> Framework
1381
+ Framework --> Providers
1382
+ ```
1266
1383
 
1267
- The primary module for powering AI coding agents. Generates implementation-ready markdown plans from natural-language project descriptions.
1384
+ ### Domain agent pipeline flow
1268
1385
 
1269
- | Attribute | Detail |
1270
- | ----------------- | ------------------------------------------------------------------------------------------------------------ |
1271
- | **Stages** | Discovery, Requirements (4 LLM calls), Design (2 LLM calls), Synthesis |
1272
- | **Sub-Agents** | -- |
1273
- | **Tools** | -- (pipeline stages, not tool-based) |
1274
- | **Output Format** | Markdown plan (11 sections) |
1275
- | **Validation** | LLM judge checks completeness and actionability |
1276
- | **Modes** | One-shot (`runPlanningAgent`), validated (`runPlanningWithResult`), interactive chat (`processPlanningChat`) |
1386
+ Each domain agent follows a structured pipeline. The Planning Agent is representative:
1277
1387
 
1278
- **Output sections:** Overview, Tech Stack, Feature Decisions, Data Models, Pages and Routes, Authentication Flow, API Routes, Implementation Details, Execution Plan, Edge Cases, Testing Checklist.
1388
+ ```mermaid
1389
+ flowchart LR
1390
+ Input["User Requirement"] --> Discovery["Discovery Stage"]
1391
+ Discovery --> Requirements["Requirements Stage"]
1392
+ Requirements --> Design["Design Stage"]
1393
+ Design --> Synthesis["Synthesis Stage"]
1394
+ Synthesis --> Plan["Structured Output"]
1395
+ Plan --> Validate["LLM Validator"]
1396
+ Validate --> Output["Validated Result"]
1397
+ ```
1279
1398
 
1280
- ```typescript
1281
- import { runPlanningWithResult } from 'sweagent';
1399
+ ### Orchestrator with sub-agents
1282
1400
 
1283
- const { planning, plan } = await runPlanningWithResult({
1284
- input: 'E-commerce: users, orders, products. Admins manage products.',
1285
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1286
- });
1287
- // planning: boolean -- did the plan pass validation?
1288
- // plan: string -- full markdown blueprint
1289
- ```
1401
+ Domain agents like Data Modeler and React Builder delegate to specialized sub-agents:
1290
1402
 
1291
- See [Planning Pipeline](#planning-pipeline) for stage-by-stage details.
1403
+ ```mermaid
1404
+ sequenceDiagram
1405
+ participant User
1406
+ participant Orchestrator
1407
+ participant Model
1408
+ participant Tools
1409
+ participant SubAgent1 as entity-analyzer
1410
+ participant SubAgent2 as schema-refiner
1292
1411
 
1293
- ---
1412
+ User->>Orchestrator: Natural-language requirement
1413
+ Orchestrator->>Model: Messages + Domain Tools
1414
+ Model-->>Orchestrator: Tool call design_database
1415
+ Orchestrator->>Tools: Execute design_database
1416
+ Tools-->>Orchestrator: Initial schema
1417
+ Orchestrator->>SubAgent1: Analyze entities and relationships
1418
+ SubAgent1-->>Orchestrator: Structured entity analysis
1419
+ Orchestrator->>SubAgent2: Refine and validate schema
1420
+ SubAgent2-->>Orchestrator: Validated schema
1421
+ Orchestrator->>Model: Compile final output
1422
+ Model-->>Orchestrator: Final result
1423
+ Orchestrator-->>User: Production-grade schema
1424
+ ```
1294
1425
 
1295
- ### Requirement Gatherer
1426
+ ### Agent execution loop
1296
1427
 
1297
- Produces structured JSON requirements -- not prose. Unlike the Planning module (markdown output), the Requirement Gatherer extracts typed data that downstream systems can consume programmatically.
1428
+ ```mermaid
1429
+ sequenceDiagram
1430
+ participant User
1431
+ participant Agent
1432
+ participant Model
1433
+ participant Tools
1298
1434
 
1299
- | Attribute | Detail |
1300
- | ----------------- | ------------------------------------------------------------------------------------- |
1301
- | **Stages** | Discovery, Requirements, Design, Synthesis |
1302
- | **Sub-Agents** | -- |
1303
- | **Tools** | Stage-specific tools |
1304
- | **Output Format** | Structured JSON |
1305
- | **Schemas** | Actors, User Flows, User Stories, Modules, Database Design, API Design |
1306
- | **Modes** | One-shot (`runRequirementGathererAgent`), interactive chat (`processRequirementChat`) |
1435
+ User->>Agent: Input + Tools + System Prompt
1436
+ loop Until Complete or Max Iterations
1437
+ Agent->>Model: Messages + Tool Schemas
1438
+ Model-->>Agent: Response (Text or Tool Calls)
1439
+ alt Tool Calls Present
1440
+ Agent->>Tools: Execute Tool Calls
1441
+ Tools-->>Agent: Tool Results
1442
+ Agent->>Agent: Append Results to Messages
1443
+ else Final Answer
1444
+ Agent-->>User: Output + Steps + Usage
1445
+ end
1446
+ end
1447
+ ```
1307
1448
 
1308
- **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).
1449
+ ### Engineering Deep Dive
1309
1450
 
1310
- ```typescript
1311
- import { runRequirementGathererAgent } from 'sweagent';
1451
+ #### The problem: long-running coding agents
1312
1452
 
1313
- const result = await runRequirementGathererAgent({
1314
- input: 'Project management tool with teams and Kanban boards',
1315
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1316
- maxIterations: 15,
1317
- });
1318
- // result.output: structured JSON with actors, flows, stories, modules
1319
- ```
1453
+ 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.
1320
1454
 
1321
- ---
1455
+ #### Incremental progress pattern
1322
1456
 
1323
- ### DB Designer
1457
+ 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.
1324
1458
 
1325
- An orchestrator agent that delegates to specialized sub-agents for entity analysis and schema refinement. Produces MongoDB-style project schemas with modules, fields, relationships, indexes, and validation rules.
1459
+ #### Feature list approach
1326
1460
 
1327
- | Attribute | Detail |
1328
- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
1329
- | **Pattern** | Orchestrator with sub-agents |
1330
- | **Sub-Agents** | `entity-analyzer` (extracts entities and relationships), `schema-refiner` (normalizes and validates schemas) |
1331
- | **Tools** | `design_database` (text requirements to schema), `design_database_pro` (structured requirements to schema), `redesign_database` (modify existing schemas), `validate_schema` (schema validation) |
1332
- | **Output Format** | MongoDB schema JSON (modules, fields, relationships) |
1461
+ 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.
1333
1462
 
1334
- ```typescript
1335
- import { runDbDesignerAgent } from 'sweagent';
1463
+ #### Clean state principle
1336
1464
 
1337
- const result = await runDbDesignerAgent({
1338
- input: 'E-commerce: users, orders, products. Admins manage products.',
1339
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1340
- maxIterations: 15,
1341
- });
1342
- // result.output: MongoDB schema with modules, fields, relationships
1343
- ```
1465
+ 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.
1344
1466
 
1345
- ---
1467
+ ### Provider adapter pattern
1346
1468
 
1347
- ### React Builder
1469
+ 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.
1348
1470
 
1349
- An orchestrator agent that generates complete frontend application configuration from a GraphQL schema. Uses a `graphql-analyzer` sub-agent to parse schema structure and a `config-validator` to verify the output against frontend config schemas.
1471
+ ### Tool execution safety
1350
1472
 
1351
- | Attribute | Detail |
1352
- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
1353
- | **Pattern** | Orchestrator with sub-agents |
1354
- | **Sub-Agents** | `graphql-analyzer` (parses GraphQL schema structure), `config-validator` (validates frontend config output) |
1355
- | **Tools** | `generate_frontend` (GraphQL to frontend config), `generate_feature_breakdown` (module/operation breakdown), `validate_frontend_config` (config validation) |
1356
- | **Output Format** | React app config JSON (app, modules, pages, fields, API hooks, branding) |
1357
- | **Schemas** | App config, User config, Page config, Field config, Branding |
1473
+ 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.
1358
1474
 
1359
- ```typescript
1360
- import { runReactBuilderAgent } from 'sweagent';
1475
+ ### Error hierarchy
1361
1476
 
1362
- const result = await runReactBuilderAgent({
1363
- input: 'GraphQL schema: type User { id: ID! name: String! } type Task { ... }',
1364
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1365
- maxIterations: 15,
1366
- });
1367
- // result.output: frontend config JSON with pages, fields, hooks, branding
1368
- ```
1477
+ | Class | When |
1478
+ | ------------------- | ------------------------------------------------ |
1479
+ | **LibraryError** | Base; all others extend it. |
1480
+ | **ModelError** | Model creation or invoke failed. |
1481
+ | **ToolError** | Tool not found or tool execution failed. |
1482
+ | **ValidationError** | Zod validation failed. |
1483
+ | **AgentError** | Agent reached max iterations without completing. |
1484
+ | **SubagentError** | Subagent config or run failed. |
1485
+
1486
+ All accept an optional `cause` for chaining.
1369
1487
 
1370
1488
  ---
1371
1489
 
1372
- ### Data Modeler
1490
+ ## API Reference
1373
1491
 
1374
- Designs data models for MongoDB or PostgreSQL with entities, fields, indexes, and relationships. Three sub-agents handle entity analysis, relationship mapping, and schema refinement.
1492
+ All public APIs are exported from the main package: `import { ... } from 'sweagent'`.
1375
1493
 
1376
- | Attribute | Detail |
1377
- | ----------------- | ---------------------------------------------------------------------------- |
1378
- | **Pattern** | Orchestrator with sub-agents |
1379
- | **Sub-Agents** | `entity-analyzer`, `relationship-mapper`, `schema-refiner` |
1380
- | **Tools** | `design_schema`, `design_schema_pro`, `refine_schema`, `validate_data_model` |
1381
- | **Output Format** | Data model JSON (entities, fields, indexes, relationships) |
1382
- | **Databases** | MongoDB, PostgreSQL |
1494
+ ### Models
1495
+
1496
+ **createModel(config)** -- Create a model instance.
1383
1497
 
1384
1498
  ```typescript
1385
- import { runDataModelerAgent } from 'sweagent';
1499
+ import { createModel } from 'sweagent';
1386
1500
 
1387
- const result = await runDataModelerAgent({
1388
- input: 'SaaS platform with organizations, users, projects, and billing',
1389
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1390
- maxIterations: 15,
1501
+ const model = createModel({
1502
+ provider: 'openai' | 'anthropic' | 'google',
1503
+ model: string, // e.g. 'gpt-4o', 'claude-sonnet-4-20250514'
1504
+ apiKey?: string, // Uses env var by default
1505
+ temperature?: number,
1506
+ maxOutputTokens?: number,
1507
+ baseUrl?: string,
1391
1508
  });
1392
- ```
1393
-
1394
- ---
1395
-
1396
- ### API Designer
1397
1509
 
1398
- Designs REST and/or GraphQL APIs from data models. Produces endpoint definitions with request/response contracts and auth requirements.
1510
+ const response = await model.invoke(messages, { tools });
1511
+ // response: { text, toolCalls, usage, finishReason }
1512
+ ```
1399
1513
 
1400
- | Attribute | Detail |
1401
- | ----------------- | ------------------------------------------------------------------------------------------------------- |
1402
- | **Pattern** | Orchestrator with sub-agents |
1403
- | **Sub-Agents** | `endpoint-analyzer` (derives endpoints from data model), `contract-designer` (designs request/response) |
1404
- | **Tools** | `design_api`, `design_api_pro`, `validate_api` |
1405
- | **Output Format** | API design JSON (REST endpoints and/or GraphQL operations) |
1514
+ **Supported models (examples):**
1406
1515
 
1407
- ```typescript
1408
- import { runApiDesignerAgent } from 'sweagent';
1516
+ | Provider | Models |
1517
+ | --------- | ---------------------------------------------------- |
1518
+ | OpenAI | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` |
1519
+ | Anthropic | `claude-sonnet-4-20250514`, `claude-3-opus-20240229` |
1520
+ | Google | `gemini-1.5-pro`, `gemini-1.5-flash` |
1409
1521
 
1410
- const result = await runApiDesignerAgent({
1411
- input: 'Design REST API for task manager with users, projects, tasks',
1412
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1413
- maxIterations: 15,
1414
- });
1415
- ```
1522
+ **Vision:** `model.generateVision(prompt, images, options)` for image inputs.
1416
1523
 
1417
1524
  ---
1418
1525
 
1419
- ### Auth Designer
1420
-
1421
- Designs authentication and authorization systems with strategies, flows, middleware, roles, and security policies.
1526
+ ### Tools
1422
1527
 
1423
- | Attribute | Detail |
1424
- | ----------------- | ------------------------------------------------------------------------------------------ |
1425
- | **Pattern** | Orchestrator with sub-agents |
1426
- | **Sub-Agents** | `security-analyzer` (analyzes security requirements), `flow-designer` (designs auth flows) |
1427
- | **Tools** | `design_auth`, `validate_auth` |
1428
- | **Output Format** | Auth design JSON (strategy, flows, middleware, roles, policies) |
1528
+ **defineTool(config)** -- Define a type-safe tool with Zod schema and handler.
1429
1529
 
1430
1530
  ```typescript
1431
- import { runAuthDesignerAgent } from 'sweagent';
1531
+ import { defineTool } from 'sweagent';
1532
+ import { z } from 'zod';
1432
1533
 
1433
- const result = await runAuthDesignerAgent({
1434
- input: 'JWT auth with email/password, Google OAuth, admin and member roles',
1435
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1436
- maxIterations: 15,
1534
+ const tool = defineTool({
1535
+ name: 'my_tool',
1536
+ description: 'What the tool does',
1537
+ input: z.object({ key: z.string() }),
1538
+ handler: async (parsed, context) => ({ result: parsed.key }),
1437
1539
  });
1438
1540
  ```
1439
1541
 
1440
- ---
1441
-
1442
- ### Frontend Architect
1542
+ **createToolSet(tools)** -- Build a record of tools for the agent (key = tool name).
1443
1543
 
1444
- Plans frontend architecture including pages, components, routing, and state management. Routes to React Builder or Next.js Builder based on framework selection.
1544
+ **getTool(toolSet, name)** / **getTools(toolSet)** -- Look up one or all tools.
1445
1545
 
1446
- | Attribute | Detail |
1447
- | ----------------- | ------------------------------------------------------------------- |
1448
- | **Pattern** | Orchestrator with sub-agents |
1449
- | **Sub-Agents** | `page-planner`, `component-analyzer`, `framework-selector` |
1450
- | **Output Format** | Frontend design JSON (pages, components, state management, routing) |
1451
- | **Frameworks** | React + Vite, Next.js |
1546
+ **executeTool(tool, input, options)** -- Run a single tool with input.
1452
1547
 
1453
- ```typescript
1454
- import { runFrontendArchitectAgent } from 'sweagent';
1548
+ **executeToolByName(toolSet, name, input, options)** -- Run by name; throws if tool missing.
1455
1549
 
1456
- const result = await runFrontendArchitectAgent({
1457
- input: 'Dashboard with analytics, settings, and user management',
1458
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1459
- maxIterations: 15,
1460
- });
1461
- ```
1550
+ **zodToJsonSchema(schema)** -- Convert a Zod schema to JSON Schema (e.g. for MCP).
1462
1551
 
1463
1552
  ---
1464
1553
 
1465
- ### Backend Architect
1466
-
1467
- Plans backend architecture including framework selection, services, middleware, routes, and folder structure. Routes to Express Builder or Apollo Builder.
1554
+ ### Agents
1468
1555
 
1469
- | Attribute | Detail |
1470
- | ----------------- | ------------------------------------------------------------------------------- |
1471
- | **Pattern** | Orchestrator with sub-agents |
1472
- | **Sub-Agents** | `framework-selector`, `service-planner` |
1473
- | **Tools** | `design_backend`, `validate_backend` |
1474
- | **Output Format** | Backend design JSON (framework, services, middleware, routes, folder structure) |
1475
- | **Frameworks** | Express, Apollo, or both |
1556
+ **runAgent(config)** -- Run the agent loop until the model returns no tool calls or max iterations is reached.
1476
1557
 
1477
1558
  ```typescript
1478
- import { runBackendArchitectAgent } from 'sweagent';
1559
+ import { runAgent } from 'sweagent';
1479
1560
 
1480
- const result = await runBackendArchitectAgent({
1481
- input: 'REST API with user auth, CRUD operations, and file uploads',
1482
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1483
- maxIterations: 15,
1561
+ const result = await runAgent({
1562
+ model,
1563
+ tools: createToolSet({ ... }),
1564
+ systemPrompt: string,
1565
+ input: string,
1566
+ maxIterations?: number, // default 10
1567
+ onStep?: (step: AgentStep) => void,
1484
1568
  });
1569
+
1570
+ // result: { output, steps, totalUsage, messages }
1485
1571
  ```
1486
1572
 
1487
1573
  ---
1488
1574
 
1489
- ### Express Builder
1490
-
1491
- Generates Express.js REST API configuration with routers, models, middleware, and environment variables.
1575
+ ### Subagents
1492
1576
 
1493
- | Attribute | Detail |
1494
- | ----------------- | ----------------------------------------------------------- |
1495
- | **Pattern** | Orchestrator with sub-agents |
1496
- | **Sub-Agents** | `route-generator`, `middleware-configurator` |
1497
- | **Tools** | `generate_express`, `scaffold_express`, `validate_express` |
1498
- | **Output Format** | Express config JSON (routers, models, middleware, env vars) |
1577
+ **defineSubagent(config)** -- Define a subagent (name must be kebab-case).
1499
1578
 
1500
1579
  ```typescript
1501
- import { runExpressBuilderAgent } from 'sweagent';
1580
+ import { defineSubagent } from 'sweagent';
1502
1581
 
1503
- const result = await runExpressBuilderAgent({
1504
- input: 'Express API for e-commerce with products, orders, and user auth',
1505
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1506
- maxIterations: 15,
1582
+ const def = defineSubagent({
1583
+ name: 'my-subagent',
1584
+ description: 'What this subagent does',
1585
+ systemPrompt: '...',
1586
+ tools?: Record<string, Tool>,
1587
+ model?: ModelConfig,
1588
+ maxIterations?: number,
1589
+ disallowedTools?: string[],
1590
+ onStep?: (step) => void,
1507
1591
  });
1508
1592
  ```
1509
1593
 
1510
- ---
1594
+ **runSubagent(definition, input, options)** -- Run the subagent in isolation.
1511
1595
 
1512
- ### Apollo Builder
1596
+ **createSubagentTool(definition, options)** -- Expose one subagent as a tool.
1513
1597
 
1514
- Generates Apollo GraphQL subgraph configuration with modules, types, resolvers, datasources, and Federation v2 support.
1598
+ **createSubagentToolSet(definitions, options)** -- Build a record of subagent tools (`subagent_<name>`).
1515
1599
 
1516
- | Attribute | Detail |
1517
- | ----------------- | --------------------------------------------------------------------- |
1518
- | **Pattern** | Orchestrator with sub-agents |
1519
- | **Sub-Agents** | `schema-generator`, `resolver-planner` |
1520
- | **Tools** | `generate_subgraph`, `scaffold_subgraph`, `validate_subgraph` |
1521
- | **Output Format** | Apollo subgraph config JSON (modules, types, operations, datasources) |
1600
+ ---
1601
+
1602
+ ### Planning
1603
+
1604
+ **runPlanningAgent(config)** -- One-shot mode: single input, auto-advances through all stages, returns plan markdown.
1522
1605
 
1523
1606
  ```typescript
1524
- import { runApolloBuilderAgent } from 'sweagent';
1607
+ import { runPlanningAgent } from 'sweagent';
1525
1608
 
1526
- const result = await runApolloBuilderAgent({
1527
- input: 'Apollo subgraph for task manager with users, projects, tasks',
1528
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1529
- maxIterations: 15,
1609
+ const result = await runPlanningAgent({
1610
+ input: string,
1611
+ model?: ModelConfig,
1612
+ maxIterations?: number,
1613
+ onStep?: (step: AgentStep) => void,
1614
+ logger?: Logger,
1530
1615
  });
1616
+ // result: AgentResult { output, steps, totalUsage, messages }
1531
1617
  ```
1532
1618
 
1533
- ---
1619
+ **processPlanningChat(userMessage, context, config)** -- Multi-turn chat mode. Pass `null` context on the first turn.
1534
1620
 
1535
- ### Next.js Builder
1621
+ ```typescript
1622
+ import { processPlanningChat } from 'sweagent';
1536
1623
 
1537
- Generates Next.js App Router configuration with pages, layouts, API routes, server actions, and middleware.
1624
+ const result = await processPlanningChat(userMessage, context, {
1625
+ model?: ModelConfig,
1626
+ maxIterations?: number,
1627
+ onStep?: (step: AgentStep) => void,
1628
+ logger?: Logger,
1629
+ });
1630
+ // result: PlanChatTurnResult { message, context, pendingQuestions, planMarkdown }
1631
+ ```
1538
1632
 
1539
- | Attribute | Detail |
1540
- | ----------------- | ---------------------------------------------------------------------------- |
1541
- | **Pattern** | Orchestrator with sub-agents |
1542
- | **Sub-Agents** | `route-planner`, `api-route-generator` |
1543
- | **Tools** | `generate_nextjs`, `validate_nextjs` |
1544
- | **Output Format** | Next.js config JSON (pages, layouts, API routes, server actions, middleware) |
1633
+ **runPlanningFromRequirements(config)** -- Convert requirement-gatherer output to a plan, skipping redundant stages.
1545
1634
 
1546
1635
  ```typescript
1547
- import { runNextjsBuilderAgent } from 'sweagent';
1636
+ import { runPlanningFromRequirements } from 'sweagent';
1548
1637
 
1549
- const result = await runNextjsBuilderAgent({
1550
- input: 'Next.js app for project management with teams and dashboards',
1551
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1552
- maxIterations: 15,
1638
+ const result = await runPlanningFromRequirements({
1639
+ requirement: FinalRequirement, // JSON from requirement-gatherer
1640
+ model?: ModelConfig,
1641
+ onStep?: (step: AgentStep) => void,
1642
+ logger?: Logger,
1553
1643
  });
1644
+ // result: AgentResult { output (plan markdown), steps, totalUsage, messages }
1554
1645
  ```
1555
1646
 
1556
- ---
1557
-
1558
- ### Execution Planner
1647
+ **assemblePlan(projectName, sections)** -- Assemble `PlanSections` into a single markdown string.
1559
1648
 
1560
- Creates phased implementation execution plans with edge case analysis and testing checklists.
1649
+ **writePlanToFile(markdown, outputPath)** -- Write plan markdown to a file.
1561
1650
 
1562
- | Attribute | Detail |
1563
- | ----------------- | --------------------------------------------------------------------------------------- |
1564
- | **Pattern** | Orchestrator with sub-agents |
1565
- | **Sub-Agents** | `edge-case-analyzer`, `testing-strategist` |
1566
- | **Tools** | `create_execution_plan`, `validate_execution_plan` |
1567
- | **Output Format** | Execution plan JSON (phases, edge cases, testing checklist, security/performance notes) |
1651
+ **PlanningContextBuilder** -- Fluent builder for `PlanningContext`:
1568
1652
 
1569
1653
  ```typescript
1570
- import { runExecutionPlannerAgent } from 'sweagent';
1654
+ import { createPlanningContextBuilder } from 'sweagent';
1571
1655
 
1572
- const result = await runExecutionPlannerAgent({
1573
- input: 'Create execution plan for the task manager project',
1574
- model: { provider: 'openai', model: 'gpt-4o-mini' },
1575
- maxIterations: 15,
1576
- });
1656
+ const context = createPlanningContextBuilder()
1657
+ .withStage('requirements')
1658
+ .withProjectDescription('Task manager app')
1659
+ .withSections({ overview: '## Overview\n...' })
1660
+ .build();
1577
1661
  ```
1578
1662
 
1579
1663
  ---
1580
1664
 
1581
- ### Hello World (Template)
1665
+ ### MCP
1582
1666
 
1583
- Minimal example module with a single greeting tool. Use as a starting point when building your own domain agent module.
1667
+ sweagent ships as a standalone **MCP server** that exposes all 13 domain agents as tools. See [MCP Server](#mcp-server) for IDE setup and tool reference.
1584
1668
 
1585
- ```typescript
1586
- import { createModel, runAgent, helloWorldTool } from 'sweagent';
1669
+ **BaseMcpClient** -- Base class for MCP clients. Lazy connection, `callTool(name, args)` for invocation.
1587
1670
 
1588
- const result = await runAgent({
1589
- model: createModel({ provider: 'openai', model: 'gpt-4o-mini' }),
1590
- tools: [helloWorldTool],
1591
- systemPrompt: 'You are helpful.',
1592
- input: 'Say hello',
1593
- });
1594
- ```
1671
+ **BaseMcpClient.resolveConfig(options, resolveOpts)** -- Build config from options and env (e.g. `MCP_URL`, `MCP_COMMAND`, `MCP_ARGS`).
1595
1672
 
1596
1673
  ---
1597
1674
 
1598
- ## Examples
1599
-
1600
- The [examples directory](./examples/README.md) contains runnable scripts organized by domain agent. Use the interactive launcher or run a file directly:
1601
-
1602
- ```bash
1603
- # Interactive launcher -- pick a domain agent, then an example
1604
- npm run example:interactive
1675
+ ### Errors
1605
1676
 
1606
- # Run a specific domain agent example
1607
- npm run example -- examples/planning/01-planning-agent.ts
1608
- npm run example -- examples/db-designer/01-db-designer-agent.ts
1609
- npm run example -- examples/react-builder/01-react-builder-agent.ts
1610
- ```
1677
+ | Class | When |
1678
+ | ------------------- | ------------------------------------------------ |
1679
+ | **LibraryError** | Base; all others extend it. |
1680
+ | **ModelError** | Model creation or invoke failed. |
1681
+ | **ToolError** | Tool not found or tool execution failed. |
1682
+ | **ValidationError** | Zod validation failed. |
1683
+ | **AgentError** | Agent reached max iterations without completing. |
1684
+ | **SubagentError** | Subagent config or run failed. |
1611
1685
 
1612
- | Domain Agent | Examples | What it produces |
1613
- | ------------------------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ |
1614
- | **Planning** | 01 Planning Agent | Implementation-ready markdown plan through 4-stage pipeline |
1615
- | **Requirement Gatherer** | 01 Requirement Gatherer Agent | Structured JSON requirements (actors, flows, stories, modules) |
1616
- | **Data Modeler** | 01 Data Modeler Agent | MongoDB/PostgreSQL data model with entities, fields, indexes |
1617
- | **DB Designer** | 01 DB Designer Agent | MongoDB schemas via `entity-analyzer` and `schema-refiner` sub-agents |
1618
- | **API Designer** | 01 API Designer Agent | REST/GraphQL API design with endpoints and contracts |
1619
- | **Auth Designer** | 01 Auth Designer Agent | Auth strategy, flows, middleware, roles, and policies |
1620
- | **Backend Architect** | 01 Backend Architect Agent | Backend architecture with framework selection and services |
1621
- | **Express Builder** | 01 Express Builder Agent | Express.js config with routers, models, and middleware |
1622
- | **Apollo Builder** | 01 Apollo Builder Agent | Apollo GraphQL subgraph config with types and resolvers |
1623
- | **Frontend Architect** | 01 Frontend Architect Agent | Frontend architecture with pages, components, and routing |
1624
- | **React Builder** | 01 React Builder Agent | Frontend config via `graphql-analyzer` and `config-validator` sub-agents |
1625
- | **Next.js Builder** | 01 Next.js Builder Agent | Next.js App Router config with pages, layouts, and API routes |
1626
- | **Execution Planner** | 01 Execution Planner Agent | Phased implementation plan with edge cases and testing checklist |
1627
- | **Core Framework** | 01 Basic Model, 02 All Providers, 03 Tool Calling, 04 Multi-Tool Agent, 05 Subagents | Models, tools, agent loop, sub-agent delegation |
1628
- | **Hello World** | 01 Hello World | Minimal agent with greeting tool (module template) |
1686
+ All accept an optional `cause` for chaining.
1629
1687
 
1630
1688
  ---
1631
1689
 
1632
- ## Configuration Reference
1690
+ ## Reference
1633
1691
 
1634
1692
  ### Environment variables
1635
1693
 
@@ -1644,21 +1702,14 @@ npm run example -- examples/react-builder/01-react-builder-agent.ts
1644
1702
  | `REQUIREMENT` | Project requirement for planning/requirement-gatherer examples |
1645
1703
  | `MAX_ITERATIONS` | Max agent iterations for examples |
1646
1704
 
1647
- ### ModelConfig
1648
-
1649
- `provider`, `model`, `apiKey?`, `temperature?`, `maxOutputTokens?`, `baseUrl?`
1705
+ ### Config types
1650
1706
 
1651
- ### AgentConfig
1707
+ - **ModelConfig** -- `provider`, `model`, `apiKey?`, `temperature?`, `maxOutputTokens?`, `baseUrl?`
1708
+ - **AgentConfig** -- `model`, `tools`, `systemPrompt`, `input`, `maxIterations?`, `onStep?`
1709
+ - **PlanningAgentConfig** -- `input`, `model?`, `maxIterations?`, `onStep?`, `logger?`
1710
+ - **PlanFromRequirementsConfig** -- `requirement`, `model?`, `onStep?`, `logger?`
1652
1711
 
1653
- `model`, `tools`, `systemPrompt`, `input`, `maxIterations?`, `onStep?`
1654
-
1655
- ### PlanningAgentConfig
1656
-
1657
- `input`, `model?`, `maxIterations?`, `onStep?`, `logger?`
1658
-
1659
- ---
1660
-
1661
- ## FAQ
1712
+ ### FAQ
1662
1713
 
1663
1714
  **Which AI provider should I use?**
1664
1715
  All work well. Choose by existing infrastructure and pricing. The API is the same regardless of provider.
@@ -1675,34 +1726,48 @@ Target is Node.js. For browsers, proxy API calls through your backend and keep k
1675
1726
  **How do I add a new provider?**
1676
1727
  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`.
1677
1728
 
1678
- ---
1679
-
1680
- ## Troubleshooting
1729
+ ### Troubleshooting
1681
1730
 
1682
- ### API key errors
1731
+ **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`.
1683
1732
 
1684
- - Ensure the key is set: `echo $OPENAI_API_KEY` (or the relevant env var).
1685
- - If using `.env`, load it: `tsx --env-file=.env your-script.ts` or `node --env-file=.env your-script.js`.
1733
+ **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.
1686
1734
 
1687
- ### Model not found
1735
+ **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.
1688
1736
 
1689
- - Use the exact model id for the provider (e.g. `gpt-4o-mini`, `claude-sonnet-4-20250514`).
1690
- - Confirm your account has access to that model.
1737
+ **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`).
1691
1738
 
1692
- ### Agent hits max iterations
1739
+ ---
1693
1740
 
1694
- - Increase `maxIterations` or simplify the task.
1695
- - Check that tools return clear, parseable results so the model can decide the next step.
1741
+ ## Examples
1696
1742
 
1697
- ### Tool not found
1743
+ The [examples directory](./examples/) contains runnable scripts organized by domain agent. Use the interactive launcher or run a file directly:
1698
1744
 
1699
- - 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`).
1745
+ ```bash
1746
+ # Interactive launcher -- pick a domain agent, then an example
1747
+ npm run example:interactive
1700
1748
 
1701
- ### Planning module returns `planning: false`
1749
+ # Run a specific domain agent example
1750
+ npm run example -- examples/planning/01-planning-agent.ts
1751
+ npm run example -- examples/data-modeler/01-data-modeler-agent.ts
1752
+ npm run example -- examples/react-builder/01-react-builder-agent.ts
1753
+ ```
1702
1754
 
1703
- - The LLM validator found missing sections. Check the `plan` string for gaps (no tech stack? no implementation order?).
1704
- - Try a more capable model (e.g. `gpt-4o` instead of `gpt-4o-mini`).
1705
- - Provide a more detailed project description as input.
1755
+ | Domain Agent | Examples | What it produces |
1756
+ | ------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------ |
1757
+ | **Planning** | 01 Planning Agent | Implementation-ready markdown plan through 4-stage pipeline |
1758
+ | **Requirement Gatherer** | 01 Requirement Gatherer Agent | Structured JSON requirements (actors, flows, stories, modules) |
1759
+ | **Data Modeler** | 01 Data Modeler Agent | MongoDB/PostgreSQL data model with entities, fields, indexes |
1760
+ | **API Designer** | 01 API Designer Agent | REST/GraphQL API design with endpoints and contracts |
1761
+ | **Auth Designer** | 01 Auth Designer Agent | Auth strategy, flows, middleware, roles, and policies |
1762
+ | **Backend Architect** | 01 Backend Architect Agent | Backend architecture with framework selection and services |
1763
+ | **Express Builder** | 01 Express Builder Agent | Express.js config with routers, models, and middleware |
1764
+ | **Apollo Builder** | 01 Apollo Builder Agent | Apollo GraphQL subgraph config with types and resolvers |
1765
+ | **Frontend Architect** | 01 Frontend Architect Agent | Frontend architecture with pages, components, and routing |
1766
+ | **React Builder** | 01 React Builder Agent | Frontend config via `graphql-analyzer` and `config-validator` sub-agents |
1767
+ | **Next.js Builder** | 01 Next.js Builder Agent | Next.js App Router config with pages, layouts, and API routes |
1768
+ | **Execution Planner** | 01 Execution Planner Agent | Phased implementation plan with edge cases and testing checklist |
1769
+ | **Core Framework** | 01-05: Model, Providers, Tools, Multi-Tool, Subagents | Models, tools, agent loop, sub-agent delegation |
1770
+ | **Hello World** | 01 Hello World | Minimal agent with greeting tool (module template) |
1706
1771
 
1707
1772
  ---
1708
1773
 
@@ -1735,11 +1800,11 @@ npm run build
1735
1800
 
1736
1801
  **Support**
1737
1802
 
1738
- - [GitHub Issues](https://github.com/sijeeshmiziha/sweagent/issues) — Bugs and features
1739
- - [GitHub Discussions](https://github.com/sijeeshmiziha/sweagent/discussions) — Questions
1803
+ - [GitHub Issues](https://github.com/sijeeshmiziha/sweagent/issues) -- Bugs and features
1804
+ - [GitHub Discussions](https://github.com/sijeeshmiziha/sweagent/discussions) -- Questions
1740
1805
 
1741
1806
  ---
1742
1807
 
1743
1808
  ## License
1744
1809
 
1745
- MIT License — see [LICENSE](LICENSE) for details.
1810
+ MIT License -- see [LICENSE](LICENSE) for details.