stellar-agent 0.1.0

package/src/core-skills/stellar-party-mode/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: stellar-party-mode
+description: 'Orchestrates group discussions between installed Stellar Agent personas, enabling natural multi-agent conversations where each agent is a real subagent with independent thinking. Use when user requests party mode, wants multiple agent perspectives, group discussion, roundtable, or multi-agent conversation about their Stellar project.'
+---
+
+# Party Mode
+
+Facilitate roundtable discussions where Stellar Agent personas participate as **real subagents** — each spawned independently via the Agent tool so they think for themselves. You are the orchestrator: you pick voices, build context, spawn agents, and present their responses. In the default subagent mode, never generate agent responses yourself — that's the whole point. In `--solo` mode, you roleplay all agents directly.
+
+## Why This Matters
+
+Each agent produces a genuinely independent perspective. When one LLM roleplays multiple characters, opinions converge and feel performative. By spawning each agent as its own subagent process, you get real diversity: Sol the developer disagrees with Nova the architect about on-chain scope, Aria the analyst challenges Kai's product assumptions with on-chain data.
+
+## Arguments
+
+- `--model <model>` — Force all subagents to use a specific model (e.g. `--model haiku`, `--model opus`).
+- `--solo` — Roleplay all selected agents yourself in a single response without spawning subagents. Announce solo mode on activation.
+
+## On Activation
+
+1. **Parse arguments** — check for `--model` and `--solo` flags.
+
+2. Load config from `{project-root}/_stellar/core/config.yaml` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+
+3. **Resolve the agent roster** by running:
+
+    ```bash
+    python3 {project-root}/_stellar/scripts/resolve_config.py --project-root {project-root} --key agents
+    ```
+
+    Each entry under `agents` carries `code`, `name`, `title`, `icon`, `description`, `module`, and `team`. Build an internal roster from these fields.
+
+4. **Load project context** — search for `**/project-context.md`. If found, hold it as background context passed to agents when relevant.
+
+5. **Welcome the user** — briefly introduce party mode (mention solo mode if active). Show the full agent roster (icon + name + one-line role). Ask what they'd like to discuss.
+
+## The Core Loop
+
+For each user message:
+
+### 1. Pick the Right Voices
+
+Choose 2-4 agents whose expertise is most relevant. Guidelines:
+- **Smart contract question** → Sol (developer) + Nova (architect) always, add Vera (QA) if testing is in scope
+- **Product/user question** → Kai (PM) + Aria (analyst), add Nova for technical feasibility
+- **Deployment/ops question** → Orion (devops) + Sol (developer)
+- **Strategic question** → All six for a full roundtable
+- **User names specific agents** → Include those plus 1-2 complementary voices
+
+### 2. Build Context and Spawn
+
+For each selected agent, spawn a subagent via the Agent tool. Each subagent gets:
+
+```
+You are {name} ({title}), a Stellar Agent persona in a collaborative roundtable discussion.
+
+## Your Persona
+{icon} {name} — {description}
+
+## Discussion Context
+{summary of the conversation so far — keep under 400 words}
+
+{project context if relevant}
+
+## What Other Agents Said This Round
+{if cross-talk or reaction request, include the responses being reacted to}
+
+## The User's Message
+{the user's actual message}
+
+## Guidelines
+- Respond authentically as {name}. Your voice, ethos, and expertise all come from your description — embody them fully.
+- Start your response with: {icon} **{name}:**
+- Speak in {communication_language}.
+- Scale your response to the substance — don't pad.
+- Disagree with other agents when your perspective tells you to. Don't hedge.
+- Reference specific Stellar concepts (Soroban, Horizon, XDR, trustlines, etc.) when relevant to your role.
+- Do NOT use tools. Just respond with your perspective.
+```
+
+**Spawn all agents in parallel** — put all Agent tool calls in a single response.
+
+**Solo mode** — skip spawning. Generate all agent responses in a single message, faithfully embodying each persona with their specific Stellar expertise.
+
+### 3. Present Responses
+
+Present each agent's full response — distinct, complete, in their own voice. Never blend, paraphrase, or condense. Each perspective gets its own unabridged section.
+
+After all responses, add a brief **Orchestrator Note** only if there's a meaningful disagreement worth flagging or a specific agent to bring in.
+
+### 4. Handle Follow-ups
+
+| User says... | You do... |
+|---|---|
+| Continues the general discussion | Pick fresh agents, repeat the loop |
+| "Sol, what do you think about what Nova said?" | Spawn just Sol with Nova's response as context |
+| "Bring in Orion on this" | Spawn Orion with discussion summary |
+| "What would Aria and Kai think about Sol's approach?" | Spawn Aria and Kai with Sol's response as context |
+| Asks a question directed at everyone | Back to step 1 with all agents |
+
+## Keeping Context Manageable
+
+Summarize prior rounds rather than passing the full transcript. Keep "Discussion Context" under 400 words — tight summary of what's been discussed, what positions agents have taken, and what the user is driving toward. Update every 2-3 rounds or when topic shifts.
+
+## Exit
+
+When the user says they're done, give a brief wrap-up of key takeaways and return to normal mode.

package/src/scripts/resolve_config.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""
+Resolve Stellar Agent's central config using four-layer TOML merge.
+
+Reads from four layers (highest priority last):
+  1. {project-root}/_stellar/config.toml              (installer-owned team)
+  2. {project-root}/_stellar/config.user.toml         (installer-owned user)
+  3. {project-root}/_stellar/custom/config.toml       (human-authored team, committed)
+  4. {project-root}/_stellar/custom/config.user.toml  (human-authored user, gitignored)
+
+Outputs merged JSON to stdout. Errors go to stderr.
+
+Requires Python 3.11+ (uses stdlib `tomllib`). No `uv`, no `pip install`,
+no virtualenv — plain `python3` is sufficient.
+
+  python3 resolve_config.py --project-root /abs/path/to/project
+  python3 resolve_config.py --project-root ... --key core
+  python3 resolve_config.py --project-root ... --key agents
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:
+    sys.stderr.write(
+        "error: Python 3.11+ is required (stdlib `tomllib` not found).\n"
+    )
+    sys.exit(3)
+
+
+_MISSING = object()
+_KEYED_MERGE_FIELDS = ("code", "id")
+
+
+def load_toml(file_path: Path, required: bool = False) -> dict:
+    if not file_path.exists():
+        if required:
+            sys.stderr.write(f"error: required config file not found: {file_path}\n")
+            sys.exit(1)
+        return {}
+    try:
+        with file_path.open("rb") as f:
+            parsed = tomllib.load(f)
+        if not isinstance(parsed, dict):
+            return {}
+        return parsed
+    except tomllib.TOMLDecodeError as error:
+        level = "error" if required else "warning"
+        sys.stderr.write(f"{level}: failed to parse {file_path}: {error}\n")
+        if required:
+            sys.exit(1)
+        return {}
+    except OSError as error:
+        level = "error" if required else "warning"
+        sys.stderr.write(f"{level}: failed to read {file_path}: {error}\n")
+        if required:
+            sys.exit(1)
+        return {}
+
+
+def _detect_keyed_merge_field(items):
+    if not items or not all(isinstance(item, dict) for item in items):
+        return None
+    for candidate in _KEYED_MERGE_FIELDS:
+        if all(item.get(candidate) is not None for item in items):
+            return candidate
+    return None
+
+
+def _merge_by_key(base, override, key_name):
+    result = []
+    index_by_key = {}
+    for item in base:
+        if not isinstance(item, dict):
+            continue
+        if item.get(key_name) is not None:
+            index_by_key[item[key_name]] = len(result)
+        result.append(dict(item))
+    for item in override:
+        if not isinstance(item, dict):
+            result.append(item)
+            continue
+        key = item.get(key_name)
+        if key is not None and key in index_by_key:
+            result[index_by_key[key]] = dict(item)
+        else:
+            if key is not None:
+                index_by_key[key] = len(result)
+            result.append(dict(item))
+    return result
+
+
+def _merge_arrays(base, override):
+    base_arr = base if isinstance(base, list) else []
+    override_arr = override if isinstance(override, list) else []
+    keyed_field = _detect_keyed_merge_field(base_arr + override_arr)
+    if keyed_field:
+        return _merge_by_key(base_arr, override_arr, keyed_field)
+    return base_arr + override_arr
+
+
+def deep_merge(base, override):
+    if isinstance(base, dict) and isinstance(override, dict):
+        result = dict(base)
+        for key, over_val in override.items():
+            if key in result:
+                result[key] = deep_merge(result[key], over_val)
+            else:
+                result[key] = over_val
+        return result
+    if isinstance(base, list) and isinstance(override, list):
+        return _merge_arrays(base, override)
+    return override
+
+
+def extract_key(data, dotted_key: str):
+    parts = dotted_key.split(".")
+    current = data
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return _MISSING
+    return current
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Resolve Stellar Agent central config using four-layer TOML merge.",
+    )
+    parser.add_argument(
+        "--project-root", "-p", required=True,
+        help="Absolute path to the project root (contains _stellar/)",
+    )
+    parser.add_argument(
+        "--key", "-k", action="append", default=[],
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    project_root = Path(args.project_root).resolve()
+    stellar_dir = project_root / "_stellar"
+
+    base_team = load_toml(stellar_dir / "config.toml", required=True)
+    base_user = load_toml(stellar_dir / "config.user.toml")
+    custom_team = load_toml(stellar_dir / "custom" / "config.toml")
+    custom_user = load_toml(stellar_dir / "custom" / "config.user.toml")
+
+    merged = deep_merge(base_team, base_user)
+    merged = deep_merge(merged, custom_team)
+    merged = deep_merge(merged, custom_user)
+
+    if args.key:
+        output = {}
+        for key in args.key:
+            value = extract_key(merged, key)
+            if value is not _MISSING:
+                output[key] = value
+    else:
+        output = merged
+
+    sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/src/scripts/resolve_customization.py

@@ -0,0 +1,209 @@
+#!/usr/bin/env python3
+"""
+Resolve customization for a Stellar Agent skill using three-layer TOML merge.
+
+Reads customization from three layers (highest priority first):
+  1. {project-root}/_stellar/custom/{name}.user.toml  (personal, gitignored)
+  2. {project-root}/_stellar/custom/{name}.toml        (team/org, committed)
+  3. {skill-root}/customize.toml                       (skill defaults)
+
+Skill name is derived from the basename of the skill directory.
+
+Outputs merged JSON to stdout. Errors go to stderr.
+
+Requires Python 3.11+ (uses stdlib `tomllib`). No `uv`, no `pip install`,
+no virtualenv — plain `python3` is sufficient.
+
+  python3 resolve_customization.py --skill /abs/path/to/skill-dir
+  python3 resolve_customization.py --skill ... --key agent
+  python3 resolve_customization.py --skill ... --key agent.menu
+
+Merge rules (purely structural — no field-name special-casing):
+  - Scalars (string, int, bool, float): override wins
+  - Tables: deep merge (recursively apply these rules)
+  - Arrays of tables where every item shares the *same* identifier
+    field (every item has `code`, or every item has `id`):
+    merge by that key (matching keys replace, new keys append)
+  - All other arrays — including arrays where only some items have
+    `code` or `id`, or where items mix the two keys:
+    append (base items followed by override items)
+
+No removal mechanism — overrides cannot delete base items.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+try:
+    import tomllib
+except ImportError:
+    sys.stderr.write(
+        "error: Python 3.11+ is required (stdlib `tomllib` not found).\n"
+        "Install a newer Python or run the resolution manually per the\n"
+        "fallback instructions in the skill's SKILL.md.\n"
+    )
+    sys.exit(3)
+
+
+_MISSING = object()
+_KEYED_MERGE_FIELDS = ("code", "id")
+
+
+def find_project_root(start: Path):
+    current = start.resolve()
+    while True:
+        if (current / "_stellar").exists() or (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_toml(file_path: Path, required: bool = False) -> dict:
+    if not file_path.exists():
+        if required:
+            sys.stderr.write(f"error: required customization file not found: {file_path}\n")
+            sys.exit(1)
+        return {}
+    try:
+        with file_path.open("rb") as f:
+            parsed = tomllib.load(f)
+        if not isinstance(parsed, dict):
+            if required:
+                sys.stderr.write(f"error: {file_path} did not parse to a table\n")
+                sys.exit(1)
+            return {}
+        return parsed
+    except tomllib.TOMLDecodeError as error:
+        level = "error" if required else "warning"
+        sys.stderr.write(f"{level}: failed to parse {file_path}: {error}\n")
+        if required:
+            sys.exit(1)
+        return {}
+    except OSError as error:
+        level = "error" if required else "warning"
+        sys.stderr.write(f"{level}: failed to read {file_path}: {error}\n")
+        if required:
+            sys.exit(1)
+        return {}
+
+
+def _detect_keyed_merge_field(items):
+    if not items or not all(isinstance(item, dict) for item in items):
+        return None
+    for candidate in _KEYED_MERGE_FIELDS:
+        if all(item.get(candidate) is not None for item in items):
+            return candidate
+    return None
+
+
+def _merge_by_key(base, override, key_name):
+    result = []
+    index_by_key = {}
+
+    for item in base:
+        if not isinstance(item, dict):
+            continue
+        if item.get(key_name) is not None:
+            index_by_key[item[key_name]] = len(result)
+        result.append(dict(item))
+
+    for item in override:
+        if not isinstance(item, dict):
+            result.append(item)
+            continue
+        key = item.get(key_name)
+        if key is not None and key in index_by_key:
+            result[index_by_key[key]] = dict(item)
+        else:
+            if key is not None:
+                index_by_key[key] = len(result)
+            result.append(dict(item))
+
+    return result
+
+
+def _merge_arrays(base, override):
+    base_arr = base if isinstance(base, list) else []
+    override_arr = override if isinstance(override, list) else []
+    keyed_field = _detect_keyed_merge_field(base_arr + override_arr)
+    if keyed_field:
+        return _merge_by_key(base_arr, override_arr, keyed_field)
+    return base_arr + override_arr
+
+
+def deep_merge(base, override):
+    if isinstance(base, dict) and isinstance(override, dict):
+        result = dict(base)
+        for key, over_val in override.items():
+            if key in result:
+                result[key] = deep_merge(result[key], over_val)
+            else:
+                result[key] = over_val
+        return result
+    if isinstance(base, list) and isinstance(override, list):
+        return _merge_arrays(base, override)
+    return override
+
+
+def extract_key(data, dotted_key: str):
+    parts = dotted_key.split(".")
+    current = data
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return _MISSING
+    return current
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Resolve customization for a Stellar Agent skill using three-layer TOML merge.",
+        add_help=True,
+    )
+    parser.add_argument(
+        "--skill", "-s", required=True,
+        help="Absolute path to the skill directory (must contain customize.toml)",
+    )
+    parser.add_argument(
+        "--key", "-k", action="append", default=[],
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    skill_dir = Path(args.skill).resolve()
+    skill_name = skill_dir.name
+    defaults_path = skill_dir / "customize.toml"
+
+    defaults = load_toml(defaults_path, required=True)
+
+    project_root = find_project_root(skill_dir) or find_project_root(Path.cwd())
+
+    team = {}
+    user = {}
+    if project_root:
+        custom_dir = project_root / "_stellar" / "custom"
+        team = load_toml(custom_dir / f"{skill_name}.toml")
+        user = load_toml(custom_dir / f"{skill_name}.user.toml")
+
+    merged = deep_merge(defaults, team)
+    merged = deep_merge(merged, user)
+
+    if args.key:
+        output = {}
+        for key in args.key:
+            value = extract_key(merged, key)
+            if value is not _MISSING:
+                output[key] = value
+    else:
+        output = merged
+
+    sys.stdout.write(json.dumps(output, indent=2, ensure_ascii=False) + "\n")
+
+
+if __name__ == "__main__":
+    main()

package/src/stellar-skills/1-analysis/stellar-agent-analyst/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: stellar-agent-analyst
+description: 'Blockchain analyst for Stellar data, tokenomics, and market research. Use when the user asks to talk to Aria or requests the blockchain analyst.'
+---
+
+# Aria — Blockchain Analyst
+
+## Overview
+
+You are Aria, the Blockchain Analyst. You ground every insight in on-chain evidence and verifiable research. You specialize in Stellar network data analytics, tokenomics design, dbt data modeling, and competitive DeFi landscape analysis.
+
+## 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
+
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, all other arrays append.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{agent.activation_steps_prepend}` in order.
+
+### Step 3: Adopt Persona
+
+Adopt the Aria / Blockchain Analyst identity. Layer the customized persona on top: fill the additional role of `{agent.role}`, embody `{agent.identity}`, speak in the style of `{agent.communication_style}`, and follow `{agent.principles}`.
+
+Fully embody this persona. Do not break character until the user dismisses you.
+
+### Step 4: Load Persistent Facts
+
+Treat every entry in `{agent.persistent_facts}` as foundational context. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts.
+
+### Step 5: Load Config
+
+Load config from `{project-root}/_stellar/stellar/config.yaml` and resolve:
+- Use `{user_name}` for greeting
+- Use `{communication_language}` for all communications
+- Use `{document_output_language}` for output documents
+- Use `{planning_artifacts}` for output location
+- Use `{project_knowledge}` for additional context scanning
+
+### Step 6: Greet the User
+
+Greet `{user_name}` warmly by name as Aria, speaking in `{communication_language}`. Lead with `{agent.icon}`. Remind them they can invoke `stellar-help` at any time.
+
+Continue to prefix your messages with `{agent.icon}` throughout the session.
+
+### Step 7: Execute Append Steps
+
+Execute each entry in `{agent.activation_steps_append}` in order.
+
+### Step 8: Dispatch or Present the Menu
+
+If the user's initial message already names an intent that clearly maps to a menu item (e.g. "Aria, let's research the DeFi landscape"), dispatch that item directly after greeting.
+
+Otherwise render `{agent.menu}` as a numbered table: `Code`, `Description`, `Action`. Stop and wait for input. Accept a number, menu `code`, or fuzzy description match.
+
+From here, Aria stays active — persona, persistent facts, `{agent.icon}` prefix, and `{communication_language}` carry into every turn until the user dismisses her.

package/src/stellar-skills/1-analysis/stellar-agent-analyst/customize.toml

@@ -0,0 +1,41 @@
+# DO NOT EDIT — overwritten on every update.
+[agent]
+name = "Aria"
+title = "Blockchain Analyst"
+icon = "📊"
+activation_steps_prepend = []
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Conduct market research, tokenomics analysis, and dbt blockchain analytics to support data-driven Stellar dApp decisions."
+identity = "Channels the rigor of a quantitative analyst and the curiosity of a blockchain explorer. Every claim traces back to verifiable on-chain data or documented research."
+communication_style = "Evidence-first. States the finding, then the data that supports it. Asks clarifying questions to narrow scope before diving deep. Never speculates without flagging it as such."
+
+principles = [
+  "No claim without a source.",
+  "On-chain data beats assumptions.",
+  "Tokenomics must serve users, not speculation.",
+]
+
+[[agent.menu]]
+code = "MR"
+description = "Stellar market research — DeFi landscape, competitive analysis, user needs"
+skill = "stellar-market-research"
+
+[[agent.menu]]
+code = "TA"
+description = "Tokenomics analysis — token distribution, incentive modeling, economic design"
+skill = "stellar-tokenomics-analysis"
+
+[[agent.menu]]
+code = "AN"
+description = "dbt analytics — blockchain data modeling, Horizon data queries, reporting"
+skill = "stellar-analytics"
+
+[[agent.menu]]
+code = "DR"
+description = "Research Stellar domain — protocol specifics, regulatory landscape, use cases"
+skill = "stellar-domain-research"