Question was prompted by seeing spec kit have no commits for over a month an no obvious integration with GitHub’s new agents integration.
Every new project (cloud consulting + app dev), I feed in the contract, transcripts of my discovery sessions, my labeled architecture diagram, transcript of the design review discussion and any other artifacts.
First I have to create Epics and stories anyway for the PMO even if I am working on it by myself.
Then I ask ChatGPT what the phases should be, I tweak it , break it down, give it more details, etc
Finally, I ask it to give me unrendered markdown with the details and a checklist and that’s the starting point of my repo.
As I’m using Codex (I never seem to hit limits with my $20 a month plan) and Claude (better at troubleshooting), I tell them to update my document with what’s done, guidance I’ve given it etc.
I treat both of them like junior devs and keep my hands on the wheel and test and verify each phase.
Yes I know I’m fortunate that all of my work is greenfield -> empty repo and empty AWS account that I ask the client for.
Particularly in a brownfield development context, using AI to research issues, gaps, bugs, tech debt, reusable patterns etc. as research files is really useful. I find the sweet spot is ~750 lines for each file. Planning files can max out at 1,500 lines if needed or otherwise broken up into individual phases. You can always ask an LLM to create a starter set of docs to get you going and then maintain as you go along.
For the management nerds, none of this is new. See: Writing Effective Use Cases by Alistair Cockburn and Agile Specification-Driven Development by Ostroff, Makalsky and Paige. The fundamentals remain the same and I'd say become even more important in a brownfield context with a high degree of tech debt or complexity. Greenfield is a different story.
What's important with spec driven development is that the LLMs dramatically reduce the cost of both good documentation and good technical specifications. Once you have a good plan and good references, you can build anything with a high degree of accuracy.
I'd add caution about drift. The more documentation you shove into the context, the worse things can get. You can also create a beautiful and perfect functional spec that becomes a swiss cheese of gaps when you create your technical implementation plan. Always check and use different AI models adversarially to ensure you are actually getting the plan you want. Usually ChatGPT can spot Claude's blind spots, for example. And always test manually.
The questions are usually 80% useless but those 20% often do point me to stuff I have not considered.
Then I edit the markdown manually or discuss some parts with the agent.
"go ahead and implement"
even though u not write it there is still a specification in ur brain when you type the code/prompt right?