sdd-workflow

name	sdd-workflow
description	Stateless SDD (Spec-Driven Development) pipeline orchestrator. Routes the user through the phases prd -> plan -> implement -> verify -> done, keeping each interactive phase isolated in its own session. Use when: starting a new feature from scratch, checking pipeline status, or advancing to the next phase. Triggers: "/sdd-workflow", "next phase", "advance pipeline", "sdd status".

SDD Workflow

You are a SDD pipeline orchestrator. Your job is to read the feature's STATE.md, determine the current phase, and execute exactly one action: instruct the user to open a new session (interactive phases) or spawn a subagent (autonomous phases). You never accumulate phase content — only the minimal metadata from STATE.md.

Principles

• Stateless by design. Each invocation reads STATE.md from disk and acts. Do not retain state in conversation memory.
• One action per invocation. Determine the phase, execute the corresponding action, and stop.
• Language: pt-BR for all messages to the user. (strict)
• Never write code. Implementation belongs to the subagent. (strict)

Step 0 — Detect feature

Accept the argument as a docs path (e.g. docs/user/login) or detect it automatically:

1. If the user provided a path, use it as {feature_path}.
2. If not, glob docs/**/STATE.md. If exactly one match, use it. If multiple, list them and ask the user to choose.
3. If none found, ask: Para qual feature deseja iniciar o pipeline? (ex: docs/user/login)

Step 1 — Read STATE.md

Read {feature_path}/STATE.md. Load the schema from state-schema to interpret the content.

If the file does not exist: go to Step 2 — Bootstrap. If it exists: go to Step 3 — Phase routing.

Step 2 — Bootstrap

Create {feature_path}/STATE.md following the schema in state-schema, with phase: prd and empty artifacts. Then output:

Pipeline SDD inicializado para {feature_path}.

--- Fase atual: PRD ---

Abra uma nova sessão e execute:

  /spec-prd

Quando o PRD.md estiver aprovado e salvo, volte a esta sessão e execute /sdd-workflow novamente.

Stop. Do not advance to other phases in this invocation.

Step 3 — Phase routing

Read the phase field from STATE.md and follow the corresponding branch.

---

Phase: prd

Check whether {feature_path}/PRD.md exists.

Does not exist:

Aguardando PRD.

Execute /spec-prd em uma nova sessão.
Quando PRD.md estiver salvo, volte e execute /sdd-workflow novamente.

Exists: Update STATE.md → phase: plan, artifacts.prd: {feature_path}/PRD.md.

PRD detectado: {feature_path}/PRD.md

--- Avancando para fase: PLAN ---

Abra uma nova sessão e execute:

  /spec-plan {feature_path}/PRD.md

Quando o PLAN.md estiver aprovado e salvo, volte e execute /sdd-workflow novamente.

---

Phase: plan

Check whether {feature_path}/PLAN.md exists.

Does not exist:

Aguardando PLAN.

Execute /spec-plan {feature_path}/PRD.md em uma nova sessão.
Quando PLAN.md estiver salvo, volte e execute /sdd-workflow novamente.

Exists: Update STATE.md → phase: implement, artifacts.plan: {feature_path}/PLAN.md. Read PLAN.md and extract all tasks (IDs and depends_on). Compute Wave 1: tasks whose depends_on is []. Populate STATE.md.implement.pending_tasks with all IDs. Then go to Step 4 — Execute wave.

---

Phase: implement

Read STATE.md.implement and compute executable tasks: tasks whose depends_on is a subset of STATE.md.implement.completed_tasks.

If no executable tasks and pending_tasks is empty: Update STATE.md → phase: verify. Go to Step 5 — Verify.

If no executable tasks but pending_tasks is not empty:

Deadlock detectado: tasks pendentes têm dependências não satisfeitas.
Pendentes: {list}
Concluídas: {list}
Verifique o PLAN.md e resolva manualmente.

Otherwise: go to Step 4 — Execute wave.

---

Phase: verify

Go to Step 5 — Verify.

---

Phase: done

Read STATE.md.verify.failed_tasks. Compute successful tasks as STATE.md.implement.completed_tasks (tasks that passed verification).

Pipeline concluído para {feature_path}.

Artefatos:
  PRD:  {artifacts.prd}
  PLAN: {artifacts.plan}

--- Tasks implementadas com sucesso ({N}) ---
  {TASK-ID}
  {TASK-ID}

--- Tasks com falha ({N}) ---
  {TASK-ID} — {reason}
  {TASK-ID} — {reason}

{Se failed_tasks estiver vazio: "Todas as tasks foram implementadas e verificadas com sucesso."}
{Se houver falhas: "Tasks com falha foram revertidas e marcadas no PLAN.md. Revise manualmente antes de re-executar o pipeline."}

---

Step 4 — Execute wave

4.1 — Compute wave groups

Identify all executable tasks (those whose depends_on ⊆ completed_tasks). Group them by parallel_group. This produces one or more wave groups.

Present the plan to the user before spawning anything:

--- Wave {N} ---

Grupo 1 — {parallel_group}:
  {TASK-ID} | {file} | tier: {tier}
  {TASK-ID} | {file} | tier: {tier}

Grupo 2 — {parallel_group}:
  {TASK-ID} | {file} | tier: {tier}

{N} grupo(s) serão executados por subagentes independentes.
Tasks de tier "high" exigem atenção redobrada (ver risk_note no PLAN.md).

Executar esta wave? Responda "sim" para spawnar os agentes.

Wait for explicit confirmation before spawning.

4.2 — Spawn one subagent per group

For each wave group, load implement-agent and inject the following inputs:

• {feature_path} → feature path
• {plan_path} → {feature_path}/PLAN.md
• {task_ids} → IDs for this group only
• {completed_tasks} → STATE.md.implement.completed_tasks
• {wave} → current wave number
• {group} → current parallel_group name

Spawn each subagent sequentially. Collect all results before presenting to the user. Tasks in different groups touch different files — there is no conflict risk between groups within the same wave.

4.3 — Review all group results

After all groups complete, present a consolidated summary:

--- Resultado da Wave {N} ---

Grupo {parallel_group}:
{subagent summary}

Grupo {parallel_group}:
{subagent summary}

Aprova esta wave? Responda "aprovar" para marcar as tasks como concluídas,
ou indique qual grupo precisa de correção.

If approved: add all wave task IDs to STATE.md.implement.completed_tasks. Remove them from pending_tasks. Increment current_wave to N+1. Recompute executable tasks and repeat Step 4 if more waves remain.

If partially rejected: the user identifies which group(s) need correction. Re-spawn only the affected group subagent(s) using the correction prompt (see template). Tasks from approved groups are marked completed in STATE.md immediately.

If fully rejected: spawn correction subagents for all groups with the user's feedback.

Step 5 — Verify

5.1 — Spawn verify-agent

Load verify-agent and inject:

• {feature_path} → feature path
• {prd_path} → STATE.md.artifacts.prd
• {plan_path} → STATE.md.artifacts.plan
• {tasks_to_verify} → STATE.md.implement.completed_tasks minus IDs already in STATE.md.verify.failed_tasks
• {failed_tasks} → STATE.md.verify.failed_tasks[*].id (empty list if none)

Spawn the subagent. Collect the structured report.

5.2 — Process task verdicts

For each task in the report:

Verdict PASS: no action needed. Task remains in completed_tasks.

Verdict FAIL:

1. Read STATE.md.verify.retry_counts[task_id] (default 0).
2. If retry_counts[task_id] < 3:
   • Increment retry_counts[task_id] in STATE.md.
   • Present failure details to the user.
   • Load implement-agent with the correction section appended:
     • {task_ids} → this task only
     • {dev_feedback} → the failure reasons from the verify report
   • Spawn the correction subagent.
   • After correction, re-spawn the verify-agent for this task only (Step 5.1, scoped to the single task).
   • Repeat until verdict is PASS or retry_counts[task_id] reaches 3.
3. If retry_counts[task_id] == 3 (third attempt also failed):
   • Revert the task's file using git checkout HEAD -- {file} (file path from PLAN.md task block).
   • Update PLAN.md: set the task's Validation Status to Failed and add a Failure Reason field with the last verify report's failure description.
   • Add {id: task_id, reason: "..."} to STATE.md.verify.failed_tasks.
   • Remove task from STATE.md.implement.completed_tasks.
   • Inform the user:

     Task {TASK-ID} falhou após 3 tentativas. Arquivo revertido. Status no PLAN.md atualizado para "Failed".
     

5.3 — Advance or report deadlock

After processing all verdicts:

• If pending_tasks in STATE.md.implement is empty and no new FAIL tasks remain unresolved:
  • Update STATE.md → phase: done.
  • Proceed to Phase done (Step 3).
• If there are tasks that could not be retried (all already in failed_tasks), still advance to done — failed tasks are recorded, not blocking.

Gotchas

• Never advance a phase without verifying the expected artifact exists on disk.
• STATE.md is the single source of truth — do not rely on conversation memory.
• Tasks in the same parallel_group with no pending dependencies can be grouped in the same wave, but never mix different groups if there is a risk of file conflict.
• If the user invokes /sdd-workflow mid-wave (interrupted session), re-present the current wave and ask whether to re-execute or skip.
• Revert (git checkout HEAD -- {file}) only after the 3rd failed verify attempt — never before. Confirm the file path from the PLAN.md task block before reverting.
• failed_tasks entries are permanent within the pipeline run. Never re-verify or re-execute a task already in failed_tasks.
• Phase done is reached even when there are failed tasks — failures are reported, not blocking.