stellar-agent 0.1.0

package/src/stellar-skills/4-implementation/stellar-write-contract/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: stellar-write-contract
+description: 'Guide implementation of Soroban smart contract logic including storage types, host functions, error handling, and cross-contract calls. Use when the user needs to implement or expand a Soroban contract.'
+---
+
+# Write Soroban Contract
+
+## Purpose
+
+Guide the user through implementing production-quality Soroban contract code.
+
+## On Activation
+
+Load config from `{project-root}/_stellar/stellar/config.yaml`. Read any architecture document at `{project-root}/_stellar-output/planning-artifacts/architecture.md` if it exists.
+
+## Core Knowledge
+
+### Storage Types
+
+Explain when to use each:
+
+- **Persistent** — data that must survive contract instance expiration (token balances, ownership records). Higher rent cost.
+- **Temporary** — data with short TTL, cheaper rent (nonces, session tokens, rate limits).
+- **Instance** — contract-level metadata tied to the contract instance lifetime (admin address, paused flag, config). Expires with the instance.
+
+```rust
+use soroban_sdk::{contractimpl, Env, Address};
+
+pub struct MyContract;
+
+#[contractimpl]
+impl MyContract {
+    pub fn set_admin(env: Env, admin: Address) {
+        // Instance storage: tied to contract instance lifetime
+        env.storage().instance().set(&Symbol::new(&env, "Admin"), &admin);
+    }
+
+    pub fn get_balance(env: Env, account: Address) -> i128 {
+        // Persistent storage: survives archival cycles
+        env.storage().persistent().get(&account).unwrap_or(0)
+    }
+}
+```
+
+### Host Functions
+
+Key Soroban host functions:
+- `env.storage()` — access Persistent/Temporary/Instance storage
+- `env.invoker()` — get the address that invoked this function (deprecated; use auth instead)
+- `env.current_contract_address()` — get this contract's own address
+- `env.events().publish((symbol, ...), data)` — emit contract events
+- `env.ledger().timestamp()` — current ledger timestamp
+- `env.ledger().sequence()` — current ledger sequence number
+
+### Authorization
+
+```rust
+pub fn transfer(env: Env, from: Address, to: Address, amount: i128) {
+    // Require the 'from' address to have authorized this call
+    from.require_auth();
+    // ... transfer logic
+}
+```
+
+### Error Handling
+
+```rust
+use soroban_sdk::contracterror;
+
+#[contracterror]
+#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
+#[repr(u32)]
+pub enum ContractError {
+    NotInitialized = 1,
+    Unauthorized = 2,
+    InsufficientBalance = 3,
+    InvalidAmount = 4,
+}
+```
+
+### Cross-Contract Calls
+
+```rust
+use soroban_sdk::contract_client;
+
+// Import external contract interface
+contract_client!(OtherContract, "../other_contract");
+
+pub fn call_other(env: Env, other_contract_id: Address) -> i128 {
+    let client = OtherContractClient::new(&env, &other_contract_id);
+    client.some_function()
+}
+```
+
+## Workflow
+
+### Step 1: Review Architecture
+
+Read any existing architecture document. Ask the user to describe the contract's purpose if no document exists.
+
+### Step 2: Define the Interface
+
+Work with the user to define function signatures before implementation:
+
+```rust
+pub trait MyContractTrait {
+    fn initialize(env: Env, admin: Address) -> Result<(), ContractError>;
+    fn deposit(env: Env, from: Address, amount: i128) -> Result<(), ContractError>;
+    fn withdraw(env: Env, to: Address, amount: i128) -> Result<(), ContractError>;
+    fn get_balance(env: Env, account: Address) -> i128;
+}
+```
+
+### Step 3: Implement Storage Layer
+
+Write storage key enums and read/write helpers:
+
+```rust
+#[contracttype]
+pub enum DataKey {
+    Admin,
+    Balance(Address),
+    Paused,
+}
+
+fn get_balance(env: &Env, account: &Address) -> i128 {
+    env.storage()
+        .persistent()
+        .get(&DataKey::Balance(account.clone()))
+        .unwrap_or(0)
+}
+```
+
+### Step 4: Implement Business Logic
+
+Implement each function with proper auth, error handling, and event emission.
+
+### Step 5: Write Tests
+
+Suggest `stellar-test-contract` for comprehensive test coverage.

package/src/stellar-skills/module-help.csv

@@ -0,0 +1,24 @@
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+Stellar,_meta,,,,,,,,,false,https://github.com/tolgazorlu/stellar-agent#readme,
+Stellar,stellar-analytics,Analytics Setup,AN,Set up dbt blockchain analytics for Stellar network data and tokenomics reporting.,,,1-analysis,,,false,{project_knowledge},dbt models
+Stellar,stellar-market-research,Market Research,MR,DeFi landscape competitive analysis and Stellar ecosystem research.,,,1-analysis,,,false,{planning_artifacts},research document
+Stellar,stellar-domain-research,Domain Research,DR,Stellar protocol deep dive — tokenomics regulatory landscape and use case research.,,,1-analysis,,,false,{planning_artifacts},research document
+Stellar,stellar-project-brief,Project Brief,PB,Define the dApp concept goals and target users in a concise brief.,,,2-planning,,,false,{planning_artifacts},project-brief
+Stellar,stellar-prd,Stellar dApp PRD,PR,Create or update Product Requirements Document for a Stellar application.,,,2-planning,stellar-project-brief,,true,{planning_artifacts},prd
+Stellar,stellar-epics-stories,Epics and Stories,ES,Break PRD into development epics and user stories with Stellar-specific acceptance criteria.,,,2-planning,stellar-prd,,true,{planning_artifacts},epics-stories
+Stellar,stellar-architecture-doc,Architecture Document,AD,Create technical architecture document covering on-chain vs off-chain Soroban contract design and Horizon integration.,,,3-architecture,stellar-prd,,true,{planning_artifacts},architecture
+Stellar,stellar-setup-environment,Setup Environment,SE,Set up local Stellar development environment with Docker quickstart Stellar CLI and SDK.,,,4-implementation,,,true,{project_knowledge},environment-guide
+Stellar,stellar-init-contract,Init Contract,IC,Initialize a new Soroban smart contract project with Rust workspace and scaffold.,,,4-implementation,stellar-setup-environment,,false,{implementation_artifacts},contract scaffold
+Stellar,stellar-write-contract,Write Contract,WC,Implement Soroban contract logic including storage types host functions and error handling.,,,4-implementation,stellar-init-contract,,false,{implementation_artifacts},contract code
+Stellar,stellar-test-contract,Test Contract,TC,Write and run comprehensive Soroban contract tests using the Rust test harness.,,,4-implementation,stellar-write-contract,,true,{implementation_artifacts},test suite
+Stellar,stellar-deploy-contract,Deploy Contract,DC,Deploy Soroban contract through full pipeline — build optimize upload instantiate verify.,,,4-implementation,stellar-test-contract,,false,{implementation_artifacts},deployed-contracts
+Stellar,stellar-create-transaction,Create Transaction,TX,Build sign and submit Stellar transactions using the JS/TS or Python SDK.,,,4-implementation,stellar-setup-environment,,false,{implementation_artifacts},transaction
+Stellar,stellar-create-asset,Create Asset,CA,Create a custom Stellar asset with issuing account stellar.toml and distribution setup.,,,4-implementation,stellar-setup-environment,,false,{implementation_artifacts},asset-config
+Stellar,stellar-setup-trustline,Setup Trustline,TL,Configure trustlines so accounts can hold and receive custom Stellar assets.,,,4-implementation,stellar-create-asset,,false,{implementation_artifacts},trustline-config
+Stellar,stellar-liquidity-pool,Liquidity Pool,LP,Create and interact with Stellar AMM liquidity pools and DEX order books.,,,4-implementation,stellar-setup-trustline,,false,{implementation_artifacts},pool-config
+Stellar,stellar-horizon-integration,Horizon Integration,HI,Integrate with Stellar Horizon REST API for account queries transaction streaming and order book data.,,,4-implementation,stellar-setup-environment,,false,{implementation_artifacts},horizon-client
+Stellar,stellar-nextjs-setup,Next.js Setup,NX,Scaffold a Next.js App Router project with Stellar SDK environment config and network setup.,,,4-implementation,stellar-setup-environment,,false,{implementation_artifacts},nextjs-project
+Stellar,stellar-nextjs-wallet,Next.js Wallet,NW,Integrate Freighter wallet into Next.js with connect/disconnect signing and account state.,,,4-implementation,stellar-nextjs-setup,,false,{implementation_artifacts},wallet-integration
+Stellar,stellar-nextjs-soroban,Next.js Soroban,NS,Call Soroban contracts from Next.js using Server Components API routes and client-side signing.,,,4-implementation,stellar-nextjs-wallet,,false,{implementation_artifacts},soroban-integration
+Stellar,stellar-freighter-integration,Freighter Integration,FI,Deep Freighter wallet integration — full API reference connection lifecycle and blob signing.,,,4-implementation,stellar-setup-environment,,false,{implementation_artifacts},freighter-integration
+Stellar,stellar-sep10-auth,SEP-10 Auth,S10,Implement SEP-10 Web Authentication with JWT for Next.js API routes and protected endpoints.,,,4-implementation,stellar-nextjs-setup,,false,{implementation_artifacts},sep10-auth

package/src/stellar-skills/module.yaml

@@ -0,0 +1,103 @@
+code: stellar
+name: "Stellar Agent Skills"
+description: "Complete AI agent team for Stellar blockchain development"
+default_selected: true
+
+# Variables inherited from Core module:
+# user_name, project_name, communication_language, document_output_language, output_folder
+
+network_preference:
+  prompt: "Which Stellar network are you primarily developing for?"
+  default: "testnet"
+  result: "{value}"
+  single-select:
+    - value: "testnet"
+      label: "Testnet — Safe development environment"
+    - value: "mainnet"
+      label: "Mainnet — Production deployment"
+    - value: "futurenet"
+      label: "Futurenet — Cutting-edge feature testing"
+
+primary_language:
+  prompt: "What is your primary development language?"
+  default: "typescript"
+  result: "{value}"
+  single-select:
+    - value: "typescript"
+      label: "JavaScript/TypeScript — dApp and SDK development"
+    - value: "rust"
+      label: "Rust — Soroban smart contracts"
+    - value: "python"
+      label: "Python — Analytics and automation"
+    - value: "fullstack"
+      label: "Full stack — Both TypeScript and Rust"
+
+planning_artifacts:
+  prompt: "Where should planning artifacts be stored?"
+  default: "{output_folder}/planning-artifacts"
+  result: "{project-root}/{value}"
+
+implementation_artifacts:
+  prompt: "Where should implementation artifacts be stored?"
+  default: "{output_folder}/implementation-artifacts"
+  result: "{project-root}/{value}"
+
+project_knowledge:
+  prompt: "Where should project knowledge be stored?"
+  default: "docs"
+  result: "{project-root}/{value}"
+
+directories:
+  - "{planning_artifacts}"
+  - "{implementation_artifacts}"
+  - "{project_knowledge}"
+
+agents:
+  - code: stellar-agent-analyst
+    name: Aria
+    title: Blockchain Analyst
+    icon: "📊"
+    team: stellar-development
+    description: "Data-driven blockchain analyst who grounds every insight in on-chain evidence. Specializes in tokenomics, dbt analytics, Stellar network data, and competitive DeFi landscape analysis. Speaks like a detective following the on-chain trail — precise, evidence-first, never speculates without data."
+
+  - code: stellar-agent-pm
+    name: Kai
+    title: dApp Product Manager
+    icon: "📋"
+    team: stellar-development
+    description: "User-value-first product manager who translates financial inclusion goals into actionable Stellar dApp specs. Cuts through blockchain hype to focus on real user needs. Speaks with direct questions and sharp follow-ups — every 'why?' leads back to the user."
+
+  - code: stellar-agent-architect
+    name: Nova
+    title: Stellar System Architect
+    icon: "🏗️"
+    team: stellar-development
+    description: "Makes the critical on-chain vs. off-chain calls, Soroban vs. Classic Stellar decisions, and multi-contract architecture choices. Favors simple, auditable designs. Speaks at the whiteboard — trade-offs first, verdicts only when evidence is clear."
+
+  - code: stellar-agent-developer
+    name: Sol
+    title: Stellar Developer
+    icon: "💻"
+    team: stellar-development
+    description: "Builds Soroban smart contracts in Rust, dApps with Stellar SDK (JS/TS), and Python automation. Test-first across both Rust test harness and testnet. Speaks in contract addresses, XDR formats, and transaction hashes — exact, citable, no filler."
+
+  - code: stellar-agent-qa
+    name: Vera
+    title: Contract QA Engineer
+    icon: "🧪"
+    team: stellar-development
+    description: "Validates smart contracts against edge cases, simulates transaction failures, and runs testnet regression suites. Never ships until simulation is clean. Speaks in test IDs and failure modes — every claim backed by a test result."
+
+  - code: stellar-agent-devops
+    name: Orion
+    title: Stellar DevOps Engineer
+    icon: "⚙️"
+    team: stellar-development
+    description: "Sets up local Stellar quickstart environments, manages Horizon instances, handles deployment pipelines from testnet to mainnet, and diagnoses network issues with stellar doctor. Speaks in commands — direct, copy-pasteable, no vague instructions."
+
+  - code: stellar-agent-frontend
+    name: Lyra
+    title: Stellar Frontend Developer
+    icon: "🎨"
+    team: stellar-development
+    description: "Builds Next.js App Router dApps connected to the Stellar network. Expert in Freighter wallet integration, Soroban contract calls from React, Horizon data fetching in Server Components, and SEP-10 authentication. Knows exactly when to use Server vs Client Components and never exposes private keys."

package/tools/installer/cli-utils.js

@@ -0,0 +1,39 @@
+const prompts = require('./prompts');
+
+const CLIUtils = {
+  async displayLogo() {
+    const color = await prompts.getColor();
+    const termWidth = process.stdout.columns || 80;
+
+    const logoWide = [
+      ' ███████╗████████╗███████╗██╗     ██╗      █████╗ ██████╗      █████╗  ██████╗ ███████╗███╗   ██╗████████╗',
+      ' ██╔════╝╚══██╔══╝██╔════╝██║     ██║     ██╔══██╗██╔══██╗    ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝',
+      ' ███████╗   ██║   █████╗  ██║     ██║     ███████║██████╔╝    ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ',
+      ' ╚════██║   ██║   ██╔══╝  ██║     ██║     ██╔══██║██╔══██╗    ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ',
+      ' ███████║   ██║   ███████╗███████╗███████╗██║  ██║██║  ██║    ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ',
+      ' ╚══════╝   ╚═╝   ╚══════╝╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝    ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ',
+    ];
+
+    const logoNarrow = [
+      ' ★  STELLAR AGENT',
+      ' ──────────────────',
+    ];
+
+    const logoLines = termWidth >= 110 ? logoWide : logoNarrow;
+    const logo = logoLines.map((line) => color.cyan(line)).join('\n');
+    const tagline = color.white('    AI Agent Team for the Stellar Network\n    Build on the blockchain for the world');
+
+    await prompts.box(`${logo}\n${tagline}`, '', {
+      contentAlign: 'center',
+      rounded: true,
+      formatBorder: color.cyan,
+    });
+  },
+
+  async displayModuleConfigHeader(moduleName, header = null, subheader = null) {
+    const title = header || `Configuring ${moduleName.toUpperCase()} Module`;
+    await prompts.note(subheader || '', title);
+  },
+};
+
+module.exports = { CLIUtils };

package/tools/installer/commands/init.js

@@ -0,0 +1,335 @@
+const path = require('node:path');
+const os = require('node:os');
+const fsp = require('node:fs/promises');
+const fs = require('node:fs');
+const yaml = require('yaml');
+const prompts = require('../prompts');
+const { CLIUtils } = require('../cli-utils');
+
+// Escape a value for safe embedding in a TOML double-quoted string
+function tomlEscape(str) {
+  return String(str).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+}
+
+const STELLAR_DIR = '_stellar';
+const OUTPUT_DIR = '_stellar-output';
+
+async function installStellarAgent(targetDir, config) {
+  const stellarDir = path.join(targetDir, STELLAR_DIR);
+  const outputDir = path.join(targetDir, OUTPUT_DIR);
+
+  // Create directory structure
+  const dirs = [
+    path.join(stellarDir, '_config'),
+    path.join(stellarDir, 'core'),
+    path.join(stellarDir, 'stellar'),
+    path.join(stellarDir, 'scripts'),
+    path.join(stellarDir, 'custom'),
+    path.join(outputDir, 'planning-artifacts'),
+    path.join(outputDir, 'implementation-artifacts'),
+    path.join(outputDir, 'project-knowledge'),
+  ];
+  for (const dir of dirs) {
+    await fsp.mkdir(dir, { recursive: true });
+  }
+
+  // Write core config
+  const coreConfig = {
+    user_name: config.user_name,
+    project_name: config.project_name,
+    communication_language: config.communication_language,
+    document_output_language: config.communication_language,
+    output_folder: OUTPUT_DIR,
+  };
+  await fsp.writeFile(
+    path.join(stellarDir, 'core', 'config.yaml'),
+    yaml.stringify(coreConfig),
+    'utf8'
+  );
+
+  // Write stellar module config
+  const stellarConfig = {
+    network_preference: config.network_preference,
+    primary_language: config.primary_language,
+    planning_artifacts: `${OUTPUT_DIR}/planning-artifacts`,
+    implementation_artifacts: `${OUTPUT_DIR}/implementation-artifacts`,
+    project_knowledge: 'docs',
+  };
+  await fsp.writeFile(
+    path.join(stellarDir, 'stellar', 'config.yaml'),
+    yaml.stringify(stellarConfig),
+    'utf8'
+  );
+
+  // Write manifest
+  const manifest = {
+    version: require('../../../package.json').version,
+    installed_at: new Date().toISOString(),
+    project_name: config.project_name,
+  };
+  await fsp.writeFile(
+    path.join(stellarDir, '_config', 'manifest.yaml'),
+    yaml.stringify(manifest),
+    'utf8'
+  );
+
+  // Copy Python scripts
+  const scriptsSource = path.join(__dirname, '..', '..', '..', 'src', 'scripts');
+  const scriptsTarget = path.join(stellarDir, 'scripts');
+  for (const script of ['resolve_customization.py', 'resolve_config.py']) {
+    const src = path.join(scriptsSource, script);
+    const dest = path.join(scriptsTarget, script);
+    if (fs.existsSync(src)) {
+      await fsp.copyFile(src, dest);
+    }
+  }
+
+  // Build and write stellar-help.csv by collecting all module-help.csv files
+  await buildHelpCatalog(targetDir, stellarDir);
+
+  // Write custom gitignore
+  await fsp.writeFile(
+    path.join(stellarDir, 'custom', '.gitignore'),
+    '*.user.toml\n',
+    'utf8'
+  );
+
+  // Write base config.toml with agent roster
+  await writeBaseConfigToml(stellarDir, config);
+}
+
+async function buildHelpCatalog(targetDir, stellarDir) {
+  const srcDir = path.join(__dirname, '..', '..', '..', 'src');
+  const csvFiles = [];
+
+  function findCsvFiles(dir) {
+    if (!fs.existsSync(dir)) return;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        findCsvFiles(path.join(dir, entry.name));
+      } else if (entry.name === 'module-help.csv') {
+        csvFiles.push(path.join(dir, entry.name));
+      }
+    }
+  }
+
+  findCsvFiles(srcDir);
+
+  let combined = 'module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs\n';
+  for (const csvFile of csvFiles) {
+    const content = fs.readFileSync(csvFile, 'utf8');
+    const lines = content.split('\n').slice(1).filter((l) => l.trim());
+    combined += lines.join('\n') + '\n';
+  }
+
+  await fsp.writeFile(
+    path.join(stellarDir, '_config', 'stellar-help.csv'),
+    combined,
+    'utf8'
+  );
+}
+
+async function writeBaseConfigToml(stellarDir, config) {
+  const tomlContent = `# Stellar Agent Configuration
+# Generated by stellar-agent init — edit with care
+
+[core]
+user_name = "${tomlEscape(config.user_name)}"
+project_name = "${tomlEscape(config.project_name)}"
+communication_language = "${tomlEscape(config.communication_language)}"
+document_output_language = "${tomlEscape(config.communication_language)}"
+output_folder = "${OUTPUT_DIR}"
+
+[stellar]
+network_preference = "${tomlEscape(config.network_preference)}"
+primary_language = "${tomlEscape(config.primary_language)}"
+planning_artifacts = "${OUTPUT_DIR}/planning-artifacts"
+implementation_artifacts = "${OUTPUT_DIR}/implementation-artifacts"
+project_knowledge = "docs"
+
+[[agents]]
+code = "stellar-agent-analyst"
+name = "Aria"
+title = "Blockchain Analyst"
+icon = "📊"
+team = "stellar-development"
+module = "stellar"
+description = "Data-driven blockchain analyst specializing in tokenomics, dbt analytics, and Stellar network data."
+
+[[agents]]
+code = "stellar-agent-pm"
+name = "Kai"
+title = "dApp Product Manager"
+icon = "📋"
+team = "stellar-development"
+module = "stellar"
+description = "User-value-first product manager who translates financial inclusion goals into Stellar dApp specs."
+
+[[agents]]
+code = "stellar-agent-architect"
+name = "Nova"
+title = "Stellar System Architect"
+icon = "🏗️"
+team = "stellar-development"
+module = "stellar"
+description = "Makes on-chain vs. off-chain calls, Soroban vs. Classic Stellar decisions, and multi-contract architecture."
+
+[[agents]]
+code = "stellar-agent-developer"
+name = "Sol"
+title = "Stellar Developer"
+icon = "💻"
+team = "stellar-development"
+module = "stellar"
+description = "Builds Soroban smart contracts in Rust and dApps with Stellar SDK (JS/TS). Test-first always."
+
+[[agents]]
+code = "stellar-agent-qa"
+name = "Vera"
+title = "Contract QA Engineer"
+icon = "🧪"
+team = "stellar-development"
+module = "stellar"
+description = "Validates smart contracts, simulates transaction failures, and runs testnet regression suites."
+
+[[agents]]
+code = "stellar-agent-devops"
+name = "Orion"
+title = "Stellar DevOps Engineer"
+icon = "⚙️"
+team = "stellar-development"
+module = "stellar"
+description = "Sets up local Stellar environments, manages Horizon instances, and handles deployment pipelines."
+
+[[agents]]
+code = "stellar-agent-frontend"
+name = "Lyra"
+title = "Stellar Frontend Developer"
+icon = "🎨"
+team = "stellar-development"
+module = "stellar"
+description = "Builds Next.js App Router dApps connected to Stellar — Freighter wallet, Soroban contract calls, SEP-10 auth."
+`;
+
+  await fsp.writeFile(path.join(stellarDir, 'config.toml'), tomlContent, 'utf8');
+  // Empty user config
+  await fsp.writeFile(path.join(stellarDir, 'config.user.toml'), '# Personal overrides — gitignore this file\n', 'utf8');
+}
+
+async function action(options) {
+  await CLIUtils.displayLogo();
+  await prompts.intro('Stellar Agent — AI agent team for Stellar blockchain development');
+
+  // Directory selection
+  const rawDir = await prompts.text({
+    message: 'Which directory to initialize?',
+    default: process.cwd(),
+    placeholder: process.cwd(),
+  });
+
+  // Canonicalize and restrict to an absolute path — prevents path traversal
+  const targetDir = path.resolve(
+    rawDir.startsWith('~') ? rawDir.replace('~', os.homedir()) : rawDir
+  );
+
+  // Reject anything that escapes the user's home directory
+  const homeDir = os.homedir();
+  if (!targetDir.startsWith(homeDir + path.sep) && targetDir !== homeDir) {
+    await prompts.cancel(`Directory must be inside your home folder (${homeDir}).`);
+    process.exit(1);
+  }
+
+  // Check for existing installation
+  const stellarPath = path.join(targetDir, STELLAR_DIR);
+  const hasExisting = fs.existsSync(stellarPath);
+
+  if (hasExisting) {
+    const actionChoice = await prompts.select({
+      message: 'Stellar Agent is already installed here. What would you like to do?',
+      choices: [
+        { name: 'Update (refresh skills, preserve config)', value: 'update' },
+        { name: 'Cancel', value: 'cancel' },
+      ],
+    });
+    if (actionChoice === 'cancel') {
+      await prompts.cancel('Installation cancelled.');
+      process.exit(0);
+    }
+  }
+
+  // Gather config
+  const userName = await prompts.text({
+    message: 'What should agents call you?',
+    default: os.userInfo().username,
+  });
+
+  const projectName = await prompts.text({
+    message: 'What is your Stellar project called?',
+    default: path.basename(targetDir),
+  });
+
+  const networkPreference = await prompts.select({
+    message: 'Which Stellar network are you primarily developing for?',
+    choices: [
+      { name: 'Testnet — Safe development environment', value: 'testnet' },
+      { name: 'Mainnet — Production deployment', value: 'mainnet' },
+      { name: 'Futurenet — Cutting-edge feature testing', value: 'futurenet' },
+    ],
+  });
+
+  const primaryLanguage = await prompts.select({
+    message: 'What is your primary development language?',
+    choices: [
+      { name: 'JavaScript/TypeScript — dApp and SDK development', value: 'typescript' },
+      { name: 'Rust — Soroban smart contracts', value: 'rust' },
+      { name: 'Python — Analytics and automation', value: 'python' },
+      { name: 'Full stack — Both TypeScript and Rust', value: 'fullstack' },
+    ],
+  });
+
+  const communicationLanguage = await prompts.text({
+    message: 'What language should agents use when chatting with you?',
+    default: 'English',
+  });
+
+  const config = {
+    user_name: userName,
+    project_name: projectName,
+    network_preference: networkPreference,
+    primary_language: primaryLanguage,
+    communication_language: communicationLanguage,
+  };
+
+  // Install
+  const spinner = await prompts.spinner();
+  spinner.start('Installing Stellar Agent...');
+
+  try {
+    await installStellarAgent(targetDir, config);
+    spinner.stop('Stellar Agent installed successfully!');
+  } catch (err) {
+    spinner.error(`Installation failed: ${err.message}`);
+    process.exit(1);
+  }
+
+  const color = await prompts.getColor();
+  await prompts.outro(
+    [
+      color.green('Get started:'),
+      '',
+      '  1. Open your AI assistant in this project folder',
+      '  2. Invoke stellar-help to see available skills',
+      `  3. Say "@stellar-developer" to start building Soroban contracts`,
+      '     or "@stellar-architect" to design your system first',
+      '',
+      `  Network: ${color.cyan(networkPreference)}  |  Language: ${color.cyan(primaryLanguage)}`,
+    ].join('\n')
+  );
+}
+
+module.exports = {
+  command: 'init',
+  description: 'Initialize Stellar Agent in your project',
+  options: [],
+  action,
+};