stellar-agent 0.2.0 → 0.3.0

package/src/stellar-skills/5-mentorship/stellar-submission-prep/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: stellar-submission-prep
+description: 'Final pre-submission checklist for Stellar/Soroban hackathons — repo polish, README, demo video, deployed testnet, contract IDs, Devpost/SCF/SDF form. Use when the user is in the last 2 hours before deadline, ready to hit submit, or verifying the submission is complete.'
+---
+
+# Submission Prep
+
+## Purpose
+
+Run the final checklist in the last 2 hours before submission. Catch the 5-minute fixes that cost the team a track win — missing testnet contract ID in README, demo video not uploaded, repo still private, team members not invited to Devpost.
+
+## On Activation
+
+Load:
+- `{planning_artifacts}/hackathon-brief.md`
+- `{implementation_artifacts}/demo-storyboard.md`
+- `{implementation_artifacts}/deployed-contracts.md` (if it exists)
+
+Check the submission deadline. Surface hours remaining at the top of the response.
+
+## Workflow
+
+### Step 1: Surface Hours Remaining
+
+```
+⏳ Hours remaining: <X>
+
+Recommended order for last 2h:
+  T-2:00  →  Repository polish
+  T-1:30  →  README final pass
+  T-1:00  →  Demo video uploaded
+  T-0:30  →  Submission form
+  T-0:15  →  Buffer for re-submission
+```
+
+If hours remaining < 0.5, skip non-critical items. Get the submission in first; polish after if time allows.
+
+### Step 2: Repository Checklist
+
+```markdown
+## Repository
+
+- [ ] Public GitHub repo (not private — judges can't see private repos)
+- [ ] Default branch is `main` and reflects the submitted code
+- [ ] Repo URL has been tested in an incognito window
+- [ ] `LICENSE` file present (MIT or Apache-2.0 is the safe default)
+- [ ] `.gitignore` excludes: `target/`, `node_modules/`, `.env`, `*.wasm`, keypair files
+- [ ] No secrets committed — grep for: `PRIVATE_KEY`, `S...` (raw secrets), `password`, `api_key`
+- [ ] All team members are repo collaborators (or visibly active in commits)
+- [ ] Last commit is from a hackathon-time window (judges check timestamps)
+```
+
+If the repo is currently private, **make it public now**. Some hackathons disqualify private submissions outright.
+
+### Step 3: README Checklist
+
+The README is the front door. A judge who can't run the project in 5 minutes moves on.
+
+```markdown
+## README must include
+
+- [ ] One-line pitch at the top (`# <Project name>` + tagline)
+- [ ] One screenshot or GIF in the first scroll height
+- [ ] Demo video link (unlisted YouTube or hosted MP4)
+- [ ] Live demo URL (if web-accessible) OR a "try it" section
+- [ ] Install + run instructions a judge can copy-paste
+- [ ] Testnet contract ID(s) with `stellar.expert` link
+- [ ] At least one successful tx hash linked from `stellar.expert`
+- [ ] Built-with stack (Soroban, Stellar SDK, Next.js, etc.)
+- [ ] Team section with handles
+- [ ] License
+```
+
+#### README template skeleton
+
+```markdown
+# <Project name>
+
+> <One-sentence tagline>
+
+![<Screenshot>](docs/screenshot.png)
+
+**Demo video:** <youtube link>
+**Live demo:** <url>
+**Testnet contract:** [`<CONTRACT_ID>`](https://stellar.expert/explorer/testnet/contract/<CONTRACT_ID>)
+**Example tx:** [`<TX_HASH>`](https://stellar.expert/explorer/testnet/tx/<TX_HASH>)
+
+## Problem
+
+<2–3 sentences>
+
+## Solution
+
+<2–3 sentences>
+
+## How it works
+
+<3 bullets describing the on-chain flow>
+
+## Install
+
+\`\`\`bash
+git clone <repo>
+cd <repo>
+npm install   # or: cargo build --target wasm32-unknown-unknown --release
+cp .env.example .env
+npm run dev
+\`\`\`
+
+## Stack
+
+- Soroban smart contracts (Rust)
+- @stellar/stellar-sdk (TypeScript)
+- Next.js App Router
+- Freighter wallet
+
+## Team
+
+- <Name> (@handle) — <what they built>
+
+## License
+
+MIT
+```
+
+### Step 4: On-Chain Verification
+
+```markdown
+## On-chain checklist
+
+- [ ] Contract deployed to testnet — record contract ID in README
+- [ ] Contract initialized (`initialize` or equivalent) — verify with `stellar contract invoke ... -- get_*`
+- [ ] At least one successful tx hash linked from README
+- [ ] If using a custom asset: issuing account + trustline tx hash documented
+- [ ] If using SEP-10: auth endpoint live and returning valid JWTs
+```
+
+Quick verification commands:
+```bash
+# Confirm contract is alive
+stellar contract invoke \
+  --id <CONTRACT_ID> \
+  --network testnet \
+  -- <view_function>
+
+# Confirm a tx
+curl -s "https://horizon-testnet.stellar.org/transactions/<TX_HASH>" | jq '.successful'
+```
+
+### Step 5: Demo Video Checklist
+
+```markdown
+## Demo video
+
+- [ ] Recorded at 1080p+ (1920×1080 minimum)
+- [ ] Length: 60–180s (check hackathon spec)
+- [ ] Audio narration audible (no static, no clipping)
+- [ ] Uploaded to YouTube as **unlisted** (NOT private — judges can't see private)
+- [ ] OR hosted on Vimeo / direct MP4 — link works in incognito
+- [ ] Linked from README
+- [ ] Linked from submission form
+- [ ] Thumbnail is a meaningful frame (not black, not the OS desktop)
+```
+
+### Step 6: Submission Form Checklist
+
+The exact form depends on the platform (Devpost, SCF, SDF, Discord). Common fields:
+
+```markdown
+## Submission form
+
+- [ ] Project title (matches repo name)
+- [ ] Tagline (one sentence)
+- [ ] Description (2–3 paragraphs — pull from README)
+- [ ] Built-with tags include: `stellar`, `soroban`, language stack, frameworks
+- [ ] Track selection confirmed (from `TR` recommendation)
+- [ ] GitHub URL
+- [ ] Demo video URL
+- [ ] Live demo URL (if applicable)
+- [ ] Testnet contract ID in the body
+- [ ] Team members invited and they have **accepted** the invite (Devpost especially — unaccepted invites disqualify)
+- [ ] Selected for the right hackathon (verify the URL on the submission page)
+- [ ] Submission saved as draft once, then submitted (in case of platform error)
+```
+
+### Step 7: Final Sanity Checks
+
+Before hitting "Submit":
+
+- [ ] Open the GitHub repo in an incognito window — it loads, README renders
+- [ ] Click the demo video link in incognito — it plays
+- [ ] Click the testnet contract link in incognito — stellar.expert shows the contract
+- [ ] Submission form preview matches what's in your README
+
+### Step 8: Submit and Confirm
+
+After submission:
+- [ ] Screenshot the "Submission received" page
+- [ ] Confirmation email received (check spam)
+- [ ] Submission visible on the public hackathon submission page (some platforms have a delay)
+
+If anything fails, you have the buffer window in Step 1 to fix and resubmit.
+
+### Step 9: Sign-off
+
+Pera signs off when the checklist is green:
+
+> "Submitted. Hands off the keyboard. Get sleep."
+
+Add a `## Submission` section to `{planning_artifacts}/hackathon-brief.md` capturing:
+- Final submission timestamp
+- Submission URL
+- Track submitted
+- Confirmation screenshot path
+
+## Anti-patterns to flag
+
+- **Submitting at T-0 minutes.** Always submit at T-30 minimum. Platforms get flaky under deadline load.
+- **Private repos / private videos.** Disqualifies the submission silently.
+- **Unaccepted team invites.** Some platforms (Devpost) only credit accepted team members.
+- **Submitting and then pushing more commits.** The submission snapshot is what's judged. Don't introduce regressions after submitting.
+- **Skipping the incognito test.** Cookies hide private/draft state. Always verify in incognito.
+
+## Output
+
+- Final state of `{planning_artifacts}/hackathon-brief.md` with `## Submission` section
+- All checklist items confirmed before final submit
+
+## Next Steps
+
+After submission:
+- Get sleep.
+- Prepare for live judging Q&A — review `{planning_artifacts}/judge-qa.md` if a live round is scheduled.
+- Plan a mainnet follow-up only after the team has rested.

package/src/stellar-skills/5-mentorship/stellar-track-recommendation/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: stellar-track-recommendation
+description: 'Match a hackathon idea to the right Stellar/Soroban track and surface the judging rubric for that track. Use when the user is undecided between tracks, wants to know which track fits their idea best, or needs to read the rubric before building.'
+---
+
+# Track Recommendation
+
+## Purpose
+
+Pick the right hackathon track for the idea. The wrong track punishes the team twice — judges score against criteria the build wasn't optimized for, and the team misses the rubric that would've shaped a better build.
+
+## On Activation
+
+Load `{planning_artifacts}/hackathon-brief.md` if it exists. If not, recommend running `IS` (Idea Scoping) first.
+
+If a hackathon URL was provided to Pera on greeting, fetch it now and read the official track list and rubrics. Treat the live page as source of truth — overrides anything below.
+
+## Workflow
+
+### Step 1: Identify Candidate Tracks
+
+Match the idea against the Stellar hackathon track families:
+
+| Track | Best fits | Stellar/Soroban primitive | Judging weight |
+|---|---|---|---|
+| **DeFi** | Lending, AMM, yield, perp/swap, stablecoin mech | Soroban contracts, AMM pools, trustlines | Technical depth · Composability · TVL potential |
+| **Payments** | Cross-border, remittance, micropayments, payroll | Classic Stellar payments, anchors, path payments | UX · Cost per tx · Anchor / SEP integration |
+| **Identity / SEP-10** | KYC, attestation, reputation, gated access | SEP-10 auth, Soroban storage for attestations | Privacy · SEP compliance · Real-world fit |
+| **Gaming / NFT** | On-chain assets, in-game economy, collectibles | Custom assets, Soroban inventory contracts | Player retention · Creative use of Soroban |
+| **RWA / Tokenization** | Real estate, invoices, commodities, carbon | Custom assets + Soroban escrow + oracles | Legal viability · Oracle design · Trust model |
+| **Infra / DevTools** | SDKs, dashboards, oracles, indexers | Anything that helps other devs ship on Stellar | Developer adoption · Reusability |
+| **Open / Other** | Idea doesn't fit above | Anything | Innovation · Demo · Business potential |
+
+### Step 2: Score the Idea Against Each Candidate
+
+For each candidate track, produce a 3-line block:
+
+```
+<Track>
+Fit: <high | medium | low> — <one-line reason>
+Win condition: <what would the judges score highly>
+Risk: <what the judges will challenge>
+```
+
+If two tracks score `high`, prefer the one with:
+- Smaller judging field (less competition)
+- Rubric the build naturally aligns to without rework
+
+### Step 3: Recommend
+
+Output:
+
+```markdown
+## Track recommendation
+
+**Primary:** <track>
+**Why:** <one sentence — the strongest rubric alignment>
+**Risk to mitigate:** <what to harden before submission>
+
+**Secondary (if primary doesn't fit at submission):** <track>
+```
+
+### Step 4: Pull the Rubric
+
+If the hackathon URL is known, extract the official rubric from the page. Otherwise use the generic Stellar judging rubric:
+
+| Criterion | Default weight | Notes |
+|---|---|---|
+| Innovation | 25% | "Have we seen this before on Stellar?" |
+| Technical implementation | 25% | Soroban depth, code quality, test coverage |
+| Business / impact | 25% | Who pays, how big, distribution path |
+| Demo quality | 25% | Recording, narration, on-chain proof |
+
+Append to `{planning_artifacts}/hackathon-brief.md` as a `## Track + rubric` section.
+
+### Step 5: Confirm
+
+Ask the user: *"Locking in `<track>` — proceed?"*
+
+If yes, suggest `MV` next.
+If no, present the secondary or ask what's missing.
+
+## Common mistakes
+
+- **Picking DeFi by default.** DeFi is the most crowded track at most Stellar hackathons. A "DeFi-lite" idea in Payments or Identity often wins more easily.
+- **Picking a track because the team likes it.** Track choice is about rubric fit, not preference.
+- **Ignoring the official rubric.** Always pull the actual hackathon's rubric over generic priors. Hackathons weight criteria differently.
+- **Multi-track submissions.** Most Stellar hackathons only allow one track. Picking two splits attention.
+
+## Output
+
+Updates `{planning_artifacts}/hackathon-brief.md` with the chosen track and the rubric the build must align to.
+
+## Next Steps
+
+- `stellar-mvp-definition` (MV) — cut the feature list against the chosen rubric
+- `stellar-judging-criteria` (JC) — when the MVP is locked, map it to the rubric line-by-line

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

@@ -3,11 +3,13 @@ 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-known-assets,Known Assets Registry,KA,Look up canonical Stellar asset issuer addresses (USDC EURC AQUA yXLM) with provenance and verification commands. Prevents issuer hallucination.,,,1-analysis,,,false,,
 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-doctor,Stellar Doctor,SD,Diagnose toolchain network reachability wallet state contract state and project context. Run before any deployment.,,,4-implementation,,,false,,
 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
@@ -22,3 +24,10 @@ Stellar,stellar-nextjs-wallet,Next.js Wallet,NW,Integrate Freighter wallet into
 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
+Stellar,stellar-idea-scoping,Idea Scoping,IS,Pressure-test the hackathon idea against the build window and produce a one-page brief with cut list.,,,5-mentorship,,,false,{planning_artifacts},hackathon-brief
+Stellar,stellar-track-recommendation,Track Recommendation,TR,Match the idea to the right Stellar/Soroban hackathon track and pull the judging rubric.,,,5-mentorship,stellar-idea-scoping,,false,{planning_artifacts},track-decision
+Stellar,stellar-mvp-definition,MVP Definition,MV,Split features into must-have / nice-to-have / skip with hour estimates and a 25% buffer rule.,,,5-mentorship,stellar-idea-scoping,,false,{planning_artifacts},mvp-cut
+Stellar,stellar-judging-criteria,Judging Criteria,JC,Reverse-map the build to the judging rubric and identify gaps before they cost points.,,,5-mentorship,stellar-mvp-definition,,false,{planning_artifacts},rubric-alignment
+Stellar,stellar-demo-prep,Demo Prep,DM,Build the hackathon demo storyboard 2-3 min script and recording checklist with common failure modes.,,,5-mentorship,stellar-mvp-definition,,false,{implementation_artifacts},demo-storyboard
+Stellar,stellar-pitch-coaching,Pitch Coaching,PC,Build the hackathon pitch 3-minute deck outline elevator pitch and judge Q&A drill.,,,5-mentorship,stellar-demo-prep,,false,{planning_artifacts},pitch-script
+Stellar,stellar-submission-prep,Submission Prep,SP,Final pre-submission checklist repo polish README demo video deployed testnet contract IDs and submission form.,,,5-mentorship,stellar-pitch-coaching,,false,{planning_artifacts},submission-confirmation

package/tools/installer/commands/init.js

@@ -54,6 +54,7 @@ async function installStellarAgent(targetDir, config) {
     planning_artifacts: `${OUTPUT_DIR}/planning-artifacts`,
     implementation_artifacts: `${OUTPUT_DIR}/implementation-artifacts`,
     project_knowledge: 'docs',
+    skills_version: config.skills_version,
   };
   await fsp.writeFile(
     path.join(stellarDir, 'stellar', 'config.yaml'),
@@ -64,6 +65,7 @@ async function installStellarAgent(targetDir, config) {
   // Write manifest
   const manifest = {
     version: require('../../../package.json').version,
+    skills_version: config.skills_version,
     installed_at: new Date().toISOString(),
     project_name: config.project_name,
   };
@@ -226,8 +228,23 @@ description = "Hackathon mentor — scopes ideas to the timebox, picks the track
 }
 
 async function action(options) {
+  const pkgVersion = require('../../../package.json').version;
+  const requestedVersion = options?.skills || pkgVersion;
+
+  // Pinning warning — we don't ship multi-version download support yet
+  if (requestedVersion !== pkgVersion) {
+    console.error(
+      `⚠️  Skills version mismatch.\n` +
+      `   You requested: ${requestedVersion}\n` +
+      `   This package:  ${pkgVersion}\n\n` +
+      `   To pin to a different version, run:\n` +
+      `     npx stellar-agent@${requestedVersion} init\n\n` +
+      `   Continuing with ${pkgVersion}...\n`
+    );
+  }
+
   await CLIUtils.displayLogo();
-  await prompts.intro('Stellar Agent — AI agent team for Stellar blockchain development');
+  await prompts.intro(`Stellar Agent v${pkgVersion} — AI agent team for Stellar blockchain development`);
 
   // Directory selection
   const rawDir = await prompts.text({
@@ -307,6 +324,7 @@ async function action(options) {
     network_preference: networkPreference,
     primary_language: primaryLanguage,
     communication_language: communicationLanguage,
+    skills_version: pkgVersion,
   };
 
   // Install
@@ -339,6 +357,8 @@ async function action(options) {
 module.exports = {
   command: 'init',
   description: 'Initialize Stellar Agent in your project',
-  options: [],
+  options: [
+    ['--skills <version>', 'Pin to a specific skills version (defaults to the installed package version)'],
+  ],
   action,
 };

package/tools/installer/commands/mcp.js

@@ -0,0 +1,38 @@
+/**
+ * `stellar-agent mcp` — start the MCP server over stdio.
+ *
+ * Invoked by MCP-aware clients (Claude Desktop, Cline, Continue, Zed)
+ * via their server config:
+ *
+ *   {
+ *     "mcpServers": {
+ *       "stellar-agent": {
+ *         "command": "npx",
+ *         "args": ["stellar-agent", "mcp"]
+ *       }
+ *     }
+ *   }
+ */
+
+const path = require('node:path');
+const { spawn } = require('node:child_process');
+
+async function action() {
+  const serverPath = path.join(__dirname, '..', '..', 'mcp-server', 'server.js');
+  const child = spawn(process.execPath, [serverPath], {
+    stdio: 'inherit',
+  });
+
+  child.on('exit', (code) => process.exit(code ?? 0));
+  child.on('error', (err) => {
+    console.error('Failed to start MCP server:', err);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  command: 'mcp',
+  description: 'Run the Stellar Agent MCP server (stdio). Used by Claude Desktop, Cline, Continue, Zed.',
+  options: [],
+  action,
+};

package/tools/installer/commands/version.js

@@ -0,0 +1,42 @@
+/**
+ * `stellar-agent version` — print CLI version + installed skills version (if any).
+ *
+ * Outputs both:
+ *   - the version of this CLI / npm package
+ *   - the skills version recorded at `_stellar/_config/manifest.yaml`
+ *     if the current directory has stellar-agent installed
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const yaml = require('yaml');
+
+async function action() {
+  const pkg = require('../../../package.json');
+  console.log(`stellar-agent v${pkg.version}`);
+
+  const manifestPath = path.join(process.cwd(), '_stellar', '_config', 'manifest.yaml');
+  if (fs.existsSync(manifestPath)) {
+    try {
+      const manifest = yaml.parse(fs.readFileSync(manifestPath, 'utf8'));
+      console.log(`  installed:     ${manifest.installed_at}`);
+      console.log(`  skills version: ${manifest.skills_version || manifest.version || '(unknown)'}`);
+      console.log(`  project:       ${manifest.project_name || '(unset)'}`);
+      if (manifest.skills_version && manifest.skills_version !== pkg.version) {
+        console.log('');
+        console.log(`  ⚠️  CLI (${pkg.version}) differs from installed skills (${manifest.skills_version}).`);
+        console.log(`     Run \`npx stellar-agent init\` (choose Update) to refresh, or`);
+        console.log(`     run \`npx stellar-agent@${manifest.skills_version} <command>\` to stay pinned.`);
+      }
+    } catch (err) {
+      console.error(`  (could not parse manifest: ${err.message})`);
+    }
+  }
+}
+
+module.exports = {
+  command: 'version',
+  description: 'Print the CLI version and the installed skills version (if any)',
+  options: [],
+  action,
+};

package/tools/installer/stellar-cli.js

@@ -55,7 +55,7 @@ if (process.stdin.isTTY) {
 }
 
 const commandsPath = path.join(__dirname, 'commands');
-const ALLOWED_COMMANDS = ['init'];
+const ALLOWED_COMMANDS = ['init', 'mcp', 'version'];
 
 const commands = {};
 for (const name of ALLOWED_COMMANDS) {