Introduction

In the early hours of this morning, I finally hit "Publish" on the Steam store page for my solo project, LOGOMANCY.

LOGOMANCY is a word game that mashes together typing, physics puzzles, and magic. Imagine Suika Game meets Mojipittan (a Japanese word-building classic): you type words, letter blocks drop with physics, and forming valid words triggers spells to clear the board.

It took exactly 10 days from the initial concept to a public Steam page. In that window, I managed to handle graphics, sound, and build a functional vertical slice good enough for a trailer. The secret sauce? A Spec-Driven Development (SDD) cycle powered by a tool I built called specre.

In this post, I want to share how SDD—especially when paired with Godot Engine and AI agents—can supercharge solo game development.

specre on GitHub (Tutorial Included)

What is Spec-Driven Development (SDD)?

If TDD (Test-Driven Development) is about writing tests first to ensure code behaves correctly, SDD (Spec-Driven Development) is the "upper layer." It’s about writing the specification first to clarify what you are building before a single line of logic exists.

Standard design docs often become massive, monolithic files in Google Docs or Confluence that start "rotting" the moment they are written. As implementation progresses, the spec and the code drift apart until the documentation is useless.

SDD solves this by managing specifications in the same lifecycle as your code.

specre: An Atomic Specification Format

specre is a lightweight toolkit designed for SDD. It’s built on five core pillars:

1. Atomic Granularity (One File, One Behavior)
   In specre, one Markdown file describes exactly one behavior. Not a "feature" like "Game Over," but a specific behavior: "When letters connected to the floor exceed the deadline, trigger Game Over and display the UI." This granularity is what makes collaboration with AI agents actually work.

2. Context Window Optimization
   LLM context windows are finite. Passing a 50-page design doc wastes tokens and confuses the agent. Because specre is atomic, the AI only needs to read the spec for the specific behavior it’s currently implementing.

3. Living Specs
   Each card tracks its status (draft → in-development → stable → deprecated) and a last_verified date. This makes "spec rot" visible and actionable.

4. Process Agnostic
   It’s a format convention, not a rigid workflow. It works whether you use TDD, BDD, or just "vibe-based" coding.

5. Tool Agnostic
   It’s just Markdown with YAML Front-matter. No proprietary IDE or SaaS required. Use Git, use your favorite editor, and stay in the flow.

The SDD Cycle in LOGOMANCY

To give you a better idea, here is a simplified version of a real specre card from the project:

---
id: "01KKZD4XXEH1M3AAGKSKZRV23Q"
name: "Display 'New Record' during Game Over if the score is a high score"
status: "stable"
last_verified: "2026-03-18"
---

## Related Files
- `logomancy_godot/src/stage/game_over_score_display.gd`
- `logomancy_godot/tests/unit/stage/test_game_over_score_display.gd`

## Feature Overview
After the score count-up finishes on the Game Over screen:
1. "HIGH SCORE: 000000" slides in from the bottom.
2. If the final score exceeds the previous high score, a "NEW RECORD!" label fades in, centered below the high score.

## Design Intent
By clearly showing the player they’ve improved, we increase the sense of growth and the motivation to "try just one more time."

## Scenarios
### Happy Path: High score update
1. Final score > saved high score.
2. High score is saved to disk.
3. HIGH SCORE line appears with the new value.
4. "NEW RECORD!" text fades in.
...

Two key takeaways here:

• The Subject-Predicate Title: The filename is the behavior.
• The "Intent" Field: This explains the value for the player. If you let an AI write this, it often makes excuses about library limitations. Keeping the "Intent" focused on player value ensures the implementation remains "contractually" sound.

The 4-Phase Workflow

I used Claude Code with a custom SDD workflow:

• Analysis: Search existing cards to understand adjacent behaviors.
• Spec Creation: Write the new behavior as a specre card.
  • Checkpoint: Human reviews the spec.
• Test-First Implementation: Write tests based on the scenarios, then implement the code.
• Maintenance: Update status to stable and commit.

The beauty of this is that the human only needs to review the spec. If the spec is right, the AI can handle the heavy lifting of implementation and testing.

Why Godot is the Perfect Match for SDD

I’ve found that the specre × SDD cycle is particularly effective with Godot Engine for three reasons:

1. GDScript Readability
   GDScript’s Python-like syntax is incredibly concise. When an AI generates code from a specre card, it doesn't waste the context window on C++ boilerplate. You get pure behavior.

2. Scene Tree & Responsibility Segregation
   Godot’s Node system encourages separating concerns. A script like game_over_score_display.gd has exactly one job, which maps 1:1 to a single specre card.

3. GUT (Godot Unit Testing) Integration
   I use the GUT framework. Since specre scenarios are written step-by-step, they translate almost directly into GUT test methods. This mapping makes it nearly impossible for the AI to "hallucinate" incorrect logic.

Note: While GDScript is dynamic, having a suite of tests derived from specs provides the safety net needed for major refactoring.

Lessons from 10 Days of Sprints

The "Project Map" Effect
By categorizing specre cards into domains, the project structure becomes visible:

• letter/ (9 cards): Input, kerning, dictionary validation.
• stage/ (20+ cards): Game loop, physics, level progression.
• magic/ (8 cards): Elemental effects, attraction logic.
• ...and so on.

The number of cards in a directory tells you exactly where the complexity of your game lies.

Lowering the Cost of Specs

The specre README says: "Make specifications so small and so cheap to write that there is no reason to skip them."

Traditional docs fail because they are "expensive." If writing a spec takes 1–2 minutes (with an AI drafting it for you), it’s faster to write the spec than it is to debug a feature you didn't think through.

Conclusion

Reaching a Steam-ready state in 10 days wasn't about "crunching"; it was about clarity of intent.

1. Atomic Specs = Clear instructions for AI.
2. Automated Workflow = Less mental overhead on "what's next."
3. Spec Review > Code Review = Higher decision throughput for the human dev.

If you're interested in the game, please check out the Steam page and add it to your Wishlist!

About the Author

I’m a designer/developer who loves pixel art and efficient systems. You can follow my progress and see my pixel animations on Bluesky.