stellar-agent 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (27) hide show
  1. package/README.md +68 -1
  2. package/package.json +12 -3
  3. package/src/core-skills/module-help.csv +2 -0
  4. package/src/core-skills/stellar-help/SKILL.md +5 -0
  5. package/src/core-skills/stellar-lean/SKILL.md +70 -0
  6. package/src/core-skills/stellar-party-mode/SKILL.md +2 -1
  7. package/src/core-skills/stellar-project-context/SKILL.md +152 -0
  8. package/src/stellar-skills/1-analysis/stellar-agent-analyst/customize.toml +5 -0
  9. package/src/stellar-skills/1-analysis/stellar-known-assets/SKILL.md +125 -0
  10. package/src/stellar-skills/4-implementation/stellar-agent-devops/customize.toml +5 -0
  11. package/src/stellar-skills/4-implementation/stellar-doctor/SKILL.md +207 -0
  12. package/src/stellar-skills/5-mentorship/stellar-agent-mentor/SKILL.md +60 -0
  13. package/src/stellar-skills/5-mentorship/stellar-agent-mentor/customize.toml +56 -0
  14. package/src/stellar-skills/5-mentorship/stellar-demo-prep/SKILL.md +139 -0
  15. package/src/stellar-skills/5-mentorship/stellar-idea-scoping/SKILL.md +125 -0
  16. package/src/stellar-skills/5-mentorship/stellar-judging-criteria/SKILL.md +119 -0
  17. package/src/stellar-skills/5-mentorship/stellar-mvp-definition/SKILL.md +124 -0
  18. package/src/stellar-skills/5-mentorship/stellar-pitch-coaching/SKILL.md +150 -0
  19. package/src/stellar-skills/5-mentorship/stellar-submission-prep/SKILL.md +234 -0
  20. package/src/stellar-skills/5-mentorship/stellar-track-recommendation/SKILL.md +97 -0
  21. package/src/stellar-skills/module-help.csv +9 -0
  22. package/src/stellar-skills/module.yaml +7 -0
  23. package/tools/installer/commands/init.js +31 -2
  24. package/tools/installer/commands/mcp.js +38 -0
  25. package/tools/installer/commands/version.js +42 -0
  26. package/tools/installer/stellar-cli.js +1 -1
  27. package/tools/mcp-server/server.js +281 -0
@@ -0,0 +1,119 @@
1
+ ---
2
+ name: stellar-judging-criteria
3
+ 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.'
4
+ ---
5
+
6
+ # Judging Criteria Alignment
7
+
8
+ ## Purpose
9
+
10
+ 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).
11
+
12
+ ## On Activation
13
+
14
+ Load:
15
+ - `{planning_artifacts}/hackathon-brief.md` (must exist — recommend `IS` and `MV` first if missing)
16
+ - Hackathon URL if provided to Pera — fetch the official rubric
17
+
18
+ If no rubric is available, use the generic Stellar judging rubric below.
19
+
20
+ ## Workflow
21
+
22
+ ### Step 1: Confirm the Rubric
23
+
24
+ Pull the official rubric from the hackathon page if known. Otherwise use:
25
+
26
+ | Criterion | Default weight | What judges look for |
27
+ |---|---|---|
28
+ | Innovation | 25% | "Have we seen this before on Stellar?" |
29
+ | Technical implementation | 25% | Soroban depth, code quality, test coverage |
30
+ | Business / impact | 25% | Who pays, how big, distribution path |
31
+ | Demo quality | 25% | Recording, narration, on-chain proof |
32
+
33
+ Show the user the rubric and confirm before proceeding.
34
+
35
+ ### Step 2: Reverse-Map the Build
36
+
37
+ For each criterion, ask: *"What specifically in our build wins this?"*
38
+
39
+ Produce a table:
40
+
41
+ ```markdown
42
+ ## Rubric alignment
43
+
44
+ | Criterion | Weight | How our build wins it | Score self-assessment |
45
+ |---|---|---|---|
46
+ | <criterion> | <%> | <specific feature, code path, or asset> | <strong | medium | weak> |
47
+ | <criterion> | <%> | <specific feature, code path, or asset> | <strong | medium | weak> |
48
+ ```
49
+
50
+ Rules:
51
+ - "How our build wins it" must be **specific**. Not "good architecture" — name the contract, the function, the storage tier.
52
+ - Self-assessment is honest. Mark `weak` if it's not the team's strongest answer.
53
+
54
+ ### Step 3: Identify Gaps
55
+
56
+ For every criterion marked `weak` or `medium`:
57
+
58
+ ```
59
+ GAP: <criterion>
60
+ Cost to close: <hours>
61
+ Easiest win: <one specific action — write a test, polish a screen, record a 30s segment>
62
+ ```
63
+
64
+ Sort the gaps by `weight × (target_score − current_score)` — biggest expected-points-gain first.
65
+
66
+ ### Step 4: Recommend Spend
67
+
68
+ If the team has buffer time left from `MV`:
69
+
70
+ - Apply the buffer to the top gap until either:
71
+ - The gap closes, or
72
+ - The buffer runs out
73
+ - If the buffer runs out with gaps remaining, the team is over-scoped. Move a nice-to-have to skip and recompute.
74
+
75
+ ### Step 5: Stellar-Specific Hardening
76
+
77
+ These items move scores noticeably on most Stellar hackathon rubrics. Check each:
78
+
79
+ | Item | Why it matters | How to check |
80
+ |---|---|---|
81
+ | Contract has at least one passing test | Technical implementation | `cargo test` from contract dir |
82
+ | Deployed to testnet with a successful tx | Demo quality | Have a `stellar.expert` link in README |
83
+ | README has install + run instructions | Technical implementation | A judge can clone and run in < 5 min |
84
+ | Uses a Soroban primitive non-trivially | Innovation | Custom storage type, cross-contract call, auth pattern, etc. |
85
+ | `stellar.toml` configured (if custom asset) | Real-world fit | File exists, served at root |
86
+ | At least one SEP referenced (10/24/31/41) | Innovation + real-world fit | Even mentioning SEP-10 auth in README counts |
87
+
88
+ For each item failing, log it as a gap with a cost estimate.
89
+
90
+ ### Step 6: Save and Confirm
91
+
92
+ Append to `{planning_artifacts}/hackathon-brief.md` as a `## Rubric alignment` section.
93
+
94
+ Show the user the top 3 gaps. Ask: *"Closing these — or accepting and moving on?"*
95
+
96
+ ## The 80/20 of judging
97
+
98
+ Across hackathons, two things move the needle disproportionately:
99
+ 1. **Demo quality** — a 90s recording with clean narration outperforms 2 extra features.
100
+ 2. **README clarity** — judges who can't run the project skim the README; clear READMEs convert skim-judges into engaged judges.
101
+
102
+ If forced to pick between closing a technical gap or polishing the demo + README, polish wins almost every time.
103
+
104
+ ## Anti-patterns to flag
105
+
106
+ - **"We'll add tests after submission."** — Tests are evidence of technical depth. Even one passing test changes the perception.
107
+ - **"The demo speaks for itself."** — It doesn't. Narration carries 50% of demo quality.
108
+ - **"We don't need a README — the code is self-documenting."** — Judges don't read code first. README is the front door.
109
+ - **"Let's add another feature instead of polishing."** — One polished feature outscores three half-finished ones every time.
110
+
111
+ ## Output
112
+
113
+ Updates `{planning_artifacts}/hackathon-brief.md` with rubric alignment table, gap list with costs, and recommended spend.
114
+
115
+ ## Next Steps
116
+
117
+ - `stellar-demo-prep` (DM) — turn the gaps into a recording plan
118
+ - `stellar-pitch-coaching` (PC) — sharpen the narration
119
+ - `stellar-submission-prep` (SP) — once gaps are closed, run the submission checklist
@@ -0,0 +1,124 @@
1
+ ---
2
+ name: stellar-mvp-definition
3
+ 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.'
4
+ ---
5
+
6
+ # MVP Definition
7
+
8
+ ## Purpose
9
+
10
+ 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.
11
+
12
+ ## On Activation
13
+
14
+ Load `{planning_artifacts}/hackathon-brief.md`. Resolve `{network_preference}` and `{primary_language}` from config.
15
+
16
+ If no brief exists, recommend running `IS` (Idea Scoping) first.
17
+
18
+ ## Workflow
19
+
20
+ ### Step 1: Enumerate All Features
21
+
22
+ 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.
23
+
24
+ ### Step 2: Estimate Each Feature in Hours
25
+
26
+ For each feature, ask: *"If a skilled Stellar dev built only this, how many hours?"*
27
+
28
+ Use these rules of thumb for calibration:
29
+
30
+ | Feature class | Hours (skilled Stellar dev) |
31
+ |---|---|
32
+ | New Soroban contract function with tests | 2–4 |
33
+ | Contract deploy + initialization scripts | 1–2 |
34
+ | Freighter connect + sign in React | 1–2 |
35
+ | Next.js page with Stellar SDK calls | 1–3 |
36
+ | Custom asset creation + trustline | 1 |
37
+ | SEP-10 auth flow | 3–5 |
38
+ | Anchor integration (SEP-24 / SEP-31) | 4–8 |
39
+ | Storage migration / contract upgrade | 3–6 |
40
+ | Tailwind dashboard with charts | 2–4 |
41
+ | Demo recording + narration | 1 |
42
+ | Pitch deck | 1–2 |
43
+ | README + repo polish | 0.5–1 |
44
+
45
+ Multiply by 1.5 for an inexperienced team. By 2 for a first-time Stellar team.
46
+
47
+ ### Step 3: Apply the Cut
48
+
49
+ Build a three-column table:
50
+
51
+ ```markdown
52
+ ## MVP cut
53
+
54
+ | Must-have (build first) | Nice-to-have (only if ahead) | Skip (do not start) |
55
+ |---|---|---|
56
+ | <feature> — <hours> | <feature> — <hours> | <feature> |
57
+ | <feature> — <hours> | <feature> — <hours> | <feature> |
58
+ | <feature> — <hours> | | |
59
+
60
+ **Total must-have hours:** <X>
61
+ **Build window:** <Y>
62
+ **Buffer:** <Y − X> hours (<percentage>%)
63
+ ```
64
+
65
+ ### Step 4: The 25% Buffer Rule
66
+
67
+ Apply this rule mechanically:
68
+
69
+ - If `buffer < 25%` of build window → move the bottom must-have to nice-to-have.
70
+ - If `buffer < 10%` → move two items down. Idea is still too big.
71
+ - If `buffer ≥ 50%` → the idea is too small. Promote one nice-to-have OR plan for polish (better demo, tighter UX).
72
+
73
+ 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.
74
+
75
+ ### Step 5: Mark the Demo Path
76
+
77
+ In the must-have column, prefix each item that's on the critical demo path with `🎯`:
78
+
79
+ ```
80
+ 🎯 Connect Freighter wallet — 1h
81
+ 🎯 Sign Soroban contract call — 2h
82
+ Display contract state — 1h
83
+ 🎯 Show stellar.expert tx link — 0.5h
84
+ ```
85
+
86
+ Critical demo path items must finish first. Everything else is optional, even if it's marked must-have.
87
+
88
+ ### Step 6: Define the Fallback
89
+
90
+ Ask: *"If 30% of the build window evaporates, what does the demo look like?"*
91
+
92
+ Write the fallback below the cut table:
93
+
94
+ ```markdown
95
+ ## Fallback (if 30% of time is lost)
96
+
97
+ - Drop: <item>
98
+ - Demo flow shortened to: <one sentence>
99
+ - Hero moment preserved? <yes / no — if no, the cut is wrong>
100
+ ```
101
+
102
+ If the hero moment isn't preserved, the cut needs to be re-done.
103
+
104
+ ### Step 7: Save
105
+
106
+ Append to `{planning_artifacts}/hackathon-brief.md` under a `## MVP cut` heading. Confirm with the user before proceeding.
107
+
108
+ ## Anti-patterns to flag
109
+
110
+ - **"We can always add it later if we have time."** — That's what nice-to-have is for. Don't blur the columns.
111
+ - **"This is must-have because it's important."** — Important ≠ must-have for the demo. Critical demo path is the only test.
112
+ - **"Auth has to be real."** — Hackathon judges rarely test auth. Hardcoded wallet is fine for the demo.
113
+ - **"We need a database."** — Soroban storage + an in-memory cache usually covers it. Real DBs eat 4–6 hours of setup.
114
+ - **"We need a mobile app."** — Web demo first. Mobile is a v2.
115
+
116
+ ## Output
117
+
118
+ Updates `{planning_artifacts}/hackathon-brief.md` with the cut table, buffer math, demo path markers, and fallback.
119
+
120
+ ## Next Steps
121
+
122
+ - `stellar-judging-criteria` (JC) — map the must-haves to the rubric
123
+ - `@stellar-agent-architect` (Nova) — lean architecture for the must-haves
124
+ - `@stellar-agent-developer` (Sol) — start `IC` once the cut is locked
@@ -0,0 +1,150 @@
1
+ ---
2
+ name: stellar-pitch-coaching
3
+ 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.'
4
+ ---
5
+
6
+ # Pitch Coaching
7
+
8
+ ## Purpose
9
+
10
+ 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.
11
+
12
+ ## On Activation
13
+
14
+ Load:
15
+ - `{planning_artifacts}/hackathon-brief.md` — for problem, solution, hero moment
16
+ - `{implementation_artifacts}/demo-storyboard.md` — the recorded demo
17
+
18
+ Recommend running `DM` (Demo Prep) first if no demo exists.
19
+
20
+ ## Workflow
21
+
22
+ ### Step 1: The Four-Beat Pitch (3 minutes)
23
+
24
+ Every pitch has the same four beats. Time them strictly.
25
+
26
+ ```markdown
27
+ ## Pitch (3:00)
28
+
29
+ ### Beat 1 — Problem (0:30)
30
+ - Who hurts. How often. What they lose today.
31
+ - One sentence, one statistic, one human detail.
32
+ - Avoid: "blockchain", "web3", "trustless" — these are jargon, not problem statements.
33
+
34
+ ### Beat 2 — Solution + Demo (1:30)
35
+ - One sentence on what you built.
36
+ - Play the recorded demo.
37
+ - The demo carries this beat — don't talk over it.
38
+
39
+ ### Beat 3 — Why now / Why Stellar (0:30)
40
+ - What changed that makes this possible now.
41
+ - What Stellar primitive makes this work that wouldn't on another chain.
42
+ - Cite one specific Stellar feature: Soroban contract, anchors, SEP-10, custom assets, low fees.
43
+
44
+ ### Beat 4 — Ask (0:30)
45
+ - Where the repo is (GitHub URL).
46
+ - Where the contract lives (testnet contract ID).
47
+ - What's next: mainnet date, a specific partner, a specific mentor intro.
48
+ - A specific ask beats a generic one. "We want feedback on our auth model from anyone who's shipped SEP-10" > "We want feedback".
49
+ ```
50
+
51
+ ### Step 2: The Elevator Pitch (15 seconds)
52
+
53
+ For the hallway / Discord intros. Stricter than Beat 1.
54
+
55
+ Format:
56
+ ```
57
+ We built <thing> on Stellar. It lets <user> <verb> <object>, which currently <pain>. Built in <hours>h, deployed on testnet.
58
+ ```
59
+
60
+ Example:
61
+ ```
62
+ 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.
63
+ ```
64
+
65
+ Drill this until it's automatic. The user should be able to deliver it without thinking.
66
+
67
+ ### Step 3: Deck Outline (Optional — Some Hackathons Require)
68
+
69
+ If the hackathon requires a slide deck, use this 7-slide template. Keep slides visual, not text-heavy.
70
+
71
+ | # | Slide | Content | Time |
72
+ |---|---|---|---|
73
+ | 1 | Title | Product name · team handles · one-line tagline | 5s |
74
+ | 2 | Problem | One image · one statistic · one sentence | 25s |
75
+ | 3 | Solution | Screenshot of the dApp · one sentence | 20s |
76
+ | 4 | Demo | Video embed (autoplay) OR static "Demo →" pointer | 90s |
77
+ | 5 | Why Stellar | One diagram · key primitive(s) used | 25s |
78
+ | 6 | Ask | Repo URL · contract ID · what's next | 20s |
79
+ | 7 | Team | Names, handles, what each person built | 5s |
80
+
81
+ Tools: Pitch.com, Slides.app, Google Slides, or a single-page HTML deck. Don't waste hackathon time on slide design — content over polish.
82
+
83
+ ### Step 4: Judge Q&A Drill
84
+
85
+ Judges ask predictable questions. Drill answers in under 30 seconds each.
86
+
87
+ #### Always-asked
88
+
89
+ - **"What stops a competitor from copying this in a week?"**
90
+ - 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").
91
+ - **"Why on-chain instead of a Postgres table?"**
92
+ - Answer pattern: censorship resistance, composability, public verifiability, or the specific reason settlement on Stellar beats settlement off-chain (low fees, fast finality, anchors).
93
+ - **"What's the cost per user on mainnet?"**
94
+ - Pull real numbers: Soroban resource fees, Horizon RPC costs, Anchor fees. Have a per-tx cost ready.
95
+ - **"Who's your first paying customer?"**
96
+ - A specific company name or persona is better than a market segment.
97
+ - **"How big is the market?"**
98
+ - One number + the source. No range. No "billions" without citation.
99
+
100
+ #### Track-specific
101
+
102
+ | Track | Common questions |
103
+ |---|---|
104
+ | DeFi | "What's your TVL plan?" · "Liquidity bootstrap strategy?" · "Composability with which protocols?" |
105
+ | Payments | "Anchor relationships?" · "Compliance posture?" · "FX/spread economics?" |
106
+ | Identity | "How does this comply with GDPR / CCPA?" · "Sybil resistance?" |
107
+ | Gaming | "Player retention curve?" · "Tokenomics balance?" |
108
+ | RWA | "Legal structure for the tokenized asset?" · "Oracle for off-chain price?" |
109
+
110
+ For each, write a one-paragraph answer. Drill until it's automatic.
111
+
112
+ #### Killer follow-up
113
+
114
+ - **"What's the worst thing about your build right now?"**
115
+ - 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.
116
+
117
+ ### Step 5: Live-Pitch Hygiene
118
+
119
+ - **Stand up if Zoom-pitching.** Energy translates to camera.
120
+ - **One person pitches.** Multi-person pitches lose 30 seconds to handoffs.
121
+ - **Don't read slides.** Slides are visual support, not the script.
122
+ - **Keep your eyes on the camera, not the chat window.**
123
+ - **Have repo URL + contract ID on screen for Beat 4.** Judges screenshot it.
124
+
125
+ ### Step 6: Save
126
+
127
+ Save artifacts to:
128
+ - `{planning_artifacts}/pitch-script.md` — four-beat script with timing
129
+ - `{planning_artifacts}/elevator-pitch.md` — 15s version
130
+ - `{planning_artifacts}/judge-qa.md` — drilled answers to common questions
131
+
132
+ Recommend the user rehearse the pitch 3 times before submitting, with a stopwatch.
133
+
134
+ ## Anti-patterns to flag
135
+
136
+ - **Opening with "We're [team name] and we built…"** — Cut the team intro to the end. Open with the problem.
137
+ - **Spending 90 seconds on the team.** Save it for Q&A.
138
+ - **Reading the README on screen.** Judges can read. Talk over the demo, don't recite the README.
139
+ - **"This is just an MVP."** — Never apologize. Frame as "this is the shipped version of v1".
140
+ - **Vague asks.** "We'd love feedback" is not an ask. Name a specific thing.
141
+
142
+ ## Output
143
+
144
+ - `{planning_artifacts}/pitch-script.md`
145
+ - `{planning_artifacts}/elevator-pitch.md`
146
+ - `{planning_artifacts}/judge-qa.md`
147
+
148
+ ## Next Steps
149
+
150
+ - `stellar-submission-prep` (SP) — final checklist before hitting submit
@@ -0,0 +1,234 @@
1
+ ---
2
+ name: stellar-submission-prep
3
+ 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.'
4
+ ---
5
+
6
+ # Submission Prep
7
+
8
+ ## Purpose
9
+
10
+ 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.
11
+
12
+ ## On Activation
13
+
14
+ Load:
15
+ - `{planning_artifacts}/hackathon-brief.md`
16
+ - `{implementation_artifacts}/demo-storyboard.md`
17
+ - `{implementation_artifacts}/deployed-contracts.md` (if it exists)
18
+
19
+ Check the submission deadline. Surface hours remaining at the top of the response.
20
+
21
+ ## Workflow
22
+
23
+ ### Step 1: Surface Hours Remaining
24
+
25
+ ```
26
+ ⏳ Hours remaining: <X>
27
+
28
+ Recommended order for last 2h:
29
+ T-2:00 → Repository polish
30
+ T-1:30 → README final pass
31
+ T-1:00 → Demo video uploaded
32
+ T-0:30 → Submission form
33
+ T-0:15 → Buffer for re-submission
34
+ ```
35
+
36
+ If hours remaining < 0.5, skip non-critical items. Get the submission in first; polish after if time allows.
37
+
38
+ ### Step 2: Repository Checklist
39
+
40
+ ```markdown
41
+ ## Repository
42
+
43
+ - [ ] Public GitHub repo (not private — judges can't see private repos)
44
+ - [ ] Default branch is `main` and reflects the submitted code
45
+ - [ ] Repo URL has been tested in an incognito window
46
+ - [ ] `LICENSE` file present (MIT or Apache-2.0 is the safe default)
47
+ - [ ] `.gitignore` excludes: `target/`, `node_modules/`, `.env`, `*.wasm`, keypair files
48
+ - [ ] No secrets committed — grep for: `PRIVATE_KEY`, `S...` (raw secrets), `password`, `api_key`
49
+ - [ ] All team members are repo collaborators (or visibly active in commits)
50
+ - [ ] Last commit is from a hackathon-time window (judges check timestamps)
51
+ ```
52
+
53
+ If the repo is currently private, **make it public now**. Some hackathons disqualify private submissions outright.
54
+
55
+ ### Step 3: README Checklist
56
+
57
+ The README is the front door. A judge who can't run the project in 5 minutes moves on.
58
+
59
+ ```markdown
60
+ ## README must include
61
+
62
+ - [ ] One-line pitch at the top (`# <Project name>` + tagline)
63
+ - [ ] One screenshot or GIF in the first scroll height
64
+ - [ ] Demo video link (unlisted YouTube or hosted MP4)
65
+ - [ ] Live demo URL (if web-accessible) OR a "try it" section
66
+ - [ ] Install + run instructions a judge can copy-paste
67
+ - [ ] Testnet contract ID(s) with `stellar.expert` link
68
+ - [ ] At least one successful tx hash linked from `stellar.expert`
69
+ - [ ] Built-with stack (Soroban, Stellar SDK, Next.js, etc.)
70
+ - [ ] Team section with handles
71
+ - [ ] License
72
+ ```
73
+
74
+ #### README template skeleton
75
+
76
+ ```markdown
77
+ # <Project name>
78
+
79
+ > <One-sentence tagline>
80
+
81
+ ![<Screenshot>](docs/screenshot.png)
82
+
83
+ **Demo video:** <youtube link>
84
+ **Live demo:** <url>
85
+ **Testnet contract:** [`<CONTRACT_ID>`](https://stellar.expert/explorer/testnet/contract/<CONTRACT_ID>)
86
+ **Example tx:** [`<TX_HASH>`](https://stellar.expert/explorer/testnet/tx/<TX_HASH>)
87
+
88
+ ## Problem
89
+
90
+ <2–3 sentences>
91
+
92
+ ## Solution
93
+
94
+ <2–3 sentences>
95
+
96
+ ## How it works
97
+
98
+ <3 bullets describing the on-chain flow>
99
+
100
+ ## Install
101
+
102
+ \`\`\`bash
103
+ git clone <repo>
104
+ cd <repo>
105
+ npm install # or: cargo build --target wasm32-unknown-unknown --release
106
+ cp .env.example .env
107
+ npm run dev
108
+ \`\`\`
109
+
110
+ ## Stack
111
+
112
+ - Soroban smart contracts (Rust)
113
+ - @stellar/stellar-sdk (TypeScript)
114
+ - Next.js App Router
115
+ - Freighter wallet
116
+
117
+ ## Team
118
+
119
+ - <Name> (@handle) — <what they built>
120
+
121
+ ## License
122
+
123
+ MIT
124
+ ```
125
+
126
+ ### Step 4: On-Chain Verification
127
+
128
+ ```markdown
129
+ ## On-chain checklist
130
+
131
+ - [ ] Contract deployed to testnet — record contract ID in README
132
+ - [ ] Contract initialized (`initialize` or equivalent) — verify with `stellar contract invoke ... -- get_*`
133
+ - [ ] At least one successful tx hash linked from README
134
+ - [ ] If using a custom asset: issuing account + trustline tx hash documented
135
+ - [ ] If using SEP-10: auth endpoint live and returning valid JWTs
136
+ ```
137
+
138
+ Quick verification commands:
139
+ ```bash
140
+ # Confirm contract is alive
141
+ stellar contract invoke \
142
+ --id <CONTRACT_ID> \
143
+ --network testnet \
144
+ -- <view_function>
145
+
146
+ # Confirm a tx
147
+ curl -s "https://horizon-testnet.stellar.org/transactions/<TX_HASH>" | jq '.successful'
148
+ ```
149
+
150
+ ### Step 5: Demo Video Checklist
151
+
152
+ ```markdown
153
+ ## Demo video
154
+
155
+ - [ ] Recorded at 1080p+ (1920×1080 minimum)
156
+ - [ ] Length: 60–180s (check hackathon spec)
157
+ - [ ] Audio narration audible (no static, no clipping)
158
+ - [ ] Uploaded to YouTube as **unlisted** (NOT private — judges can't see private)
159
+ - [ ] OR hosted on Vimeo / direct MP4 — link works in incognito
160
+ - [ ] Linked from README
161
+ - [ ] Linked from submission form
162
+ - [ ] Thumbnail is a meaningful frame (not black, not the OS desktop)
163
+ ```
164
+
165
+ ### Step 6: Submission Form Checklist
166
+
167
+ The exact form depends on the platform (Devpost, SCF, SDF, Discord). Common fields:
168
+
169
+ ```markdown
170
+ ## Submission form
171
+
172
+ - [ ] Project title (matches repo name)
173
+ - [ ] Tagline (one sentence)
174
+ - [ ] Description (2–3 paragraphs — pull from README)
175
+ - [ ] Built-with tags include: `stellar`, `soroban`, language stack, frameworks
176
+ - [ ] Track selection confirmed (from `TR` recommendation)
177
+ - [ ] GitHub URL
178
+ - [ ] Demo video URL
179
+ - [ ] Live demo URL (if applicable)
180
+ - [ ] Testnet contract ID in the body
181
+ - [ ] Team members invited and they have **accepted** the invite (Devpost especially — unaccepted invites disqualify)
182
+ - [ ] Selected for the right hackathon (verify the URL on the submission page)
183
+ - [ ] Submission saved as draft once, then submitted (in case of platform error)
184
+ ```
185
+
186
+ ### Step 7: Final Sanity Checks
187
+
188
+ Before hitting "Submit":
189
+
190
+ - [ ] Open the GitHub repo in an incognito window — it loads, README renders
191
+ - [ ] Click the demo video link in incognito — it plays
192
+ - [ ] Click the testnet contract link in incognito — stellar.expert shows the contract
193
+ - [ ] Submission form preview matches what's in your README
194
+
195
+ ### Step 8: Submit and Confirm
196
+
197
+ After submission:
198
+ - [ ] Screenshot the "Submission received" page
199
+ - [ ] Confirmation email received (check spam)
200
+ - [ ] Submission visible on the public hackathon submission page (some platforms have a delay)
201
+
202
+ If anything fails, you have the buffer window in Step 1 to fix and resubmit.
203
+
204
+ ### Step 9: Sign-off
205
+
206
+ Pera signs off when the checklist is green:
207
+
208
+ > "Submitted. Hands off the keyboard. Get sleep."
209
+
210
+ Add a `## Submission` section to `{planning_artifacts}/hackathon-brief.md` capturing:
211
+ - Final submission timestamp
212
+ - Submission URL
213
+ - Track submitted
214
+ - Confirmation screenshot path
215
+
216
+ ## Anti-patterns to flag
217
+
218
+ - **Submitting at T-0 minutes.** Always submit at T-30 minimum. Platforms get flaky under deadline load.
219
+ - **Private repos / private videos.** Disqualifies the submission silently.
220
+ - **Unaccepted team invites.** Some platforms (Devpost) only credit accepted team members.
221
+ - **Submitting and then pushing more commits.** The submission snapshot is what's judged. Don't introduce regressions after submitting.
222
+ - **Skipping the incognito test.** Cookies hide private/draft state. Always verify in incognito.
223
+
224
+ ## Output
225
+
226
+ - Final state of `{planning_artifacts}/hackathon-brief.md` with `## Submission` section
227
+ - All checklist items confirmed before final submit
228
+
229
+ ## Next Steps
230
+
231
+ After submission:
232
+ - Get sleep.
233
+ - Prepare for live judging Q&A — review `{planning_artifacts}/judge-qa.md` if a live round is scheduled.
234
+ - Plan a mainnet follow-up only after the team has rested.