AI Workflow
DevSpec is built around a single, repeatable loop: you describe work, your AI agent implements it, your pipeline ships it, and DevSpec tells you the moment it is live and ready to test. Connecting a hosting platform is what closes that loop — without it, DevSpec can track everything up to the push, but not whether your changes actually made it to production.
This page walks through each stage of that lifecycle so you can see how the pieces fit together.
The lifecycle at a glance
📊 Diagram coming soon. A visual map of the AI workflow lifecycle will live here. For now, the stages below describe the full end-to-end flow.
The loop moves through six stages:
Action Item → Agent implementation → Branch push → CI/CD deploy → DevSpec notification → Verification
Each stage hands off cleanly to the next, so work flows from an idea in a conversation all the way to a verified change in your product without you having to babysit it.
1. Action Item
Everything starts with an action item — a single, well-scoped unit of work. Create it in a session or directly, then make a current explicit implementation request naming that item. A canonical conversation request must be server-authorized for an exact owner/delegated target.
2. Agent implementation
Your coding agent connects over MCP, calls reserve_work_items for the explicitly requested ids, then claim_work_item one at a time and implements in an isolated worktree. It reads project context, runs your checks, and records what it did. Internal reservation records coordinate claims; they are not work delivery. Controls and explicit owner-scoped automation runs remain separate.
3. Branch push
Once the work is implemented, the agent commits with a DevSpec tracking tag and pushes the branch to your repository — typically a dedicated deployment branch you are comfortable deploying from automatically.
4. CI/CD deploy
Your hosting platform (Vercel, Netlify, Coolify, GitHub Actions, and others) detects the push and deploys automatically. This is the stage that connecting a hosted deployment target unlocks — it is how DevSpec learns that a deploy started, succeeded, or failed.
5. DevSpec notification
When the deployment webhook fires, DevSpec matches it back to the action item that produced the change. The moment the work is actually live, DevSpec surfaces it to your team as ready to test — and if the deploy failed, it flags that too, so no one wastes time testing work that never shipped.
6. Verification
Verification records acceptance-criterion evidence through the configured verification surfaces. Lifecycle promotion and completion authority come from the served devspec://product/implementation-contract and the state returned by DevSpec; this guide does not hardcode a separate completion route.
Why connecting a hosting platform matters
Stages 1 through 3 work with just your repository connected. But the deploy, notification, and verification stages all depend on DevSpec knowing when your CI/CD pipeline ships. Connecting a hosting platform is what turns DevSpec from "tracks the work" into "tells you exactly when it is live and ready to test" — closing the loop on the whole AI workflow.