Forem: austin amento

The Dev Journal That Writes Itself (And Gives You XP)

austin amento — Sun, 22 Mar 2026 21:40:50 +0000

This is a submission for the Notion MCP Challenge

Every developer has a graveyard of half-remembered side projects.

You know the feeling. Someone asks "what have you been building?" during a job search and you blank. Or you're writing a performance review and can't reconstruct what you shipped in Q1. Or you're three months into learning to code and can't tell if you're getting better, which honestly stings more than the other two.

The problem isn't that you aren't building. It's that the work disappears into git history the moment it's committed.

I built DevPulse to fix that. And then I turned your git history into a game.

What I Built

DevPulse is a global Claude Code agent that automatically logs your coding sessions to Notion after every commit. It tracks your growth with XP and levels, maintains daily streaks, runs a 25-quest achievement system, and unlocks 30 achievement badges — all triggered by a single slash command, from any project on your machine.

🎮 Async Queue System for Ad Insertion Engine

⚡ 100 base × 1.5 (7-day streak) × 1.25 (diff run) + 10 (daily spark) + 50 (Ship It quest) = 247 XP
📊 Total: 1,847 XP

🏆 Level: Senior Dev → Staff Engineer 🎉

🔥 Streak: 8 days

🏅 Badges Unlocked:
  - Week Warrior ⚡ (7-day streak!)
  - Challenge Accepted ⚔️

⚔️ Quest Completed:
  - Challenge Accepted (50 XP) — 2 sessions this week at Difficulty 4+

• Built async-safe queue with retry logic and exponential backoff — no dropped frames under load
• Logged to Master Dev Log · Profile updated: 14 sessions, 1,847 XP, Staff Engineer
• Quests DB updated: Challenge Accepted → Completed

No server. No backend to maintain. No manual journaling. You committed your code — DevPulse reads the diff and handles everything else.

Who It's Actually For

I designed this for two people simultaneously, because I think they have the same core problem.

If you're learning to code: DevPulse makes the invisible visible. Every session logged is proof of work — proof that you showed up and built something. The difficulty ratings go from 1 (config tweaks) to 5 (complex algorithms). You watch them climb as you grow. Your first month might be all 2s and 3s. Six months later you're cracking 4s and 5s and the XP reflects it. The streak system is the most important feature here: building the habit of shipping daily, even small things, is what separates developers who grow fast from those who plateau. And when you can't articulate what you've been working on? Pull up your weekly recap.

If you're an experienced developer: You already know how fast projects blur together. DevPulse gives you a structured, searchable record across every project on your machine — filtered by stack, sorted by difficulty, summarized weekly. The weekly recap generates a Growth Narrative written from your actual data, not generic encouragement. It's also genuinely useful for performance reviews, resume updates, and the "so what have you been working on?" questions you get in every technical conversation.

The Growth Narrative

This is the feature I'm most proud of. Every /weekly-recap generates a Claude-written analysis of your actual week — specific to your data:

"Backend-heavy week — 4 of 5 sessions touched the database layer and your average difficulty climbed to 3.8, up from 2.6 last week. TypeScript was your most-used technology for the third week running. You logged sessions on 5 different days, your most consistent week yet. Next week: your streak hits 14 days — push for Streak Legend."

That's not templated. That's Claude reading your Master Dev Log, spotting the pattern, and writing it back to you. It's a mirror that shows you your own growth in a way raw git logs never could.

The Architecture

The system runs as a global Claude Code configuration — installed once to ~/.claude/, active in every project on your machine:

~/.claude/
├── CLAUDE.md                    ← DevPulse identity + XP formula + all 30 badge definitions
└── commands/
    ├── pulse-check.md           ← /pulse-check workflow (11 sequential steps)
    ├── weekly-recap.md          ← /weekly-recap workflow
    └── monthly-recap.md         ← /monthly-recap workflow

When you type /pulse-check, Claude loads the agent identity from CLAUDE.md and executes the 11-step workflow in pulse-check.md. Every operation that touches persistent state goes through Notion MCP — there is no other storage layer.

The Four Notion Databases

DevPulse manages four databases entirely through MCP:

Database	Purpose
Master Dev Log	One row per session — title, stack, difficulty, XP, commit hash, badges
DevPulse Profile	Single-row state machine: streak, total XP, level, all badges earned
DevPulse Quests	25 quests (13 weekly rotating + 12 permanent milestones)
DevPulse Recaps	Weekly and monthly recap pages with tech breakdown + growth narrative

Three of these are auto-created on first run. The one you set up manually (Master Dev Log) is the source of truth — DevPulse never deletes or modifies rows in it after they're written.

The Full Gamification Engine (V2)

I started with V1 (basic logging + 7 badges) and iterated to a full gamification system.

XP Multiplier Formula:

Session XP = floor((Difficulty × 20) × streak_mult × diff_run_mult) + daily_spark + quest_bonus

streak_mult: 1.5× at 7-day streak, 2× at 30 days — consistency is rewarded
diff_run_mult: 1.25× when two back-to-back sessions hit Difficulty ≥ 4 — keeps you pushing hard
daily_spark: flat +10 XP on your first session of the day
quest_bonus: bonus XP from any quests completed this session
Combined multiplier cap: 3.0× — no runaway math

25-Quest System:

13 weekly quests rotate every Monday: Ship It, Deep Work, Consistency Check, Stack Master, Challenge Accepted, Bug Hunter, Early Bird, Polyglot Week, and more
12 permanent milestone quests: Century Club, Perfectionist, Streak Legend, Tech Specialist, Versatile, and more
Quest completion writes to the Quests DB and adds XP to the current session's total

30 Achievement Badges across three groups — from First Flame (session 1) through Diamond Coder (30-day streak), Deep Diver (three Difficulty-5 sessions in 7 days), Full Stack (frontend + backend in one session), and Achievement Hunter (15+ badges earned).

Show Us the Code

🔗 GitHub: github.com/puginator/devlog

The distributable config lives in claude-config/. Here's what makes the system tick:

`claude-config/CLAUDE.md` — The Agent Identity

This file ships the XP formula, difficulty rubric, level thresholds, and all 30 badge definitions into Claude's context on every session. The badge definitions are the most interesting part — they reference in-memory values computed earlier in the same session:

## Badge Definitions
Badge checks use post-Step-8 streak value, Total Sessions = Profile Total Sessions + 1,
and provisional Total XP.

| Label | Condition |
|---|---|
| Multiplier | Session where streak_mult ≥ 1.5 AND diff_run_mult = 1.25 AND daily_spark was applied |
| Deep Diver | 3+ sessions with Difficulty = 5 in any rolling 7-day window |
| Full Stack | Session Stack contains ≥ 1 frontend AND ≥ 1 backend technology |
| Achievement Hunter | 15+ badges in Profile Badges Earned |

The hard constraints section is what makes the system reliable across sessions:

## Hard Constraints
- Never hallucinate Notion properties — stop and report errors exactly
- Never log empty sessions (no meaningful changes = decline and explain)
- Badge checks are idempotent — compare against Badges Earned in Profile before announcing
- Quest evaluation is idempotent — check Completed On before awarding quest XP; if set, skip
- Stack always written as an array of strings — never a comma-separated string
- Difficulty run query always executes before Step 6 to read the previous session only

`claude-config/commands/pulse-check.md` — The Core Workflow

11 steps executed in sequence. A few highlights:

Step 1b — Duplicate check (prevents double-logging the same commit):

If the commit hash is NOT "uncommitted": search Master Dev Log for an existing row
where Commit Hash matches this hash. If found: stop and say "Already logged commit
[hash] — make a new commit before running Pulse Check again!"

Step 4b — XP multiplier computation (pure in-memory, no Notion reads):

streak_mult:
- 7–29 days → 1.5
- 30+ days → 2.0
- Otherwise → 1.0

diff_run_mult:
Query most recent Master Dev Log row (sort Date descending, limit 1). Read Difficulty.
- If previous Difficulty ≥ 4 AND current Difficulty ≥ 4 → 1.25
- Otherwise → 1.0

combined_mult = min(streak_mult × diff_run_mult, 3.0)
daily_spark = +10 XP if Last Active Date ≠ today
provisional_xp = floor((Difficulty × 20) × combined_mult) + daily_spark_xp

Step 9b — Quest evaluation (runs after the session row is written):

Each active quest has a specific condition evaluated against the session and Master Dev Log:

Ship It (50 XP): 3+ sessions logged this ISO week
Deep Work (50 XP): current session Difficulty = 5
Challenge Accepted (50 XP): 2+ sessions this week at Difficulty ≥ 4
Bug Hunter (50 XP): 2+ sessions this week where Commit Message contains "fix" or "bug"
Consistency Check (50 XP): sessions logged on 3+ different days this week

Completed quests update in the Quests DB, add to quest_bonus, and the session row's XP Earned is patched with the final total.

Step 6 — Automatic V1→V2 schema migration:

Before writing the row, verify Master Dev Log has the `XP Earned` (Number) and
`Commit Message` (Rich Text) properties. If either is missing, add it using
notion_update_database before proceeding.

Zero manual Notion work to upgrade. DevPulse detects missing columns and adds them on the first V2 run.

`claude-config/commands/weekly-recap.md` — The Recap Generator

The weekly recap queries 7 days of Master Dev Log rows and writes a Notion page. The Growth Narrative step is where it gets interesting:

## Step 6 — Growth Narrative
Write a 3–4 sentence analysis of the week. Must reference actual data (most-used stack,
difficulty trend, project focus, streak status). Must include one specific pattern
observation (e.g. "Backend-heavy week — 3 of 5 sessions touched the database layer").
Must end with a forward-looking callout for next week.

Claude isn't filling in a template — it's reading your actual session data, identifying the pattern, and writing it back as analysis.

How I Used Notion MCP

Notion MCP is the entire backend of DevPulse. Every piece of state lives in Notion. Claude reads and writes through @notionhq/notion-mcp-server — there's no local database, no config file, no server of any kind.

Here's every MCP operation the system uses:

`notion_search` — Database discovery

Every workflow starts by finding its databases by name:

notion_search("Master Dev Log")     → session logging
notion_search("DevPulse Profile")   → XP, streak, badges
notion_search("DevPulse Quests")    → active quests
notion_search("DevPulse Recaps")    → weekly/monthly summaries

This is what makes DevPulse portable. The databases can live anywhere in your Notion workspace.

`notion_query_database` — Precise filtered reads

The quest system and badge checks require querying Master Dev Log with specific filters:

# Sessions this ISO week (quest evaluation)
filter: { Date: { on_or_after: "2026-03-16", on_or_before: "2026-03-22" } }

# Previous session only (diff_run_mult)
sorts: [{ property: "Date", direction: "descending" }], page_size: 1

# All Difficulty-5 sessions (Deep Diver badge, Hardcore badge)
filter: { Difficulty: { equals: 5 } }

# Active quests only
filter: { Status: { equals: "Active" } }

`notion_create_page` — Writing session data

notion_create_page(
  parent: { database_id: master_dev_log_id },
  properties: {
    "Session Title": "Async Queue System for Ad Insertion Engine",
    "Project": "ad-engine",
    "Stack": ["TypeScript", "Node.js", "Redis"],  ← always an array, never a string
    "Difficulty": 4,
    "XP Earned": 247,
    "Date": "2026-03-19",
    "Commit Hash": "a3f9b2c",
    "Commit Message": "feat: implement async ad queue with retry logic"
  }
)

Stack is always written as an array of strings — a hard constraint in CLAUDE.md because early versions wrote "TypeScript, React" as a single value, which broke the tech frequency aggregation in weekly recaps.

`notion_update_page` — State management

After writing the session, DevPulse updates the Profile and patches the session row if quests completed:

# Profile update
notion_update_page(profile_row_id, {
  "Current Streak": 8,
  "Total XP": 1847,
  "Current Level": "Staff Engineer",
  "Badges Earned": ["First Flame", "Bug Slayer", "Week Warrior", "Challenge Accepted"],
  "Last Active Date": "2026-03-19"
})

# Session row patched with final XP after quest bonuses resolved
notion_update_page(session_row_id, { "XP Earned": 247 })  ← was 187 before quest bonus

# Quest marked complete
notion_update_page(quest_row_id, { "Status": "Completed", "Completed On": "2026-03-19" })

`notion_update_database` — Schema migration

V1→V2 upgrade adds missing columns automatically:

notion_update_database(master_dev_log_id, {
  "XP Earned": { number: {} },
  "Commit Message": { rich_text: {} }
})

Runs once, on the first V2 /pulse-check, only if the columns don't exist.

Auto-creating databases on first run

If DevPulse Profile or DevPulse Quests don't exist, Claude creates them with the full schema and seeds all 25 quests in a single batch — 12 milestone quests as Active rows, plus 3 weekly quests timed to the current week's deadline.

Why Notion MCP Was the Right Choice

DevPulse works because Notion is actually a real relational database, not just a note-taking app. Filtering by date, sorting by difficulty, updating specific properties, running schema migrations — all the things you'd normally need a backend for are just Notion API calls.

@notionhq/notion-mcp-server gives Claude direct access to every Notion operation from inside the conversation context. No server needed. The entire DevPulse backend is: Claude + a markdown config file + MCP.

The MCP interface is the key piece. Without it, I'd need a server to broker requests between Claude and the Notion API. With @notionhq/notion-mcp-server, Claude has direct access to every Notion operation from inside the conversation context. The entire DevPulse backend is: Claude + a markdown config file + MCP. That's it.

DevPulse is open source and works for anyone with Claude Code. Clone the repo, run setup.sh, and your first /pulse-check sets everything up automatically — including writing your first entry to Notion and starting your streak at day 1.

If you're just starting to code, that first entry is going to mean more than you think it will six months from now.

Building SoloQuest: Letting Gemini Be the DM, and Code Be the Referee

austin amento — Mon, 02 Mar 2026 05:08:09 +0000

This is a submission for the Built with Google Gemini: Writing Challenge

What I Built with Google Gemini

SoloQuest started with a question that felt a little absurd and a little irresistible:

Could I build a solo D&D 5e campaign where an AI acts as the Dungeon Master, and have it actually feel coherent for more than a few turns?

At first, this was just a prompt experiment in Google AI Studio. I wanted to see whether Gemini could stay in character as a rules-aware DM over a long conversation. The early results were exciting. Gemini was great at scene-setting, roleplay, and making even simple encounters feel dramatic.

Then the cracks started to show.

A goblin would attack twice because initiative state drifted. A defeated enemy would still be described as active. A spell slot would get consumed in the narration but not in the actual game state. Death saves sounded correct and still ended up inconsistent.

That was the turning point. I realized I was trying to use Gemini for two jobs at once:

storytelling
stateful rules execution

It was excellent at the first and unreliable at the second.

That insight became the architecture for SoloQuest.

Today, SoloQuest is a full-stack Next.js app with Firebase Auth and Firestore, Stripe subscriptions, Google Text-to-Speech for narration, and Gemini powering the core game experience. The model handles narration, roleplay, encounter flavor, NPC dialogue, and player choice framing. My code handles the deterministic layer: combat state, initiative, HP math, spell slots, inventory, conditions, progression, and persistence.

The core loop works like this:

The player enters an action
The app sends Gemini the current campaign context, including character state, combat state, inventory, quest context, and recent session history
Gemini returns both narrative text and a structured MECHANICS block
A deterministic rules engine parses that block and applies the actual state transitions
Everything is saved back to Firestore so the campaign can continue across sessions

Gemini plays the DM. My code plays the referee.

That division of labor turned a fun prototype into a real product.

Demo

You can try SoloQuest at thesoloquest.com

What I Learned

The Most Important Design Decision Was Deciding What the AI Was Allowed to Do

The biggest lesson from this project had nothing to do with clever prompts. It was about system boundaries.

Early on, I kept trying to fix mechanical inconsistency with better instructions. I added more rules to the system prompt, more formatting requirements, more reminders about initiative order, death saves, conditions, and spell slots. It helped a little, but not enough. The problem was not that Gemini was failing to read my instructions. The problem was that I was assigning deterministic responsibilities to a probabilistic system.

Once I accepted that, progress became much faster.

Over eight phases of development, I moved game mechanics out of Gemini and into a rules engine. Gemini still decides how the world sounds and feels. The engine decides what actually happens.

That changed everything.

Here are a few examples:

Initiative and turn order are fully engine-controlled. My code rolls initiative, sorts combatants, advances turns, and enforces who can act.
Attack resolution uses real AC and stat data. Gemini can narrate a hit, but if the math says it missed, the engine wins.
Conditions like stunned, grappled, and paralyzed are stored as structured state with start-of-turn and end-of-turn hooks.
Spells are resolved by deterministic handlers based on spell category, such as attack roll, saving throw, auto-hit, or area effect.
Reactions like Shield, Uncanny Dodge, and Opportunity Attacks are surfaced as interactive prompts instead of left to narration.
Encounter generation is constrained by SRD-based balance rules so the model has creative freedom without producing absurd difficulty spikes.

The key mental model became:

Gemini should generate intent and drama. The engine should own truth.

That idea ended up being useful beyond games. It feels like a general rule for building with LLMs. If the model is responsible for something that must be correct every time, you should seriously consider whether that responsibility belongs in code instead.

The most valuable non-technical skill here was learning how to design the handoff between AI output and deterministic systems. That handoff is easy to underestimate, but in a product like this it defines the user experience.

Google Gemini Feedback

What Worked Really Well

Gemini is genuinely strong at long-form narrative interaction. It does a good job maintaining tone, pacing, and scene continuity across many turns, which matters a lot in a solo RPG where the model is effectively carrying the voice of the world.

It was also strong enough at structured output to support a hybrid architecture. I instructed it to always include a MECHANICS block alongside the narrative, and that gave me a consistent enough interface to build a parser and rules engine around.

A typical response pattern looks something like this:

NARRATIVE:
The goblin lunges from behind the crates, dagger flashing in the torchlight.

MECHANICS:
ACTION_TYPE: ATTACK
SOURCE: goblin_1
TARGET: player
ATTACK_TYPE: dagger

The important part is that Gemini is not trusted to finalize the outcome. It declares intent. The engine resolves whether the attack hits, how much damage is applied, whether a reaction is available, and what the updated combat state becomes.

I also liked working with the @google/genai SDK. It felt straightforward to integrate, and one design choice that paid off early was versioning my system instruction. I keep a SYSTEM_INSTRUCTION_VERSION constant so I can evolve the DM prompt over time without corrupting older save files or creating mismatches across campaigns.

Where I Hit Friction

The biggest friction point was long-context consistency.

As campaigns grew, Gemini would sometimes drift from earlier constraints. It might quietly invent a mechanic, forget a restriction, or phrase a response in a way that implied a state change that never actually happened. This forced me to constantly ask whether a bug belonged to prompt design, parser design, or the underlying architecture.

The second major friction point was output normalization. Even when Gemini followed the general structure, the exact formatting could vary. I ended up building a fairly defensive parser that handles misplaced directives, missing separators, whitespace variation, partial formatting failures, and narrative text leaking into the mechanics section.

That parser exists because the model was good enough to be useful, but not rigid enough to be treated like a strict protocol.

I also felt the absence of a more native function-style interface for state mutations in this workflow. I effectively created a domain-specific command layer for the model to speak through:

HP_CHANGE: -12
CONDITION_ADD: poisoned
SPELL_SLOT_USED: 2

That worked, but it shifted complexity into my application. A more direct way to return strongly structured actions would have simplified a lot of infrastructure.

The messiest failure mode was hallucinated state. In early versions, Gemini would occasionally introduce enemies I had never spawned, add items that were never earned, or award XP for events that had not actually occurred. To contain that, I added a validation layer that checks model responses before any game state is mutated. If validation fails, the app sends a repair prompt asking Gemini to correct the output.

That helped reliability, but it also introduced latency because a bad response can require an additional model call.

In the end, Gemini got much better as soon as I narrowed its job description. The more precise I was about what belonged to the model and what belonged to the engine, the better the overall system behaved.

Where I'm Headed Next

The engine is now through eight phases of rules implementation. The remaining work is less about core feasibility and more about completeness and production hardening: item economy, attunement, ammunition tracking, encumbrance, error dashboards, combat-friction telemetry, feature flags, and migration tooling for older campaigns.

What is interesting is that as the engine becomes more capable, the prompt becomes simpler.

Rules that Gemini used to carry in prompt instructions are now enforced directly in code. That means I can remove prompt complexity instead of adding to it. The system gets more reliable while the model's role becomes more focused.

That is where I think this architecture is heading:

Gemini handles prose, pacing, roleplay, and choice design. The engine handles rules, state, and truth.

That separation is what made SoloQuest viable, and it is the main thing I would tell anyone building with Gemini from day one:

Use the model for what it is uniquely good at. Protect that space. Move everything deterministic out of it as quickly as you can.

You can try SoloQuest at thesoloquest.com. Your first 50 turns are free. If you are building with Gemini or experimenting with AI-driven game systems, I would love to compare notes in the comments.

Pinned Brews - A social coffee community

austin amento — Mon, 02 Mar 2026 04:21:06 +0000

This is a submission for the DEV Weekend Challenge: Community

The Community

I spent 12 years in the specialty coffee world before pivoting into web development in 2020. One thing I always wished existed was a simple place to see what other people were actually brewing, enjoying, and recommending.

There are plenty of places to buy coffee, but not many places that make it easy to discover new coffees and roasters through other people’s real brew logs and tasting notes. I built Pinned Brews for that kind of coffee community: people who love trying new roasters, comparing brew methods, and sharing what’s in their cup.

What I Built

I built Pinned Brews, a social coffee logging app where people can:

post the coffees they’re drinking
log brew methods, ratios, and tasting notes
discover new roasters through a public feed
build profiles around their coffee habits
unlock achievements for exploring and posting
get AI-powered brew suggestions for future tweaks

The goal was to keep the app simple and approachable while still making it fun to explore what the wider coffee community is brewing.

Demo

Give it a try here: Pinned Brews

Code

Repo: github.com/puginator/pinned-brews

How I Built It

I built Pinned Brews with:

Next.js for the app frontend and routing
Supabase for auth and database storage
Vercel for deployment
Gemini for AI brew suggestions
custom SVG brew method icons for a more coffee-specific UI

I also used AI tools during the build process to quickly explore early UI ideas, generate some custom brew graphics, and help organize seed data from roasters and coffees listed on drinktrade.com.

What I Learned

This project was a fun way to combine two parts of my background: specialty coffee and web development. The biggest challenge was keeping the app lightweight and fun while still making it feel like a real community product instead of just a personal brew tracker.

What’s Next

If I keep building it out, I’d love to add:

comments and discussions on brews
following favorite brewers or roasters
richer coffee search and filtering
more personalized discovery features

Prompt Architecture for a Reliable AI Dungeon Master

austin amento — Fri, 27 Feb 2026 05:45:30 +0000

How I structured prompts to make an LLM behave like a consistent, rule-following D&D 5e GM and actually stay that way across long sessions.

Building an AI Dungeon Master sounds straightforward until you actually try it.

Left to its own devices, an LLM will happily let a level-1 fighter dual-wield longswords, cast spells they never learned, and narrate a killing blow before the player has rolled a single die. Fun the first time. Maddening as a recurring loop.

The core challenge isn't creativity LLMs are genuinely great at that. The challenge is consistency. D&D 5e has hundreds of interlocking rules, and a solo player with no human GM to correct mistakes will notice fast when the AI forgets that Warlocks recharge spell slots on a short rest, or that a Bard can't swap their Known Spells mid-dungeon. Get caught bending the rules once, and the player trusts nothing.

Here's how I tackled it in SoloQuest.

Layer 1: The System Prompt as a Rules Contract

The foundation is a dense, versioned system instruction (currently on v9) that functions less like a creative brief and more like a contract the model has to sign before every session.

It covers things like:

Inventory and resource tracking. The AI is told explicitly what it can and cannot offer based on the current character state. Confiscated items are off-limits. When a consumable gets used, the model emits a machine-readable tag (ITEM_USED: Item Name) that the game parser watches for. Same with ability charges. This isn't vague guidance, it's a protocol.

Spell management by caster type. Rather than one generic spell rule, the prompt distinguishes three different systems: prepared casters (Cleric, Druid, Paladin), known casters (Bard, Sorcerer, Warlock), and spellbook casters (Wizard). Each one has different rules for what they can cast and when their slots come back. Warlocks even get a dedicated callout, because "Warlock slots recharge on short rest, not long rest" is one of the most common AI failure modes I ran into early on.

Rolls are mandatory before outcomes. This one is bolded in the prompt. The model gets shown the wrong pattern ("Your sword strikes true, dealing 8 damage!") and the correct one: request the roll, wait, then narrate after. Without this, the AI just collapses into a choose-your-own-adventure book where the dice are decoration.

Encounter balance guardrails. At levels 1-3, solo encounters have hard HP caps baked into the prompt (level 1 enemies: max 7 HP, no multiattack). A single bad roll at low level with no party to pick you up is a run-ender, so I encoded the balance logic directly rather than hoping the model had good instincts about what's "survivable."

Layer 2: Injecting the Rules Right When They're Needed

The system prompt handles general behavior, but specific mechanics need to be fresh in context exactly when they matter.

Every turn, I run the player's input through a lightweight keyword extractor that picks up signals: Are there active enemies? Is the player low on HP? What class are they? What verb did they use, "attack," "sneak," "cast"?

From those signals, a scoring function pulls the top 3 most relevant rules from a structured SRD database and drops them directly into the user prompt:

RELEVANT D&D 5E RULES (Follow these strictly):

Sneak Attack: Requires a finesse or ranged weapon, plus advantage or an ally adjacent to the target...

Two-Weapon Fighting: The off-hand attack uses a bonus action and does not add your modifier to damage...

This means the model doesn't have to recall Sneak Attack from training data. The rule is just sitting right there in the prompt when the Rogue tries to use it. Scoring is weighted (exact tag match scores highest, loose content match scores lowest), and irrelevant rules get filtered out so they don't clutter the context window.

Layer 3: Game State as the Source of Truth

The most brittle moment in a long session is continuity. After 30 turns, does the model remember the player is concentrating on Hold Person? That the goblin lieutenant fled rather than died? That the fighter is at 3 of 12 HP?

To handle this, I serialize the entire engine state into every prompt turn. The AI always receives:

Combat state: initiative order, whose turn it is, each enemy's distance and line of sight, cover values
Exploration state: travel pace, light level, time elapsed, last passive perception result
Death save tracker: active or not, current success/failure counts
Active effects: conditions with round durations, poisons with their DCs, disease stage progression

The prompt declares these trackers as authoritative. The AI cannot narrate hitting an enemy behind full cover, can't apply damage to a character with immunity, can't start concentrating on a second spell without dropping the first. The state in context is the source of truth, not whatever the model thinks it remembers.

One more detail worth calling out: the machine-readable combat trace from the previous turn also gets passed in. This gives the model a clear record of what mechanics were actually applied last round, which prevents a frustrating drift pattern where the model re-narrates a hit that was actually a miss.

Layer 4: Enforced Response Structure

Parsing AI output reliably means removing all ambiguity from the format. Every turn, the model is required to return four sections:

[NARRATIVE] — the story beat, written however it likes
[MECHANICS] — machine-readable tags only (HP_CHANGE:-8, ENEMY_HP: Goblin Scout, 4, ROLL:1d20+DEX for Stealth)
[SUGGESTIONS] — player options, each tagged as requiring a roll or not
[CHRONICLE] — a one-line campaign log entry, only on significant beats

The parser maps the mechanics tags directly to state transitions in the game engine. HP_CHANGE, ENEMY_SPAWN, ITEM_GAINED, SPELL_SLOT_USED, CONCENTRATION all feed deterministic updates. The AI's prose can be whatever it wants, but the mechanics section has to be machine-readable.

The roll:true/false flag on each suggestion is checked by the client before an action gets sent. If a suggestion requires a roll and the player hasn't provided one, the UI stops and prompts for it. The AI can't skip the dice.

Testing: No Unit Tests, Just Instrumented Playtesting

There's no test suite for DM behavior. A spec can tell you if a function returns the right boolean, but it can't tell you whether the goblin acted like a goblin.

Instead, I leaned on a few practices:

Debug logging at parse time. Every injected SRD rule gets logged. Every mechanic event gets logged. This is how I caught the model emitting ITEM_GAINED: Health Potion x1 (with a quantity suffix the parser didn't expect) and traced it back to a missing naming constraint in the prompt.

Version bumping as change control. The system instruction version constant forces a cache miss on character caches whenever the prompt changes. What felt like a minor clarification sometimes produced drastically different combat behavior. Treating each meaningful edit as a version was the only way to reason about what actually changed.

Failure pattern cataloguing. When the AI broke a rule, I wrote it down, not as a bug ticket, but as a new clause in the system prompt. "Do not narrate level-ups directly, the game system handles this automatically" is in there because the model confidently told players "You feel a surge of power, you are now level 3!" on three separate playtests. Every clause traces back to a real failure.

What I'd Do Differently

The biggest tension is prompt size vs. model attention. At v9, the system instruction is around 350 lines before any per-turn context is added. Long-context models handle the length fine, but rules buried in the middle of a dense block can get overshadowed by recency effects from the conversation history.

Looking back, I'd front-load the most commonly violated rules (roll-before-outcome, spell prep rules) closer to the top, and probably split the narrative craft guidance into a separate injection that only appears during non-combat turns. There's no reason to spend context budget on "pacing and encounter variety" guidance while the player is mid-fight.

The SRD injection approach scales really well though. Adding a new mechanic like attunement, exhaustion, or diseases just means writing one structured rule object with tags and dropping it into the right category file. The scoring handles the rest.

Getting an LLM to follow structured rules reliably is harder than it looks. The model will do what the prompt describes, but only if the description is precise enough, and precise enough turns out to be a moving target. The real work is translating a rulebook written for human interpretation into something that survives a 50-turn campaign without drifting.

That gap between "the rules" and "what the model actually does" is where most of the engineering lives.

Building something AI-powered and running into consistency issues? I'd love to hear how you're handling it in the comments.

I'm Solo-Devving an AI D&D Game — and Now I'm Building in Public

austin amento — Tue, 17 Feb 2026 00:51:09 +0000

I've been quietly building The SoloQuest for a while now, and I think it's time to start talking about it.

The SoloQuest is an AI-powered solo D&D 5e experience — basically a personal AI Dungeon Master that lets you create a character, pick a scenario, and play through a fully narrated adventure with real ability checks, combat mechanics, and death saves. No scheduling, no party coordination, just you and the dice.

Why I Started Building This

Like a lot of D&D fans, I love the game but struggle to get a group together consistently. I wanted something that captured the feel of sitting at a table — the narrative tension, the mechanical crunch, the "oh no I rolled a 3" moments — but that I could pick up anytime on any device. When I went to the web I found Old Greg's Tavern and thought this is so cool, but I wish I could change a few things.

So I started building it myself.

What's Been Fun

A few things have made this project genuinely enjoyable to work on:

The AI side is endlessly interesting. Getting an AI to act as a competent DM — one that tracks state, enforces rules, creates compelling NPCs, and doesn't just hand you the win — is a fascinating problem. Every iteration teaches me something new about prompt design and how to keep narratives coherent over long sessions. Also its been great practice adding agents and different skills to my workflow.

Character creation was a blast to design. There are 40+ archetypes spanning all the D&D 5e races and classes, each with unique backstories and flavor. Building out that system and seeing characters like a Tiefling Shadowbound Arcanist or a Halfling Quickstep Trickster come to life was incredibly rewarding.

It actually works. There's something special about playing your own product and getting lost in it. I've caught myself doing "just one more turn" testing sessions that turned into actual adventures.

Why I'm Building in Public Now

Here's the honest part: solo development is isolating. You can grind away for months and nobody knows or cares. The momentum comes entirely from within, and some days that tank runs dry.

I've decided to start posting about the process here because I think accountability and community are the missing pieces. I want to share the wins, the weird bugs, the design decisions, the things I've learned about AI, game design, and shipping a product as one person.

If you're into any combination of D&D, AI, indie game dev, or just the solo dev grind, I'd love for you to follow along.

Check It Out

You can try it at thesoloquest.com — your first 50 turns are free. I also have a Discord if you want to connect directly.

More posts coming soon, hopefully. Next up I'll probably dig into some of the technical challenges of making AI follow D&D rules without going off the rails. 🎲

Follow me here on dev.to to keep up with the journey. And if you've got questions about the game or the stack, drop them in the comments — I'm an open book.

Building a D&D inspired Dungeon Crawler with GitHub Copilot CLI

austin amento — Fri, 06 Feb 2026 06:55:54 +0000

This is a submission for the GitHub Copilot CLI Challenge

Introduction

I set out to build a D&D dungeon crawler web game using TypeScript and React—a unique twist that uses Unix-style file system commands (ls, cd, chmod, cat) as gameplay mechanics in an effort to help me remember the commands.

With GitHub Copilot CLI, I transformed this from a scattered idea into a fully-tested, deployed web application in just a few hours.

TLDR; CLI Dungeon Crawler: Try it here

The Approach

Rather than building everything myself, I used Copilot CLI to plan out what exactly I wanted to build, then make smart architectural decisions, and validate everything with tests. Here's how:

Explore - Suggest and explore what I want to build
Design - Make informed architectural and technical decisions
Build - Implement with confidence
Test - Validate constantly
Deploy - Ship to Vercel

Results

✨ Deployed Features:

Random Dungeon Generation (4-13 rooms, validated)
Dynamic Boss System (difficulty scales with dungeon size)
Smart Boss Spawn Detection (triggers when ready)
Victory System (defeat boss to win)
Real-time Combat UI (TypeScript/React)
Expanded Unix-style Commands:
- Navigation: ls, cd, pwd, tree, find
- Interaction: cat, chmod, unlock, grep, touch, head, tail
- Character: status, inventory, whoami
- Combat: attack, defend, cast, flee (with a/d/s/f shortcuts)
- System: help, history, man, echo, mv, rm, quit

How Copilot CLI Improved Development

1. Fast Architecture Understanding

Instead of manually reading code, I got precise answers: "How does dungeon generation work?" → immediate exploration results.

2. Confident Refactoring

Dynamic boss system required changes to game flow. Tests ran instantly. Zero breaking changes.

3. Better Design Decisions

Before implementing boss spawn logic, I verified:

How room state is tracked
The game flow architecture
Best places for integration hooks

4. Comprehensive Testing

Created test suite covering:

Room count constraints
Boss difficulty scaling
Victory detection
State management

5. Ready for Production

Validated, tested code ready for Vercel deployment immediately.

Key Takeaways

Explore the codebase systematically before making changes

Write tests that validate business logic, not just happy paths

Get feedback immediately - tests run in seconds

Deploy with confidence - zero test regressions means zero surprises

Keep the development loop tight - explore → build → test → deploy

The Result

A fun, playable, fully-tested D&D dungeon crawler that:

Works with random dungeons
Scales difficulty automatically
Has smart boss spawn logic
Provides satisfying victory conditions
Is well-documented
Has comprehensive test coverage

But more importantly: a case study in how GitHub Copilot CLI can transform your development process from linear and error-prone to iterative and confident.

Play It Now

The game is deployed and playable. Visit the live application on here

This works way better on a computer vs phone just FYI

Conclusion

GitHub Copilot CLI really changed my approach to this whole project from start to finish
What changed:

Detailed suggestions and creation of a plan
Step by step implementation of suggested plan
By breaking it into steps allowed me to test and build piece by piece
Features were easy to add with its context of the project

All with zero test regressions and complete feature coverage.

If you're building something, use this workflow:

Explore thoroughly
Test constantly
Deploy with confidence

That's the power of GitHub Copilot CLI integrated into your development process.

Austin Amento

Creator of CLI-DND

2026

Forge your experience Without the Chat: Building Proactive D&D Tools with Algolia

austin amento — Thu, 29 Jan 2026 04:39:38 +0000

This is a submission for the Algolia Agent Studio Challenge: Consumer-Facing Non-Conversational Experiences

Beyond the Chatbot

Not every intelligent experience needs to be a conversation.

When you're building a PC, you don't want to chat about compatibility—you want the system to just know that your AMD motherboard won't work with an Intel CPU. When you're creating a fashion look, you don't want to ask "does this match?"—you want suggestions that already complement your choices.

The Adventurer's Codex applies this philosophy to Dungeons & Dragons. While the Oracle module offers conversational discovery, three other modules demonstrate how contextual data retrieval can proactively assist users within existing workflows—no dialogue required.

The Three Non-Conversational Experiences

1. The Forge: Guided Character Building with Smart Compatibility

The Problem: Building a D&D character requires making interdependent choices. Your race should complement your class. Your subclass should fit your playstyle. But traditional builders just show you lists—they don't tell you what works well together.

The Solution: The Forge is a step-by-step wizard that uses Algolia's filtering to proactively surface compatible options at each stage.

2. DM Mode: Contextual Encounter Suggestions

The Problem: Dungeon Masters improvise constantly. A player goes off-script, and suddenly you need a monster. You're writing a scene description and realize you need a trap. Stopping to search breaks creative flow.

My Solution: DM Mode watches what you're writing and proactively suggests relevant encounters—no explicit query needed.

How It Works

The DM has a split-pane interface: text editor on the left, contextual suggestions on the right.

Context-Aware Filtering

The key is the filter: type:Enemy OR type:Trap. DM Mode doesn't show classes, races, or spells—only threats. The system understands the context of what a DM needs.

When the DM writes "spider webs," they don't have to search for spider monsters. The suggestions panel automatically shows Giant Spiders, Phase Spiders, Ettercaps, and Web Traps.

The Creative Flow

The DM keeps writing. Suggestions update silently in the periphery. When they need an encounter, the perfect option is already waiting. No explicit search. No breaking concentration. No dialogue.

This is intelligence injected into the creative workflow, not replacing it.

3. Party Builder: Proactive Composition Analysis

The Problem: A D&D party needs balance. Without a healer, everyone dies. Without damage, combat takes forever. Without a tank, the squishy wizard gets targeted. But most groups don't realize they have a problem until they're mid-dungeon.

My Solution: Party Builder proactively analyzes group composition and surfaces warnings before the adventure begins.

Try It Yourself

Experience smart, non-conversational assistance:

Enter The Forge →

Build a character. Run an encounter. Assemble a party. See how contextual intelligence enhances every step—without a single chat bubble.

The Technical Pattern

All three experiences share a common technical approach:

1. Observe User Context

// The Forge: Track selected class
const [selectedClass, setSelectedClass] = useState(null);

// DM Mode: Watch text content
const [sceneText, setSceneText] = useState('');

// Party Builder: Monitor party roster
const [party, setParty] = useState([]);

2. Derive Intent from Context

// The Forge: User selected Wizard → they want Wizard subclasses
const subclassFilter = `type:Subclass AND parentClass:${selectedClass}`;

// DM Mode: User is writing a scene → they might need encounters
const encounterFilter = 'type:Enemy OR type:Trap';

// Party Builder: User has 4 characters → analyze their composition
const roleAnalysis = analyzePartyRoles(party);

3. Proactively Retrieve Relevant Data

// The Forge: Fetch compatible races sorted by stat bonus
<Configure
  filters="type:Race"
  optionalFilters={[`statBonuses:${primaryStat}`]} // Boost matching stats
/>

// DM Mode: Search monsters matching scene keywords
<SearchBox defaultValue={debouncedSceneText} hidden />

// Party Builder: No search needed—analysis is computed from indexed data
const recommendations = getRecommendationsForMissingRoles(roleAnalysis);

Future

I think this could be fun to keep building the codex and the Algolia features, it's been very exciting learning about how the platform works

The Oracle: A Conversational D&D Character Discovery Experience

austin amento — Thu, 29 Jan 2026 04:39:28 +0000

This is a submission for the Algolia Agent Studio Challenge: Consumer-Facing Conversational Experiences

The Problem with Choice Paralysis

"I want to play a character like Gandalf, but cooler."

"Something that can heal but also deal damage?"

"I don't know... maybe like a sneaky magic user?"

These are real things players say when creating Dungeons & Dragons characters. They know the feeling they want, but they're facing 12 classes, dozens of races, and hundreds of subclasses. Traditional character builders force players to browse categories and read walls of text. But that's not how people actually think about characters.

The Oracle is my answer: a conversational interface that lets players describe their fantasy in natural language and receive intelligent, contextually relevant suggestions powered by Algolia's search capabilities.

What is The Oracle?

The Oracle is a guided discovery tool disguised as a mystical advisor. Players approach it like they would a wise sage in a fantasy tavern:

Player: "I want to be a frontline warrior who uses divine magic to protect allies"

The Oracle: Returns Paladin class, Oath of Devotion subclass, Protection Fighting Style, and compatible races like Human and Dragonborn

The experience feels like a conversation, but under the hood, it's powered by Algolia's intelligent search with the richly indexed D&D knowledge base.

Try The Oracle

Experience the conversational character discovery yourself:

Consult The Oracle →

Describe your fantasy. Receive your destiny.

The Conversational Flow

Stage 1: The Open Question

The Oracle opens with a search interface that invites natural language:

┌─────────────────────────────────────────────────────────┐
│  🔮 The Oracle                                          │
│                                                         │
│  "Describe your ideal adventurer, and I shall reveal    │
│   the path that awaits you..."                          │
│                                                         │
│  ┌───────────────────────────────────────────────────┐  │
│  │ I want to be a wise healer who protects nature    │  │
│  └───────────────────────────────────────────────────┘  │
│                                                         │
└─────────────────────────────────────────────────────────┘

Players can type anything—there's no wrong input. The Oracle interprets intent, not just keywords.

Stage 2: Guided Playstyle Prompts

For players who need a starting point, we provide conversational prompts disguised as playstyle choices:

"I want to stand in front and take hits" → Frontline Fighter
"I want to deal massive damage" → Damage Dealer
"I want to cast powerful spells" → Spellcaster
"I want to keep my allies alive" → Healer
"I want to be sneaky and cunning" → Stealth & Cunning
"I want to talk my way through problems" → Face & Diplomat

Each playstyle triggers a semantically rich query that surfaces relevant options. When a player clicks "Healer," we don't just search for "healer"—we search for:

"healing support restoration life cleric druid divine nature protect ally"

This targeted prompting ensures comprehensive, contextually relevant results.

Stage 3: Contextual Results

Results are grouped conversationally, as if The Oracle is explaining options:

┌─────────────────────────────────────────────────────────┐
│  The Oracle has spoken...                               │
│                                                         │
│  📜 RECOMMENDED CLASSES                                 │
│  ┌─────────────────────────────────────────────────┐   │
│  │ 🛡️ Cleric                                        │   │
│  │ "Divine spellcasters who channel the power of   │   │
│  │  their deity to heal wounds and smite enemies"  │   │
│  │  Primary Stat: Wisdom                           │   │
│  └─────────────────────────────────────────────────┘   │
│  ┌─────────────────────────────────────────────────┐   │
│  │ 🌿 Druid                                         │   │
│  │ "Guardians of nature who wield primal magic     │   │
│  │  and can transform into beasts"                 │   │
│  │  Primary Stat: Wisdom                           │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  🧬 COMPATIBLE RACES                                    │
│  ┌─────────────────────────────────────────────────┐   │
│  │ 🧝 Wood Elf (+2 DEX, +1 WIS)                     │   │
│  │ 🌲 Firbolg (+2 WIS, +1 STR)                      │   │
│  └─────────────────────────────────────────────────┘   │
│                                                         │
│  ⚔️ RELATED OPTIONS                                     │
│  │ Life Domain • Circle of Dreams • Healing Word   │    │
│                                                         │
└─────────────────────────────────────────────────────────┘

Stage 4: Refinement Through Dialogue

The conversation continues. If the player selects "Druid," The Oracle responds with follow-up context:

"A Druid who protects nature... Perhaps you seek the Circle of the Shepherd, who calls upon spirit guardians, or the Circle of Dreams, connected to the mystical Feywild?"

Each selection narrows the search, creating a back-and-forth dialogue that guides players to their perfect character.

How Algolia Powers the Conversation

Rich Data Indexing

The D&D codex is indexed with semantic richness that enables natural language understanding:

{
  "name": "Cleric",
  "type": "Class",
  "description": "Divine spellcasters who channel deity power",
  "tags": ["healer", "support", "divine", "holy", "priest", "restoration",
           "protection", "light", "life", "armored caster", "wisdom"],
  "primaryStat": "Wisdom",
  "playstyles": ["healer", "support", "frontline"],
  "fantasy_archetypes": ["priest", "paladin-lite", "battle medic", "holy warrior"]
}

When a player types "I want to be a battle medic," Algolia matches against fantasy_archetypes, tags, and description—not just the class name.

Synonym Configuration

We configured synonyms in Algolia to handle player language:

gandalf => wizard, wise, magic, staff, grey
legolas => ranger, archer, elf, dexterity, bow
tank => defender, frontline, armor, shield, protection
glass cannon => damage, squishy, powerful, fragile

Future

I hope to keep building on this platform as it's been a blast getting to know the Algolia system

Portfolio Dungeon Crawler

austin amento — Mon, 19 Jan 2026 01:06:05 +0000

This is a submission for the New Year, New You Portfolio Challenge Presented by Google AI

About Me

My name is Austin, I am a self taught developer who lives in the Pacific North West. I love learning new things related to development and enjoy playing with new AI models.

What I Built

I thought it would be fun to make my resume be hidden in a DnD text game. Where you will need to explore the dungeon to fully unlock the full portfolio. I wanted to create an experience that you can have unique experiences each time (thanks to the gemini DM). After uncovering the mysteries of the dungeon I figured you need to end the experience with a boss battle to feel complete. Give it a try and let me know what you think!

Portfolio

Feel free to explore the dungeon and experience my portfolio below!

How I Built It

I built this using AI studio and deploying on Google Cloud. I have really enjoyed building some MVPs using AI Studio. This was inspired by a solo project I'am working on which is a Solo Dnd experience that I am hoping to release in the coming weeks.

What I'm Most Proud Of

Im really excited for the way you can uncover hidden parts of your journal (my portfolio) as you explore the dungeon. Also I wanted a fun way to wrap up the experience once all the information was discovered so I included a boss fight to signify you have completed the dungeon.

Forem: austin amento

The Dev Journal That Writes Itself (And Gives You XP)

What I Built

Who It's Actually For

The Growth Narrative

The Architecture

The Four Notion Databases

The Full Gamification Engine (V2)

Show Us the Code

claude-config/CLAUDE.md — The Agent Identity

claude-config/commands/pulse-check.md — The Core Workflow

claude-config/commands/weekly-recap.md — The Recap Generator

How I Used Notion MCP

notion_search — Database discovery

notion_query_database — Precise filtered reads

notion_create_page — Writing session data

notion_update_page — State management

notion_update_database — Schema migration

Auto-creating databases on first run

Why Notion MCP Was the Right Choice

Building SoloQuest: Letting Gemini Be the DM, and Code Be the Referee

What I Built with Google Gemini

Demo

What I Learned

The Most Important Design Decision Was Deciding What the AI Was Allowed to Do

Google Gemini Feedback

What Worked Really Well

Where I Hit Friction

Where I'm Headed Next

Pinned Brews - A social coffee community

The Community

What I Built

Demo

Code

How I Built It

What I Learned

What’s Next

Prompt Architecture for a Reliable AI Dungeon Master

Layer 1: The System Prompt as a Rules Contract

Layer 2: Injecting the Rules Right When They're Needed

Layer 3: Game State as the Source of Truth

Layer 4: Enforced Response Structure

Testing: No Unit Tests, Just Instrumented Playtesting

What I'd Do Differently

I'm Solo-Devving an AI D&D Game — and Now I'm Building in Public

Why I Started Building This

What's Been Fun

Why I'm Building in Public Now

Check It Out

Building a D&D inspired Dungeon Crawler with GitHub Copilot CLI

Introduction

The Approach

Results

✨ Deployed Features:

How Copilot CLI Improved Development

1. Fast Architecture Understanding

2. Confident Refactoring

3. Better Design Decisions

4. Comprehensive Testing

5. Ready for Production

Key Takeaways

The Result

Play It Now

Conclusion

Forge your experience Without the Chat: Building Proactive D&D Tools with Algolia

Beyond the Chatbot

The Three Non-Conversational Experiences

1. The Forge: Guided Character Building with Smart Compatibility

2. DM Mode: Contextual Encounter Suggestions

How It Works

Context-Aware Filtering

The Creative Flow

3. Party Builder: Proactive Composition Analysis

Try It Yourself

The Technical Pattern

1. Observe User Context

2. Derive Intent from Context

3. Proactively Retrieve Relevant Data

Future

The Oracle: A Conversational D&D Character Discovery Experience

`claude-config/CLAUDE.md` — The Agent Identity

`claude-config/commands/pulse-check.md` — The Core Workflow

`claude-config/commands/weekly-recap.md` — The Recap Generator

`notion_search` — Database discovery

`notion_query_database` — Precise filtered reads

`notion_create_page` — Writing session data

`notion_update_page` — State management

`notion_update_database` — Schema migration