Skip to content

Shared Workflow Infrastructure

This document defines when shared Python infrastructure belongs under factory_app/workflows/_shared/ instead of a workflow-local tools/ directory or the runtime core.

Core Rule

factory_app/workflows/_shared/ is for factory-owned builder infrastructure consumed by multiple factory workflows.

It is not part of generated workflow bundles.

Do not confuse these three cases:

  • factory_app/workflows/_shared/: factory-owned shared implementation used by AppGenerator, AgentGenerator, DesignDocs, ValueEngine, ThemeCapture, or other builder workflows
  • factory_app/workflows/{WorkflowName}/tools/*.py: workflow-local implementation owned by one workflow pack
  • mozaiksai.core.*: runtime/framework APIs required by runtime instances beyond the builder

What Belongs In _shared

Put a module in factory_app/workflows/_shared/ only when all of these are true:

  • it is consumed by two or more factory workflows
  • it is builder infrastructure, not app-specific or product-specific behavior
  • it should run as part of generation/build orchestration, validation, or bundle assembly
  • it does not belong to every runtime instance as a general framework API

Typical _shared examples:

  • deterministic quality gates reused by multiple generator workflows
  • builder-only lifecycle helpers reused across multiple factory workflows
  • static audit/validation helpers shared by AppGenerator and AgentGenerator

Current canonical examples:

  • factory_app/workflows/_shared/generated_ui_contract.py
  • factory_app/workflows/_shared/platform/build_lifecycle.py

What Must Stay Workflow-Local

Keep code inside factory_app/workflows/{WorkflowName}/tools/ when any of the following is true:

  • the helper is only used by one workflow
  • the helper is part of that workflow's authored contract
  • the workflow manifest references the file as a workflow-local tool path
  • the helper expresses workflow-specific business behavior, prompt semantics, or output shaping

Generated workflow bundles must keep their own helpers workflow-local. Generated output must not emit or depend on:

  • workflows/_shared
  • app.workflows._shared
  • sibling workflow tool folders

If a workflow manifest needs a workflow-local file path but the implementation is shared, use this pattern:

  1. put the implementation in factory_app/workflows/_shared/...
  2. keep a thin workflow-local wrapper in tools/...
  3. let the workflow manifest continue to reference the workflow-local file

That keeps runtime file-path expectations stable while making shared ownership explicit.

What Belongs In mozaiksai.core

Promote code into mozaiksai.core.* only when it is required outside the builder and is part of the runtime/framework contract itself.

Examples:

  • runtime orchestration primitives
  • workflow pack parsing/loading
  • multi-tenant filtering and persistence namespaces
  • transport, eventing, or shared framework adapters

Do not move builder-only logic into runtime core just because more than one factory workflow uses it.

DesignDocs Boundary

DesignDocs is not the owner of shared builder infrastructure.

DesignDocs may describe:

  • surface ownership
  • UI intent
  • realization boundaries
  • persistent app/workflow contracts

But DesignDocs does not decide where shared Python builder helpers live. That boundary is enforced directly in the builder implementation:

  • tool imports
  • hooks
  • deterministic quality gates
  • assembly/persistence tools

If shared code participates in generation or validation, wire it into the factory workflow tools and hooks directly. Do not rely on DesignDocs prompt prose to make it part of the build process.

Practical Decision Order

When adding a helper, decide placement in this order:

  1. Is it used by only one workflow? Put it in that workflow's tools/.
  2. Is it used by multiple factory workflows but only during builder execution? Put it in factory_app/workflows/_shared/.
  3. Is it required as a general runtime/framework API beyond the builder? Put it in mozaiksai.core.*.

Cross References