Disclaimer: The opinions expressed herein are my own personal opinions and do not represent my current or past employers’ view in any way.

I was just chatting with one of my former managers back from the days when I lived in Austria. He was telling me how shocked he was with the capabilities of today’s AI coding agents and how he built an infrastructure project within days, something that would take a team many months in the past. The most interesting part? He did it entirely by writing specifications instead of code, letting the agents work through the details.

I bet you too no longer write code with bare hands but rather get it produced by your agents. I think we are past that point where we were discussing if code is written by AI. The question now is how AI does it and what are the working workflows. For instance, how does the next agent pick up the work? If you need to do another coding session, how do you ensure you are not changing the original design decisions?

We all know about AGENTS.md, CLAUDE.md, and README.md files. They attempt to store key project guidance so an agent has a good baseline when it starts. But oftentimes, a static markdown file just isn’t enough. I was looking into what’s available in the open-source world to solve this context problem, which led me to try out github’s spec-kit.

Without too much of introductory nonsense, here it is: https://github.com/github/spec-kit . Creators say this is “An open source toolkit for building high-quality software with any AI coding agent — a ready-to-use spec-driven process (or bring your own), endlessly extensible, community-driven, and built for your whole organization.“

In this post I’m just giving it a go on one of my personal projects and sharing how it goes. I have this personal minimalistic coding harness project: https://github.com/andriybuday/ii/ and now I’m going to add spec-kit into it and then have a few different model providers implement things and see how it goes.

Warning: this might be somewhat Inception movie style coding, because I will use a well known harness to improve my harness, so my harness can improve itself.

Step 1: Setting Up

One of the things that I had to re-learn and bend my mind around was that I no longer try to be correct or know how certain commands work but instead learn to communicate with agents. For example, the guide might say “uv tool install …” I might not have “uv” tool installed locally. I don’t care, I don’t actually try to run this command myself, but instead chat with my agent to install the stuff for me, and if it gets stuck it would usually find a way to unstuck itself. This really bends my mind, because previously I would look up ways to solve my problems on StackOverflow and google them, but now I just can entrust the agent to go through this process a lot quicker.

Step 2: Constitution

After you have the spec-kit installed and initialized for your agent, you will have commands like /speckit-* available. I started with /speckit-constitution. What’s awesome about this was that agent realized that in a way my project already specified bits and pieces of what’s considered constitution in “AGENTS.md” file, so it just pulled relevant info. This ended up being the commit for the constitution: https://github.com/andriybuday/ii/compare/docs/speckit-constitution?expand=1

Step 3: Work with it

The way of working through speckit seems to be through the order of these operations, roughly: specify -> clarify -> plan -> tasks -> implement (copied over from claude description):

• /speckit-specify Describe the feature in plain language. It creates specs/NNN-short-name/spec.md — user stories, functional requirements, edge cases — and a feature branch. No code yet, no implementation details, just what and why. /speckit-specify Add OpenAI as a second LLM provider, selectable via II_PROVIDER
• /speckit-clarify (optional but recommended) Asks up to 5 targeted questions about ambiguities in the spec and encodes your answers back into it. Worth running before planning if the spec has any judgment calls — like exactly how provider selection should behave.
• /speckit-plan Turns the spec into plan.md — architecture/design decisions, file-level approach, contracts. This is where your constitution actually gets enforced: the plan template checks proposed design against .specify/memory/constitution.md, so if a plan would blow past the ~100-line core-loop budget or add per-provider branching instead of a common abstraction, it
  should get flagged here rather than during implementation.
• /speckit-tasks Breaks plan.md into tasks.md — a dependency-ordered, checkbox task list. This is the actual to-do list /speckit-implement executes.
• /speckit-analyze (optional) Cross-checks spec.md / plan.md / tasks.md for consistency gaps before you start burning implementation time. Non-destructive, just a report.
• /speckit-implement Works through tasks.md top to bottom, executing and checking off tasks.

Step 4: Enhance ii with speckit: /speckit-specify

I know this is getting inception movie style next level, but why not. So I gave claude this prompt:

❯ /speckit-specify I would like to add skill loading capability. We want to be able to load a skill like “speckit-specify” and then have command appear in the harness like /speckit-specify. If there is industry agent agnostic way of doing so, let’s make that priority, if it has to be agent specific we can use “.ii” folder and then “skills” subfolder. We should also allow to load “.claude/skills” so if someone used claude we should be able to load those skills as well.

The above has done a bunch of stuff locally and then suggested running /scpeckit-clarify, which I think is cool, as this is something that asks you questions back. For example, it asked me how to handle name conflicts in skills and built-in commands, if auto-discovery should be implemented, and how skills should be processed in history.
The cool thing it did in the end was that it ran all of my specifications against the “constitution” and checked if there are any contradictions with it and if not if anything has to be resolved.

Step 5: /speckit-plan and /speckit-tasks and /speckit-analyse

Now I got to a stage to actually ask it to generate agent agnostic plan and then tasks. Your agent may reply with this:
No constitution violations, so the Complexity Tracking table is empty. Next step: /speckit-tasks to break this into a dependency-ordered task list.

Analysis phase gives bunch of tables and info, like # of requirements, # of tasks, constitution compliance, risks, etc.

Step 6: Benefit and use from within ii itself

So, now that this is in place and I can have skill loading inside of ii, let me give it a try:

And guess what? At one point I got this dreaded message:
ii> /speckit-plan

API Error: 400 {“type”:”error”,”error”:{“type”:”invalid_request_error”,”message”:”Your credit balance is too low to access the Anthropic API. Please go to Plans & Billing to upgrade or purchase credits.”},”request_id”:”req_011CeZikY3neVWx9ejmT7sui”}

So that was perfect time to switch to another LLM, but a bummer is that my ii harness doesn’t yet support non-anthropic models. So I pulled musecode to finish the specification. In case you don’t know MuseCode, that’s Meta’s coding harness. MuseCode immediately loaded the speckit commands and picked up exactly where Claude left off:

It took me a few iterations to get the proper implementation in place, which made me wonder if I underspecified my specs. The way I understand speckit is that some level of ambiguity is allowed in the specification, letting the LLM fill in the details. However, I was probably too loose in how I specified the UX. Maybe UX is the one area that still needs explicit human input. After all, an AI isn’t human and doesn’t know what it actually feels like to ‘experience’ an interface. Either way, I eventually got autocomplete working similarly to how it works in most coding harnesses:

Conclusion

In this post I tried out github’s speckit via claude code, muse code, and ii (my tiny coding harness). This may sound cliche, but you know how people say that punch-cards coding switched to primitive coding languages, like fortran/assembler, which switched to higher level and so on? Well, it seems we are now switching to another higher level, which is something in the realm of specification for your product, something that is plain English, but just structured nicely. Both my former manager and I left the call with open question: how all of this is going to affect the jobs and future of software engineering. We don’t have clear answers, nobody has. But learning how to write these structured specs seems like one of the ways to prepare for it.