Most software projects drift. Scope expands, priorities shift, and half the time you finish features you never meant to start. Over the last year, I’ve been experimenting with a workflow that keeps the project laser-focused: combine GitHub Speckit with an AI assistant from the very beginning — before a single line of code is written.
This article walks you through the full soup-to-nuts process so you can replicate it in your own workflow.
Step 1 — Write 5+ User Stories Before Anything Else
Before opening VS Code or generating a single file, start with clarity.
Write at least five user stories that describe what your users actually need.
Template:
As a <type of user>,
I want <the outcome/behavior>,
So that <the value it provides>.
User Stories for a Pet-Supply Website
1. As a pet owner, I want to easily find products for my specific type of pet so that I don’t waste time browsing irrelevant items.
This ensures the site is organized around pet categories (dog, cat, reptile, bird, etc.) so shoppers can find what they need quickly.
2. As a customer, I want clear product descriptions and reviews so I can feel confident I’m buying the right item for my pet.
This ensures product pages have meaningful content, photos, specs, and social proof.
3. As a shopper, I want a simple and secure checkout process so I can complete my purchase without frustration.
This sets expectations for a clean, fast, trustworthy checkout experience.
4. As a returning customer, I want to see my past orders so I can easily reorder food, litter, or other recurring items.
This sets the foundation for user accounts, history, and subscription-like features.
5. As a pet owner, I want personalized product recommendations based on my pet’s needs so I can discover items that help me care for them better.
This covers personalized browsing, recommendations, or tailored landing pages.
Create these first. Everything else flows from them.
Step 2 — Create a New Repository and Open It in VS Code
I’m assuming you’re working on linux or in windows on WSL, and with VSCode. From your terminal:
mkdir my-new-project
cd my-new-project
code .
You now have a clean repository open and ready for Speckit and AI-assisted development.
Step 3 — Install GitHub Speckit
Speckit installs via uv:
sudo apt update
sudo apt install uv
uv tool install speckit
Verify:
speckit --help
Speckit gives your project structure before any code exists — specifications, tasks, a constitution, and more. This will become the “source of truth” the AI must follow.
Step 4 — Add Your User Stories to the Repository
Create a file named:
userstories.md
Paste your stories there.
Why store them in a file?
Because your AI agent and Speckit tools will reference these repeatedly when generating specifications.
Step 5 — Ask Your AI Agent to Generate the Speckit Documents
In Cursor (or your AI IDE), tell your agentic AI the following
Based on
userstories.md, create the necessary Speckit documents to get the project started.
The AI will generate:
- a Speckit constitution
- spec files tied to each user story
- tasks broken down into concrete steps
- initial project scaffolding
You now have a structured project foundation without writing code.
Step 6 — Tell Your AI to Execute the Instructions in start.ai
Here’s what start.ai contains:
Review progress.ai and the speckit files and tell me what we should be working on next.
Continuously update progress.ai as if you were a secretary recording all the decisions we implement.
Make sure we always honor our speckit constitution.
Tell me whenever you think we can mark a spec-kit task complete.
Encourage me to not do work that isn't defined in a speckit task.
Below is why each line matters.
“Review progress.ai and the speckit files and tell me what we should be working on next.”
This gives the AI context.
It ensures the assistant:
- Knows the project’s current state
- Understands outstanding tasks
- Can recommend the next action based on the specs
This prevents random AI-generated detours.
“Continuously update progress.ai as if you were a secretary recording all the decisions we implement.”
progress.ai becomes your living project journal.
It records:
- What decisions were made
- Why they were made
- What tasks were completed
- What trade-offs were accepted
This solves the “AI forgets everything between sessions” problem.
“Make sure we always honor our speckit constitution.”
The constitution defines your project’s rules, including:
- coding standards
- architectural principles
- naming conventions
- testing expectations
- performance guidelines
- design patterns
- dependency philosophy
It is a living document.
You can evolve it as the project grows, but once something is part of the constitution, the AI will enforce it automatically.
This is how you keep your project clean and consistent.
“Tell me whenever you think we can mark a speckit task complete.”
This makes the AI act like a project manager.
It will proactively notify you when:
- acceptance criteria are met
- a task aligns with the spec
- work is good enough to move forward
This prevents tasks from dragging on unnecessarily.
“Encourage me to not do work that isn’t defined in a speckit task.”
This is the anti–scope-creep rule.
You’re telling the AI:
“Don’t let me wander. Keep me inside the defined scope. If something needs to be done, it needs a task definition.”
This eliminates:
- accidental features
- unnecessary refactors
- premature optimization
- coding tangents
The project stays lean and intentional.
Why This Workflow Works
By combining:
- user stories (clarity)
- Speckit (structure)
- AI agent (execution)
- start.ai (rules)
…you create a project environment that is:
- focused
- predictable
- clean
- documented
- spec-driven
- easy to onboard into
Most importantly, you avoid building anything that doesn’t matter, and if something HAS to be done, you’ll create a new task for it.
Leave a Reply