Workflow discovery, creation, and automatic execution design

1. Design decisions

Remove the entry point for new agentic_workflow calls.Separate its capabilities into search_workflows, create_workflow, revise_workflow and execution of a specific Workflow; also provide a complete auto_workflow entry point for manual user use only.

Chat Agent path

Agent → search / create / revise / workflow

The Agent decides whether to call an existing Program directly. Search only when the catalog is large or candidates are not loaded. The Agent does not call auto_workflow.

Manual user path

User → auto_workflow(task)

One request performs search, one visible selection, creation if needed, and execution. Every step remains independently visible in the DAG.

auto_workflow is a convenience orchestration entry, not a candidate Workflow or component. Exclude it from search results, prohibit imports in generated code, and omit it from Agent tools.

workflow/ categorizes code only. Directories, helper files, and internal subdirectories are not Programs. Programs, the Registry, and call graphs treat only actually registered Agent method as executable entities. Directory hierarchy must not change public names, invocation, or execution semantics.

Workflow parameter ownership

Users supply the task, evidence and deliverable requirements. Execution parameters belong to the Workflow; do not expose them through Advanced, settings dialogs or parameter questions.

When a Workflow has several task-dependent parameters, make one tool-free model request before execution to produce the complete plan. Supply real runtime capabilities and application limits. Validate every field and cross-field constraint, apply a complete fallback on invalid output or planning failure, and propagate cancellation. Fixed invariants remain code-owned; the model cannot change permissions, credentials or application ceilings. Persist the effective plan before resumable work and reuse it on resume.

The canonical development example, parameter contract and acceptance checklist are in Workflow authoring. Missing task facts may require clarification; execution tuning must not be delegated to the user.

2. Current implementation and confirmed gaps

Current fact	Problem	Target handling
Public entry points are `search_workflows`, `create_workflow`, `revise_workflow` and the user-level `auto_workflow`; the legacy `agentic_workflow` is no longer registered.`resume_workflow` remains an internal function.	The old name did not indicate search, generation, publication, and execution.	New calls use four explicit entries; historical runs support read-only recovery.
Read-only search, create/revise publication, and specific Workflow execution are independent public operations;`auto_workflow` only orchestrates these entries and retains no second implementation.	Read-only discovery, persistent writes, and business execution must not share one lifecycle.	Separate behavior by public contract; remove the composite execution path.
Existing projects pin run inputs with Git revisions, snapshots, and `project_ref.json` .	Versioning and recovery must remain independent of orchestration.	Retain project formats, snapshots, checkpoints, and explicit resume.
Ordinary execution failures preserve their original error and checkpoint without rewriting published Workflows.	An ordinary execution must not silently change published source.	Pre-publication structural/test repairs stay in create; published changes require explicit revise.
`auto_workflow` appears in user forms and Programs (automatic entry · manual user use only), not in Agent tools.	Users need a complete entry, while Agents already have task routing; these have different semantics.	`auto_workflow` is visible to users and hidden from Agents.
`method_options = dict(tool_visible=)` passes Layer-2 `register(..., expose)`; the default is `True`, keeping all existing functions exposed.	A decorator must express “visible to users, unavailable as an Agent tool.”	`auto_workflow` registers with `tool_visible=False` .
Execution-time repair is removed.`create_workflow` retains bounded pre-publication author retries (`PROJECT_AUTHOR_ATTEMPTS`).	Ordinary run failures must not automatically publish a revision.	Published changes require explicit `revise_workflow`.
Four public entries moved into `workflow/`; the old source directory is deleted.	Classification paths must remain independent of runtime identity.	Programs uses classification directories only for navigation. Function nodes and function-level call graphs derive from the Registry and the selected entry’s reachable AST.
New projects use a multi-file package contract, but product documentation still describes parameterless `workflow()`, banning every import, and automatic execution-time rewriting.	Human authors would follow the old contract and infer actual rules only from validator errors.	Use the current validator as the only rule source, with English/Chinese author pages and shared CLI static validation.
`tests/test_workflow.py`Currently participates only in AST/import checks and is not executed before publication.	Static validity does not establish behavioral correctness; directly executing untrusted tests would cross the security boundary.	First define static validate; later implement a behavioral-test gate with mandatory sandboxing, no network, filtered credentials, constrained write directories, and timeouts.

This design reuses existing Workflow packages, Git, snapshots, checkpoints, DAG callers, and cancellation state. It introduces no second execution Runtime, graph DSL, Workflow database, or string dispatcher.

Code classification and runtime identity

Python directories organize source; runtime identity comes only from registration. Neither derives from the other: directory names cannot automatically become Programs, and moving files cannot automatically change public function names.

openprogram/programs/workflow/
└── workflow/                         # Classification directory, not executable
    ├── __init__.py                   # Entries and shared implementation
    ├── <helper>.py                   # Create only for an independent responsibility
    └── <subsystem>/                  # Further responsibility-based organization as needed

Executable entities shown by Registry / Programs:
  search_workflows
  create_workflow
  revise_workflow
  auto_workflow

Not executable entities:
  workflow
  __init__.py
  Any helper file
  Any internal subdirectory

Layer	Sole responsibility	Prohibited behavior
Filesystem	Organize Python source by `agentic / workflow` type; entries, helpers, and internal subdirectories can share a classification tree.	Do not register Programs merely because files or directories exist; do not pre-create files such as `runtime.py`, `legacy.py` without independent responsibilities.
Registry	Use decorated function names, schemas, exposure, and source files as authoritative runtime identity.	Do not overwrite function names with parent directory names or re-register the legacy `agentic_workflow`.
Programs catalog	Directory nodes expand only; function nodes come from the Registry and can be selected, inspected, and run.	Do not show `workflow/` as an executable Program or helper files as functions.
Call graph	The root is the registered function selected by the user; dependency edges follow its actual calls.	Do not use source directory names as roots or show an old aggregate name because a file contains several entries.
Runtime	Continue calling public function names; run, checkpoint, cancellation, and legacy recovery contracts remain unchanged.	Do not turn source moves into new execution paths, state formats, or compatibility entries.

Long-term constraint:Developers may add entries or helpers in this classification directory for new Workflow management functions, but executable Programs must derive from registered functions. Directory scans may generate navigation nodes, never executable entities.

3. Target architecture and two primary paths

Manual user orchestrationChat Agent decisionPublic Workflow capabilitiesPersistent state and execution

Chat Agent decision order

An already-loaded Program or Workflow clearly matches: call it directly without searching first.
An unloaded dynamic Workflow may exist: call search_workflows.
Complete match: invoke the candidate’s pinned revision directly.
Partial capability only: compose direct calls for a one-off task; when reuse, recovery, scheduling, or stable structure is needed, call create_workflow.
No match: the Agent can still use tools directly for an ordinary one-off task. Create only when the user explicitly requests a reusable asset or the task has stable recurring structure.

4. Public capability contracts

Entry	Caller	Responsibility	Prohibited behavior
`search_workflows(task)`	Agent, user	Deterministically return ranked candidates, pinned revisions, contracts, permissions, and match evidence.	Must not call a model, write files, execute candidates, or publish.
`create_workflow(task)`	Agent, user	Read candidate components, generate a new package, validate, publish, and return a ref.	Must not execute the user task or modify existing projects.
`revise_workflow(workflow_id, request)`	Agent, user	Create a new candidate from a specified revision, validate it, and publish a new revision.	Must not be silently triggered by ordinary execution failure or overwrite old revisions.
`auto_workflow(task)`	Manual user use only	Call search; one visible selection Agent decides reuse/create; finally call the selected Workflow. Layer-2 unexposed registration keeps it out of Agent tools.	Must not appear in Agent tools or search candidates, or automatically revise published projects.
Specific Workflow entry	Agent, user, other Workflows	Execute a defined business contract.	Must not reenter global search or authoring.

{
  "action": "reuse | create",
  "workflow_id": "research_report",
  "workflow_revision": "<immutable git revision>",
  "result": {},
  "run_id": "<workflow run id>"
}

auto_workflow must report whether it reused or created. Search, creation, and execution each produce DAG child nodes, not a single unexplained aggregate node.

5. Search, component reuse, and creation

One package contract and a human-author entry

Agent and human authors use the same static validator. New projects must use the package format pyproject.toml + README.md + __init__.py + workflow.py + tests/test_workflow.py + helper ; legacy entry.py is outside new authoring. The first CLI phase provides openprogram workflows validate <directory>, returning read-only diagnostics for structure, metadata, AST, imports, entries, and dependency-import shapes. Missing dependencies, cycles, and revision pins remain create/revise publication checks.--json provides stable script output. create/revise invokes the same candidate validator before publication, without a second rule set.

Static validate does not execute project code and must not be described as passing publication tests. A behavioral-test gate must run in a mandatory sandbox independent of the user profile, with network disabled by default, credentials filtered, and write directories and time bounded; unavailable sandboxing must deny publication. This gate is a separate subsequent task.

Search contract

Search uses catalog metadata and pinned Git HEAD for deterministic text retrieval, then gives candidate contracts to the calling Agent. Chat Agent decides in the chat path; the manual auto path uses its sole visible selection Agent. Search results are not execution permission; permissions, input schemas, and side effects accompany candidates.

{
  "workflow_id": "web_research",
  "revision": "<git revision>",
  "retrieval_score": 4,
  "matched_terms": ["web", "research"],
  "input_schema": {},
  "output_schema": {},
  "permissions": ["network"]
}

Reuse components during creation

create_workflow receives read-only snapshots of available Workflows and the public Program catalog. Generated projects reference Workflow packages through normal Python imports without copying dependency source. The manifest pins each dependency revision; publication rejects dependency cycles, missing entries, and undeclared permission expansion.

research_report/
├── pyproject.toml
├── README.md
├── workflows/
│   └── research_report/
│       ├── __init__.py
│       ├── collect.py      # imports web_research
│       └── synthesize.py
└── tests/
    └── test_research_report.py

Pin inputs

Freeze catalog revisions and reachable dependencies; later external commits do not change this authoring attempt.

Generate one candidate

Only the candidate directory is writable; source repositories, dependency Workflows, and user directories stay read-only.

Deterministic validation

Check package, unique entry, schemas, imports, dependency closure, cycles, permissions, and test commands.

Bounded pre-publication repair

Repair only generated-candidate structure or test failures, with a retry limit. Do not repair cancellation or provider errors.

Atomic publication

After all validation succeeds, create one commit and update the catalog. Return a Workflow ref without executing the user task.

One-off tasks do not automatically create Workflows. Creation requires an explicit user request or at least one need for stable reuse, recovery, scheduling, or versioned review.

6. Lifecycle, failure, and trust boundaries

Phase	Allowed state change	Failure rule
search	No persistent run; read-only result	Report or skip corrupt catalog items; never change projects.
create / revise	`running → completed \| failed \| cancelled`	Failure and cancellation do not publish. Candidates may be reclaimed; diagnostics go to run state.
workflow run	`running → completed \| failed \| capped \| cancelled \| interrupted`	Preserve the original error and checkpoint; do not automatically rewrite a published Workflow.
auto	Aggregate child-call state	Stop on any child failure; never mark partial results completed.
resume	Resume only the specified run	Pin the original snapshot/revision; do not search again or reselect a project.

Boundary requirements

Authoring writes are limited to the current candidate and run state. Network, credentials, and external tools follow current session permissions.
Publication to the same target Workflow must serialize; different projects may run concurrently. Concurrent publication does not alter running snapshots.
Cancellation, permission denial, timeout, provider terminal errors, and external Stop never enter repair.
The invocation form inherits the session’s Project; it offers no second working-directory override.
Local App refresh refuses to proceed when active runs exist; restarting must not rewrite run state as failed or cancelled.
Legacy code.py, legacy snapshots, and historical runs support read-only recovery; new calls never produce the old format.

7. Official framework comparison

Comparisons establish boundaries only; OpenProgram does not import other frameworks’ Runtimes or DSLs. “Not covered” means the cited official pages do not define a complete product contract for automatically generating and publishing persistent Python Workflows.

Official material	Relevant capability	Adoption or adaptation	Not directly covered
OpenAI Agents SDK · orchestration	Distinguishes LLM decisions from code orchestration; a manager can call specialized Agents as tools.	Adopt “Chat Agent owns the user conversation; specialized capabilities are independent tools”;`auto_workflow` uses code orchestration.	Does not define local Workflow catalog generation, Git publication, or legacy-run compatibility.
OpenAI Agents SDK · tool search	Large tool surfaces can defer search and loading while keeping search observable.	Adopt on-demand search without searching before every message; return contracts rather than directly executing.	Does not create new persistent tool implementations.
LangGraph · workflows and agents	Explicitly distinguishes predefined Workflow paths from Agents that dynamically choose tools.	Adopt the responsibility distinction; retain Python control flow without adding a graph DSL.	Does not define Agents automatically writing, testing, and publishing new Python Workflows.
LangGraph · subgraphs	Reuses subgraphs through input/output schemas with explicit parent/child persistence boundaries.	Adopt contract-based composition and pinned dependency revisions; OpenProgram expresses relationships using Python imports.	Does not provide an OpenProgram-style Git project catalog or authoring-publication flow.
CrewAI · Flows	Flows combine explicit events, state, and Crews into structured processes.	Adopt only the separation of deterministic processes from Agent collaboration.	The cited page does not describe runtime search and generation of persistent Flow assets.

Adopted, adapted, and rejected

Choice	Decision	Boundary
Agent searches tools/Workflows on demand	Adopt	Call known Programs directly; search large catalogs only.
Contract-based composition of reusable subprocesses	Adapt	Use Python imports, schemas, and pinned Git revisions without a subgraph DSL.
Manager-style complete entry	Adapt	Manual user use only: `auto_workflow`; Agents do not call it recursively.
Automatically rewrite published flows after execution failure	Reject	Changes must explicitly enter `revise_workflow`.
Automatically persist every one-off task	Reject	Let the Agent complete tasks directly when reuse or recovery has no value.
Create similar Workflows based on task wording	Reject	Selection assesses capabilities by candidate contracts. Language, output paths, date ranges, and ordinary parameter differences do not constitute a new execution structure.

8. Implementation plan

Each phase has a separate commit and proceeds through public RED, minimal GREEN, specification review, and quality review. Do not start the next phase until both reviews pass. Existing tests/component/agent/test_agentic_workflow.py anchors the monolithic entry; migrate corresponding test ownership in each phase so removing the entry does not invalidate all tests at once.

Phase 0

Connect exposure controls

Add to Agent method a tool-level exposure parameter passed into Layer-2 register(..., expose); reuse existing _unexposed/exposed_names().

Gate: minimal registration-contract tests prove the parameter takes effect; defaults remain unchanged and all existing functions stay exposed.

Phase 1

Extract read-only search

Extract from the existing module the public contract search_workflows ; return pinned revisions, schemas, permissions, and match information; exclude auto_workflow and legacy projects. Move search tests to the new entry.

Gate: catalog and run directories remain byte-identical before and after the call; the Agent can read candidates without execution nodes.

Phase 2

Separate creation and revision

Move candidates, validation, dependency pinning, and publication into create_workflow; implement revise_workflow with an explicit target and new revision. Creation does not execute the user task. Delete execution-time repair; move author/validate/publish tests to the new entry.

Gate: create adds only one project; revise adds only one revision; failure, cancellation, and terminal errors never publish; no automatic execution-time publication path exists.

Phase 3

Create user-level auto_workflow

Use the preceding public capabilities for search → visible select → reuse/create → run. The full DAG shows each step. The invocation form contains only task and inherits the session Project; register it as hidden from Agents using Phase 0.

Gate: visible in user forms but absent from Agent tools; real App reuse and create paths are distinguishable.

Phase 4

Remove new agentic_workflow calls

Stop registering the old entry and remove selection/repair branches used only by the old composite path. Retain explicit resume_workflow(run_id) and the legacy read-only executor. Delete or migrate remaining tests tied to the monolithic entry; retain resume/legacy tests.

Gate: new catalogs, DAGs, and runs contain no agentic_workflow; historical runs remain inspectable and resumable with unchanged artifacts.

Phase 5

Classification directories, UI, documentation, and final gates

First establish “directories classify; Registry defines runtime identity,” then move relevant source into workflow/. Programs creates expandable navigation from actual directories and function nodes from the Registry; the call-graph root uses the selected function name. Finally synchronize product documentation and accept direct, reuse, create, cancel, and legacy recovery in the default App.

Gate: the source tree has no old agentic_workflow/; the Registry has no legacy name; in Programs, workflow expands but cannot run. Its expanded contents show only four registered functions. Helper files and internal directories are not Programs. Call-graph roots use selected function names. Directory moves do not change registered schemas, execution, recovery, or cancellation. Automated regressions must cover these constraints, followed by documentation build, zero dead links, and visual acceptance in the default App.

Phase 6

Unify author static validation

Expose the current package validator as a shared read-only entry for the human CLI and Agent author; add English/Chinese author specifications. create/revise revalidates candidates through the same function before publication. Exclude legacy reading, behavioral tests, scaffold, publish CLI, and catalog migration from this phase.

Gate: a valid directory yields the same metadata and file list in CLI and Agent candidate validation. Invalid directories return nonzero status and deterministic diagnostics. Validation neither writes directories, initializes Git, nor executes test code.

Phase 7

Mandatory isolated behavioral-test gate

Run candidate tests before publication in a mandatory sandbox independent of the user profile, with no network, filtered credentials, constrained write directories, and a timeout. Missing sandbox, test failure, or cancellation prevents publication.

Gate: malicious credential reads, out-of-root writes, network access, timeout, and ordinary failure all have public RED tests. create/revise keeps catalog and HEAD unchanged on every failure.

Minimum file boundaries

Scope	Preferred change location	Explicit exclusions
Runtime and public functions	`openprogram/programs/workflow/` classification directory; organize entries, shared implementation, and necessary internal subdirectories as ordinary Python code within it.	Do not register classification directories as Programs, rewrite execution Runtime during source moves, or pre-create files without actual responsibilities.
Registration and exposure	`openprogram/programs/_registry.py`, `_runtime.py` ’s existing exposure mechanism.	No second permission or tool-registration system.
Component and execution tests	Existing Workflow public-entry tests, registration-contract tests, and legacy recovery tests. Test filenames may be cleaned separately later and do not define runtime identity.	Do not rewrite Runtime tests because source moves; do not replace public-entry tests with mock-only coverage.
Programs UI	Existing Programs routes, catalog, and page components; the backend returns classification nodes and registered function nodes separately.	Do not maintain a second frontend Workflow function list or create a Workflow database or separate management application.

9. Public acceptance matrix

Scenario	Public entry	Required observation
Agent already has an exact tool	Chat message	Direct Workflow Call; no search/create/auto nodes.
Complete match in catalog	`search_workflows` → Workflow	Return a pinned ref and reuse it; no repository or revision changes.
Partial components only	`create_workflow`	New package references components by import without copying dependency source; does not execute the user task.
Explicit revision	`revise_workflow`	Old revision remains executable; new revision becomes active after all publication gates pass.
Complete automatic user run	`auto_workflow`	DAG shows search, the sole selection Agent, optional create, and final Workflow; result includes action and ref.
Same task type, different wording or language	`auto_workflow`	Search candidates carry validated name, summary, and tags as capability descriptions. Reuse pinned revisions when existing capabilities cover the task. A zero term score alone does not justify create. When candidates exist, create requires a concrete nonempty missing_capability or is rejected before authoring.
Agent tool discovery	Chat Agent tool inventory	Includes search/create/revise and specific Workflows; excludes auto and the legacy agentic entry.
Programs classification browsing	`functions / agentic / workflow`	`workflow` is a non-executable classification node with only four registered functions as children. Helpers and internal directories do not become Programs.
Programs call graph	Select any Workflow management function	Title and root use the selected function name, never the old `agentic_workflow` or a directory name as runtime identity.
Execution failure	Specific Workflow	State is failed, original error retained, published source and HEAD unchanged.
Cancellation or Stop	create/revise/auto/run	Relevant runs end cancelled, without repair, publication, or leftover running state.
Concurrent publication to one project	Two revise calls	Serialize active-revision validation; lose no commits and never overwrite a new HEAD.
Legacy-run recovery	Internal compatible recovery (`resume_workflow(run_id)`)	Execute the pinned old artifact read-only; create no project, publish nothing, and do not change the old snapshot.

Final completion cannot rely on unit tests alone. Exercise real forms and Chat paths in the default /Applications/OpenProgram.app , then reload the session and verify DAG callers, run states, Workflow refs, and catalog changes.

10. Implementation status

Parameter ownership is a design requirement with a development example. Existing Workflows require individual adoption; Goal currently selects reasoning effort automatically and retains defaults for its other settings. This document does not mark full-parameter planning as implemented across the catalog.

Capability	Current evidence	Status
Git Workflow packages, snapshots, checkpoints, and explicit resume	Already implemented in the current runtime and retained by this design.	Existing
`Agent method` tool-level exposure connected to Layer-2	`method_options = dict(tool_visible=)` passes Layer-2 `register(..., expose)`; the default is `True`, keeping all existing functions exposed.	Implemented
Independent `search_workflows`	Public read-only entry returns pinned revisions, schemas, permissions, and match evidence; excludes `auto_workflow` and legacy projects without entries; no model calls, file writes, execution, or publication.	Implemented
Independent `create_workflow` / `revise_workflow`	create adds only projects without executing user tasks. revise rejects publication when candidate contents equal the active revision (`revision unchanged`); otherwise it adds one revision. Dependency revisions are written into `pyproject.toml` ’s `workflow-dependencies`; failures and cancellations never publish.	Implemented
User-level `auto_workflow`	Source lives in `openprogram/programs/workflow/auto_workflow.py`; visible in user forms and Programs automatic entries; registered with `tool_visible=False` ; orchestrates search → visible selection Agent (public `agent()`, `AUTO_DECISION_ATTEMPTS=3`) → reuse/create → pinned execution, without automatic revise. This entry is a complete single-file Workflow without independent steps, dependencies, or a test package, so no same-named directory is added.	Implemented
Suppress creation of similar Workflows	Search gives selection validated names, summaries, and tags. Selection prefers candidates whose capabilities cover the task. Wording, language, output paths, date ranges, and ordinary parameter differences must not trigger create. A zero term score indicates only lack of lexical overlap. With nonempty candidates, create without missing_capability fails before publication.	Implemented
Shared static author validator and CLI	Agent candidates and local directories use the same package contract;`openprogram workflows validate` is read-only, supports text/JSON diagnostics, and neither imports nor executes candidate code. Reading development directories ignores Python-generated`__pycache__` without relaxing source-location rules. Metadata identity, a unique public entry, safe`__all__`, decorator origin, and final re-export binding are checked by the same validator.	Implemented
Pre-publication behavioral-test gate	Manual test/publish and generated create/revise execute behavioral tests in a mandatory OS sandbox independent of the user profile. Independent review passes; complete integration acceptance is still underway.	Pending
Revision-specific execution and dependency pins	`_run_published_workflow` uses `git archive` to check out the selected revision;`workflow_dependencies` persists at publication and is pinned during execution. Old revisions remain executable after a new HEAD is published.	Implemented
legacy `code.py` resume	`resume_workflow` replays legacy run snapshots/`code.py` read-only. Failures return failed without calling the planner or rewriting artifacts.	Implemented
Workflow cancellation terminal state	Internal `resume_workflow(run_id)` direct regressions cover package snapshots, legacy `code.py` and `SINGLE`: `CancelledError` persisted as a non-executable `cancelled` run projection;`KeyboardInterrupt` is persisted as a `interrupted` run projection allowing later calls to reuse artifacts/checkpoints. Both retain original exception propagation. Generating and persisting a new canonical `execution_id` for a recovery attempt remains the responsibility of unified Execution integration.	Implemented
Stop new `agentic_workflow` calls	The old entry is no longer registered; new catalogs, DAGs, and runs contain no `agentic_workflow`; `resume_workflow` remains an internal function.	Completed
Separate classification directories from executable entities	`workflow/` serves only as classification. Programs shows four public functions from the Registry, supporting nested categories and multi-entry files. Call graphs analyze the selected function and reachable helpers; directories and helpers do not define runtime identity. Specification and quality re-reviews passed.	Implemented
Real acceptance in default App	Code and documentation gates are complete, awaiting visual acceptance in the default `/Applications/OpenProgram.app` for direct / reuse / create / cancel / legacy resume.	Pending

Phase 0–6 source implementation, component regressions, CLI public paths, documentation build, and both independent re-reviews are complete. Mandatory sandbox behavioral-test gates and real default-App acceptance remain pending.

11. Explicit exclusions

Do not add @workflow, a graph DSL, a second Runtime, or a string call_workflow() dispatcher.
Do not automatically turn every user message into a Workflow or create projects by default for one-off tasks.
Do not automatically modify published Workflows or implicitly publish revisions after ordinary execution errors.
No Workflow database, background Git polling, remote push, Marketplace, or remote dependency resolution.
This phase does not implement scaffold, manual publish commands, catalog state-directory migration, or execution of untrusted tests; each is a separate subsequent task.
Do not change existing Python call semantics for Agents, Programs, or Workflows; this design separates only entry points and lifecycles.

Portable Workflow package contract

A Workflow is a self-contained Python package under openprogram/programs/workflow/<workflow_id>. Its public function name and package-relative location remain stable when the OpenProgram checkout moves. Package metadata, imports, dependency revisions, UI links and invocation requests never contain a developer home directory.

Concern	Contract
Identity	The lowercase package identifier is the registered callable name. Python composition uses ordinary imports and direct calls. No new runtime, decorator or invocation protocol is introduced.
Internal location	Persist `{"scope":"programs","path":"workflow/weekly_report"}` using a canonical two-component POSIX path. The scope means `openprogram/programs/` in the active project. Resolve it against the active OpenProgram Programs catalog only at filesystem boundaries. Never resolve it against the conversation working directory. Reject absolute scoped paths, traversal and ambiguous catalog matches. When a wheel contains a non-Git copy of a Workflow, that copy does not compete with the independently versioned source package; two matching Git projects remain ambiguous.
External installation	The installed App may use an explicitly owner-recorded source checkout. A single `catalog_root` installation binding identifies that checkout; `refresh-local-app.sh` updates it from the checkout being installed. This binding is distinct from each package's portable path. External development symlinks retain their explicit authorization; a relative identifier does not authorize arbitrary external code.
Migration	Convert previously authorized in-project absolute entries to scoped relative entries, including records whose old checkout no longer exists. Only a structurally valid matching package in a known catalog can satisfy a legacy Workflow entry. Do not repeat unrestricted directory discovery when a checkout moves. Preserve unrelated external records and authorization revocation.
CLI listing	`openprogram programs list` includes published Workflow entry points already loaded by the authorized registry, including projects inside one category directory. Names and descriptions come from their registered callables and source. Keep bundled entries and optional Program status; list each name once. Do not import or list arbitrary unrecorded directories, alter tool exposure, or execute Workflow bodies to list them. Verify through a fresh CLI process with an isolated owner catalog and an unapproved sibling.
Discovery and UI	Use one callable catalog for launch parameters and favorites. Refresh updates React and runtime readers together. A missing or invalid callable produces a visible error; Use never silently waits and disappears. Sidebar and Programs launch use the same handoff. Resolve a missing cached callable with one authenticated catalog fetch, publish that response to both shared readers, and display a localized failure if the callable is unavailable. Route cleanup, a newer launch or a changed chat owner cancels stale form opening. Do not consume a pending launch before the deferred chat reset completes.
Authoring	Design input, output, side effects, failure and cancellation before implementation. Keep metadata, public entry point, helpers, tests and README inside the package. Validate structure, run behavior checks, publish an immutable revision, verify discovery, favorite and open its parameter form. A static validation pass is not execution evidence.
Compatibility	Preserve existing function names, schema, favorites ordering, dependency pins, ordinary Python imports and uncommitted Workflow files. Runtime absolute paths remain internal filesystem details, not persisted package identities.

Authoring and publication lifecycle

The formal manual interface is openprogram workflows validate DIRECTORY, openprogram workflows test DIRECTORY, and openprogram workflows publish DIRECTORY. Validate is read-only. Test copies a validated candidate and pinned dependencies into a temporary workspace and runs its tests in a required OS sandbox with network disabled, credential-free environment, protected source files and bounded process lifetime. Manual publication and the generated create/revise entry points use the same required behavior-test gate. Publish repeats validation and tests on the exact snapshot it commits; it never trusts an old success report. Existing packages require an explicit --replace and a clean destination. Failure, timeout, sandbox unavailability or unsuccessful tests publish nothing.

Documented from workflows.NAME import NAME imports resolve to the same authorized callable as openprogram.programs.workflow.NAME in the live catalog. The live alias exposes only named authorized entry points. Snapshot execution explicitly owns its workflows namespace and continues to load pinned bytes; it never falls back to the live catalog. The package README specifies purpose, input, output, effects, failure/cancellation behavior, dependencies, tests and a reproducible invocation.

Acceptance

Record, move the checkout, discover and resolve the same authorized Workflow without editing package metadata or per-package paths.
Recover the previously recorded weekly-report package from its obsolete checkout prefix without authorizing unrelated directories.
Reject traversal, unknown scope, unauthorized packages and ambiguous resolution; preserve explicitly installed external sources.
In the default installed App, the existing weekly_report favorite appears and Use opens its task form; do not execute or submit a report during acceptance.
The English authoring guide and Chinese translation specify identical creation, validation, publication, relocation and troubleshooting behavior, with commands verified against the CLI.

Implementation status

Scoped source persistence, authorized legacy relocation, installed-catalog import and shared form launching have passed independent specification and quality review. Manual test/publication, documented import aliases and authoring documentation have also passed independent specification and quality review. Repository-wide verification is incomplete and does not imply a full-suite pass. Installed-App acceptance and deployment are recorded in release evidence.