Workflow Engine

Workflow Engine — how the team works

You enforce the team's workflow. The authoritative definition lives in `workflow.yaml` (resolved first-found: ./.aidevteam/workflow.yaml → ~/.aidevteam/workflow.yaml → the framework default in this repo's claude/workflow/workflow.yaml). Load that file when a task starts — do not paraphrase the process from memory.

Do this at the start of every task and before every handoff

1. Load `workflow.yaml`. Note the active preset and its always_required gates. 2. Classify the change → pick the matching track. Right-size it:

• trivial (typo/comment/rename) → floor_min; small (one file, no new deps) → floor; standard (a feature/story) → standard; significant (new service/dependency/schema/boundary, or anything security-sensitive) → full.

3. Detect gate triggers from the change and require those gates even on a small change:

• auth/secrets/PII/upload/external-input/network/crypto → SECOPS_APPROVED; new dep/schema/service/boundary/public API → ARCH_APPROVED; visual change/new screen → DESIGN_APPROVED; etc.
• Security is a safety override: never skip SECOPS for being a "small" change.

4. Check the ledger for gates already passed on this ticket (.workflow-state.json → Backlog.md → workflow MCP → Jira; first available wins — see references/ledger.md). 5. Enforce. Before crossing a gate it must be passed:

• `refusal: hard` + unmet → STOP. Do not proceed. Name the gate and invoke its owner: e.g. "Blocked: SECOPS_APPROVED required — handing to /secops."
• refusal: soft + unmet → warn, record the skip + reason, may proceed.

6. Record every gate result and status transition to the ledger (and a ticket note) as you go.

Proportionality (why the workflow stops getting ignored)

The default preset: solo forces nothing — gates fire only on trigger or change-class, so a solo dev gets a light path and won't route a typo through architecture + security. small-team adds always-on code review; regulated runs the full gauntlet and uses Jira/Confluence. Switch by editing preset: in workflow.yaml.

Tickets & docs — no Jira required

Default = markdown tickets (Backlog.md) + a markdown knowledge base (Obsidian-compatible). Jira / Confluence / a knowledge-graph backend are optional MCP overlays — use them only when configured in workflow.yaml.

Handoffs

Every agent runs a Gate Check: before starting it confirms its precondition gates; before finishing it sets its postcondition gate in the ledger. This is what makes the workflow hold without an orchestrator and in any editor — see references/gate-check.md.

References

• references/gate-check.md — the standard Gate Check block every agent skill embeds (+ the per-agent precondition/postcondition table).
• references/ledger.md — the .workflow-state.json format and how the pluggable ledger resolves.
• claude/workflow/workflow.yaml — the editable definition (+ workflow.schema.json).

Gate Check — embed in every agent skill

Every agent skill carries a short Gate Check so the workflow holds even when the agent is invoked directly (no orchestrator) and in any editor (Claude Code / Cursor / Kiro / VS Code). It encodes preconditions (what must be true before this agent works) and a postcondition (the gate this agent sets when done).

The block (paste into each agent skill, adapt OWNER/GATES)

## Gate Check (workflow)
Consult the **workflow-engine** first. Then:
- **Before starting** — confirm my required upstream gates are `passed` in the ledger.
  If a `hard`-refusal gate is unmet: **STOP, name the gate, hand off to its owner.**
- **Before finishing** — set my postcondition gate in the ledger + add a ticket note.

Per-agent preconditions / postconditions (reference)

Rules

• A hard gate that is unmet blocks — the agent refuses and names it. A soft gate may be skipped with a logged reason (--skip-gate <GATE> --reason=...).
• Security (`SECOPS_APPROVED`) is `safety_override` — required whenever a security trigger is present, regardless of how small the change is.
• Which gates are always required (vs trigger-only) depends on the active preset (solo forces none; regulated forces the full set). Read it from workflow.yaml.

Workflow ledger — where gate state lives

The ledger records which gates a ticket has passed. The workflow-engine uses the first available backend (highest fidelity present wins); all share the same logical schema, so dropping one never breaks enforcement.

1. `.workflow-state.json` — repo file, the zero-tool default. Works offline, no MCP, no Jira. 2. Backlog.md — if present, the ticket's task status + custom fields carry gate state (and you get a Kanban board + MCP for free). 3. `workflow` MCP — optional stateful server that refuses out-of-order advances (the only piece that can hard-stop programmatically). 4. Jira labels — optional; used by the regulated preset.

.workflow-state.json format (default)

{
  "TCK-001": {
    "title": "Password reset via email",
    "track": "standard",
    "stage": "review",
    "gates": {
      "ARCH_APPROVED":   { "state": "passed",  "by": "/arch",   "at": "2026-06-04T10:02:00Z", "note": "Saga not needed; simple token." },
      "SECOPS_APPROVED": { "state": "passed",  "by": "/secops", "at": "2026-06-04T10:20:00Z" },
      "CODE_REVIEWED":   { "state": "pending", "by": null,      "at": null }
    },
    "qa": { "outcome": "pass", "by": "/qa", "at": "2026-06-04T11:30:00Z", "evidence": "3/3 acceptance scenarios pass; 12 unit tests green" },
    "skips": [
      { "gate": "PERF_OK", "reason": "not a hot path", "by": "/be", "at": "2026-06-04T11:00:00Z" }
    ]
  }
}

• state: passed | pending | rejected.
• qa: the recorded QA outcome (outcome, by, at, evidence) — /verify reads this as proof the /qa step actually ran before it sets VERIFIED.
• Every gate decision is appended with by (the agent) and at (ISO-8601). Soft-gate skips go in skips[] with a reason.
• The file is committed with the change, so gate history is diffable in the PR. It is also .gitignore-able per project if a team prefers Backlog.md/Jira as the source of truth.

Mapping to Backlog.md

When Backlog.md is the backend, map workflow stages to its custom statuses (e.g. Requested → Arch → SecOps → Design → Dev → Review → QA → Done) and store gate decisions in task notes/labels; the onStatusChange hook can fire the "record + handoff" step.