Stellar Forge

What Is This?

Stellar Forge is two things that work together:

1. An AI orchestration layer (the "Skill") — a set of six specialist agent definitions + a graph engine kernel (CLAUDE.md) that routes your requests to the right agents, verifies their output against structured evals, and steers on failure. It runs inside Claude Code or OpenCode.

2. A project scaffold CLI (create-stellar-agentic) — generates a production-ready Stellar monorepo with contracts, frontend, backend, CI/CD, and agent files pre-configured. If you use Claude Code, it auto-installs the Skill too.

The CLI bootstraps the project. The Skill builds it. You can use either independently — together they're a complete workflow.

Stellar Forge is an open-source reference implementation (MIT) demonstrating a supported AI-assisted Stellar development workflow: install the Skill → scaffold with the CLI → build & refine with AI assistance → evaluate against structured checks → validate on Stellar Testnet. See the Instawards Statement of Work for the full scope.

Who Is This For?

Why Not Just Use ChatGPT / Copilot / Cursor?

Generic AI tools don't know Stellar. They don't know that:

• Contracts must be #![no_std] with soroban-sdk
• Wallet connection requires Stellar Wallets Kit (not wagmi)
• x402 payments need OZ Channels facilitator + CAIP-2 network IDs
• The correct curve for on-chain ZK verification is BLS12-381, not BN254

Stellar Forge embeds that domain knowledge into 10 installable skills, 6 agent definitions, and 5 eval files. Every agent checks its output against structured pass/fail criteria before handing off. It's not a chat — it's a multi-agent graph engine with domain expertise.

Architecture

stellar-forge/
├── SKILL.md          # Entry point — loads the graph engine
├── CLAUDE.md         # Graph engine kernel — routes tasks as work graphs
│
├── agents/           # 6 agent definitions (node prompts)
│   ├── stellar-contracts.md
│   ├── stellar-frontend.md
│   ├── stellar-backend.md
│   ├── stellar-payments.md
│   ├── stellar-ops.md
│   └── stellar-zk.md
│
├── skills/           # Domain knowledge (loaded on demand)
│   ├── smart-contracts/   →  soroban-sdk, WASM, storage, auth, testing
│   ├── dapp/              →  Wallets Kit, tx building, React hooks
│   ├── data/              →  RPC + Horizon, event queries
│   ├── assets/            →  SAC, trustlines, classic tokens
│   ├── agentic-payments/  →  x402, MPP Charge/Channel
│   ├── standards/         →  SEPs, CAPs, ecosystem
│   ├── zk-proofs/         →  Groth16, BLS12-381, Circom/Noir
│   ├── stellar-mcp/       →  MCP server tools
│   ├── frontend-design/   →  dApp UI patterns
│   └── graphify/          →  Knowledge graphs
│
├── evals/            # Pass/fail criteria per component
│   ├── 01-contract-eval.md
│   ├── 02-frontend-eval.md
│   └── ...
│
├── templates/        # Source templates for CLI scaffold
│   ├── contracts/    # hello-world, token (SEP-41), vault (milestone escrow)
│   ├── frontend/
│   ├── backend/
│   └── cicd/
│
├── packages/
│   ├── create-stellar-agentic/  # npm-published CLI
│   └── forge-gateway/           # remote Stellar-context MCP server
└── .claude/commands/  # Slash commands

How the Pieces Connect

You (prompt)
   │
   ▼
Graph Engine (CLAUDE.md)
   │  Parses intent, generates a work graph
   │
   ├──────────────────┬──────────────────┐
   │                  │                  │
   ▼                  ▼                  ▼
Agent Node 1      Agent Node 2      Agent Node 3
(contracts)       (frontend)        (backend)
   │                  │                  │
   ▼                  ▼                  ▼
Verifier (eval)   Verifier (eval)   Verifier (eval)
   │                  │                  │
   └──────────────────┼──────────────────┘
                      ▼
               Synthesize → Report

The Kernel

The kernel (CLAUDE.md) is the graph engine. It is not a runtime — it is a structured prompt that tells the AI how to organize its own work. It defines:

• Org graph — 6 agent nodes with zone ownership and persistent context
• Work graph generation — how to wire agents together per task (sequential, parallel, conditional, fan-out, fan-in)
• Node execution contract — what the kernel passes to each agent (intent + context + tools) and what it expects back (output + state delta + verifier result)
• Edge definitions — what data flows between nodes (contract IDs, ABI, payment middleware config, API endpoints)
• Failure recovery — retry same node → reroute to fallback → escalate

Each task gets a dynamically-generated work graph. For "Build a token contract with a React frontend", the graph is:

[contracts] ──(contract_id)──→ [frontend]
     ↓                              ↓
  verifier                       verifier
  (pass)                         (pass) → [kernel: synthesize]

The 6 Agents

These are prompt-based agent definitions in agents/*.md. Each is a structured instruction set (not a running process) that tells the AI which zone it owns, what data it needs, what tools it can use, and what constraints apply.

You can customize, add, or remove agents — each is just a markdown file in agents/. Register new agents in the CLAUDE.md org graph table.

Installation

Which One?

Skill (AI Orchestration)

# For Claude Code or OpenCode
npx skills add rylsherdamz-rgb/stellar-forge

# Specify the agent
npx skills add rylsherdamz-rgb/stellar-forge --agent claude-code
npx skills add rylsherdamz-rgb/stellar-forge --agent opencode

After installing, start a session and prompt:

"Build a token contract with a React frontend and x402 payments"

The graph engine routes to the relevant agents, each with domain skills and evals loaded. Outputs are verified against pass/fail criteria, with up to 3 retries on failure.

CLI (Project Scaffold)

npx create-stellar-agentic my-dapp

This generates a production-ready monorepo:

my-dapp/
├── contracts/          # Rust smart contracts (hello-world + SEP-41 token)
├── frontend/           # Next.js 15 + Wallets Kit + hooks + components
├── backend/            # Express + RPC + x402/MPP payment middleware
├── .github/workflows/  # CI/CD for contracts, frontend, backend
├── scripts/            # deploy-contract.sh (test gate → deploy → record)
├── agents/             # 6 agent definitions (works with Claude Code)
├── evals/              # Eval criteria per component
├── CLAUDE.md           # Graph engine kernel
└── SKILL.md            # Orchestration entry point

Killer feature: the CLI automatically installs the Skill. When you run npx create-stellar-agentic, it copies all 10 skills to ~/.claude/skills/ and sets up the CLAUDE.md kernel. Opening the generated project in Claude Code instantly activates the full multi-agent harness — no extra steps.

CLI Options

Features

Agentic Kit Hooks (no raw RPC)

Eval-Driven Pipeline

Each agent's output is checked against structured pass/fail criteria. If it fails, the kernel feeds the failure details back as corrective context (max 3 retries).

MCP Integrations

Forge Gateway (remote Stellar-context MCP server)

packages/forge-gateway — a Raven-style gateway that exposes the framework's curated Stellar knowledge (skills, evals, standards, ecosystem intel) to any MCP client over HTTP. Built with the Streamable HTTP transport.

npm run gateway            # start on :8787 (POST /mcp, /api/search, /api/execute, /playground)
npm run gateway:test       # 10/10 unit tests
npm run gateway:check-live # probe Soroban RPC, Horizon, npm, docs site, GitHub

Forge Vault (milestone escrow)

templates/contracts/vault — a trustless milestone-escrow contract. The depositor commits funds against release keys; the recipient claims each milestone by presenting the matching sha256 preimage; the arbiter can override (release or refund); the depositor recovers unclaimed funds after the deadline.

cargo test --manifest-path templates/contracts/vault/Cargo.toml  # 9/9 tests

Live on Stellar Testnet: CB2JGINPQP6DSWEY6N5XOWOSVOW6IPCNLSM2AQWVKP3LTVSQ3SQSHKFZ (see data/deployments/testnet.json).

Contract Deployment

Test-gated deployment — cargo test must pass or the deploy aborts.

• First deploy on a network: auto-deploys, records to data/deployments/, updates .env
• Subsequent deploys: prompts for confirmation

Configuration

Releases & npm auto-publish

Tagging v<semver> on master triggers:

• npm publish — .github/workflows/publish-npm.yml verifies the tag matches packages/create-stellar-agentic/package.json's version, gates on the gateway tests, then publishes to npm (needs the NPM_TOKEN secret)
• Site deploy — .github/workflows/deploy-site.yml ships the docs site to Vercel

Bump the version first, then tag:

npm version patch -w create-stellar-agentic && git push --tags

Environment Variables

FAQ

Can I use this without Claude Code?
Yes. npx create-stellar-agentic works standalone. The graph engine only activates in Claude Code sessions.

What networks are supported?
Testnet (default), mainnet, and local/testcontainer. Mainnet requires explicit env opt-in.

How do eval retries work?
Each agent gets max 3 attempts. On failure, the kernel feeds the eval failure details back as corrective context for the retry.

How do I add my own agent?
Create an agent file in agents/, register it in CLAUDE.md's org graph table, and add its eval to evals/.

My contracts don't compile — what SDK version?
Template contracts target soroban-sdk = "27.0.0-rc.1". Run cargo update for a newer patch.

How does the vault escrow work?
The depositor commits funds via deposit; the recipient calls claim_milestone(index, proof) where sha256(proof) must equal the stored release key. The arbiter can release/refund regardless, and the depositor recovers unclaimed funds after the deadline. See templates/contracts/vault/src/lib.rs.

How does the npm release flow work?
Tag v<version> → CI verifies the tag matches packages/create-stellar-agentic/package.json, runs tests, publishes to npm, and redeploys the site. Push tags after bumping the version.

Related

• Documentation & Demo
• Stellar Documentation
• Stellar Wallets Kit
• Stellar Agentic Kit
• OpenZeppelin Stellar Contracts