Discussion: Workflow Runtime Integration

[jeff-r2026]

We plan to add workflow support to TeamAI.

Today, TeamAI can distribute shared capabilities such as skills, rules, MCP configurations, environment settings, and team context.

The next step is to also distribute how these capabilities work together as a repeatable workflow.

For example:

Plan
↓
Implement
↓
Test
↓
Review
↓
Fix

Our current idea is to keep TeamAI focused on defining and distributing the workflow, while using an external runtime to execute and coordinate the agents.

TeamAI Workflow
↓
Workflow Runtime
↓
Claude Code / Codex / OpenCode / ...

For the first version, we are considering integrating Paseo as the workflow runtime.

Paseo already provides many of the execution capabilities we need, such as multi-agent coordination, agent sessions, worktrees, runtime state, and remote execution.

TeamAI would remain responsible for the team-level layer:

• workflow distribution and versioning
• skills, rules, MCP and context
• execution history and improvement data

Before we start the integration, we’d like to hear from the community:

• Have you used Paseo for similar workflows?
• Are there other orchestration/runtime projects you think would be a better fit for TeamAI?
• Is there anything we should pay special attention to when integrating an external workflow runtime?

Our current preference is to start with Paseo, but we’d like to hear other ideas before moving forward.

[SaulMoro]

Thanks for opening this. Our team would use workflows, and we already work from different tools (I use Orca, a teammate uses T3 Code). So before the Paseo integration starts, I'd like to argue for one thing: make the runtime an adapter, with Paseo as the first adapter rather than part of the workflow model.

These tools change every month. If the workflow format uses Paseo concepts, switching later means rewriting every team's workflows and losing their history. TeamAI already solves this for MCP: servers are declared once and rendered into each tool's native format. Workflows could follow the same pattern with runtimes.

A split that fits what these tools can do today:

flowchart LR
  subgraph TeamAI
    F[workflow format] --> C[control flow + run history]
  end
  C --> A{{runtime adapter}}
  C --> L[local mode<br/>coordinator skill]
  A --> P[Paseo]
  A --> O[Orca / herdr / Sandcastle]
  P --> T[Claude Code / Codex / OpenCode]
  O --> T
  L --> T

Loading

An adapter only runs one step at a time: prepare a worktree, start an agent, wait, read the result, stop. Neither Paseo's Hub workflows nor Orca's task DAG can express a bounded review/fix loop, so TeamAI has to own the control flow anyway. Local mode needs no runtime and covers tools without a public API, such as T3 Code.

Shipping v1 with two executors, local and Paseo, would prove the format is neutral. The runtime code could sit behind one interface, the way GitProvider does today. A public plugin API can wait until a second adapter exists.

A rough sketch, borrowing GitHub Actions syntax. The team repo holds the workflows, with no runtime or tool in them:

# workflows/linear-ticket.yaml
inputs: { ticket: string }
steps:
  - id: implement
    agent: implementer             # agent | command | workflow
    prompt: prompts/implement.md   # Markdown with {{inputs.ticket}}
  - id: test
    command: npm test
    needs: [implement]             # steps without a dependency between them can run in parallel
  - id: review
    workflow: review-and-fix       # a step can be another workflow
    if: steps.test.outcome == 'success'

# workflows/review-and-fix.yaml
steps:
  - id: review
    agent: reviewer
    output: { verdict: pass | fix }   # written to a result file
  - id: fix
    agent: implementer
    if: steps.review.outputs.verdict == 'fix'
    loop: { back_to: review, max_iterations: 3 }

Each user picks the runtime and tools in their local config:

workflows:
  runtime: orca          # local | paseo | orca | ...
  tools: { default: claude, implementer: codex }
  allow: { isolation: worktree, network: false }

I can run these through Orca with Codex, and my teammate can run the same files locally with Claude inside T3 Code.

Things worth watching:

• A shared workflow runs code on every member's machine. The user's local config (allow) should set the permission ceiling, not the workflow, and prompts should not expand shell commands.
• The same check should cover the runtime: a workflow that needs worktrees should fail before it starts on a runtime that can't create them.
• pull should check that referenced agents and sub-workflows reach the same scope.
• TeamAI agents carry a raw model string that is written verbatim into every tool's file, so an implementer with model: opus breaks as soon as someone binds it to Codex. Agents could declare a tier (model: strong | fast) that each user's local config resolves per tool.
• For history, a TeamAI-owned run record aligned with the OpenTelemetry GenAI conventions, plus a traceparent passed to each step, would link agent traces to the run. If that sounds useful, an OTLP export for all TeamAI telemetry could be a separate proposal.

Happy to validate the format against Orca once there's a draft.

[jeff-r2026]

Thanks for opening this. Our team would use workflows, and we already work from different tools (I use Orca, a teammate uses T3 Code). So before the Paseo integration starts, I'd like to argue for one thing: make the runtime an adapter, with Paseo as the first adapter rather than part of the workflow model.

These tools change every month. If the workflow format uses Paseo concepts, switching later means rewriting every team's workflows and losing their history. TeamAI already solves this for MCP: servers are declared once and rendered into each tool's native format. Workflows could follow the same pattern with runtimes.

A split that fits what these tools can do today:

An adapter only runs one step at a time: prepare a worktree, start an agent, wait, read the result, stop. Neither Paseo's Hub workflows nor Orca's task DAG can express a bounded review/fix loop, so TeamAI has to own the control flow anyway. Local mode needs no runtime and covers tools without a public API, such as T3 Code.

Shipping v1 with two executors, local and Paseo, would prove the format is neutral. The runtime code could sit behind one interface, the way GitProvider does today. A public plugin API can wait until a second adapter exists.

A rough sketch, borrowing GitHub Actions syntax. The team repo holds the workflows, with no runtime or tool in them:

workflows/linear-ticket.yaml

inputs: { ticket: string }
steps:

• id: implement
  agent: implementer # agent | command | workflow
  prompt: prompts/implement.md # Markdown with {{inputs.ticket}}
• id: test
  command: npm test
  needs: [implement] # steps without a dependency between them can run in parallel
• id: review
  workflow: review-and-fix # a step can be another workflow
  if: steps.test.outcome == 'success'

workflows/review-and-fix.yaml

steps:

• id: review
  agent: reviewer
  output: { verdict: pass | fix } # written to a result file
• id: fix
  agent: implementer
  if: steps.review.outputs.verdict == 'fix'
  loop: { back_to: review, max_iterations: 3 }
  Each user picks the runtime and tools in their local config:

workflows:
runtime: orca # local | paseo | orca | ...
tools: { default: claude, implementer: codex }
allow: { isolation: worktree, network: false }
I can run these through Orca with Codex, and my teammate can run the same files locally with Claude inside T3 Code.

Things worth watching:

• A shared workflow runs code on every member's machine. The user's local config (allow) should set the permission ceiling, not the workflow, and prompts should not expand shell commands.
• The same check should cover the runtime: a workflow that needs worktrees should fail before it starts on a runtime that can't create them.
• pull should check that referenced agents and sub-workflows reach the same scope.
• TeamAI agents carry a raw model string that is written verbatim into every tool's file, so an implementer with model: opus breaks as soon as someone binds it to Codex. Agents could declare a tier (model: strong | fast) that each user's local config resolves per tool.
• For history, a TeamAI-owned run record aligned with the OpenTelemetry GenAI conventions, plus a traceparent passed to each step, would link agent traces to the run. If that sounds useful, an OTLP export for all TeamAI telemetry could be a separate proposal.

Happy to validate the format against Orca once there's a draft.

Thanks for the thoughtful proposal. I agree that TeamAI’s workflow definition should stay independent of Paseo, with Paseo as the first runtime adapter.

We don’t have a design draft yet. Would you be interested in writing an initial proposal based on your ideas here? In particular, it would help to cover the workflow model, the boundary between TeamAI and the runtime adapter, and what you think belongs in v1. We can review it together and use Orca to check whether the design stays runtime-independent.

No need to settle every detail upfront—a draft would give the community something concrete to discuss.

[SaulMoro]

Yes, happy to write it. Before a full draft, here is the shape I'd build it on, so we can agree on it first.

Goal. A team workflow runs for any member whose setup meets its requirements, whatever executor or tool they use. TeamAI stays the team layer above these tools, so a team doesn't have to standardize on one of them.

What needs agreement now is the boundary: TeamAI owns the format, the engine and run events, and executors run one step behind one contract. The syntax and the design notes are there to test that, and are open.

Boundary. TeamAI owns what a workflow means. The executor owns how a step runs.

flowchart TB
  subgraph TeamAI
    F[workflow format] --> E[engine<br/>DAG, if, bounded loops, concurrency]
    E --> H[run events and history]
  end
  E -- run-step --> X{{plugin contract<br/>JSON over stdio}}
  X -- result.json --> E
  subgraph Executors[executor plugins]
    L[local<br/>headless, unattended]
    S[skill<br/>agent in session]
    P[Paseo]
    O[Orca / custom]
  end
  X <--> L
  X <--> S
  X <--> P
  X <-.-> O

Loading

The engine is a small state machine. Sessions, worktrees, agent lifecycle and remote execution stay in the executor. The MCP analogy from my first comment holds for distribution but not for execution. Every tool has a native MCP config to render into, and no runtime has a native equivalent of this format today. Paseo's Hub bundles are now legacy and have no loops, and Orca's task DAG has no conditions. Even if a runtime adds them later, a TeamAI workflow should mean the same thing whichever executor runs it.

Contracts TeamAI owns.

• The workflow format.
• A result.json per step, checked against the step's output. This is what makes if: steps.review.outputs.verdict == 'fix' mean the same everywhere. An isolated step also returns its changes as a git branch, whatever the executor used for isolation.
• Run events, so history is comparable across executors.

Because runs share one model, TeamAI can learn across Paseo, Orca and local runs instead of per tool. A review's verdict shows how each agent does with each tool and model, a final step can teamai contribute what the run taught, import --from-mr learns from the merged PR, and run metrics point recall maintenance at the prompt that needs the most fix loops.

Plugins. Every executor uses one contract: an external teamai-executor-<name> process that speaks JSON over stdio (capabilities, run-step, cancel, cleanup). Any language works, so Paseo or Orca could ship their own. In v1, each call runs one step, and TeamAI runs several in parallel up to the plugin's maxConcurrency. In skill mode, the agent in the session asks TeamAI for the next step and reports the result, so loop counts stay in TeamAI and not in the model. That needs a minimal CLI for next and report. A step's optional agent is a TeamAI agent, the same definition pull deploys as a subagent. The executor runs the step as that agent, with the tool's own flag where there is one.

→ {"op":"run-step","run":"r1","step":"review","agent":{"name":"reviewer","instructions":"...","model":"..."},"prompt":"...","repo":"...","requires":{"isolated":true},"allow":{"network":false}}
← {"outcome":"success","outputs":{"verdict":"fix"}}

Safety. Each step declares what it requires, such as an isolated copy of the repo or network access. The member's local allow sets the limits, and the executor decides how to enforce them: the tool's own sandbox, a container, or a remote machine. TeamAI checks both before the run starts and names what fails. Orca, for example, launches agents with their permission-bypass flags by default.

v1.

• Format with prompt, command and workflow steps, an optional agent, needs, if, bounded loop on workflows and steps, break, outputs, with and typed inputs, timeout, approve and interactive, and fan-out over a step's output (for_each).
• The engine and an experimental plugin contract. It becomes stable once a second plugin, Orca or custom, has used it.
• Built-in executors: local, the skill, and Paseo. local starts the tools headless, so it also runs unattended, for example in a GitHub Actions job, with the member's config passed as flags or env.

Later, as separate threads.

• A pluggable engine, as a possible evolution. Once an executor can run the whole format natively, it could take a full workflow if it passes a conformance suite and emits the same run events.
• Model aliases. An agent's raw model breaks when someone binds the agent to another tool. Team-defined aliases resolved per tool would help agents even without workflows. Proposed in Proposal: model aliases so one agent works in every tool #830.
• OpenTelemetry support across all of TeamAI, as its own proposal, since it's the industry standard.
• Remote execution.

Acceptance check. Alice runs a workflow on Paseo, Bob runs the same files through the skill in T3 Code, and Charlie runs them on Orca. None of them needs to know or configure the others' executor, nobody edits the shared workflow, and all three runs record steps, loop iterations, outcomes and outputs in the same form, so they can be compared. I can test the Orca side. A second test case is Sandcastle's parallel-planner template: plan, parallel implement on isolated branches, then a merge step. It maps to these steps with a for_each and a normal step for the merge. A fuller version re-plans from the live backlog each round, as Sandcastle does, and adds a review/fix loop, a retro per round and one PR at the end. Illustrative syntax, not a proposed API:

# workflows/ready-issues.yaml
timeout: 4h
steps:
  - id: rounds
    requires: { isolated: true }             # every round builds up one branch
    workflow:                                # inline sub-workflow
      loop: { max_iterations: 10 }           # one round per pass
      steps:
        - id: backlog
          command: gh issue list --label ready --json number,title   # JSON on stdout
          requires: { network: true, env: [GH_TOKEN] }
        - id: plan
          needs: [backlog]
          prompt_file: prompts/plan.md       # picks the unblocked issues from {{steps.backlog.outputs}}
          output: { issues: [{ id: string, title: string }] }
          break: steps.plan.outputs.issues == []   # nothing left: end the loop, as success
        - id: build
          needs: [plan]
          for_each: steps.plan.outputs.issues      # in parallel, one per issue
          requires: { isolated: true }       # starts from the round's branch, returns its own
          workflow:
            steps:
              - id: implement
                agent: implementer           # a TeamAI agent, agents/implementer.yaml
                prompt_file: prompts/implement.md # {{item.title}}
                timeout: 30m
              - id: test
                needs: [implement]
                command: npm test            # outcome from the exit code
        - id: ship
          needs: [build]
          if: steps.build.branches != []     # no commits this round: skip, then re-plan
          workflow: integrate                # workflows/integrate.yaml
          with: { branches: "{{steps.build.branches}}", issues: "{{steps.plan.outputs.issues}}" }
        - id: retro
          needs: [ship]
          prompt_file: prompts/retro.md      # drafts this round's learning from the run events
          output: { title: string, learning: string }
        - id: share
          needs: [retro]
          approve: Share this round's learning with the team?   # no: the step is skipped
          prompt: |
            Share this learning with `teamai contribute`, titled "{{steps.retro.outputs.title}}":
            {{steps.retro.outputs.learning}}
          requires: { network: true }
  - id: pr
    needs: [rounds]                          # once, after every round
    command: gh pr create --fill
    requires: { network: true, env: [GH_TOKEN] }

# workflows/integrate.yaml
inputs: { branches: [string], issues: [{ id: string, title: string }] }
steps:
  - id: merge
    agent: merger
    prompt_file: prompts/merge.md            # merges {{inputs.branches}}, marks {{inputs.issues}} done
  - id: review
    needs: [merge]
    agent: reviewer
    prompt_file: prompts/review.md
    output: { verdict: pass | fix }
  - id: fix
    needs: [review]
    if: steps.review.outputs.verdict == 'fix'
    agent: implementer
    prompt_file: prompts/fix.md
    loop: { back_to: review, max_iterations: 3 }

Additional info: cloud software factories. Three hosted "software factories" fit the same boundary. Each one orchestrates in its own board, prompt or code, around a single agent loop, and none has a workflow format shared across tools.

	Orchestrates with	Fits as
Mastra Factory	Board stages with human gates, one Mastra Code agent	An executor: mastracode headless behind local, or the Mastra server. It reads AGENTS.md, skills and .mcp.json from the repo.
Vercel eve and its software factory template	The orchestrator's prompt, on the code-first Workflow SDK ("No YAML or state machines")	An executor: eve's MCP or HTTP API, or Vercel Sandbox running the member's own CLI. It reads SKILL.md and subagents.
LangChain Deep Agents and Open SWE	The model, or LangGraph graphs in code	An executor: dcode -n locally, or Agent Protocol remotely. It reads AGENTS.md, .agents/skills and .mcp.json.

All three need the same four things from the contract, now listed as decided in the design notes: a remote repo, async steps with a handle, a waiting outcome for people in the loop, and changes that report a pushed branch and an optional PR URL.

A factory can also use the team's assets without a workflow: running teamai pull when its sandbox session starts, on platforms with a hook for it such as Foreman's factoryOnSession, puts the team's skills, rules and MCP where these agents already look. I haven't tried it yet.

Design notes: decided details and open points, for whoever drafts the spec

Decided in this thread, not spelled out above:

• Steps. A step is a prompt, a command or a workflow. agent is optional. With it, the executor runs the step as that TeamAI agent (native flag where the tool has one, such as claude --agent or opencode run --agent, and injected instructions where it doesn't, such as codex exec). Without it, the member's default tool runs the prompt.
• Inline. workflow: takes a file name or inline steps. An inline sub-workflow sees the enclosing item and inputs, and a file one gets only its with.
• Commands. command steps get inputs as environment variables, never interpolated into the shell string. Prompts don't expand shell commands, so data such as the backlog comes from a command step's output.
• Keys. prompt is inline text and prompt_file a path. needs lists dependencies. requires lists what the step needs (isolated, network, env). with feeds a prompt's template variables or a sub-workflow's typed inputs.
• Contract. run-step carries the resolved agent (name, instructions, the model resolved for that tool, tools), so an executor works even where the agent file isn't deployed. TeamAI writes result.json for command steps from the exit code and, if output is set, from JSON on stdout.
• Isolation. The executor picks the mechanism. A nested isolated step starts from the enclosing copy's branch, and the round's merge brings its branch back. An isolated step returns a git branch. requires: { isolated: true } on a workflow step makes the whole sub-workflow share one copy, and an isolated step keeps its copy across loop iterations.
• Fan-out. for_each items run in parallel. A failed item doesn't cancel its siblings. The step exposes branches (the ones that succeeded) and results[] with {item, outcome, outputs, branch}.
• Failure. A failed step stops its dependents unless their if reads its outcome. A skipped step doesn't block them. An empty for_each succeeds with no results. timeout works per step and per workflow and ends the step as a timeout failure.
• Loops. loop on a workflow repeats its whole body, one round per pass. On a step, back_to jumps back, and without while it goes back when the step ran. while is optional and evaluated when the round or step settles. break: <expr> on a step ends the enclosing loop, or the workflow, as success and skips the rest of the round. So no issues ends the run, and a round without commits re-plans, as Sandcastle does. Dependents wait until the loop settles and see its last output. An exhausted loop fails with loop exhausted.
• Run events. Metadata, not content: step, agent, tool, model, outcome, verdict, iterations, duration, tokens. Who judged whom is read from the graph (a fix that loops back to review).
• Trust. TeamAI trusts what an executor declares it can enforce, so choosing an executor is a trust decision.
• Remote executors. repo takes a local path or { url, base }. run-step may return a handle, and the engine then calls status or attach and stores the executor's run and trace IDs in run events. changes reports a branch pushed to a remote, plus an optional pr_url.
• People in the loop. A step can need a person: approve: <message> is a gate before the step, and a no skips it, interactive: true has the person work in the tool, and the agent can ask mid-step. The contract carries this as the outcome waiting { kind: approve | answer | interactive, message } and the op respond. The executor declares human: [approve, answer, interactive] and picks the channel, such as the session, a TUI, an app or a board. When it can't, TeamAI's CLI or the skill session takes approvals and answers, and interactive fails before the run starts. A waiting run persists and resumes later.
• Gates. With a person present, a gate waits. In an unattended run, an optional gate skips its step unless the member's config sets auto_approve, and a required one fails with approval required. approve: { message: ..., required: true } can't be auto-approved.
• Unattended runs. The local executor takes the member's config as flags or env, since there is no ~/.teamai in CI or a cloud runner.

Open, to settle in the spec (several come from a gap analysis of Sandcastle):

• Starting an isolated copy from a named or existing branch, and author-named branches, needed so a re-planned item keeps its progress (Sandcastle uses sandcastle/issue-{id}).
• Copying untracked files such as .env into an isolated copy. Dependency caches stay with the executor.
• Resuming or forking an agent session, gated on an executor capability.
• output accepting full JSON Schema, keeping the shorthand.
• retry: { max, on: [timeout, output_invalid] } and a closed set of error kinds.
• result.json carrying changes: { branch, base, commits }, and never dropping uncommitted work silently.
• Parallel prompt steps without isolation: warn, don't reject, since read-only reviewers are fine.
• A member's minimum isolation (sandbox: required) and workflow-level defaults for requires.
• An explicit evaluates: when the graph can't attribute a review, for example one review over several implementers.
• A TeamAI-native PR step through GitProvider, instead of gh.
• Feeding step outcomes back into recall feedback.
• Team assets such as skills and MCP in a remote sandbox: the executor asks TeamAI for them, rendered for the step's tool, instead of relying on what the repo has committed.
• Secrets as named capabilities, such as github:push, split between the host and the sandbox, instead of values sent over the pipe.
• Executors declaring how they apply an agent (native, injected or none), and what happens when they can't honor its tools.
• An idempotency key per step attempt, since some remote APIs start work twice on a retry.

[SaulMoro]

The proposal in my reply above is ready for review. It covers the boundary between TeamAI and executors, the plugin contract, a v1 scope, and a full example based on Sandcastle's parallel-planner template. The design notes at the end list what's decided and what's still open.

Feedback from anyone who builds or runs agent workflows would help, whatever tool or runtime you use:

• Does the format cover a workflow you run today? If not, what's missing?
• Would the executor contract fit the runtime you use?
• Is there anything you'd cut from v1?

I can check any change against Orca.

cc @jeff-r2026, since you suggested reviewing it together.

[SaulMoro]

I've added two things to the proposal above:

• A section on cloud software factories: Mastra Factory, Vercel's eve, and LangChain's Deep Agents with Open SWE. All three fit as executors, and they point to the same four contract changes: a remote repo, async steps, a waiting outcome for people in the loop, and a pushed branch with an optional PR URL.
• People in the loop: an approve gate and interactive steps, where the executor picks how to reach the person. A gate asks before its step runs, and a no skips the step. In an unattended run, an optional gate skips its step unless the member's config auto-approves it.

If you use one of these platforms, I'd like to hear whether that matches what you see.

[jeff-r2026]

I've added two things to the proposal above:

• A section on cloud software factories: Mastra Factory, Vercel's eve, and LangChain's Deep Agents with Open SWE. All three fit as executors, and they point to the same four contract changes: a remote repo, async steps, a waiting outcome for people in the loop, and a pushed branch with an optional PR URL.
• People in the loop: an approve gate and interactive steps, where the executor picks how to reach the person. A gate asks before its step runs, and a no skips the step. In an unattended run, an optional gate skips its step unless the member's config auto-approves it.

If you use one of these platforms, I'd like to hear whether that matches what you see.

Thanks for the detailed proposal. I like the boundary you’ve drawn between TeamAI and the executors.

For the first implementation, would it make sense to validate the design with Paseo? Since it already handles agent sessions and worktrees, that may be the quickest way to test a small end-to-end workflow. We could add local and skill executors once we’ve learned from that integration.

I also agree with aligning run events with OpenTelemetry. I’d like to prioritize that for Team Improvement, and let workflow history build on it. Your model tier idea is useful too: different steps should be able to use models suited to their complexity.