Workflow Extension Lifecycle

Workflows turn tools, agents, connectors, approvals, and artifacts into repeatable execution paths. A workflow can be a built-in runtime template, a saved workflow draft, an automation workflow, or a project workflow selected by the coordinator bridge.

Adding or changing a workflow is a runtime contract change. Treat it as more than a designer layout: it defines who can trigger work, which tools and profiles run, what side effects are possible, what evidence is produced, and how completion is verified.

Lifecycle

Choose the workflow kind and owner.
Define the trigger and input contract.
Model the graph with explicit nodes and connectors.
Bind roles to agent profiles, tools, skills, and policy classes.
Declare approval behavior for repo writes, external writes, and other high-risk actions.
Define output artifacts and structured results.
Add verifier, smoke, and negative tests.
Document operator-facing review steps.
Verify capability inventory and project/profile reachability.

Choose The Workflow Shape

Use the smallest workflow shape that matches the job.

Shape	Use when
Built-in workflow template	The runtime needs a stable reusable scaffold such as coding, analysis, QA, research, provider smoke, or self-development.
Saved automation workflow	A local operator wants a repeatable manual, scheduled, webhook, or future file-watch workflow.
Project workflow	The coordinator should use a project-specific graph for a known runtime template.
Child workflow	A parent workflow needs to call another saved workflow and keep traceable child-run output.

Do not seed customer-specific workflows as built-in Aegis fixtures. Keep project-specific report packages, account choices, and client-specific profile mappings in saved workflow or project data.

Template Contract

Built-in workflow templates are validated by workflowTemplateSchema and should declare:

Field	Purpose
`id`	Stable template id used by coordinator runs, saved project workflows, capabilities, and tests.
`version`	Template version. Bump when role order, task shape, approval behavior, or output contract changes.
`stages`	Ordered runtime phases such as intake, plan, execute, verify, repair, review, or finalize.
`roles`	Stable role names used by task sessions and profile records.
`taskTemplates`	Role/objective pairs that describe delegated work.
`agentProfiles`	Optional role defaults for provider, model, prompt profile, tools, skills, and policy class.
`repairPolicy`	Optional bounded repair behavior.
`allowedTools`	Permission tokens available to the workflow.
`verifierConfig`	Verifier or smoke metadata required by the runtime.
`approvalRules`	Action types that require approval.

Saved workflow drafts use graph data: nodes, connectors, runtime, and optional template metadata. Nodes should stay user-level and executable; do not expose every internal field, retry note, output key, or bookkeeping concern as its own visible node.

Trigger And Input Contract

Every workflow needs a clear trigger and bounded input shape.

Common triggers:

manual run;
coordinator chat;
schedule;
webhook;
saved workflow call;
connector source intake;
future file-watch trigger.

Inputs should be explicit enough to replay and test:

project path or source package reference;
account or connector ids;
workflow template id when work will be queued;
request text or structured request fields;
approval preview for generic external writes;
output artifact paths when downstream nodes depend on them.

If required trigger details are missing, ask the operator before queuing work. Do not encode uncertainty as a failed test result.

Graph And Connector Rules

Workflow graphs should be readable at the operator level.

Use trigger nodes for intake.
Use explicit tool/action nodes for connector calls, parsing, notification, storage, and coordinator queueing.
Use agent.delegate for genuine model-backed reasoning, summarization, classification, or structured-output decisions.
Use branches, filters, joins, retries, loops, and delays only when they represent real control flow.
Use connector payload mappings when downstream inputs depend on upstream output.
Preserve existing graph topology unless the change explicitly requires rewiring.

Avoid adding manual approval nodes just because a workflow creates a draft artifact. Add approval when the next action sends, mutates external state, writes a repo, changes Aegis configuration, or crosses another high-risk boundary.

Tools, Profiles, And Skills

Workflow permissions should come from explicit role/profile configuration, not hidden runtime assumptions.

Agent nodes should declare the intended role.
Profiles should declare provider/model hints, prompt profile, tool allowlist, skill ids, approval policy class, and allowed policy classes.
Tool permissions should use complete allowlists. A broad token should not silently unlock connector-specific or verifier-specific behavior.
Connector account ids and scopes should be visible in node config or project data.
Project workflows should preserve coordinator repo-write guardrails such as external write requests, trusted repo-write access, auto-apply limits, and approval policy.

For tool-level details, follow the Tool Extension Lifecycle.

Approval Behavior

High-risk actions need an explicit approval story before a workflow is considered complete.

Approval-sensitive examples:

repo writes;
external writes;
generic OAuth *.api-request write methods;
report delivery/send steps;
purchases, trades, tax, network-device actions, and broad self-extension;
destructive local cleanup or restore actions.

Approval previews should bind the decision to concrete inputs: action type, target, account id, method, path, artifact path, content hash, expected side effect, and evidence to review.

Coordinators and agents should not be able to approve human-owned high-risk checkpoints.

Outputs And Artifacts

Workflows should produce durable evidence, not only model prose.

Expected outputs can include:

workflow-test/result.json for designer/manual test runs;
project-workflow/bridge.json, project-workflow/result.json, and project-workflow/draft.json for project workflow bridge runs;
run artifacts produced by tools;
coordinator reports;
report section artifacts;
approval checkpoint artifacts;
notification or delivery draft artifacts.

Downstream nodes should reference artifact paths or structured output fields, not scrape model text.

Verification

Completion should depend on evidence.

Use the right verification layer:

schema validation for templates, saved workflow drafts, and workflow test inputs;
focused node-level tests for new primitives and mappings;
workflow draft/manual run tests for graph execution;
coordinator bridge tests for project workflow templates;
artifact contract tests for report or delivery workflows;
approval regression tests for high-risk actions;
smoke tests for provider, connector, or environment setup.

If the workflow produces a customer-facing or public artifact, fail closed when required evidence is missing.

Tests

Minimum coverage for a new or changed workflow:

template or draft loads through the schema;
required roles and profile bindings resolve;
all referenced tools exist and required allowlists are complete;
trigger input validation rejects malformed or incomplete input;
connector/account/scope failures are surfaced before side effects;
branch, retry, loop, join, and payload mappings execute as expected;
approval-gated nodes cannot run without the expected approval;
required artifacts are written and can be read from the run workspace;
verifier failures produce repair, blocked, or failed state instead of false success;
capability inventory and workflow listing expose the workflow as expected.

Examples:

Built-in workflow template and bridge coverage: tests/saved-workflows.test.ts
Workflow draft execution: tests/workflow-test-runs.test.ts
Workflow primitives: tests/primitive-tools.test.ts
Report orchestration and contract coverage: tests/report-orchestration.test.ts, tests/report-contracts.test.ts
Approval behavior: tests/approval-checkpoints.test.ts, tests/report-approval-gates.test.ts

Operator Docs

Update docs when a workflow changes what operators can run or approve.

Document:

who should use the workflow;
how it is triggered;
required inputs and connector setup;
tools, profiles, and policy classes used;
approval checkpoints and review evidence;
artifacts produced;
verifier or smoke expectations;
known unsupported modes.

For workflow families that assemble other workflows, describe parent/child run traceability and where operators inspect child-run status.

Capability Inventory

Workflow templates appear in the capability inventory. Before calling a workflow complete, verify that the inventory communicates:

id and kind;
owner/source and version;
state;
required inputs;
policy classes and approval expectations;
smoke status where applicable;
profile reachability;
related tools and skills where applicable.

This keeps workflow extension visible before it becomes a path that coordinators, automations, or headless clients can trigger.

Review Checklist

Before merging a workflow change:

Trigger and input contract are explicit.
Node graph is operator-level and executable.
Tool allowlists and connector scopes are specific.
Agent profiles have bounded tools, skills, and policy classes.
High-risk actions have approval gates and negative tests.
Outputs are structured and artifact-backed.
Verifier behavior cannot be bypassed by self-reported success.
Project workflow and saved workflow behavior stays compatible.
Documentation and capability inventory expectations are updated.