Externalize built-in workflows into declarative workflow packs

[amiel-35]

Problem

Built-in workflows currently appear to be shipped as application data or code rather than as first-class, versionable workflow definitions.

This makes workflows harder to:

• review
• diff
• translate
• localize by jurisdiction
• contribute without touching TypeScript
• import/export between deployments
• maintain independently from the application engine
• reuse across hosted, self-hosted, and local deployments

For a legal AI product, workflows are not just UI defaults. They are reusable legal work products: prompts, review columns, output formats, extraction rules, and task-specific instructions.

Keeping them inside application code or opaque runtime data makes community contribution and jurisdiction-specific adaptation harder than it needs to be.

Current behavior

From the current application model, workflows seem to be represented with fields such as:

id
title
type
practice
prompt_md
columns_config
is_system

This is a good underlying model. The missing piece is a clean file-based format for defining, reviewing, importing, exporting, and contributing workflows.

Proposal

Introduce a declarative workflow pack format, based on YAML or JSON, backed by a JSON Schema.

A workflow definition could map directly to the existing workflow model.

Example:

id: builtin-nda-review
title: NDA Review
type: tabular
practice: Commercial
jurisdiction: US
language: en
version: 0.1.0
is_system: true

prompt_md: |
  Review the uploaded NDA and identify key legal and commercial issues.
  Base your review only on the provided document.
  Cite the relevant document passages where possible.

columns_config:
  - name: Parties
    format: bulleted_list
    prompt: Identify all parties and their roles.

  - name: Confidentiality obligations
    format: free_text
    prompt: Summarize the confidentiality obligations, exclusions, duration, and key exceptions.

  - name: Term and survival
    format: free_text
    prompt: Identify the term of the agreement and any survival provisions.

  - name: Risk level
    format: risk_level
    prompt: Classify the overall risk as low, medium, or high, based only on the document.

Suggested repository structure

workflow-packs/
  builtin/
    nda-review.workflow.yaml
    credit-agreement-review.workflow.yaml
    commercial-lease-review.workflow.yaml

  examples/
    simple-assistant.workflow.yaml
    simple-tabular-review.workflow.yaml

schemas/
  workflow.schema.json

docs/
  workflows.md

Possible implementation path

This could be introduced incrementally:

1. Define workflow.schema.json
2. Add a loader for .workflow.yaml and/or .workflow.json
3. Add a script such as:

npm run workflows:import

4. Optionally support an environment variable:

WORKFLOW_PACKS_DIR=./workflow-packs

5. Import workflows into the existing workflows table
6. Keep backward compatibility with existing built-in workflows
7. Move existing built-ins to declarative files over time
8. Document how to create and contribute workflows

Possible import behavior

The import script could:

• read all *.workflow.yaml and *.workflow.json files
• validate each file against workflow.schema.json
• upsert workflows by stable id
• preserve existing user-created workflows
• mark imported built-ins as is_system = true
• fail clearly when required fields are missing
• report imported, skipped, and invalid workflows

Example command:

npm run workflows:import -- ./workflow-packs/builtin

Non-goals

This proposal does not require:

• changing the workflow execution model
• removing existing database-backed workflows
• replacing the current UI for creating workflows
• forcing all workflows to be public
• changing LLM providers
• changing document processing

It only proposes making workflow definitions easier to store, review, import, export, and contribute.

Benefits

• Cleaner separation between engine and legal content
• Easier community contributions
• Easier localization by language and jurisdiction
• Reviewable diffs for prompt and column changes
• Easier private workflow packs for firms or organizations
• No need to rebuild application code for content-only changes
• Better support for hosted, self-hosted, and desktop deployments
• Foundation for curated workflow packs or marketplaces later

Why this matters

Mike is especially promising because it is not just a generic chat interface. Its value comes from structured legal workflows, tabular review, document-specific instructions, and reusable legal tasks.

Making workflows declarative would make that value easier to extend, review, share, and adapt.

It would also make it easier for contributors to create jurisdiction-specific packs, for example:

workflow-packs/
  us/
    finance/
    corporate/
    litigation/

  uk/
    commercial/
    employment/

  eu/
    gdpr/
    procurement/

  fr/
    contrats/
    corporate/
    immobilier/
    rgpd/

Suggested acceptance criteria

A first version could be considered complete if:

• at least one assistant workflow can be loaded from a YAML or JSON file
• at least one tabular workflow can be loaded from a YAML or JSON file
• workflows are validated before import
• invalid workflows produce actionable error messages
• imported workflows appear in the existing workflow UI
• the format is documented
• the existing built-in workflows continue to work