Workflows & Gates

SDTK treats a piece of work as a workflow with gates: a sequence (or DAG) of stages where moving forward requires either evidence, a human decision, or both. This page explains the two gate systems you'll meet — the SDLC phase gates in the spec pipeline, and human_gate stages in agent workflows.

SDLC phase gates (SDTK-SPEC)

Formal feature delivery moves through five roles, in order, without skipping:

PM → BA → ARCH → DEV → QA

Each phase writes real artifacts (PRD, business analysis, architecture spec, implementation plan, QA report) and each transition is a gate: the next role starts only when the previous phase's artifact is complete and accepted. Traceability runs end-to-end — requirements link to design, design to implementation, implementation to tests.

Before PM even starts, a discovery gate applies: a raw idea first becomes docs/discovery/REQUIREMENT_<FEATURE_KEY>.md, and PM initiation begins only when that artifact is marked READY_FOR_PM_INITIATION. Ideas that aren't ready get NEEDS_MORE_DISCOVERY or NOT_ACTIONABLE_YET instead of a premature spec.

See SDTK-SPEC and Idea to Ship.

Review gates (SDTK-CODE, SDTK-DESIGN, SDTK-OPS)

• Code: sdtk-code ship requires a review decision; verification evidence is collected by verify --evidence before ship. Code review completes before a QA release decision.
• Design: sdtk-design review --artifact … produces dated review evidence before handoff packages the design for coding.
• Ops: every deployment journey closes with ops-verify — a deploy without verification evidence isn't done.

human_gate stages (SDTK-AGENT)

Agent workflows are JSON DAGs where stages are either task or human_gate:

{
  "stages": [
    { "id": "draft",   "type": "task",       "role": "author" },
    { "id": "approve", "type": "human_gate", "depends_on": ["draft"] },
    { "id": "publish", "type": "task",       "role": "publisher",
      "depends_on": ["approve"] }
  ]
}

When the run reaches approve, the state machine stops: everything downstream is blocked until a person decides —

sdtk-agent gate approve --run-id <run_id> --gate approve --approved-by <name>
# or
sdtk-agent gate reject  --run-id <run_id> --gate approve --approved-by <name>

The decision is written to the ledger's approvals/ directory with attribution, and the reducer unblocks (or fails) the downstream stages accordingly.

Other stage mechanics:

• depends_on — a stage becomes ready only when all dependencies are terminal-successful.
• skip_when — conditional skip rules let a DAG branch without duplicating workflows.
• Retry/timeout policy — task failures are retry-bounded; exhausted retries fail the stage rather than looping.
• Evidence intake — a task completes by producing an evidence file under evidence/; the manual adapter is literally "wait for a human to drop evidence".

Why gates, not vibes

Gates convert "the AI said it's done" into "there is an artifact, and a named person accepted it". That's the difference between a chat transcript and an audit trail — and it's what makes it safe to hand multi-step work to agents at all.

Where to go next

The Trust LayerEvidence, guardrails, review packets, and reports.

Durable Agent RunsAuthor a DAG, hit a gate, approve it, finish the run.

sdtk-agent referenceEvery run and gate command with options.