SPARK Method

    ███████╗██████╗  █████╗ ██████╗ ██╗  ██╗
    ██╔════╝██╔══██╗██╔══██╗██╔══██╗██║ ██╔╝
    ███████╗██████╔╝███████║██████╔╝█████╔╝
    ╚════██║██╔═══╝ ██╔══██║██╔══██╗██╔═██╗
    ███████║██║     ██║  ██║██║  ██║██║  ██╗
    ╚══════╝╚═╝     ╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝
    ═══════════════════════════════════════
    Production-Ready AI Agents | LangGraph TS

SPARK (Structured Production Agent Rapid Kit) is a methodology for building production-ready AI agents using LangGraph TypeScript.

Built for Claude Code. Deploys to Railway.

Quick Start

# Install
npm install -g spark-method

# Initialize in your project
cd my-agent-project
npx spark-method init

# Start Claude Code and use
/spark

Philosophy

80/20 Rule

80% of agent use cases are solved by the ReAct pattern:

1. Reason about what to do
2. Act by calling a tool
3. Observe the result
4. Repeat until done

Start simple. Add complexity only when proven necessary.

Production First

Every decision considers production deployment:

• Error handling that LLMs understand
• Memory persistence for real users
• Health checks for reliability
• Cost awareness per invocation

Code Readability

For developers coming from low-code backgrounds (n8n, Make, Zapier):

• Verbose comments explaining "why"
• Descriptive variable names
• Explicit TypeScript types
• Clear error messages

Workflow

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   ARCHITECT  │ ──► │   BUILDER    │ ──► │   DEPLOYER   │
│              │     │              │     │              │
│ Design agent │     │ Implement    │     │ Deploy to    │
│ tools, state │     │ code         │     │ Railway      │
└──────────────┘     └──────────────┘     └──────────────┘

Phase 1: Design (Architect)

• Define agent purpose (single responsibility)
• Design 3-7 focused tools
• Create state schema
• Output: docs/agent-design.md

Phase 2: Build (Builder)

• Implement tools with Zod schemas
• Create ReAct or StateGraph agent
• Add memory/checkpointing
• Output: src/ directory

Phase 3: Deploy (Deployer)

• Configure Railway project
• Setup environment variables
• Deploy with health checks
• Output: Live service

Commands

All commands use / prefix in Claude Code:

| Command | Description | |---------|-------------| | /spark | Start orchestrator | | /spark-architect | Design agent | | /spark-builder | Implement code | | /spark-deployer | Deploy to Railway |

Within agents, use * prefix:

| Command | Description | |---------|-------------| | *help | Show available commands | | *agent {name} | Switch to specialist | | *workflow | Show workflow diagram |

Project Structure

After initialization:

your-project/
├── .spark-core/           # SPARK Method files
│   ├── agents/            # Agent definitions
│   ├── templates/         # Document templates
│   ├── tasks/             # Executable tasks
│   ├── checklists/        # Validation checklists
│   ├── data/              # Knowledge base
│   └── workflows/         # Workflow definitions
├── .claude/
│   └── commands/
│       └── spark/         # Claude Code commands
├── docs/
│   └── agent-design.md    # Your agent design
└── src/
    ├── tools/             # Tool implementations
    ├── agent.ts           # Agent definition
    └── index.ts           # Entry point

Example: Weather Agent

import { createReactAgent } from "@langchain/langgraph/prebuilt";
import { ChatOpenAI } from "@langchain/openai";
import { tool } from "@langchain/core/tools";
import { z } from "zod";
import { MemorySaver } from "@langchain/langgraph";

// Define a focused tool
const getWeather = tool(
  async ({ city }) => {
    // Your API call here
    return `The weather in ${city} is sunny, 22°C`;
  },
  {
    name: "get_weather",
    description: "Get current weather for a city. Returns temperature and conditions.",
    schema: z.object({
      city: z.string().describe("City name, e.g., 'São Paulo'"),
    }),
  }
);

// Create the agent
const agent = createReactAgent({
  llm: new ChatOpenAI({ model: "gpt-4o", temperature: 0 }),
  tools: [getWeather],
  checkpointer: new MemorySaver(),
  prompt: "You are a helpful weather assistant.",
});

// Use it
const result = await agent.invoke(
  { messages: [{ role: "user", content: "What's the weather in Tokyo?" }] },
  { configurable: { thread_id: "user-123" } }
);

License

MIT

Credits

Inspired by BMAD Method - the Breakthrough Method of Agile AI-driven Development.

Built for the LangGraph ecosystem by @joaodnascimento.