/workflow-state

name: workflow-state
description: Internal skill for managing workflow lifecycle state in sdd/workflows/. Provides session-independent, resumable workflow tracking.
user-invocable: false

Workflow State Skill

Purpose

Manages `sdd/workflows/<id>-<name>/` state - tracking where each item is in the solicitation → review → approval → implementation lifecycle.

This is **process state management**, not project task management.

Core Principle: Zero Session Context

**ALL workflow state is persisted in `sdd/` files.** A new session must be able to resume with ZERO knowledge of what happened before:

• No conversation history
• No in-memory state
• No assumptions

Read the files, know the state. This enables aggressive context compaction and allows users to clear sessions freely.

Directory Structure

sdd/
├── sdd-settings.yaml
├── archive/
│   ├── external-specs/         # External specs archived here (read-only)
│   │   └── 20260205-1430-feature-spec.md  # yyyymmdd-HHmm-lowercased-filename.md
│   ├── revised-specs/          # Specs removed during decomposition revision
│   │   └── 20260205-1430-a1b2c3-user-auth-03-password-reset/
│   │       └── SPEC.md
│   └── workflow-regressions/   # Work archived during phase regression
│       └── 20260205-1430-user-auth-1-impl/
│           ├── changes.patch   # Git patch for committed changes
│           ├── stash.patch     # Git stash for uncommitted changes
│           ├── src/            # Implementation files
│           └── metadata.yaml   # Regression context
└── workflows/                  # Multiple concurrent workflows supported
    ├── a1b2c3-user-auth/       # One workflow (user A, branch feature-x)
    │   ├── workflow.yaml       # This workflow's state
    │   └── drafts/
    │       ├── 01-user-management/
    │       │   ├── context.md
    │       │   ├── 01-api-contracts/
    │       │   │   └── context.md
    │       │   └── 02-auth-service/
    │       │       └── context.md
    │       └── 02-notifications/
    │           └── context.md
    └── x7y8z9-notifications/   # Another workflow (user B, branch feature-y)
        ├── workflow.yaml
        └── drafts/...

Status Progression (Four-Field Model)

The workflow uses four separate status fields for granular tracking:

Spec Phase

1. `spec_status: pending` → `in_progress` → `ready_for_review` → `approved`

Plan Phase (only after ALL specs approved)

2. `plan_status: pending` → `in_progress` → `approved`

Implementation Phase (only after ALL plans approved)

3. `impl_status: pending` → `in_progress` → `complete`

Review Phase (after implementation)

4. `review_status: pending` → `ready_for_review` → `approved`

**Key Difference from Previous Design:**

The old design had a single `status` field with immediate `spec_approved → plan_review` transition. The new design:

1. **`spec_status: approved` IS a resting state** - Phase gating requires ALL specs approved before ANY planning starts 2. **Plan phase is separate** - Only begins after checkpoint "All specs approved" 3. **Review phase is explicit** - User must approve implementation, not just verify tests pass

Phase Gating Rules

| Gate | Condition | |------|-----------| | Start planning | ALL items have `spec_status: approved` | | Start implementing | ALL items have `plan_status: approved` | | Complete workflow | ALL items have `review_status: approved` | | Approve spec | No OPEN questions in Requirements Discovery section | | Approve spec | No dependencies with `spec_status: needs_rereview` |

Resource Files

For detailed guidance, read these on-demand:

• [internal-api.md](resources/internal-api.md) — All 15 operations with input/output schemas
• [workflow-yaml-schema.md](resources/workflow-yaml-schema.md) — Full schema documentation with all fields
• [recovery.md](resources/recovery.md) — Checkpoint triggers, recovery scenarios, regression handling

Input

Schema: [`schemas/input.schema.json`](./schemas/input.schema.json)

Accepts operation type and operation-specific parameters for workflow lifecycle management.

Output

Schema: [`schemas/output.schema.json`](./schemas/output.schema.json)

Returns workflow ID, current phase, and progress tracking.

Workflow ID Generation

Workflow IDs are short, unique identifiers:

1. Generate 6 random alphanumeric characters (a-z, 0-9) 2. Check for collision with existing workflows 3. If collision, regenerate 4. Format: `a1b2c3`, `x7y8z9`, etc.

Change ID Format

Change IDs are derived from the workflow name:

• Format: `<name>-<seq>` (e.g., `user-auth-1`, `user-auth-2`)
• `name`: The workflow's user-chosen name
• `seq`: Sequence number within workflow (1, 2, 3, ...)
• Unique across concurrent workflows (different workflows = different name prefix)

Epic Handling

• Each epic is an item with `type: epic` and `children` array
• Children are features within the epic
• Epic status tracks overall progress:
• `pending` until first child starts
• `complete` when all children complete
• Epic itself doesn't get a change_id - only leaf features get change_ids
• Epic folder in `changes/` contains child change folders

Cleanup Behavior

• When item moves from `drafts/` to `changes/`:
• Keep `context.md` in drafts for reference
• Delete `solicitation-workflow.yaml`
• When item is marked `complete`:
• Remove from `workflow.yaml` items array
• When all items complete:
• Delete entire `sdd/workflows/<id>-<name>/` directory including `workflow.yaml`
• Completed items remain in `changes/` permanently (that's the source of truth)

INDEX.md Handling

• `changes/INDEX.md` is updated when items move to `changes/` directory
• No separate INDEX.md in `sdd/workflows/` - workflow.yaml is the source of truth
• `workflow_state.ready_for_review()` updates `changes/INDEX.md` with new entry

Consumers

• `/sdd` orchestrator — creates workflows and manages lifecycle
• `spec-solicitation` skill — reads context, saves specs
• `change-creati