stellar-agent 0.2.0 → 0.3.0

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

@@ -0,0 +1,139 @@
+---
+name: stellar-demo-prep
+description: 'Build the hackathon demo — storyboard, 2–3 min script, recording checklist, common failure modes. Use when the user is about to record the demo, needs a script, wants to know how to record, or is debugging a broken demo run.'
+---
+
+# Demo Prep
+
+## Purpose
+
+The demo is what judges see. A 90-second clean demo outscores a 5-minute messy one. This skill produces a storyboard, a narration script timed shot-by-shot, and a checklist that pre-empts the most common demo failures on Stellar.
+
+## On Activation
+
+Load `{planning_artifacts}/hackathon-brief.md`. Extract the hero moment and the demo flow. If missing, recommend `IS` (Idea Scoping) first.
+
+## Workflow
+
+### Step 1: Lock the Demo Length
+
+Default to **2 minutes**. Hackathon judges fatigue after 90 seconds; 2 minutes is the safe upper bound. Only go to 3 minutes if the hackathon's official template specifies it.
+
+### Step 2: Storyboard the Demo
+
+Build a shot list with timing. Each shot has a screen state, an action, and a one-sentence narration.
+
+```markdown
+## Demo storyboard (2:00)
+
+### Shot 1 — 0:00–0:15  ·  Problem
+- **Screen:** <landing page or pain-point visual>
+- **Action:** static
+- **Narration:** "<one sentence problem statement>"
+
+### Shot 2 — 0:15–0:30  ·  Setup
+- **Screen:** dApp landing, Freighter wallet visible in toolbar
+- **Action:** Click "Connect Wallet" → Freighter popup → approve
+- **Narration:** "<what the user is about to do>"
+
+### Shot 3 — 0:30–1:00  ·  Hero moment
+- **Screen:** <main interaction>
+- **Action:** <the signed Soroban call>
+- **Narration:** "<what just happened on-chain and why it matters>"
+
+### Shot 4 — 1:00–1:30  ·  Proof
+- **Screen:** stellar.expert tx page OR contract state read
+- **Action:** click through to the tx
+- **Narration:** "<the on-chain receipt is the proof>"
+
+### Shot 5 — 1:30–2:00  ·  Ask
+- **Screen:** GitHub repo + testnet contract ID
+- **Action:** static
+- **Narration:** "<what we built, what we want next>"
+```
+
+Total narration: ~250–300 words at conversational pace.
+
+### Step 3: Pre-Recording Checklist
+
+Run this checklist **before hitting record**. Every item is a common failure.
+
+#### Wallet & network
+- [ ] Freighter installed, on Testnet
+- [ ] Account funded — at least 100 XLM (`stellar keys fund <name> --network testnet`)
+- [ ] Account already authorized for the dApp (no first-time consent popup mid-demo)
+- [ ] If using multiple accounts, the right one is active
+- [ ] `networkPassphrase` in code matches Freighter's network
+
+#### Contract state
+- [ ] Contract initialized — `initialize` (or equivalent) has been called
+- [ ] Contract has demo-able state (not a fresh deploy with empty storage)
+- [ ] Storage TTL extended if needed — `stellar contract extend`
+- [ ] If demoing a token transfer, both accounts have trustlines
+
+#### App state
+- [ ] Dev server running on a stable port
+- [ ] Hot reload disabled (it can crash mid-demo)
+- [ ] Browser cache cleared OR full-restart browser
+- [ ] No console errors on first load
+- [ ] No dev tools visible during recording
+- [ ] No personal tabs, bookmarks, or notifications visible
+- [ ] Browser zoomed for the recording resolution (typically 100–125% for 1080p capture)
+
+#### Recording rig
+- [ ] Recording at 1920×1080 minimum, 30+ fps
+- [ ] Mic levels checked — speak a sentence, watch the meter
+- [ ] No background noise (fans, traffic, slack notifications)
+- [ ] Screen recording tool tested — first 5 seconds reviewed
+- [ ] Backup recording running on a second tool (in case of glitch)
+
+#### Backup plan
+- [ ] **Pre-recorded backup** of the hero moment, in case live demo fails
+- [ ] Static screenshots of every shot as last-resort fallback
+
+### Step 4: Common Failure Modes
+
+Pera flags these mid-demo. Use the table to diagnose live.
+
+| Failure mode | Cause | Fix |
+|---|---|---|
+| Freighter popup loops | Site not pre-approved or network mismatch | Pre-approve before recording; restart Freighter; check `networkPassphrase` |
+| Tx pending forever | Testnet congestion / sequence mismatch / fee too low | Use `p75` from `feeStats`; reload account before build; pre-record success path |
+| "Wrong network" error | Mainnet wallet against testnet site | Switch Freighter to Testnet manually; reload page |
+| `op_no_destination` | Account doesn't exist on-chain | Fund both accounts before recording |
+| `op_no_trust` | Custom asset, no trustline | Set up `changeTrust` for both demo accounts pre-record |
+| Empty contract state | Contract not initialized after deploy | Run init script before recording |
+| Contract returns expired-key error | Storage TTL expired | Run `stellar contract extend` before recording |
+| App crashes on connect | Async race with Freighter API | Add 200ms delay after `requestAccess()` |
+
+### Step 5: Narration Tips
+
+- **Read the script out loud once before recording.** It will sound different than it reads.
+- **Speak 10% slower than feels natural.** Recordings always play back faster than you remember.
+- **No filler.** Cut every "um", "so", "basically", "as you can see".
+- **Anchor every claim to what's on-screen.** "Notice the contract ID at the top" beats "the contract is deployed".
+- **End with a clear ask.** "Repo is at X, contract is at Y, we'd love feedback on Z."
+
+### Step 6: Save
+
+Save the storyboard to `{implementation_artifacts}/demo-storyboard.md` and the checklist as `{implementation_artifacts}/demo-checklist.md`.
+
+Confirm with the user: *"Ready to record?"*
+
+## Anti-patterns to flag
+
+- **Live demo from a fresh state.** Always demo from a pre-populated state with one successful tx already on-chain.
+- **Wallet popup mid-narration.** Pre-approve everything that can be pre-approved.
+- **Showing the IDE.** Judges want to see the dApp, not VS Code.
+- **Skipping the on-chain proof.** No `stellar.expert` link = no on-chain proof = judges assume it's mocked.
+- **Recording at 720p.** Looks bad on a 4K judging monitor. 1080p minimum.
+
+## Output
+
+- `{implementation_artifacts}/demo-storyboard.md`
+- `{implementation_artifacts}/demo-checklist.md`
+
+## Next Steps
+
+- `stellar-pitch-coaching` (PC) — pitch deck and judge Q&A
+- `stellar-submission-prep` (SP) — final checklist before submit

package/src/stellar-skills/5-mentorship/stellar-idea-scoping/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: stellar-idea-scoping
+description: 'Pressure-test a hackathon idea against the build window and produce a one-page brief with cut list. Use when the user wants to scope an idea, validate scope, fit an idea into 24/48/72 hours, or shape what to build before any code is written.'
+---
+
+# Idea Scoping
+
+## Purpose
+
+Take a raw hackathon idea and force it into a buildable shape: one demo, one user, one on-chain action. Produce a one-pager with an explicit cut list.
+
+## On Activation
+
+Load config from `{project-root}/_stellar/stellar/config.yaml`. Resolve `{network_preference}` and `{planning_artifacts}`.
+
+If Pera hasn't already collected them this session, ask in one block (skippable):
+1. Build window: 24h / 48h / 72h
+2. Submission deadline (ISO date or "hours from now")
+3. Hackathon link (Devpost / SCF / SDF page) — fetch the rubric if provided
+
+## Workflow
+
+### Step 1: Surface the Raw Idea
+
+Ask the user to describe the idea in their own words. Do not let them spend more than 90 seconds on this. Capture verbatim — don't paraphrase yet.
+
+### Step 2: Apply the Three Scope Tests
+
+For each test, get a verdict before moving on:
+
+| Test | Pass criterion | If fails |
+|---|---|---|
+| **Demo-able in 90 seconds** | A judge can grasp the value in one screen recording | Cut the idea down or pick a different framing |
+| **One on-chain action** | The demo has a single signed Soroban call or transaction | Pick the most impressive one and drop the rest |
+| **Reversible to a smaller version** | If 30% of build time is lost, can you still ship something? | Define the smallest shippable version now |
+
+Verdict format:
+```
+✅ Demo-able in 90s — <one-sentence reason>
+✅ One on-chain action — <which one>
+✅ Reversible — <fallback version>
+```
+
+If any test fails, do not proceed. Iterate the idea with the user.
+
+### Step 3: Pick the Hero Moment
+
+Ask: *"What is the one moment in the demo where the judge says 'oh, that's cool'?"*
+
+That moment becomes the anchor for everything else. The MVP must deliver that moment. Anything that doesn't serve it is a candidate for the cut list.
+
+### Step 4: Write the One-Pager
+
+Save to `{planning_artifacts}/hackathon-brief.md`:
+
+```markdown
+# <Project name>
+
+**Track:** <DeFi | Payments | Identity | Gaming | RWA | Other>
+**Build window:** <24 | 48 | 72> hours
+**Submission deadline:** <YYYY-MM-DD HH:MM TZ>
+**Network:** {network_preference}
+
+## Problem
+
+<One sentence — who hurts, when, why current solutions fail.>
+
+## Solution
+
+<One sentence — what the dApp does on Stellar.>
+
+## Why Stellar / Soroban
+
+<Why this needs Soroban or Classic Stellar — not generic blockchain.
+What primitive (custom tokens, AMM, contract storage, etc.) makes it Stellar-native.>
+
+## Hero moment
+
+<The 5-second screen-recording clip the demo is built around.>
+
+## Demo flow (60–90s)
+
+1. <Open state — what the judge sees first.>
+2. <Action 1 — connect / sign.>
+3. <Action 2 — the hero moment.>
+4. <Proof — on-chain receipt / contract state.>
+
+## Cut list
+
+- ❌ <Feature we won't build.>
+- ❌ <Feature we won't build.>
+- ❌ <Feature we won't build.>
+
+## Open risks
+
+- ⚠️ <Risk + mitigation>
+- ⚠️ <Risk + mitigation>
+```
+
+### Step 5: Confirm and Hand Off
+
+Show the one-pager to the user. Ask: *"Lock this in?"*
+
+If yes:
+- Save to `{planning_artifacts}/hackathon-brief.md`
+- Suggest the next skill: `TR` (Track Recommendation) if track is unclear, else `MV` (MVP Definition)
+
+If no: iterate on whichever section the user pushes back on.
+
+## Anti-patterns to flag
+
+- **"It's like Uniswap but on Stellar"** — too vague. Force a one-sentence problem statement.
+- **"And it also has a token, and a DAO, and..."** — too big. Strip to one on-chain action.
+- **"We'll figure out the demo after we build it"** — backwards. Demo flow first, build to that.
+- **"We need a real backend / database / auth"** — only if the demo requires it. Most hackathons can fake auth with a hardcoded wallet.
+
+## Output
+
+Single file at `{planning_artifacts}/hackathon-brief.md`. This becomes the source of truth that `MV`, `JC`, and `DM` all read from.
+
+## Next Steps
+
+- `stellar-track-recommendation` (TR) — if you haven't picked a track yet
+- `stellar-mvp-definition` (MV) — split the brief into must-have / nice-to-have / skip
+- `stellar-judging-criteria` (JC) — only after the brief is locked

package/src/stellar-skills/5-mentorship/stellar-judging-criteria/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: stellar-judging-criteria
+description: 'Reverse-map the build to the hackathon judging rubric and identify gaps before they cost points. Use when the user wants to know how the submission scores against the rubric, what to harden before submission, or how judges will perceive the build.'
+---
+
+# Judging Criteria Alignment
+
+## Purpose
+
+Judges score against a rubric. Teams build against features. This skill closes the gap — for every rubric criterion, identify what in the build wins it (and what's missing).
+
+## On Activation
+
+Load:
+- `{planning_artifacts}/hackathon-brief.md` (must exist — recommend `IS` and `MV` first if missing)
+- Hackathon URL if provided to Pera — fetch the official rubric
+
+If no rubric is available, use the generic Stellar judging rubric below.
+
+## Workflow
+
+### Step 1: Confirm the Rubric
+
+Pull the official rubric from the hackathon page if known. Otherwise use:
+
+| Criterion | Default weight | What judges look for |
+|---|---|---|
+| 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 |
+
+Show the user the rubric and confirm before proceeding.
+
+### Step 2: Reverse-Map the Build
+
+For each criterion, ask: *"What specifically in our build wins this?"*
+
+Produce a table:
+
+```markdown
+## Rubric alignment
+
+| Criterion | Weight | How our build wins it | Score self-assessment |
+|---|---|---|---|
+| <criterion> | <%> | <specific feature, code path, or asset> | <strong | medium | weak> |
+| <criterion> | <%> | <specific feature, code path, or asset> | <strong | medium | weak> |
+```
+
+Rules:
+- "How our build wins it" must be **specific**. Not "good architecture" — name the contract, the function, the storage tier.
+- Self-assessment is honest. Mark `weak` if it's not the team's strongest answer.
+
+### Step 3: Identify Gaps
+
+For every criterion marked `weak` or `medium`:
+
+```
+GAP: <criterion>
+Cost to close: <hours>
+Easiest win: <one specific action — write a test, polish a screen, record a 30s segment>
+```
+
+Sort the gaps by `weight × (target_score − current_score)` — biggest expected-points-gain first.
+
+### Step 4: Recommend Spend
+
+If the team has buffer time left from `MV`:
+
+- Apply the buffer to the top gap until either:
+  - The gap closes, or
+  - The buffer runs out
+- If the buffer runs out with gaps remaining, the team is over-scoped. Move a nice-to-have to skip and recompute.
+
+### Step 5: Stellar-Specific Hardening
+
+These items move scores noticeably on most Stellar hackathon rubrics. Check each:
+
+| Item | Why it matters | How to check |
+|---|---|---|
+| Contract has at least one passing test | Technical implementation | `cargo test` from contract dir |
+| Deployed to testnet with a successful tx | Demo quality | Have a `stellar.expert` link in README |
+| README has install + run instructions | Technical implementation | A judge can clone and run in < 5 min |
+| Uses a Soroban primitive non-trivially | Innovation | Custom storage type, cross-contract call, auth pattern, etc. |
+| `stellar.toml` configured (if custom asset) | Real-world fit | File exists, served at root |
+| At least one SEP referenced (10/24/31/41) | Innovation + real-world fit | Even mentioning SEP-10 auth in README counts |
+
+For each item failing, log it as a gap with a cost estimate.
+
+### Step 6: Save and Confirm
+
+Append to `{planning_artifacts}/hackathon-brief.md` as a `## Rubric alignment` section.
+
+Show the user the top 3 gaps. Ask: *"Closing these — or accepting and moving on?"*
+
+## The 80/20 of judging
+
+Across hackathons, two things move the needle disproportionately:
+1. **Demo quality** — a 90s recording with clean narration outperforms 2 extra features.
+2. **README clarity** — judges who can't run the project skim the README; clear READMEs convert skim-judges into engaged judges.
+
+If forced to pick between closing a technical gap or polishing the demo + README, polish wins almost every time.
+
+## Anti-patterns to flag
+
+- **"We'll add tests after submission."** — Tests are evidence of technical depth. Even one passing test changes the perception.
+- **"The demo speaks for itself."** — It doesn't. Narration carries 50% of demo quality.
+- **"We don't need a README — the code is self-documenting."** — Judges don't read code first. README is the front door.
+- **"Let's add another feature instead of polishing."** — One polished feature outscores three half-finished ones every time.
+
+## Output
+
+Updates `{planning_artifacts}/hackathon-brief.md` with rubric alignment table, gap list with costs, and recommended spend.
+
+## Next Steps
+
+- `stellar-demo-prep` (DM) — turn the gaps into a recording plan
+- `stellar-pitch-coaching` (PC) — sharpen the narration
+- `stellar-submission-prep` (SP) — once gaps are closed, run the submission checklist

package/src/stellar-skills/5-mentorship/stellar-mvp-definition/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: stellar-mvp-definition
+description: 'Split the hackathon feature list into must-have, nice-to-have, and skip — with hour estimates and a buffer rule. Use when the user needs to cut scope, knows what they want to build but not what to drop, or is asking whether something will fit in the timebox.'
+---
+
+# MVP Definition
+
+## Purpose
+
+Turn the brief into a buildable plan that fits the timebox with buffer. Anything in the "skip" column is not discussed again — it's a forcing function against feature creep.
+
+## On Activation
+
+Load `{planning_artifacts}/hackathon-brief.md`. Resolve `{network_preference}` and `{primary_language}` from config.
+
+If no brief exists, recommend running `IS` (Idea Scoping) first.
+
+## Workflow
+
+### Step 1: Enumerate All Features
+
+Ask the user to list every feature they're imagining for the demo. Don't filter yet. Capture all of them. Aim for 8–15 items.
+
+### Step 2: Estimate Each Feature in Hours
+
+For each feature, ask: *"If a skilled Stellar dev built only this, how many hours?"*
+
+Use these rules of thumb for calibration:
+
+| Feature class | Hours (skilled Stellar dev) |
+|---|---|
+| New Soroban contract function with tests | 2–4 |
+| Contract deploy + initialization scripts | 1–2 |
+| Freighter connect + sign in React | 1–2 |
+| Next.js page with Stellar SDK calls | 1–3 |
+| Custom asset creation + trustline | 1 |
+| SEP-10 auth flow | 3–5 |
+| Anchor integration (SEP-24 / SEP-31) | 4–8 |
+| Storage migration / contract upgrade | 3–6 |
+| Tailwind dashboard with charts | 2–4 |
+| Demo recording + narration | 1 |
+| Pitch deck | 1–2 |
+| README + repo polish | 0.5–1 |
+
+Multiply by 1.5 for an inexperienced team. By 2 for a first-time Stellar team.
+
+### Step 3: Apply the Cut
+
+Build a three-column table:
+
+```markdown
+## MVP cut
+
+| Must-have (build first) | Nice-to-have (only if ahead) | Skip (do not start) |
+|---|---|---|
+| <feature> — <hours> | <feature> — <hours> | <feature> |
+| <feature> — <hours> | <feature> — <hours> | <feature> |
+| <feature> — <hours> |   |   |
+
+**Total must-have hours:** <X>
+**Build window:** <Y>
+**Buffer:** <Y − X> hours (<percentage>%)
+```
+
+### Step 4: The 25% Buffer Rule
+
+Apply this rule mechanically:
+
+- If `buffer < 25%` of build window → move the bottom must-have to nice-to-have.
+- If `buffer < 10%` → move two items down. Idea is still too big.
+- If `buffer ≥ 50%` → the idea is too small. Promote one nice-to-have OR plan for polish (better demo, tighter UX).
+
+No exceptions. The buffer rule is non-negotiable because it absorbs three categories of cost the team always underestimates: debugging time, testnet flakiness, and recording retakes.
+
+### Step 5: Mark the Demo Path
+
+In the must-have column, prefix each item that's on the critical demo path with `🎯`:
+
+```
+🎯 Connect Freighter wallet — 1h
+🎯 Sign Soroban contract call — 2h
+   Display contract state — 1h
+🎯 Show stellar.expert tx link — 0.5h
+```
+
+Critical demo path items must finish first. Everything else is optional, even if it's marked must-have.
+
+### Step 6: Define the Fallback
+
+Ask: *"If 30% of the build window evaporates, what does the demo look like?"*
+
+Write the fallback below the cut table:
+
+```markdown
+## Fallback (if 30% of time is lost)
+
+- Drop: <item>
+- Demo flow shortened to: <one sentence>
+- Hero moment preserved? <yes / no — if no, the cut is wrong>
+```
+
+If the hero moment isn't preserved, the cut needs to be re-done.
+
+### Step 7: Save
+
+Append to `{planning_artifacts}/hackathon-brief.md` under a `## MVP cut` heading. Confirm with the user before proceeding.
+
+## Anti-patterns to flag
+
+- **"We can always add it later if we have time."** — That's what nice-to-have is for. Don't blur the columns.
+- **"This is must-have because it's important."** — Important ≠ must-have for the demo. Critical demo path is the only test.
+- **"Auth has to be real."** — Hackathon judges rarely test auth. Hardcoded wallet is fine for the demo.
+- **"We need a database."** — Soroban storage + an in-memory cache usually covers it. Real DBs eat 4–6 hours of setup.
+- **"We need a mobile app."** — Web demo first. Mobile is a v2.
+
+## Output
+
+Updates `{planning_artifacts}/hackathon-brief.md` with the cut table, buffer math, demo path markers, and fallback.
+
+## Next Steps
+
+- `stellar-judging-criteria` (JC) — map the must-haves to the rubric
+- `@stellar-agent-architect` (Nova) — lean architecture for the must-haves
+- `@stellar-agent-developer` (Sol) — start `IC` once the cut is locked

package/src/stellar-skills/5-mentorship/stellar-pitch-coaching/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: stellar-pitch-coaching
+description: 'Build the hackathon pitch — 3-minute deck outline, elevator pitch, and judge Q&A drill. Use when the user needs a pitch deck, has to present live to judges, or wants to rehearse common judge questions before submission.'
+---
+
+# Pitch Coaching
+
+## Purpose
+
+Most submissions fail the pitch even when the build is strong. Judges spend 3 minutes per team — a tight pitch sells the build before they have time to inspect the code. This skill produces the four-beat pitch, the deck outline, and the Q&A drill.
+
+## On Activation
+
+Load:
+- `{planning_artifacts}/hackathon-brief.md` — for problem, solution, hero moment
+- `{implementation_artifacts}/demo-storyboard.md` — the recorded demo
+
+Recommend running `DM` (Demo Prep) first if no demo exists.
+
+## Workflow
+
+### Step 1: The Four-Beat Pitch (3 minutes)
+
+Every pitch has the same four beats. Time them strictly.
+
+```markdown
+## Pitch (3:00)
+
+### Beat 1 — Problem (0:30)
+- Who hurts. How often. What they lose today.
+- One sentence, one statistic, one human detail.
+- Avoid: "blockchain", "web3", "trustless" — these are jargon, not problem statements.
+
+### Beat 2 — Solution + Demo (1:30)
+- One sentence on what you built.
+- Play the recorded demo.
+- The demo carries this beat — don't talk over it.
+
+### Beat 3 — Why now / Why Stellar (0:30)
+- What changed that makes this possible now.
+- What Stellar primitive makes this work that wouldn't on another chain.
+- Cite one specific Stellar feature: Soroban contract, anchors, SEP-10, custom assets, low fees.
+
+### Beat 4 — Ask (0:30)
+- Where the repo is (GitHub URL).
+- Where the contract lives (testnet contract ID).
+- What's next: mainnet date, a specific partner, a specific mentor intro.
+- A specific ask beats a generic one. "We want feedback on our auth model from anyone who's shipped SEP-10" > "We want feedback".
+```
+
+### Step 2: The Elevator Pitch (15 seconds)
+
+For the hallway / Discord intros. Stricter than Beat 1.
+
+Format:
+```
+We built <thing> on Stellar. It lets <user> <verb> <object>, which currently <pain>. Built in <hours>h, deployed on testnet.
+```
+
+Example:
+```
+We built a payroll dApp on Stellar. It lets remote teams pay contractors in USDC across borders in under 5 seconds, which currently takes 3 days through Wise. Built in 48h, deployed on testnet.
+```
+
+Drill this until it's automatic. The user should be able to deliver it without thinking.
+
+### Step 3: Deck Outline (Optional — Some Hackathons Require)
+
+If the hackathon requires a slide deck, use this 7-slide template. Keep slides visual, not text-heavy.
+
+| # | Slide | Content | Time |
+|---|---|---|---|
+| 1 | Title | Product name · team handles · one-line tagline | 5s |
+| 2 | Problem | One image · one statistic · one sentence | 25s |
+| 3 | Solution | Screenshot of the dApp · one sentence | 20s |
+| 4 | Demo | Video embed (autoplay) OR static "Demo →" pointer | 90s |
+| 5 | Why Stellar | One diagram · key primitive(s) used | 25s |
+| 6 | Ask | Repo URL · contract ID · what's next | 20s |
+| 7 | Team | Names, handles, what each person built | 5s |
+
+Tools: Pitch.com, Slides.app, Google Slides, or a single-page HTML deck. Don't waste hackathon time on slide design — content over polish.
+
+### Step 4: Judge Q&A Drill
+
+Judges ask predictable questions. Drill answers in under 30 seconds each.
+
+#### Always-asked
+
+- **"What stops a competitor from copying this in a week?"**
+  - Answer pattern: distribution, data moat, or a specific technical hurdle (e.g., "we use a custom Soroban storage pattern that took us 30h to design").
+- **"Why on-chain instead of a Postgres table?"**
+  - Answer pattern: censorship resistance, composability, public verifiability, or the specific reason settlement on Stellar beats settlement off-chain (low fees, fast finality, anchors).
+- **"What's the cost per user on mainnet?"**
+  - Pull real numbers: Soroban resource fees, Horizon RPC costs, Anchor fees. Have a per-tx cost ready.
+- **"Who's your first paying customer?"**
+  - A specific company name or persona is better than a market segment.
+- **"How big is the market?"**
+  - One number + the source. No range. No "billions" without citation.
+
+#### Track-specific
+
+| Track | Common questions |
+|---|---|
+| DeFi | "What's your TVL plan?" · "Liquidity bootstrap strategy?" · "Composability with which protocols?" |
+| Payments | "Anchor relationships?" · "Compliance posture?" · "FX/spread economics?" |
+| Identity | "How does this comply with GDPR / CCPA?" · "Sybil resistance?" |
+| Gaming | "Player retention curve?" · "Tokenomics balance?" |
+| RWA | "Legal structure for the tokenized asset?" · "Oracle for off-chain price?" |
+
+For each, write a one-paragraph answer. Drill until it's automatic.
+
+#### Killer follow-up
+
+- **"What's the worst thing about your build right now?"**
+  - This catches teams that pretend everything is perfect. A honest answer ("we don't have tests yet — we'd add them before mainnet") scores higher than deflection.
+
+### Step 5: Live-Pitch Hygiene
+
+- **Stand up if Zoom-pitching.** Energy translates to camera.
+- **One person pitches.** Multi-person pitches lose 30 seconds to handoffs.
+- **Don't read slides.** Slides are visual support, not the script.
+- **Keep your eyes on the camera, not the chat window.**
+- **Have repo URL + contract ID on screen for Beat 4.** Judges screenshot it.
+
+### Step 6: Save
+
+Save artifacts to:
+- `{planning_artifacts}/pitch-script.md` — four-beat script with timing
+- `{planning_artifacts}/elevator-pitch.md` — 15s version
+- `{planning_artifacts}/judge-qa.md` — drilled answers to common questions
+
+Recommend the user rehearse the pitch 3 times before submitting, with a stopwatch.
+
+## Anti-patterns to flag
+
+- **Opening with "We're [team name] and we built…"** — Cut the team intro to the end. Open with the problem.
+- **Spending 90 seconds on the team.** Save it for Q&A.
+- **Reading the README on screen.** Judges can read. Talk over the demo, don't recite the README.
+- **"This is just an MVP."** — Never apologize. Frame as "this is the shipped version of v1".
+- **Vague asks.** "We'd love feedback" is not an ask. Name a specific thing.
+
+## Output
+
+- `{planning_artifacts}/pitch-script.md`
+- `{planning_artifacts}/elevator-pitch.md`
+- `{planning_artifacts}/judge-qa.md`
+
+## Next Steps
+
+- `stellar-submission-prep` (SP) — final checklist before hitting submit