Add a workflow¶

A workflow is a versioned, structured definition of a government journey. It should be driven by an approved service catalog entry—not generated directly from an unconstrained model response.

1. Define the catalog identity¶

Give the workflow a stable machine code, citizen-facing title, supported agencies, and eligibility boundary. Codes are persisted, so rename the display title instead of changing an existing code.

WORKFLOW_CODE = "EXAMPLE_RECORD_UPDATE"
WORKFLOW_VERSION = 1

2. Create the workflow definition¶

Add a definition alongside the existing workflow seeds. Describe:

• intake questions and validation;
• required and conditional documents;
• milestones and their ordering;
• actions within each milestone;
• completion rules and next-action text;
• the agencies that may receive an eventual request.

Use stable IDs for every question, document requirement, milestone, and action. The Flutter client renders these structures dynamically.

3. Register and seed it¶

Register the definition in the workflow catalog and include it in the backend startup seed/test fixture. Seeding must be idempotent. If an existing definition changes meaning, create a new version and preserve active journeys on their original version.

4. Teach the intent layer¶

Add compact routing signals that help the intent compiler distinguish the workflow from nearby requests. The AI may normalize free text, but deterministic policy decides whether the confidence is high enough to suggest or create a journey.

Do not require a life event when the citizen has made a direct service request. “Update an address on my National ID” can be actionable even without a marriage, move, or loss event.

5. Verify the citizen experience¶

Test at least:

1. a clear request that should select the workflow;
2. an ambiguous request that should remain conversational;
3. a related but unsupported request;
4. missing and invalid answers;
5. every conditional document branch;
6. save, reload, and resume;
7. progress calculation and final completion.

6. Document the workflow¶

Update the supported scope and relevant API or operations pages. Record the source and approval status of each requirement internally. Restricted agency material must not be copied into public documentation.