# Ported Workflows — Notes

The four workflows in this directory are **OpenLife-adapted ports** of
community workflow patterns for story-driven development. They are
read-only reference material once shipped; OpenLife runtime loads them
through `CompositeWorkflowProvider`, which also reads
`.catalog/workflows/` for local overrides.

## What was kept verbatim

- The four-phase shape of `story-development-cycle` (Create → Validate → Implement → QA).
- The Bootstrap → Discovery → Sharding → Dev Cycle backbone of `greenfield-fullstack`.
- The 10-phase outline of `brownfield-blueprint` (3 data-collection + 3 review + QA gate + 3 finalization).
- The 5-iteration cap of `qa-loop`.
- Standard agent slots (`@analyst`, `@pm`, `@architect`, `@ux-design-expert`, `@dev`, `@qa`, `@po`, `@sm`, `@devops`, `@data-engineer`).

## What was removed during the port

| Upstream field/concept | Why removed |
|---|---|
| Refs to upstream-specific config files | OpenLife uses `.openlife/` for runtime state; the references would mislead operators. Replaced with `.openlife/config.yaml` etc. |
| `optional_steps: [brainstorming-session, market-research-prompt, …]` blocks | Carried over as `optional_steps` field on the host step. Upstream surfaces these as guided sub-prompts; OpenLife v1.2 just lists them — execution of the sub-prompts is operator-driven. |
| Inline `condition: user_wants_ai_generation` with complex expression syntax | OpenLife v1.2 supports only literal boolean flags via run context (`ctx[step.condition] === true`). Anything compound stays out of scope until v1.3 adds an expression evaluator. |
| Long inline `notes:` blocks repeating reference material | Pruned to operator-actionable guidance only. The KB is reference; the workflow is execution. |
| Upstream QA-loop auto-decision (`verdict_blocked` → automatic escalate) | OpenLife v1.2 engine does not yet support conditional short-circuit. The loop is unrolled into 5 explicit iterations; escalation runs as the final phase after the loop budget exhausts. Replaced when v1.3 adds `condition: !qa_approved`. |

## What was added (OpenLife-specific extensions)

| Extension | Where | Rationale |
|---|---|---|
| `squad: <id>` on `qa-gate` step | story-development-cycle, brownfield-blueprint | Lets the gate delegate to the qa-loop squad as a unit, not just `@qa` solo. The upstream schema had no squad slot at the step level. |
| `idempotent: true` flag | All review-and-fix loop steps | Engine resume after partial-run crash respects this — non-idempotent steps are skipped on resume to avoid double side-effects; idempotent steps may re-execute once. |
| `creates` paths rooted in `docs/` and `.openlife/` | All workflows | Aligns with OpenLife's runtime/state layering. |

## Validation

All four files parse clean against `WorkflowSchema` via
`openlife workflow validate <file>`. Verified by Story 4.4 AC #1.

```bash
openlife workflow list
openlife workflow validate dist-templates/workflows/story-development-cycle.yaml
openlife workflow validate dist-templates/workflows/greenfield-fullstack.yaml
openlife workflow validate dist-templates/workflows/brownfield-blueprint.yaml
openlife workflow validate dist-templates/workflows/qa-loop.yaml
```

## Extension contract

Operators may add their own workflows under:

1. `dist-templates/workflows/<id>.yaml` — ships with the npm package (preferred for community-distributed templates)
2. `.catalog/workflows/<id>.yaml` — local override / project-specific

`CompositeWorkflowProvider` reads from both, with the local catalog taking
precedence when an id collides.

> Reference: `WorkflowSchema.ts` for the strict schema and stable error codes;
> `WorkflowEngine.ts` for execution semantics including elicit pause, resume,
> and abort.
