DEV Community: rosidotidev

BMAD Method (Part 1): Spec-Driven Development Where the Human Stays in Control

rosidotidev — Sun, 01 Nov 2026 13:17:58 +0000

As a software architect and senior software engineer, I keep watching the same change happen in the way we build software. In the first series I wrote about GitHub Spec Kit, and I stayed on one idea that I still think matters most: spec-driven development (SDD). Write the intent first, make it explicit, let the agent build against it, then check the result against what was written.

That idea does not depend on a framework. Spec Kit is one way to apply it, BMAD Method is another, and a markdown file in your repo is a third. In this series I look at BMAD Method, and in this first article I stay on the concepts and the commands. I do not show a finished result yet.

My angle is the same as before: not how fast an agent writes code, but who decides what gets built and who answers for what is produced. I think this is the question the industry is starting to ask. Anthropic has published a Claude Academy course, The AI-native SDLC playbook, which asks teams to capture the intent in a version-controlled file and to keep a person in charge at the approval gates. BMAD has been moving in that direction for a while. This is a personal view, not a verdict.

What Is Spec-Driven Development?

Let's start from the problem. Many developers have had the same experience with an AI coding tool. The agent writes code quickly, the code often runs, and yet nobody on the team can say why it was written that way. Two sessions later the intent is gone, buried in a chat history, and the next change starts from a guess.

I call this vibe coding. I do not think the problem is the model. The problem is where the context lives. If the intent exists only in a prompt, it disappears when the session ends. If it exists in a document that the agent reads and the human reviews, the team can inspect it, change it, and keep it.

SDD, for me, comes down to four points:

The intent is written down before the code. In a file, not in a chat.
The agent works inside that intent. It does not reinterpret it silently.
The human approves the intent and judges the result. The agent does not own the definition of done.
The spec is versioned with the code. When the intent changes, the change is visible.

As in the first article, I would say the rigor of the spec can vary (spec-first, spec-anchored, spec-as-source), and these four points hold at every level.

Mental Model: the framework is a way to apply the idea at scale, not the idea itself.

BMAD in a Nutshell

BMAD stands for Breakthrough Method of Agile AI-Driven Development. It maps familiar roles (analyst, product manager, UX designer, architect, developer) onto AI agents, and it keeps the work in documents that the agents read and the humans review.

Two ideas matter most for me. The first is that each document has one owner and one writing skill. The Product Requirements Document (PRD) is the source of the product definition, and nothing else claims to define it. The planning docs say that documents are "contracts between people first and input to the skills second". The second idea is a rule: nothing downstream reinterprets the PRD. If a story needs an answer the PRD does not have, the answer goes into the PRD first, and the derived documents are regenerated. This is the whole point of the design.

The other thing BMAD gives you is more than one path. The first decision is about size, not tools. A change of roughly 500 lines, across a few files, fits one build session. If the intent is already well defined, you hand it to a build, or to the epics and stories skill when the work is bigger. If it is not, you use the analysis skills first, in any order, until it is. The planning skills write the requirements down; they do not decide what you want.

Trivial, you review it yourself:   edit directly, no process
One session (about 500 lines):     intent -> /bmad-build -> result
Epic-sized:                        intent -> brief, PRD, UX, architecture, epics and stories -> one /bmad-build per story -> retrospective
Project-sized:                     several epics, shared decisions first, then the epic path for each

The skills are grouped by phase: Analysis (optional, any order), Planning (PRD and UX), Solutioning (architecture, epics and stories, sprint status) and Build (one story at a time). One note: the version I have installed (6.12.4) labels its skills only plan and ship, so the four names are the grouping of the planning guide, not a label you will see in the tool.

Mental Model: size the process to the work, and make sure the intent is clear before anything is built.

Why It Is Built This Way

The BMAD docs describe what each piece is and how to use it. They say little about why it is built this way, so part of what follows is my reading, and I mark it as such.

Documents carry the whole picture across sessions. The planning guide says that the PRD, the architecture and each ticket's requirements "exist so later sessions can still see the whole", and it warns that "Dividing work can lose information". That is the trade: the work is cut into one-session units, and the documents keep the pieces from drifting apart. Each run starts in a fresh chat for a reason the build docs give: "Reusing a session from another workflow can mix contexts and confuse the run."
Shared decisions are written once, where they are shared. The stated purpose of the architecture step is: "Make the technical decisions that keep separately built parts consistent." I think this is why the architecture stays short: it records what several builders must follow and leaves the rest to each story. The docs do not say "only", so this part is my reading.
Human attention goes where a mistake gets copied. The build docs say that early stories "often settle the architecture, initial project structure, and repeated patterns", and that these decisions deserve human attention "before automating repetitions of them". I think the same logic explains the gates on the PRD and the architecture: an error there is not fixed once, it is built into every story.

One thing I did not find: a reason for splitting the work across roles in the first place. The closest statement is about people, not agents: "You make the calls, so you understand what you ship." I would not claim more than that.

Mental Model: the documents are the memory, and the human gates sit where a mistake gets copied.

Setting Up

The version I use is BMAD 6.12.4, the stable one. It installs from the project directory with one command:

npx bmad-method install

The installer writes the skills for the coding tool I choose (Claude Code in my case) into .claude/skills/, and a _bmad/ folder with the configuration. The skills are typed in the slash form (/bmad-build, /bmad-prd), and that is the form I use here. When I am unsure where to start, there is /bmad-help. The online docs now describe a newer v7 preview with some different names. I follow the version I use, and I say where the docs differ.

A Simple Example: a Todo List

I use the same todo list as in the Spec Kit series, so the two approaches can be compared on the same problem. There are two situations, and they lead to two different paths. In both I show the commands and not the results.

Path One: Adding a Flag to a Todo List I Already Have

Suppose the todo list is already implemented, with add, edit and delete. I want to add a "done" flag to each item and toggle it from the list view. The change is small, clear and low risk, and it fits in one session. For this path I need only one skill: bmad-build. It takes an intent, investigates, plans, implements, reviews, and fixes what it finds.

Below is the flow from the build documentation (docs.bmad-method.org/build/build-a-change/), redrawn in my own style. The main line runs from top to bottom: intent, clarify, plan, implement, review, result. Dashed lines show where a human takes part, and the loops are the interesting part.

Step 1: Size the Work and Start Fresh (one session, no shared context):

/bmad-build Add a "done" flag to each todo item, toggle it from the list view, and keep the state after reload.

The change touches a few files and far fewer than 500 lines, so bmad-build is the right tool. A trivial change that I will review myself does not need the process at all. I run the command in a new chat, because reusing a session from another workflow can mix contexts, and that is where wrong assumptions come from. The intent can be rough, and it can also be an issue link or a story (/bmad-build story 2.3, which I use in Path Two). I prefer to write it in full. A rough intent is allowed, but it moves the cost to the questions the agent asks later.

Step 2: Clarify and Plan (the human answers, the plan is the optional gate):

The agent reads the codebase and any planning documents. Anything the repository cannot settle becomes an open question, and I answer carefully, because wrong answers here are the costliest to fix later. In the todo case I would expect a question about whether done items stay in the list. That is my decision, not the agent's.

Then the agent checks three facts: intent gaps, irreversible actions, and the footprint of the change. If all three are clean, it takes the light path: a minimal plan and the implementation in the same session. If anything is flagged, it writes a full plan and waits for my approval. Fixing the plan is cheaper than fixing the code.

Step 3: Implement and Review (the agent's own gates):

The agent implements, checks the change against the acceptance criteria it recorded, and reviews its own work with three lenses: a Blind Hunter (problems without the bias of the implementation context), an Edge Cases Hunter (forgotten corner cases) and a Verification Gap Finder (do the tests really cover the change?). The review ends in a triage, and each outcome has a destination:

Patch. The issue belongs to this change, so it is fixed and the review runs again.
Bad plan. The code is wrong because the plan was weak, so the flow returns to Plan.
Intent gap. The plan is wrong because the goal was wrong, so it returns to Clarify.
Void. The change is rejected.
Defer. An unrelated pre-existing issue goes to deferred-work.md.

I like that the loops are explicit. A review that can only say fixed or not fixed hides the cause of the problem, and here the cause has to be named.

Step 4: Present and Review the Result (the human gate):

The agent gives a short summary and commits locally. I run the walkthrough or skim the diff, tell the agent what to fix, and when I am satisfied I ask it to push the commit and open the PR. Two things can still go wrong after this.

If the change turns out to be wrong after I accepted it. If I pushed the commit and then find a problem, the way back is the ordinary one in git, so the history stays intact:

git revert HEAD

This creates a new commit that cancels exactly what the agent added. I do not patch the problem inside the old chat. I start a fresh chat and run /bmad-build again, with the intent rewritten to say what I missed (for instance: "the flag must survive a page reload"). The intent is the thing I correct, and the code follows it. This is a git practice that fits the flow, not a step that BMAD runs for me.

What the agent chose not to fix. An unrelated problem is not fixed silently and not dropped: it is written into deferred-work.md, with the story it came from, a one-line summary and the evidence. I read this file after every run. A backlog nobody reads is where problems go to be forgotten, so for each entry I decide whether it is a new change, a note to keep, or something to drop on purpose.

Path Two: Writing a Todo List From Scratch

Now suppose there is no todo list yet. I want a todo app with due dates and filters, kept in the browser. This is a body of work with several build units, so one /bmad-build is not enough. The planning documents become the contract, and each step reads the files that the previous step wrote. Every step runs in a fresh chat (/clear first). I show the real commands. What each step reads and writes is in one table, a few sections below.

Step 1: Brainstorm (optional, what and why, no technology):

/bmad-brainstorming A simple todo list web app. Explore features, UX ideas and what must stay out of version 1.

A coach runs the session in the stance I choose: facilitator, creative partner, or ideate for me. My decisions are kept apart from the ideas the coach offered. If the idea is still half-formed, /bmad-forge-idea pressure-tests it and /bmad-deep-recon researches a competitor or a technology. A personal view, not a verdict: if I cannot write the intent in three sentences after this step, I am not ready for a PRD.

Step 2: Product Brief (what and why, in one page):

/bmad-product-brief Create a product brief for a simple todo list web app. Use the brainstorming result at <intent path> as the main input and treat its "Decisions" table as settled.

The skill asks whether I want to create, update or validate, and whether I take the Fast path or the Coaching path. Every planning skill has the same three intents, and I run validate in a fresh chat before moving on (/bmad-product-brief validate the brief at <brief path>).

Step 3: PRD (what to build, not how):

/bmad-prd Create the PRD for the todo list using the brief at <brief path> and the brainstorming intent at <intent path>. Features in order: (F0) foundations and storage; (F1) the list: add, tick, delete; (F2) due dates, overdue sign and filters.

The PRD is the source of the product definition, and every later document derives from it. Functional requirements get stable ids (FR-1, FR-2, ...), and what the skill inferred is tagged [ASSUMPTION] so that I can correct it. Edits belong in the PRD, not in the stories (/bmad-prd update the PRD at <prd path>: <what to change>), so the derived documents can be generated again.

Step 4: UX (optional, how it looks and how it behaves):

/bmad-ux Create the UX documents for the todo list from the PRD at <prd path>. Simple, calm, keyboard friendly, one screen.

The skill captures my vision and does not impose its own. It writes two peer documents: DESIGN.md (how it looks) and EXPERIENCE.md (how it behaves). I would skip it only if I accept designing those details later, during the builds.

Step 5: Architecture (how, only where two builders could disagree):

/bmad-architecture Create the architecture for the todo list from the PRD at <prd path>, DESIGN.md and EXPERIENCE.md at <ux folder>. Decide: front-end framework, where tasks are stored, the task data model, the testing strategy.

The output is not a full technical document. It is a short architecture spine that records only the decisions that two units, built independently, could make in incompatible ways. A decision gets a stable id (AD-1, AD-2, ...) only if it is non-obvious and a real trade-off. This is where my review matters most, because a wrong shared decision spreads to every story.

Step 6: Epics and Stories (work cut by user value):

/bmad-create-epics-and-stories Create the epics and stories list from the PRD, UX documents and architecture. Create exactly three epics, in this order: Epic 1 Foundations; Epic 2 Task list; Epic 3 Due dates and filters. Every story needs acceptance criteria.

Every functional requirement is mapped to an epic, and every story has acceptance criteria in the Given, When, Then form and fits one build session. I check the epic and story numbers, because every build command from now on uses them.

Step 7: Readiness Check (the gate before the build):

/bmad-sprint-planning check implementation readiness

The skill reads the planning documents the way a skeptic reads a handoff, and answers PASS, CONCERNS or FAIL. On CONCERNS or FAIL I fix the planning documents and run the check again. If something major changes later, there is /bmad-correct-course <description of the change>.

Step 8: Sprint Status (one file that says where every story is):

/bmad-sprint-planning run sprint planning

It writes sprint-status.yaml, with every epic, story and retrospective as a key. All stories start as backlog, then move to ready-for-dev, in-progress, review and done.

Step 9: Build One Story at a Time (the implementation phase):

/bmad-build story 1.1

/bmad-build does not pick the next story by itself: I give it the number each time, one story per fresh chat, in order. Each run follows the flow of Path One. The story moves to review in the sprint status, and the agent does not close its own work: I review, and I decide when a story is done. An optional extra check, in a fresh context, is /bmad-code-review. I would not use the unattended build skill for the first stories, because they set the patterns for the rest.

Step 10: Retrospective (close the epic):

/bmad-retrospective 1

The skill reads the evidence the epic left (the specs, the diff, the commits, the sprint status) and judges the epic against the criteria it set for itself. Every finding carries a source, and a claim with no source is dropped. A failing epic never closes as quietly accepted.

Looking at these ten steps together, the pattern is always the same. Each skill writes one document or one piece of code. Each document has one writer. Each gate has a human decision. The agent works inside the boundaries that the earlier documents set.

What BMAD Writes to Disk

What makes the process work is the files, because each step reads what the previous one wrote. BMAD keeps two folders at the project root, and they have different jobs.

_bmad/ is the metadata. Installed version and modules, the skill list, the configuration, the team overrides, and the script that writes the logs. It holds no deliverable.
_bmad-output/ is the handoffs. Every document a skill produces, in one run folder per document, plus the sprint status and the build specs.

Here is the handoff chain in one table: what each step reads, and what it writes for the next one.

Step	Reads	Writes
Brainstorm	nothing (the idea is in the command)	`brainstorm-intent.md`
Brief	`brainstorm-intent.md`	`brief.md`, `addendum.md`
PRD	brief, addendum, intent	`prd.md`
UX	`prd.md`	`DESIGN.md`, `EXPERIENCE.md`
Architecture	PRD, `DESIGN.md`, `EXPERIENCE.md`	`ARCHITECTURE-SPINE.md`, plus `SOLUTION-DESIGN.md` in coaching mode
Epics and stories	PRD, UX documents, spine	`epics.md`
Readiness check	`epics.md` and the documents behind it	PASS, CONCERNS or FAIL
Sprint status	`epics.md`	`sprint-status.yaml`
Build, per story	the story, the spine, UX documents for UI work	code, `spec-N-M-*.md`, `epic-N-context.md`, `deferred-work.md`, status moved to `review`
Retrospective	the specs of the epic, git history, `sprint-status.yaml`	the retrospective and its decision

Each run folder also holds a .memlog.md. It is the memory of that document: an append-only log with one line per decision, assumption or change, written by a script and never edited by hand. This is the shape of one (the lines are illustrative, for the todo PRD):

- (decision) Working mode: Fast path, entry point Vision + Features
- (assumption) Selected filter survives a reload
- (event) PRD finalized

Three things follow from this design:

A fresh chat can continue. A step reads files, not the history of the previous chat, so I can close the session and resume tomorrow.
Every decision has a trace. The memlog says what was decided and why, and which assumptions are still open.
A change starts at the source. If a story needs an answer the PRD does not have, the answer goes into the PRD first, and the later steps run again.

BMAD keeps one memlog per document, not one for all the sessions. If I want the view across the steps, I would keep a small file for it.

What the Method Gives You

Context that survives sessions. Decisions live in files, so a new chat starts from documents, not from memory.
Version control for decisions. The PRD, the architecture and the stories live in git, next to the code.
Predictability. I know the likely end state of a session, because it was written before the session started.
Several sizes of process. A one-session change and a whole product use the same vocabulary with very different amounts of ceremony.

The other side, with the same sincerity as before:

What the Method Does Not Give You

Correctness by default. An agent can implement the wrong thing precisely. A good spec reduces guessing, it does not remove it.
Zero overhead. For a typo or a CSS tweak, even the short path is too much.
Freedom from handoff problems. Agents with different roles can still make conflicting assumptions. The documents make the conflict visible, but a human has to resolve it.
Room in the context window. Specs, architecture and stories consume context, so they must stay concise.
A replacement for judgment. The framework tells you when to stop and ask. It does not tell you what the product should be.

The Role of the Human

In every path, the agent produces a lot, and the human is responsible for what is accepted. On the short path I answer the open questions, approve the plan when it is flagged, and review the result. On the long path there are moments where a human decision blocks the next step. These are the ones I meet in the version I use (the planning guide of the online docs lists five sign-off points for the newer version):

Moment	What I judge	What it blocks
Brainstorm intent	Which directions survive, the Decisions table	The brief and the PRD
PRD validation	The findings report	UX and architecture
Architecture validation	The decisions that are mine, the corrections	Epics and stories
Readiness check	PASS, CONCERNS or FAIL	Sprint planning and the first build
Plan approval and story review	The plan when flagged, the diff, `deferred-work.md`	Marking the story done
Retrospective decision	Did the epic meet its criteria	The next epic

Each of these leaves a written trace, in a memlog, a report or a status file. In a regulated company that is the audit trail, and in a small team it is the best record of why a decision was made. I think this is the clearest statement of responsibility I have seen in an agent workflow.

Mental Model: bounded autonomy, not full automation.

Takeaways

A spec is a contract between people first, and input for agents second. If the intent is not clear to the people involved, no agent will make it clear for them.
Size comes first. One session, one epic and one project need different amounts of process, and choosing between them is my call.
The loops in the build flow are the point. A bad plan, an intent gap and a deferred problem each go back to the layer that caused them, so a wrong decision is not buried in the code.
The human approves the plan and judges the result, and the agent works inside both. The responsibility for what is produced does not move. What changes is where I spend my attention: on the intent, the gates and the diff.
The handoff between steps is a file, not a chat. That is what lets a fresh session continue, and what leaves a written trace of every decision.

What Comes Next

BMAD is one answer to a question that many people are asking at the same time: how do we give an agent enough written intent to work well, and keep a human in charge of what comes out? I do not think it is the only answer, and I would not want this series to be only about one tool.

In the next article I want to make the example more concrete. I also want to keep the radar on, because spec-driven development is moving fast: what the major players are doing about it, how the SDLC changes when an agent does part of the work, and which other approaches are worth exploring. Two that I already have on my list are OpenSpec by Fission-AI, and the agent-skills collection by Addy Osmani. I have not formed a view on them yet, and I would rather look before I write about them.

There will be at least one more article after this one. Stay tuned.

What is your experience with planning documents and agents? Do you keep the spec in the repo, in a tracker, or in the chat? I would love to read your experience in the comments.

Agents-skill

rosidotidev — Tue, 27 Oct 2026 05:51:03 +0000

Spec-Driven Development in Practice: Porting RoomBook from Spring Boot to NestJS

rosidotidev — Sun, 25 Oct 2026 10:09:23 +0000

In the second article I built RoomBook with Spec Kit: an Angular frontend, a Spring Boot backend, SQLite, and five feature cycles, each with its own spec, plan and tasks. I finished with a question: can the backend be replaced by another stack while the contract, the tests and the frontend stay fixed?

This article is the answer I got, and the answer took more than one prompt. The new backend is written in NestJS on Node.js with TypeScript, in backend-nest/, next to the old one. Getting there meant a constitution amendment, a specification, a plan, four implementation phases with checkpoints, an amendment in the middle of the work, and a parity check against the original service. Everything ran on the same repository and under the same constitution, with one new feature folder for the migration.

The toolkit is GitHub Spec Kit, and the whole project, with the specifications from the first two articles and the migration described here, is in my room_book repository, under specs/. As before, this is a personal account, and I quote the command outputs where they matter.

The Goal, Stated as Constraints

A migration has an easy version of the goal, "rewrite the backend in the new stack", and a hard version, "users must not notice". I took the hard one and wrote it down as constraints:

The HTTP contract stays the one in openapi.yaml, byte for byte.
The business rules stay the ones already specified: no overlaps, opening hours, 15-minute slots, a 4-hour maximum, no bookings in the past, cancellation up to one hour before the start, and disabled rooms not bookable.
Errors keep the application/problem+json format and the same status codes.
The data already in the SQLite file must still be readable.
The Angular frontend is not modified.

Most of the work came from taking these lines seriously. If the frontend changes, the migration has failed, even when the new backend works perfectly.

Two Decisions Before the First Command

Two decisions were written down before the first Spec Kit command, so that anyone running the process could see them.

The first is about data. Two backends must never write to the same SQLite file at the same time, so the new service works on a copy of roombook.db. The original file stays where it is, untouched, and I keep its SHA-256 hash to prove it.

The second is about the cutover. Removing backend/ and renaming backend-nest/ is a separate change, and I decided it should be an explicit choice, made after parity, not a step inside the feature. I wrote this into the specification as an assumption, so that no task could quietly remove the old backend.

Step 1: Constitution, as a Minor Amendment

The constitution from the second article described a Spring Boot stack, Flyway and a monorepo with backend/. A migration breaks some of those statements, so the first command amended the file instead of replacing it:

/speckit-constitution Amend the RoomBook constitution for the backend migration from Spring Boot
to NestJS. Changes: (1) Technical constraints: the backend is NestJS on Node.js LTS with
TypeScript, in backend-nest/ ... (2) Principle V: schema and seed changes go through versioned
SQL migrations, run by an internal runner; Flyway is no longer used. (3) Principle VII: backend/
remains only during the migration and is removed at cutover. All other principles stay unchanged.
Bump the version as a MINOR change and record the rationale in the Governance section.

Notice what the prompt does not do: it does not rewrite the principles. Contract first, the injectable clock, the service-layer rules, the shared design system: all of them stay. The amendment only touches what the migration really changes, and the version number tells the reader that the change is a MINOR one. The rationale goes into the Governance section, so the reason is recorded where the next person will look.

The check is simple: the file contains the new stack, the version went up, and the rationale is there.

Step 2: Specify, Without a Single Framework Name

The specification is the one place where I was strict. A specification for a migration is still a specification of behavior, so it must not mention the technology:

/speckit-specify Replace the RoomBook backend with a new implementation in backend-nest/, without
changing visible behaviour. The HTTP contract defined in openapi.yaml stays unchanged and the
frontend is not modified. The business rules stay identical. Errors stay in application/problem+json
format with the same status codes. The data already present in backend/data/roombook.db must be
readable by the new backend through a copy of the file. No new feature is included.

The result is specs/006-nest-backend-replacement/spec.md. The check I give myself for every spec is short: no stack names in the requirements, and no [NEEDS CLARIFICATION] marker left behind. A migration makes this rule harder to keep, because the temptation to write "use the same Express middleware" is strong. I kept it out.

The optional clarify step is where I wanted the questions most: how the copy is made, what happens with a database that has not been migrated yet, and how parity is checked. Those are the questions a migration hides.

Step 3: Plan, the Place Where the Stack Enters

Now the stack goes in, and it is the same idea I described in the first article: the spec says what, the plan says how.

/speckit-plan Backend in backend-nest/ with NestJS on Node.js LTS and TypeScript. Module structure:
rooms and bookings, each with a controller (HTTP mapping only), a service (business rules) and a
repository (SQLite access). Persistence with better-sqlite3 and the versioned SQL files V1–V4 reused...
Tests: Jest with supertest for the contract tests, which validate requests and responses against
specs/001-project-setup/contracts/openapi.yaml and every documented status code.

Two things in this prompt matter more than the rest.

The first is reuse of the migrations. The SQL files V1 to V4 are copied as they are. The Spring service uses Flyway, which keeps its own history table, so the new service must verify that history without changing it. The plan therefore splits the job in two: a read-only check of Flyway's table at startup, and a separate table for future migrations (V5 and later). The research file records this as a decision, R-003, with its reason: the copy's history must not change.

The second is the clock. Every time-dependent rule uses an injectable Clock, as the constitution asks. For the parity runs, the new service can be frozen with an environment variable, while the Spring service keeps the real clock. That sounds odd at first, but it makes the recorded requests robust against time: a request about "tomorrow at 10:00" means the same thing on both sides, and it does not depend on when the test runs.

The planning step produced plan.md, research.md, data-model.md, contracts/README.md and quickstart.md. The check I run on the plan is the one from the second article: no reference to Spring in the implementation choices. The Spring code is there only as a reference for the rules, and the plan says so.

The plan also records the versions I checked on the day: NestJS 12, better-sqlite3 13 (which requires Node 22 or later) and Jest 30. The local runtime was Node 24. Writing the versions down is a small habit that saves a lot of confusion later.

Step 4: Checklist and Tasks, Test First

The checklist is an optional gate. Spec Kit does not require it, and it was tempting to skip it, because the spec already comes with its own requirements checklist. I ran it anyway, with an explicit focus, because the questions this migration could hide are about compatibility, not about the code:

/speckit-checklist Quality of the parity requirements: unchanged contract, complete business rules,
error format, compatibility with the existing database

The checklist does not change the spec and does not inspect the code. It produces questions about the requirements, written as if a reviewer had never seen the implementation: is every rule complete, is every error stated, is the database compatibility defined well enough to be tested? A person answers them. In this project the checklist belongs to the reviewer, so it is something I read and judge, not something I let the agent tick off. Before implementation, the requirements checklist had 16 items, all checked, and the implement command reads that state as a gate before it starts.

Then came the tasks, which is where the method turned into test-first development. I chose TDD on purpose, and I wrote it into the order of the phases instead of leaving it to the agent:

/speckit-tasks Order the tasks in phases: (1) scaffolding of backend-nest/ and the migration runner;
(2) contract tests for each endpoint, written before the code; (3) implementation of the rooms and
bookings modules; (4) parity comparison with the Spring backend on the same copied database.
No task modifies openapi.yaml.

The four phases each have a precise role:

Scaffolding and migration runner. The runner's tests were written before the runner. The first red tests asked a simple question: does the service refuse to start on a missing or mismatched database?
Contract tests, red by design. This phase has no controller and no service. Every endpoint and every documented status code gets a test that validates against openapi.yaml, and all of them fail at the start. The implement instruction is explicit that they must fail because the feature is missing, not because of a setup error. A test that is red because of a broken import looks like progress, and it is not, so I read the failure messages myself.
Implementation, test first again. The booking rules were written as tests before the rules themselves. Only then did the rooms and bookings modules appear, and the tests turned green one at a time. The boundaries of the rules were checked with a fixed clock, so the results were deterministic.
Parity. The same requests are sent to both services, on identical copies of the database, and the responses are compared.

Phase 2 is the one I would point to. The contract tests were the specification in executable form, and they were red before a single line of the new backend existed. Later, when the amendment moved DTOs and transactions into their final places, the same suite was the check that nothing visible had changed.

The analysis step, run before implementation, checked two things that I wanted to be sure of: no task touches openapi.yaml, and every endpoint has a contract test. It found no critical inconsistency.

Step 5: Implement and Converge, One Phase at a Time

Each phase follows the loop from the second article: implement, converge, repeat until converge says "Converged", and check the phase checkpoint before moving on. The implement argument repeats the hard limits every time, because each run starts with a fresh context and I do not want to rely on memory:

/speckit-implement Only phase 2 (T021–T034). ... Do not implement any controller or service in this
phase. The new route tests must fail because the feature is missing, not because of a setup error.
Do not modify openapi.yaml, frontend/ or backend/.

The sentence about the failing tests is the one I would copy into any migration. A test that fails for a setup error looks like progress, and it is not. I check the failure messages myself: an import error or a wrong path means the phase is not done.

Some things I learned from the runs, which the tasks alone would not have shown:

import type for interfaces. With decorators, emitDecoratorMetadata and ts-jest in ESM mode, importing an interface as a normal value fails at load time. It was a small error, found by the first test run, and it is now a rule in the decision log.
Shared state in tests. The overlap test in the booking contract file failed only when it ran after another test. Alone it passed. The failure came from a shared app and database, not from the rules. The fix gives that single test its own app and its own database, without changing any expectation: 201 for the first booking, 409 "Slot already booked" for the overlap.

This second point is the one I want to underline. When a test fails, the first question is whether the code is wrong or the test is wrong. In this project, a test expectation that looks wrong must be reported, not edited, and the migration instructions say so explicitly.

An Amendment in the Middle of the Migration

Halfway through, I wanted two changes that had nothing to do with the migration's first goal. I wanted one DTO file per module, following the pattern of the earlier features, and I wanted database transactions to belong only to the service layer, as the constitution already says. Neither change alters the contract or the rules, but both alter the structure.

I did not open a new feature for this. I used the existing one, with the same Spec Kit sequence, and each command was given an explicit folder so that nothing would be created by mistake:

/speckit-specify Amendment to feature 006 (backend-nest replacement), no new user-facing behaviour: ...
/speckit-plan Amendment to the existing plan of feature 006 (do not create a new feature)...
/speckit-tasks Amendment to the existing tasks of feature 006... Append a new phase after the existing
tasks; do not renumber or edit existing completed tasks.
/speckit-implement Only phase 5 (T061–T068)...

The results were a new requirement pair in the spec (FR-022 for the DTOs, FR-023 for transactions), an updated plan and data model, and a Phase 5 appended to tasks.md. Existing tasks were not renumbered. That detail matters more than it looks: the task list is a log, and a log that gets rewritten is no longer a log.

The amendment also gave me a useful example of how converge behaves. After the phase, converge found one high-severity gap, the shared-state overlap test I described above, and one medium gap: the parity gate had not been run yet. It did not fix either. It appended Phase 6, with one task per gap, and the loop closed them.

Every decision taken without asking went into a decision table, with an ID, the decision, and a short reason. The table is short, so I can review it in two minutes. For example, D-2 moved the BookingSummary type into the bookings DTO file rather than the rooms one, because its mapping belongs to the booking shape. That is the kind of choice I would have made silently in a normal project.

The Parity Gate, and Where I Stopped

The last phase is the one that decides whether the migration is real: the same requests, sent to the Spring service and to the NestJS service, on identical copies of the database, must produce identical responses.

The harness has three rules. It resets both copies before each run, so a run cannot depend on a previous one. It uses a fixed set of recorded requests, 99 in this run, chosen to be robust against time. And it compares the status, the headers that matter and the body, byte by byte where the format is part of the contract.

The gate command is simple:

npm --prefix backend-nest run parity

The gate ran to completion. Before the final run I re-recorded the Spring reference against the live Spring service, because the earlier reference file had been removed. The recording holds 99 requests. Then the gate replayed them on fresh copies of the database:

Fresh copies made from backend/data/roombook.db (sha256 2e10fed8…cd44).
Compared 99 requests (Spring on http://127.0.0.1:8090, Nest on http://127.0.0.1:8091).
Differences: 0. Spring drift vs recorded: 0.

The harness starts both services itself, on ports 8090 and 8091. The ports in the early plan were 8080 and 8081, so the harness was adjusted to the run rather than the other way round.

Zero differences and zero drift are the result that matters. The checks around it are green too: the NestJS suite passes 15 of 15 suites and 72 of 72 tests, openapi.yaml shows no diff, the frontend/ and backend/ folders show no diff, and the SHA-256 of the original database is unchanged. With this run, the last two tasks, T060 and T070, are done. The cutover, removing backend/ and renaming backend-nest/, remains a separate decision, as the specification requires (FR-021).

What the Process Gave Me

After a second project with Spec Kit, here is what I would add to the list from the previous articles:

A migration becomes a checklist of constraints. Writing "no change to the contract, the rules, the errors and the frontend" forced every later step to name what it must not touch.
Tests that fail for the right reason. The phase 2 instruction is the most valuable sentence in the whole set of implement instructions. A red test is only progress when it is red for the expected reason.
Decisions are visible. The decision tables, the R- and D- entries, made it possible to review what the agent decided on its own, instead of finding it in the code later.
The contract as a fixed point. A SHA-256 check before and after, and a rule in every prompt, kept openapi.yaml untouched through the four phases and the amendment.

What the Process Taught Me

The other side, with the same sincerity as before:

The parity set is a deliberate, bounded choice. For this exercise, 99 recorded requests were enough to cover the rules and error paths of the current API, and the gate compares the two services on each of them. In a production setting, the same harness could replay many more requests, including generated edge cases, because adding a case is just adding an entry to the file. The number is a starting point we chose, not a limit of the method.
The spec is only as good as the questions asked. Clarify found the copy strategy and the unmigrated-database case. It did not find, by itself, every behaviour that the old code had and nobody wrote down. That is why the parity harness matters.
Good instructions take time to write. Each command carried its own limits, checks and expected outputs, which is what made the process repeatable. Writing them was real work, and the cost is time, not tokens.
A person still decides the cutover. The agent can make the new backend pass its tests. It cannot decide that removing the old one is safe.

Takeaways

Constraints are the specification of a migration. The fixed points, the contract, the rules, the errors and the frontend, are what make the change measurable.
Phase order is the safety net. Scaffolding, then tests that fail for the right reason, then code, then parity.
Amendments belong to the existing feature. A log with numbered tasks and decision tables is easier to trust than a rewritten one.
Passing tests are not parity. The gate that matters compares two running services on the same data. Once it reports zero differences, the migration has evidence behind it, not only green tests.

The migration itself is in the repository: the specification and plan in specs/006-nest-backend-replacement/ and the code in backend-nest/. The one decision left is the cutover, which is a separate change, and it is my call.

What Comes Next

With this article, the series on GitHub Spec Kit comes to an end. The next one is about the BMAD Method. I am studying it right now, and writing about what I study is one of the best ways I know to learn it, especially when each concept is tied to a practical example from a real project situation. BMAD is similar in spirit to Spec Kit, but more complex: it has a steeper learning curve, and in exchange it covers a wider part of the software lifecycle. Stay tuned.

Have you tried changing the stack of a project that has a contract, without touching the frontend? What did you keep fixed, and what did you find out only at the end? I would like to read your experience in the comments.

Spec-Driven Development in Practice: Building RoomBook with GitHub Spec Kit

rosidotidev — Sun, 18 Oct 2026 18:23:26 +0000

In the first article I stayed on the theory: the specification as a contract, the Spec Kit workflow, a todo list as a toy example. This time I do what I promised and build something real. The application is called RoomBook, a meeting-room booking app with an Angular frontend, a Spring Boot REST backend and SQLite persistence, built from the first line to the last one with GitHub Spec Kit and a coding agent.

The whole project is on my GitHub: room_book on Github. Every spec, plan, checklist and task list I mention below is in the repository, under specs/. I show the method here and link the files for the rest, because a full walkthrough would be longer than anyone wants to read.

I wrote this article with two goals. The first is to show what Spec Kit does, step by step, on a project with real business rules. The second is to be honest about what it gives you and what it does not. As in the first article, this is a personal view, not a verdict.

The Example: RoomBook

Why a room booking app? Because it looks trivial and is not. A booking is just a room, a title, a person and two timestamps, but the rules around it are exactly the kind of thing an AI agent gets subtly wrong when nobody writes them down:

No overlap on the same room, but back-to-back bookings are allowed (10:00-11:00 and 11:00-12:00).
Allowed hours 08:00-20:00, Monday to Friday, on 15-minute boundaries.
Maximum duration 4 hours, and no bookings in the past.
Cancellation allowed until one hour before the start, as a soft delete.
A deactivated room cannot be booked, and its future bookings are reported, not deleted.

Authentication, notifications and recurring bookings are explicitly out of scope. Saying what is not in the project is as important as saying what is.

I split the work into five macro features, and each one is a complete Spec Kit cycle:

The first three (setup, rooms API, rooms UI) are the base. Then comes a pure backend feature, the bookings API, and a pure frontend feature, the bookings UI. These two are the interesting ones, because they show how Spec Kit behaves when a project already has a constitution, a contract and a design system, and you only extend them.

This is what the result looks like. The day view on desktop, with several rooms side by side:

The room administration screen, where an inactive room is marked with a label and an icon, not only with a different color:

None of these screens was designed in a mockup tool. They come from a specification, and that is what the rest of the article is about.

Step 0: Init and Constitution

Spec Kit is installed and initialized from the terminal. These are the only terminal commands of the whole process, everything else is typed in the chat of the coding agent:

uv tool install specify-cli
specify init roombook --integration <your-agent>
cd roombook
git init

The repository has to be under Git, because Spec Kit creates numbered feature branches. After the init, the agent gets the Spec Kit commands as skills, and you find them in the project:

<prj_root>/.claude/skills/speckit-specify/SKILL.md
<prj_root>/.claude/skills/speckit-plan/SKILL.md
...

Then the constitution, written once. This is the prompt I used, shortened here (the full text is in the repository):

/speckit-constitution Define principles for RoomBook, a meeting-room booking app with an
Angular frontend, a Spring Boot REST backend and SQLite persistence. Principles:
(1) API-first: the OpenAPI document is the source of truth and is changed before any code.
(2) Contract tests are mandatory for every endpoint.
(3) Business rules live in the service layer, never in controllers or in the frontend.
(4) Time-dependent logic must use an injectable Clock so tests are deterministic.
...
(10) The UI follows one shared design system based on design tokens, defined once and
never hard-coded in components.

The result is a file of eleven principles. Here are a few lines:

<prj_root>/.specify/memory/constitution.md

### I. API-First (NON-NEGOTIABLE)
The OpenAPI document is the single source of truth for the HTTP API. Any API change MUST be
made in the OpenAPI document before any backend or frontend code is written.

### IV. Deterministic Time
All time-dependent logic MUST use an injectable `Clock`. Code MUST NOT call `now()` without a
clock. Tests MUST use a fixed clock so results are deterministic.

I want to stress why this file matters. Every later plan is evaluated against it, and every deviation has to be justified in the plan itself. When the agent writes the booking rules, it does not decide on its own how to handle time: the constitution already decided. That is a piece of architecture, written once, enforced many times.

One Cycle, Five Times

Each macro feature follows the same sequence, which is the one from the first article with the three optional gates switched on:

The cycle is the same every time, and that is the point. I do not invent a new process for a backend feature and another one for a frontend feature. What changes is the content of the prompts: the specification talks about behavior, the plan talks about technology. And I review the output of every step before running the next one.

Let me show the two interesting cases.

Backend Feature: Bookings API

Step 1: Specify (what and why, no technology):

/speckit-specify Let employees book meeting rooms without double bookings. A booking has a
room, a title, the organizer's name, a start and an end time. Two bookings on the same room
cannot overlap, but one may start exactly when another ends. Bookings are allowed from 08:00
to 20:00, Monday to Friday, on 15-minute boundaries, last at most 4 hours and cannot be in the
past. A booking can be cancelled until one hour before it starts; cancelling frees the slot
and keeps the history. A deactivated room cannot be booked...

There is no Spring Boot, no SQL and no endpoint in this text. It describes rules a business person could read and correct.

Step 2: Clarify (find the holes before planning):

/speckit-clarify

This is where I started to see real value. The agent asked targeted questions about things I had not said, and folded the answers back into the spec. These are some of them, copied from the generated file:

<prj_root>/specs/004-bookings-api/spec.md

## Clarifications
- Q: Which time zone applies? -> A: A single office time zone, Europe/Rome by default and
  configurable; hours, weekdays and 15-minute boundaries are evaluated in the office time zone.
- Q: Can a booking span midnight? -> A: No; start and end must fall on the same office-local day.
- Q: Is cancellation allowed at exactly one hour before the start? -> A: Yes; it is allowed
  when at least 60 minutes remain before the start and refused when fewer remain.

I had never written a word about time zones. Without this step, the agent would have guessed one, silently, and I would have found out in production. With it, the question became a decision with my name on it.

Step 3: Plan (how, with the contract first):

/speckit-plan Extend openapi.yaml first: booking schemas, the four endpoints and the
400/404/409/422 problem+json responses. Add a Flyway migration for the booking table with a
foreign key to room and an index on (room_id, start_at). The booking service validates all
rules using the injectable Clock; overlap check and insert in a single transaction...

Here the technology enters, and the first article's rule applies: the spec says what, the plan says how. Note the order in the prompt: the contract is extended before any code, as the constitution requires. In the generated contract, even the order in which rules are checked is documented:

<prj_root>/specs/001-project-setup/contracts/openapi.yaml

/api/bookings:
  post:
    operationId: createBooking
    description: >
      Rules, checked in this order after the fields are present: unknown room (404),
      deactivated room (422), hours 08:00-20:00 office time Monday to Friday on 15-minute
      boundaries, same local day, duration of at most 4 hours, end after start, start not
      before now (400), then overlap with a confirmed booking of the same room (409).

Step 4: Checklist (quality of the requirements, not of the code):

/speckit-checklist Requirements quality for booking rules: completeness, ambiguity and testability of each rule

The checklist produced 42 items. They are questions about the requirements, which is why I find them useful: they read like a reviewer who has not seen the code. For example:

<prj_root>/specs/004-bookings-api/checklists/rules.md

- [ ] CHK005 Is "from 08:00 to 20:00" unambiguous about whether 20:00 is a valid end and 08:00 a valid start?
- [ ] CHK008 Are public holidays explicitly in or out of scope for "Monday to Friday"?
- [ ] CHK016 Is it stated who may cancel a booking, given there is no authentication, and that the organizer name is not a credential?

These checklists are reviewer-owned: the tool generates the questions, a human decides whether the answers are good enough.

Step 5: Tasks, analyze, implement (build it):

/speckit-tasks
/speckit-analyze
/speckit-implement

The task list for this feature has 28 tasks, each one naming the files it touches. /speckit-analyze is read-only: it cross-checks spec, plan and tasks and reports conflicts and gaps before a single line of code is written. Then /speckit-implement executes the tasks in dependency order.

Step 6: Converge (the part I did not expect to like):

/speckit-converge

This was the moment I understood what "checked, not just read" means. After the first implementation, converge compared the code with the spec and found a gap. It added a new task under a Convergence section of tasks.md:

<prj_root>/specs/004-bookings-api/tasks.md

## Phase 9: Convergence
- [X] T028 Add rule tests in `backend/src/test/java/com/roombook/service/BookingRulesTest.java`
  with winter offsets and around the daylight-saving change of 25 October 2026 (Europe/Rome):
  the same office-local 08:00-20:00 window is accepted before and after the change although
  the UTC offset differs, 07:45 and 20:15 are still refused...

The code worked. What was missing was a test for a requirement that came from the clarification about time zones. That is exactly the kind of gap that survives a code review, because nobody thinks about the last Sunday of October on a Tuesday afternoon. Converge did not edit the code: it appended a task, and the loop implement, then converge, closed it.

Frontend Feature: Bookings UI

The frontend feature starts from a very different situation: the backend exists, the contract is published and the design system was created two features earlier. This changes the text of the prompts, and it is where I think Spec Kit shows its structure best.

Specify talks only about the user:

/speckit-specify Let employees see when a meeting room is free and book it from the browser.
They pick a room and a date and see a day view from 08:00 to 20:00 in 15-minute steps, with
booked periods showing the booking title... If the system refuses the booking, the message
explains why in plain language and the entered data is kept. The screens adapt to the device:
on a phone the day is a vertical agenda for one room with a date strip...

Plan names the existing contract as a constraint, not as something to design:

/speckit-plan Angular standalone components with routes /availability and /my-bookings,
reusing the layout, error-display component and generated client from F02. Do not modify
openapi.yaml; the contract from F03 is a fixed constraint... Reuse the design tokens, Material
theme and app shell from F02; add no new colors or fonts.

This sentence is the whole lesson. An agent that is told to "build the booking screens" might decide that a new endpoint would be convenient. An agent that is told the contract is fixed has to find a way inside it, or report a finding. And since the constraint is written down, it can be verified: the feature folder contains a hash of the contract taken before the work started, and the same hash was checked at the end.

<prj_root>/specs/005-bookings-ui/contract-baseline.sha256
664521af719673603dd80717031c4518870d3e9c8f1281633009919aa68353fe

$ sha256sum specs/001-project-setup/contracts/openapi.yaml
664521af719673603dd80717031c4518870d3e9c8f1281633009919aa68353fe

Same hash, same contract. The frontend did not touch it.

The clarify step was again useful for decisions I would have left to chance. Two of them:

<prj_root>/specs/005-bookings-ui/spec.md

- Q: What happens when a selection spans an occupied period? -> A: Only the free part up to
  the occupied period is selected; the occupied period is never included.
- Q: How is the organizer name remembered between visits? -> A: It is stored on the device (in
  the browser) and pre-filled in the booking form; it is never sent anywhere except as the
  organizer of a booking or as the name to look up.

The adaptive behavior is also in the specification, so it is verified like everything else. The same page changes layout at the breakpoints defined in the constitution, 600 and 1024 pixels. On a tablet, a timeline for one room:

On a phone, a vertical agenda with a date strip and a bottom navigation bar:

Here too the convergence step found gaps and wrote them as tasks: component tests for the layout at each breakpoint with a stubbed breakpoint observer, and tests for the date strip and the responsive dialog. Nothing was missing in the screens. What was missing was the proof that they behave as specified.

What Spec Kit Leaves in the Repository

Before looking at the code, it is worth looking at what the process produced next to it. Every macro feature has its own numbered folder under specs/, created by /speckit-specify and filled by the commands that follow:

<prj_root>/
├── .specify/memory/constitution.md      <- the eleven principles, written once
├── specs/
│   ├── 001-project-setup/               <- F00, also holds the shared contracts/openapi.yaml
│   ├── 002-rooms-api/                   <- F01
│   ├── 003-rooms-ui/                    <- F02
│   ├── 004-bookings-api/                <- F03
│   └── 005-bookings-ui/                 <- F04
├── backend/
└── frontend/

The five folders have the same shape. This is the one of the bookings API, with the command that created each file:

<prj_root>/specs/004-bookings-api/
├── spec.md              <- specify + clarify (what and why, with the Clarifications)
├── plan.md              <- plan (how: stack, constraints, structure)
├── research.md          <- plan (decisions and rejected alternatives)
├── data-model.md        <- plan (entities, fields, constraints)
├── contracts/           <- plan (notes on the changes to the shared openapi.yaml)
├── quickstart.md        <- plan (how to run and validate the feature by hand)
├── checklists/
│   ├── requirements.md  <- specify (quality of the spec)
│   └── rules.md         <- checklist (the 42 questions)
└── tasks.md             <- tasks, then updated by implement and converge

The frontend feature 005-bookings-ui has the same files plus two that exist only there: contract-baseline.sha256, the hash of the contract taken before the work, and contrast.md, the check of the colors against the accessibility rules of the constitution.

I like this layout for one reason: each file answers one question, and the question has an owner. spec.md is for the business, plan.md and data-model.md for the architect, checklists/ for the reviewer and tasks.md for whoever runs the implementation. When a rule looks wrong in the code, I know in which file to look for the sentence that caused it.

Mental Model: the specs/ folder is the memory of the project. The code can be regenerated, this folder cannot.

What Was Built: Backend and Frontend

The specs describe the project, and here is what they produced. The two applications are small, and their structure follows the plans closely.

The backend is Spring Boot on Java 21, with SQLite and Flyway:

<prj_root>/backend/src/main/java/com/roombook/
├── api/         BookingController, RoomController, HealthController, DTOs, ApiExceptionHandler
├── service/     BookingService, BookingRules, RoomService, one exception per business rule
├── repository/  BookingRepository, RoomRepository
└── config/      ClockConfig, OfficeZoneConfig, DataDirectoryInitializer

<prj_root>/backend/src/main/resources/db/migration/
├── V2__create_room.sql
├── V3__seed_demo_rooms.sql
└── V4__create_booking.sql

Layers: controller -> service -> repository, with no business rule in the controllers.
Rules in one place: BookingRules holds the checks on hours, boundaries and duration, and BookingService adds the overlap check and the transaction.
Errors as types: one exception per rule (BookingConflictException, CancellationTooLateException, RoomDeactivatedException), mapped to problem+json by ApiExceptionHandler, as the contract says.
Time as a dependency: ClockConfig and OfficeZoneConfig inject the clock and the office time zone, so the tests can fix both.
Database: one Flyway migration per feature, nothing created by hand.
Tests: the contract/ package has one class per group of endpoints and checks the responses against openapi.yaml, while the service/ package covers the rules, concurrency and performance.

The frontend is Angular with standalone components and Angular Material:

<prj_root>/frontend/src/app/
├── api/         client generated from openapi.yaml, never edited by hand
├── bookings/    availability.page, day-view, date-strip, booking-form, my-bookings.page, bookings.facade
├── rooms/       room-list.page, room-admin.page, room-card, room-form, deactivate-dialog, rooms.facade
├── layout/      shell and page components (the app shell)
├── shared/      problem-message, responsive-dialog, office-time, clock, organizer-store
└── styles/      tokens.css, theme.scss (the design system)

Generated client: api/ comes from the contract, so the frontend cannot call an endpoint that does not exist.
Pages and facades: in the bookings and rooms areas, each page has a facade that wraps the generated client, so components do not talk to HTTP directly.
Shared pieces: the error component turns a problem+json into a plain message, and the responsive dialog is a dialog on desktop and a full screen on a phone.
Design tokens: colors and breakpoints live in styles/, as the constitution requires, and no feature adds its own.

The counts are small on purpose: 26 backend test classes and 16 frontend spec files, which hold the tests counted below. What matters is that the folders in the code mirror the folders in specs/: a rule in a spec has a place in service/, a screen in a spec has a page in app/.

What the Tool Gives You

After building a real project with it, here is what I would put on the value side:

Questions before code. Clarify and checklist turn unstated assumptions into written decisions. This is, for me, the single biggest gain: the time zone, the midnight rule and the cancellation boundary were all decided by a person, not by a model.
Traceability. Every task points to a requirement, every requirement to a user story. When something looks wrong in the code, I can follow it back to a sentence in the spec.
A constitution that works. Eleven principles, written once, shaped four features. Contract first, fixed clock, problem+json errors: I did not repeat them in a single feature prompt.
Gates that fail loudly. Converge and analyze do not praise the work, they look for gaps. In my case they found missing tests, which is the kind of debt that normally stays invisible.
A repeatable cycle. The same eight commands for a backend rule engine and for a responsive grid.

The numbers of the project, for context: 36 tasks for the setup and between 27 and 28 for each of the four features, about 110 backend tests and 91 frontend tests, all generated from the tasks and the contract.

What the Tool Does Not Give You

It would be easy to stop at the list above, so let me add the other side, with the same sincerity as in the first article:

A wrong spec produces wrong code, faithfully. Converge says the code matches the spec. It cannot say the spec is what the business needs.
The review work does not disappear, it moves. Reading a constitution, a spec, a plan, a checklist and a task list is real work. I spent more time reading than typing.
The volume of artifacts is large. Each feature produces a folder with ten files or more. For a one-hour fix, this is too much, and the rule of thumb from the first article applies: use the minimum rigor that removes ambiguity.
It is spec-anchored, not spec-as-source. The contract and the tests keep the spec honest, but I did not hand the generation over to the spec alone. A person still decides when the loop stops.

Takeaways

If I have to summarize what the practice added to the theory:

The contract-first chain works in practice. Constitution, spec, plan and OpenAPI constrain each other, and a hash is enough to prove that a frontend feature left the contract untouched.
The clarify step is where the value starts. It forces the decisions that nobody wants to take upfront, and it records them.
Converge finds what the tests did not ask for. It does not replace a review, but it makes the gaps visible and turns them into tasks.
The cost is real. More reading, more files, more discipline. It pays off when the rules are real, as in a booking system, and probably not for a script.

The project, with all the specs, plans, checklists and tasks, is here: . If you clone it, start from specs/004-bookings-api/ and read the clarifications first.

What Comes Next

In the next article I take the challenge I announced: a port of the backend to another technology. The REST contract, the tests, the data model and the Angular application are my fixed points. RoomBook has now a contract with a known hash and a suite of about 110 backend tests, so the question has become measurable: if they stay untouched, the specification survived the move.

What do you think about Spec Kit on a project with real business rules? Have you tried it, or a different SDD tool? I would love to read your experience in the comments.

Spec-Driven Development with GitHub Spec Kit (Part 1): The Theory

rosidotidev — Mon, 12 Oct 2026 21:20:36 +0000

As a software architect and senior software engineer, I find myself in the middle of a change that I can only describe as epochal. The way we think about software development and enterprise architecture is shifting, and so are the roles that humans and "intelligent systems" play today and will play tomorrow.

My angle is Spec-Driven Development (SDD) with GitHub Spec Kit, seen from where I work every day: software architecture. In this first article I stay on the theory, with a small example of SDD to make it concrete. In the next ones I build a real application with Spec Kit. GitHub Spec Kit is not the only option: alternatives include Kiro, OpenSpec and BMAD. For now, though, GitHub Spec Kit is the one that best fits my preferences and the way I like to work. This is a personal choice, not a claim that one approach is universally better than the others. I wrote this article to share my view and to set a personal starting point that I can come back to (and probably correct) while things evolve. BMAD is one I may explore in a future article, or perhaps a short series of its own.

What Is Spec-Driven Development?

Let's start from the problem. Ask an AI agent to "add user registration to my app" and it has to guess: which fields, which password rules, is the email verified, how are accounts stored? The result is often plausible-looking code resting on dozens of unstated assumptions, many of them wrong. This is what people call vibe coding.

To me, SDD is the answer. It is an approach where a detailed, human- or AI-validated specification becomes the single source of truth before any code is written. Instead of documentation as an afterthought, the process is inverted: the specification is an executable blueprint that drives the AI coding agents.

Not every SDD approach keeps the spec alive for the same amount of time. I've found a classification featured in numerous articles to be incredibly helpful to distinguish three levels of rigor:

Spec-first: a well-thought spec is written before coding to guide the initial implementation. Once the code exists, the spec may be discarded or drift: its value is the initial clarity, which makes it a good fit for AI-assisted first builds and prototypes.
Spec-anchored: the spec is kept and evolves with the software, through automated tests and contracts. A change in behavior updates both, and tests derived from the spec (BDD scenarios, or OpenAPI with contract testing) fail when they drift. It suits most production systems well.
Spec-as-source: the spec is the main source file and agents generate or update code directly from its changes. Humans edit only the spec and never the generated code, so drift is eliminated by design. It needs mature, trusted generation tooling and today is practical mainly where generation is well defined, such as server stubs from OpenAPI.

My rule of thumb: use the minimum level of rigor that removes ambiguity in your context. Spec-first for AI-assisted initial development, spec-anchored for long-lived production systems, spec-as-source only when the generation tooling is mature and trusted.

The Specification as a Contract

This is the idea I want at the center of this series.

In a code-centric flow, requirements documents drift and design diagrams rot, so the code ends up being the de facto truth. Asking "what should this function do?" means reading the implementation. SDD flips the relationship: the specification becomes the authoritative description that humans and machines use to build and maintain the system. The spec declares the intent, the code realizes it.

I think three properties turn a specification into a contract and not just documentation:

Each phase constrains the next. Specify answers what, plan answers how, then come tasks, implementation and validation. Each phase produces an artifact that guides the following one, creating a chain of accountability from intent to implementation.
The spec stays the authority. When validation finds a gap, you either fix the code or revise the spec. Either way, the specification remains the reference point.
It is checked, not just read. Traditional design documents are read by developers who then write code that hopefully matches them. A contract is meant to be verified: if the code diverges, something should fail.

Contracts are not new in software. API specifications such as OpenAPI have long played this role: once the API contract is agreed, frontend and backend teams can work in parallel, and any implementation that matches the contract is valid by definition. SDD brings the same logic to the whole build process.

Mental Model: the spec declares the intent, the code is an implementation detail. And I would be careful with false confidence: a passing check only proves that the code matches the spec. If the spec is wrong, the code will faithfully implement the wrong thing.

GitHub Spec Kit in a Nutshell

Spec Kit is the open source toolkit from GitHub for spec-driven development. You interact with it through commands in your coding agent, and it plugs into many of them (Copilot, Claude, Gemini, Codex and others). It can also be extended with extensions, presets, workflows and bundles.

The core process is:

Specify -> Plan -> Tasks -> Implement -> Converge

The constitution, the project-wide principles and constraints, is defined once per project. Each phase produces a Markdown artifact that feeds the next one. For production features, three optional quality gates are added.

clarify: Asks targeted questions about anything underspecified and folds your answers back into the spec, so you're not planning on top of ambiguity. Run it before planning, optionally with a focus area.
checklist: Generates a custom quality checklist These custom checklists are reviewer-owned
analyze: Reports conflicts, gaps, and ambiguities across spec.md, plan.md, and tasks.md

A Simple Example: a Todo List

Theory is easier with a concrete case. Take the simplest idea I can think of, a todo list, and look at what goes where. The example is mine, written just to show the separation. The syntax is the real one from the Spec Kit docs, in GitHub Copilot's default skills mode (/speckit-*). You type these commands in the chat of your coding agent, not in the terminal. Other agents may invoke them in a different way, so check the docs for your setup.

Step 1: Constitution (project-wide principles, written once):

/speckit-constitution Todo List is an adaptive web application.
Every API change starts from the REST contract.
Business logic lives in the backend, never in the UI.
Every feature comes with automated tests.
The UI must work on both phone and desktop.

This creates or updates the project constitution: the guiding principles against which every later phase is evaluated. A few lines from the file look like this:

<prj_root>/.specify/memory/constitution.md

## Core Principles

### I. Adaptive Todo Application
The product MUST be an adaptive web application for managing todo items.
...
### II. REST Contract First
Every API change MUST begin with an update to the REST contract.
...
## Governance
Amendments MUST be reviewed and recorded in the constitution before dependent work proceeds.

Spec Kit also keeps dependent templates in sync. Create the file once at the beginning of the project, then update it whenever your principles change.

Step 2: Specify (what and why, no technology):

/speckit-specify Develop a todo list application where a user can add a task,
mark it as done, delete it and filter tasks by status.
A task needs a non-empty title.
Completed tasks stay visible until they are deleted.
Out of scope for now: sharing tasks between users and notifications.

The generated spec contains four user stories: Add a Task, Mark a Task Done, Delete a Task, and Filter Tasks by Status. Its built-in requirements checklist has 16 items, all checked in this example. A few excerpts from the generated files:

<prj_root>/specs/001-todo-list/spec.md

## User Scenarios & Testing
### User Story 1 - Add a Task (Priority: P1)
...
## Requirements
- **FR-002**: The system MUST reject an empty or whitespace-only title...
...
## Success Criteria
- **SC-004**: Users can complete the add, complete, delete, and filter journeys on both phone and desktop form factors.

<prj_root>/specs/001-todo-list/checklists/requirements.md

## Feature Readiness
- [x] All functional requirements have clear acceptance criteria
- [x] User scenarios cover primary flows

The spec focuses on the what and why: user-facing behavior, goals, and outcomes, not the tech stack. The built-in checklist reviews the spec's quality and completeness before planning.

Step 3: Plan (how, the technology belongs here):

/speckit-plan Use an Angular web application, a REST API and a backend component (Python)
that holds the business logic, on top of a relational database (SQLite).
Data model: Task(id, title, status, createdAt).
Expose create, read, update and delete endpoints on /tasks.

This creates the implementation plan and four supporting design artifacts under <prj_root>/specs/001-todo-list/. The excerpts below are copied from those files.

plan.md (Most important file for technical requirements):

<prj_root>/specs/001-todo-list/plan.md
## Summary

Deliver an adaptive todo-list web application for adding, completing, filtering, and deleting tasks.
The Angular client uses a contract-first REST API; a Python FastAPI service owns validation and
business rules and persists tasks to a file-backed SQLite database through Python's standard
`sqlite3` module.

research.md (technical discovery file):

<prj_root>/specs/001-todo-list/research.md
### SQLite from Python

- **Decision**: Use Python 3.12's built-in `sqlite3` module with one connection per request, created
  and closed on the request's worker thread. Keep each mutation in a short transaction and commit
  only after all statements succeed; roll back on failure.

data-model.md (file used for data model):

<prj_root>/specs/001-todo-list/data-model.md
## Task

| Field | Type | Required | Rules |
|---|---|---:|---|
| `id` | UUID | Yes | Generated by the backend; unique and immutable. |
| `title` | String | Yes | Must contain at least one non-whitespace character. Valid submitted values are preserved. |

contracts/openapi.json (REST interface spec):

<prj_root>/specs/001-todo-list/contracts/openapi.json
  "paths": {
    "/tasks": {
      "get": {
        "operationId": "listTasks",
        "summary": "List tasks, optionally filtered by status",

quickstart.md (setup frontend and backend):

<prj_root>/specs/001-todo-list/quickstart.md
## Start the Backend

From the repository root in PowerShell:

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e "backend[test]"
```

Step 4: Tasks (break the work down):

/speckit-tasks

No arguments here: the command reads the design artifacts and creates <prj_root>/specs/001-todo-list/tasks.md. This file contains 40 tasks: Setup (3), Foundational (8), Add a Task (7), Mark a Task Done (6), Delete a Task (6), Filter Tasks by Status (7), and Polish (3). Each story has a goal, an independent test, and its own test and implementation tasks. In this example, the tests are included because the constitution requires automated tests for every feature.

The file defines the task format and traceability labels:

<prj_root>/specs/001-todo-list/tasks.md
## Format: `[ID] [P?] [Story] Description`
- **[P]** marks work that touches separate files and has no dependency on an incomplete task.
- **[Story]** identifies the user story for story-phase tasks; setup, foundation, and polish tasks have no story label.
- Every task names the exact file or files to create or modify.

Here is its User Story 1 section. The [X] markers shown are the current state, after /speckit-implement completed the tasks:

## Phase 3: User Story 1 - Add a Task (Priority: P1, MVP)
**Goal**: Create a task from a non-empty title and show it in the All task list.
**Independent Test**: Submit a valid title and confirm exactly one active task with the submitted title is returned and displayed; empty and whitespace-only submissions create no task and show a title-required message.
### Tests for User Story 1
- [X] T012 [P] [US1] Add POST `/tasks` and default GET `/tasks` request/response contract tests, including 201, Task response fields, and 422 Problem Details, in `backend/tests/contract/test_create_task_contract.py`.

Parallel work and phase dependencies are also recorded in the same file:

### Parallel Opportunities
- Setup tasks T001-T003 touch separate backend, frontend, and root configuration files.
- Within each story, its three test tasks use separate contract, integration, and UI test files and can be authored in parallel before story implementation.

Before implementation, /speckit-analyze can check the consistency of spec, plan, and tasks; it is read-only and reports conflicts and gaps.

Step 5: Implement (build it):

/speckit-implement

This is the command that writes the code. It executes the tasks in tasks.md, running each phase in dependency order and respecting the parallel markers. Before starting, it reads the state of the checklists as a gate: if some items are unchecked it asks before proceeding, and it never changes the checklist markers. For a small feature like our todo list you can run it once and build everything. For a larger one, you can scope each run with an argument (for example only the Setup and Foundational phases), validate the result and then continue.

If you catch yourself writing "use PostgreSQL" in the specification, move it to the plan. This is the whole point: the spec says what, the plan says how. And it is exactly what makes me curious about changing only the plan later.

Step 6: Converge (check that nothing was missed):

/speckit-converge

This assesses the codebase against the spec, the plan and the tasks to confirm that nothing was missed. It is append-only: it never edits or deletes code, and its only possible write is adding tasks to tasks.md. You run it only after implement has run on the current tasks.md. It first prints a summary of the findings graded by severity, then ends in one of two ways:

Converged: no gaps found. tasks.md stays unchanged and you can move on to the review or the pull request.
Tasks appended: gaps found. The new tasks are added under a Convergence section of tasks.md, you run implement again to complete them and then converge once more, until it reports converged.

The Role of the Human

SDD does not take people out of the loop: I think it moves the place where their judgment is applied. Accepting generated changes with minimal resistance is just vibe coding with more files. Machines take over the mechanical work: generating code, keeping artifacts consistent, detecting drift. Humans keep authority over intent, domain meaning, risk tolerance and the legal and ethical constraints that no execution trace can reveal. Those constraints have to be written explicitly into the specification, which is where human judgment is encoded and then enforced.

In practice, for me this means explicit approval boundaries: a breaking schema change, a policy shift, a refactoring proposed by the AI or a compatibility downgrade should never pass without a person's decision. Spec Kit points in the same direction. Every phase produces an artifact you review before moving on, and in its own agentic SDLC tests and scans stay deterministic automation while merge decisions stay with the maintainers.

For the engineer, I believe, this changes where value comes from: no longer the speed of writing lines of code, but the quality of the specifications they refine and validate, as an orchestrator and validator who defines the what upstream and approves the how at the boundaries.

Mental Model: bounded autonomy, not full automation. Enforcement is automated, meaning stays human.

Takeaways

If I have to summarize my starting point in a few lines:

The specification is a contract. Each phase constrains the next, the spec stays the authority, and it is checked and not just read.
GitHub Spec Kit gives you the workflow: Specify -> Plan -> Tasks -> Implement -> Converge, with clarify, checklist and analyze as quality gates.
Humans move upstream, and their responsibility grows. People decide specifications, guidelines and architectures: engineers and architects evolve from writing code to owning what the system must do and why.
Keep a reality check. Less context drift, fewer hallucinations and no technical debt from chaotic prompting are the declared goals of SDD, not guaranteed results.

In the upcoming articles, we move from theory to practice: an adaptive Angular web application communicating via REST with a backend component holding the business logic on top of a relational database, fully specified and built using Spec Kit.
Next, I challenge myself by porting the backend to a different technology stack. The core idea here is to primarily adapt the plan, which dictates the technical specifications and stack changes. The REST contract, tests, data model, and Angular application act as our fixed anchor points: if they remain untouched, we prove just how powerfully specification-driven planning can handle technology shifts. The code will be on my GitHub (rosidotidev)

What has your experience with Spec-Driven Development been like? I'd love to hear your thoughts, questions, or feedback in the comments.

Github copilota spec

rosidotidev — Sat, 03 Oct 2026 06:42:49 +0000

Karpathy's LLM Wiki? No Code with Claude or Github Copilot!

rosidotidev — Sat, 23 May 2026 15:22:49 +0000

I first encountered Andrej Karpathy's LLM Wiki gist and realized it captures something essential about how we should manage knowledge in the AI era: a structured, human-curated knowledge base that grows from what you feed it, not from what an LLM hallucinates. The problem is that most implementations I found required heavy coding. I decided to build a completely no-code version that works seamlessly with both Claude Code and GitHub Copilot's .github/copilot-instructions.md system.

The result is llm-wiki-nocode: a production-ready knowledge management system where you ingest documents, ask questions, and maintain a living wiki, all through natural language commands, zero Python required.

What Is an LLM Wiki?

Before diving into the implementation, let me explain the concept. An LLM Wiki is a structured knowledge base that:

Ingests raw documents and extracts entities (tools, people, companies), concepts (patterns, ideas), and relationships
Retrieves facts exclusively from stored knowledge (no training data, no hallucinations)
Maintains integrity through automated health checks and human review
Compounds knowledge as you validate and refine auto-generated answers

The key principle is simple: everything the wiki knows comes from what you feed it. Not from the LLM's training data. Not from the web. Only from your sources.

This solves a real problem. When you ask an LLM a question about your proprietary system, it often confidently makes things up. A wiki-based approach forces it to admit "I found nothing" if the knowledge isn't there. No pollution. No false authority.

Why No-Code?

Most LLM Wiki implementations assume you have a Python environment, dependency management, vector databases, and patience for debugging integrations. That's the wrong barrier to entry.

I'm also building a production Python version using the Microsoft Agent Framework, structured around agentic workflows, knowledge graph construction, and semantic retrieval. But that's a separate project with its own architecture and tradeoffs. It will be the subject of a future article.

This project takes the opposite approach: zero dependencies, zero installation, pure natural language. No friction. Immediate usability.

What if you could ingest a document, ask questions, and maintain your knowledge base entirely through natural language? No terminals. No pip install. No YAML configuration. Just commands that read like English:

/wiki-ingest

/wiki-query What are the key architectural patterns?

/wiki-lint

This is what llm-wiki-nocode delivers. The system is designed to be human-operable: someone who has never written a line of code can build and maintain their own knowledge base.

The Three Core Operations

The wiki's entire interface consists of three commands. Everything else follows from these three:

1. `/wiki-ingest`, Build Your Knowledge Base

Ingest is where documents become knowledge. You point it at a raw file (Markdown, plain text, whatever), and it extracts entities, the named things like tools, frameworks, companies, people, and concepts, the abstract ideas like patterns, methodologies, principles. It detects relationships between them, merges new information with existing wiki pages, flags contradictions for your review, and updates the index and audit log in one pass.

You can pass a file path, use scan for auto-ingest, or --RESET-ALL if you want to start fresh. The output is new and updated pages in wiki/, plus a detailed log of what changed.

2. `/wiki-query`, Ask Questions Without Hallucination

Query is the retrieval side. You ask a question in natural language, and the system reads 3–8 relevant wiki pages and synthesizes an answer exclusively from that content. No external knowledge. No training data pollution. This is the core promise: every claim in the answer is cited with a wikilink showing exactly where it came from. The answer is saved to questions_pending/ for your review before it gets integrated as a synthesis page in the wiki.

3. `/wiki-lint`, Maintain Health

Lint is your wiki's health check. It runs in two phases: first, a deterministic pass that catches broken links, orphaned pages, missing frontmatter, and empty sections. Then a semantic phase that looks for contradictions, stale claims, missing pages, and unreferenced entities. The output is a detailed report with suggested fixes, saved to lint_pending/ for you to review and approve.

The Directory Structure

Understanding the layout is key to understanding how the wiki works:

wiki/                      ← Living knowledge base
├── index.md               ← Catalog of all pages
├── log.md                 ← Operation audit trail
├── sources/               ← One page per ingested document
├── entities/              ← Named things: tools, frameworks, companies
├── concepts/              ← Abstract ideas: patterns, methodologies
└── synthesis/             ← Approved answers from your questions

raw/                       ← Documents awaiting ingestion

questions_pending/         ← Auto-generated answers (your review)
questions_approved/        ← Answers you've validated

lint_pending/              ← Wiki health reports (your review)
lint_approved/             ← Fixes you've approved

docs/                      ← Specifications and guides

The key insight: wiki/ is the single source of truth. Everything else is a queue waiting for a human decision. raw/ is input. questions_pending/ and lint_pending/ are decisions waiting to be made. Once you approve something, it moves to _approved/ and gets integrated back into wiki/.

Three Page Types

The wiki uses three distinct page types to keep knowledge organized.

Sources are created when you ingest a document, one page per source file. Each source page contains the title, author, date, raw content, and a list of all entities and concepts extracted from that document. This is your audit trail: you know exactly which document something came from.

Entities are named, identifiable things. A tool like Jira or Kubernetes. A framework like React or MAF. A company. A person. Each entity page lists its definition, where it appears (which sources and concepts reference it), and related entities. This creates a web of interconnected knowledge.

Concepts are abstract ideas and patterns. A methodology like microservices or CQRS. A principle like DRY or YAGNI. A design pattern. Each concept page includes an explanation, examples (always with source citations), and connections to related concepts and entities. Concepts are how you see patterns across your sources.

How It Works: The Human-Gated Loop

This is the part that makes llm-wiki-nocode different from other implementations. The system never makes 100 auto-decisions and leaves you to inherit the consequences. Instead, it follows a human-gated approval loop.

The system generates, ingests a document, answers a question, finds health issues. Then you review what was generated, looking at the _pending/ folders. You decide which auto-generated content is good enough to integrate, and which needs refinement or rejection. Once you approve, the content moves to _approved/ and gets integrated back into the living wiki.

This loop is non-negotiable. The system assists; you decide. You never wake up one morning and discover the wiki made a thousand bad decisions overnight.

Automated generation    →    Human review    →    Integration
         ↓                        ↓                      ↓
   @wiki-querier          questions_pending/      wiki/synthesis/
   @wiki-linter           lint_pending/           wiki pages updated

Getting Started: A Practical Example

The repo includes three ready-made documents in the bak/ directory for testing. There's afw-instructions.md, technical documentation about Microsoft Agent Framework best practices. mfa_agents_howto.md is a how-to guide for building agents. And ARCH_BOOKING_PLATFORM.md is a simulated system architecture document. These examples show how the wiki handles diverse source material.

To test the wiki, copy one of these files to raw/ and run ingest:

cp bak/ARCH_BOOKING_PLATFORM.md raw/
/wiki-ingest

The ingestor will parse the architecture doc, extract entities like services, technologies, and teams, pull out concepts like "microservices", "event-driven", and "CQRS", create pages for each in wiki/entities/ and wiki/concepts/, and log every change in wiki/log.md.

Next, ask it a question:

/wiki-query What are the core services in the booking platform?

The querier will search the wiki for relevant pages, answer using only what's there, cite sources with wikilinks, and save the answer for your review.

Finally, run a health check:

/wiki-lint

The linter will check for broken links, orphaned pages, contradictions, and suggest fixes. You review the report, decide which fixes to apply, and the wiki improves itself.

The Configuration Layer: `.claude/` and `.github/`

This is a critical design decision that deserves explanation.

`.claude/` Directory, Claude Code Configuration

The .claude/ folder contains the complete configuration for Claude Code:

.claude/
├── CLAUDE.md                  ← Project instructions and behavioral constraints
├── settings.json              ← Command registration and harness configuration
└── commands/
    ├── wiki-ingest.md         ← /wiki-ingest command workflow definition
    ├── wiki-query.md          ← /wiki-query command workflow definition
    └── wiki-lint.md           ← /wiki-lint command workflow definition

How it works: CLAUDE.md is the main system prompt that defines the wiki's identity and available commands. settings.json registers each command and maps it to a workflow. Each file in commands/ is a complete specification, it tells Claude exactly how to perform that operation: what to read, what to extract, what format to use, what to validate.

When you type /wiki-ingest in Claude Code, it reads commands/wiki-ingest.md and executes that workflow.

`.github/` Directory, GitHub Copilot Configuration

Similarly, .github/ contains GitHub Copilot-specific instructions:

.github/
├── prompts/
│   ├── wiki-ingest.prompt.md   ← LLM prompt for ingest command
│   ├── wiki-query.prompt.md    ← LLM prompt for query command
│   └── wiki-lint.prompt.md     ← LLM prompt for lint command
├── instructions/
│   └── wiki-schema.instructions.md  ← Shared page format and schema documentation
└── agents/
    ├── wiki-ingestor.agent.md  ← Ingestor agent definition
    ├── wiki-querier.agent.md   ← Querier agent definition
    └── wiki-linter.agent.md    ← Linter agent definition

GitHub Copilot reads these files automatically when you open the repo. The prompts/ folder contains the LLM instructions (analogous to Claude's commands/). The agents/ folder defines how each agent behaves. The instructions/ folder holds shared schema documentation so both Claude Code and Copilot understand the page format identically.

Mental Model: Think of .claude/ and .github/ as platform-specific adapters. The core logic (what to extract, how to format, what to validate) is shared through wiki-schema.instructions.md. But the way you invoke commands, the syntax, and how each LLM system structures its workflows differs between Claude Code and GitHub Copilot.

This dual-support approach means:

If you use Claude Code: Open the project, type /wiki-ingest, Claude reads .claude/commands/wiki-ingest.md
If you use GitHub Copilot: The repo integrates automatically, Copilot reads .github/prompts/wiki-ingest.prompt.md and uses .github/agents/wiki-ingestor.agent.md
If you use neither: You can still read all the files and understand exactly what each operation does

No core logic is duplicated. Both versions implement the same three operations with identical semantics, they just speak different dialects.

Key Design Choices

Working through the full implementation revealed several important patterns worth sharing.

The wiki uses retrieval-only queries, not fine-tuning. It doesn't train or modify the LLM. Instead, it uses semantic search to find relevant pages and asks the LLM to synthesize an answer from only those pages. This is both simpler to implement and more reliable than RAG with fine-tuning.

Entities and concepts are fundamentally different, and treating them that way matters. A tool like Jira or PostgreSQL is an entity, a concrete thing you can point to. A pattern like CQRS or event sourcing is a concept, an idea that can apply in many contexts. When the wiki understands this distinction, you can ask "What concepts relate to Kubernetes?" and get a meaningful, connected answer.

Human review before integration is non-negotiable. A single document ingest can generate hundreds of pages. If you didn't review them, you'd have garbage in your wiki. The _pending/ folders force a decision point. It's cheap human attention spent upfront that saves you from debugging corrupted data later.

The audit trail is mandatory. Every operation, every ingest, query, lint, is logged with timestamps, the files it touched, and what changed. This is how you answer "When did I ingest that architecture doc?" and "What exactly did that ingest change?" questions months later when your memory is fuzzy.

Finally, the wiki uses plain Markdown with simple YAML frontmatter. No proprietary format. No database. Everything is human-readable, editable, and version-controlled. You can throw it in Git, diff it, and understand what changed without needing special tools.

What's Not Included (Yet)

This is a no-code system for knowledge ingestion and retrieval. It doesn't include vector databases or semantic search, you don't need them at small scale, and simple keyword plus fuzzy matching works fine for document lookup. If you scale large, that's a future architectural decision you can make then.

The wiki doesn't fine-tune or train the model. It works with any LLM that supports Claude Code or Copilot integrations, so you're not locked into a single backend.

Web ingestion isn't built in. You ingest documents from files. If you want to ingest web pages, you'd scrape them to Markdown first and place them in raw/.

Multi-user collaboration is deferred. The system assumes a single human curator making review and approval decisions. Role-based approval and conflict resolution for teams are possible, but not yet implemented.

None of these are impossible, they're just outside the current scope, waiting for a real use case to drive them.

Takeaways

Building llm-wiki-nocode clarified something important: the most powerful knowledge systems are simple systems that humans control. The wiki doesn't make decisions. It generates, you review, you decide.

If you're drowning in documentation that lives in Slack threads, scattered Markdown files, or worse, in everyone's heads, this pattern offers a way out. Feed documents to the wiki. Ask questions. Maintain a single source of truth. All without leaving your editor.

The code is on GitHub (rosidotidev/llm-wiki-nocode). The specifications are in docs/. Start with a simple document, ingest it, ask a question, and see what happens.

What would you use a no-code LLM wiki for? Is knowledge management the bottleneck in your projects, or is something else? I'd love to hear your thoughts in the comments.

Microsoft Agent Framework: From Agents to Workflows, Five Iterations of a DOCX-to-Markdown Pipeline

rosidotidev — Sun, 26 Apr 2026 12:35:17 +0000

In my previous article, I built a multi-agent pipeline that reads a Markdown backlog and provisions Epics and Stories on Jira. That project used two agents collaborating sequentially, wired together with plain Python orchestration.

This time I wanted to understand something specific: does the Microsoft Agent Framework (MFA) have a construct for defining execution graphs, similar to what LangGraph offers with its StateGraph or CrewAI with its Flow? In other words, can you define nodes, edges, and let the framework handle execution order, state propagation, and event streaming? To find out, I needed a use case that was practical enough to be reusable, complex enough to stress the graph model, and different enough from the Jira pipeline to force me into new territory.

I landed on converting Word documents into rich Markdown files with AI-generated image descriptions. The kind of structured, image-heavy documents (functional specifications, architecture documents, technical guides) that are notoriously hard to index in a RAG system because the images carry as much information as the text. A useful asset in itself, and a good bench for a multi-step pipeline.

MFA Workflows in 30 Seconds

The answer to my question turned out to be yes. The framework provides a Workflow system built on three primitives:

Executor: a processing node. You subclass it, implement a @handler method, and it receives typed input and produces output. An executor can wrap an agent, call an API directly, or run pure Python, the framework doesn't care.
WorkflowBuilder: the graph constructor. You declare a start node, then chain .add_edge(source, target) calls to define the execution path.
Edges: directed connections between executors. Data flows along edges via ctx.send_message(), while ctx.set_state() / ctx.get_state() provide a shared store accessible by any node in the graph.

When you call workflow.run(input, stream=True), the framework walks the graph and emits events (executor_invoked, executor_completed, output) that give you real-time visibility into each step.

With these primitives in hand, I could start building.

The idea behind the use case is simple: if you can turn every image into a detailed textual description embedded directly in the Markdown, a future RAG pipeline can "see" diagrams, screenshots, and flowcharts without needing a multimodal model at query time. The image content becomes searchable text.

What started as a straightforward agent-based pipeline evolved through five iterations into something quite different: a workflow-based, LLM-minimal architecture where Python does 90% of the work and the LLM is called only for what it's genuinely good at, describing images.

All the code is available on GitHub (MSFTAgentSample).

The Use Case

Given a folder of .docx files, the pipeline should:

Extract all text, tables, and images from each document, preserving the logical order and tracking where each image appears in the text flow.
Describe every extracted image using GPT-4o vision, producing thorough, structured descriptions that capture every visible element.
Assemble a clean Markdown document where headings, paragraphs, tables, and images are rendered correctly, with each image followed by its AI-generated description.
Write the final .md files to disk, ready for indexing or publishing.

The output looks like this:

## 6. Functional Requirements

The system shall provide a task management interface...

![Image](./images/img-003-a1b2c3d4.png)
**[Image Description]:** This is a screenshot of a UI mockup showing
a task management dashboard with three columns: To Do, In Progress,
and Done. Each column contains card-like elements with task titles...
**[End Image Description]**

The Starting Point: Agents Only (v1)

The first version followed the same pattern as the Jira pipeline: sequential agents, no workflow. Three agents collaborating in a chain:

DocExtractorAgent → ImageAnalystAgent → ContentAssemblerAgent

Each agent wraps a specific capability:

DocExtractorAgent calls a @tool function that uses unstructured and python-docx to extract text segments and images from .docx files. The output is a structured JSON with text_segments (typed: Title, NarrativeText, Table, ListItem, image) and an images array with file paths and surrounding context.
ImageAnalystAgent receives the extraction JSON, collects all image references, and calls a describe_images tool that sends each image to GPT-4o-mini vision. The vision prompt is thorough: it asks for image type identification, element-by-element description, all visible text transcription, relationships and flow, and layout details.
ContentAssemblerAgent takes the extraction data plus the image descriptions and produces the final Markdown.

The orchestration is plain Python, same as before:

response1 = await extractor_agent.run(f'input_dir="{INPUT_DIR}", output_dir="{OUTPUT_DIR}"')
response2 = await analyst_agent.run(response1.text)
response3 = await assembler_agent.run(
    f"extraction:\n{response1.text}\n\ndescriptions:\n{response2.text}\n\noutput_dir=\"{OUTPUT_DIR}\""
)

This worked, but several problems were immediately visible.

What Broke and Why

The LLM forgot to close tags. The ContentAssemblerAgent was instructed to wrap each image description in **[Image Description]:** and **[End Image Description]** tags. But on long documents, the LLM would sometimes omit the closing tag, breaking downstream parsing.

No observability. With plain agent.run() calls, you only see the final output. You don't know which agent is running, how long each step took, or where a failure occurred.

Sequential image analysis was slow. Each image was sent to GPT-4o-mini one at a time. A document with 10 images meant 10 sequential API calls, each taking 3-5 seconds.

Scalability was questionable. The ContentAssemblerAgent received the entire extraction JSON in its prompt. For a 50-page document, that JSON could exceed the model's context window, causing truncation or quality degradation.

These issues led me to explore the Workflow feature of the Microsoft Agent Framework.

Introducing Workflows (v2)

With the workflow primitives I described above, the first step was straightforward: wrap each agent inside an executor. Here's what a minimal executor looks like:

from agent_framework import Executor, WorkflowContext, handler

class MyExecutor(Executor):

    def __init__(self):
        super().__init__(id="my_executor")

    @handler
    async def handle(self, input_data: str, ctx: WorkflowContext[str]) -> None:
        result = do_something(input_data)
        await ctx.send_message(result)  # forward to next executor

Wire them up, and you get a graph with event streaming out of the box:

workflow = (
    WorkflowBuilder(start_executor=executor_a)
    .add_edge(executor_a, executor_b)
    .add_edge(executor_b, executor_c)
    .build()
)

async for event in workflow.run(input_data, stream=True):
    if event.type == "executor_invoked":
        print(f"Starting {event.executor_id}...")
    elif event.type == "executor_completed":
        print(f"Done: {event.executor_id}")
    elif event.type == "output":
        print(f"Result: {event.data}")

For v2, the graph was:

DocExtractorExecutor ──▶ ImageAnalystExecutor ──▶ ContentAssemblerExecutor

One thing worth noting: besides edge-based data flow (ctx.send_message), executors can also use shared state (ctx.set_state / ctx.get_state). This lets a node store data that any downstream node can read directly, without it having to pass through intermediate nodes.

For example, the DocExtractor saves the extraction result to state so that the ContentAssembler (two steps later) can read it directly, without the data having to flow through the ImageAnalyst:

class DocExtractorExecutor(Executor):

    @handler
    async def handle(self, prompt: str, ctx: WorkflowContext[str]) -> None:
        response = await self._agent.run(prompt)
        ctx.set_state("extraction", response.text)  # shared state
        await ctx.send_message(response.text)        # edge to next executor

Same functionality as v1, but now with event streaming and a clear graph structure.

The Template + Filler Pattern (v3)

The closing-tag problem from v1 persisted in v2, because the ContentAssembler was still an LLM generating the full Markdown including image descriptions. LLMs are inherently unreliable for repetitive structural tasks like "always close every tag."

The solution was to split the assembly into two steps:

TemplateAssembler (LLM), generates the Markdown structure with  HTML comment placeholders instead of actual descriptions.
TemplateFiller (pure Python), reads the image descriptions from state and replaces each placeholder with the formatted description using a regex.

The workflow became a 4-node graph:

DocExtractor ──▶ ImageAnalystStateful ──▶ TemplateAssembler ──▶ TemplateFiller

The TemplateFiller is completely deterministic:

_PLACEHOLDER_RE = re.compile(r"<!--IMG:([\w.\-]+)-->")

def _replace(match: re.Match) -> str:
    fname = match.group(1)
    replacement = desc_map.get(fname)
    if replacement is None:
        return match.group(0)  # leave placeholder as-is
    return replacement

filled = _PLACEHOLDER_RE.sub(_replace, content)

No LLM, no token cost, no randomness. The closing tag problem disappeared because the Python code always writes both the opening and closing tags.

This was the turning point. It made me ask: where else am I using an LLM for something Python can do better?

Scaling Up (v4): Parallel Vision + Chunked Assembly

With the architecture cleaned up, two scaling bottlenecks remained:

Image analysis was sequential. The ImageAnalyst agent called the describe_images tool, which internally looped through images one at a time. For N images, that's N sequential API calls.

The fix: a new ParallelImageAnalystExecutor that bypasses the agent entirely and calls AsyncOpenAI directly with asyncio.gather, bounded by a semaphore:

class ParallelImageAnalystExecutor(Executor):

    def __init__(self):
        super().__init__(id="parallel_image_analyst")

    @handler
    async def handle(self, extraction_json: str, ctx: WorkflowContext[str]) -> None:
        aclient = AsyncOpenAI()
        semaphore = asyncio.Semaphore(MAX_CONCURRENT)

        tasks = [
            _describe_image_async(aclient, img["path"], img.get("context", ""), semaphore)
            for img in all_images
        ]
        results = await asyncio.gather(*tasks)

        result_json = json.dumps({"images": list(results)}, ensure_ascii=False)
        ctx.set_state("descriptions", result_json)
        await ctx.send_message(result_json)

With MAX_CONCURRENT=5 (configurable via environment variable), 10 images now take ~5 seconds instead of ~40.

Template assembly could exceed context window. The TemplateAssembler received the entire document extraction in a single prompt. For large documents, this meant prompt truncation or degraded output quality.

The fix: a ChunkedTemplateAssemblerExecutor that splits the document's text_segments at heading boundaries (using the Title type from unstructured), processes each chunk with a separate LLM call, and concatenates the results:

def _chunk_segments(text_segments: list[dict]) -> list[list[dict]]:
    chunks: list[list[dict]] = []
    current: list[dict] = []

    for seg in text_segments:
        if seg.get("type") in {"Title", "Header"} and current:
            chunks.append(current)
            current = []
        current.append(seg)

    if current:
        chunks.append(current)
    return chunks

Each LLM call sees only one section (~5-15 paragraphs), keeping token usage low and quality consistent regardless of document length.

Going LLM-Minimal (v5): The Final Architecture

At this point I stepped back and asked: do I actually need an LLM for any of the remaining steps?

The DocExtractor

The DocExtractor agent received a prompt, called the extract_docx_files tool, and returned the tool's JSON output unchanged. The agent was a pure passthrough, it added zero value over calling the Python function directly.

The replacement is trivial:

from afw_core.tools.docx_extractor import _extract_all_docx

class DocExtractorDirectExecutor(Executor):

    def __init__(self, input_dir: str, output_dir: str):
        super().__init__(id="doc_extractor_direct")
        self._input_dir = input_dir
        self._output_dir = output_dir

    @handler
    async def handle(self, prompt: str, ctx: WorkflowContext[str]) -> None:
        results = _extract_all_docx(
            Path(self._input_dir), Path(self._output_dir),
        )
        result_json = json.dumps(results, ensure_ascii=False)
        ctx.set_state("extraction", result_json)
        await ctx.send_message(result_json)

One LLM call eliminated.

The TemplateAssembler

This is where I had to think harder. The LLM was converting text_segments JSON into Markdown. The segments already had type information:

{"type": "Title", "text": "6.1 Functional Overview"}
{"type": "NarrativeText", "text": "The system shall provide..."}
{"type": "Table", "text": "| Col1 | Col2 |..."}
{"type": "image", "text": "[IMAGE: img-003-a1b2c3d4.png]"}
{"type": "ListItem", "text": "Enable a user to capture a task in less than 10 seconds"}

I investigated what metadata unstructured provides. It turned out that Title elements have a category_depth field (0 for top-level headings, 1 for sub-headings), and heading numbering patterns (6.1, 6.1.2) can be used to infer deeper nesting.

The entire Markdown assembly became a for loop with type-based rules:

def _segments_to_markdown(text_segments: list[dict]) -> str:
    lines: list[str] = []
    prev_type: str | None = None

    for seg in text_segments:
        seg_type = seg.get("type", "")
        text = seg.get("text", "").strip()
        if not text:
            continue

        if prev_type == "ListItem" and seg_type != "ListItem":
            lines.append("")

        if seg_type == "Title":
            prefix = _heading_prefix(text)  # ## / ### / #### based on numbering
            lines.append(f"{prefix} {text}")

        elif seg_type == "ListItem":
            lines.append(f"- {text}")

        elif seg_type == "Table":
            lines.append(text)  # already Markdown from extractor

        elif seg_type == "image":
            fname = _extract_filename(text)
            lines.append(f"![Image](./images/{fname})")
            lines.append(f"<!--IMG:{fname}-->")

        else:  # NarrativeText, Text, etc.
            lines.append(text)

        prev_type = seg_type

    return "\n".join(lines)

Deterministic, instantaneous, zero cost. And the heading hierarchy is actually more consistent than what the LLM produced, because it follows strict rules rather than "inferring" structure.

Many more LLM calls eliminated.

The Final Workflow Graph

DocExtractorDirect ──▶ ParallelImageAnalyst ──▶ DeterministicAssembler ──▶ TemplateFillerMulti
   (Python)               (async Vision)             (Python)                  (Python)

LLM usage: only the N parallel vision calls for image descriptions. Everything else is pure Python.

The Workflow Builder

The wiring is clean and concise:

from agent_framework import WorkflowBuilder

def build_doc_ingest_tpl_multi_opt_workflow(input_dir: str, output_dir: str):
    extractor = DocExtractorDirectExecutor(input_dir, output_dir)
    analyst = ParallelImageAnalystExecutor()
    assembler = DeterministicAssemblerExecutor()
    filler = TemplateFillerMultiExecutor()

    return (
        WorkflowBuilder(start_executor=extractor)
        .add_edge(extractor, analyst)
        .add_edge(analyst, assembler)
        .add_edge(assembler, filler)
        .build()
    )

Notice: no client or options parameter. Since no executor uses an agent, there's no LLM client to inject. The ParallelImageAnalyst creates its own AsyncOpenAI client internally because it needs vision, not chat.

The Entry Point

The entry point consumes the workflow's event stream:

async def main():
    workflow = build_doc_ingest_tpl_multi_opt_workflow(INPUT_DIR, OUTPUT_DIR)

    async for event in workflow.run(
        f'input_dir="{INPUT_DIR}", output_dir="{OUTPUT_DIR}"',
        stream=True,
    ):
        if event.type == "executor_invoked":
            label = {
                "doc_extractor_direct": "📖 Extracting documents (direct)",
                "parallel_image_analyst": "🔍 Analysing images (parallel)",
                "deterministic_assembler": "📝 Assembling Markdown (deterministic)",
                "template_filler_multi": "🔧 Filling image descriptions",
            }.get(event.executor_id, event.executor_id)
            print(f"\n{label}...")

        elif event.type == "executor_completed":
            print(f"   ✓ {event.executor_id} completed")

        elif event.type == "output":
            assembled = AssembledDocumentList.model_validate_json(event.data)
            for doc in assembled.documents:
                print(f"   ✅ {doc.source_file} → {doc.output_path}")

Evolution Summary

Version	Entry Point	Architecture	LLM Calls	Key Change
v1	`main_doc_ingest.py`	Sequential agents	3 per file	Baseline
v2	`main_doc_ingest_wfl.py`	Workflow (3 executors)	3 per file	Graph-based, event streaming
v3	`main_doc_ingest_wfl_tpl.py`	Workflow (4 executors)	2 + N images	Template + filler pattern
v4	`main_doc_ingest_wfl_tpl_multi.py`	Workflow (4 executors)	N parallel + M chunks	Parallel vision, chunked assembly
v5	`main_doc_ingest_wfl_tpl_multi_opt.py`	Workflow (4 executors)	N parallel only	LLM-minimal: Python does the rest

The cost reduction from v1 to v5 is dramatic. For a document with 5 images and 10 sections, v1 makes ~8 LLM calls (3 agents). V5 makes exactly 5 (one per image, in parallel). The extraction and assembly are free.

Key Lessons Learned

Executors don't have to wrap agents. The framework's Executor class is a general-purpose processing unit. It can wrap an agent, call an API directly, or run pure Python logic. The best executors are often the ones with no LLM at all.

The template + filler pattern is widely applicable. Whenever you need an LLM to generate structured output with repetitive elements (tags, placeholders, formatting), consider splitting the task: let the LLM generate the structure, and let Python fill in the repetitive parts deterministically.

asyncio.gather with a semaphore is the right pattern for parallel API calls. It's simple, it respects rate limits, and it keeps you in control of concurrency. No need for complex job queues or thread pools.

unstructured gives you more metadata than you think. Before deciding to use an LLM for heading hierarchy, I checked what unstructured already provides. It turned out it has category_depth, parent_id, and typed elements (Title, ListItem, NarrativeText, Table), enough to build a complete Markdown document without any AI involvement.

Workflow versioning via file suffixes works well. Each iteration is a separate file (doc_ingest.py, doc_ingest_tpl.py, doc_ingest_tpl_multi.py, doc_ingest_tpl_multi_opt.py) with its own entry point. Previous versions are preserved for comparison and rollback. No git archaeology needed.

Conclusion: Takeaways

There is an old saying: "When all you have is a hammer, everything looks like a nail." Working with LLMs can feel exactly like that. You have this incredibly powerful tool that can understand language, generate text, analyze images, and it becomes tempting to route every step through it. Extraction? Let the LLM handle it. Assembly? The LLM can figure out the Markdown. Heading hierarchy? Surely the LLM knows best.

The single biggest takeaway from this project is that the best LLM call is the one you don't make. Before building v5, I assumed the extraction and assembly steps "needed" an LLM because they involved understanding document structure. They didn't. The extraction was already a Python tool behind an agent wrapper. The assembly was a deterministic mapping from typed segments to Markdown. The LLM added cost, latency, and randomness without adding value.

Stripping away those unnecessary calls didn't just save tokens. It made the pipeline faster, more predictable, and easier to debug. When something goes wrong in a pure Python executor, you get a stack trace, not a hallucination.

The MFA workflow model made this evolution natural. Because each step is an independent executor wired into a graph, I could replace an agent-based node with a pure Python node without touching anything else. The framework doesn't push you toward LLMs, it gives you the scaffolding and lets you decide what goes inside each node. That turned out to be exactly the right level of abstraction.

The pattern of wrapping agents inside executors and passing data through shared state also proved valuable for reuse. The same agent can be plugged into different workflows without modification, because the executor handles the wiring and the state handles the context. This, combined with a clean, well-defined workflow API, made it straightforward to evolve the solution incrementally, from a naive agent chain all the way to an aggressively optimized pipeline, without ever having to rewrite from scratch.

If the first article was about discovering the framework's building blocks, this one was about learning when not to use them. Use the LLM where it genuinely shines, like describing images. For everything else, write Python.

The generated Markdown files, with their embedded image descriptions, are ready for a RAG pipeline. A simple chunking strategy (split on headings, keep image descriptions with their context) would make both text and image content searchable through standard text embeddings, no multimodal retrieval model required.

All the code is available on GitHub (MSFTAgentSample). The PIPELINE_DOCX_TO_MD.md file documents all five variants with setup instructions and usage commands.

Microsoft Agent Framework: From Zero to Multi-Agent Pipeline

rosidotidev — Sun, 19 Apr 2026 09:53:25 +0000

I have some background with other agent frameworks like CrewAI and LangGraph, so when Microsoft released the Agent Framework, a lightweight Python package for building AI agents with native MCP (Model Context Protocol) support, I was curious to give it a try. I decided to build something practical: a pipeline that reads a product backlog from a Markdown file and automatically creates Epics and Stories on Jira. I chose this specific use case because I had already implemented it with CrewAI, so I was familiar with the configuration setup and could focus on comparing the frameworks rather than figuring out the integration details from scratch.

As reported in the official documentation, the Microsoft Agent Framework is the direct successor of both Semantic Kernel and AutoGen, created by the same Microsoft teams. It combines AutoGen's simple abstractions for single- and multi-agent patterns with Semantic Kernel's enterprise-grade features like session-based state management, type safety, telemetry, and extensive model support. On top of that, the Microsoft Agent Framework introduces workflows for explicit control over multi-agent execution paths and a robust state management system for long-running and human-in-the-loop scenarios.

What I found was a framework that favors simplicity and explicitness. You write Python functions, you wire them together, and you stay in control of the flow. In this article, I walk through the incremental approach I followed, from an "hello world" agent to a fully modular multi-agent pipeline.

You can find all the code shown in this post on this GitHub repo (MSFTAgentSample).

What I Used So Far

I have only scratched the surface of the framework, but here are the building blocks I worked with in this project:

Agent: the core class. You give it a name, instructions, a chat client, and a list of tools. It runs autonomously, deciding which tools to call and when to stop.
OpenAIChatClient: one of the available LLM providers. The framework integrates with most major LLMs, but for simplicity I used OpenAI since I still had some tokens to spend :-).
MCPStdioTool: a bridge to any MCP server. Point it at a command and it auto-discovers all available tools via the MCP protocol.
@tool: a decorator to turn any Python function into a tool the agent can invoke.

There is certainly more to explore, but these four primitives were enough to build a fully working multi-agent pipeline.

Step 1: Hello World, One Agent, No Tools

The very first thing I did was verify that the framework works. The simplest possible setup: one agent, one LLM client, one hardcoded query, no tools at all.

from __future__ import annotations
import asyncio
import os

from agent_framework import Agent
from agent_framework.openai import OpenAIChatClient, OpenAIChatOptions
from dotenv import load_dotenv


async def run_manager_agent(query: str) -> None:
    client: OpenAIChatClient = OpenAIChatClient(
        api_key=os.environ.get("OPENAI_API_KEY", ""),
        model=os.environ.get("OPENAI_CHAT_MODEL", "gpt-4o-mini"),
    )

    agent: Agent[OpenAIChatOptions] = Agent(
        client=client,
        name="ManagerAgent",
        instructions=(
            "You are a manager agent. Answer the user's query "
            "as accurately and concisely as possible."
        )
    )

    result = await agent.run(query)
    print(result.text)


def main() -> None:
    load_dotenv()
    query = "What is a Large Language Model and how does it work?"
    asyncio.run(run_manager_agent(query))


if __name__ == "__main__":
    main()

Mental Model: This is the equivalent of a "print hello world" in the agent framework world. You create a client, create an agent, call agent.run(), and print the result. Everything is async, so you need asyncio.run() as the entry point. The .env file provides the API key and model name via python-dotenv.

Notice how explicit everything is. There is no magic configuration, no auto-discovery. You pass the API key, you choose the model, you write the instructions. The agent's identity is fully defined by a single instructions string.

Step 2: Adding an MCP Tool (Jira)

Once the basics worked, the next step was connecting the agent to the real world. The Microsoft Agent Framework has first-class support for MCP (Model Context Protocol), which is the standard for exposing tools to AI agents. The mcp-atlassian package provides a full MCP server for Jira and Confluence.

import asyncio
import os
from dotenv import load_dotenv
from agent_framework import Agent, MCPStdioTool
from agent_framework.openai import OpenAIChatClient, OpenAIChatOptions

load_dotenv()

async def main():
    # MCP Proxy: auto-discovers all Jira tools via MCP protocol
    jira_proxy = MCPStdioTool(
        name="jira_server",
        command="pipenv",
        args=["run", "mcp-atlassian"],
        env={
            "JIRA_URL": os.getenv("JIRA_URL"),
            "JIRA_USERNAME": os.getenv("JIRA_USERNAME"),
            "JIRA_API_TOKEN": os.getenv("JIRA_API_TOKEN"),
        },
    )

    client = OpenAIChatClient(
        api_key=os.environ.get("OPENAI_API_KEY", ""),
        model=os.environ.get("OPENAI_CHAT_MODEL", "gpt-4o-mini"),
    )
    options = OpenAIChatOptions(temperature=0.0)

    jira_agent = Agent(
        name="JiraManagerAgent",
        instructions=(
            "You are a professional Project Management Assistant. "
            "You have direct access to Jira via integrated tools. "
            "Your goal is to help users manage tickets, track progress, "
            "and create issues."
        ),
        client=client,
        default_options=options,
        tools=[jira_proxy],
    )

    print("Jira Manager Agent is online...")

    user_query = """
        IMPORTANT: Execute each step below ONE AT A TIME.
        Step 1: Create an epic in the SARI project called 'Shopping List'.
        Step 2: Create a story: 'Story 1: Shopping List CRUD Angular UI' 
                and set the epic as parent.
        Step 3: Create a story: 'Story 2: Shopping List CRUD Angular 
                in memory mocked service' and set the epic as parent.
        Create issues one at a time, never in parallel.
    """

    try:
        response = await jira_agent.run(user_query)
        print("\nAgent Response:")
        print(response.text)
    finally:
        await jira_proxy.close()

if __name__ == "__main__":
    asyncio.run(main())

The key piece here is MCPStdioTool. You point it at a command (pipenv run mcp-atlassian), pass the necessary environment variables, and the framework auto-discovers every tool the MCP server exposes: jira_create_issue, jira_search, jira_get_issue, jira_link_to_epic, and many more. The agent sees all of them and decides which ones to call based on your query.

A Hard Lesson: Parallel Tool Calls

This step is where I hit my first real problem. When asked to create an epic and two stories, the agent would sometimes send multiple jira_create_issue calls in parallel. The second call would fail with a cryptic error: expected 'key' property to be a string. After adding debug logging and investigating, I discovered that the MCP server cannot handle parallel tool calls reliably.

The fix was surprisingly simple: tell the agent explicitly in its instructions to "Create issues ONE AT A TIME, never in parallel." This is a pattern I now apply consistently. If your MCP server doesn't handle concurrency well, just instruct the agent accordingly. It respects the instruction.

Step 3: Two-Agent Pipeline (Monolithic)

With the Jira integration working, I wanted to build something more structured: a pipeline with two agents collaborating sequentially. The idea was simple:

BacklogReaderAgent reads a Markdown backlog file from disk
JiraExecutorAgent takes the backlog content and creates all issues on Jira

To give agents the ability to read and write files, I used the @tool decorator to create custom function tools:

from typing import Annotated
from agent_framework import tool

@tool
def read_file(file_name: Annotated[str, "Name of the file to read"]) -> str:
    """Read and return the contents of a file from the input directory."""
    path = os.path.join("input", file_name)
    with open(path, "r", encoding="utf-8") as f:
        return f.read()

@tool
def write_file(content: Annotated[str, "The content to write"]) -> str:
    """Write content to a timestamped file in the output directory."""
    os.makedirs("output", exist_ok=True)
    timestamp = datetime.now().strftime("%Y%m%d_%H%M")
    file_name = f"execution_result_{timestamp}.md"
    path = os.path.join("output", file_name)
    with open(path, "w", encoding="utf-8") as f:
        f.write(content)
    return f"File written: {path}"

The Annotated[str, "description"] syntax is how you document parameters for the agent. The framework reads these annotations and exposes them as part of the tool schema, so the LLM knows what to pass.

Then, the two agents and the orchestration logic, all in one file:

    # Agent 1: reads the backlog file
    reader_agent = Agent(
        name="BacklogReaderAgent",
        instructions=(
            "You are a backlog reader assistant. "
            "When asked, use the read_file tool to read a markdown file. "
            "Return the full contents of the file as-is."
        ),
        client=client,
        default_options=options,
        tools=[read_file],
    )

    # Agent 2: executes the backlog on Jira
    executor_agent = Agent(
        name="JiraExecutorAgent",
        instructions=(
            "You are a Jira execution assistant. "
            "Create issues ONE AT A TIME, never in parallel. "
            "After all operations, write a summary using write_file."
        ),
        client=client,
        default_options=options,
        tools=[jira_proxy, write_file],
    )

    # Orchestration: sequential pipeline
    read_response = await reader_agent.run(
        f"Read the file '{backlog_file}' and return its contents."
    )
    backlog_content = read_response.text

    exec_response = await executor_agent.run(
        f"Execute the following backlog on Jira.\n\n{backlog_content}"
    )

Mental Model: Notice that the orchestration is plain Python. There is no pipeline abstraction, no DAG. You call agent.run(), get the result, and pass it to the next agent. You are the orchestrator.

The backlog file is a simple Markdown document placed in the input/ directory:

# Weather Dashboard Backlog - SARI Project

## Epic: Weather Dashboard
- Type: Epic
- Description: Real-time weather dashboard application.

### Stories

- **Story 1: City Search and Autocomplete**
  - Type: Story
  - Description: Implement a search bar with autocomplete...

- **Story 2: Current Weather Display**
  - Type: Story
  - Description: Show current weather conditions...

The agent reads this, understands the structure, and creates the epic first, then each story linked to the epic as parent. All on Jira, automatically.

Step 4: Modular Pipeline with Pydantic Validation

The monolithic version worked perfectly, but everything was in one file. For a production-ready layout, I refactored the code into a well-structured directory:

MSFTAgentSample/
├── afw_core/
│   ├── agents/
│   │   ├── backlog_reader.py
│   │   └── jira_executor.py
│   ├── tools/
│   │   ├── file_reader.py
│   │   └── file_writer.py
│   ├── mcps/
│   │   └── jira.py
│   ├── llms/
│   │   └── openai.py
│   └── models/
│       └── backlog.py
│
├── input/
│   └── backlog.md
├── output/
├── main_backlog_from_md_std.py
└── .env

Each module has a single responsibility and exposes a factory function. For example, the agent definitions:

# afw_core/agents/backlog_reader.py
from agent_framework import Agent

def create_agent(client, options, tools):
    return Agent(
        name="BacklogReaderAgent",
        instructions=(
            "You are a backlog reader assistant. "
            "When asked, use the read_file tool to read a markdown file. "
            "After reading, respond with ONLY a JSON object matching this schema: "
            '{"epic_count": <int>, "story_count": <int>, "description": <string>}.'
        ),
        client=client,
        default_options=options,
        tools=tools,
    )

# afw_core/agents/jira_executor.py
from agent_framework import Agent

def create_agent(client, options, tools):
    return Agent(
        name="JiraExecutorAgent",
        instructions=(
            "You are a Jira execution assistant. "
            "Create issues ONE AT A TIME, never in parallel. "
            "When linking stories to an epic, first create the epic, "
            "then create each story and set the epic as parent. "
            "After all operations, write a summary using write_file."
        ),
        client=client,
        default_options=options,
        tools=tools,
    )

The convention I adopted is: name and instructions are hardcoded inside the factory function (they are intrinsic to the agent's identity), while client, options, and tools are always injected from outside (they are infrastructure concerns). This separation keeps agent definitions clean and reusable.

Pydantic for Structured Output

A key improvement in the modular version was adding Pydantic validation between the two agents. Instead of passing raw text from the reader to the executor, I defined a model:

# afw_core/models/backlog.py
from pydantic import BaseModel

class BacklogOutput(BaseModel):
    epic_count: int
    story_count: int
    description: str

The reader agent is instructed to return JSON matching this schema. The main script validates it:

from afw_core.models.backlog import BacklogOutput

read_response = await reader_agent.run(
    f"Read the file '{backlog_file}' and return its contents."
)
backlog = BacklogOutput.model_validate_json(read_response.text)
print(f"Backlog loaded: {backlog.epic_count} epic(s), {backlog.story_count} stories")

If the agent returns malformed JSON, Pydantic throws a validation error immediately, rather than letting corrupted data propagate to the executor agent. This is a simple but effective pattern for inter-agent data contracts.

The Entry Point

The modular entry point becomes clean orchestration logic with no implementation details:

# main_backlog_from_md_std.py
import asyncio
import os
from dotenv import load_dotenv

from afw_core.llms.openai import create_client
from afw_core.mcps.jira import create_proxy
from afw_core.tools.file_reader import read_file
from afw_core.tools.file_writer import write_file
from afw_core.agents.backlog_reader import create_agent as create_reader_agent
from afw_core.agents.jira_executor import create_agent as create_executor_agent
from afw_core.models.backlog import BacklogOutput

load_dotenv()

async def main():
    client, options = create_client(
        api_key=os.environ.get("OPENAI_API_KEY", ""),
        model=os.environ.get("OPENAI_CHAT_MODEL", "gpt-4o-mini"),
    )
    jira_proxy = create_proxy()

    reader_agent = create_reader_agent(client=client, options=options, tools=[read_file])
    executor_agent = create_executor_agent(client=client, options=options, tools=[jira_proxy, write_file])

    # Step 1: Read and validate
    read_response = await reader_agent.run("Read the file 'backlog.md' and return its contents.")
    backlog = BacklogOutput.model_validate_json(read_response.text)

    # Step 2: Execute on Jira
    try:
        exec_response = await executor_agent.run(
            f"Execute the following backlog on Jira.\n\n{backlog.description}"
        )
        print(exec_response.text)
    finally:
        await jira_proxy.close()

if __name__ == "__main__":
    asyncio.run(main())

How you can see, the entry point reads like a recipe: create the infrastructure, create the agents, run them in sequence, handle cleanup. All the complexity lives in the modules under afw_core/.

The Pipeline in Action

Here is what the pipeline produces when you run it against a real Jira project:

Jira board after execution: the Epic and all linked Stories created automatically.

Console output: the full agent execution log showing each tool call and result.

Execution report: the summary file generated by the executor agent in the output/ directory.

Key Lessons Learned

Working through these four steps, several patterns emerged that are worth sharing:

MCP tools don't handle parallelism well. When the LLM sends multiple tool calls in a single response, the MCP server may fail. The workaround is simple: add "ONE AT A TIME" to the agent's instructions. The agent respects this.

The framework's error handling has a hidden default. The max_consecutive_errors_per_request parameter defaults to 3. If an agent hits 3 consecutive tool errors, it stops retrying. This is defined in agent_framework._tools and caught me off guard initially. Knowing this default helps you debug "why did it stop?" scenarios.

No __init__.py needed. Python's implicit namespace packages work fine. The key is choosing a unique directory name (afw_core) that doesn't collide with installed packages. I initially tried naming directories agents/, tools/, mcp/, but these collided with the framework's own modules. Renaming to afw_core/agents/ solved everything.

A well-defined directory structure makes a real difference. Applying a clear project layout (afw_core/ with separate modules for agents, tools, MCP proxies, LLM clients, and models) greatly simplifies working with the framework. It keeps things organized and makes the codebase easy to extend as you add more agents and integrations.

The biggest gap today: no native tools. This is, in my opinion, the framework's main weakness right now. Other frameworks like LangChain/LangGraph and CrewAI ship with a rich ecosystem of built-in tools (web search, PDF readers, database connectors, vector stores, and many more). With the Microsoft Agent Framework, you either build every tool yourself with @tool or rely on MCP servers. For simple use cases that's fine, but for projects that need quick access to common integrations, the lack of native tools is a significant disadvantage that other frameworks still handle much better.

Pydantic validation between agents is cheap insurance. It adds minimal overhead and catches data corruption early. Especially useful when the first agent's output is the second agent's input.

Agent instructions are powerful. You have a single instructions string that gives you full freedom to express exactly what you need, including operational constraints like "never call tools in parallel."

Conclusion: Takeaways

The Microsoft Agent Framework is a solid entry point into the world of AI agent development. Its explicit, code-first approach means there are very few surprises: what you write is what gets executed. The MCP integration is first-class and makes it trivial to connect agents to external services like Jira, Confluence, or GitHub.

The incremental approach I followed, from a single agent with no tools to a modular multi-agent pipeline, worked well as a learning strategy. Each step introduced exactly one new concept, making it easy to debug when things went wrong.

If you are starting with AI agents and want a framework with minimal abstraction, the Microsoft Agent Framework is worth a try. The codebase in this article serves as a progressive tutorial you can follow step by step.

All the code is available on GitHub (MSFTAgentSample).

In-Depth Comparison: Workflow Control with LangGraph and CrewAI

rosidotidev — Fri, 01 Aug 2025 15:47:07 +0000

(Originally published on my blog: https://roby73.hashnode.dev/in-depth-comparison-workflow-control-with-langgraph-and-crewai)
Choosing between CrewAI and LangGraph for multi-agent orchestration isn’t trivial, especially for developers balancing rapid prototyping with future scalability.

Personally, I gravitate toward CrewAI for its straightforward setup and developer-friendly abstractions. It lets you build production-ready agent flows in minutes, staying focused on business logic rather than complex orchestration architecture. That ease of use and quick iteration cadence make CrewAI a great fit for many projects.

That said, LangGraph has quickly become the go-to framework for large, stateful projects in production, thanks to its expressive graph-based DSL and wide adoption among major tech players. It offers granular control over state, dependencies, and memory, which is often necessary for complex or long-running workflows.

Absolute Control Over Agent Steps: LangGraph vs. CrewAI

One of LangGraph’s undeniable strengths is the absolute control it offers over every single step executed by agents in the workflow. Thanks to its explicit graph-based architecture, you precisely define nodes, edges, and state transitions. This granular orchestration lets you monitor, intervene, and debug the entire flow of execution with full visibility.

In contrast, CrewAI’s abstraction via agents and tasks simplifies setup and speeds development, but sometimes this comes at the cost of less direct visibility and control over internal step execution. The orchestration logic is more implicit and "black-boxed" inside the Crew abstractions, which can make fine-grained intervention more challenging.

That said, with the introduction of Flows in CrewAI—explicitly defined workflows coordinating agents and tasks—you can reclaim a similar level of control and transparency over execution. The Flows feature lets you model sequences, conditions, and branching explicitly, reducing the "black box" effect while still keeping CrewAI’s ease of use.

The Java Verifier examples below provide a clear demonstration of this: while LangGraph exposes every node and edge explicitly, CrewAI Flows allow similarly controlled stepwise execution and monitoring inside a more developer-friendly environment.

Example: The Java Verifier

To illustrate the difference in abstraction and workflow style between CrewAI and LangGraph, here is a minimal “Verifier” agent implementation in both frameworks. The goal of this verifier is to validate, correct, and optimize small Java code snippets. The workflow is designed with a loop: it first checks the code for syntax errors. If an error is found, it attempts to correct the code and then re-enters the verification step. This "verify-correct" loop continues until the code is deemed syntactically correct. Only then does the workflow proceed to the final step of optimizing the code for readability and performance. You can find all the code shown in this post on this Github repo (Java-Verifier-LangGraph-CrewAI)

1. CrewAI: Java Verifier with Flow

(This image has been generated using the functionality at the end of the provided Python code)

CrewAI Flows allow you to define a multi-agent workflow in a class-based structure that feels familiar to developers. You declare agents and then use decorators (@start, @router, @listen) to map out the flow. This structure keeps the logic contained and easy to read. For this particular example, we chose to orchestrate the individual agents directly within the Flow rather than using a complete Crew. This approach gives us more direct control over each agent's step, which was ideal for this straightforward, cyclical process. It's important to note that in more complex scenarios, CrewAI's flexibility allows you to orchestrate entire Crews of agents, leveraging their collective intelligence for a different level of abstraction.

from typing import Any, Dict, List
from dotenv import load_dotenv
from pydantic import BaseModel, Field

from crewai.agent import Agent
from crewai.flow.flow import Flow, listen, start, router

load_dotenv()

class CodeValidationState(BaseModel):
    code: str = ""
    syntax_status: str = ""

class JavaCodeValidationFlow(Flow[CodeValidationState]):

    analyzer_agent = Agent(
        role="Java code syntax analyzer",
        goal="Receive Java code and reply exactly with 'correct' or 'incorrect' based on syntax.",
        backstory="You are a meticulous and precise code quality tool."
    )

    corrector_agent = Agent(
        role="Java code corrector",
        goal="Receive syntactically incorrect Java code and return corrected code with valid syntax only. Return only Java code with no explanation and no markdown",
        backstory="You are an expert Java programmer who fixes code errors.",
        verbose=True
    )

    optimizer_agent = Agent(
        role="Java code optimizer",
        goal="Receive syntactically correct Java code and optimize it for readability and performance without changing logic. Return only Java compilable code with no explanation and no markdown",
        backstory="You are a senior developer specializing in code optimization."
    )

    @start("try_again")
    def start_analysis(self):
        """Starts the workflow, sends the code to the analyzer."""
        print(f"Starting code analysis...\n {self.state.code}")
        result = self.analyzer_agent.kickoff(self.state.code)
        syntax_status = result.raw
        self.state.syntax_status = syntax_status
        print(f"Analyzer result: {syntax_status}")

    @router(start_analysis)
    def conditional_next_step(self):
        """Decides whether to proceed with correction or optimization."""
        syntax_status = self.state.syntax_status
        print(f"conditional_next_step {syntax_status}")
        if syntax_status=="correct":
            return "correct"
        else:
            return "incorrect"

    @router("incorrect")
    def correct_code_step(self):
        """Performs code correction."""
        result = self.corrector_agent.kickoff(self.state.code)
        print(f"Corrector: code corrected.\n {result.raw}")
        self.state.code = result.raw
        return "try_again"

    @listen("correct")
    def optimize_code_step(self):
        """Performs code optimization."""
        result = self.optimizer_agent.kickoff(self.state.code)
        self.state.code = result.raw
        print("Optimizer: optimization finished.")
        print("\nWorkflow complete. Final optimized code:")
        print("---" * 20)
        print(self.state.code)
        print("---" * 20)

# Example usage of the workflow
def run_code_validation_flow():
    # Initial Java code with a syntax error (missing semicolon)
    initial_java_code = """
    public class Test {
        public static void main(String[] args) {
            System.out.println("Hello, World!"
        }
    }
    """
    flow = JavaCodeValidationFlow()

    print("Starting CrewAI Java code validation flow...\n")
    # Start the workflow and get the final result
    flow.kickoff(inputs={"code": initial_java_code})
    return flow

if __name__ == "__main__":
    flow=run_code_validation_flow()
    flow.plot('my_flow_plot')

Mental Model: In CrewAI, you first define the roles and goals of your agents. Then, you use a Flow to orchestrate them through a series of steps. The flow itself feels like a regular class with methods, where decorators handle the routing logic. This keeps the logic contained and aligned with a developer's class-based thinking. Notice that here we are using default LLM used by CrewAI that at the minute is “gpt-4o-mini“.

2. LangGraph: Java Verifier with Graph

(This image has been generated using the functionality at the end of the provided Python code)

LangGraph's approach is more explicit and foundational. You define a graph with nodes and edges, where each node is a function. The state of the workflow is passed explicitly between nodes, and conditional edges are used to manage the flow.

import os
from langgraph.graph import StateGraph, END
from dotenv import load_dotenv
from typing import TypedDict, Annotated  # Import TypedDict and Annotated
from langgraph.types import Command
from langchain_openai import OpenAI
from IPython.display import Image, display
# Ensure your OpenAI API Key is set in environment variable OPENAI_API_KEY
load_dotenv()
# Define your state schema
class CodeState(TypedDict):
    code: str
    is_correct: bool
class JavaVerifierGraph(StateGraph):
    def __init__(self):
        # Initialize LangChain OpenAI wrapper (reads OPENAI_API_KEY from env)
        self.llm = OpenAI(model="gpt-4o-mini", temperature=0)
        workflow = StateGraph(CodeState)
        workflow.add_node("start_analysis_node", self.start_analysis_node)
        workflow.add_node("optimize_code_node", self.optimize_code_node)
        workflow.add_node("correct_code_node", self.correct_code_node)

        # Define entry and transitions
        workflow.set_entry_point("start_analysis_node")
        # Conditional edges from analyzer node
        workflow.add_conditional_edges("start_analysis_node",
                                       self.conditional_next_node,
                                       {"optimize_code_node": "optimize_code_node",
                                        "correct_code_node": "correct_code_node"})
        # Cycle back from corrector to analyzer
        workflow.add_edge("correct_code_node", "start_analysis_node")
        self.graph = workflow.compile()



    def llm_check_code_syntax(self,code: str) -> bool:
        prompt = (
            "Check if the following Java code is syntactically correct. "
            "Reply ONLY with 'correct' or 'incorrect'.\n\n"
            f"Java code:\n{code}\n\nAnswer:"
        )
        result = self.llm(prompt)
        return result.strip().lower() == "correct"

    def llm_correct_code(self,code: str) -> str:
        prompt = (
            "Correct the following Java code to be syntactically valid. "
            "Provide only the corrected code without explanations.\n\n"
            f"Java code:\n{code}\n\nCorrected Java code:"
        )
        return self.llm(prompt).strip()

    def llm_optimize_code(self,code: str) -> str:
        prompt = (
            "Optimize the following syntactically correct Java code "
            "for readability and performance. Return only Java code with no explanation and no markdown.\n\n"
            f"Java code:\n{code}\n\nOptimized Java code:"
        )
        return self.llm(prompt).strip()

    # The analyzer node sets 'is_correct' in state to guide conditional branching,
    # no explicit goto inside the node function.
    def start_analysis_node(self,state:CodeState):
        code = state["code"]
        print("Analyzer: Checking syntax via LLM...")
        is_correct = self.llm_check_code_syntax(code)
        print(f"Analyzer: Code is {'correct' if is_correct else 'incorrect'}")
        return Command(update={"is_correct": is_correct})

    # Optimizer node - performs optimization and ends the workflow.
    def optimize_code_node(self,state:CodeState):
        code = state["code"]
        print("Optimizer: Optimizing code via LLM...")
        optimized_code = self.llm_optimize_code(code)
        print("Optimizer: Optimization complete. Ending workflow.")
        return Command(update={"code": optimized_code}, goto=END)

    # Corrector node - fixes syntax errors; no goto, flow cycles via explicit edge.
    def correct_code_node(self,state:CodeState):
        code = state["code"]
        print("Corrector: Correcting code via LLM...")
        corrected_code = self.llm_correct_code(code)
        print("Corrector: Correction complete. Returning to analyzer.")
        return Command(update={"code": corrected_code})

    # Branching function to decide next node after analyzer based on 'is_correct'.
    def conditional_next_node(self,state:CodeState):
        return "optimize_code_node" if state.get("is_correct") else "correct_code_node"

    def run_workflow(self,code):
        initial_state = {
            "code": code,
            "is_correct": True  # 'analyzer' will set this value at the beginning
        }

        print("Starting the execution of the workflow with invoke()...\n")

        # Run the workflow and get the final state
        final_state = self.graph.invoke(initial_state)

        print("\nWorkflow completed!")
        print("-" * 50)
        print("Final Java code (corrected and optimized):\n")
        print(final_state["code"])
        print("-" * 50)
        print(f"Final 'is_correct' state: {final_state['is_correct']}")

    def get_graph(self):
        return self.graph.get_graph()


def run_code_validation_flow():

    initial_code = """
    public class Test {
        public static void main(String[] args) {
            System.out.println("Hello World!")
        }
    }
    """

    initial_state = {
        "code": initial_code,
        "is_correct": True  # 'analyzer' will set this value at the beginning
    }

    print("Starting the execution of the workflow with invoke()...\n")

    graph=JavaVerifierGraph()
    final_state = graph.run_workflow(initial_state)


    return graph

if __name__ == "__main__":
    graph=run_code_validation_flow()
    # This command generates the PNG data as bytes, which works outside of Jupyter
    mermaid_png_bytes = graph.get_graph().draw_mermaid_png()

    # Specify the filename for the output image
    output_filename = "langgraph_workflow.png"

    try:
        # Open the file in binary write mode ('wb')
        with open(output_filename, "wb") as f:
            # Write the image bytes to the file
            f.write(mermaid_png_bytes)
        print(f"Diagram sevaed on {output_filename}")
    except Exception as e:
        print(f"Error during diagram generation: {e}")

Mental Model: With LangGraph, you build the workflow by explicitly defining a state schema, followed by individual nodes (functions). You then connect these nodes with edges. The orchestration logic is literally a graph you construct, giving you a powerful, albeit more complex, low-level tool for state management.

Conclusion

I appreciate CrewAI’s lean, quick-to-launch workflows and developer experience, which speed up prototyping and smaller scope projects. The Flow feature adds a layer of explicit control that bridges the gap with more low-level frameworks. Meanwhile, LangGraph stands out for heavyweight, scalable AI pipelines in enterprise-grade systems with a need for full-control graph orchestration.

To gain a more complete understanding of each framework's workflow implementation capabilities, other critical aspects must be considered. These include state management, the ability to handle state persistence (saving and resuming a workflow), and the ease of implementing a Human-in-the-Loop (HITL) scenario. These factors are crucial for designing robust, long-running processes that require durability or external intervention.

For the time being, CrewAI fits my development style best, but I watch LangGraph’s evolution with interest as it appears to be solidifying its place as the go-to framework for complex AI agent orchestration at scale.

Crewai

rosidotidev — Wed, 30 Jul 2025 18:47:56 +0000

Spring.ai

rosidotidev — Sun, 27 Jul 2025 13:19:05 +0000

DEV Community: rosidotidev

BMAD Method (Part 1): Spec-Driven Development Where the Human Stays in Control

What Is Spec-Driven Development?

BMAD in a Nutshell

Why It Is Built This Way

Setting Up

A Simple Example: a Todo List

Path One: Adding a Flag to a Todo List I Already Have

Path Two: Writing a Todo List From Scratch

What BMAD Writes to Disk

What the Method Gives You

What the Method Does Not Give You

The Role of the Human

Takeaways

What Comes Next

Agents-skill

Spec-Driven Development in Practice: Porting RoomBook from Spring Boot to NestJS

The Goal, Stated as Constraints

Two Decisions Before the First Command

Step 1: Constitution, as a Minor Amendment

Step 2: Specify, Without a Single Framework Name

Step 3: Plan, the Place Where the Stack Enters

Step 4: Checklist and Tasks, Test First

Step 5: Implement and Converge, One Phase at a Time

An Amendment in the Middle of the Migration

The Parity Gate, and Where I Stopped

What the Process Gave Me

What the Process Taught Me

Takeaways

What Comes Next

Spec-Driven Development in Practice: Building RoomBook with GitHub Spec Kit

The Example: RoomBook

Step 0: Init and Constitution

One Cycle, Five Times

Backend Feature: Bookings API

Frontend Feature: Bookings UI

What Spec Kit Leaves in the Repository

What Was Built: Backend and Frontend

What the Tool Gives You

What the Tool Does Not Give You

Takeaways

What Comes Next

Spec-Driven Development with GitHub Spec Kit (Part 1): The Theory

What Is Spec-Driven Development?

The Specification as a Contract

GitHub Spec Kit in a Nutshell

A Simple Example: a Todo List

The Role of the Human

Takeaways

Github copilota spec

Karpathy's LLM Wiki? No Code with Claude or Github Copilot!

What Is an LLM Wiki?

Why No-Code?

The Three Core Operations

1. /wiki-ingest, Build Your Knowledge Base

2. /wiki-query, Ask Questions Without Hallucination

3. /wiki-lint, Maintain Health

The Directory Structure

Three Page Types

How It Works: The Human-Gated Loop

Getting Started: A Practical Example

The Configuration Layer: .claude/ and .github/

.claude/ Directory, Claude Code Configuration

.github/ Directory, GitHub Copilot Configuration

Key Design Choices

What's Not Included (Yet)

Takeaways

Microsoft Agent Framework: From Agents to Workflows, Five Iterations of a DOCX-to-Markdown Pipeline

MFA Workflows in 30 Seconds

The Use Case

The Starting Point: Agents Only (v1)

What Broke and Why

Introducing Workflows (v2)

The Template + Filler Pattern (v3)

Scaling Up (v4): Parallel Vision + Chunked Assembly

Going LLM-Minimal (v5): The Final Architecture

The DocExtractor

The TemplateAssembler

The Final Workflow Graph

The Workflow Builder

1. `/wiki-ingest`, Build Your Knowledge Base

2. `/wiki-query`, Ask Questions Without Hallucination

3. `/wiki-lint`, Maintain Health

The Configuration Layer: `.claude/` and `.github/`

`.claude/` Directory, Claude Code Configuration

`.github/` Directory, GitHub Copilot Configuration