Agent Orchestration

Agent orchestration lets IntuitivePM coordinate AI-assisted work directly from your boards. A personal orchestrator can plan work, assign approved Virtual Colleague agents, monitor progress, and queue completed work for review.

The board remains the source of truth. Tasks, subtasks, status columns, comments, review decisions, and attached files show what is planned, what is running, what is waiting, and what has been accepted.

Core Concepts

How Work Moves

1. A task or subtask is moved to In Progress.
2. If the work already has an approved agent, IntuitivePM starts the scheduling step automatically.
3. The orchestrator chooses the best agent and runtime, or a user selects an approved agent manually.
4. The agent claims the work and starts.
5. The agent writes progress, questions, caveats, and completion evidence in task comments.
6. If the agent needs a decision, the work can wait on the orchestrator or on a user.
7. When the assigned work is complete, it moves to review.
8. The orchestrator or a human reviewer claims the review decision.
9. The reviewer accepts the work to Done or sends it back to In Progress with feedback.

Review is always required before agent-executed work is accepted as Done.

How IntuitivePM Chooses Agents

When automatic selection is used, IntuitivePM compares approved agents and online runtimes against the work requirements. It considers reviewed agent capability information, model family, tools, workspace scope, repository scope, risk limits, quality/cost/latency boundaries, runtime capacity, recent outcome-based reliability history, and any explicit agent or runtime choice made by a user or orchestrator.

If a candidate cannot be used, IntuitivePM records the reason, such as the runtime being offline, the agent being outside the approved scope, the task risk exceeding the agent limit, or the required specialty not matching the agent profile. If structured profiles are not available yet, IntuitivePM falls back to the older runtime tag matching behavior.

Open the task Orchestration section and use Preview to see the selection explanation before live dispatch. The preview shows the preferred candidate, score, reliability contribution, reason, matched signals, and rejected candidates so reviewers and orchestrators can understand why a route was chosen.

For audit, reporting, and reliability scoring, IntuitivePM records append-only outcome history for selections, lease outcomes, and review accept/reject decisions. These records include the selected agent/runtime, score breakdown, ranked candidates, caveat signal, timestamps, and relevant durations. Reliability uses this outcome history first and only falls back to recent lease rows when no relevant outcome history exists yet.

Review decisions also receive a structured review-quality assessment. IntuitivePM scores the decision against configured review templates and completion evidence, then stores the score, grade, criteria, caveat count, and summary with the review outcome. This helps admins distinguish clean accepted work from accepted work with weak evidence or rejected work that needs follow-up.

For automated orchestrator review, IntuitivePM uses a separate review lease. This prevents two orchestrators from reviewing the same task at the same time and keeps the review decision separate from the agent’s execution lease.

Company admins maintain each agent’s reviewed capability profile in System -> Integrations -> Agent Registry. The profile captures model routing, model family, quality, latency, cost, stability, execution modes, specialties, allowed scopes, tools, review strengths, risk limits, and autonomy limits.

Admins can use AI Assist in the capability profile section to create a reviewed draft. IntuitivePM asks one approved model to draft the profile, asks a second model to critique it when another approved model is available, and asks the first model to resolve the feedback. The draft shows confirmed, adjusted, needs-review, and low-confidence fields. It is not saved automatically; an admin must apply the draft and then save the profile.

External runtimes can also submit capability claims about themselves, such as available tools, model family, workspace scope, and runtime tags. These claims are not trusted automatically. A company admin reviews them in Agent Registry and decides whether to apply the proposed profile changes, apply runtime tags, approve without changing routing data, or reject the claim.

Orchestration Queue On The Board

Open a board and select Orchestration Queue in the board header to review dispatchable agent work for the current board scope.

The queue shows tasks and subtasks from the board’s projects, their execution state, waiting reason, assigned agent, assigned runtime, and last update time. Use Preview to run the same dry-run selection used in the task modal. Use Dispatch when the selected route is correct and the work should be offered to the agent runtime.

If the board is team-scoped, the queue is scoped to the projects on that team board. It does not show unrelated company work.

Task Instructions

Use the instruction fields in the task Orchestration section when the normal description is not specific enough for agent work:

• Execution agent instructions tell the agent exactly how to approach the work.
• Orchestrator/reviewer instructions tell the orchestrator or reviewer what to inspect and how strict to be.
• Completion evidence tells the agent what proof must be supplied before review.

Managed external runtimes receive these instructions with the task context. IntuitivePM also uses them as signals when deriving task requirements for automatic agent selection.

Subtasks

Subtasks are executable child tasks with their own IDs. The orchestrator may assign different subtasks to different agents when work can be done in parallel.

If one subtask depends on another, IntuitivePM shows the waiting state and the reason so team members understand why the work is not ready yet.

Each API-backed subtask can also have its own execution-agent instructions. Use this when the parent task gives the overall goal but each subtask needs specialized guidance.

Completion Evidence

Agents must leave a completion comment before work can be reviewed. The comment should clearly say whether the work finished with no issues or with specific caveats.

When documentation evidence is required, completion comments include:

• Code updated:
• Docs updated:
• Docs touched:
• Tests run:

The reviewer can return the task if the evidence is missing or incomplete.

For managed Claude Code execution agents, IntuitivePM expects the runtime to use the approved workspace configured by the company admin. Company admins should validate the runtime in smoke mode first. Smoke mode confirms assignment, comments, lease handling, progress, and Review handoff without making live workspace changes.

Live execution can create or edit files in the approved workspace, while bypass permission mode should remain disabled. If live execution is tested temporarily, return the runtime to smoke mode afterward unless the company has approved it for continuous live work.

Managed runtimes keep additional local run logs for support and audit review. Those logs stay on the runtime host; the official IntuitivePM record is still the task comment thread, progress events, lease history, and Review decision.

Asking Questions

Agents, orchestrators, and users communicate through task comments.

• Use @orchestrator when a task needs planning, sequencing, or review guidance.
• Use @user when a user decision is needed.
• Use @agent when you need to clarify something with the assigned agent.

When work is waiting for a decision, only that task or subtask is paused. Other independent work can continue.

Workflow runs that are waiting on a human approval also appear in the workflow’s Runs view. The approval queue shows the waiting step, related task, routing mode, due time when configured, and whether the approval is assigned to you. Select Open run to inspect the paused node and approve, reject, or request changes from the run monitor.

Only routed approvers can make the decision. A workflow step may route approval to the requester, workflow owner, specific users, a team, a project role, or a board-owner fallback. If you can see the run but are not one of the routed approvers, IntuitivePM shows the context but keeps the decision buttons disabled.

Approval queues also show overdue approvals and whether a waiting step is assigned to you. When requesting changes or rejecting a step, include feedback so the worker, reviewer, or human owner knows what needs to change.

Work Files

Open Work -> Files to manage your personal workspace. You can upload input documents, maintain templates, and download outputs created by agents.

Allowed uploads include common text files, JSON, PDFs, Microsoft Office files, OpenDocument files, and common image formats such as JPG, PNG, GIF, WebP, SVG, BMP, TIFF, AVIF, HEIC, and HEIF. Executable and script files are blocked. The maximum upload size is 100 MB per file.

Administrators can also configure Knowledge Sources for agents and workflows. Knowledge Sources can point to IntuitivePM files or folders, GitHub repositories, URL-backed pages, connected Jira issues when Jira Cloud is enabled, selected Confluence spaces or pages when Confluence is enabled, and selected SharePoint document libraries or folders when SharePoint is enabled.

When Jira Cloud is connected, Jira issues can be linked directly to tasks or added as authenticated Knowledge Sources. Agents receive scoped Jira issue context, sanitized descriptions and comments, citations, and freshness warnings through IntuitivePM. They do not receive Jira credentials or call Jira directly. If an agent proposes a Jira update, a human reviews and applies the proposal from IntuitivePM.

When Confluence is connected, admins enable specific spaces. Agents can read selected pages from those enabled spaces through IntuitivePM. The agent receives sanitized Markdown, citations, content hashes, and attachment metadata, not Atlassian credentials. Attachment byte downloads are not enabled in the current rollout.

When SharePoint is connected, admins enable specific sites, document libraries, and folders. Agents can read supported text, PDF, DOCX, and XLSX files from those enabled scopes through IntuitivePM. The agent receives extracted text, citations, and content hashes, not Microsoft Graph credentials.

Admins can preview Knowledge Source resolution and inspect recent source-read audit events from the Knowledge Sources diagnostics area. Jira write proposal audit events are available from the Jira connection details. Confluence connection details include page preview, operational history, and source-read audit filters for connection, space, and page. SharePoint connection details include file preview, operational history, and source-read audit filters for connection, library, folder, and file item.

By default, your agents can:

• Read your workspace files.
• Create new files.
• Update only files they created last.

Agents cannot delete files or freely edit everything unless you explicitly enable full access for that agent.

Managed Internal And External Agents

IntuitivePM supports two runtime models:

• Managed internal agents are operated by IntuitivePM and are best for standard workflow assistance that can use IntuitivePM context, approved AI providers, connected Knowledge Sources, and Work Files.
• External agent runtimes are operated by your company and are best when work must run in your environment, use private tools, access local workspaces, or execute custom automation.

See Managed Internal Agents for the internal model and Connect External Agent Runtimes for customer-operated runtimes.

External Agents

External agents must be approved by a company administrator. This protects your company from unauthorized workspaces, models, and execution environments.

An external runtime can represent either an execution agent or an orchestrator agent. Both connect through the same approved runtime channel, so an orchestrator can inspect work, schedule agents, review completed output, and send stop or reload requests from the same operational environment as the execution agents.

Connected runtimes receive wake-up and control events from IntuitivePM, while IntuitivePM remains the source of truth for task status, comments, assignments, review decisions, and files. If a runtime is temporarily disconnected, your company setup may allow it to discover assigned work again when it reconnects.

For managed executor runtimes, stop and reload requests are enforced while work is running. Reload interrupts the current run so the agent can reacquire changed task instructions. Stop interrupts the current run and blocks stale work from being submitted to Review.

Admins can find each runtime ID in System -> Integrations -> Agent Registry by opening the agent and reviewing the runtime list. The runtime ID is needed when connecting scripts, containers, workflows, or developer tools to the approved agent identity.

While a connected runtime is actively reporting progress, users viewing the board see a live activity badge on the task card. The tooltip shows who is working, which runtime is connected, the current phase, and the latest short progress message. This helps humans monitor active work without opening every task.

Managed external runtimes refresh that progress during long executor runs. If the runtime stops reporting, the badge expires automatically; the durable task comments, lease state, and Review history remain the audit record.

When an agent submits work for Review, an orchestrator accepts work to Done, or a reviewer sends work back to In Progress, IntuitivePM persists the status change first and then broadcasts the card movement to connected board viewers. The runtime WebSocket is only a wake-up/control channel; runtimes do not move cards by sending arbitrary WebSocket messages.

The dashboard can also include an Agent Activity widget. It summarizes online runtimes, active leases, work waiting on users or orchestrators, the agent review queue, recent completions, caveats, failures, accepted/rejected reviews, average review-quality score, top active agents, and recent progress. Open the widget to see expanded charts for current state, recent outcomes, review quality, active agents, and live progress. Use it to monitor the operating state and review quality of agent work across your accessible projects.

When automated review pauses or escalates, reviewers can use the task modal’s Human review override in the Orchestration section. Accepting moves the task to Done. Returning requires feedback and moves the task back to In Progress for the assigned agent or next selected agent.

Admins control:

• Which external agent identities are available.
• Which runtimes can execute work.
• Whether external execution is enabled for the company.
• Which AI providers and models are approved.

Regular members can choose only from approved options.

Slack And Teams

Slack and Teams can mirror orchestration comments, but IntuitivePM remains the control plane. Status changes, assignment changes, review decisions, and orchestration state changes must happen inside IntuitivePM.

Admin Setup Checklist

Before using orchestration in a company workspace:

1. Confirm orchestration is enabled for the company.
2. Create or verify each member’s orchestrator Virtual Colleague.
3. Configure orchestrator rule sets.
4. Approve any external agents and runtimes.
5. Configure documentation areas if agents must update docs.
6. Connect Jira if agents need existing Jira issues as task context.
7. Connect Confluence if agents need approved spaces or pages as workflow context.
8. Connect SharePoint if agents need approved document libraries or folders as workflow context.
9. Decide whether Work Files and Slack/Teams mirroring should be enabled.

How-To Guides

Use these guides when you are ready to configure and operate the workflow:

• Agent Orchestration Architecture & Security gives network, firewall, component, data-flow, and security review guidance for Enterprise deployments.
• Set Up Agent Orchestration explains the company setup, Virtual Colleague roles, external agent approval, Work Files permissions, and smoke testing.
• Managed Internal Agents explains IntuitivePM-managed agents, lifecycle states, security boundaries, and troubleshooting.
• Assign Work To Agents explains how to prepare tasks, use subtasks, communicate through comments, and review agent output.
• Jira Integration explains how to connect Jira Cloud, link issues to tasks, use Jira as workflow context, and approve write-back proposals.
• Confluence Integration explains how to connect Confluence, enable spaces, preview pages, and use Confluence pages as workflow context.
• SharePoint Integration explains how to connect SharePoint, enable libraries and folders, and use SharePoint files as workflow context.
• Connect External Agent Runtimes explains how administrators approve external runtimes and validate connectivity.
• External Runtime Packages explains how customers obtain, verify, install, update, and roll back runtime packages.
• Run Codex And Claude Code As External Agents gives a working Ubuntu runtime bridge example.

Related Guides

• Virtual Colleagues Overview
• Creating Virtual Colleagues
• AI Provider & Model Selection