Stellar Agent

An AI agent team for Stellar blockchain developers. Run one command to add a team of eight specialized AI agents to any project.

Install

npx stellar-agent init

This scaffolds a _stellar/ directory in your project. From that point, invoke agents directly from your AI assistant (Claude Code, Cursor, Windsurf, etc.).

Pinning a version

The CLI and the skill catalog ship as one versioned package. To pin a project to a specific version of the agent team:

npx [email protected] init     # always installs v0.2.0 skills

The chosen version is recorded in _stellar/_config/manifest.yaml. Check it any time with:

stellar-agent version

If the CLI you're running differs from the skills version recorded in your project, the command warns you and tells you how to re-pin.

Agent Team

📊 Aria — Blockchain Analyst

@stellar-agent-analyst

Tokenomics research, on-chain data analysis, dbt analytics, and DeFi competitive landscape. Start here when you need to understand the market or model your token economy.

| Command | What it does | |---|---| | MR | Market research — DeFi landscape and Stellar ecosystem | | TA | Tokenomics analysis — supply, distribution, velocity | | AN | Analytics setup — dbt models for Stellar network data | | DR | Domain research — protocol constraints and regulatory context |

📋 Kai — dApp Product Manager

@stellar-agent-pm

PRDs, epics, user stories, and project briefs. Turns your idea into a structured plan with Stellar-specific acceptance criteria.

| Command | What it does | |---|---| | PB | Project brief — one-page concept and goals | | PR | Product Requirements Document | | ES | Epics and stories — development breakdown with acceptance criteria |

🏗️ Nova — Stellar System Architect

@stellar-agent-architect

On-chain vs off-chain decisions, Soroban contract design, system diagrams. Use before writing any code.

| Command | What it does | |---|---| | AD | Architecture document — full system design with Mermaid diagrams | | CD | Contract design — storage schema, auth model, cross-contract calls |

💻 Sol — Stellar Developer

@stellar-agent-developer

Soroban smart contracts in Rust, Stellar SDK transactions in TypeScript, and deployment pipelines.

| Command | What it does | |---|---| | IC | Init contract — stellar contract init with workspace setup | | WC | Write contract — storage types, host functions, error handling | | DC | Deploy contract — build → optimize → upload → instantiate | | TX | Create transaction — payments, path payments, account operations | | CA | Create asset — custom asset issuance and stellar.toml | | TL | Setup trustline — changeTrust and setTrustLineFlags | | LP | Liquidity pool — AMM deposit, withdraw, and DEX swaps |

🎨 Lyra — Stellar Frontend Developer

@stellar-agent-frontend

Next.js App Router dApps connected to Stellar — Freighter wallet, Soroban contract calls from React, SEP-10 auth.

| Command | What it does | |---|---| | NS | Next.js setup — scaffold project with Stellar SDK and env config | | WL | Wallet integration — Freighter connect/disconnect and signing | | SC | Soroban in Next.js — Server Components + client-side contract calls | | FI | Freighter integration — full API reference and lifecycle | | SA | SEP-10 auth — Web Authentication with JWT for API routes | | HI | Horizon integration — fetch account and transaction data |

🧪 Vera — Contract QA Engineer

@stellar-agent-qa

Smart contract testing, testnet validation, and regression suites. Never ships until simulation is clean.

| Command | What it does | |---|---| | TC | Test contract — Rust test harness with mock_all_auths and try_* | | TV | Testnet validation — end-to-end regression on testnet |

⚙️ Orion — Stellar DevOps Engineer

@stellar-agent-devops

Local Stellar environment setup, Horizon instance management, and testnet → mainnet deployment.

| Command | What it does | |---|---| | SE | Setup environment — Stellar CLI, Rust, Docker quickstart | | HI | Horizon integration — server setup, streaming, fee strategy | | DP | Deploy — full deployment pipeline with runbook |

🧭 Pera — Hackathon Mentor

@stellar-agent-mentor

Hackathon-arc mentor for Stellar/Soroban submissions. Scopes ideas to the timebox, picks the right track, aligns the build to judging criteria, and coaches demo and pitch. Invoked at the start of a hackathon to shape scope and at the end to ship the demo. On activation, asks for the hackathon link (Devpost / SCF / SDF URL), hours remaining, and target track — all skippable.

| Command | What it does | |---|---| | IS | Idea scoping — one-pager and cut list against the build window | | TR | Track recommendation — DeFi / Payments / Identity / Gaming / RWA fit | | MV | MVP definition — must-have / nice-to-have / skip split | | JC | Judging criteria — map the build to the rubric | | DM | Demo prep — storyboard, 2–3 min script, recording checklist | | PC | Pitch coaching — deck outline and judge Q&A prep | | SP | Submission prep — repo, README, demo video, contract IDs checklist |

Core Commands

These work from any project with _stellar/ initialized:

| Command | What it does | |---|---| | stellar-help | Browse the full skill catalog with next-step recommendations | | stellar-brainstorming | Facilitated brainstorming for project ideas, architecture, and tokenomics | | stellar-party-mode | Multi-agent roundtable — all agents in one discussion | | stellar-lean | Switch the active agent into terse, result-only output mode |

Typical Workflow

1. stellar-brainstorming     → explore the idea
2. @stellar-agent-analyst    → MR  market research
3. @stellar-agent-pm         → PB  project brief → PR  PRD → ES  epics
4. @stellar-agent-architect  → AD  architecture document
5. @stellar-agent-devops     → SE  setup environment
6. @stellar-agent-developer  → IC  init contract → WC  write → DC  deploy
7. @stellar-agent-qa         → TC  test contract → TV  testnet validation
8. @stellar-agent-frontend   → NS  Next.js setup → WL  wallet → SC  Soroban

Hackathon Workflow

When you're building against a submission deadline, swap in Pera at the bookends:

1. @stellar-agent-mentor     → IS  idea scoping → TR  track → MV  MVP cut
2. @stellar-agent-architect  → AD  architecture (lean — only what demo needs)
3. @stellar-agent-developer  → IC → WC → DC
4. @stellar-agent-frontend   → NS → WL → SC
5. @stellar-agent-mentor     → JC  judging → DM  demo → PC  pitch → SP  submit

Local Development

# Install dependencies
npm install

# Validate all skills
npm run validate:skills

# Test CLI
node tools/installer/stellar-cli.js --help

# Run the MCP server locally
npm run mcp

# Link globally for testing in other projects
npm link
# then in another project:
stellar-agent init

Releasing

CI/CD is wired up via GitHub Actions:

• .github/workflows/validate.yml — runs on every push and PR to main: validates all skills, runs the test suite on Node 20.x and 22.x, builds the docs site, and smoke-tests the MCP server.
• .github/workflows/publish.yml — runs on tags matching v*: re-validates, verifies the tag matches package.json version, publishes to npm with provenance, and creates a GitHub release.

One-time setup: add an NPM_TOKEN secret to the repo (Settings → Secrets and variables → Actions). Use a granular access token scoped to publish only the stellar-agent package.

Releasing a new version:

npm version minor       # 0.2.0 → 0.3.0 (creates commit + git tag v0.3.0)
git push --follow-tags  # triggers publish.yml

prepublishOnly runs validate:skills && test automatically on any npm publish — local or CI.

Requirements

• Node.js >= 20.12.0
• An AI assistant that supports agent/persona invocation (Claude Code, Cursor, etc.)