Block Builder Game Design

I wanted to take the lessons learned from manually coding a simple web application and apply it to agentic coding. I spend some time designing a new agentic coding framework to stay more organized as a project grows. Some things inside this framework are useful, other parts could get eliminated, and some parts may need to be modified. The idea of this game was not to make something fancy or state of the art, but to show the capabilities of well done planning for execution. My findings remain rather consistent throughout projects I engage in. In my head, the project is very simple, yet the limits of agentic coding run into similar barriers for many of my projects. I expect it to do more than its capable of doing on its own. I don't provide enough input in the front loading of it to build the product exactly as I want. I run through planning because I want to build, but that is a critical error when you get to the end result and the product shape is slightly different than intended. Another major point as a mentor of mine put it, AI is like fashion, its constantly changing so if you aren't adept to change, you will fall behind. This is a key when it comes to developing with AI.

You can trial the game by entering block-builder.terzima.com

Where I Started

I wanted to continue from the completed extremely boring yet foundational work done on guessing game. Guessing game was not meant to be state of the art technology, it was supposed to be a teaching foundation for how a system interacts with each other so that the skills can be translated to agentic coding. Once again, I decided to build an unnecessary layer into my code for the sake of using what was learned and applying it to a different application. I wanted to use the exact same framework. Python backend, javascript frontend with HTML and CSS display. This will likely be my last project in this ultra simple framework. A switch to TSX or JSX will likely make more sense for any future javascript type applications. However, I'm still sticking with the basics that likely was one of the early evolutions after writing in pure HTML in the .com era.

Agentic Coding Framework

I find using the web chat feature of chatGPT to be incredible helpful when ideating and brainstorming. This is a skill I learned prior to any web development. As a one man army building a composites startup who knew nothing about the physical requirements necessary to build composites, I quickly learned the ins and outs of using AI for brainstorming. The cool thing about AI is it doesn't give me the best ideas, but it does push me to find the solutions. In my composites days, I had to learn everything about facility requirements to build. This was not a matter of determining 5 items to buy, but 100s. I needed to build custom pieces, find workbenches, look at CFM requirements (air displacement) for vacuum pumps based on my composite needs. Find the balance between price, performance, and long term needs. It was this constant large scale search on determining the exact pieces I needed to build. Later on I needed to work through the actual research. The research was not shoebox, it was brand new. I had no exact solution on how to do it, and needed help brainstorming ideas. I'd run into road blocks and use it to help me craft solutions. Very often it would tell me to do something and me, being a mechanical engineer, knew what it told me was completely incorrect. This is very important, the AI can have conviction it is right, when it actually is wrong. This is my long intro into the cautious approach we need to take when using it for any form of research and development.

So I started with a simple idea. I remember sitting in my Geometry class in 8th grade playing this Block Dude game (TI 84 Graphing Calculator shoutout). It had very simple game mechanics, you would engage with a block, you can jump, and move around. The goal was to get to a door. I thought to myself, “I remember loving this game when I finished my classwork, it would be cool to make it myself.” So that is exactly what I set out to do. I came into the conversation with the web chat pointing towards a few things, and looking to further define most of it. I did this not in my office space, but on the road back from the gym using voice mode to optimize my working time. I usually start the conversation stating my goal. I want to build a web based game called block builder using a python backend and JS, HTML, CSS frontend. From there, there was a long way to go. We needed to define the physics requirements, the game mechanics, and a lot more. I needed to broker the contract between the frontend and backend. The backend in reality does very little except acts as a database for the frontend to pull and load the levels. Since I wanted a lightweight application, I wanted movement to be discrete rather than continuous. I wanted it to have the capabilities to later be a static webpage with just a frontend so I wouldn't need to pay to host my backend. At the end of all the brainstorming, I switched it to a higher quality model and asked it to summarize everything into an md file to hold everything an AI agent would need to build out the application as we designed it. This included repo layout, what each file is supposed to do, detailed game mechanics, and much much more.

Prior to starting this project, I wanted to try and update my agentic coding framework. I previously had been using the superpowers plugin and realized it caused me to miss a lot of steps. I would rush through brainstorming and my starting point would be too underspecified. I found myself making specs and plans that had a lot of gaps in them. I would try and do too much as once (this might change with Fable now). This yielded lots of spec updates, messy design, and uncertainty if the code I'm producing is even pointing towards the actual goal I have in mind. I also was killing tokens with my design methodology. Even with being on a Codex Max plan, I was getting close to my token limits. Although this is not too much of a concern at this moment, I want my practices to be as token efficient as I can be. If something could be done with a quarter amount of the token spend at the same quality of work, I'm setting myself up for future failure if I don't do that. Tokens right now under unlimited plans are heavily subsidized. As we move into a world of paying at cost, this will heavily transition to understanding the needs of a project and using the right models efficiently to get it done. Keeping an extremely strong perpetual memory so that we aren't reliant on the latest chat session we have with a bot to feel out what needs to be done.

I decided to make my system around the framework as I understand. Use known token efficiency practices, keep a cleaner repo worktree, perform change requests instead of expanding specs and plans willy nilly. So I build a template repo with this in mind and ported it in to start my project. After using it for one project, it needs a lot of work, and I'll also need to look a little more openly at what other people have done. This is my second attempt at making a template for agentic coding and my last template I superceded with superpowers.

Development

It was very simple in the beginning when everything was very defined. I have an intake doc folder and I place that large MD file I have there and create my first chat in the project folder. I copy paste my seeding prompt and let it get to work. After the seeding prompt it makes the first plan for me to read and approve before implementation. For an agentic coder, this project was extremely easy. I had a working prototype extremely fast. Quickly resolved some game mechanics issues. I had a problem where jump when straight up instead of up and one move left or right. It didn't have a change direction mode so I needed it to stay in position if I wanted my character to face the other direction. Gravity also had a starting problem that needed to be resolved. With these things fixed I had a working application. I followed my framework and the prompts I came up with to best get the agent to code as intended. I made some upgrades to the template based on faults I saw on detail. Then, I ran into the real issue: game design.

Game Design

With how crazy good these coding models are at building products, it struggled with game design and I did not realize for a long time. As this was a demo project of agentic coding flow more so than caring about the exact application content; I wanted it to just produce me a 100 working levels so it could feel more complete. Unfortunately for me, I don't really settle for trash design and that was all the AI agent was really capable of out the gate. It had a near impossible time discerning that having extra blocks in a level significantly simplifies the puzzle. It saw more complexity as just adding more blocks. If you specified you wanted exact number of blocks, it would end up with too little making the level physically impossible. There were a lot of issues with how it designed and its because the game design is a lot harder for it to test out. Additionally, part of the goal was to have a solver that would ensure the levels produced were possible. This was another shortcoming as this solver quickly reached limits as I didn't design it as a first class product, but more of an afterthought. I thought it should be relatively simple for a computer to determine if a level is solvable, well the issue with that is the infinite number of solutions it could attempt. Lots of these solutions are all the same taste as wrong. For the speed I was trying to develop it was much easier to test every level myself than to be in solver development. At the end I gave up on solver development. It would take much too long to come up with a universal solver to my game physics with the knowledge that I have.

This did not leave me in the happiest place because I was chasing having a bunch of levels with increasing difficulty and not the patience to design them myself. I actually really enjoyed the game too and play testing it with the levels the AI did come up with. The best conclusion I drew with using AI for game development is it is really good at building broad working mechanics or imitating an exact product, but pure creativity and logic it dies. It can recreate Minecraft very easily, but would struggle with coming up with a chess tactics book completely on its own. AI is extremely good at chess because it has been giving all the tactics, but what happens when you tell AI to play chess without any prior chess knowledge against a grandmaster, it would definitely lose. So my realization was I was doing the same thing. I wanted it to build me complex, solvable, increasingly difficult math puzzles without prior knowledge on what this means for this exact game. A future approach that may be better is to treat the AI as an extremely smart black box that could perhaps generate me the second 100 levels if I gave it all the information necessary. Multiple examples of trace wins per level, trace failures per level, intended final level shape, level starting shape, and exact increasing difficulty per level all hand designed. Realistically, before deciding what it needs, I would probably ask it.

Conclusion

So where does this leave me. I stopped solver development because it was unnecessary and undershaped to work for a variety of levels. I stopped AI game development. I now have the working prototype with 50 levels. 10 of which are broken fully built out. I have some decisions to make. Do I continue working on this, or do I accept my lessons learned and take this thought experiment for what it was.

I ultimately decided that this project is exactly where it needs to be. There are some areas I may decide to go just for the fun of it, but with a world of projects to complete, this one will have to stop here for now. Maybe if I get a clean 50-100 levels ready, I'll publish to the app store so everyone can enjoy the nostalgia of the calculator game I enjoyed as a kid. Right now, you can experience it at block-builder.terzima.com

I learned that having a cleaner agentic coding framework works well, but sometimes feels like a chore when you just want it to continue working on a fix without needing all this paperwork in the middle documenting everything. I also think its a strong reminder to not keep taking the models work for what it says. Many times during my solver product loop, I found myself being told by a model, oh it just needs this to work and I would naively believe it. Then I would find myself in a constant loop with maybe some progress but ultimately not the product I was trying to build. In the future, if I find a core mechanic doesn't work, I would need to slow down and think through what the problem is instead of rushing to keep making more code. I made a batch plan system so individual plans would be broken down into more detail but it could all be one implementation. I ended up not using this at all. This may have been because my system was very simple, but it could be more useful for future work. Now, I will provide you my agent's review of the system I had in place.

Overall Take

The framework was very good at preventing chaos. It made the repo resumable, kept scope explicit, and gave future agents a durable trail of why decisions happened. The strongest part was the separation between Discovery, Spec, Plan, Implementation, and Review. That separation prevented a lot of silent scope drift.

The tradeoff is that the process sometimes became heavier than the work. For concrete app slices, it worked well. For exploratory work like the solver, it became too easy to keep refining specs/plans around an approach that was not proving itself.

What Worked Well

• Specs and plans created durable context. A new agent could read AGENTS.md, repo-map, CURRENT_STATE, and the active spec/plan without needing chat history.
• Modes reduced accidental behavior. “Do not edit specs during implementation” and “open a Change Request” protected the project from quiet requirement changes.
• Human approval classes were useful. A2/A3 made it clear when human judgment or external action actually mattered.
• Commits were meaningful checkpoints. The commit history tells a pretty clear story of scaffold, gameplay, levels, solver attempts, static release, and CI fixes.
• Tests and checks were tied to plans. This improved confidence and made work less vibes-based.
• Skills helped when they were specific. Controlled planning docs, systematic debugging, verification-before-completion, and TDD all added real value.
• The framework handled handoff well. CURRENT_STATE.md and handoff docs reduced “where were we?” friction.

Shortcomings

• CURRENT_STATE.md became part dashboard, part history log, part implementation notebook. That made it useful but also noisy.
• The solver work exposed a weakness: formal process does not guarantee the approach is right. We documented and planned several solver strategies, but the core algorithmic direction was still shaky.
• Change Requests were sometimes too expensive for exploratory uncertainty. They are excellent for controlled product work, but less ideal when the right answer is “we need a spike, and we may throw it away.”
• Planning could become self-reinforcing. Once language entered the spec/plan, later work tended to orbit it, even after evidence suggested the framing was wrong.
• PRs became large because the branch accumulated many slices. That made GitHub review, CI, and deployment harder than they needed to be.
• Local policy hooks were useful but sometimes overzealous, like flagging .env.example.
• Deployment assumptions were under-tested until late. The Vercel setup showed that “local static export works” is not the same as “hosted deployment is configured correctly.”
• Skills occasionally added friction. Brainstorming's full design-doc path is too much for small discovery questions unless intentionally scoped down.

What I'd Improve Next Time

• Keep CURRENT_STATE.md shorter. Use it as a dashboard only: active objective, active docs, current status, blockers, next action. Move history to worklogs.
• Add an explicit “Spike” mode. For uncertain research, set a time/attempt budget, expected evidence, and kill criteria before writing full specs.
• Split experimental tooling from product delivery. The solver should have lived in a separate exploratory track with clearer success/failure gates.
• Keep PRs smaller. Merge scaffold, gameplay, levels, static release, and CI fixes as separate review units.
• Add a “deployment dry-run” checklist earlier. For Vercel, that means package metadata, lockfile, build command, output directory, and a hosted-preview expectation.
• Make CI policies testable from day one. The .env.example false positive should have had a tiny regression test earlier.
• Use docs as contracts, not transcripts. The best docs constrained implementation; the weakest docs preserved too much journey.
• Prefer one active spec/plan at a time. Multiple historical active-looking docs made state harder to reason about.
• Add sunset criteria for failed approaches. Example: “If solver cannot solve N benchmark levels within X attempts, stop improving solver and switch strategy.”

My Bottom Line

The framework is strong for controlled agentic development. It shines when the task is known, bounded, and testable. It is weaker when the task is research-heavy or algorithmically uncertain.

For the next project, I would absolutely reuse the mode system, specs/plans, approval classes, commits, and verification discipline. I would make the process lighter, add a real spike mode, keep status docs leaner, and avoid letting exploratory failures accumulate into huge formal plans.

With this in mind, I have a lot of work to do with improving my structure for development, but this is all part of the learning process. As I mentioned before, I am not the first to do this, so future work should always look at what the best of open source provides me instead of being locked into my developed system.