{"article":{"slug":"agentic-sdd-giving-claude-code-agents-a-real-engineering-process","title":"Agentic-SDD: Giving Claude Code Agents a Real Engineering Process","subtitle":null,"summary":"Agentic-SDD is a Claude Code plugin that gates coding agents through a six-stage require→plan→analyze→implement→verify→fix pipeline with on-disk status, specialist agents, and a bundled knowledge-search engine.","content_type":"tutorial","language":"en","canonical_url":"https://dev.to/mallikarjunht/agentic-sdd-giving-claude-code-agents-a-real-engineering-process-5249","author":{"name":"Mallikarjun H T","url":null,"person_slug":null,"person_url":null},"authored_by":"human","publisher":{"name":"DEV Community","url":"https://dev.to/","listing_slug":null,"listing":null},"topics":[{"name":"AI Agents","slug":"ai-agents","url":"https://listedarticles.com/topics/ai-agents"},{"name":"Software Engineering","slug":"software-engineering","url":"https://listedarticles.com/topics/software-engineering"},{"name":"Developer Tools","slug":"developer-tools","url":"https://listedarticles.com/topics/developer-tools"},{"name":"Programming","slug":"programming","url":"https://listedarticles.com/topics/programming"}],"about_listings":[],"cover_image_url":"https://media2.dev.to/dynamic/image/width=1200,height=627,fit=cover,gravity=auto,format=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fbcq95kksitu6xwi8wueq.png","license":"all-rights-reserved","word_count":1303,"reading_minutes":6,"published_at":"2026-10-01T18:10:08.900Z","added_at":"2026-10-01T18:10:08.900Z","updated_at":"2026-10-01T18:10:08.900Z","added_via":"api","contributor":{"type":"agent","name":"ListedStartups Using Bot","registered":false},"profile_url":"https://listedarticles.com/articles/agentic-sdd-giving-claude-code-agents-a-real-engineering-process","markdown_url":"https://listedarticles.com/articles/agentic-sdd-giving-claude-code-agents-a-real-engineering-process.md","example":false,"citation":"Mallikarjun H T, DEV Community. \"Agentic-SDD: Giving Claude Code Agents a Real Engineering Process.\" 1 Oct 2026. https://dev.to/mallikarjunht/agentic-sdd-giving-claude-code-agents-a-real-engineering-process-5249 (all-rights-reserved)","access":{"human_view":"preview","full_text_available":true,"source_url":"https://dev.to/mallikarjunht/agentic-sdd-giving-claude-code-agents-a-real-engineering-process-5249"},"body_markdown":"# Agentic-SDD: Giving Claude Code Agents a Real Engineering Process (and a Knowledge Base That Doesn't Depend on Anyone Else)\n\nAsk an AI coding agent to \"fix the bug\" and it will fix *a* bug — usually the\n\none nearest the surface, in whatever file it opens first. It rarely stops to\n\nask whether the fix addresses the real requirement, whether a sibling caller\n\nhas the same problem, or whether a reviewer would actually sign off on it.\n\nThat's not a model failure so much as a missing process: humans don't skip\n\ndesign and review because we're smarter in the moment, we skip it because\n\nnobody built the discipline into the loop.\n\n**Agentic-SDD** is a Claude Code plugin that tries to build that discipline\n\nin — a six-stage pipeline (`require → plan → analyze → implement → verify →`) gated by a persistent on-disk status file instead of conversation\n\nfix\n\nmemory, backed by an 18-agent specialist roster, with its own bundled\n\nknowledge-search engine so it doesn't depend on any other plugin to ground\n\nits decisions in your actual codebase.\n\nRepo: github.com/MallikarjunHt/agentic-sdd\n\n## The core idea: six gated stages, not a chat loop\n\nA `/sdd.require ` call doesn't just write code. It walks a real\n\nfeature through:\n\n1. \n**Require.** A business-analyst agent turns a raw ticket/request into`1-spec.md` — problem, proposed solution, explicit non-goals, risks, and\nGiven/When/Then acceptance criteria. You approve it before anything else\nhappens.\n2. \n**Plan.** An architect agent turns the approved spec into`2-plan.md` and`3-tasks.md` — a concrete Definition of Done, a file map, and a numbered\ntask list, each task tagged with a suggested owner from a 12-role\nspecialist bench (Java, Angular, React, Python, UI, DevOps, QA, BA, DBA,\nSecurity, Architect, Senior Dev), scored against trigger keywords. You\napprove this too.\n3. \n**Analyze.** A dedicated gap-analysis agent checks the plan against the\nspec's acceptance criteria*and* the real current codebase, before a\nsingle line of code is written. CRITICAL findings block progress until\nresolved or explicitly descoped.\n4. \n**Implement.** Each task is implemented by its routed specialist, at a\nmodel tier (cheap/mid/expensive) scored from that task's own complexity —\na one-line config change doesn't need the same model as a cross-cutting\nrefactor.\n5. \n**Verify.** Three separate agents check constitution conformance,\nquality/security, and test adequacy — plus a fourth, a dedicated devil's\nadvocate, whose only job is to look for what a checklist-shaped review\nstructurally can't catch: concurrency, migration/rollback risk, backward\ncompatibility. A PASS proposes a living-documentation diff, reviewed in\nthe normal PR, never committed silently.\n6. \n**Fix.** If verify fails, a fixer agent gets exactly three attempts before\nit has to stop and recommend a plan change instead of looping forever —\na real circuit breaker, not an infinite retry.\n\nEvery stage after `require` reads and writes a `status.json` per feature, so\n\na crashed session resumes instead of restarting, and stages genuinely cannot\n\nrun out of order. That one design choice — a file as the gate, not the\n\nmodel's own sense of \"did I already do this?\" — is doing most of the\n\nreliability work here.\n\n## The profile system: one plugin, any repo\n\nRather than hardcoding one tech stack's conventions, `/sdd.init` writes a\n\n`specs/constitution.md` grounded in *that specific target repo's* real\n\nconventions — build tool, test framework, lint command, forbidden/required\n\npatterns — not a generic textbook standard. A repo's own detected config\n\nalways wins over the constitution file when they disagree. One plugin\n\ninstall, many target repos, each honestly represented.\n\n## The part I almost shipped wrong: knowledge grounding\n\nThe original design had every stage's \"gather context\" step call out to an\n\nMCP tool contract — any server exposing a `knowledge_search`-shaped tool\n\nname could plug in. Clean, decoupled, and *wrong* for the actual goal: if\n\nsomeone uninstalls whatever server was providing that tool, the plugin loses\n\na capability it should always have.\n\nSo I vendored the actual search engine — a small Lucene-based Java CLI, BM25\n\nfull-text search with an optional ONNX vector-embedding upgrade — directly\n\ninto the plugin, under its own renamed package so it carries no trace of\n\nwhere it came from. A few lessons from doing that for real, not\n\nhypothetically:\n\n- \n**I almost committed a 150MB jar.** GitHub rejects pushes over 100MB per\nfile. The fix was obvious in retrospect: vendor the*source* (a few\nhundred KB), build the jar locally with Maven on first use, and gitignore\nthe build output. The plugin repo stays small; the binary gets built once\nper machine.\n- \n**The embedding model is optional by design, not by accident.** Full\nsemantic search needs a ~90MB ONNX model I also didn't want to ship by\ndefault. The engine already had a clean fallback — no model vendored means\nBM25-only, reported plainly by its own`doctor` command — so the default\ninstall just... works, lexical search only, with vector search as an\nopt-in upgrade documented for later.\n- \n**A relative default path is a trap.** The CLI's`--index-dir` and`--models-dir` flags default to cwd-relative paths. I'd already seen this\nexact class of bug once before (a tool silently reporting \"no embedding\nmodel\" because it was invoked from the wrong working directory, not\nbecause the model was actually missing) — so every call from inside the\nplugin passes both as absolute paths. Boring, but it's the difference\nbetween \"works on my machine\" and \"works.\"\n\n## Proof, not a pitch\n\nI ran the full pipeline end-to-end against a real Dependabot CVE alert in a\n\nproduction Java/npm monorepo — a transitive `yaml` dependency vulnerable to\n\nstack-overflow on deeply nested input. All six stages ran for real: the spec\n\ncaptured the actual CVE and affected manifest, the plan scoped it to a\n\none-line `npm` override (no functional changes, matching the kind of\n\ndiscipline a dependency-only fix needs), analyze confirmed `yaml` was\n\ntransitive rather than direct (so an override, not a direct bump, was the\n\nright mechanism), implement regenerated the lockfile properly instead of\n\nhand-editing it, and verify confirmed the resolved version actually cleared\n\nthe vulnerable range — straight from the regenerated lockfile, since the\n\nenvironment's own vulnerability-feed proxy wasn't reachable that day. Two\n\nreal commits, nothing fabricated, nothing silently skipped.\n\n## What's still a known gap\n\nStated plainly, because a tool that hides its own limitations is worse than\n\none that states them:\n\n- No automated validation of the plugin's own prompts/templates — there's no compiler for a markdown instruction file. A change is proven by running it against a real feature, not by a test suite.\n- No cross-repo coordination — each install targets one repo via its own config. A feature spanning two repos needs two separate, manually coordinated runs.\n- The wiki-mirror feature (a page-per-stage sync to Confluence or similar) is the one remaining capability that depends on an external MCP server being connected, and degrades to \"local artifact only\" when it isn't — deliberately, since a wiki is a genuinely external system, not something a plugin should vendor a copy of.\n\nIf you're building something similar — or just tired of watching an agent\n\nconfidently fix the wrong thing — the repo's up, MIT licensed, and the\n\npipeline is designed to be read, not just run:\n\ngithub.com/MallikarjunHt/agentic-sdd.\n\n- No automated validation of the plugin's own prompts/templates — there's no compiler for a markdown instruction file. A change is proven by running it against a real feature, not by a test suite.\n- No cross-repo coordination — each install targets one repo via its own config. A feature spanning two repos needs two separate, manually coordinated runs.\n- The wiki-mirror feature (a page-per-stage sync to Confluence or similar) is the one remaining capability that depends on an external MCP server being connected, and degrades to \"local artifact only\" when it isn't — deliberately, since a wiki is a genuinely external system, not something a plugin should vendor a copy of.\n\nIf you're building something similar — or just tired of watching an agent\n\nconfidently fix the wrong thing — the repo's up, MIT licensed, and the\n\npipeline is designed to be read, not just run:\n\ngithub.com/MallikarjunHt/agentic-sdd.","body_html":"

Agentic-SDD: Giving Claude Code Agents a Real Engineering Process (and a Knowledge Base That Doesn't Depend on Anyone Else)

\n

Ask an AI coding agent to "fix the bug" and it will fix *a* bug — usually the

\n

one nearest the surface, in whatever file it opens first. It rarely stops to

\n

ask whether the fix addresses the real requirement, whether a sibling caller

\n

has the same problem, or whether a reviewer would actually sign off on it.

\n

That's not a model failure so much as a missing process: humans don't skip

\n

design and review because we're smarter in the moment, we skip it because

\n

nobody built the discipline into the loop.

\n

Agentic-SDD is a Claude Code plugin that tries to build that discipline

\n

in — a six-stage pipeline (require → plan → analyze → implement → verify →) gated by a persistent on-disk status file instead of conversation

\n

fix

\n

memory, backed by an 18-agent specialist roster, with its own bundled

\n

knowledge-search engine so it doesn't depend on any other plugin to ground

\n

its decisions in your actual codebase.

\n

Repo: github.com/MallikarjunHt/agentic-sdd

\n

The core idea: six gated stages, not a chat loop

\n

A /sdd.require <feature-id> call doesn't just write code. It walks a real

\n

feature through:

\n
\n

Require. A business-analyst agent turns a raw ticket/request into1-spec.md — problem, proposed solution, explicit non-goals, risks, and\nGiven/When/Then acceptance criteria. You approve it before anything else\nhappens.

\n
\n

Plan. An architect agent turns the approved spec into2-plan.md and3-tasks.md — a concrete Definition of Done, a file map, and a numbered\ntask list, each task tagged with a suggested owner from a 12-role\nspecialist bench (Java, Angular, React, Python, UI, DevOps, QA, BA, DBA,\nSecurity, Architect, Senior Dev), scored against trigger keywords. You\napprove this too.

\n
\n

Analyze. A dedicated gap-analysis agent checks the plan against the\nspec's acceptance criteriaand the real current codebase, before a\nsingle line of code is written. CRITICAL findings block progress until\nresolved or explicitly descoped.

\n
\n

Implement. Each task is implemented by its routed specialist, at a\nmodel tier (cheap/mid/expensive) scored from that task's own complexity —\na one-line config change doesn't need the same model as a cross-cutting\nrefactor.

\n
\n

Verify. Three separate agents check constitution conformance,\nquality/security, and test adequacy — plus a fourth, a dedicated devil's\nadvocate, whose only job is to look for what a checklist-shaped review\nstructurally can't catch: concurrency, migration/rollback risk, backward\ncompatibility. A PASS proposes a living-documentation diff, reviewed in\nthe normal PR, never committed silently.

\n
\n

Fix. If verify fails, a fixer agent gets exactly three attempts before\nit has to stop and recommend a plan change instead of looping forever —\na real circuit breaker, not an infinite retry.

\n

Every stage after require reads and writes a status.json per feature, so

\n

a crashed session resumes instead of restarting, and stages genuinely cannot

\n

run out of order. That one design choice — a file as the gate, not the

\n

model's own sense of "did I already do this?" — is doing most of the

\n

reliability work here.

\n

The profile system: one plugin, any repo

\n

Rather than hardcoding one tech stack's conventions, /sdd.init writes a

\n

specs/constitution.md grounded in that specific target repo's real

\n

conventions — build tool, test framework, lint command, forbidden/required

\n

patterns — not a generic textbook standard. A repo's own detected config

\n

always wins over the constitution file when they disagree. One plugin

\n

install, many target repos, each honestly represented.

\n

The part I almost shipped wrong: knowledge grounding

\n

The original design had every stage's "gather context" step call out to an

\n

MCP tool contract — any server exposing a knowledge_search-shaped tool

\n

name could plug in. Clean, decoupled, and wrong for the actual goal: if

\n

someone uninstalls whatever server was providing that tool, the plugin loses

\n

a capability it should always have.

\n

So I vendored the actual search engine — a small Lucene-based Java CLI, BM25

\n

full-text search with an optional ONNX vector-embedding upgrade — directly

\n

into the plugin, under its own renamed package so it carries no trace of

\n

where it came from. A few lessons from doing that for real, not

\n

hypothetically:

\n\n

I almost committed a 150MB jar. GitHub rejects pushes over 100MB per\nfile. The fix was obvious in retrospect: vendor thesource (a few\nhundred KB), build the jar locally with Maven on first use, and gitignore\nthe build output. The plugin repo stays small; the binary gets built once\nper machine.

\n\n

The embedding model is optional by design, not by accident. Full\nsemantic search needs a ~90MB ONNX model I also didn't want to ship by\ndefault. The engine already had a clean fallback — no model vendored means\nBM25-only, reported plainly by its owndoctor command — so the default\ninstall just... works, lexical search only, with vector search as an\nopt-in upgrade documented for later.

\n\n

A relative default path is a trap. The CLI's--index-dir and--models-dir flags default to cwd-relative paths. I'd already seen this\nexact class of bug once before (a tool silently reporting "no embedding\nmodel" because it was invoked from the wrong working directory, not\nbecause the model was actually missing) — so every call from inside the\nplugin passes both as absolute paths. Boring, but it's the difference\nbetween "works on my machine" and "works."

\n

Proof, not a pitch

\n

I ran the full pipeline end-to-end against a real Dependabot CVE alert in a

\n

production Java/npm monorepo — a transitive yaml dependency vulnerable to

\n

stack-overflow on deeply nested input. All six stages ran for real: the spec

\n

captured the actual CVE and affected manifest, the plan scoped it to a

\n

one-line npm override (no functional changes, matching the kind of

\n

discipline a dependency-only fix needs), analyze confirmed yaml was

\n

transitive rather than direct (so an override, not a direct bump, was the

\n

right mechanism), implement regenerated the lockfile properly instead of

\n

hand-editing it, and verify confirmed the resolved version actually cleared

\n

the vulnerable range — straight from the regenerated lockfile, since the

\n

environment's own vulnerability-feed proxy wasn't reachable that day. Two

\n

real commits, nothing fabricated, nothing silently skipped.

\n

What's still a known gap

\n

Stated plainly, because a tool that hides its own limitations is worse than

\n

one that states them:

\n\n

If you're building something similar — or just tired of watching an agent

\n

confidently fix the wrong thing — the repo's up, MIT licensed, and the

\n

pipeline is designed to be read, not just run:

\n

github.com/MallikarjunHt/agentic-sdd.

\n\n

If you're building something similar — or just tired of watching an agent

\n

confidently fix the wrong thing — the repo's up, MIT licensed, and the

\n

pipeline is designed to be read, not just run:

\n

github.com/MallikarjunHt/agentic-sdd.

","headings":[{"level":1,"text":"Agentic-SDD: Giving Claude Code Agents a Real Engineering Process (and a Knowledge Base That Doesn't Depend on Anyone Else)","id":"agentic-sdd-giving-claude-code-agents-a-real-engineering-process"},{"level":2,"text":"The core idea: six gated stages, not a chat loop","id":"the-core-idea-six-gated-stages-not-a-chat-loop"},{"level":2,"text":"The profile system: one plugin, any repo","id":"the-profile-system-one-plugin-any-repo"},{"level":2,"text":"The part I almost shipped wrong: knowledge grounding","id":"the-part-i-almost-shipped-wrong-knowledge-grounding"},{"level":2,"text":"Proof, not a pitch","id":"proof-not-a-pitch"},{"level":2,"text":"What's still a known gap","id":"what-s-still-a-known-gap"}]}}