DEV Community

Dzu Tran
Dzu Tran

Posted on

Stop Letting AI Code Without Specs: How We Built a 4-Role Autonomous Engineering Framework

#ai #opensource #architecture #webdev

If you've spent any serious amount of time using AI coding assistants like Cursor, Claude Code, Copilot, or Windsurf on non-trivial codebases, you've almost certainly experienced these moments of frustration:

  1. Premature Implementation: You describe a broad feature, and the AI immediately starts editing 10 random files without analyzing edge cases or asking for clarification.
  2. Context Window Amnesia: Five prompts into the session, the AI forgets the architectural constraints you established at the start and begins undoing previous logic.
  3. Ghost Fixes & Silent Regressions: The AI claims "I have fixed the issue!", but upon closer inspection, it just broke two other critical components because no independent QA tested it.

We faced these exact challenges while scaling a high-traffic production application to 95–100 Google PageSpeed scores, OWASP Zero-Trust compliance, and strict WCAG accessibility.

To eliminate prompt-drift and hallucinated implementations once and for all, we built and open-sourced Agentic-SDD: A spec-driven multi-agent operating framework that turns single-agent assistants into a disciplined 4-role software engineering team.

🏛️ The 4-Role Operating Lifecycle

Instead of treating the AI as an all-in-one coder that plans, writes, tests, and deploys without oversight, Agentic-SDD strictly separates concerns into 4 independent roles:

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Role 01    │ ──> │   Role 02    │ ──> │   Role 03    │ ──> │   Role 04    │
│   Planner    │     │  Developer   │     │  QA Tester   │     │  Gatekeeper  │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
       │                    │                    │                    │
  Clarifies            Implements           Adversarial          Audits diffs
  edge cases           strictly in          boundary tests       & signs off
  & specs plan         Impacted Files       & self-heals         for release
Enter fullscreen mode Exit fullscreen mode

1. 🏛️ Role 01 — System Architect & Planner

  • Rule: Strictly Read-Only on production source code.
  • Workflow: Proactively asks 2–3 edge-case clarification questions (Step 0 Clarifications) before generating a formal technical specification in tracking/plan/<FEATURE>_PLAN.md.
  • Output: Scope (In/Out), impacted files table, and testable acceptance criteria.

2. 💻 Role 02 — Software Engineer / Developer

  • Rule: Strictly bound to the Impacted Files declared in the plan (Zero Scope Drift).
  • Workflow: Follows strict web interface guidelines (explicit 60 FPS transitions, zero layout shifts), implements defensive logic with try/catch, and syncs action checklist items (- [x]).

3. 🧪 Role 03 — QA & Quality Engineer

  • Rule: Independent verification; forbidden from touching business logic code directly.
  • Workflow: Executes boundary tests (edge cases, empty inputs, network failure, 4-viewport responsive audits: 430px, 768px, 1024px, 1440px+).
  • Autonomous Self-Healing Loop: If a bug is detected, QA publishes a structured report with root causes. The Orchestrator automatically dispatches Dev to fix and QA to re-test (up to 3 autonomous cycles) until reaching 100% PASS.

4. 🛡️ Role 04 — Strict Tech Lead & Gatekeeper

  • Rule: The only role authorized to approve merges, archive plans, or sign off on releases.
  • Workflow: Audits git diffs against performance regressions, security vulnerabilities, and accessibility standards.

🚀 Why "Markdown-First Persistent State"?

Most multi-agent frameworks force you to set up complex vector databases, Redis queues, or Python orchestration servers.

Agentic-SDD takes the opposite approach: Git & Markdown are all the state you need.

Every handoff is preserved as a permanent artifact in your repo:

  • tracking/plan/: Active technical specifications.
  • tracking/report/: QA audit findings and self-healing logs.
  • tracking/task/: Daily prioritized task board (DAILY_TASKS.md).
  • tracking/log/: Release history (CHANGELOG.md).
  • tracking/done/: Permanent archive of completed specifications.

Result: Zero external dependencies, zero database setup, and zero token waste—agents only read the exact markdown artifact required for their role.

⚡ Try It in 5 Seconds (Zero Dependencies)

We packaged the framework into an ultra-lightweight Node.js CLI (< 50KB, starts in ~100ms) with zero third-party dependencies:

# Initialize into any new or existing project (Next.js, Astro, Vue, Python, Go, etc.)
npx @dzutr/agentic-sdd init --preset fullstack-edge --ide all

# Verify setup integrity across all 5 roles & tracking directories
npx @dzutr/agentic-sdd doctor

# Audit your codebase for UI standards & spec compliance
npx @dzutr/agentic-sdd verify
Enter fullscreen mode Exit fullscreen mode

Universal Multi-IDE Support

One single source of truth (.agent-roles/ and AGENTS.md) generates native bridge adapters for your preferred AI tool:

  • Cursor: .cursor/rules/agentic-sdd.mdc
  • Claude Code: CLAUDE.md
  • Windsurf: .windsurfrules
  • Antigravity: .antigravity/roles/
  • GitHub Copilot: .github/copilot-instructions.md

📦 Open Source & Community

Agentic-SDD is completely free and open-source under the MIT License.

If you find this approach helpful for building disciplined, predictable AI engineering workflows, please consider dropping a Star ⭐ on GitHub to support the project!

We'd love to hear your thoughts: How do you currently prevent AI coding assistants from hallucinating or scope-drifting across long sessions?

Top comments (0)