Spec Driven Develop Workflow

Spec-Driven Develop Workflow

Spec-Driven Develop is the main workflow for large coding-agent implementation tasks. It is designed for migrations, rewrites, architecture refactors, large feature builds, and any project where starting with code before analysis would create avoidable risk.

The workflow is architecture-first: the agent analyzes the codebase, confirms scope, creates a plan, sets up tracking, executes tasks, validates results, and archives artifacts.

Trigger Keywords

Spec-Driven Develop is intended to trigger when a user describes a large transformation:

Language	Example Triggers
English	rewrite, migrate, overhaul, refactor entire project, transform, rebuild in another language, spec-driven
Chinese	改造, 重写, 迁移, 重构, 大规模, 规范驱动

Phase Overview

Phase 0  Quick Intent Capture
Phase 1  Deep Project Analysis
Phase 2  Intent Refinement and Confirmation
Phase 3  Task Decomposition
Phase 4  Progress Tracking and Governance
Phase 5  Confirm and Execute
Phase 6  Archive

Phase 0: Quick Intent Capture

The agent captures the high-level direction in one or two sentences. This is not a detailed requirement interview. The goal is to give analysis a useful focus.

Example:

I understand that you want to migrate the current Python service to a TypeScript service while preserving API compatibility. I will first analyze the current project so I can ask grounded scope questions.

Phase 1: Deep Project Analysis

The agent analyzes the repository before planning implementation.

Expected outputs:

• docs/analysis/project-overview.md
• docs/analysis/module-inventory.md
• docs/analysis/risk-assessment.md

The analysis covers:

• Architecture and stack.
• Entry points and build commands.
• Module responsibilities and dependencies.
• S.U.P.E.R compliance per module.
• Testing baseline and risk areas.
• Project-level instruction and memory surfaces.
• GitHub tracking pre-flight mode.

Phase 2: Intent Refinement and Confirmation

The agent asks targeted questions based on the analysis. This avoids generic planning based on assumptions.

The confirmation should cover:

• Scope: which modules are in or out.
• Target state: language, framework, architecture, behavior.
• Constraints: compatibility, runtime, deployment, deadline, preferred libraries.
• Priorities: maintainability, performance, compatibility, delivery speed.
• S.U.P.E.R priorities: which architecture violations must be fixed now.
• Testing policy: what automated checks must protect the change.
• Governance: where durable project rules and memory should live.

Phase 2 creates the authoritative task definition for the rest of the run.

Phase 3: Task Decomposition

The agent breaks the confirmed goal into phases, tasks, dependencies, parallel lanes, milestones, and acceptance criteria.

Expected outputs:

• docs/plan/task-breakdown.md
• docs/plan/dependency-graph.md
• docs/plan/milestones.md

Each task should include:

• Priority: P0, P1, or P2.
• Effort: S, M, L, or XL.
• Dependencies.
• Affected files.
• S.U.P.E.R design drivers.
• Test expectation.
• Memory or governance impact.
• Acceptance criteria.

If GitHub mode is available, the workflow also creates Issues, Milestones, Labels, and optionally a Project board.

Phase 4: Progress Tracking and Governance

The workflow creates docs/progress/MASTER.md as the cross-session entry point.

In GitHub modes, MASTER.md is a lightweight index pointing to:

• GitHub Project URL, if available.
• Milestones.
• Issue mapping.
• Analysis and plan documents.
• Quick gh status commands.
• Current phase and next steps.

In local-only mode, MASTER.md stores the task tracker directly in Markdown.

Phase 4 also resolves governance surfaces:

• Shared instruction files such as AGENTS.md.
• Claude Code-specific instructions such as CLAUDE.md.
• Existing platform rule directories.
• Native project memory, when available.
• Explicit repo-local fallback memory only when selected or already declared.

Phase 5: Confirm and Execute

After presenting the plan, the agent executes the tasks. Depending on the platform, work may run sequentially or through parallel agents.

During execution, each task should:

• Read the task source of truth.
• Work in the expected branch or worktree when GitHub mode is active.
• Implement only the accepted scope.
• Run targeted tests first, then type/lint/build checks when applicable.
• Run the S.U.P.E.R quick check.
• Update resolved instruction or memory surfaces when durable rules changed.
• Record execution telemetry for adaptive control.

Phase 6: Archive

When the work is complete, the workflow archives analysis, plans, progress, and governance snapshots into:

docs/archives/<project-name>/

The archive provides traceability for future agents and future maintainers.

What Makes This Different from a Prompt Template?

A prompt template usually tells the agent how to behave in one interaction. Spec-Driven Develop defines a repeatable project workflow:

• It produces artifacts.
• It has resumable progress.
• It models task dependencies.
• It can use GitHub Issues and PRs as execution state.
• It enforces architecture checks.
• It measures execution drift.
• It resolves governance and memory surfaces.

Related Pages

• GitHub-Issues-Projects-and-PRs
• Adaptive-Control-and-Drift-Score
• SUPER-Architecture-Principles
• Project-Governance-and-Memory