Workflows

DSL-bound stage contracts

Workflows in .sdlc/workflows/ are runtime-neutral stage contracts bound to the harness DSL. They define the delivery pipeline graph that workflow-layer methodologies (AIDLC-style lifecycle) describe conceptually — but as machine-readable, gate-enforceable specifications.

Commands are entry points. Workflows are the contracts commands execute. The harness materializes and enforces them.

Commands (slash-invokable protocols in the runtime adapter) are entry points. Workflows are the machine-readable contracts those commands execute.

User invokes:     /implement-feature
Command file:     {specialization_layer}/commands/implement-feature.md
Workflow binding: .sdlc/sdlc.yaml → workflows.feature.definition
Workflow file:    .sdlc/workflows/feature-flow.yaml

Everything flows from the DSL binding. Changing which workflow a command invokes is a sdlc.yaml edit — not a command rewrite.

---

Workflow file structure

name: feature-flow
version: "1.0"
description: End-to-end feature implementation from requirement to merged PR.
trigger: /implement-feature
command: .cursor/commands/implement-feature.md   # path resolved via active adapter

stages:
  - id: planning
    name: Feature Planning
    agent: planner
    definition: .cursor/agents/planner.md
    inputs:
      - feature_description: "from command invocation"
    outputs:
      - plan: "structured plan document"
      - e2e_scenarios: "test scenarios list"
    blocking: true
    on_failure: abort

  - id: implementation
    agent: implementer
    blocking: true
    on_failure: return_to_planning

success_criteria:
  - review.review_status == "APPROVED"
  - qa.qa_status == "PASS"
  - pr_creation.pr_url is defined

failure_behavior:
  - log to operational-context memory
  - do not merge
  - surface failure stage and reason

Key fields:

Field	Purpose
trigger	Slash command that starts this workflow
stages[].agent	Persona id — resolved to {specialization_layer}/agents/{agent}.md
stages[].blocking	If true, failure aborts the pipeline
stages[].on_failure	abort, return_to_{stage}, or escalate_to_architect
success_criteria	Machine-checkable conditions — enforced by sdlc_gate_check.py
playbooks_when	Optional domain playbook provision at stage entry

Integration-specific stages (ticket state sync, evidence upload) reference the active work-items integration via skills — not hardcoded vendor names in the workflow YAML. Stage ids like work-items-in-review and work-items-closure describe the operation; the skill resolves the provider from sdlc.yaml integrations.work_items.

---

Registry

Workflow	Trigger	Primary output
bootstrap-flow.yaml	/sdlc:init	Operational SDLC bound to repository
spec-flow.yaml	/spec:create	Spec, ticket, worktree
feature-flow.yaml	/implement-feature	PR, QA evidence
e2e-flow.yaml	/run-e2e	Evidence, recordings
deployment-flow.yaml	/deploy-release	Release
incident-flow.yaml	/fix-incident	Fix PR, incident record
e2e-orchestration-flow.yaml	/sdlc:e2e	Run manifest, deployed product

Bindings declared in sdlc.yaml:

workflows:
  feature:
    definition: .sdlc/workflows/feature-flow.yaml
    trigger: /implement-feature
    agents: [planner, implementer, reviewer, qa]
    outputs: [pr, evidence, handoff]

Doctor validates that every declared workflow file exists and that every trigger has a corresponding command in the active adapter.

---

feature-flow — the canonical vertical slice

context-hydration
    ↓
planning (planner)
    ↓
implementation (implementer)
    ↓
review (reviewer)
    ↓
qa (qa)
    ↓
pr-creation
    ↓
work-items-in-review
    ↓
work-items-closure (on merge)

This workflow runs identically whether tickets are in Plane, Jira, or Linear. Stages that touch the ticket system delegate to a skill that reads the active integration manifest — generated during init, not shipped with the package.

Success criteria are gate inputs. sdlc_gate_check.py verifies all criteria before setting feature_flow_complete: true on a run manifest ticket.

---

e2e-orchestration-flow — macro composition

The orchestrator workflow does not replace feature-flow. It composes it:

Orchestrator stage	Delegates to
decomposition	planner on epic scope
work-items-hierarchy	/spec:create per slice
execution (per ticket)	/implement-feature → feature-flow
deploy	/deploy-release → deployment-flow
post-deploy	/sdlc:post-deployment
reflect	/sdlc:reflect + /handoff

Orchestrator invariants (hard gates):

• Never implement {target_root}/** in the main workspace session
• Never mark execution complete without all tickets passing feature-flow gates
• One ticket → one worktree → one PR

Composition index: .sdlc/workflows/README.md.

---

Adding a workflow

1. Write .sdlc/workflows/{name}-flow.yaml with stages and success_criteria
2. Register in sdlc.yaml under workflows:
3. Create command protocol in {specialization_layer}/commands/
4. Add gate checks to sdlc_gate_check.py if stage transitions need deterministic enforcement
5. Register in .sdlc/INDEX.md
6. Run /sdlc:doctor to verify binding sync

New gates must appear in both sdlc.yaml gates: and sdlc_gate_check.py. A workflow success criterion without a gate check is advisory only.

---

Init learns the repository, workflows execute on it

/sdlc:init runs bootstrap-flow.yaml. The runtime:

1. Discovers repository structure (/sdlc:discovery or inline)
2. Sets workspace.target_root and profile
3. Walks lifecycle slots — user selects providers or defers
4. Generates integration manifests for selected slots (via skills + /sdlc:config pipeline)
5. Materializes stack-specific rules in the adapter
6. Sets status: operational

After init, the same workflow definitions apply. The DSL now points at this repository’s paths, integrations, and constraints. No workflow rewrite per project — only DSL specialization.

A Python monolith, a Turborepo, and an empty directory all receive identical workflow YAML. What differs is target_root, profile, active integrations, and adapter rules generated from discovery.

---

Operational consequences

Workflows outlive runtimes. Adapter swap does not touch .sdlc/workflows/.

Success criteria are gate contracts. Adding a criterion to YAML without updating sdlc_gate_check.py creates a false sense of enforcement.

Integration stages are generic. Workflows name operations (sync ticket state, upload evidence), not vendors. Vendor specifics live in integration manifests generated at init.

Composition beats reimplementation. The orchestrator owns ordering and gates; feature-flow owns vertical slice execution. Neither duplicates the other.