zhu1090093659/spec_driven_develop

What it solves

Spec-Driven Develop provides a structured, architecture-first workflow for AI coding agents to handle large-scale software changes—such as migrations, rewrites, and complex refactors—without losing track of progress or blindly executing flawed plans. It prevents the common issue of AI agents drifting from the original intent or introducing architectural regressions during complex implementations.

How it works

The project is a platform-agnostic set of Markdown-based "skills" that AI agents can read and execute. It implements a seven-phase pipeline (from intent capture and deep analysis to execution and archiving) and uses a closed-loop feedback system called "Adaptive Control" to monitor execution telemetry. If the agent's progress drifts too far from the plan, the system triggers automatic course corrections or re-decomposition of tasks.

It integrates natively with GitHub to track tasks via Issues, Milestones, and Labels, grouping work into coherent "delivery batches" rather than fragmented PRs. It also includes two auxiliary workflows: "Deep Discuss" for structured technical brainstorming and "Review SPD" for findings-first code reviews focused on bugs and regressions.

Who it’s for

Developers using AI coding agents (such as Claude Code, Cursor, Windsurf, or Aider) who are performing high-risk, large-scale architectural changes or complex feature implementations that require rigorous planning and tracking.

Highlights

• S.U.P.E.R Architecture Principles: Enforces Single Purpose, Unidirectional Flow, Ports over Implementation, Environment-Agnostic, and Replaceable Parts through automated health checks and checklists.
• Adaptive Control Loop: A cybernetics-inspired feedback system that halts or refactors the plan when execution drift exceeds specific thresholds (20%, 40%, 60%).
• GitHub-Native Tracking: Automatically creates Issues and Milestones and manages worktrees and batch PRs for professional-grade project management.
• Platform Agnostic: Works as a plugin for Claude Code, Codex, and OpenCode, or as a simple Markdown skill for any agent that supports custom instructions.