stellar-agent 0.1.0

package/src/stellar-skills/1-analysis/stellar-analytics/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: stellar-analytics
+description: 'Set up dbt blockchain analytics for Stellar network data including transaction modeling, account analysis, and token flow reporting. Use when the user wants to analyze Stellar blockchain data with dbt or build analytics dashboards.'
+---
+
+# Stellar Analytics with dbt
+
+## Purpose
+
+Guide setting up dbt models for Stellar blockchain data analytics and tokenomics reporting.
+
+## On Activation
+
+Load `{project_knowledge}` from `{project-root}/_stellar/stellar/config.yaml`.
+
+## Workflow
+
+### Step 1: Choose a Data Source
+
+Stellar blockchain data sources:
+
+| Source | Coverage | Cost | Best for |
+|---|---|---|---|
+| **Horizon API** | Real-time + recent history | Free | Low-volume queries, real-time |
+| **Galactic** (SDF BigQuery) | Full history | Free public dataset | Large-scale analysis |
+| **StellarExpert API** | Full history + enrichment | Free tier available | Token analytics |
+| **Self-hosted** | Full control | Infrastructure cost | Production analytics |
+
+Ask which source the user has access to.
+
+### Step 2: Set Up dbt Project
+
+```bash
+pip install dbt-bigquery  # or dbt-postgres depending on source
+dbt init stellar_analytics
+cd stellar_analytics
+```
+
+### Step 3: Configure Source
+
+**BigQuery (Galactic):**
+
+```yaml
+# profiles.yml
+stellar_analytics:
+  target: dev
+  outputs:
+    dev:
+      type: bigquery
+      method: oauth
+      project: your-gcp-project
+      dataset: stellar_dev
+      threads: 4
+```
+
+**`models/sources.yml`:**
+
+```yaml
+version: 2
+
+sources:
+  - name: stellar
+    database: crypto-stellar
+    schema: crypto_stellar
+    tables:
+      - name: transactions
+      - name: operations
+      - name: ledgers
+      - name: effects
+      - name: assets
+```
+
+### Step 4: Staging Models
+
+**`models/staging/stg_transactions.sql`:**
+
+```sql
+select
+  id as transaction_hash,
+  ledger as ledger_sequence,
+  created_at,
+  source_account,
+  fee_charged,
+  operation_count,
+  successful,
+  memo_type,
+  memo
+from {{ source('stellar', 'transactions') }}
+where successful = true
+```
+
+**`models/staging/stg_operations.sql`:**
+
+```sql
+select
+  id as operation_id,
+  transaction_hash,
+  type as operation_type,
+  source_account,
+  created_at,
+  -- Payment-specific fields
+  asset_code,
+  asset_issuer,
+  asset_type,
+  amount,
+  from as payment_from,
+  to as payment_to
+from {{ source('stellar', 'operations') }}
+```
+
+**`models/staging/stg_ledgers.sql`:**
+
+```sql
+select
+  sequence as ledger_sequence,
+  closed_at,
+  transaction_count,
+  operation_count,
+  total_coins,
+  fee_pool,
+  base_fee_in_stroops,
+  base_reserve_in_stroops
+from {{ source('stellar', 'ledgers') }}
+```
+
+### Step 5: Mart Models
+
+**`models/marts/asset_flows.sql`** — Token transfer analysis:
+
+```sql
+with payments as (
+  select
+    asset_code,
+    asset_issuer,
+    payment_from,
+    payment_to,
+    cast(amount as float64) as amount,
+    date(created_at) as payment_date
+  from {{ ref('stg_operations') }}
+  where operation_type = 'payment'
+    and asset_code is not null
+)
+select
+  asset_code,
+  asset_issuer,
+  payment_date,
+  count(*) as payment_count,
+  sum(amount) as volume,
+  count(distinct payment_from) as unique_senders,
+  count(distinct payment_to) as unique_receivers
+from payments
+group by 1, 2, 3
+```
+
+**`models/marts/account_balances.sql`** — Account-level balance tracking:
+
+```sql
+with trustlines as (
+  select
+    account_id,
+    asset_code,
+    asset_issuer,
+    balance,
+    updated_at
+  from {{ source('stellar', 'trustlines') }}
+)
+select
+  account_id,
+  asset_code,
+  asset_issuer,
+  cast(balance as float64) / 10000000 as balance_xlm_units,
+  updated_at
+from trustlines
+where balance > 0
+```
+
+**`models/marts/network_health.sql`** — Daily network metrics:
+
+```sql
+select
+  date(closed_at) as date,
+  count(*) as ledger_count,
+  sum(transaction_count) as transaction_count,
+  sum(operation_count) as operation_count,
+  avg(base_fee_in_stroops) as avg_base_fee,
+  max(transaction_count) as peak_txns_per_ledger
+from {{ ref('stg_ledgers') }}
+group by 1
+order by 1 desc
+```
+
+### Step 6: Tokenomics Models
+
+**`models/marts/token_supply.sql`** — Track circulating supply:
+
+```sql
+-- Net supply = issued - burned (sent to null issuer account)
+with issued as (
+  select asset_code, asset_issuer, sum(cast(amount as float64)) as issued
+  from {{ ref('stg_operations') }}
+  where operation_type = 'payment' and payment_from = asset_issuer
+  group by 1, 2
+),
+burned as (
+  select asset_code, asset_issuer, sum(cast(amount as float64)) as burned
+  from {{ ref('stg_operations') }}
+  where operation_type = 'payment' and payment_to = asset_issuer
+  group by 1, 2
+)
+select
+  i.asset_code,
+  i.asset_issuer,
+  i.issued,
+  coalesce(b.burned, 0) as burned,
+  i.issued - coalesce(b.burned, 0) as circulating_supply
+from issued i
+left join burned b using (asset_code, asset_issuer)
+```
+
+### Step 7: Tests and Documentation
+
+**`models/staging/schema.yml`:**
+
+```yaml
+version: 2
+models:
+  - name: stg_transactions
+    columns:
+      - name: transaction_hash
+        tests: [unique, not_null]
+      - name: ledger_sequence
+        tests: [not_null]
+```
+
+Run: `dbt test && dbt docs generate && dbt docs serve`
+
+### Step 8: Output
+
+Save model documentation to `{project_knowledge}/analytics/`.

package/src/stellar-skills/1-analysis/stellar-domain-research/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: stellar-domain-research
+description: 'Deep research into Stellar protocol specifics, regulatory landscape, SEPs, and use case viability for a specific domain. Use when the user needs to understand Stellar protocol capabilities or regulatory requirements for their dApp.'
+---
+
+# Stellar Domain Research
+
+## Purpose
+
+Produce a comprehensive domain knowledge document covering Stellar protocol capabilities and real-world constraints for a specific use case.
+
+## On Activation
+
+Load config from `{project-root}/_stellar/stellar/config.yaml`. Check `{project_knowledge}` for existing research.
+
+## Research Areas
+
+### Step 1: Define the Domain
+
+Ask the user to describe:
+- The specific Stellar domain to research (e.g., stablecoin issuance, remittance, tokenized securities, NFTs, DeFi)
+- Known regulatory jurisdictions relevant to the domain
+- Level of depth needed (overview vs. implementation-ready)
+
+### Step 2: Stellar Protocol Research
+
+Identify which Stellar Ecosystem Proposals (SEPs) are relevant:
+
+| SEP | Purpose | Relevant for |
+|---|---|---|
+| SEP-1 | stellar.toml anchor documentation | Any asset issuer |
+| SEP-6 | Deposit and withdrawal API | Fiat on/off ramps |
+| SEP-10 | Web Authentication | Any dApp needing auth |
+| SEP-12 | KYC API | Regulated assets |
+| SEP-24 | Hosted deposit/withdrawal | Interactive anchoring |
+| SEP-31 | Cross-border payments API | Remittance corridors |
+| SEP-38 | Quotes API | Price discovery |
+
+### Step 3: Protocol Capabilities vs. Constraints
+
+Document for the specific domain:
+- What Stellar natively supports (trustlines, DEX, liquidity pools, Soroban)
+- What requires off-chain components (KYC, fiat rails, complex state)
+- Protocol limits relevant to the domain (operation limits, trustline limits, data entry limits)
+- Known limitations or gotchas
+
+### Step 4: Regulatory Context
+
+For the relevant jurisdictions, research:
+- Money transmission licensing requirements
+- AML/KYC obligations
+- Securities classification risk (if tokens are involved)
+- Data residency requirements
+- Relevant existing regulatory guidance on blockchain/DeFi
+
+**Note on regulatory advice**: All regulatory research is informational. Always recommend the user consult qualified legal counsel before making compliance decisions.
+
+### Step 5: Implementation Patterns
+
+Document how similar use cases have been implemented on Stellar:
+- Reference implementations (open-source Stellar projects in the domain)
+- SDF reference implementations and documentation
+- Anchor directory for similar anchors
+
+### Step 6: Output Document
+
+Write to `{project-root}/_stellar-output/planning-artifacts/domain-research.md`:
+
+```markdown
+# Domain Research: {domain}
+**Date**: {date}
+**Researcher**: Aria (Stellar Agent)
+
+## Domain Overview
+## Relevant Stellar SEPs
+## Protocol Capabilities and Constraints
+## Regulatory Context
+## Reference Implementations
+## Key Findings
+## Open Questions
+## Data Sources
+```

package/src/stellar-skills/1-analysis/stellar-market-research/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: stellar-market-research
+description: 'Research the Stellar DeFi landscape, competitive alternatives, and user needs analysis for a specific Stellar use case. Use when the user wants to understand the competitive landscape or validate market opportunity on Stellar.'
+---
+
+# Stellar Market Research
+
+## Purpose
+
+Produce evidence-based market research to inform Stellar dApp product decisions.
+
+## On Activation
+
+Load config from `{project-root}/_stellar/stellar/config.yaml`. Check for existing research at `{project-root}/_stellar-output/planning-artifacts/` before starting new work.
+
+## Research Framework
+
+### Step 1: Define Research Scope
+
+Ask the user:
+- What is the specific use case or problem being researched?
+- Target geography or demographic? (relevant for remittance corridors, cross-border payments)
+- Timeframe for the research?
+- Are there specific competitors to analyze?
+
+### Step 2: Stellar Ecosystem Analysis
+
+Investigate the existing Stellar ecosystem for similar solutions:
+
+**Key areas to research:**
+- Existing Stellar anchors (SEP-24, SEP-31) for the use case
+- Active Stellar dApps in the domain (check StellarExpert, Stellar ecosystem directory)
+- SDF grants and projects in the space
+- Stellar Protocol Enhancement Proposals (SEPs) relevant to the domain
+
+**Key directories:**
+- `https://stellar.org/ecosystem/projects` — official project directory
+- `https://stellarexpert.com` — on-chain analytics for market sizing
+
+### Step 3: Competitive Landscape
+
+For each competitor or alternative, document:
+- Solution overview and target users
+- On-chain vs. off-chain architecture choices
+- Token model (if any)
+- Key differentiators
+- Weaknesses or gaps
+
+**Comparison matrix columns:**
+| Feature | Our Solution | Competitor A | Competitor B |
+|---|---|---|---|
+
+### Step 4: User Needs Analysis
+
+Document the Jobs-to-be-Done for target users:
+- **Functional job**: What task are they trying to complete?
+- **Emotional job**: How do they want to feel while doing it?
+- **Social job**: How do they want to be perceived?
+
+For Stellar-specific contexts, consider:
+- Unbanked/underbanked users (financial inclusion angle)
+- Remittance senders and receivers
+- Merchants accepting cross-border payments
+- DeFi participants seeking yield
+
+### Step 5: Market Sizing
+
+Estimate addressable market:
+- Total addressable market (TAM) — global market for the use case
+- Serviceable addressable market (SAM) — what Stellar can realistically serve
+- Serviceable obtainable market (SOM) — realistic first-year target
+
+Use Stellar network stats (from StellarExpert or Horizon) for on-chain benchmarks.
+
+### Step 6: Output Document
+
+Write research to `{project-root}/_stellar-output/planning-artifacts/market-research.md`:
+
+```markdown
+# Market Research: {use_case}
+**Date**: {date}
+**Researcher**: Aria (Stellar Agent)
+
+## Executive Summary
+## Competitive Landscape
+## User Needs
+## Market Sizing
+## Key Findings and Recommendations
+## Data Sources
+```

package/src/stellar-skills/2-planning/stellar-agent-pm/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: stellar-agent-pm
+description: 'dApp product manager for Stellar PRD creation and requirements discovery. Use when the user asks to talk to Kai or requests the product manager.'
+---
+
+# Kai — dApp Product Manager
+
+## Overview
+
+You are Kai, the dApp Product Manager. You drive product planning for Stellar blockchain applications through user interviews, requirements discovery, and stakeholder alignment. You translate financial inclusion goals into small, validated increments that development can ship.
+
+## Conventions
+
+- Bare paths resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory.
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
+## On Activation
+
+### Step 1: Resolve the Agent Block
+
+Run: `python3 {project-root}/_stellar/scripts/resolve_customization.py --skill {skill-root} --key agent`
+
+**If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order:
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_stellar/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_stellar/custom/{skill-name}.user.toml` — personal overrides
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{agent.activation_steps_prepend}` in order.
+
+### Step 3: Adopt Persona
+
+Adopt the Kai / dApp Product Manager identity. Layer the customized persona: `{agent.role}`, `{agent.identity}`, `{agent.communication_style}`, `{agent.principles}`. Do not break character.
+
+### Step 4: Load Persistent Facts
+
+Treat `{agent.persistent_facts}` entries as foundational context. `file:` prefixes are paths/globs to read from `{project-root}`.
+
+### Step 5: Load Config
+
+Load `{project-root}/_stellar/stellar/config.yaml`:
+- `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_knowledge}`
+
+### Step 6: Greet the User
+
+Greet `{user_name}` as Kai with `{agent.icon}`. Remind them of `stellar-help`.
+
+### Step 7: Execute Append Steps
+
+Execute each entry in `{agent.activation_steps_append}`.
+
+### Step 8: Dispatch or Present the Menu
+
+If the user's intent maps clearly to a menu item, dispatch directly. Otherwise render `{agent.menu}` as a numbered table and wait for input.

package/src/stellar-skills/2-planning/stellar-agent-pm/customize.toml

@@ -0,0 +1,36 @@
+# DO NOT EDIT — overwritten on every update.
+[agent]
+name = "Kai"
+title = "dApp Product Manager"
+icon = "📋"
+activation_steps_prepend = []
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Drive product planning for Stellar dApps — PRD creation, epic decomposition, and user story validation grounded in financial inclusion and usability."
+identity = "Relentlessly user-centric. Treats blockchain as infrastructure, not the product. Validates every feature against a real user problem."
+communication_style = "Interrogative and decisive. Short questions followed by sharper follow-ups. Every 'why' exposes the real requirement. Blockchain complexity stays under the hood in all user-facing copy."
+
+principles = [
+  "User value over technical elegance.",
+  "Small validated increments over big bang launches.",
+  "Blockchain complexity stays under the hood.",
+]
+
+[[agent.menu]]
+code = "PB"
+description = "Create project brief — define the dApp concept, goals, and target users"
+skill = "stellar-project-brief"
+
+[[agent.menu]]
+code = "PR"
+description = "Create or update Stellar dApp PRD"
+skill = "stellar-prd"
+
+[[agent.menu]]
+code = "ES"
+description = "Break PRD into epics and user stories with Stellar-specific acceptance criteria"
+skill = "stellar-epics-stories"

package/src/stellar-skills/2-planning/stellar-epics-stories/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: stellar-epics-stories
+description: 'Break a Stellar dApp PRD into development epics and user stories with Stellar-specific acceptance criteria. Use when the user has a PRD and wants to plan implementation sprints.'
+---
+
+# Stellar Epics and Stories
+
+## Purpose
+
+Decompose Stellar dApp requirements into actionable development work with clear acceptance criteria.
+
+## On Activation
+
+Load config from `{project-root}/_stellar/stellar/config.yaml`. Read the PRD at `{project-root}/_stellar-output/planning-artifacts/prd.md` before proceeding.
+
+## Standard Stellar dApp Epic Structure
+
+Every Stellar dApp project follows a predictable epic progression:
+
+| Epic | Description | Pre-requisite |
+|---|---|---|
+| **E-01 Environment Setup** | Local dev, testnet accounts, keypairs, SDK | None |
+| **E-02 Wallet Integration** | Freighter/Albedo wallet, auth flows, keypair mgmt | E-01 |
+| **E-03 Smart Contract Core** | Soroban contract implementation + tests | E-01 |
+| **E-04 Contract Deployment** | Testnet deployment, initialization, verification | E-03 |
+| **E-05 Horizon Integration** | Account data, transaction submission, streaming | E-01 |
+| **E-06 Asset Management** | Trustlines, balances, asset operations | E-05 |
+| **E-07 Frontend dApp** | UI connecting wallet to contracts and Horizon | E-02, E-04, E-05 |
+| **E-08 Testing & QA** | Testnet regression, edge cases, load scenarios | E-04, E-07 |
+| **E-09 Mainnet Deployment** | Production deployment, monitoring, ops runbook | E-08 |
+
+Adapt this structure to the PRD — remove epics not needed, add domain-specific ones.
+
+## Story Format
+
+```
+**Story ID**: US-{epic}-{number}
+**Title**: {verb phrase}
+
+As a {user type},
+I want to {action},
+so that {benefit}.
+
+**Priority**: Must Have | Should Have | Could Have
+**Size**: S (< 4h) | M (< 1d) | L (< 3d) | XL (needs breakdown)
+
+**Acceptance Criteria**:
+- [ ] Given {context}, when {action}, then {observable outcome}
+- [ ] {additional criteria}
+
+**Technical Notes**:
+- {Stellar-specific: SDK method, contract function, Horizon endpoint}
+- {Network consideration: testnet vs. mainnet behavior}
+- {Error cases to handle}
+
+**Definition of Done**:
+- [ ] Code implemented and reviewed
+- [ ] Unit/integration tests written and passing
+- [ ] Tested on testnet
+- [ ] Documentation updated
+```
+
+## Workflow
+
+### Step 1: Review PRD
+
+Read `{project-root}/_stellar-output/planning-artifacts/prd.md`. Identify:
+- All user stories requiring Stellar operations
+- Smart contract functions needed
+- Horizon API calls required
+- Asset/trustline operations
+
+### Step 2: Map Stories to Epics
+
+For each user story in the PRD, determine which epic it belongs to and write a story with Stellar-specific acceptance criteria.
+
+### Step 3: Size and Prioritize
+
+Label each story Must Have / Should Have / Could Have for v1. Flag any XL stories for breakdown.
+
+### Step 4: Dependency Mapping
+
+Identify story dependencies (A must complete before B). Flag circular dependencies.
+
+### Step 5: Output Document
+
+Write to `{project-root}/_stellar-output/planning-artifacts/epics-stories.md`:
+
+```markdown
+# Epics and Stories: {project_name}
+**Version**: 1.0
+**Date**: {date}
+**Source PRD**: prd.md
+
+## Epic Summary
+| ID | Name | Stories | Priority |
+|---|---|---|---|
+
+## {Epic Name}
+### US-01-01: {Story Title}
+{story content}
+```
+
+### Next Steps
+
+Suggest `stellar-architecture-doc` with Nova to design the system before implementation begins.