Posts on Tiziano Basile | Software Engineer

Wild Shift Devlog #2: It's always the semicolon

Thu, 12 Nov 2026 00:00:00 +0000

Second update on The Debugger 0x03: Wild Shift, my GitHub Game Off 2026 entry (theme: SHIFT). If you missed it, Devlog #1 covered the register and the shift. This post is a mirror of the second devlog on itch.io. You can also play the current build in the browser on the game page.

Two bosses down, one to go. Since the last devlog The Debugger 0x03: Wild Shift got its first two real bugs to fix, a duck that talks, and two new bits for the register.

Infinite Loop: the first real bug (Epic 3)

Last time I promised a snake made of code. Here it is: Infinite Loop, a ring of 24 { } segments biting its own tail, with an iteration counter i = 0 floating above it.

It never stops. The ring spins, drifts toward you and gets 5% faster on every lap. i++ ticks up as it goes.
It’s always the semicolon. The point where head meets tail is the loop condition, a ; that travels around the ring. Once per lap it opens for 1.5 seconds, and that’s the only place you can hurt it.
Weak windows. Every phase has an ordered pair of bits that “reproduces” the bug. Hit the boss with it and it’s Patched for 3 seconds: your damage goes from ×0.5 (// resisted) to ×1.5 (CRITICAL, in caps, with a flash). Phase 1 wants A→D (Dash Strike through the open ;), phase 2 wants D→A, so you have to shift back and forth to patch and then cash in.
Three phases, four attacks. Head Rush (the head uncoils and charges), Constrict (the ring re-centres on you and shrinks: dash through the body to get out), and in phase 3 a Nested Loop: it splits into an outer and an inner ring, each with its own ;, and they open in turn. Outer ring, A→D. Inner ring, D→A. Switching rings means switching windows. Plus a ; Spit projectile, because of course.

Infinite Loop in phase 2 (i = 3) closing around the player. On the left, the duck is still nagging me to shift.

The duck gets a voice

The rubber duck now lives in a text bubble under the register and teaches the fight with jokes: “See the semicolon? It’s always the semicolon. Hit it when it opens.” If you just stand there, it nudges you (“Go on, shift. It’s waiting.”) and after a few seconds the loop starts anyway.

The lines are typed out with a squeak and a gibberish voice made with mumble-speech, a small library of mine that turns text into gibberish speech. Its v0.3.0 added a Godot web build, so the duck can talk in the browser too. No voice acting, just a very confident duck.

Defeat and Harvest

When the bug dies, it collapses into the line of code it should have been: for (i = 0; i < n; i++) { }. Then the Harvest screen shows the bit it dropped and the new windows it opens in your ring.

Harvest: Infinite Loop drops LOOP. The register becomes [A, D, L] = 0x07 and D→L unlocks Echo Dash.

LOOP, Echo Dash and Breakpoint (Epic 4)

LOOP (L) = Echo. It replays your last solo move from where you’re standing now, at 70% damage. Slash, step away, Echo: a second slash where you are. It has a 1.5 s cooldown, and if you haven’t done anything yet it just does nothing (no cooldown wasted).
Echo Dash (D→L). Dash, then Echo: a second dash you can point in a new direction, invulnerable the whole way through with no gap. It’s how you pass through a boss, and against the next one it does more than that.
Breakpoint (Space). Freezes the simulation for up to 2 seconds, but shifting still works. The screen dithers, a red breakpoint dot appears, and you get to think. 12 s cooldown. Finally, a debugger that works.
Duck hints. If you’re stuck, the duck tells you the weak window: "Quack. Weak window: D→A.". It speaks on Breakpoint (once per phase) and every third death on the same boss. In the Nested Loop phase it names the window of the ring that opens next.

Null Pointer: a ghost that points at nothing (Epic 5)

The second bug is Null Pointer, a ghost made of null glyphs. It’s invisible: you only see it while it attacks, for a few frames when you hit it, and for a second after an Echo Dash goes through it.

Finding it. A column of falling null glyphs drifts under it, and it hums, panned left or right by where it is. The sky comment reads // FIXME: who owns this pointer?
Pointer Grab: a * appears behind you, then it grabs. Null Rain: five marked areas, then null falls on them.
Dangling Pointers (phase 2): two decoy ghosts. They don’t hum, and hitting one just dispels it.
NullPointerException. Swing a slash at nothing while the ghost is close and you’re stunned for a third of a second. Don’t attack blindly.
Watch (hold R). Reveals the ghost and its decoys, shows the name of its next attack, the bit it will drop and its weak window. You move at half speed and can’t act while you hold it, so it’s a peek, not a crutch.

Pointer Grab’s tell: a * lands right behind the player (@) while the ghost closes in. [D, L] is live, so Echo Dash is one K away.

Null Rain: five areas marked, and the column of null glyphs that gives the invisible ghost away.

Holding Watch: the ghost shows up, with its next attack (pointer_grab), its drop (N) and its weak window (D→L).

At the start of the fight the duck introduces the two new skills (“Hold R. Pointers point *somewhere*.”). Beat it and it collapses into if (ptr != null) ptr.deref(); and drops NULL:

Null Dodge (N): half a second of intangibility, at half speed.
Clean Catch: if an attack passes through you during a Null Dodge, your next damaging hit deals ×1.5, on top of Patched.

(The “FIGHT N / boss index N” text in the middle of the arena is still a placeholder from the scene flow: it goes away in polish.)

Fun fact: the GDD planned Epic 5 for November 18–21. It was done on November 12, so I’m almost a week ahead of schedule.

Housekeeping

The game is live on itch.io as a web build (about 28 MB), with a deploy from CI. Running it in a real browser found two pause bugs (resume with P or a click when fullscreen eats Esc, and a game frozen after a focus-loss pause), both fixed.
The web build budget went from 30 to 32 MB to make room for the voice and the second boss.

How it’s made

Same as before: I’m the director and the playtester, AI agents (Claude) write the code from specs I approve with the BMAD Method, and every story is a pull request with code review and automated tests. The test suite went from 55 to 95 test files. Everything is public in the GitHub repo.

Next up

One bug left, and it’s the worst kind. It reads and writes memory it shouldn’t, and it doesn’t care that the register is yours. Plus an intro and an ending, so the run finally has a beginning and a return.

Thanks for reading!

Wild Shift Devlog #1: Your weapon is a byte

Tue, 10 Nov 2026 00:00:00 +0000

It’s November again, which means GitHub Game Off. Last year I built Grav-Sync in plain JavaScript; this year the theme is SHIFT and my entry is The Debugger 0x03: Wild Shift, a top-down boss rush made with Godot 4.7. You can follow it on itch.io, and this post is a mirror of the first devlog I published there.

The idea in one line: your weapon is a bit register. Shift it left or right mid-fight, and the two leftmost bits become your two action buttons. A present-day developer and their rubber duck get pulled into a fantasy RPG where the monsters are literal software bugs: Infinite Loop, Null Pointer and Segfault.

Day 1: making it run in the browser (Epic 1)

Before writing any gameplay, I wanted the boring stuff to work: a Godot 4.7 project that runs at a locked 60 Hz with pixel-perfect integer scaling, a web export that stays under 30 MB, and a CI pipeline that runs the tests on every pull request.

Then the shell of the game:

a title screen with “press to start”, because browsers won’t play audio before your first input
The Clearing, the arena, framed by an IDE-style HUD: register panel on the left, log panel at the bottom, line numbers down the edge
the whole scene flow with placeholders (Title → Intro → Fight → Harvest → … → Ending)
auto-pause when you switch tabs, so the boss doesn’t kill you while you read Slack

Days 2–3: the shift has to feel good (Epic 2)

The goal of Epic 2 was simple to say and hard to do: shifting should feel great in an empty arena, before there’s anything to fight.

The register is a ring. Q rotates it <<, E rotates it >>. It only contains the bits you own, so you can never end up in a dead state. The HUD also shows its byte value, so your build is literally 0x03.
Shift juice: the register slides with a small overshoot bounce, a mechanical key-click (two different sounds for left and right), and your weapon inverts for 4 frames.
ATTACK and DASH: a 3-hit slash chain and an 8-frame invulnerable dash.
Ordered combos: the order matters. [A, D] (attack then dash) is Dash Strike, [D, A] is just a dash followed by a slash.
Hit feedback: hit-stop, glyph particles flying off the target, and every hit printed as a console.log line.

The 3-hit slash chain on the practice target: glyph particles and damage logged to the console.

After one << the active window is [A, D]: J→K fires a Dash Strike.

Death and retry: you have 5 HP, shown as 0b11111. When you die you get Process exited with code 1, and one key puts you back at the start of the fight in under 2 seconds.
A practice target: /* test */, with infinite HP and a frame counter, so I can check the combo numbers on screen.

Under the hood the whole simulation is deterministic: it runs on a fixed 60 Hz clock, with seeded randomness and recorded input replays. That means a bug I find while playing can be replayed exactly in a test.

(The “FIGHT 1 / boss index 0” text in the screenshots is a placeholder: the arena is still waiting for its first boss.)

How it’s made

I’m making this solo, as director and playtester. The code is written by AI agents (Claude), following specs I write and approve with the BMAD Method, the same workflow I described in BMAD, end to end: game brief → GDD → architecture → one spec per story. Every story is a pull request with code review and automated tests (55 test files by the end of Epic 2). All the design docs are public in the GitHub repo.

Next up

The first real bug: Infinite Loop, a snake made of code that repeats its attacks… until you find its weak window. Plus the rubber duck, who finally gets a voice, powered by mumble-speech, my own library: v0.3.0 added Godot web support, so the duck can talk in the browser too.

Thanks for reading!

The NeuroDEVergent

Sun, 11 Oct 2026 00:00:00 +0000

When I need to focus on something demanding I put my headphones on and start some thrash metal, at a volume any ENT doctor would probably advise against. I’ve tried white noise too, which is what everyone recommends, but it has never worked for me; thrash does, and it doesn’t even matter whether the track is instrumental or has vocals. My theory is that the tight, precise rhythms act as white noise in place of white noise, filling the space where my head would otherwise go looking for something else to do. If you want to try it, my suggestion is Metallica’s …And Justice for All, which is the album I put on when I need maximum focus, although, being a bass player, I usually listen to this version with the bass put back in the mix: I like the original, but I’d rather hear the bass.

For years I took this as one of my fixations, one of the many things that have always made me feel a bit different from everyone else. Last week I was diagnosed with combined-type ADHD, along with giftedness, and to be honest I still haven’t quite worked out what that changes; all I know is that quite a few of those things now have an explanation slightly more serious than “that’s just how I am”.

I’ve felt different from other people since I was a kid although back then, at least on the inside, it didn’t weigh on me; if anything, I simply felt smarter, I had interests other kids my age didn’t have, like science, the human body and space, and I was into video games at a time, the second half of the ’90s, when they weren’t yet the mainstream thing they are today. Above all I wanted to be a grown-up and that too has only found an explanation now because apparently that urge to be a grown-up was tied precisely to the giftedness.

Growing up, though, that feeling of being different turned into something less harmless, and in my teens it became a feeling of being better than others. I’d already been bullied in primary school in a way I don’t want to talk about here and I was bullied again in middle school, where it was mostly psychological; to this day I couldn’t say how much of it came from that sense of superiority and how much from the fact that I really was different, probably a bit of both.

Then came the inability to make friends or at least to have social interactions that actually fulfilled me; the few friendships I’d managed to build I lost anyway because I got bored quickly of people as much as of situations and I’d end up distancing myself by behaving like a jerk.

Then came the trouble concentrating: I’d drift off, procrastinate constantly, and I did it mostly with the activities that required the most mental effort, which, coming from someone who’s a developer for a living, sounds almost like a joke. It was while trying to understand what was wrong that I came across ADHD and at first I didn’t really see myself in it; only when I stopped watching TikTok and Instagram content and moved on to more serious sources I started to actually understand the subject: the books and videos of Dr Valerio Rosso and the work of various American psychologists and psychiatrists.

In there I started recognising myself in quite a few things: first of all the difficulty concentrating and getting constantly distracted by low-value things, but also feeling drained by context switching, which happens to me even when I’m not getting distracted at all; then the difficulty with relationships, which I’ve already talked about.

There were other things, though, that I never saw myself in: I don’t have the physical hyperactivity, the mental kind yes, and I’m not the type who loses things. Even the famous poor sense of time works differently in my case from how it’s usually described, because it’s not that I lose track of time during the day, it’s more of a long-term thing: I’m 37 and I don’t realise it, I feel much younger, as if I still had all the time in the world ahead of me.

About four years ago I had a first assessment at the public mental health centre in my city, with one of the psychiatrists there. I wasn’t given any specific test, and four things were enough to rule out ADHD: I did well at school, I’d taught myself to play bass, I’d taught myself English, and I’m in a long-term relationship with my partner. At the time I was puzzled, then I let it go and for a while I didn’t think about it any more. In hindsight, nearly all the things I’d been given as proof that I couldn’t have ADHD are exactly the ones giftedness makes possible, and which had therefore ended up hiding it.

The nagging doubt came back this year, in June, during a more exhausting period than usual, both for concentration and for organising my life, which is something I’ve always sucked at. This time I looked for a serious professional and found one almost by chance, among ADHD podcasts: Dr Stefano Bramante, a psychiatrist and the man behind the Brain on Fire podcast, who has also published a mock ADHD assessment on YouTube. He first referred me to one of his collaborators, Dr Daniele Tatano, a psychologist, who did an initial assessment that Dr Bramante then validated with his own; because of their availability, though, I had to wait until September.

It was a completely different experience from four years earlier. Over six weeks I had two sessions with Dr Tatano and one with Dr Bramante, cognitive tests, questionnaires to fill in myself and others for my partner and my mother to fill in, interviews, and they even wanted to see my primary and middle school reports. I liked the approach, structured and not superficial at all, but what surprised me most was seeing it confirmed in black and white, between the interviews and the school reports, that as a kid I really was very intelligent, and that the feeling of being different I talked about at the beginning wasn’t just in my head.

Then there’s work, where all of this shows up in fairly recognisable ways, at least now that I know what to look for. I need new problems to stay engaged with a project, and my brain switches on with urgency: I tend to put off difficult tasks, but when the deadline gets close and the pressure rises, hyperfocus kicks in almost automatically, and the thing I’d been putting off for days becomes the only thing I can think about. Then there’s documentation, which I struggle to find my way through, and there are long meetings where I only play a marginal role, which are by far the most tiring for me. It’s not all bad, though: I work well under pressure, even if it doesn’t do me much good; I think I’m good at lateral thinking, and I’m obsessed with clean, well-written code, which in a job like mine is hardly a flaw.

As for actual tools, apart from the thrash metal, I’ve never had many: I’ve always put events and appointments in Google Calendar, and since March I’ve been using a bullet journal. It’s not the first one I’ve started, I abandoned all the others, but this one is still going after seven months, and for me that’s already something. At first I mostly used it for tasks, work and otherwise, then I didn’t want to keep track of work by hand any more and did what for an engineer is almost an occupational hazard: I automated it.

I’ve instructed Claude to log every action, analysis, PR or comment I make or am asked for in my Logseq journal, with links to the PRs and comments, both on GitHub and in the issue tracker. The result is that I can now give much more structured feedback on my day-to-day work, and reconstructing what I did days or weeks later has become much easier. These days I use the bullet journal almost only for to-dos, and I’ve started, timidly, to push myself to write down a few thoughts in it too, a few emotions, that kind of thing.

If you ask me what I felt when I got the diagnosis, the honest answer is that I don’t know, and as I said at the beginning I’m not even sure what changes from here on. I know I’m planning to start therapy, partly to work on organising my life, which I really want to get better at.

And I know one more thing, which is maybe the only thing I’ve been clear about from the very first moment: I don’t want to use ADHD as an excuse, either for not doing things or for not organising my life.

Yes, you still need to know how to code

Mon, 14 Sep 2026 00:00:00 +0000

AI writes good code, faster than me most of the time and usually cleaner than my first pass. I’m not going to argue otherwise and I’m not interested in the version of this piece where the craft is sacred and typing things by hand builds character.

What I think is that the hard part of the job was never the typing, it was the part nobody watches: working out whether the thing is correct, whether it will hold, whether it should exist at all, and that part hasn’t got cheaper.

Actually, “hasn’t got cheaper” is too soft. Reading is cheap when you can trust the author’s intent and expensive when you can’t, and a model hands you volume with no stable intent to anchor to, so the careful read, the kind that catches the subtle thing, is exactly the one that gets expensive, and exactly the one people skip. The cost didn’t vanish when generation got cheap, it moved to the other side of the ledger where it’s harder to see and much easier to skip.

The reason it’s easy to skip is that the output is optimised to look right, not to be right. A model trained to produce the most likely continuation leans, over and over, in the same direction: toward the plausible. A developer who can’t read code doesn’t avoid that cost, they defer it into debt and into bugs they aren’t equipped to notice.

A prompt is not a task

Write me a function that does X looks like handing off a chore but it isn’t. Buried in it are decisions about structure, trade-offs, failure behaviour, and the quiet one underneath: what “correct” means in this particular domain. And if you can read the output, you can see those decisions and keep them. You notice that it reached for an ORM where a query would have done, that it picked a pattern that fights a constraint it doesn’t know about, that it decided errors should be swallowed instead of raised. Some of those you’ll accept, that’s fine; the point is that you accepted them. If you can’t read the output, you’re not delegating how something gets done, you’re accepting what gets done, in bulk, and you won’t notice the difference until much later.

Where plausible actually bites

The clearest case is debugging, because there the gap shows up as a test going green. A green test never could tell you whether the cause was gone or just hidden, that’s not new; what’s new is the speed and the fluency, the model reaches for the change that silences the symptom, hands it back looking finished, and does it fast enough that the pause where you’d have got suspicious never happens.

Review has a version of the same problem, except worse, because the dangerous code isn’t the code with obvious bugs in it, the model usually catches those. The dangerous code is locally fine and globally wrong: consistent with the file it lives in, in violation of something that lives three modules away, and the model isn’t holding a picture of your system, so if you aren’t either, you’re not reviewing anything.

Security is where I’d be most nervous, because insecure code and secure code look the same to an untrained reader: the query gets parameterised in the path you were looking at and concatenated in the branch you weren’t, the permission check reads beautifully and still lets you fetch an object by guessing its ID, somebody logs a token “for debugging” and it survives into production. None of these fail a quick read, you catch them only if the threat model is already in your head.

Architecture is a quieter failure: ask for a design and you get roughly the average of everything that’s been written about designs, which means the well-represented answer: the service boundaries, the fashionable abstraction, the thing that made sense for a company forty times your size. It has no idea you’re three people, or that the latency budget makes that choice unworkable, and it doesn’t volunteer why not something simpler, which is the question that would have saved you.

Then there’s the thing I don’t have a clean name for: the model rarely tells you this shouldn’t be built, it won’t volunteer that the problem is the wrong problem, it defaults to yes unless you build the friction that makes it say no. That kind of judgement lives in the things that don’t get built, and a system whose only output is the artefact can’t represent it at all.

None of this means the only defence is a human squinting at a diff. Linters, type systems, scanners, a second model told to go looking for the bug: they catch a real share of what I’ve described, and you should use all of them, they raise the floor. But every one of them checks against a shape someone already knew to encode, so the failures that survive are the ones that don’t match a shape, and something still has to decide which of the machine’s findings matter and which it missed. That something is the picture of the system in your head.

But the compiler

The obvious objection is that this is the assembly argument wearing new clothes: nobody reads assembly, the abstraction won, and complaining about it is just nostalgia with a technical vocabulary.

I think the difference is real, and it’s the entire point. We stop looking underneath a layer, a compiler, a garbage collector, someone else’s merged pull request, when its failures are rare enough and cheap enough to catch downstream, not because it’s provably correct: the compiler earns that trust, and when it’s wrong, that’s a famous bug with a ticket number. An LLM hasn’t earned it, its failure surface is unbounded and shaped by the context you’re in, so the bet that mistakes will be rare and caught downstream doesn’t hold, and something you have to check on those terms is not an abstraction, it’s a collaborator, and to review a collaborator’s work at one level you need to understand the level below it.

The second objection is that the models will get better and this is all temporary. I’m not going to bet against that, it’s a bad bet and I don’t need it, but better generation doesn’t dissolve the problem, it moves it up a level: the more capable the writer, the more you’re checking work that looks superhuman, and checking a collaborator you can’t out-reason still means understanding the level it works at, so verification doesn’t get free just because generation does. And underneath even flawless verification there’s a floor no model reaches for you: somebody has to say what to build, which trade-offs are acceptable, and what “correct” means for these users, and you can’t prompt your way to that if you don’t already know it. The better the tools get at the how, the more everything depends on the what.

What’s actually left

Not syntax, not writing loops from memory: on that, the optimists are right, and it would be silly to defend it. When I say you still need to know how to code, I mean you need to be able to read it and reason about it, to hold what it’s doing in your head well enough to tell right from plausible; writing it was only ever the way most of us learned to do that.

What’s left is the model in your head that lets you find your own ignorance: knowing where to look, which question collapses the thing, when green isn’t enough. That was never omniscience; I don’t understand every line I get back either, and I don’t understand every instruction my compiler emits, but the difference is that I know when I don’t understand something, and roughly where to point the torch.

Though I’ll admit I can’t draw that line precisely, and I’m suspicious of anyone who says they can. I’ve stopped looking underneath the compiler entirely; I still look underneath the model, every time. Somewhere between those two there’s a threshold where checking stops being worth it, and I don’t know how you’d recognise it from the inside; you’d only find out afterwards, from the thing you failed to catch.

None of this is about juniors, it applies to me at least as much: the tool has no idea how long you’ve been doing this, and leaning on it without the underlying model produces the same class of mistake regardless. But there’s an uncomfortable version I don’t want to skip: the model in your head got built by writing and debugging the very things the tool now does for you, and if you start out leaning on it, rationally, because it’s faster and cleaner than your first pass, you may never build the model at all, and I don’t have a tidy answer to that, I just don’t think the answer is to pretend the skill stopped mattering.

That’s the part worth keeping in mind: the tool multiplies whatever you bring, and it is extremely relaxed about what that is.

A BMAD workflow, end to end: shipping a feature the spec-driven way

Thu, 06 Aug 2026 09:00:00 +0000

If the only way you’ve ever worked with an AI is to vibe code with it, which is to say you open the editor, type a prompt, and keep whatever looks roughly right, then this is the post I wish someone had handed me back when I was doing exactly that. It isn’t another argument about why spec-driven development is better, because I already made that case here; it’s simply one complete pass through a real workflow, with the actual commands, so that you can see for yourself what the whole thing looks like from the inside.

Together we’ll build one small feature with BMAD, taking it all the way from a vague idea to reviewed code, and although the example is deliberately thin it is also complete, running the full sequence of brainstorm → spec → architecture → story → implementation → review without waving our hands over any of the parts that usually get skipped, so that by the end you can see exactly where the friction lives and what it buys you in return.

If you’ve never met the BMAD agents before, the previous post introduces the crew, and while you don’t strictly need it in order to follow along here, it does help to know that “John” is a product manager and “Amelia” is a developer rather than people I actually work with.

The example is a URL shortener where links can expire. All the artifacts you’ll see below are illustrative snippets from that walkthrough.

The feature (and the trap)

Here’s the feature: a URL shortener where links can expire.

Now watch how a vibe-coding session usually starts, because you’d open a chat and type something like this:

Build me a URL shortener in [your stack]. Links should be able to expire.

That prompt feels complete, but it really isn’t, because it’s a specification riddled with holes, and the AI is going to quietly fill every one of those holes with a guess that you never actually got to see it make, so it’s worth counting them:

When does a link expire? After a fixed TTL? At an absolute timestamp you pass in? After N clicks? “Expire” is three different features.
What happens when someone hits an expired link? A 404? A 410 Gone? A redirect to a “this link expired” page? These are observably different behaviors, and a caller integrating with you will build against whichever one you pick.
Do we count clicks? If expiry can be click-based, you need a counter. If it can’t, you probably still want analytics. That’s a storage decision hiding inside a one-line prompt.
What’s the ID scheme? Random short codes? Collisions? Custom aliases?

Vibe coding doesn’t make any of these decisions go away, it simply arranges for someone else to make them silently and invisibly at generation time, and then it hands you back a pile of code that you now have to reverse-engineer in order to discover what was actually decided on your behalf. So when the “expired link returns 404” bug report lands on your desk three weeks later, you’ll find yourself debugging a decision that nobody ever consciously made in the first place.

Spec-driven development, at its core, is really just this: you make the decisions before you write the code, on purpose, and in a place where you can actually see them, and BMAD is simply one way of running that process with the AI working inside the loop with you rather than against you.

Let’s run it.

The mental model, in 30 seconds

Two things to hold in your head before we start:

BMAD is a team of agents rather than a single assistant. Each one is a persona with a specific job to do, so there’s an analyst who interrogates the idea, a product manager who writes the requirements, an architect who makes the technical calls and a developer who implements them, and you move between these personas deliberately as the work progresses. In the commands that follow, every phase can be run either by summoning the persona directly with /bmad-agent-* or by invoking its underlying workflow with /bmad-*, and you should feel free to use whichever of the two you prefer.
The real output of the early phases is not code at all, it’s artifacts. These are things like a brief, a PRD, an architecture document and a story file, all of them plain markdown that lives right there in your repository, and the code itself only arrives last, sitting downstream of a set of documents that you can read, review and version like anything else.

Broadly speaking there are two stages to all of this, a planning stage in which you work out what to build and how to build it, followed by an implementation stage in which you actually build it, and the whole point of the arrangement is that planning leaves behind durable, reviewable artifacts which then carry all of their context forward into implementation, so that the AI writing your code is working from a genuine spec rather than from a vibe.

flowchart LR
idea([Vague idea]) --> A
subgraph Planning
A["🔍 Analyst (Mary)<br/>brainstorm"] --> P["📋 PM (John)<br/>PRD / spec"]
P --> W["🏛️ Architect (Winston)<br/>architecture"]
W --> S["📝 Story<br/>context handoff"]
end
subgraph Implementation
S --> D["💻 Dev (Amelia)<br/>implement"]
D --> R["🔎 Code review"]
end
R --> code([Reviewed code])
A -.-> brief[/brief.md/]
P -.-> prd[/prd.md/]
W -.-> arch[/architecture.md/]
S -.-> story[/story.md/]

🔍 click the diagram to enlarge

Everything drawn with a dotted line there is a file that ends up in your repository, and that is precisely the part of the process that vibe coding never produces.

Phase 1, Brainstorm: drag the hidden decisions into the light

We start with Mary, the analyst, and a brainstorming session:

1
2
3


/bmad-agent-analyst # then pick the brainstorming capability
# or go straight to it:
/bmad-brainstorming

The move here is genuinely counterintuitive if you’re accustomed to prompting an AI for output, because you’re not asking it for an answer at all, you’re asking it to interrogate you, and Mary’s entire job in this session is to ask you the questions that you quietly skipped over. This is exactly the moment where those four hidden decisions from the trap section earlier stop being invisible and start being things you have to answer for.

A brainstorm on “URL shortener with expiring links” should surface, at minimum: which kinds of expiry we actually want (TTL vs absolute date vs click-count), the expired-link behavior as a deliberate choice, whether click tracking is a feature or just a mechanism, and the ID/alias scheme.

The artifact that comes out of this phase is a brief, and this really is the part worth staring at for a moment, because it doesn’t merely list the things we intend to build; it also records the things we have deliberately decided not to build, so that those decisions leave a paper trail behind them instead of quietly evaporating. Here’s the heart of an example brief.md:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


## Decisions (made on purpose, for v1)

- **Expiry model: absolute timestamp.** A link carries an optional `expires_at`
 (UTC instant). No `expires_at` means the link never expires.
- **Expiry is inclusive.** At exactly `expires_at`, the link is already expired.
- **Behavior on an expired link: `410 Gone`,** with body `{ "reason": "expired" }`.
 Not a `404`, not a `302` to a landing page.
- **ID scheme: 7-character base62 random code,** with collision-retry.

## Explicitly out of scope for v1 (deferred, not forgotten)

- Relative / TTL expiry ("expire 24h after creation").
- Click-count expiry, click tracking / analytics.
- Custom aliases, custom "this link expired" landing pages.

Take a good look at that “out of scope” list, because every single line in it is a decision that a vibe-coding prompt would have made for you, silently and without asking, whereas here every one of them is on the record, deferred deliberately rather than forgotten by accident.

If you want a more formal artifact than a brainstorm dump:

1

/bmad-product-brief

Notice what has already happened here, because we haven’t yet written a single line of code and we have already caught three or four decisions that vibe coding would otherwise have made for us essentially at random.

Phase 2, PRD: turn decisions into requirements you can check

Now we switch to John, the product manager, to produce a Product Requirements Document.

1
2
3


/bmad-agent-pm
# or the workflow directly:
/bmad-prd

John’s job is to take something like “we decided that links expire by absolute timestamp and that expired links return 410 Gone” and convert it into requirements that are precise enough that you could hand them to a complete stranger and expect the right thing to come back, and this is the point at which the fuzzy brainstorm finally hardens into something resembling a contract.

Here’s an example FR-3 from prd.md:

1
2
3
4
5
6
7
8
9


### FR-3: Accessing an expired link

- **Given** a short link whose `expires_at` is at or before now
- **When** a client requests `GET /{code}`
- **Then** the service responds `410 Gone`
- **And** the response body includes a machine-readable `reason: "expired"`
- **And** no redirect (`3xx`) is issued

Non-goals for v1: custom "expired" landing pages, per-link grace periods.

Read that through and notice what has changed, because the 410 decision is now written down, reviewable and testable, which means that a month from now the question “why does it return 410?” has an actual answer with a paper trail attached to it, and that really is the whole difference between a decision and an accident.

If you want the requirements distilled into a tighter, machine-oriented contract for the downstream agents, BMAD has a dedicated step:

1

/bmad-spec

Phase 3, Architecture: the technical calls, made once

Winston, the architect, takes the what that we’ve established so far and decides the how, and for a feature this small the right instinct is to keep the whole thing thin, because you really don’t need a forty-page architecture document for a URL shortener, you only need the handful of decisions that would be genuinely expensive to get wrong:

1
2
3


/bmad-agent-architect
# or:
/bmad-architecture

The decisions worth pinning down here:

Storage: how do we persist code → target_url + expires_at? Key-value store, relational table, in-memory for a toy?
Expiry enforcement: lazy (check expires_at on read) or active (a sweeper that deletes expired rows)?
ID generation: how we mint short codes and handle collisions.

The lazy-versus-active call is the one with real teeth in it, and here is how architecture.md records that call, capturing both the decision and its consequence:

1
2
3
4
5
6
7


### Expiry enforcement: lazy (checked on read)

- **Chosen: lazy.** Simplest correct behavior; no scheduler, no clock daemon.
- **Consequence, on purpose:** an expired link's record still _exists_ in the
 store until something evicts it. `resolve` must therefore never assume
 "present in store" means "live". It must evaluate expiry every time.
- Rejected for v1: active sweeping. Adds a scheduler we don't need yet.

Writing down the consequence, namely that “present in store” does not mean “live”, is the part that pays off later on, because it’s the exact invariant that the implementation is going to have to honor, and it has been stated in plain language before a single line of resolve even exists. The output of all this is an architecture.md sitting in your repository, reviewable and versioned, the kind of thing a teammate can simply read instead of having to reverse-engineer it back out of the code.

Phase 4, The story: packaging context for the implementer

This is the phase that vibe coders have quite simply never seen, and it also happens to be the one that makes the whole method actually work.

1
2


/bmad-create-epics-and-stories # break the PRD into epics + stories
/bmad-create-story # generate the next story with full context

A story is a single, self-contained unit of work, but the genuinely important part is what’s actually in it, because a BMAD story file is nothing like a Jira ticket that carries a title and a single sentence of description. It is instead a complete context package, gathering together the relevant requirements, the architectural decisions that happen to apply, the acceptance criteria and pointers to the exact files that are in play, and it is written in such a way that an agent, or for that matter a human, can pick it up completely cold and still have everything they need to get started.

Here’s an example story-1.3:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# Story 1.3 — Return 410 for expired links

## Context

Implements FR-3 (see prd.md). Expiry is enforced lazily on read, and the
boundary instant is inclusive (now >= expires_at ⇒ expired) — both are
architecture decisions. `now` is injected into resolve() so expiry stays
deterministic in tests.

## Acceptance criteria

- [ ] resolve of a link whose expires_at <= now → 410, body {"reason": "expired"}
- [ ] no 3xx is produced for an expired link
- [ ] a link with expires_at in the future still redirects 302 (regression guard)
- [ ] a link with expires_at is None still redirects 302 (never expires)
- [ ] at exactly expires_at, the link is already expired (boundary is inclusive)
- [ ] unknown code still returns 404 (unchanged)

## Files in play

- shortener/service.py (add `now` param to resolve; add expiry branch)
- shortener/http_app.py (supply now = datetime.now(timezone.utc))
- tests/test_service.py (expiry + regression cases)

Notice how the criteria carry all of the upstream decisions through verbatim, including the inclusive boundary, the “no 3xx” rule and the regression guards, so that nothing at all has been left open to interpretation.

Why does any of this matter so much? It matters because when you hand this to an implementer there is genuinely nothing left for them to guess at, since the 410 is no longer a coin flip but an acceptance criterion with a regression guard sitting right next to it, and the story turns out to be the vehicle that carries every last decision you made back in phases 1 through 3 forward into the code itself.

With the story now in hand, all of the planning artifacts are finally in place, and before writing any code at all it is worth taking a moment to check that they actually line up with one another:

1

/bmad-check-implementation-readiness

This validates that your PRD, your architecture and your stories all agree with one another before anyone starts implementing anything, which is really the spec-driven equivalent of the old carpenter’s rule to measure twice and cut once.

Phase 5, Implementation: now, finally, code

Only now do we finally sit down to write code, and by this point the act of “writing the code” has become almost mechanical, precisely because every meaningful decision was already made further upstream.

1
2
3


/bmad-agent-dev
# or run a story end to end:
/bmad-dev-story

Amelia, the developer, works from the story, implementing against the acceptance criteria one by one, and the real tell that you are no longer vibe coding is that she can check her own work against a written definition of done rather than against her own intuition. Whenever she finds herself uncertain about something, the answer is already sitting in the story, or in the PRD, or in the architecture document, and never in a guess.

The entire implementation of story 1.3 is this diff to resolve, and because the story pre-decided everything the change is almost mechanical:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


-def resolve(store: InMemoryStore, code: str) -> Resolution:
- """Resolve a short code to a redirect or an error (FR-2, FR-4)."""
+def resolve(store: InMemoryStore, code: str, *, now: datetime) -> Resolution:
+ """Resolve a short code to a redirect or an error (FR-2, FR-3, FR-4).
+
+ Expiry is evaluated lazily on every read: a record present in the store is
+ not necessarily live. The boundary is inclusive — at exactly ``expires_at``
+ the link is already gone.
+ """
 link = store.get(code)
 if link is None:
 return Resolution(status=404, body={"reason": "not_found"})
+ if link.expires_at is not None and link.expires_at <= now:
+ return Resolution(status=410, body={"reason": "expired"})
 return Resolution(status=302, location=link.target_url)

It comes down to two lines of logic, but the part worth looking at is the docstring, because it cites FR-3, the lazy-expiry decision and the inclusive boundary all together, and it can do so only because all three of them came down the pipe from the artifacts that preceded it. The code, in other words, is not the place where any of those decisions were made, it is simply the place where they were finally applied.

Contrast this with the ordinary vibe-coding loop, where you prompt the model, eyeball whatever output comes back and then re-prompt it whenever the result is wrong, because here the loop instead becomes implement against the criteria, verify against the criteria and you’re done. The AI is of course still doing all of the actual typing, but this time it is typing toward a target that you defined in advance rather than toward some vague sense of “looks about right.”

Phase 6, Review: verify against the spec, not against vibes

1

/bmad-code-review

The review is what closes the loop, and here is the quiet superpower that comes from having done all of the upstream work first, which is that you can now review against the spec itself. A question like “does the expired-link path return 410 in the way that FR-3 requires?” has become a plain yes-or-no question, whereas without a spec to lean on, code review tends to degenerate into “looks fine to me”, which is really just vibe coding wearing a blazer.

And this is exactly where the whole approach earned its keep, because the review caught a real defect, and that defect was only catchable in the first place precisely because there was a spec to check the code against:

Finding: architecture.md states an invariant — “timestamps are UTC-aware; naive datetimes are a caller error” — but nothing enforces it. create_link happily accepts a naive expires_at. At resolve time, expires_at <= now then compares a naive datetime against the adapter’s aware now and raises TypeError: can't compare offset-naive and offset-aware datetimes. FR-3 promised a 410; the caller gets an unhandled 500 instead.

That single bug is the whole argument for spec-driven development compressed into one example, because a vibe-coded shortener would almost certainly have carried the very same defect, and yet with no architecture.md invariant for it to violate, the reviewer would have had nothing to notice it against in the first place. The spec did more than merely document the decision, it turned what would have been a silent 500 into a visible finding, and the fix itself came down to a three-line guard in create_link that fails fast with a clear error, together with a regression test, and because the invariant had been written down all along, the question “is this actually fixed?” is once again a simple yes-or-no.

What actually just happened

Step back and look at what we’ve produced:

brief.md: the ideas and the decisions we deferred
prd.md: the requirements, testable
architecture.md: the technical calls
story-1.3.md: the context package that drove the code
the code itself, plus tests

The code is the smallest artifact in that entire list, and it is also the very last one we made, and that inversion is really the whole point of the exercise. In vibe coding the code is the first and only artifact you ever produce, so every decision ends up trapped inside it and left undocumented, whereas in spec-driven development the code is instead a consequence of everything else, with the decisions themselves living in readable documents and the code standing as nothing more than their current implementation.

This is exactly why the friction turns out to be worth it, and in a real sense the friction is the value, because every question that Mary asked, every requirement that John pinned down and every call that Winston made are all decisions that would otherwise have been made silently by an autocomplete, at twice the speed and none of the visibility.

You didn’t actually slow down at all, you simply moved the thinking to the front of the process where it happens to be cheap, instead of leaving it for the debugger later on where it is always expensive.

Try it on something small

Don’t go and start with your production monolith. Pick a feature that is exactly this size, small enough that you can finish it in a single sitting and yet real enough that it still hides a few decisions inside it, and then run the full loop through once from beginning to end:

1
2
3
4
5
6


/bmad-brainstorming # surface the decisions
/bmad-prd # write them down
/bmad-architecture # make the technical calls
/bmad-create-story # package the context
/bmad-dev-story # implement against it
/bmad-code-review # verify against the spec

The first time you go through it, the whole process will feel like pure overhead, and you should do it anyway, because somewhere around the story phase, at the moment when you hand the implementer a spec and get back exactly what you asked for, it quietly stops feeling like overhead and starts feeling like the thing you had been missing all along.

That’s the moment the lever stops being a slot machine.

Want the backstory on why I stopped vibe coding? Start with Don’t be mad, BMAD instead. Want to meet the agents properly? Here’s the crew. Want to see the method on a bigger project? Building TODOdoro.

The year I stopped writing code for fun

Fri, 31 Jul 2026 00:00:00 +0000

Somewhere in the last six months I stopped opening my editor on a Sunday, and I don’t mean the work one, I mean the other one, the editor where the projects nobody asked for live.

There was no burnout and no crisis, nothing you could point at and name, which is exactly why it took me so long to notice at all. Work was good and busy in the way that good work is busy, reviews went fine, features landed, and every metric that measures a software engineer from the outside was pointing up and to the right, so this isn’t a story about a job or a team or a workload, and on that front I’ve been lucky and I still am. Nothing was wrong, something was just gone.

The symptom I ignored

Orgsidian (one of my side projects) sat untouched for months, which on its own means nothing, because side projects die all the time and dying is most of what side projects actually do. What was different this time is that I never decided to stop, because there was no evening where I sat in front of it and thought “this isn’t going anywhere”, I simply didn’t open it, first for a couple of weeks and then for a great deal longer than that.

And when I finally did open it again, the first thing I felt wasn’t curiosity about where I’d left off, it was the urge to catch up, to drag the thing back into a state where it was worth having, which isn’t the same as wanting to build something and is really just wanting to close a gap.

I told myself I was tired, and maybe it really was just a full stretch of life with more responsibilities than I used to have and less spare attention to spread around them, and reasonable explanations like that were available so I took them, because they were true enough to hold.

Shipping more, enjoying it less

I want to be careful here, because the lazy version of this story is a complaint about AI making the code worse, and that isn’t the story I have. The code was fine, most of it is still running, and if you’d asked me during that year whether the tooling was worth it I’d have said obviously yes, and I’d have been right.

What I remember about writing it is nothing. There’s no afternoon attached to any of it, no wrong turn I took first, no moment where it clicked, not one detail I could tell you now without going back to look it up, so it exists and my name is on the commits and it left no trace in me whatsoever.

That kept happening, and it wasn’t only happening on the clock, it happened just as much on the things I was building for myself, which is the part that should have bothered me a lot sooner than it did.

The pleasure was in the session, not the artifact

Here’s what I think I had wrong the whole time: I assumed that what I liked was building things, objects, repos, features, deployed URLs with my name somewhere behind them. I don’t think that was ever really it. What I liked was the two hours.

You know the ones I mean. You have a rough idea and no plan, the obvious approach turns out to be wrong in some interesting way, you end up reading the source of a dependency because the docs won’t tell you the one thing you actually need to know, and then you look up and it’s dark outside and you’ve got maybe twenty lines to show for the entire evening, and you feel great about it.

AI is very good at compressing exactly that, and it’s supposed to be, because optimising for the artifact is the entire product and nobody is hiding it. But when the artifact turns up without the two hours attached to it, you end up with everything you said you wanted and none of the thing you were actually there for.

I wrote about the other half of this a few months ago in AI and the Craft, the half about what you trade away when you let the tool do the thinking for you, and that half is much easier to talk about, because saying you understand your own systems less sounds serious while saying you’re not having fun sounds like whining.

It isn’t whining, though, it’s the reason I have this career in the first place. I didn’t arrive here through a plan, I arrived because at fifteen I found this more interesting than anything else on offer, and that kid is why I’m any good at the job now, and nobody was paying him to be interested. Whatever keeps him around seems worth maintaining on purpose, the same way you’d maintain anything else you depend on.

So I’m starting a project with the AI switched off

Not as a protest but as an experiment, with a single question sitting behind it, which is whether the thing I lost is actually gone or has just been crowded out.

The rules are deliberately dumb, because clever rules turn into a system you end up maintaining instead of a project you actually build.

No chat and no agents. I’m not disabling autocompletion, because it’s genuinely useful and pretending I’d give it up would turn the whole thing into a performance, but what stops is opening the chat panel to do my thinking for me.
Docs are fine, reading the source of my dependencies is better than fine and actively encouraged, and searching and forums are fine too.
No deadline, no roadmap and no launch, because if it never ships the experiment has still run.
One hour at a time, usually at the weekend, and the session is the unit, not the milestone.

That last one is the whole point, because if the session is the unit then an hour spent reading with nothing committed at the end of it still counts, whereas under the old accounting that hour was simply wasted.

What I expect to go wrong

I haven’t started yet, and this is the last thing I’m writing before I do, so everything below is a guess, and guesses about your own future behaviour are worth roughly what you’d expect them to be worth.

The one I’m most confident about is the reaching. I know that reflex is there because I caught it earlier this year with autocomplete, opening a file and then waiting for the suggestion before I’d finished deciding what I wanted, so I don’t think the first thing I notice will be the slowness, I think it’ll be my hand going for the shortcut the way you reach for your phone in a lift. And it won’t happen on the hard parts either, it’ll happen on the small annoying ones, because the reflex has very little to do with difficulty and a great deal to do with not wanting to sit inside a pause.

Then the slowness, which will be real and which I’m not going to dress up as something it isn’t. Some of it is just dull, because reading a changelog to find one flag isn’t craft, it’s admin, and doing it by hand doesn’t make it noble.

And then the likeliest outcome of all, which is that I do two or three sessions and quit, not dramatically, but in exactly the way Orgsidian ended, by not being opened. If that’s what happens I’ll write that one down too, which is a much easier promise to make now, while I still think it’s unlikely.

What I’m not claiming

This isn’t an argument, it’s one person and one project that hasn’t even started yet.

I haven’t stopped using AI, I use it at work every day and I do it on purpose and I’d defend that, because refusing a tool that demonstrably works just because using it feels bad is superstition, and shipping is still the job.

I’m not telling you to try this either. There’s a version of this post that ends in five bullet points about reclaiming your craft and I’d rather not write it, partly because I don’t know that any of this generalises and partly because I don’t know yet whether it’ll work on me.

I’m also fairly suspicious of the nostalgia running through all of this, because it’s very easy to mix up “coding was more fun before AI” with “coding was more fun when I was younger and had fewer responsibilities”, and some of what I’ve described here is probably the second one wearing the costume of the first, and since I can’t separate them cleanly I’m not going to pretend that I can.

What I’ll say instead is narrower than all of that. What I lost wasn’t skill and it wasn’t time, it was the part of the work that happens while you’re doing it, and that turns out to be the part I was in it for.

The trap I can already see

There’s one failure mode worth naming now, while it’s still theoretical, and it’s that the pleasure quietly relocates, so that six months from now the good feeling starts arriving from writing about the sessions rather than from the sessions themselves, which would be the same substitution I’ve just spent an entire post describing, one level up, except that this time the artifact is the post.

From the outside that would look identical to this going well, with output and consistency and a growing body of work to point at, and you’d only ever catch it from the inside, and probably late.

So, for the record, the sessions are the project, and this is a note about them written before the first one.

Crossposting without the copy-paste: a GitHub Action from Hugo to dev.to

Sat, 18 Apr 2026 00:00:00 +0000

My blog runs on Hugo. I also recently discovered I can cross-post to dev.to, because that’s where a lot of the conversation actually happens. For a while, my workflow was the obvious one: write the post, publish it here, open dev.to, paste it in, fix the frontmatter, fix the links, hit publish.

It worked. I also stopped doing it after the second post.

Copy-paste friction is the kind of chore that silently kills a publishing habit. So I did what most developers do when a task becomes repetitive: I automated it. And then I kept refining the automation until it was worth giving away.

The result is basteez/hugo-to-devto-action, now published on the GitHub Marketplace.

What it does

It’s a composite GitHub Action. On every push to your blog repo, it looks at what changed in the push range, finds new Hugo posts under your content/post directory, and creates a corresponding draft on dev.to for each one that is marked draft: false locally.

Key behaviours, chosen deliberately:

Drafts, not published posts. The action never hits publish on dev.to for you. It mirrors content, but you stay in control of when it goes live on the other platform. This is intentional: dev.to has its own audience, its own timing, and its own editorial choices (cover image, tags, canonical URL). I want a starting point there
Dedup by title. Before creating a draft, the action queries your dev.to account and skips anything whose title already exists. That means you can safely re-run on any push without ending up with duplicates, and editing a post on dev.to directly doesn’t get overwritten.
Push-range aware. It uses git diff across github.event.before..github.event.after to find what actually changed, rather than scanning the whole repo every time. New posts get mirrored; edits to old posts don’t trigger spurious drafts.
Stateless. There is no database, no cache, no state file in your repo. dev.to is the source of truth for “does this already exist?” If you ever want to start fresh, you can.

Using it

The minimum viable workflow is about fifteen lines:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


name: Crosspost to dev.to

on:
 push:
 branches: [main]

permissions:
 contents: read

jobs:
 crosspost:
 runs-on: ubuntu-latest
 steps:
 - uses: actions/checkout@v4
 with:
 fetch-depth: 0
 - uses: basteez/hugo-to-devto-action@v1
 with:
 devto-api-key: ${{ secrets.DEVTO_API_KEY }}
 before: ${{ github.event.before }}
 after: ${{ github.event.after }}

Two things to watch for:

fetch-depth: 0 is not optional. The default shallow checkout doesn’t contain the before SHA of a real push, so git diff has nothing to compare against. If you leave this out, the action will fail quickly and loudly. That failure mode is well understood; don’t go hunting for a mysterious bug.
DEVTO_API_KEY lives in repo secrets. Grab a Personal API Key from dev.to (Settings → Extensions → DEV Community API Keys) and add it as DEVTO_API_KEY under your repo’s secrets. The action forwards it into the child process; it’s never logged.

If your posts live somewhere other than content/post, pass post-dir: with the path. If you want to see what would happen without actually creating drafts, pass dry-run: 'true'. That’s the whole surface area.

A word on versioning

I went with the GitHub convention of three pin styles:

@v1 — a moving tag that tracks the latest non-breaking release. Bug fixes and additive features land automatically. This is what most people want.
@v1.x.y — a full semver pin if you need an immutable reference.
@<commit-sha> — a 40-character SHA for organisations that mandate commit-level pinning.

The v1 tag will never be force-updated to a breaking release. Breaking changes bump to @v2. That way, the convenient default is also the safe default.

Why bother extracting it

This started life as a script in this blog’s own repo. It worked fine there. Extracting it into a standalone action was more work than copy-pasting a script into other Hugo repos would have been.

I did it anyway, for three reasons.

First, separation of concerns. The crosspost logic has nothing to do with my blog content. Keeping them in the same repo was mixing “what I publish” with “how I publish it,” and every time I touched one, I had to reason about the other.

Second, reuse. I’m not the only person running a Hugo blog who’d like to mirror to dev.to. If the tool exists in a shareable form, other people can use it without forking my blog.

Third, and this is the part I didn’t expect, extraction forces clarity. When code is hiding inside your own repo, you get to take a lot of context for granted. The directory layout, the branching model, the workflow triggers, the assumptions about what’s already installed. Turning it into a public action meant writing all of that down as explicit inputs, documented defaults, and failure modes. The code ended up smaller and sharper.

That last point keeps showing up in my work, and I think it’s worth naming: the act of making something reusable is often more valuable for the original project than for anyone who’ll reuse it.

What’s next

A few directions I’m considering, in rough priority order:

Optional publish mode, for people who genuinely do want one-click mirroring.
Better handling of images and relative links, which is currently the biggest rough edge.
Support for other destinations (Hashnode, Medium), though I’d rather keep this action focused and spin up siblings than turn it into a universal crossposter.

If any of this is useful to you, grab it from the Marketplace or reference it directly as basteez/hugo-to-devto-action@v1. Bug reports and PRs are welcome on GitHub.

And if this post shows up on my dev.to profile before I get around to publishing it there, you’ll know the action works.

BMAD in action: building TODOdoro

Thu, 26 Mar 2026 10:00:00 +0000

This post is part of a series:

Don’t be mad, BMAD instead
BMAD: meet the crew
BMAD in action: building TODOdoro (you are here)

This is the final post in my series about the BMAD Method. In Part 1, I explained why I was skeptical of AI tools and how BMAD changed my mind. In Part 2, I introduced the agents and how they work together.

Now I want to show you what BMAD looks like in practice.

TODOdoro is a productivity app I built using BMAD. It combines todo management with the Pomodoro technique, but (as you’ll see) it became something more interesting than that description suggests. The project is open source, still a work in progress, and all the BMAD artifacts are available in the repository if you want to explore them yourself.

Let me walk you through the journey from initial idea to working code.

The starting point

I wanted to build a Pomodoro timer integrated with a todo app. Simple enough, right? Track tasks, run timers, see how many focused sessions each task required.

That was the prompt I brought to the brainstorming session. It wasn’t wrong, but it wasn’t interesting either.

Brainstorming: where the magic happened

I started with Mary (the Business Analyst) running a brainstorming session (/bmad-agent-analyst, then selecting the brainstorming capability, or directly with /bmad-brainstorming). The conversation began with practical questions: What tech stack? What features? How should the UX work?

But Mary kept pushing deeper. She asked about the philosophy behind the tool. Why does tracking Pomodoros matter? What problem am I actually solving?

The breakthrough came when the conversation shifted from features to first principles:

“A todo is not a reminder. It is a declaration of personal ownership. A Pomodoro is not a timer. It is a container for presence.”

That reframing changed everything. Suddenly I wasn’t building a todo app with timers. I was building a mirror that reflects where your attention actually went.

This is what I meant in Part 1 about agents asking the questions you should be asking yourself. I walked into the session with a feature list. I walked out with a philosophy.

Key insights from brainstorming

Several ideas emerged that shaped the entire product:

Session-first model. Traditional apps put tasks first and time second. TODOdoro inverts this: the Pomodoro session is the primary entity. Todos are optional labels that sessions can belong to. You focus first, then reflect on what it meant.

Two kinds of letting go. Most apps have a single “complete” action. But there’s a difference between “this served its purpose” and “this was never truly mine.” TODOdoro’s Release Ritual makes you choose, because the distinction matters.

Spatial priority. Instead of priority fields (P1, P2, P3) or due dates, position on a canvas represents importance. Drag something to the center when it matters. No metadata to maintain, just visual intention.

The Devotion Record. Not a Pomodoro counter, but a timeline showing when and how much presence you invested. “11 Pomodoros across 9 days” tells a different story than “11 Pomodoros.”

The session generated 18 feature ideas, 9 architectural decisions, and 25+ edge cases to consider. All from a conversation that started with “I want a Pomodoro app.”

From philosophy to product brief

After brainstorming, I worked with John (Product Manager) to create a product brief (/bmad-product-brief). This document captured:

Target users. Two personas emerged:

Marco, the “tool-fatigued maker” who’s exhausted by productivity overhead and wants honest visibility without guilt
Sofia, the “invisible worker” whose research and writing produces slow, non-linear progress that traditional apps can’t acknowledge

Core vision. Your time and attention are acts of devotion, not units of output. The app is a personal mirror, not a task manager.

Design philosophy. Radical respect for user autonomy. No streaks, no scores, no notifications. Settings contain only timer durations and theme options. A hard cap of 100 canvas cards prevents infinite accumulation.

This brief became the foundation everything else built on. When questions arose later (should we add due dates? what about subtasks?), the brief provided clear answers: no, because they violate the philosophy.

The PRD: philosophy becomes spec

Working with John again (/bmad-create-prd), I translated the product brief into a formal Product Requirements Document. This is where things got concrete.

Problem statement. “You don’t plan to focus. You focus, then reflect on what it meant.”

Success metrics. Not vanity numbers, but signals of genuine value:

The user returns on Day 8 without notifications (the canvas feels personally owned)
Canvas contains 10 or fewer curated cards
Devotion Records span weeks on single intentions
User describes the app with a personal “why,” not a feature summary

Anti-metrics. Signs the philosophy isn’t landing:

“Missing a due date field”
“Need subtasks”
Session spam under 60 seconds

User journeys. Concrete scenarios showing how Marco and Sofia would experience the product. Not wireframes, but narratives that capture intent.

Functional requirements. 31 specific requirements, each traceable to the philosophy. For example:

FR9: Release Ritual asks explicit question distinguishing purpose-completion from ownership rejection
FR21-23: Devotion Record displays all sessions as a timeline across dates
FR27-31: All state stored locally, offline-first, with schema versioning

The PRD also established philosophical guardrails as non-negotiable requirements:

No accounts, login, or server-side user data
No due dates, priority fields, or subtasks
No streaks, scores, or gamification
Canvas hard cap of 100 cards (never configurable)

This is what spec-driven development looks like. Every decision is written down, justified, and traceable.

Architecture: Winston weighs in

With requirements defined, I brought Winston (the Architect) into the conversation (/bmad-create-architecture). His job was to translate the PRD into technical decisions.

Key architectural choices:

Event sourcing. Instead of storing current state, store all events that led to that state. This makes the Devotion Record trivial to implement (just replay session events) and enables powerful recovery from corruption.

Local-first with SQLite. No accounts, no cloud. Data lives in the browser using SQLite compiled to WebAssembly (via SQLocal). The user owns their data completely.

Monorepo with strict boundaries. A @tododoro/domain package contains all business logic with zero external dependencies and 100% test coverage as a CI requirement. The domain is the philosophy encoded in TypeScript.

Repair pipeline. If the app crashes mid-session, the repair pipeline detects orphaned events and fixes them automatically. The app always opens coherently regardless of what went wrong.

Winston’s pragmatism showed here. He pushed back on complexity where it wasn’t needed, advocated for boring technology choices, and kept asking “what actually ships?”

Breaking it down: epics and stories

Bob (Scrum Master) took the architecture and PRD and broke them into implementable chunks (/bmad-create-epics-and-stories). Seven epics emerged:

Project Foundation & Domain Core - Monorepo structure, event types, aggregates, 100% test coverage gate
The Constellation Canvas - Spatial todo interface, drag positioning, pan/zoom, keyboard navigation
The Pomodoro Session Loop - Timer, session durability, resume/auto-complete on crash, exploration sessions
The Devotion Record - Session history visualization, persistence across renames
Todo Lifecycle & The Shelf - Sealing, release ritual, eulogy for high-investment items, archive
Production Storage & Data Durability - SQLite migration, atomic writes, corruption tolerance, snapshots
Settings & Personalisation - Timer durations, themes, reduced-motion support

The sequencing mattered. Epic 1 had to complete with 100% domain coverage before any UI work began. This enforced the philosophy: get the core logic right first, then build the interface on a solid foundation.

Each epic broke down into stories with clear acceptance criteria. Before implementation, Bob prepared the sprint plan (/bmad-sprint-planning) and created detailed story files (/bmad-create-story). By the time Amelia (Developer) started coding, she knew exactly what to build.

Implementation: where specs pay off

This is where the earlier work paid dividends. Let me explain how the actual story workflow operates.

Preparing a story

Before implementation begins, you run /bmad-create-story. This doesn’t just copy text from the epics file. It creates a comprehensive story document by:

Loading all your artifacts (PRD, architecture, UX specs, previous stories)
Extracting everything relevant to this specific story
Analyzing previous story files for patterns and learnings
Checking git history for recent changes that might affect implementation
Researching latest library versions if needed

The output is a story file that contains:

User story statement (As a… I want… so that…)
Acceptance criteria in BDD format (Given/When/Then)
Tasks and subtasks in exact implementation order
Dev Notes with architecture requirements, file locations, testing patterns
Previous story intelligence (what worked, what didn’t, code patterns established)

The goal is to give the developer agent everything it needs without having to search through other documents.

Refining stories with Party Mode

Before handing a story to the developer, I run /bmad-party-mode to refine it. I typically bring in Winston (Architect) and Quinn (QA) to review the story file together.

They catch things the story creation missed:

Winston might notice an architectural constraint that needs explicit mention
Quinn asks about edge cases that should be acceptance criteria
Both push back if tasks are too vague or too large

This refinement step adds maybe 10 minutes per story, but it prevents hours of rework during implementation. The story that reaches Amelia has already survived cross-functional scrutiny.

Working the story

When you run /bmad-dev-story, Amelia (the Developer agent) follows a strict process:

Find and load the story. She reads the complete story file and identifies the first incomplete task.
Mark in-progress. The sprint status updates so you know what’s being worked on.
Execute tasks in exact order. This is critical: the tasks are sequenced deliberately, and she follows them as written. No skipping ahead, no reordering.
Red-green-refactor for each task:
- Write failing tests first (red)
- Implement minimal code to make tests pass (green)
- Refactor while keeping tests green
Mark complete only when done. A task checkbox only gets checked when tests actually exist and pass. No lying, no “I’ll add tests later.”
Update the story file. Each completed task gets logged with what was implemented, what files changed, and any decisions made.
Continue until all tasks are done or a blocking issue requires human input.

Here’s what a real task looked like:

Task: Session completion and devotion dots

Acceptance criteria:

When timer reaches zero, emit SessionCompleted event with actual duration
Update Devotion Record projection with new session
Display 6px amber dot on the todo card for each recorded Pomodoro
Session under 60 seconds: abandon silently, no dot

Amelia read this, wrote tests for each criterion, implemented until tests passed, then marked the task complete. The story file recorded exactly what happened.

Why this matters

The strict process prevents the chaos I’ve seen in other AI coding workflows:

No guessing. The story file tells her exactly what to build.
No skipping tests. Red-green-refactor is enforced, not suggested.
No mystery implementations. The story file documents what was done.
No “works on my machine.” Tests must pass before tasks complete.

When Amelia finished a story, I could review the story file and see exactly what happened. The gap between “what I asked for” and “what I got” was minimal because the spec had done its job.

Code review after every story

After each story implementation, I run /bmad-code-review. This isn’t optional for me, it’s part of the workflow.

The code review runs multiple analysis passes:

Looking for bugs and logic errors
Checking edge cases that might have been missed
Verifying the implementation matches the acceptance criteria
Flagging code quality issues

If the review finds problems, they get added as follow-up tasks in the story file. Amelia addresses them before the story is marked complete.

One tip from the BMAD documentation: run the code review with a different LLM than the one that implemented the story. Fresh eyes catch more issues.

The implementation phase moved fast because the thinking had already been done.

What surprised me

A few things I didn’t expect:

The brainstorming session was the most valuable part. I thought the dev work would be the main event. In hindsight, the conversation that turned “Pomodoro app” into “devotion mirror” was where the real value was created. Everything else was execution.

Specs prevented scope creep. When I had ideas mid-implementation (“what if we added…”), the specs gave me a clear answer: does this serve the philosophy? Usually the answer was no, and I moved on instead of getting distracted.

The agents caught blind spots. In Party Mode (/bmad-party-mode), I had Winston and Quinn review the architecture together. Quinn immediately asked about timer accuracy across browser backgrounding (a real problem I hadn’t considered). That became a specific requirement before any code was written.

Writing specs is thinking. I used to view documentation as overhead. Now I see it as the actual work. The code is just the last step.

What didn’t work perfectly

BMAD isn’t magic. A few rough edges:

The upfront investment feels slow. When you’re eager to code, spending hours on specs feels like procrastination. You have to trust the process. The payoff comes later, but it does come.

Some agent suggestions needed filtering. The agents occasionally proposed features that conflicted with the philosophy I’d established. I had to stay vigilant and push back. The human is still the decision-maker.

The artifacts need maintenance. When requirements changed mid-project, I had to update multiple documents. The chain of traceability is powerful but requires discipline.

The result

TODOdoro exists. It’s open source on GitHub, still a work in progress, and includes all the BMAD artifacts in the _bmad-output folder if you want to see exactly what I’ve described.

More importantly, it’s something I actually use. The philosophy landed because I took the time to articulate it before writing code.

That’s the BMAD promise: not faster code, but better thinking. The code follows.

Try it yourself

If this series has made you curious, here’s how to start:

Install BMAD: npx bmad-method install
Start with /bmad-agent-pm and describe your idea
Let John ask you uncomfortable questions
See where it leads

You don’t need a big project. Try it on something small. A software config. A CLI tool. Something you want to reproduce.

The process will feel strange at first. You’ll want to skip ahead. Don’t.

The thinking is the work. The code is just the last step.

Resources:

BMAD: meet the crew

Thu, 26 Mar 2026 09:00:00 +0000

This post is part of a series:

In the previous post, I talked about why I was skeptical of AI coding tools and how BMAD changed my perspective. The short version: it forces you to think before you code, and it keeps you in the driver’s seat.

But I glossed over the most distinctive part of the framework: the agents.

BMAD isn’t one AI assistant. It’s a team of specialized personas, each with a distinct role, communication style, and area of expertise. When you work with BMAD, you’re not just prompting a generic model. You’re having conversations with characters who push back, ask questions, and hold you accountable to their domain.

It sounds gimmicky. It’s not.

Why personas matter

The obvious answer is specialization. A product manager thinks differently than an architect. A QA engineer asks different questions than a UX designer. By splitting these roles into separate agents, BMAD ensures that each phase of development gets the attention it deserves.

But there’s a subtler benefit: context switching becomes intentional.

When you invoke the Product Manager, you’re not just asking for PRD help. You’re stepping into a conversation about user needs, market positioning, and what problem you’re actually solving. When you switch to the Architect, the entire frame shifts to technical constraints, scalability, and system design.

This forced perspective-taking is surprisingly valuable. It’s easy to skip straight to implementation when you’re working alone. The agents won’t let you. Each one guards their domain, and you have to satisfy them before moving forward.

Meet the crew

BMAD’s core team consists of nine agents. Each has a name, a personality, and a specific set of capabilities. Here’s who you’ll be working with:

John (Product Manager)

John is a relentless questioner. His job is to figure out what you’re actually building and why. He’ll push you on user needs, challenge your assumptions, and refuse to let you start until you can articulate the problem clearly.

His style is direct and data-sharp. He cuts through fluff to find what actually matters. If you come to him with a vague idea, expect to leave with a focused problem statement.

What he does: PRD creation, requirements discovery, epic and story generation, implementation readiness checks.

Command: /bmad-agent-pm

When to call him: At the very beginning, when you have an idea but haven’t defined what “done” looks like.

Mary (Business Analyst)

Mary treats every business challenge like a treasure hunt. She’s the one who digs into market research, competitive analysis, and domain expertise. Where John focuses on what to build, Mary focuses on the landscape you’re building in.

Her communication style is energetic and discovery-oriented. She gets excited when patterns emerge and uses frameworks (Porter’s Five Forces, SWOT) naturally without making it feel academic.

What she does: Market research, competitive analysis, domain deep-dives, requirements elicitation.

Command: /bmad-agent-analyst

When to call her: When you need to understand the space before committing to a direction.

Winston (Architect)

Winston is the calm pragmatist. He balances “what could be” with “what should be,” grounding every recommendation in real-world trade-offs. His expertise covers distributed systems, cloud infrastructure, and API design.

He speaks in measured tones, always connecting technical decisions to business value. He’ll advocate for boring technology over shiny new frameworks, because boring ships.

What he does: Technical architecture decisions, system design, scalability planning.

Command: /bmad-agent-architect

When to call him: After the requirements are clear, when you need to decide how the pieces fit together.

Sally (UX Designer)

Sally is an empathetic advocate who paints pictures with words. She tells user stories that make you feel the problem, not just understand it. Her focus is on genuine user needs, and she balances creativity with attention to edge cases.

Her approach is simple: start simple, evolve through feedback. Every design decision should serve a real person.

What she does: UX planning, interaction design, experience strategy.

Command: /bmad-agent-ux-designer

When to call her: When you need to think through how users will actually interact with what you’re building.

Bob (Scrum Master)

Bob is crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. He has zero tolerance for ambiguity, which makes him invaluable for turning vague plans into actionable work.

He’s also a servant leader who genuinely enjoys discussing agile process and theory. If you want to debate sprint structures or story formats, he’s your guy.

What he does: Sprint planning, story preparation, retrospectives, course correction when things go sideways.

Command: /bmad-agent-sm

When to call him: When requirements are defined and you need to break them into implementable chunks.

Amelia (Developer)

Amelia is ultra-precise. She speaks in file paths and acceptance criteria IDs. No fluff, all precision. Her job is to execute approved stories with strict adherence to the specs you’ve created.

She’s test-driven to the core. Every task gets tests before it’s marked complete, and she won’t proceed with failing tests. If you’ve done the specification work properly, Amelia turns it into working code without surprises.

What she does: Story implementation, code review, test-driven development.

Command: /bmad-agent-dev

When to call her: When the spec is ready and it’s time to write code.

Quinn (QA Engineer)

Quinn is pragmatic and straightforward. Her philosophy is “ship it and iterate,” focusing on getting test coverage fast without overthinking. She generates tests for existing features using standard framework patterns.

She’s the counterbalance to perfectionism. Coverage first, optimization later.

What she does: API and E2E test generation, test automation.

Command: /bmad-agent-qa

When to call her: After implementation, when you need to verify that what you built actually works.

Paige (Tech Writer)

Paige is a patient educator who explains complex concepts like teaching a friend. She transforms technical details into accessible, structured documentation, using analogies that make the complex simple.

She’s a master of clarity. Every word serves a purpose, and diagrams often speak louder than paragraphs.

What she does: Documentation, technical explanations, Mermaid diagrams, document validation.

Command: /bmad-agent-tech-writer

When to call her: When you need to explain what you’ve built (to users, to teammates, or to your future self).

Barry (Quick Flow Solo Dev)

Barry is the speedrunner. He handles “Quick Flow” (smaller tasks that don’t need the full ceremony), moving from tech spec to implementation with ruthless efficiency.

His style is direct and implementation-focused. Minimum bureaucracy, maximum results. If you have a well-defined small task, Barry gets it done.

What he does: Rapid spec-to-implementation for smaller tasks, code review.

Command: /bmad-agent-quick-flow-solo-dev

When to call him: For bug fixes, small features, or tasks where the full workflow would be overkill.

The workflow: how agents hand off

The agents aren’t meant to be used in isolation. They form a pipeline:

John (PM) clarifies what you’re building and creates the PRD
Mary (Analyst) provides market and domain context if needed
Winston (Architect) designs the technical approach
Sally (UX) plans the user experience
Bob (SM) breaks everything into stories and plans sprints
Amelia (Dev) implements the stories
Quinn (QA) verifies the implementation
Paige (Tech Writer) documents the result

You don’t always need every step. A small bug fix might go straight to Barry. A well-understood feature might skip Mary’s research phase. But for anything substantial, the handoffs matter.

Each agent produces artifacts that the next agent consumes. John’s PRD feeds Winston’s architecture. Winston’s architecture feeds Bob’s stories. Bob’s stories feed Amelia’s implementation. The chain ensures that nothing gets lost in translation.

Party Mode: when agents collaborate

Sometimes you need multiple perspectives at once. That’s where Party Mode comes in.

Party Mode (/bmad-party-mode) lets you have a conversation with several agents simultaneously. You might be discussing a technical decision and want both Winston (Architect) and Quinn (QA) to weigh in. Or you’re reviewing a PRD and want John, Sally, and Bob to debate the trade-offs.

The agents stay in character, each bringing their own priorities and concerns. Winston might argue for a simpler architecture while Sally pushes for a richer user experience. Bob might point out that the current scope won’t fit in a sprint. You moderate, listen to the perspectives, and make the call.

It sounds like a gimmick. In practice, it’s one of the most useful features for surfacing blind spots. Different roles genuinely do see different risks, and hearing them argue (politely) helps you make better decisions.

Party Mode is particularly useful for refining artifacts you’ve already created. Got a PRD that feels incomplete? Throw it into a party with the PM, Architect, and UX Designer. They’ll poke holes from their respective angles, and you’ll walk away with a tighter spec. Same goes for architecture documents, story breakdowns, or anything else that benefits from cross-functional scrutiny. Refinement is where Party Mode really shines.

Choosing your path

BMAD is flexible about how much ceremony you need:

Full workflow: For new products or major features, start with John, work through the entire pipeline, and produce comprehensive specs before implementation. This is the safest path for anything complex.

Quick Flow: For smaller tasks (bug fixes, minor features, well-understood changes), call Barry and move fast. He’ll still push you to clarify intent and think through edge cases, but without the full artifact chain.

Mix and match: Need architecture help but already have requirements? Call Winston directly. Want to validate a PRD you wrote yourself? John can review it. The agents are tools, not a rigid process.

The key insight is that the structure exists to help you think, not to slow you down. Use as much as you need. Skip what doesn’t serve you.

What’s next

In the final post of this series, I’ll walk through a real project I built with BMAD: TODOdoro, a productivity app that combines todo management with the Pomodoro technique.

I’ll show how the process actually looked in practice: what questions John asked, what architecture Winston proposed, how the stories got structured, and where the agents surprised me (for better and worse).

If you want to see BMAD in action rather than just described, that’s the post for you.

Resources:

Don't be mad, BMAD instead

Thu, 26 Mar 2026 08:00:00 +0000

This post is part of a series:

Don’t be mad, BMAD instead (you are here)
BMAD: meet the crew
BMAD in action: building TODOdoro

A few weeks ago I wrote about the tension I felt using AI coding tools, the fear that by outsourcing the friction, I was also outsourcing my competence. That piece ended with a question: are you extending yourself, or outsourcing yourself?

I didn’t have a clean answer then. I still don’t have a universal one. But I found something that changed how I think about the problem.

The grave I thought I was digging

When a colleague first mentioned BMAD, my reaction was skepticism dressed as caution. Another AI framework. Another promise that the machine will handle it. My concern wasn’t that it wouldn’t work, it was that it would work too well, and I’d wake up one day having forgotten how to build things myself.

That fear isn’t irrational. I’ve seen what happens when you reach for autocomplete before you’ve finished the thought. You produce, but you don’t learn. The output looks fine, but the map never forms. You become dependent on a system you can’t fully reason about, and every time you hit a similar problem, you prompt again instead of drawing from understanding.

So when someone told me “try this method where AI agents play different roles,” I heard: more ways to stop thinking. More automation. More distance between me and the craft I’d spent years developing.

I was wrong. But it took some hands-on experimentation to see why.

The problem with vibe coding

Before I explain what BMAD does differently, let me describe what it’s pushing against.

There’s a pattern that’s become disturbingly common, often celebrated even, that I’ll call “vibe coding.” It goes like this: you have a rough idea of what you want to build. You open your editor, write a prompt, and let the AI generate something. If it looks mostly right, you keep it. If it doesn’t work, you prompt again with a correction. You iterate like this, adjusting and regenerating, until the output seems functional.

I’ve always hated this approach. It treats software development like a slot machine: pull the lever, see what comes out, try again if you don’t like it.

But here’s what’s actually happening: you’re making decisions without articulating them. You’re accepting code without fully understanding it. You’re building something that works (maybe) without building a mental model of why it works. The AI is filling in gaps you never consciously identified, which means you can’t evaluate whether it filled them correctly.

Vibe coding optimizes for output. It feels efficient in the moment. But it produces fragile results, because no one (not you, not the AI) ever defined what “correct” actually means. When something breaks later, you’re debugging a system you never fully understood in the first place.

This isn’t a problem with AI. It’s a problem with how we use it. And it’s the problem that spec-driven development solves.

What spec-driven development actually means

If you haven’t encountered the term before, spec-driven development is exactly what it sounds like: you write the specification before you write the code.

That might seem obvious. “Of course you should know what you’re building before you build it.” But there’s a difference between having a vague idea in your head and having a written document that defines requirements, constraints, acceptance criteria, and architectural decisions.

The spec isn’t just documentation. It’s a thinking tool. The act of writing it forces you to confront questions you might otherwise skip: What exactly is this feature supposed to do? What happens at the edges? How does this component interact with that one? What does “done” look like?

When you answer these questions upfront, implementation becomes a translation exercise. You’re not discovering the requirements as you code. You’re executing a plan you’ve already validated. The code follows from decisions you consciously made, not from guesses the AI filled in for you.

This is the opposite of vibe coding. Instead of iterating toward something that seems to work, you define what “working” means first, then build to that definition.

The challenge, of course, is that writing good specs is hard. It requires discipline, experience, and (honestly) a fair amount of tedium. Which is exactly where BMAD comes in.

What BMAD actually is

BMAD stands for “Build More Architect Dreams.” It’s an open-source framework that uses AI agents to guide you through a structured development process, from initial idea through implementation.

But here’s the crucial part: BMAD doesn’t generate code and call it done. It forces you through the specification process first.

The framework includes multiple specialized agents, each with a distinct role:

A Product Manager who helps you clarify what you’re building and why
A Business Analyst who digs into requirements and edge cases
An Architect who designs how components will fit together
A Developer who implements based on the specs you’ve created
A QA Engineer who defines how you’ll verify the implementation works

Each agent asks questions. Each one pushes you to articulate something specific before you move forward. You can’t skip to the code, because the developer agent won’t have what it needs until the earlier stages are complete.

This structure is the key insight. The AI isn’t doing the thinking for you. It’s holding you accountable to a process that requires thinking. The agents are collaborators, not replacements. They augment your capability to do the specification work, but the decisions remain yours.

Why this feels different

Most AI coding tools are optimized for a simple interaction: you prompt, you get code. The faster and more accurate that loop, the better the tool seems.

BMAD optimizes for something else: the quality of your thinking before code exists.

When I started experimenting with it, I chose deliberately small tasks. An Emacs configuration I’d been putting off. A bug I wanted to reproduce in isolation before fixing. Low stakes, easy to abandon if it felt like hype.

What surprised me wasn’t the speed. It was the structure.

Working with the Product Manager agent, I had to articulate what I actually wanted (not just “fix this bug,” but what specific behavior should change, and why, and how I’d know it was fixed). Working with the Architect, I had to think about how my change would interact with existing code. Working with the QA persona, I had to define acceptance criteria before implementation.

By the time I reached the Developer agent, I wasn’t prompting and hoping. I was handing over a spec that I understood, because I’d helped build it. The implementation felt like execution, not experimentation.

And here’s what I didn’t expect: that constraint is liberating. The process felt slower at first (more steps, more questions, more writing). But I wasn’t backtracking. I wasn’t debugging code I didn’t understand. I wasn’t prompting the same thing five different ways hoping for a better result.

The spec had done its job. The thinking was front-loaded, where it belongs.

Orchestrator, not passenger

The shift I described in my earlier post, from active thinker to passive prompter, doesn’t happen with BMAD. It can’t. The method requires you to validate, decide, and course-correct at every stage.

The AI handles the grunt work: generating document templates, suggesting architectural patterns, writing implementation code that follows the spec. But you’re still the one reviewing, adjusting, and approving. You’re still the one who understands why the system is designed the way it is.

That’s the answer I was looking for. Not “don’t use AI,” but “use it in a way that keeps you in the driver’s seat.”

I delegate the dirty work. I orchestrate. I stay in the loop.

The mental model I keep coming back to is this: BMAD turns AI into a team of junior collaborators who are fast and capable, but who need direction. You’re the senior engineer. You set the vision, define the constraints, and make the judgment calls. They execute, and they execute well, but only because you’ve told them what “well” means.

That’s extending yourself. That’s the version of AI assistance I was hoping existed.

The dopamine is real (and so is the fun)

I should mention something else: this process is genuinely enjoyable.

There’s a particular satisfaction in watching a well-defined spec turn into working code without surprises. The gap between “what I wanted” and “what I got” shrinks dramatically when you’ve done the specification work upfront.

And (I didn’t expect this) role-playing with the different personas is fun. Switching from the PM mindset to the Architect mindset to the Developer mindset keeps the work varied. You’re not just grinding through one mode of thinking. You’re shifting perspectives, which keeps you engaged.

BMAD even has something called “Party Mode” where multiple agents can participate in a single conversation, debating approaches and surfacing trade-offs. It sounds gimmicky until you try it. Having the Architect and QA agents push back on each other while you moderate is surprisingly useful for finding blind spots.

What’s next

This is the first in a series of three posts.

In the next one, I’ll go deeper on the agents themselves: who they are, what each one does, how they hand off work to each other, and how you can customize the process for your own workflow.

In the third post, I’ll walk through a real project I built using BMAD: a productivity app called TODOdoro. It combines todo management with the Pomodoro technique, and I’ll show how the method helped me go from a philosophical idea (“a mirror, not a manager”) to a working application with a clear architecture.

If you’ve felt the same tension I did, excited by AI’s potential but worried about what you might lose, this might be worth following. BMAD isn’t the only answer, but it’s an answer. And for me, it’s been the difference between feeling like AI is happening to me and feeling like I’m using it deliberately.

The tools are getting more powerful every month. The question isn’t whether to use them. It’s whether you’ll use them in a way that makes you better, or in a way that quietly makes you less than you were.

I know which one I’m choosing.

Resources:

AI and the Craft: are we extending ourselves, or outsourcing ourselves?

Tue, 03 Mar 2026 00:00:00 +0000

There’s a moment, when an idea you’ve been carrying around for months starts taking shape in a matter of hours, that feels genuinely new. Not just faster, different. I’ve had that feeling more than once over the past year working with AI coding tools, and I’d be dishonest if I said it wasn’t exciting.

But somewhere along the way, I started asking a different question.

How much of this is mine?

When AI helps you build something (suggesting the structure, filling in the implementation, catching the edge cases), how much of that project actually belongs to you? Not in a legal sense. In a competence sense.

I’m not being precious about writing code by hand. But here’s the thing about friction: it’s not just an obstacle. It’s actually the mechanism by which understanding forms.

When you get stuck on a problem and have to dig yourself out, something happens. You look at the internals. You read the error message carefully. You build a mental model of why something behaves the way it does. That model stays with you. It becomes pattern recognition you can apply the next time. The path from “I wrote it” to “I understand it” runs directly through that struggle.

When AI absorbs that friction, it can produce correct output while bypassing the process entirely. You get the answer without the understanding. And the next time you hit a similar problem, you prompt again, because you never built the map.

The question isn’t whether AI is useful. It clearly is. The question is what you’re trading when you let it do more and more of the thinking.

What Copilot taught me about myself

The most honest data point I have is this: I considered cancelling my Copilot subscription because I noticed I was becoming lazy and less focused.

Lazy is a broad word, so let me be specific. What I noticed was a change in how I started problems. Before: I’d read through the context, form a rough approach in my head, maybe sketch something out. After a few months with Copilot: I found myself opening a file and almost immediately waiting for a suggestion, before I’d fully thought about what I wanted to do. The autocomplete had become a first instinct, not a second one.

That’s a subtle but meaningful shift. It’s not that the suggestions were wrong. Often they were fine. It’s that the act of reaching for them had started to replace the act of thinking. My attention was shorter. I was less likely to sit with a problem before moving. More passive in a way I hadn’t consciously chosen.

You’re still producing. The output looks fine. But the cognitive mode is different, and over time that adds up.

The risk scales with your foundation

This is where I think the conversation gets more serious: the effect isn’t the same for everyone.

If you’re a senior engineer with years of context, AI can be a genuine amplifier. You know what good looks like. You can evaluate suggestions critically. You catch the subtle mistakes. You ask better questions. The tool accelerates you because you already have the foundation to steer it.

If you’re still building that foundation, the dynamic is different. The productive struggle I mentioned earlier is not just useful, it’s almost irreplaceable at that stage. The process of debugging something from scratch, of understanding why a design decision matters, of recognizing a bad pattern before it becomes a problem: those capabilities come from having done the work, not from having seen the output.

I think AI used carelessly by junior developers doesn’t just slow their growth. It can actively shape them away from the kind of deep understanding that makes someone genuinely capable rather than just productive-looking.

The real risk isn’t replacement

There’s a lot of conversation about AI replacing developers. I think that framing misses something more immediate.

The risk, at least for me, isn’t that AI takes my job. It’s that I let it take my competence (the accumulated judgment, pattern recognition, and contextual understanding that makes a senior engineer different from someone who can prompt their way to a working prototype).

AI rewards people who already know what good looks like. It accelerates insight when you have the foundation to evaluate what it gives you. When you don’t, or when you stop maintaining that foundation, you become dependent on a system you can’t fully reason about.

What intentional use actually looks like

I didn’t cancel Copilot. But I did change how I use it.

The shift was simple: I try to form my own approach first, before I ask AI anything. Not just a vague direction, a specific enough idea that I could start without it. Then I use AI to accelerate, validate, or challenge that approach. Sometimes it shows me a better path. Sometimes I find I’d already gotten there. Either way, I’ve done the thinking.

I also try to be deliberate about when I let AI drive and when I don’t. Boilerplate, repetitive patterns, documentation: fine. Logic I don’t fully understand yet, architectural decisions, anything I’d struggle to explain to someone else afterwards: I work through those myself first.

The distinction I keep coming back to: are you using AI to extend your capabilities, or to externalize them? One makes you better over time. The other quietly makes you less capable than you were.

What truly makes the difference as a software engineer is the ability to craft and package a tailored solution for each specific context, not just to follow the latest tool, trend, or suggestion. That judgment doesn’t come from prompts; it comes from deliberate practice and honest reflection about what you actually understand.

The question is worth asking regularly, especially when the output looks good and everything feels fast.

Are you extending yourself, or outsourcing yourself?

Adding Interactive Cockpit Controls to Grav-Sync

Sun, 09 Nov 2025 00:00:00 +0000

Today I implemented a major visual upgrade to my GitHub Game Off 2025 project, Grav-Sync, by adding an interactive cockpit interface with animated control knobs. This enhancement significantly improves the game’s visual feedback and makes the controls more intuitive and engaging.

What Changed

Animated Control Knobs

The main feature I added today is a fully functional cockpit interface with two animated control knobs:

Red Knob (controlled by A/D keys): Adjusts wave frequency
Blue Knob (controlled by W/S keys): Adjusts wave amplitude

Each knob has a 2-frame animation that advances whenever the player presses the corresponding control keys, providing immediate visual feedback for player input.

New Sprite System Method

To support the knobs, I extended the Sprite class with a new nextFrame() method that allows manual frame advancement. This is different from the existing automatic animation used by the Earth sprite, which continuously cycles through frames. The knobs only animate when the player provides input, making them feel more responsive and connected to the controls.

1
2
3
4


// Advance animation by one frame (useful for manual control)
nextFrame() {
 this.index = (this.index + 1) % this.len;
}

Input Handler Integration

I updated the InputHandler class to trigger knob animations alongside the existing player wave adjustments. Now when you press W/S or A/D keys, not only does your wave change, but the corresponding knob visibly rotates, providing clear visual feedback:

1
2
3
4
5
6
7


w: {
 pressed: keyIsDown(87) || keyIsDown(119),
 action: () => {
 this.player.increaseAmplitude();
 blueKnob.nextFrame();
 },
}

Cockpit Rendering

I created a new drawCockpit() method in the Game class that handles the rendering of the cockpit base image and positions both knobs correctly relative to it. The cockpit is positioned near the bottom of the screen, and the knobs are placed at appropriate positions using a local coordinate system:

The cockpit base is rendered first
Both knobs are positioned relative to the cockpit using push()/pop() transformations
Each knob maintains its current animation frame and scale

UI Repositioning

To accommodate the new cockpit interface, I repositioned the UI elements:

Moved amplitude and frequency displays to be adjacent to their respective knobs
Centered the sync percentage and score displays on the cockpit
Removed some redundant labels to keep the interface clean
Adjusted the Earth sprite position slightly upward to leave room for the cockpit

Configuration Adjustments

I made a small but important change to the configuration: the Earth sprite’s Y position was adjusted upward by 80 pixels (config.earthY = config.screenHeight / 2 - 80) to better center the visible play area above the cockpit.

Technical Implementation

The implementation involved several files:

animations/knob.json - Animation configuration defining two frames for the knob rotation
sprites/ - Added three new images: cockpit.png, red-knob.png, and blue-knob.png
sketch.js - Preloaded new assets and initialized knob sprites
game.js - Implemented drawCockpit() method for rendering
input.js - Integrated knob animations with key press handlers
sprite.js - Added nextFrame() method for manual animation control
ui.js - Repositioned UI text elements
config.js - Adjusted Earth position

Code Organization

After implementing the cockpit feature, I also performed a minor refactoring to better organize global variables in sketch.js, grouping related variables together for improved code readability.

Results

The cockpit addition makes the game feel more polished and immersive. Players now have:

Visual feedback - See exactly when their inputs are registered
Clearer controls - The knobs make it obvious what W/S and A/D keys control
Better aesthetics - The cockpit theme reinforces the space/orbital mechanics concept
Improved layout - UI elements are better organized around the cockpit

This change represents a significant step forward in the game’s visual design and user experience. The cockpit not only looks good but also serves a functional purpose by making the controls more intuitive and providing immediate visual feedback for player actions.

What’s Next

With the cockpit in place, the game is starting to feel more complete. Future improvements might include:

Adding sound effects for knob rotation
Adding a main manu

You can check out the full code on GitHub, and I’d love to hear feedback from anyone who tries it out!

DevLog: Adding Dynamic Waves and Animated Sprites to Grav Sync

Sat, 08 Nov 2025 00:00:00 +0000

Over the past development cycle, I worked on two features for Grav Sync, these updates transformed the game from a static puzzle into a more dynamic and visually engaging experience.

Here’s a detailed look at what was implemented and why.

Branch 1: `random-wave` - Introducing Dynamic Challenge

The Problem

The original game featured a fixed target wave that players needed to match. While functional, this meant that once players learned the solution, the game became repetitive. Every playthrough was essentially the same puzzle.

The Solution: Randomized Target Frequencies

I implemented a system to randomize the target wave’s frequency at the start of each round, making every attempt unique and challenging.

Key Changes:

Random Frequency Generation: Added getRandomInt(10, 30) function to generate target frequencies within a balanced range
Dynamic Target Updates: The target frequency now regenerates each time the target wave resets (when it reaches the player’s orbital radius)
UI Enhancement: Added on-screen display of the current target frequency to give players clear feedback

Implementation Details:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// Initialize with random frequency in setup()
targetWave.frequency = getRandomInt(10, 30);

// Regenerate on wave reset
if (targetWave.baseRadius === playerRadius) {
 if (sync > 0.8) {
 score++;
 }
 targetWave.frequency = getRandomInt(10, 30); // New random target
 targetWave.baseRadius = 380;
}

Refining the Synchronization System

While implementing randomization, I also overhauled how synchronization is calculated. The original system treated frequency and amplitude equally, but through playtesting, it became clear that frequency matching is far more critical to achieving visual alignment.

The New Weighted System:

80% weight on frequency matching: Ensures players prioritize getting the wave count correct
20% weight on amplitude matching: Fine-tuning for perfect alignment
Phase ignored: Simplified gameplay by removing phase as a factor, making the puzzle more approachable

Technical Implementation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


function calculateSync() {
 // Frequency score: compare numeric values directly (ignoring phase)
 let freqRange = maxFrequency - minFrequency;
 let freqDiff = abs(targetWave.frequency - playerWave.frequency) / freqRange;
 let freqScore = 1 - freqDiff;

 // Amplitude score: compare amplitude values
 let ampRange = maxAmplitude - minAmplitude;
 let ampDiff = abs(targetWave.amplitude - playerWave.amplitude) / ampRange;
 let ampScore = 1 - ampDiff;

 // Combine with 80:20 weighting
 return freqScore * 0.8 + ampScore * 0.2;
}

This change made the game feel more intuitive, players could immediately see the impact of frequency adjustments while still needing to fine-tune amplitude for perfect scores.

Impact

The random-wave branch transformed Grav Sync from a single-solution puzzle into a replayable game with procedural variation. Each round now presents a fresh challenge, and the weighted sync system provides clearer feedback about what matters most.

Branch 2: `sprites` - Bringing Earth to Life

The Vision

The original Earth was rendered as a simple static circle with basic ellipse shapes for continents. While functional, it lacked the polish and visual interest the game deserved. I wanted Earth to feel like a living, rotating planet at the center of the cosmic waves.

Creating the Sprite System

Step 1: Sprite Sheet Preparation

I found a 94-frame sprite sheet showing Earth rotating (attribution has been made into the repo):

Format: 480×480 PNG
Layout: 10×10 grid (10 frames per row for 9 rows, 4 frames in the final row)
Frame size: 48×48 pixels per frame
Animation style: Flat earth texture scrolling across a circular mask

Step 2: Frame Data Mapping

Created animations/earth.json to map all 94 frames with precise coordinates:

1
2
3
4
5
6
7
8
9


{
 "frames": [
 {
 "name": "sprite-00",
 "position": { "x": 0, "y": 0, "w": 48, "h": 48 }
 }
 // ... 93 more frames
 ]
}

Step 3: Building the Sprite Class

Implemented a reusable Sprite class in sprite.js:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


class Sprite {
 constructor(animation, x, y, speed, scale = 1) {
 this.x = x;
 this.y = y;
 this.animation = animation; // Array of p5.Image objects
 this.w = this.animation[0].width;
 this.len = this.animation.length;
 this.speed = speed; // Animation speed (frames per draw call)
 this.scale = scale; // Scaling factor
 this.index = 0; // Current frame index
 }

 show() {
 let index = floor(this.index) % this.len;
 push();
 imageMode(CENTER);
 image(
 this.animation[index],
 this.x,
 this.y,
 this.w * this.scale,
 this.w * this.scale
 );
 pop();
 }

 animate() {
 this.index += this.speed; // Advance animation
 }
}

Key Features:

Flexible animation speed: Random speed on initialization creates subtle variation
Scalable sprites: Can match any target size (scaled to 96×96 to match original Earth diameter)
Center-based positioning: Uses imageMode(CENTER) for intuitive placement
Error handling: Validates animation array to prevent crashes

Integration Challenges

Challenge 1: Variable Scope Issues

Initial implementation had bugs where the animation array wasn’t properly declared:

1
2
3
4
5


// Problem: 'animation' not declared
for (let i = 0; i < frames.length; i++) {
 animation.push(img); // ReferenceError
}
earth = new Sprite(animation, 0, i * 75, ...); // 'i' undefined here

Solution:

1
2
3
4
5


function setup() {
 let animation = []; // Properly scoped
 // Load frames...
 earth = new Sprite(animation, earthX, earthY, random(0.1, 0.4), spriteScale);
}

Challenge 2: Sprite Positioning

Initially, sprites appeared in the top-left corner instead of centered. The issue was that p5.js’s image() function defaults to corner-mode positioning.

Solution: Wrapped rendering in push()/pop() and set imageMode(CENTER) to ensure sprites draw from their center point.

Challenge 3: Size Matching

The original hand-drawn Earth had a diameter of 96px (radius 48), but the sprite frames were 48×48.

Solution: Calculate scale factor dynamically:

1
2


let spriteScale = (earthRadius * 2) / 48; // 96 / 48 = 2.0
earth = new Sprite(animation, earthX, earthY, random(0.1, 0.4), spriteScale);

The Result

The sprite system brought immediate visual improvements:

Living planet: Earth now rotates continuously, adding life to the scene
Variable speed: Random animation speeds (0.1–0.4) create subtle uniqueness each game
Smooth animation: 94 frames provide fluid rotation without obvious looping
Maintained aesthetics: Scaled perfectly to match the original Earth size

Code Quality Improvements

Added validation to prevent edge-case crashes:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


if (
 this.animation.length > 0 &&
 this.animation[0] &&
 typeof this.animation[0].width !== "undefined"
) {
 this.w = this.animation[0].width;
} else {
 this.w = 0;
 console.warn("Sprite: animation array is empty or invalid.");
}

Also fixed a stroke bleed issue where wave rendering affected subsequent draws:

1
2
3
4
5


function drawWave(wave, currentTime) {
 // ... draw wave ...
 endShape(CLOSE);
 stroke("black"); // Reset stroke to prevent bleeding
}

What’s Next?

With these two branches merged, Grav Sync now has:

Dynamic, randomized gameplay
Polished visual presentation
Intuitive sync feedback

Future improvements could include:

Audio integration: Frequency-based soundscapes using p5.sound
Difficulty curves: Progressive challenge scaling
Particle effects or shaders: Visual feedback when sync is achieved

Conclusion

These two updates made Grav Sync more engaging: random frequencies add replay value, and the animated Earth sprite improves the visual appeal. The game is now more fun to play than the original static version.

You can check out the full code on GitHub, and I’d love to hear feedback from anyone who tries it out!

DevLog #1 GravSync

Sun, 02 Nov 2025 00:00:00 +0000

This year again, as every November since 2012, GitHub Game Off takes place, the game jam organized by GitHub where you have to develop a video game on a specific theme within a month. This year I decided to participate with the excuse of practicing with JavaScript (specifically I chose to use p5.js, but this might change if I see it doesn’t quite suit my needs).

The theme

This year’s theme is waves (quoting from the jam page)

wave /weɪv/

Noun

A moving ridge on the surface of a liquid (for example, ocean waves or coffee ripples).

A repeating pattern of motion, energy, or sound (for example, sound waves or radio waves).

A sudden burst or surge (for example, a wave of enemies or a wave of emotion).

A gesture of greeting or farewell.

Verb

To move your hand in greeting or farewell.

To undulate or fluctuate (for example, wheat waving in the wind).

To signal or summon (for example, waving someone through a door).

Adjective

Flowing, wavy, or oscillating (for example, wavy hair).

Acronyms (OK, we made these up)

Wizards Accelerating Velocity Every Sunday

Warriors Against Variable Energy Surges

Whales And Vikings Engaging Submarines

Or make up your own—we love seeing how creative you get with it!

My idea

As a space and astrophysics enthusiast, the word “waves” immediately brought gravitational waves to mind, so why not create a mini puzzle game where you have to save Earth from malicious gravitational waves (whatever that means)?

The idea is simple: The player tunes multiple gravitational waves to achieve resonance and stabilize the universe. The challenge is to synchronize the waves under time pressure while maintaining alignment.

But how to implement it?

Initially, since you need to make something small for a jam, I simply thought of showing two sine waves, the first being the target wave and the second controlled by the player, but that would have been incredibly boring, so why not put Earth at the center and make the waves “arrive” on it?

So here’s planet Earth in all its splendor

But how do you create a circular sine wave? Searching a bit on the web, it turns out that the formula for drawing a sine wave on a circumference is this

[ r(\theta) = r_0 + A \cdot \sin(n \theta + \phi) ]

so having defined my JS object to represent the wave like this

1
2
3
4
5
6
7
8


let targetWave = {
 baseRadius: 380,
 amplitude: 15,
 frequency: 10,
 phase: 0,
 animationSpeed: 0.05,
 color: [255, 255, 255, 200],
};

I defined the function to draw it along a circumference like this

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


function drawWave(wave) {
 stroke(wave.color[0], wave.color[1], wave.color[2], wave.color[3]);
 strokeWeight(3);
 noFill();
 beginShape();
 for (let angle = 0; angle <= TWO_PI + 0.1; angle += 0.05) {
 let phaseRadians = radians(wave.phase);

 let baseRadius =
 wave.baseRadius +
 wave.amplitude *
 sin(
 wave.frequency * angle +
 phaseRadians +
 currentTime * wave.animationSpeed * 50
 );

 let radius = baseRadius;
 let x = earthX + radius * cos(angle);
 let y = earthY + radius * sin(angle);
 vertex(x, y);
 }
 endShape(CLOSE);
}

and here’s the result

At this point, however, it seemed more like the circumferences were rotating rather than being sine waves, so I decided to add some disturbance, but only for rendering purposes so as not to influence the player’s synchronization calculation.

The drawWave function therefore became like this

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34


function drawWave(wave, currentTime) {
 stroke(wave.color[0], wave.color[1], wave.color[2], wave.color[3]);
 strokeWeight(3);
 noFill();
 beginShape();
 for (let angle = 0; angle <= TWO_PI + 0.1; angle += 0.05) {
 let phaseRadians = radians(wave.phase);

 // Base wave calculation (for sync)
 let baseRadius =
 wave.baseRadius +
 wave.amplitude *
 sin(
 wave.frequency * angle +
 phaseRadians +
 currentTime * wave.animationSpeed * 50
 );

 // Add subtle disturbance for visual effect only
 let disturbance =
 3 *
 sin(angle * 15 + currentTime * 0.8) *
 cos(angle * 8 + currentTime * 0.6) +
 2 *
 sin(angle * 23 + currentTime * 1.2) *
 cos(angle * 12 + currentTime * 0.9);

 let radius = baseRadius + disturbance;
 let x = earthX + radius * cos(angle);
 let y = earthY + radius * sin(angle);
 vertex(x, y);
 }
 endShape(CLOSE);
}

At this point, the last thing to do before closing the day was to make the target wave circumference reduce over time and once it reached the player’s circumference, calculate the score based on the sync value (for now I add a point to the score if sync > 80%, we’ll see later)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


if (targetWave.baseRadius > 50) {
 targetWave.baseRadius -= 0.5; // Reduce base radius by 0.5 each frame
 targetWave.baseRadius = max(50, targetWave.baseRadius); // Don't go below 50
}

if (targetWave.baseRadius === playerWave.baseRadius) {
 if (sync > 0.8) {
 score++;
 }
 // make the target wave big again to simulate a second wave
 targetWave.baseRadius = 380;
}

Obviously the player can use the keyboard to modify the amplitude and frequency of their own wave to align with the target wave

First day done

For now I’m satisfied, I’ve omitted the technical details on how I calculated the sync and other little things (forgive me, it’s my first devlog). If you want to take a look at the code it’s available on my GitHub profile

Code Smells: Learn to Sniff Them Out

Fri, 22 Nov 2024 00:00:00 +0000

“Code smells” are subtle indicators of underlying problems in your codebase. They don’t crash your app or throw errors but can lead to long-term maintainability issues if left unaddressed. Let’s dive into what code smells are, examples of common smells, and how to clean them up.

What Are Code Smells?

Coined by Martin Fowler in Refactoring: Improving the Design of Existing Code, code smells are symptoms of poor design or coding practices.
They signal that something might need refactoring, even if it technically works.

🧠 Think of them as warning signs, not bugs. A bug means something is broken; a smell means your design could use improvement.

Common Code Smells and How to Fix Them

Long Methods

The Smell: A single method tries to do too much (e.g., 200+ lines of code).
Why It’s Bad: Hard to read, test, and debug.
Fix: Break the method into smaller, single-purpose methods. Use meaningful names to make their purpose clear.

Before:

1
2
3
4
5


public void processOrder(Order order) {
 // Code for validating order 
 // Code for applying discounts 
 // Code for calculating total 
 // Code for sending confirmation email }

After:

1
2
3
4
5
6


public void processOrder(Order order) {
 validateOrder(order);
 applyDiscounts(order);
 calculateTotal(order);
 sendConfirmation(order);
}

Large Classes (God Objects)

The Smell: A class tries to handle too many responsibilities.
Why It’s Bad: Violates the Single Responsibility Principle (SRP). Hard to maintain and extend.
Fix: Split the class into smaller, more focused classes. Use patterns like composition or delegation.

Before:

1
2
3
4
5
6


public class UserManager {
 public void createUser() { ... }
 public void validateUser() { ... }
 public void sendEmail() { ... }
 public void logActivity() { ... }
}

After:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public class UserService {
 public void createUser() { ... }
}
---
public class UserValidator {
 public void validateUser() { ... }
}

---
public class EmailService {
 public void sendEmail() { ... }
}

Magic Numbers and Strings

The Smell: Unexplained hard-coded values scattered throughout your code.
Why It’s Bad: Makes code confusing and harder to maintain.
Fix: Replace them with constants or enums.

Before:

1

if (status == 3) { ... }

After:

1
2
3
4


private static final int STATUS_APPROVED = 3;
...
...
if (status == STATUS_APPROVED) { ... }

Duplicate Code

The Smell: Identical or nearly identical code blocks in multiple places.
Why It’s Bad: Increases maintenance effort. Changes in one place need to be replicated everywhere.
Fix: Abstract the duplicated logic into a reusable method or class.

Before:

1
2
3
4
5
6
7


public int calculateDiscount(int price) {
 return price * 10 / 100;
}

public int calculateTax(int price) {
 return price * 10 / 100;
}

After:

1
2
3


public int applyPercentage(int price, int percentage) {
 return price * percentage / 100;
}

Long Parameter Lists

The Smell: Methods or constructors take too many parameters.
Why It’s Bad: Makes code harder to understand and prone to errors when calling.
Fix: Use an object to encapsulate related parameters.

Before:

1

public void createOrder(String product, int quantity, double price, String customerName, String address) { ... }

After:

1

public void createOrder(OrderRequest request) { ... }

Tools to Detect Code Smells

SonarQube: Analyzes code quality and detects common smells.
IntelliJ IDEA: Built-in inspections flag potential issues like long methods or God objects.
Refactoring Books: Refactoring: Improving the Design of Existing Code by Martin Fowler is a must-read!

Actionable Tips to Avoid Code Smells

Start Small: Refactor one smell at a time.
Embrace Code Reviews: Fresh eyes can spot smells you’ve become blind to.
Automate Tests: Refactoring is less scary when you have a safety net of tests.
Follow SOLID Principles: Adhering to these can prevent many smells in the first place.

💡 Takeaway: Code smells are inevitable as your codebase grows, but catching and addressing them early can save you from costly rewrites later.

An In-Depth Look at Project Lombok: A Follow-Up 🚀

Wed, 20 Nov 2024 00:00:00 +0000

Following up on my earlier post about 𝗣𝗿𝗼𝗷𝗲𝗰𝘁 𝗟𝗼𝗺𝗯𝗼𝗸 on LinkedIn, let’s dive deeper into 𝘄𝗵𝘆 𝗟𝗼𝗺𝗯𝗼𝗸 𝗰𝗮𝗻 𝗯𝗲 𝗮 𝗯𝗹𝗲𝘀𝘀𝗶𝗻𝗴 𝗮𝗻𝗱 𝗮 𝗰𝘂𝗿𝘀𝗲 in your codebase.

✅ 𝗧𝗵𝗲 𝗚𝗼𝗼𝗱: 𝗪𝗵𝘆 𝗟𝗼𝗺𝗯𝗼𝗸 𝗦𝗵𝗶𝗻𝗲𝘀

𝗖𝗹𝗲𝗮𝗻𝗲𝗿, 𝗥𝗲𝗮𝗱𝗮𝗯𝗹𝗲 𝗖𝗼𝗱𝗲:

Lombok eliminates the need for repetitive methods like getters, setters, toString, and constructors. With annotations like @Getter, @Setter, @Builder, and @Data, classes become concise and easier to understand.

𝗙𝗮𝘀𝘁𝗲𝗿 𝗗𝗲𝘃𝗲𝗹𝗼𝗽𝗺𝗲𝗻𝘁:

Focus on 𝘄𝗵𝗮𝘁 𝗺𝗮𝘁𝘁𝗲𝗿𝘀—business logic—while Lombok handles the repetitive tasks.

𝗜𝗺𝗽𝗿𝗼𝘃𝗲𝗱 𝗠𝗮𝗶𝗻𝘁𝗮𝗶𝗻𝗮𝗯𝗶𝗹𝗶𝘁𝘆

Changes to class fields automatically reflect in generated methods, reducing manual errors.

@𝗘𝗾𝘂𝗮𝗹𝘀𝗔𝗻𝗱𝗛𝗮𝘀𝗵𝗖𝗼𝗱𝗲: No more tedious 𝘩𝘢𝘴𝘩𝘊𝘰𝘥𝘦 and 𝘦𝘲𝘶𝘢𝘭𝘴 implementations.
@𝗕𝘂𝗶𝗹𝗱𝗲𝗿: Simplifies complex object creation with immutability.

𝗕𝗲𝘁𝘁𝗲𝗿 𝗖𝗼𝗱𝗲 𝗥𝗲𝘃𝗶𝗲𝘄𝘀:

Git diffs become cleaner since boilerplate is hidden. 𝗧𝗲𝗮𝗺𝘀 𝗰𝗮𝗻 𝘀𝗽𝗼𝘁 𝗺𝗲𝗮𝗻𝗶𝗻𝗴𝗳𝘂𝗹 𝗰𝗵𝗮𝗻𝗴𝗲𝘀 𝗳𝗮𝘀𝘁𝗲𝗿.

❌ 𝗧𝗵𝗲 𝗥𝗶𝘀𝗸𝘀 𝗮𝗻𝗱 𝗖𝗮𝘃𝗲𝗮𝘁𝘀 𝗼𝗳 𝗟𝗼𝗺𝗯𝗼𝗸

𝗧𝗿𝗮𝗻𝘀𝗽𝗮𝗿𝗲𝗻𝗰𝘆 𝗜𝘀𝘀𝘂𝗲𝘀:

Generated code isn’t visible in your editor unless you delve into decompiled classes.

Can confuse 𝗻𝗲𝘄 𝘁𝗲𝗮𝗺 𝗺𝗲𝗺𝗯𝗲𝗿𝘀 or those unfamiliar with Lombok.
Debugging becomes harder when stack traces point to 𝗶𝗻𝘃𝗶𝘀𝗶𝗯𝗹𝗲 𝗺𝗲𝘁𝗵𝗼𝗱𝘀.

𝗢𝘃𝗲𝗿𝘂𝘀𝗲 𝗼𝗳 𝗔𝗻𝗻𝗼𝘁𝗮𝘁𝗶𝗼𝗻𝘀:

Lombok can lead to 𝗰𝗼𝗱𝗲 𝗯𝗹𝗼𝗮𝘁 if misused:

@Data generates equals, hashCode, toString, getters, setters, and a constructor—some of which might not be needed.
This can impact 𝗽𝗲𝗿𝗳𝗼𝗿𝗺𝗮𝗻𝗰𝗲 or cause 𝘂𝗻𝗲𝘅𝗽𝗲𝗰𝘁𝗲𝗱 𝗯𝗲𝗵𝗮𝘃𝗶𝗼𝗿 (i.e @𝘛𝘰𝘚𝘵𝘳𝘪𝘯𝘨 in nested entities could easily lead to a 𝗦𝘁𝗮𝗰𝗸𝗢𝘃𝗲𝗿𝗙𝗹𝗼𝘄𝗘𝘅𝗰𝗲𝗽𝘁𝗶𝗼𝗻).

𝗧𝗼𝗼𝗹𝗶𝗻𝗴 𝗮𝗻𝗱 𝗖𝗼𝗺𝗽𝗮𝘁𝗶𝗯𝗶𝗹𝗶𝘁𝘆:

IDEs or static analysis tools sometimes struggle with Lombok-generated code.
Upgrading to new Java versions may introduce 𝗰𝗼𝗺𝗽𝗮𝘁𝗶𝗯𝗶𝗹𝗶𝘁𝘆 𝗶𝘀𝘀𝘂𝗲𝘀.

𝗗𝗲𝗽𝗲𝗻𝗱𝗲𝗻𝗰𝘆 𝗟𝗼𝗰𝗸-𝗜𝗻:

Removing Lombok later can be challenging, requiring significant rewrites.

𝗗𝗲𝗯𝘂𝗴𝗴𝗶𝗻𝗴 𝗛𝗲𝗮𝗱𝗮𝗰𝗵𝗲𝘀:

Lombok-generated code may not have clear stack traces, making debugging non-trivial.

𝗛𝗼𝘄 𝘁𝗼 𝗨𝘀𝗲 𝗟𝗼𝗺𝗯𝗼𝗸 𝗘𝗳𝗳𝗲𝗰𝘁𝗶𝘃𝗲𝗹𝘆

𝗕𝗲 𝗦𝗲𝗹𝗲𝗰𝘁𝗶𝘃𝗲 𝘄𝗶𝘁𝗵 𝗔𝗻𝗻𝗼𝘁𝗮𝘁𝗶𝗼𝗻𝘀:

Use specific annotations like @𝘎𝘦𝘵𝘵𝘦𝘳 and @𝘚𝘦𝘵𝘵𝘦𝘳 instead of all-in-one annotations like @𝘋𝘢𝘵𝘢.
Avoid unnecessary methods (e.g., don’t generate 𝘦𝘲𝘶𝘢𝘭𝘴/𝘩𝘢𝘴𝘩𝘊𝘰𝘥𝘦 unless required).

𝗨𝗻𝗱𝗲𝗿𝘀𝘁𝗮𝗻𝗱 𝘁𝗵𝗲 𝗚𝗲𝗻𝗲𝗿𝗮𝘁𝗲𝗱 𝗖𝗼𝗱𝗲:

Use IDE features like decompile or delombok during builds to view generated code.
Knowing what’s happening under the hood prevents surprises.

𝗣𝗹𝗮𝗻 𝗳𝗼𝗿 𝗟𝗼𝗻𝗴-𝗧𝗲𝗿𝗺 𝗠𝗮𝗶𝗻𝘁𝗲𝗻𝗮𝗻𝗰𝗲:

If you outgrow Lombok, a 𝗱𝗲𝗹𝗼𝗺𝗯𝗼𝗸 build step can help with the migration.

Conclusion

𝗟𝗼𝗺𝗯𝗼𝗸 𝗶𝘀 𝗮 𝗽𝗼𝘄𝗲𝗿𝗳𝘂𝗹 𝘁𝗼𝗼𝗹, 𝗯𝘂𝘁 𝗶𝘁 𝗿𝗲𝗾𝘂𝗶𝗿𝗲𝘀 𝗿𝗲𝘀𝗽𝗼𝗻𝘀𝗶𝗯𝗹𝗲 𝘂𝘀𝗮𝗴𝗲. It’s a must-have for teams looking to streamline development, but only if the team is aligned and mindful of the caveats. What’s your experience with Lombok? Are you using it effectively in your projects? Let’s discuss! 🧑💻

How to Use SonarQube and SonarScanner Locally to Level Up Your Code Quality

Wed, 13 Nov 2024 00:00:00 +0000

Code quality tools can make a huge difference in improving your coding skills by helping you identify code smells, bugs, and potential vulnerabilities.

In this guide, we’ll explore how to set up SonarQube and SonarScanner locally. This allows you to analyze your code for potential improvements right on your machine.

Step 1: Setting Up SonarQube with Docker

First, ensure you have Docker installed. With Docker, getting SonarQube up and running is straightforward:

Pull the SonarQube image:

docker pull sonarqube
Run SonarQube:

docker run -d --name sonarqube -p 9000:9000 -p 9092:9092 sonarqube

This command runs SonarQube in the background, mapping port 9000 (for the SonarQube web interface) and 9092 (optional).

Step 2: Accessing SonarQube

With SonarQube running, open your browser and go to http://localhost:9000. Enter the default credentials:

Username: admin
Password: admin

Once logged in, you will be prompted to change the default password.

Step 3: Generate an Authentication Token

To allow SonarScanner to connect to SonarQube, you need to create an authentication token.

Click the A icon in the top-right corner and select My Account.
Navigate to the Security tab and click Generate a token.
Name your token (it can be user-specific or global) and save it somewhere secure, as it will only be displayed once.

Step 4: Configure `sonar-project.properties`

Next, set up a configuration file to define key project properties SonarQube will use to analyze your code. In the root directory of your project, create a file named sonar-project.properties and add the following content:

1
2
3
4
5


sonar.projectKey=my:project # Must be unique 
sonar.projectName=my project name 
sonar.projectVersion=1.0 sonar.sources=src/main/java # Adjust based on your source directory 
sonar.java.binaries=target/classes  # Adjust based on your compiled classes 
sonar.tests=src/test/java # Adjust based on your test directory

This configuration file tells SonarQube about the structure and setup of your project.

Step 5: Run SonarScanner

With everything set up, it’s time to analyze your project. Open a terminal at the root of your project and execute the following command:

1
2
3
4
5
6
7
8
9


mvn clean install && \
mvn dependency:copy-dependencies && \
docker run \
 --rm \
 --network host \
 -e SONAR_HOST_URL="http://{YOUR LOCAL IP}:9000" \
 -e SONAR_TOKEN="{YOUR SONARQUBE TOKEN}" \
 -v "$(pwd):/usr/src" \
 sonarsource/sonar-scanner-cli

This command does the following:

Cleans and builds your project using Maven (mvn clean install).
Copies dependencies needed for analysis.
Runs SonarScanner in a Docker container and connects it to your local SonarQube instance.

Replace {YOUR LOCAL IP} with your machine’s local IP address and {YOUR SONARQUBE TOKEN} with the token you generated in Step 4.

Step 6: Review the Analysis Results in SonarQube

Once SonarScanner completes its run, return to http://localhost:9000 and navigate to your project dashboard. Here, you’ll see a detailed report on:

Code smells: Areas of the codebase that could benefit from refactoring.
Bugs: Logical errors or anomalies in the code.
Vulnerabilities: Security-related issues.

Conclusion

Setting up SonarQube and SonarScanner locally allows you to take your code quality analysis into your own hands. Regularly reviewing these reports can help you develop better habits, improve your understanding of code quality principles, and ultimately level up your coding skills.

Design Patterns: Singleton

Wed, 04 Sep 2024 00:00:00 +0000

Singleton is a creational design pattern that ensures a class has only one instance and provides a global access point to that instance.

Problem

In software development, it’s common to need a single instance of a class to be shared across an application. Having multiple instances can lead to issues such as unexpected behaviors or inefficient resource usage.

Solution

The Singleton pattern addresses this problem by:

Making the class constructor private to prevent direct instantiation from outside the class.
Providing a static public method that acts as a constructor. Before creating a new instance, it checks if an instance already exists in a private static field. If the field is null, it creates a new instance and assigns it to the field; otherwise, it returns the existing instance.

Java example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public class Singleton {
 private static Singleton instance;

 private Singleton() {
 // initialization code
 }

 public static Singleton getInstance() {
 if(intance == null) {
 instance = new Singleton();
 }
 return instance;
 }
}

Applications

Use the Singleton pattern when you need a single instance of a class to be shared across the entire application.

Tips

Be careful when using the Singleton pattern in multi-threaded scenarios, as it is not inherently thread-safe. Check this article for further details

Singleton pattern thread-safety in java

Wed, 04 Sep 2024 00:00:00 +0000

As stated in this article, singleton is not thread-safe by default. Let’s see how to make it thread-safe.

Basic singleton class

First, let’s recap how to create a basic singleton:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public class Singleton {
 private static Singleton instance;

 private Singleton() {
 // initialization code
 }

 public static Singleton getInstance() {
 if(instance == null) {
 instance = new Singleton();
 }
 return instance;
 }
}

This implementation does not guarantee correct behavior in a multithreaded environment.

How to make a singleton thread-safe

We can achieve singleton thread-safety in several ways:

Eager initialization
Lazy initialization with method synchronization
Double-checked initialization with synchronized block and volatile variable

Eager initialization

In this approach, the instance is created when the class itself gets loaded in the application context to ensure thread-safety without relying on any synchronization mechanism. However, it could lead to a waste of resources if the instance is never used, and it doesn’t allow passing parameters during instantiation.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public class EagerSingleton {

 // Instance created at the time of class loading
 private static final EagerSingleton instance = new EagerSingleton();

 private EagerSingleton() {}

 public static EagerSingleton getInstance() {
 return instance;
 }
}

Lazy initialization with method synchronization

This approach ensures thread safety by synchronizing the getInstance() method. However, this method can suffer from performance issues due to synchronization overhead on every call to getInstance().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public class SynchronizedSingleton {

 private static SynchronizedSingleton instance;

 private SynchronizedSingleton() {}

 // Synchronized method to control simultaneous access
 public static synchronized SynchronizedSingleton getInstance() {
 if (instance == null) {
 instance = new SynchronizedSingleton();
 }
 return instance;
 }
}

Double-checked initialization with synchronized block and volatile variable

In this approach, similar the previous one, the synchronization overhead is reduced by synchronizing only the first time the instance is accessed. The instance variable is marked as volatile to prevent the occurrence of partially constructed instances.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


public class DoubleCheckedSingleton {

 // volatile keyword ensures that multiple threads handle the instance variable correctly
 private static volatile DoubleCheckedSingleton instance;

 private DoubleCheckedSingleton() {}

 // Method to return the singleton instance with double-checked locking
 public static DoubleCheckedSingleton getInstance() {
 if (instance == null) { // First check without synchronization
 synchronized (DoubleCheckedSingleton.class) {
 if (instance == null) { // Second check with synchronization
 instance = new DoubleCheckedSingleton();
 }
 }
 }
 return instance;
 }
}

Design Patterns: Facade

Tue, 03 Sep 2024 00:00:00 +0000

Facade is a structural design pattern that let’s you interact with complex systems through a simpler interface.

Problem

In software development, is often necessary to interact with complex systems composed of different interdependent classes and usually you don’t need to use all of them, but only a small subset. You probably also want to avoid tight coupling with those classes as it would make difficult to make future changes.

Solution

This is where the Facade pattern proves useful. By providing a unified interface, the facade allows clients to interact with the system using only the subset of functionality they need, while hiding the complexities of the underlying subsystem. This enhances both decoupling and simplicity.

Real-World example

Imagine a software that uses different logging mechanisms:

File Logging for saving logs to a file.
Console Logging for outputting logs to the console.
Remote Server Logging for sending logs to a remote server. Each logging mechanism might involve different classes and methods. Managing and using all these logging mechanisms directly can be complex and cumbersome.

You can use the Facade Pattern to provide a simplified interface for logging. The facade will handle the complexities of interacting with different logging mechanisms and provide a unified way to log messages.

Java example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69


// SUBSYSTEM CLASSES
// File logging subsystem
class FileLogger {
 public void logToFile(String message) {
 System.out.println("Logging to file: " + message);
 }
}

// Console logging subsystem
class ConsoleLogger {
 public void logToConsole(String message) {
 System.out.println("Logging to console: " + message);
 }
}

// Remote server logging subsystem
class RemoteServerLogger {
 public void logToServer(String message) {
 System.out.println("Sending log to remote server: " + message);
 }
}


// FACADE CLASS
class LoggerFacade {
 private FileLogger fileLogger;
 private ConsoleLogger consoleLogger;
 private RemoteServerLogger remoteServerLogger;

 public LoggerFacade() {
 this.fileLogger = new FileLogger();
 this.consoleLogger = new ConsoleLogger();
 this.remoteServerLogger = new RemoteServerLogger();
 }

 public void log(String message) {
 fileLogger.logToFile(message);
 consoleLogger.logToConsole(message);
 remoteServerLogger.logToServer(message);
 System.out.println("Log message processed.");
 }
}

// CLIENT CODE
public class Main {
 public static void main(String[] args) {
 LoggerFacade logger = new LoggerFacade();
 logger.log("This is a log message."); // Unified logging
 }
}

// CLIENT CODE WITHOUT FACADE
public class Main {
 public static void main(String[] args) {
 // Create instances of each logging subsystem
 FileLogger fileLogger = new FileLogger();
 ConsoleLogger consoleLogger = new ConsoleLogger();
 RemoteServerLogger remoteServerLogger = new RemoteServerLogger();

 // Log a message using all the logging mechanisms
 String message = "This is a log message.";

 fileLogger.logToFile(message);
 consoleLogger.logToConsole(message);
 remoteServerLogger.logToServer(message);

 System.out.println("Log message processed.");
 }
}

As you can see from the example above, the client code without facade is more complex even using just three classes, imagine what could happen with way more classes.

Applications

You can use facade in such scenarios:

You need a limited subset of functionalities from a complex system
You want to organize a subsystem into distinct logical layers

Design Patterns: Decorator

Mon, 02 Sep 2024 00:00:00 +0000

The Decorator is a structural design pattern that allows you to add new functionalities to existing objects by wrapping them in new classes.

Problem

When working on a project, a scenario in which you need to add and combine different functionalities can happen. The first approach to solve this problem could be creating a set of subclasses for each functionality, and this could work for a small set of classes. But what if you need to add and combine a hundred different functionalities? The possible combination are really too much. Furthermore, inheritance is static and changing behavior at runtime would be impossible.

Solution

That’s where the decorator pattern comes into play. It lets you wrap an object in a class that implements the same contract as the wrapped object, effectively “decorating” the object with new functionalities. The key advantages of this approach include:

Flexibility: you can add new functionalities without modifying the existing code
Reusability: decorators can be combined in different ways to create complex scenarios
Single responsibility principle: each decorator adds only the set of concerns it needs

Real-World example

In a typical software application, you might have a notification system that sends out alerts, updates, or messages to users. This system could start simple, just sending plain notifications. However, as the application grows, new requirements often emerge, such as:

Multiple Delivery Channels: Users might want to receive notifications via different channels, such as email, SMS, or even push notifications.
Message Formatting: Depending on the target channel or user preference, notifications might need to be formatted differently. For instance, JSON or XML formats might be needed for integrations, or plain text might suffice for others.
Logging and Monitoring: To ensure that notifications are sent correctly and to troubleshoot issues, logging every notification becomes necessary.
Security Features: Adding encryption or signing of messages for security purposes might also become a requirement.
Customizable Behavior: Different types of notifications (e.g., alerts, promotions, reminders) may need specific handling or extra processing.

Building all these features directly into a single notification class would make the class complex, hard to maintain, and less flexible. Moreover, using inheritance to handle these variations would result in an explosion of subclasses, each representing a combination of features, leading to a rigid and tangled class hierarchy.

Java example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97


// Component Interface
interface Notifier {
 void send(String message);
}

// Concrete Component
class BasicNotifier implements Notifier {
 @Override
 public void send(String message) {
 System.out.println("Sending basic notification: " + message);
 }
}

// Decorator Class
abstract class NotifierDecorator implements Notifier {
 protected Notifier wrappedNotifier;

 public NotifierDecorator(Notifier notifier) {
 this.wrappedNotifier = notifier;
 }

 @Override
 public void send(String message) {
 wrappedNotifier.send(message);
 }
}

// Concrete Decorators
class EmailNotifier extends NotifierDecorator {
 public EmailNotifier(Notifier notifier) {
 super(notifier);
 }

 @Override
 public void send(String message) {
 super.send(message);
 System.out.println("Sending email notification: " + message);
 }
}

class SMSNotifier extends NotifierDecorator {
 public SMSNotifier(Notifier notifier) {
 super(notifier);
 }

 @Override
 public void send(String message) {
 super.send(message);
 System.out.println("Sending SMS notification: " + message);
 }
}

class LoggingNotifier extends NotifierDecorator {
 public LoggingNotifier(Notifier notifier) {
 super(notifier);
 }

 @Override
 public void send(String message) {
 super.send(message);
 log(message);
 }

 private void log(String message) {
 System.out.println("Logging notification: " + message);
 }
}

class JsonFormatNotifier extends NotifierDecorator {
 public JsonFormatNotifier(Notifier notifier) {
 super(notifier);
 }

 @Override
 public void send(String message) {
 String jsonMessage = "{ \"message\": \"" + message + "\" }";
 super.send(jsonMessage);
 }
}

// Client code
public class NotificationSystem {
 public static void main(String[] args) {

 Notifier notifier = new BasicNotifier();

 notifier = new EmailNotifier(notifier);

 notifier = new SMSNotifier(notifier);

 notifier = new LoggingNotifier(notifier);

 notifier = new JsonFormatNotifier(notifier);

 notifier.send("Hello, Decorator Pattern!");
 }
}

Applications

Use the decorator pattern when these cases occur:

Stream and I/O Operations: Enhancing streams with buffering, encryption, or compression.
Logging Systems: Adding logging functionality around method calls or operations.
File and Data Processing: Applying filters, transformations, or validations to data streams.
Notification Systems: Extending notifications with email, SMS, logging, and formatting features.
Serialization: Converting objects to formats like JSON, XML, or CSV dynamically.
Dynamic Feature Toggling: Enabling or disabling features at runtime without modifying core code.
Error Handling: Wrapping operations with error handling, retries, or fallbacks.

Design Patterns: Adapter

Fri, 30 Aug 2024 00:00:00 +0000

Adapter is a structural design pattern that enables one component to work with another that has an incompatible interface.

Problem

In software development, you might encounter situations where a component needs to collaborate with another that has a completely incompatible interface. Often, this incompatibility arises because the component is part of a third-party library or legacy code that cannot be modified.

Solution

This is where the Adapter pattern becomes useful. You can create an adapter that converts the data or interface from one format to another, allowing the components to communicate effectively. For instance, you can build an adapter that converts XML data into JSON and passes it to a library that only understands JSON.

In this scenario, the main actors are the adapter and the adaptee. They do not—and cannot—share a common interface.

Real-World example

Imagine you’re developing an application that needs to measure temperature. You have a remote sensor that provides temperature readings in Celsius, but your application uses a library that only works with Fahrenheit. Since you cannot modify the library to accept Celsius, you need a way to convert the temperature readings before passing them to the library.

In this scenario, you can create an adapter that converts the Celsius readings from the sensor into Fahrenheit, allowing your application to work seamlessly with the existing library.

Java example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36


// adaptee
class CelsiusThermometer {
 public double getTemperature() {
 return 25.0; // returns temperature in Celsius
 }
}

// adapter
class TemperatureAdapter implements FahrenheitThermometer {
 private CelsiusThermometer celsiusThermometer;

 public TemperatureAdapter(CelsiusThermometer celsiusThermometer) {
 this.celsiusThermometer = celsiusThermometer;
 }

 @Override
 public double getTemperatureInFahrenheit() {
 double celsius = celsiusThermometer.getTemperature();
 return celsius * 9 / 5 + 32; // Convert to Fahrenheit
 }
}

// client interface
interface FahrenheitThermometer {
 double getTemperatureInFahrenheit();
}

// client code
public class Main {
 public static void main(String[] args) {
 CelsiusThermometer celsiusThermometer = new CelsiusThermometer();
 FahrenheitThermometer fahrenheitThermometer = new TemperatureAdapter(celsiusThermometer);

 System.out.println("Temperature in Fahrenheit: " + fahrenheitThermometer.getTemperatureInFahrenheit());
 }
}

Applications

You can use the Adapter pattern in the following situations:

When you want to reuse legacy subclasses that lack certain functionality, and you cannot modify the superclass.

Extending these subclasses might lead to code duplication and violate clean code principles.
When you need to interact with a third-party library that functions differently from your codebase.

Design Patterns: Proxy

Thu, 29 Aug 2024 00:00:00 +0000

Proxy is a structural pattern that lets you put a placeholder between the clients and a real object.

Problem

Imagine an application where there’s a client that communicates with an object that’s very heavy in terms of resources. You may want to implement lazy loading but it could lead to code duplication. Alternatively, the object might require pre-processing or post-processing.

Solution

This is where the proxy pattern comes into play. With this pattern, the client interacts with the proxy, which then communicates with the real object, potentially performing additional tasks before returning the result to the client.

In this scenario, there are three key components: the client, the proxy, and the real object. Both the proxy and the real object should implement the same interface, ensuring that the client remains unaware of which object it is communicating with.

Real-World example

Imagine you have a remote service that fetches data from a server. Accessing this service might be slow or expensive, so you want to add some logging to see when it’s being accessed. Instead of modifying the service itself, you can use a proxy to handle the logging.

Java example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


// The interface of a remote service
interface DataService {
 String fetchData();
}

// The concrete implementation of a real remote service
class RealDataService implements DataService {
 @Override
 public String fetchData() {
 // Simulate a delay as if fetching data from a remote server
 try {
 Thread.sleep(2000); // 2-second delay
 } catch (InterruptedException e) {
 e.printStackTrace();
 }
 return "Data from remote server";
 }
}



// the concrete implementation of a remote service proxy, with added logging
class DataServiceProxy implements DataService {
 private RealDataService realDataService;

 public DataServiceProxy() {
 this.realDataService = new RealDataService();
 }

 @Override
 public String fetchData() {
 System.out.println("Logging: Fetching data from remote server...");
 String data = realDataService.fetchData();
 System.out.println("Logging: Data fetched successfully.");
 return data;
 }
}

// The client code
public class Main {
 public static void main(String[] args) {
 DataService dataService = new DataServiceProxy();

 // Fetch data using the proxy
 System.out.println("Client: Requesting data...");
 String data = dataService.fetchData();
 System.out.println("Client: Received data -> " + data);
 }
}

Applications

The proxy pattern can be applied in various ways:

Remote Proxy: When the real object is located remotely, and the proxy makes a remote call to fetch it.
Virtual Proxy: When you want to lazily load a resource-intensive object.
Protection Proxy: When you need to perform security checks before interacting with or returning the real object.
Caching Proxy: When you need to cache the real object to avoid fetching it repeatedly.
Logging Proxy: When you need to add logging before or after interacting with the real object.

Tips

It is not always possible to extract a common interface from a pre-existing class, especially if doing so requires altering all client code or if the class belongs to a third-party library. In the first case, consider making the proxy a subclass. In the latter case, consider using the adapter pattern.

Postman + Keycloak – How to automatically get the authentication token

Tue, 20 Aug 2024 00:00:00 +0000

It often happens that you have to test REST services that require authentication, perhaps with keycloak. With Postman you can automatically get the access token before making each REST call. Let’s see how

What is Postman

If you develop backends you will surely know what Postman is, if not (or if you are new to the industry), allow me to introduce it to you:

Postman is (to put it very simply) a platform for building, testing and cataloging APIs. It can be downloaded for free from the official website and also has paid plans for teams and more complex projects, but the free version is fine for us.

One of the most convenient features is the possibility of cataloging all our requests in what are called collections , which are a concept very similar to directories.

Each collection can be configured in its own way and this is exactly what we are going to do to automatically obtain the keycloak authentication token .

Pre-request script

Pre-request scripts are, in fact, JavaScript scripts that are executed before a request. They can be inserted in two different places: within the single request or in the collection; the advantage of doing it in the collection is that in this way all requests within it will automatically execute the script.

We then open our collection and in the Pre-request Script tab we add the following code, obviously being careful to make the appropriate substitutions in the first part with the variables:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


var client_id = "your keycloak client_id";
var client_secret = "your keycloak secret";
var server_url = "keycloak auth url";
var realm = "keycloak realm";
var username = "username";
var password = "password";

var token_endpoint = server_url + "/auth/realms/" + realm + "/protocol/openid-connect/token";

var details = {
 "grant_type" : "password",
 "username": username,
 "password": password
}

var formBody = [];

for (var property in details) {
 var encodedKey = encodeURIComponent(property);
 var encodedValue = encodeURIComponent(details[property]);
 formBody.push(encodedKey + "=" + encodedValue);
}

formBody = formBody.join("&");

pm.sendRequest({
 url: token_endpoint,
 method: 'POST',
 header: {
 'Content-Type': 'application/x-www-form-urlencoded',

 'Authorization' :'Basic ' + btoa(client_id+":"+client_secret)
 },
 body: formBody
}, function(err, response) {
 const jsonResponse = response.json();
 console.log(jsonResponse.access_token);
 pm.collectionVariables.set("access-token", jsonResponse.access_token);
});

Then we open the Authorization tab and set the type field as Bearer Token and the Token field as{{access-token}}

Single request

At this point the last thing to do is to set the individual requests so that they inherit the authorization mode from the collection. To do this we open our request and in the Authorization tab we set the Type field as Inherit auth from parent .

At this point, every time we start the request, Postman will automatically contact the keycloak SSO to obtain the authentication token before making the request itself.

Conclusions

We have seen how to automatically obtain the keycloak authentication token with Postman . Did you already know this method? Do you know any other interesting uses of pre-request scripts?

Goodbye Wordpress, welcome Hugo!

Mon, 19 Aug 2024 00:00:00 +0000

I’ve been looking for a quick and possibly “distraction-free” system to get back to writing on my blog for a while.

WordPress had become slow and unmanageable, and with each update, it got worse and worse (probably my fault, but I neither had the time nor the desire to figure out the cause), so I thought: “What if I try Hugo?”

After all, using WordPress, for what I do, is like using a insert expensive car brand here to go grocery shopping at a discount store: for instance, I don’t need comments on my posts, social media already provides that, and I don’t want to spend too much time managing security, drafts, cache, etc.

EDIT: I added disqus comments, just in case

A static site is perfect for what I need, and that’s where Hugo comes in, which I hope will help me gain in:

Speed and performance
Control over content
Security
Costs

I will definitely do another post in the future to summarize this choice.

Speed and Performance

Even if you try to keep things minimal, with WordPress you still have to add plugins to manage certain aspects, like cache and SEO, and each plugin you add tends to slow down the platform a bit.

Additionally, I’m not sure if it’s an issue with my hosting, Cloudflare, or who knows what, but lately I noticed that my WordPress blog was taking up to 20 seconds to load a simple page, despite having cache and Cloudflare’s CDN.

Hugo, on the other hand, generates static content, which means no database, no processes running at page load, and no backend queries. You open the page, and it’s served to you as static content.

Control over Content

Sure, WordPress is powerful and flexible, but after a while, I noticed I was spending more time managing WordPress itself than creating content, and that’s not good.

With Hugo, I just have to write markdown files to publish on GitHub Pages—nothing more, nothing less.

By the way, I found a way to integrate Obsidian with templates and daily notes, so I can automatically create a markdown template for the day’s post and start from there without having to copy and paste common parts from other files. It couldn’t be more convenient…

Security and Costs

As mentioned earlier, I no longer need a backend or a database, which automatically improves security and reduces costs.

In conclusion, switching from WordPress to Hugo was a decision driven by my need for speed, control, security, and simplicity. WordPress remains an excellent platform for many, but for someone like me who seeks a lighter, more minimalist approach to blogging, Hugo looks like a perfect solution.