Repository navigation
Discussion: Workflow Runtime Integration #818
Description
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.
Activity
SaulMoro commentedon Sep 24, 2026
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 --> TAn 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
GitProviderdoes 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:
Each user picks the runtime and tools in their local config:
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:
allow) should set the permission ceiling, not the workflow, and prompts should not expand shell commands.pullshould check that referenced agents and sub-workflows reach the same scope.modelstring that is written verbatim into every tool's file, so animplementerwithmodel: opusbreaks 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.traceparentpassed 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 commentedon Sep 25, 2026
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 commentedon Sep 25, 2026
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 <-.-> OThe 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.
result.jsonper step, checked against the step'soutput. This is what makesif: 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.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 contributewhat the run taught,import --from-mrlearns from the merged PR, and run metrics pointrecall maintenanceat 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'smaxConcurrency. 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 optionalagentis a TeamAI agent, the same definitionpulldeploys as a subagent. The executor runs the step as that agent, with the tool's own flag where there is one.Safety. Each step declares what it
requires, such as an isolated copy of the repo or network access. The member's localallowsets 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.
prompt,commandandworkflowsteps, an optionalagent,needs,if, boundedloopon workflows and steps,break,outputs,withand typedinputs,timeout,approveandinteractive, and fan-out over a step's output (for_each).local, the skill, and Paseo.localstarts 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.
modelbreaks 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.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-plannertemplate: plan, parallel implement on isolated branches, then a merge step. It maps to these steps with afor_eachand 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: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.
mastracodeheadless behindlocal, or the Mastra server. It readsAGENTS.md, skills and.mcp.jsonfrom the repo.SKILL.mdand subagents.dcode -nlocally, or Agent Protocol remotely. It readsAGENTS.md,.agents/skillsand.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, awaitingoutcome for people in the loop, andchangesthat report a pushed branch and an optional PR URL.A factory can also use the team's assets without a workflow: running
teamai pullwhen its sandbox session starts, on platforms with a hook for it such as Foreman'sfactoryOnSession, 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:
prompt, acommandor aworkflow.agentis optional. With it, the executor runs the step as that TeamAI agent (native flag where the tool has one, such asclaude --agentoropencode run --agent, and injected instructions where it doesn't, such ascodex exec). Without it, the member's default tool runs the prompt.workflow:takes a file name or inlinesteps. An inline sub-workflow sees the enclosingitemandinputs, and a file one gets only itswith.commandsteps 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 acommandstep's output.promptis inline text andprompt_filea path.needslists dependencies.requireslists what the step needs (isolated,network,env).withfeeds a prompt's template variables or a sub-workflow's typedinputs.run-stepcarries 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 writesresult.jsonforcommandsteps from the exit code and, ifoutputis set, from JSON on stdout.requires: { isolated: true }on aworkflowstep makes the whole sub-workflow share one copy, and an isolated step keeps its copy across loop iterations.for_eachitems run in parallel. A failed item doesn't cancel its siblings. The step exposesbranches(the ones that succeeded) andresults[]with{item, outcome, outputs, branch}.ifreads itsoutcome. A skipped step doesn't block them. An emptyfor_eachsucceeds with no results.timeoutworks per step and per workflow and ends the step as atimeoutfailure.loopon a workflow repeats its whole body, one round per pass. On a step,back_tojumps back, and withoutwhileit goes back when the step ran.whileis 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 withloop exhausted.fixthat loops back toreview).repotakes a local path or{ url, base }.run-stepmay return a handle, and the engine then callsstatusorattachand stores the executor's run and trace IDs in run events.changesreports a branch pushed to a remote, plus an optionalpr_url.approve: <message>is a gate before the step, and a no skips it,interactive: truehas the person work in the tool, and the agent can ask mid-step. The contract carries this as the outcomewaiting { kind: approve | answer | interactive, message }and the oprespond. The executor declareshuman: [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, andinteractivefails before the run starts. A waiting run persists and resumes later.auto_approve, and a required one fails withapproval required.approve: { message: ..., required: true }can't be auto-approved.localexecutor takes the member's config as flags or env, since there is no~/.teamaiin CI or a cloud runner.Open, to settle in the spec (several come from a gap analysis of Sandcastle):
sandcastle/issue-{id})..envinto an isolated copy. Dependency caches stay with the executor.outputaccepting full JSON Schema, keeping the shorthand.retry: { max, on: [timeout, output_invalid] }and a closed set of error kinds.result.jsoncarryingchanges: { branch, base, commits }, and never dropping uncommitted work silently.promptsteps without isolation: warn, don't reject, since read-only reviewers are fine.sandbox: required) and workflow-level defaults forrequires.evaluates:when the graph can't attribute a review, for example one review over several implementers.GitProvider, instead ofgh.github:push, split between the host and the sandbox, instead of values sent over the pipe.native,injectedornone), and what happens when they can't honor itstools.SaulMoro commentedon Sep 25, 2026
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-plannertemplate. 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:
I can check any change against Orca.
cc @jeff-r2026, since you suggested reviewing it together.
SaulMoro commentedon Sep 25, 2026
I've added two things to the proposal above:
repo, async steps, awaitingoutcome for people in the loop, and a pushed branch with an optional PR URL.approvegate andinteractivesteps, 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 commentedon Sep 25, 2026
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.
SaulMoro commentedon Sep 26, 2026
The model tier idea from this thread now has a proposal in #830: agents say
model: strong, the team maps it per tool, members can override locally, and it works without a gateway. Feedback welcome there.SaulMoro commentedon Sep 28, 2026
#875 proposes team-declared secrets:
env/secrets.yamldeclares keys with no value, each member keeps the value on their machine, and resolution is team value > machine value > environment. A CLI gets the value underteamai env exec -- <cmd>. A few points for the workflow spec, so the two fit:requires.envrefers to declared keys. No second list in the workflow. A key inenv/secrets.yamlresolves as a secret, a key inenv.yamlas a variable, andpullwarns about one that's neither.env execwarns and runs, since it can't know whetherghneeds the token or usesgh auth login. A step that lists the key has said it needs it, so the run fails before it starts, naming the key andteamai env set KEY. A step that can live with the CLI's own login doesn't list it.commandor agent step sees the scope's variables and the secrets in its ownrequires.env, not every secret the scope declares. A shared workflow runs team-authored code on every member's machine.~/.teamai, so the job's secrets are the environment, which Proposal: declare team secrets in the repo, keep their values on each machine, for MCP servers and CLIs #875 already falls back to.outputs,result.jsonand run events, which feed retros,teamai contributeand recall. TeamAI knows the values, so it masks them before storing anything.commandsteps must not reuse a declared key.localexecutor starts the tool with the step's env, instead of relying on the SessionStart line from Proposal: declare team secrets in the repo, keep their values on each machine, for MCP servers and CLIs #875 reaching a headless run.run-stepnever carries secret values. The named-capabilities point stays open, andenv/secrets.yaml(key, description, url) is what a remote executor maps to its own secret store.feat(env): declare team secrets in env/secrets.yaml and show their st…
feat(env): team-declared secrets with member-local values (#875) (#880)
SaulMoro commentedon Oct 11, 2026
I compared the proposal with three systems close to it: T3 Code task graphs, Warp Factories, and Mastra Factory. The boundary holds. In none of them does the system itself enforce loop limits and gates.
They are ahead in other places. I'd move these points from open to decided:
schemaVersion,name,description, and an optionalalias.pullandpushvalidate a workflow as one unit and report errors by file and line. An invalid workflow keeps its last valid version.defaults:. A step'srequires.envmerges with them. Every other key replaces them.cancel <step>stops a step and its dependents.retry <step>runs it again, with the steps that were skipped because of it.fixthat loops back continues the implementer's session when the executor can resume it.workspace: new,continue, orread-onlyreplacesrequires.isolated. A step with severalneedsstarts from the first one's branch and merges the others.deliver: propens the PR throughGitProvider. The PR targets the closest earlier step with its own PR, or the run's base.cleanup. When it fails, the engine does not, so the workspace stays for inspection.auto_startandauto_approveare separate settings in the member's config, and both are off by default. With both off, no run starts and no tokens are spent without the member.1. The header
The skill uses
descriptionto pick a workflow.v1alpha1becomesv1together with the plugin contract.4. Step states
stateDiagram-v2 stopped: stopped (failed, timeout, or cancelled) [*] --> pending pending --> waiting: gate, start time, or usage limit pending --> running: dependencies succeeded pending --> skipped: a dependency stopped, or if is false waiting --> running: approved, time reached, or limit reset waiting --> skipped: approval refused running --> waiting: usage limit hit running --> delivering: agent turn done running --> stopped delivering --> stopped delivering --> succeeded: committed, pushed, PR opened stopped --> pending: retry succeeded --> [*] note right of waiting approve, answer, interactive, scheduled, or quota end notedeliveringis the commit, the push, and the PR. If a step cannot deliver, it fails, so TeamAI never drops uncommitted work without saying so.9 and 10. Workspaces and PRs
flowchart LR base[(main)]:::git review["review<br/>workspace: read-only<br/>no branch, no commit"]:::ro auth["auth<br/>workspace: new<br/>from main"]:::new billing["billing<br/>workspace: new<br/>from main"]:::new merge["merge<br/>workspace: new<br/>starts from auth, merges billing<br/>deliver: pr"]:::new docs["docs<br/>workspace: continue<br/>same branch as merge"]:::cont followup["follow-up<br/>workspace: new<br/>deliver: pr"]:::new review --> auth & billing auth & billing --> merge merge --> docs merge --> followup merge -. "PR into main" .-> base followup -. "PR into merge's branch (stack)" .-> merge classDef ro fill:#5b6770,stroke:#3f4850,color:#fff; classDef new fill:#2f6f8f,stroke:#1f4f6b,color:#fff; classDef cont fill:#6a4f8f,stroke:#513b6d,color:#fff; classDef git fill:#b5762f,stroke:#865520,color:#fff;The current draft does not say which branch
mergestarts from.7 and 12. Reports in skill mode
sequenceDiagram participant A as Agent in the session participant T as TeamAI engine participant P as Person A->>T: next T-->>A: step implement, attempt a7, revision 12 A->>T: report a7, revision 12, success T-->>A: accepted, revision 13 A->>T: report a7, revision 12, success (sent again) T-->>A: rejected, stale revision A->>T: next T-->>A: step share waits for approval A->>T: approve T-->>A: rejected, only a person approves T->>P: ask through the executor's channel for people P-->>T: yes T-->>A: step share, attempt a8, revision 14In skill mode, the agent that runs the steps also reports to TeamAI. It can send a report twice, and it could approve its own gate. The executor's
humancapability says how a person answers: the tool's permission prompt, a TTY, or an app. This changes the design note that lets the skill session take approvals. The session can show the question, but the answer must come through a channel the agent does not control.Measurement
Measurement is where a tool-neutral format can do something none of these systems can. Warp has scorers and improvement PRs, but only for runs inside Warp.
flowchart LR repo[(team repo<br/>agents, prompts, skills)]:::git subgraph executors [any executor] paseo[Paseo]:::exec orca[Orca]:::exec local[local or skill]:::exec end events[(run events<br/>step, agent, tool, model,<br/>outcome, loops, scorer label)]:::teamai scorers["scorers/<name>.md<br/>labels, passing score,<br/>sampling rate"]:::teamai proposal["improvement PR<br/>links the failing runs"]:::teamai person{{person reviews}}:::human repo -- "teamai pull" --> executors executors --> events scorers --> events events -- "repeated failures,<br/>exhausted fix loops" --> proposal proposal --> person person -- merge --> repo classDef exec fill:#2f6f8f,stroke:#1f4f6b,color:#fff; classDef teamai fill:#2f8f4f,stroke:#1f6b39,color:#fff; classDef human fill:#a33a3a,stroke:#7a2a2a,color:#fff; classDef git fill:#b5762f,stroke:#865520,color:#fff;scorers/<name>.mdfile in the team repo names the agents it judges, its labels and scores, a passing score, and a sampling rate. Its label goes into the run events.Run events have the same form for every executor. So one scorer compares the same agent across Paseo, Orca, and local runs.
T3 Code is an executor candidate. It gives agents tools to start threads in worktrees and to manage task graphs. My first comment said T3 Code had no public API, and that is no longer true.
Later, not v1.
dagcapability runs a part of the workflow with no loops or conditions as one unit. Then multi-machine placement and PR stacks come from T3 or Orca.localexecutor starts runs, andaliasnames a routing label such asteamai:ship.waiting { kind: event }for a merged PR, green CI, or a finished deploy. That takes a workflow from issue to production instead of stopping at an open PR.requires.platform, for examplemacos/aarch64for an iOS build.SaulMoro commentedon Oct 11, 2026
Revised proposal for discussion: TeamAI workflows
This revises my previous proposal and, like it, is open for discussion. It keeps its goal, its format and its boundary, and adds what came out of comparing it with T3 Code, Warp Factories and Mastra Factory.
The main change I propose is the direction of the contract. TeamAI is a CLI with git as its backend and has no server, so it should not hold a run open and push steps to executors. A run is now a state machine in files, and drivers pull steps from it. That one change removes the need for a long-lived process, turns skill mode into an ordinary driver, and makes runs durable by default.
What changed from the previous proposal:
run-stepover stdioteamai workflow nextandreportrun-stepcarries the agent's instructions and modelteamai pull. The lease names the agent.waitingcovers quota and mid-step questionsrequires: { isolated: true }with implicit nesting rulesworkspace: new,continueorread-only, with an explicit join rulegh pr createin acommandstepdeliver: prthroughGitProvider/teamai workflow <name>ifandapproveonlyends, andchoosewith options. A parent branches on how a sub-workflow ended.What needs agreement first is the boundary and the driver contract. The syntax, the examples and the design notes are there to test them, and are open.
Goal
A team workflow runs for any member whose setup meets its requirements, whatever driver or tool they use. TeamAI stays the team layer above these tools, so a team does not have to standardize on one of them.
Boundary
TeamAI owns what a workflow means. The driver owns how a step runs.
flowchart LR subgraph repo [team repo] wf[workflows/*.yaml]:::git assets[agents, prompts,<br/>skills, scorers]:::git end subgraph cli [TeamAI CLI, no process of its own] engine[engine<br/>state machine: control flow,<br/>outputs, leases, revisions]:::teamai state[(run state<br/>local files)]:::teamai engine <--> state end subgraph drivers [drivers: the loop lives here] local[local<br/>headless, CI]:::driver skill[skill<br/>agent in the session]:::driver paseo[Paseo adapter]:::driver end tools[Claude Code, Codex,<br/>OpenCode, and others]:::driver reports[(teamai-reports branch<br/>run records, stats,<br/>published snapshots)]:::git person{{person}}:::human assets -- "teamai pull" --> drivers wf --> engine drivers -- "next / report<br/>JSON" --> engine drivers --> tools engine -- "run record, pushed<br/>at start and end" --> reports state -. "publish / resume,<br/>on demand" .-> reports person -- "respond<br/>TTY or dashboard" --> engine person -- "driver's own channel" --> drivers classDef git fill:#b5762f,stroke:#865520,color:#fff; classDef teamai fill:#2f8f4f,stroke:#1f6b39,color:#fff; classDef driver fill:#2f6f8f,stroke:#1f4f6b,color:#fff; classDef human fill:#a33a3a,stroke:#7a2a2a,color:#fff;if, loops,breakandfor_each. The driver never sees the graph.reportanswerscleanup: truereportis rejected.result.jsonagainst the step'soutputneeds, and pushapprovegates and start times, and whether a channel may answer a gateteamai initandteamai pullin its environmentrequires, the member'sallowand the driver's capabilities before a step startsallow: the tool's sandbox, a container, or a remote machinereportnextsayswaitThe 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. Paseo's Hub bundles are legacy and have no loops. Orca's task DAG has no conditions. T3 Code's task graphs have no conditions, loops or typed outputs. Warp keeps its loops and gates in the foreman's prompt. A TeamAI workflow should mean the same thing whichever driver runs it.
How a run moves
A driver asks for work, runs it, and reports. Every driver uses the same commands, whether it runs in TeamAI's process (
local, skill) or outside it (the Paseo adapter, a custom driver in any language).sequenceDiagram participant D as Driver (local) participant T as TeamAI engine participant A as Agent tool participant P as Person D->>T: next (capabilities) T-->>D: lease implement, attempt a7, revision 12 D->>A: run agent implementer in a new worktree A-->>D: done, branch pushed D->>T: report a7, revision 12, success, changes T-->>D: accepted, revision 13 D->>T: next T-->>D: gate, share waits for approval P->>T: respond yes, from a TTY or the dashboard D->>T: next T-->>D: lease share, attempt a8, revision 14 D->>A: run the step A-->>D: usage limit reached D->>T: report a8, released T-->>D: accepted, share is pending again Note over D: the driver stops asking until its limit resetsnextreturns one of four answers. The output uses one envelope,{ "data": ... }or{ "error": { "code", "message" } }, so a driver in any language can parse it.reportoutcomes aresuccess,failed,timeout,cancelledandreleased.releasedhands the step back without using a retry, for example when the driver runs out of usage. Any driver can take the step again.The engine never calls a driver. Everything it needs to tell one comes back as the answer to
nextorreport, includingcleanupand the PR URL.All commands sit under one
teamai workflowgroup, for two kinds of caller:next,reportstart,resume,respond,retry,cancel,publishstartcreates a run and hands it to the driver in the member's config.resumecontinues a run on this machine, from the local state or from a published snapshot. The CLI help for each command is the contract a driver reads, andskill-data/core/references/commands.mdis generated from it.Step states
stateDiagram-v2 stopped: stopped (failed, timeout, or cancelled) [*] --> pending pending --> waiting: approve or choose gate, or start time pending --> leased: a driver takes it pending --> skipped: a dependency stopped, every dependency skipped, or if is false waiting --> pending: answered, or time reached waiting --> skipped: approval refused leased --> pending: released by the driver leased --> delivering: agent turn done leased --> stopped delivering --> succeeded: branch pushed, PR opened delivering --> stopped stopped --> pending: retry succeeded --> [*] note right of leased held by one driver until report, retry, resume, or the step's timeout end noteA run is
draft,running,succeeded,failedorcancelled.deliveringis the driver's report of what it pushed, plus the PR when TeamAI opens it. If a step cannot deliver, it fails, so uncommitted work is never dropped without saying so.Leases make runs durable
A lease belongs to one driver, identified by its kind, machine and workspace. It does not expire unless the step has a
timeout. When the same driver callsnextagain, it gets its own open leases first. So a member can stop a run in the middle and continue tomorrow:Any driver can take any step whose
requiresit can meet. A step withworkspace: continuestays with the driver that holds the copy. When more than one driver works on a run, every step pushes its branch, so the next step can start from it.Workflow format
A workflow is a YAML file in the team repo, under
workflows/, next toagents/,prompts/andskills/. It names no driver and no tool.Keys in one place:
schemaVersion,name,descriptionnamematches the file name.alias,invocableinputs,outputs,endsprompt,prompt_file,command,workflowworkflowtakes a file name or inlinesteps.agentneeds,if,break,loop,for_each,endoutput,with,envinputs, and inputs for acommandstep as environment variablesworkspace,delivernew,continueorread-only, andprrequires,defaultsnetwork,env,platform), and workflow-level values for any keysetup,budget,max_turnsapprove,choose,interactive,timeoutsessioncontinueresumes the step's own previous pass.{ from: <step> }resumes the session another step reported.Branches and endings
A workflow is a graph.
ifalready picks a path, and three keys name where the paths lead:ends:lists the ways a workflow can finish, each with the outcome the run takes, such asends: { shipped: succeeded, dropped: succeeded, stuck: failed }.end: <name>on a step finishes the workflow with that name when the step succeeds. Pending steps are skipped and open leases are cancelled. A step whose only job is to finish has noprompt,commandorworkflow.choose: { message, options, default }waits for a person to pick one option. Later steps readsteps.<id>.choice, andsteps.<id>.notewhen the person adds a comment.approveis the yes-or-no case ofchoose.A parent reads how a sub-workflow finished from
steps.<id>.end, and the values it declares inoutputsfromsteps.<id>.outputs. A run that settles without reaching an end finishes as before:succeededif no step stopped, otherwisefailed.nextreturns achooseas a gate with itsoptions, and a person answers withteamai workflow respond r1 plan.decide revise --note "keep the old flag", or through any channel the driver declares. In an unattended run,choosetakes itsdefaultwhen the member's config setsauto_approve. Without a default or withoutauto_approve, it fails the run like a required gate.Every run ends. Loops are bounded by
max_iterations, and a step goes back only throughloop.back_to. There is nogoto,switchorneeds_any.ifon each branch covers a switch. A step thatneedsevery branch joins them, because a step is skipped only when every step it needs was skipped.pullrejects a workflow in which a step cannot be reached, or in whichendsis declared and no end can be reached. The worked example near the end puts these keys together.Workspaces and PRs
flowchart LR base[(main)]:::git review["review<br/>workspace: read-only<br/>no branch, no commit"]:::ro auth["auth<br/>workspace: new<br/>from main"]:::new billing["billing<br/>workspace: new<br/>from main"]:::new merge["merge<br/>workspace: new<br/>starts from auth, merges billing<br/>deliver: pr"]:::new docs["docs<br/>workspace: continue<br/>same branch as merge"]:::cont followup["follow-up<br/>workspace: new<br/>deliver: pr"]:::new review --> auth & billing auth & billing --> merge merge --> docs merge --> followup merge -. "PR into main" .-> base followup -. "PR into merge's branch (stack)" .-> merge classDef ro fill:#5b6770,stroke:#3f4850,color:#fff; classDef new fill:#2f6f8f,stroke:#1f4f6b,color:#fff; classDef cont fill:#6a4f8f,stroke:#513b6d,color:#fff; classDef git fill:#b5762f,stroke:#865520,color:#fff;newstarts a copy from the firstneedsstep's branch, or from the enclosing copy, or from the run's base. The driver merges the otherneedsbranches into it, and the step's agent resolves conflicts.continueworks in the enclosing copy, or the firstneedsstep's copy, on the same driver. Steps inside a sub-workflow continue its copy by default.read-onlygets no branch and makes no commit. Parallel reviewers use it.deliver: prtargets the closest earlier step along firstneedsthat opens its own PR, or the run's base. So a run can produce a stack. TeamAI never merges.reportanswerscleanup: truewhen the step succeeded and no later step continues its copy. After a failure it answersfalse, so the workspace stays for inspection.People in the loop
approve: <message>before a stepteamai workflow respond, the dashboard, or the AI tool's own question tool, such as Claude Code'sAskUserQuestion. A no skips the step. Achooseanswer goes tosteps.<id>.choice.interactive: true, the person works in the toolhumantakes the step.releasedorfailed.releasedand stops asking until its reset.approve: { message: ..., required: true }cannot be approved automatically. In an unattended run, an optional gate skips its step unless the member's config setsauto_approve, and a required gate fails the run withapproval required.The driver declares its channels for people, and whether an agent carries the answer. A TTY, the dashboard and a driver's own UI have no agent in the path. A question tool in the session does: the person answers, but the agent passes the answer on, so a mistaken agent could skip the question. Such a channel can answer optional gates only. A gate with
required: trueneeds a channel with no agent in the path, and the run record notes the channel of every answer. None of this protects against a hostile agent: on the same machine, an agent with a shell can fake a TTY. Approval through the git provider, by a member with rights, is listed under Later for teams that need a guarantee.Safety
requires. The member'sallowsets the ceiling, and the driver declares what it can enforce. TeamAI checks the three before a step starts and names what fails. Choosing a driver is a trust decision, because TeamAI trusts what the driver declares.requires.envlists keys declared inenv.yamlor inenv/secrets.yaml(Proposal: declare team secrets in the repo, keep their values on each machine, for MCP servers and CLIs #875). A lease carries key names only. A local driver gets the values the way Proposal: declare team secrets in the repo, keep their values on each machine, for MCP servers and CLIs #875 defines. A remote driver maps the declared keys to its own secret store. A step sees only the keys it lists, and a missing key fails the run before it starts, naming the key andteamai env set KEY. Unattended runs take secrets from the environment, never as flags.reportruns where the values are, so it masks them before anything reaches the run state, a published snapshot, or a run record. Inputs passed as environment variables tocommandsteps cannot reuse a declared key.commandsteps get inputs as environment variables, never interpolated into the shell string. Prompts never expand shell commands, so data such as the backlog comes from acommandstep's output.triage-issuebelow does both.setup: { command, requires }runs when the driver creates anewworkspace, before the agent, with its own network and keys. Sonetwork: falseon the agent still lets the tests install dependencies, and a registry token never reaches the agent. Its keys are not cached into the workspace or a snapshot. A sub-workflow uses its parent'ssetupunless it declares one.deliverfails withprotected path, naming the files, when the diff touches CI workflows or agent configuration (.github/workflows/,.claude/,.mcp.json,AGENTS.md,CLAUDE.mdand the other tools' equivalents). A step that starts from a branch an agent wrote runs the tool with that configuration from the run's base. Otherwise a hook one agent committed would run in a later step that holds a token.budget: { tokens: 20M }on a workflow counts the tokens everyreportcarries, sub-workflows included. Once it is spent,nexthands out no more leases and the run fails withbudget exceeded.max_turnson a step goes in the lease, and the driver passes it to the tool when the tool has such a flag.auto_startandauto_approve, both off by default. With both off, no run starts and no tokens are spent without the member. In v1 every run is started by a person or a CI job, soauto_startmatters once triggers exist.Durability and sharing across machines
The run state lives in local files, under the member's TeamAI data directory, written under a cross-process lock. The state goes to git only when the member asks. The run record, which holds no content, is pushed on its own, as "Run records, stats and scorers" describes.
sequenceDiagram participant A as Machine A (local driver) participant R as teamai-reports participant B as Machine B (skill driver) A->>A: run ready-issues, round 3 of 10 A->>R: teamai workflow publish r1 (snapshot, owner A) Note over A: laptop closed B->>R: teamai workflow resume r1 R-->>B: snapshot, owner set to B B->>B: lease a7 in flight goes back to pending as a8 A->>R: teamai workflow publish r1, next day R-->>A: rejected, not fast-forward, B owns the runpublishwrites a snapshot of the current state to theteamai-reportsbranch, underruns/<id>/state.yaml: metadata and masked outputs, no prompts. It reuses the side-branch code that stats already use.resumetakes ownership. Git rejects the old owner's next push, so two machines never move the same run without a server.pendingwith a new attempt. A branch the old driver pushed is noted in the run record for manual recovery and is never merged automatically.Invocable workflows
invocable: trueputs a workflow in the agent's context at session start, the same way TeamAI already adds team rules and the secrets hint through itsSessionStarthook. The agent runs it through the existingteamaiskill, so nothing new is deployed to the tools.The list carries one line per workflow,
nameanddescription, because some tools cap the context a hook adds (Codex keeps only the start and end past 2,500 tokens). The agent starts a workflow when a task matches its description, or the member types/teamai workflow <name>. How to drive a run lives inteamai skill get workflowand in the CLI help, so the injected lines never go stale. A workflow is not invocable by default, because a shared workflow runs team-authored steps on the member's machine.Run records, stats and scorers
Every run leaves a record on the
teamai-reportsbranch, next tostats/. TeamAI pushes it twice, through the side-branch code stats already use: when the run starts, and when it ends, at a named end or not. Because of the first push, a run whose machine dies, such as a CI runner killed by its job timeout, still shows up as started and never ended. Nothing is pushed in between, and a sub-workflow is part of its parent's run. If a push fails, the record stays local, the answer tostartor to the lastreportsaysrecord: pending, and the nextteamai pullsends it.The record holds the step, agent, tool, model, outcome, end, iterations, duration, tokens (input, cached input and output), scorer label, team revision, PR URL, and the CI job URL when there is one. It holds no prompts, outputs or diffs, the same rule
UserStatsfollows today. Each member'sstats/<user>.yamlgets aworkflowssection, summarized from their own records and updated by the end push.teamai dashboardandteamai digestshow it.scorers/<name>.mdfile names the agents it judges, its labels and scores, a passing score, a sampling rate and a model.modeltakes what an agent'smodeltakes: an alias such asstrongorfast, resolved per tool frommodels/aliases.yaml(Proposal: model aliases so one agent works in every tool #830), or a model name. When a sampled step succeeds, the engine adds aread-onlystep that runs the scorer, leased to the same driver so the content stays where it is. Only its label goes into the run record. A scorer needs no mechanism of its own.recall maintenanceandteamai contributea concrete input.Run records have the same form for every driver. So one scorer compares the same agent across Paseo, CI and skill runs, which no single vendor's factory can do.
Drivers and the member's config
nextchecks the driver's environment before it hands out a lease. It fails when the step's agent is not deployed there ("agent implementer is not deployed here. Run teamai pull."). If the driver's last pulled revision differs from the run's, the step runs and the run record notes the revision it used.Each member picks the driver and the tools in their local config:
The built-in drivers call the engine module in process. An external driver calls the same two operations through
teamai workflow next|report --json. A conformance suite runs the same scenarios through both paths, so they cannot drift apart.toolsis read by thelocaldriver, which starts the tool for each agent. It holds at mostmax_parallelleases at once, so a widefor_eachqueues instead of starting every agent.Proposed v1
prompt,prompt_file,command,workflow,agent,needs,if,break, boundedloop,for_each,output,with,env,inputs,outputs,ends,end,defaults,setup,budget,max_turns,workspace,deliver,requires,timeout,approve,choose,interactive,session,invocable.teamai workflowcommands. The driver contract is experimental until a second external driver has used it.local, skill and Paseo.localruns headless, so it also runs in a GitHub Actions job. Jeff suggested validating the design with Paseo first. I would start withlocalas the smallest end-to-end path, but the order is the maintainers' call.workflowssection in stats, a workflows page in the dashboard, andpublishandresume.Later, as separate threads
localdriver starts runs, andaliasnames a routing label such asteamai:ship.waiting { kind: event }for a merged PR, green CI, or a finished deploy. This takes a workflow from issue to production.requires.platform, for examplemacos/aarch64for an iOS build.Acceptance check
Alice runs a workflow through Paseo. Bob runs the same files through the skill in T3 Code. A CI job runs them with the
localdriver. Bob publishes his run, and Dana resumes it on another machine. None of them configures anyone else's driver, nobody edits the shared workflow, and all runs leave records in the same form, so they can be compared.A second test is Sandcastle's
parallel-plannertemplate: plan, implement in parallel on separate branches, then merge. Theready-issuesexample above is that template plus planning again each round, a review loop, a retro and one PR at the end.Cloud software factories
Hosted factories fit as drivers without changes to the pull model. Mastra Factory, Vercel eve and LangChain Open SWE each orchestrate in their own board, prompt or code, and none has a workflow format shared across tools. A remote sandbox runs
teamai pull, callsnext, works, and callsreportwith a pushed branch and an optional PR URL.Worked example: a small software factory
Seven workflows that each work alone and compose into a factory.
ship-issuetakes one issue from triage to a PR,nightly-backlogruns it over the backlog, andfix-cianswers a failed CI run. Three are invocable, so an agent can start them from a chat. The others open PRs or need a planned task, so a person or a CI job starts them. A person reviews every PR and TeamAI never merges, so this is not a dark factory.triage-issue(aliastriage)agent-readyorneeds-humanready,needs-humanplan-change(aliasplan)planned,droppedreview-and-fiximplement-taskdone,stuckship-issueshipped,skipped,not-ready,dropped,stucknightly-backlog(aliasnightly)fix-cifixed,skipped,stuckflowchart LR ci([CI job, 02:00<br/>local driver]):::ci person{{person}}:::human nightly[nightly-backlog]:::wf ship[ship-issue]:::wf impl[implement-task<br/>one per task]:::wf failed([failed CI run]):::ci fixci[fix-ci]:::wf subgraph inv [invocable: the agent can start them] triage[triage-issue]:::inv plan[plan-change]:::inv review[review-and-fix]:::inv end ci -- "teamai workflow start" --> nightly nightly -- "for_each issue" --> ship ship --> triage & plan & review ship -- "for_each task" --> impl failed -- "teamai workflow start" --> fixci person -. "teamai workflow start" .-> ship person -. "/teamai workflow" .-> inv classDef inv fill:#2f8f4f,stroke:#1f6b39,color:#fff; classDef wf fill:#2f6f8f,stroke:#1f4f6b,color:#fff; classDef ci fill:#b5762f,stroke:#865520,color:#fff; classDef human fill:#a33a3a,stroke:#7a2a2a,color:#fff;The team repo holds the files, and
teamai pulldeploys the agents to every member and runner:triage-issue. Only a member with write access can make an issueagent-ready. That decision comes from the GitHub API, and the agent reads the issue only after it.A maintainer vouches for an outside author's issue by adding the
agent-readylabel. An edit after the label voids it, so the author cannot swap the text the maintainer read. A member with the triage role can add labels too, but has no write access, so that label does not count. The permission calls need a token with push access, and a call that fails counts as no access. Iftrustitself fails,escalatestill runs, because itsifreadstrust. The triager still gets no network, no token and no shell, and itsoutputallows only a kind, a boolean and a summary.plan-change. A person picksbuild,reviseordrop. A revision goes back to the same planner session with the person's note.implement-task. Not invocable: it takes one task from a plan, so it runs insideship-issue. The implementer runs the unit tests as part of its work, so the workflow gates on the end-to-end tests. When they keep failing, a person can take over the implementer's session.ship-issue. It composes the four workflows above. The change gets one PR into the run's base. When the plan says the docs need work, a second PR stacks on the first. The retro reads what the reviewer sent back. Oncesharecontributes it and members runteamai pull, every implementer starts with it, so the next review has less to send back.flowchart LR triage[triage<br/>triage-issue]:::step plan[plan<br/>plan-change]:::step subgraph change [change: workspace new, deliver: pr] build[build<br/>implement-task per task]:::step merge[merge]:::step verify[verify<br/>e2e tests]:::step review[review<br/>review-and-fix]:::step build --> merge --> verify --> review end docs[docs<br/>stacked PR]:::step retro[retro]:::step share{{share<br/>approve}}:::human notready((not-ready)):::stop dropped((dropped)):::stop stuck((stuck)):::bad shipped((shipped)):::ok triage -- "end == ready" --> plan triage -- "end != ready" --> notready plan -- "end == dropped" --> dropped plan -- "end == planned" --> change change -- failed --> stuck change -- "if outputs.docs" --> docs change --> retro --> share docs & share --> shipped classDef step fill:#2f6f8f,stroke:#1f4f6b,color:#fff; classDef human fill:#a33a3a,stroke:#7a2a2a,color:#fff; classDef ok fill:#2f8f4f,stroke:#1f6b39,color:#fff; classDef stop fill:#5b6770,stroke:#3f4850,color:#fff; classDef bad fill:#b5762f,stroke:#865520,color:#fff;nightly-backlog. A CI job starts it on weeknights with thelocaldriver. Blocked issues wait for the issues that block them.fix-ci. A failed CI run on one of the factory's PRs starts it. The fix arrives as a small PR into the failing branch, so a person sees it apart from the change.The
guardis what keeps CI and the factory from looping: a failing fix PR targets a branch, notmain, so it never starts anotherfix-ci.An agent and a scorer. The agent is the format TeamAI already deploys.
review-and-fixalready judges the implementer on every run, and the run record keeps its verdicts and fix passes. The scorer judges the reviewer, which nothing else checks.scorers/review-quality.md:Two places, two drivers. Alice works attended in Claude Code. The factory runs in GitHub Actions. The runner has no
~/.teamai, so it runs a non-interactiveteamai initand passes the member settings as flags.GitHub Actions is the easiest place to start a factory. Runners are free for public repos, issues are the tickets, labels hand work on, cron runs the nightly, and the job log shows what went wrong. A few things to know:
initasks nothing in CI, because GitHub setsCI. It registers the runner as the token's user,acme-factory, and it ends with ateamai pull.GITHUB_TOKENreaches only this repo, not the team repo. Without theworkflowscope, that token cannot push a change to.github/workflows/, even if protected paths missed one. Unlike theGITHUB_TOKEN's labels, that token's labels start workflows, so theifignores that account's events. Otherwise a labeltriage-issueadds would start a second job for an issuenightly-backlogis already shipping.ship-issueat once, which starts with triage, so an issue from an author without write access stops atnot-ready.nightly-backlogtakes what is left withneeds-triage, such as issues opened before the factory existed.max_iterationsbounds them. A chain of label, job, label has no limit, and no single run sees all of it.teamai pull. They are pushed when each run starts and ends, as "Run records, stats and scorers" describes.One night, and the morning after.
The ends, outcomes and scorer labels in this trace land in run records. The learnings land in the team repo, where a person reviews them. After a few weeks of
noisylabels on the reviewer, the improvement PR proposes a change toprompts/review.mdand links the runs.Design notes: proposed details and open points, for whoever drafts the spec
Proposed:
prompt, acommandor aworkflow.agentis optional. With it, the driver runs the step as that TeamAI agent, with the tool's native flag where there is one (claude --agent,opencode run --agent) and injected instructions where there is none (codex exec).item,inputsandsteps. A file sub-workflow gets only itswith.result.jsonforcommandsteps from the exit code and, ifoutputis set, from JSON on stdout.for_eachitems run in parallel. A failed item does not cancel its siblings. The step exposesbranches(the ones that succeeded) andresults[]with{item, outcome, outputs, branch}. An emptyfor_eachsucceeds with no results.for_each: { items, max_parallel }caps how many items run at once. An item whoseafterlists other items'idwaits until they succeed, and itsnewworkspace starts from their branches, merged as forneeds. If one of them fails, the item is skipped. A cycle fails the step withplan has a cycle, naming it.ifreads that step. A step is skipped when every step itneedswas skipped, so a step that needs several branches joins them. Afor_eachstep fails when any of its items fails.timeoutworks per step and per workflow and ends the step as atimeoutfailure.if,break,while,for_eachandoutputsreadinputs,item, andsteps.<id>withoutcome,outputs,passes,end,choice,note,branchesandresults. They use==,!=,&&,||and!. In a{{ }}template, a step that has not run yet renders empty. Awithvalue that is a single{{ }}keeps its type, sotask: "{{item}}"passes an object.workspacekey continues the enclosing copy. Outside any copy, it runsread-only.loopon a workflow repeats its whole body, one round per pass. On a step,back_tojumps back, and withoutwhileit goes back when the step ran.whileis optional and evaluated when the round or step settles.break: <expr>ends the enclosing loop, or the workflow, as success. Dependents wait until the loop settles and see its last output.steps.<id>.passeslists the outputs of every pass. An exhausted loop fails withloop exhausted.reportreturns the session handle, and the engine keeps it per step and attempt. A step starts a fresh session by default, on every pass, so a reviewer never carries what it saw before.session: continueresumes the step's own previous pass, andsession: { from: <step> }resumes the session another step reported. Either one binds the lease to the driver, machine and tool that hold the session, asworkspace: continuedoes. A driver that cannot resume starts fresh with the context in the prompt.pullrejects afromthat names a step outside the scope, or afor_eachstep outside its own item.changesreports{ branch, base, commits, pr_url? }. Withoutpr_url,reportopens the PR withGitProviderin the driver's environment. A remote driver without provider credentials must returnpr_urlitself, orreportfails and names what is missing.fixthat loops back toreview.Open:
sandcastle/issue-{id}.outputaccepting full JSON Schema, keeping the shorthand.retry: { max, on: [timeout, output_invalid] }.sandbox: required).evaluates:when the graph cannot attribute a review, such as one review over several implementers.github:push, instead of keys the sandbox resolves itself.native,injectedornone), and what happens when it cannot honor the agent'stools.Feedback from the maintainers and from anyone who builds or runs agent workflows would help, whatever tool or runtime you use:
nextandreport?I can check any change against the skill driver in T3 Code, and against Orca as an external driver.
jeff-r2026 commentedon Oct 12, 2026
Thanks for the thorough proposal. I agree with the goal, the boundary, and the pull-based driver contract. Please go ahead with your proposed v1, starting with the local driver. The open points don't need to block you — please use your proposed defaults, and we can refine them as the work lands.
Separately, I also like the approach used by Claude Projects. We can explore whether TeamAI should adopt some of those ideas later, but let's keep that as a separate discussion.
9 remaining items
hsuchifeng commentedon Oct 13, 2026
The accepted v1 is now split into sub-issues. Each one is blocked by the issues it needs, and triggers, event waits, git-provider approval, concurrent multi-machine leases,
requires.platform, and OpenTelemetry stay out of this set.Implementation tracking
#1076 is the first slice and can start now. After it lands, #1077, #1078, and #1083 can proceed in parallel.
SaulMoro commentedon Oct 13, 2026
Thanks for splitting this up so quickly. The order reads well, and starting from the command-only slice was a good call. I went through each ticket against the proposal and left a few small suggestions where they apply:
for_eachTwo small things here:
workflows/<ns>/) aren't in any ticket. It would be nice to have them from the start, like skills and agents, but a follow-up works too.SaulMoro commentedon Oct 14, 2026
I went through the remaining tickets against what TeamAI already has, and left suggestions where changing something later costs more than doing it now:
feat(workflow): run prompt and agent steps with the local driver #1120 (for [feat] Run prompt and agent steps with the local driver #1077): one way to start the CLIs, on top ofDone in feat(workflow): run prompt and agent steps with the local driver #1120 (39a7dc1): it starts the CLIs with the sameai-client.ts, which also fixes Windows. Token counts from the tool instead of from the agent. No silent fallback to an older workflow version when an older CLI meets a key it does not know.resolveCliPathand cross-spawn asai-client.ts, reads model, session and tokens from each tool's own output, and leaves a workflow with an unknown key unrunnable with "Update teamai".workflows/<ns>/,prompts/<ns>/andscorers/<ns>/.tool,modelandmodelAlias, uses a longer run id, and sums scorer labels with asource.scorer.md, and scorers and prompt steps without an agent take amodel.Follow-ups, none blocking: on-demand scoring, improvement PRs from scorer failures and exhausted fix loops, benchmarks across alias mappings, built-in scorers, pass-rate trends and cost per run, a model alias for TeamAI's own judges, a doctor warning when a tool drops an agent's
tools, scoring subagents in normal sessions, hooks that skip the background pull inside a step (the adapter already setsTEAMAI_WORKFLOW_RESULT, which can mark it), and amodeloverride next toagent.SaulMoro commentedon Oct 16, 2026
Updates from #1137, which is now revised. Nothing under this issue waits on it.
agent:selects a definition, and stays optional. What a step ran as is more than that: how the tool applied the definition, the tool and its version, model and effort, the team revision delivered to the checkout, and the project commit. Run records, labels and stats will useagentfor that composition, recorded per pass by [feat] Record the agent each workflow step ran as #1176. That is also where "the run record notes the revision it used" (Drivers and the member's config) lands.modelto prompt steps and todefaults, an alias or a model name, resolved per tool by the driver. A prompt step runs on the first of: its ownmodel, the model its definition sets for the tool,defaults.model, the tool's default. A step'smodelreplaces the definition's model and effort.defaults.modelonly fills a gap, as Warp'sagentDefaultsdoes, and never replaces a model a definition sets for its role. Decided point 3 still holds, since a step'smodelreplacesdefaults.model. The difference is that the definition's model sits between the two, sodefaults.modelis the one key that does not act as if written on every step.teamai initno longer pulls ([bug] init without --agent in a non-interactive shell reports agents synced but delivers nothing into the project #1065, fixed by fix(init): do not pull team resources during init (#1065) #1069), so the runner has no workflows. Add- run: teamai pullafter theinitline, and drop "it ends with ateamai pull" from the note under it.