suaveplan/openspec/archive/2026-05-24-enterprise-workflow/tasks.md

Tasks — Enterprise migration: @suaveplan/workflow

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree and account for all worktrees
• 0.2 Confirm no stale .claude/worktrees/ directories
• 0.3 Read upstream ../suaveplan/packages/universal/workflow/ (43 files) end-to-end

1. Spec authoring

• 1.1 Read upstream source + README
• 1.2 Read sibling FSM / job-scheduler for genesis conventions
• 1.3 Read openspec/AGENTS.md §0a / §0c / §13 / §14
• 1.4 Draft proposal.md with parity checklist
• 1.5 Draft specs/workflow/spec.md with **Verified by:** per requirement

2. Implementation

• 2.1 Scaffold packages/foundation/flow/workflow/ — package.json, tsconfig.lib.json, vite.config.ts, vitest.config.ts
• 2.2 src/errors/workflow-error.ts — WORKFLOW_CODES via defineCodes + WorkflowError
• 2.3 src/constants/index.ts
• 2.4 src/types/common.ts + src/types/workflow-hooks.ts
• 2.5 src/utils/utils.ts (+ test + md)
• 2.6 src/otel/instruments.ts (+ md) — meter, counters, histogram
• 2.7 src/steps/step/step.ts (+ test + md)
• 2.8 src/steps/parallel-step/parallel-step.ts (+ test + md)
• 2.9 src/steps/conditional-step/conditional-step.ts (+ test + md)
• 2.10 src/compensation/compensator/compensator.ts (+ test + md)
• 2.11 src/compensation/saga/saga.ts (+ test + md)
• 2.12 src/middleware/hook/hook.ts (+ test + md)
• 2.13 src/middleware/retry/retry.ts (+ test + md)
• 2.14 src/core/context/context.ts (+ test + md)
• 2.15 src/core/workflow-builder/workflow-builder.ts (+ test + md)
• 2.16 src/core/workflow-engine/workflow-engine.ts (+ tests + md)
• 2.17 src/index.ts — explicit named re-exports per §6a

3. Tests

• 3.1 Co-located .test.ts per feature
• 3.2 tests/dep-graph.test.ts
• 3.3 Every it(...) has explicit { timeout: 5000 } (or 30000 if async)

4. Documentation

• 4.1 Sibling .md per implementation .ts
• 4.2 README.md at root with Modules section
• 4.3 Update CLAUDE.md flow listing

5. Pre-archive verification (5-gate triple)

• 5.1 bunx biome check packages/foundation/flow/workflow/src/ — zero errors
• 5.2 bunx turbo lint typecheck test --filter=@suaveplan/workflow — green
• 5.3 bunx turbo test:coverage --filter=@suaveplan/workflow — 100/100/100/100
• 5.4 No banned patterns (TODO / FIXME / ts-ignore / .skip / .only / biome-ignore / direct vitest import) in src/
• 5.5 bunx turbo build --filter=@suaveplan/workflow — green

6. Pre-archive 7-row checklist

• 6.1 Generics threaded across <TData> / <TCtx>
• 6.2 Zod schema wired at buildConfig() boundary
• 6.3 Every code in WORKFLOW_CODES reachable from a real call site
• 6.4 Strict-mode behaviors covered (onError: stop/compensate/continue)
• 6.5 OTel counters + histogram emitted from production paths and asserted
• 6.6 Lifecycle dedup tested (HookRegistry.once, idempotent unregister)
• 6.7 No retroactive ticks

7. Archive

• 7.1 Fold spec delta into openspec/specs/workflow/spec.md
• 7.2 Move openspec/changes/enterprise-workflow/ → openspec/archive/2026-05-24-enterprise-workflow/
• 7.3 Refresh MANIFEST.md via bun scripts/folder-reorg/generate-manifest.ts