| name | Task Lifecycle |
| description | Guide for (a) choosing the right execution mode — inline, interactive plans, ephemeral background agents, durable task runs, delegated subagents, team coordination — and (b) reading Prometheus's own internal state (agents, tasks, jobs, teams, recent work) via automation_dashboard and the granular tools, then rendering it with show_agent_work. Covers task_control, run_task_now, background_spawn, automation_dashboard, agent_list, schedule_job_*, and show_agent_work. |
| emoji | 📋 |
| version | 4.0.0 |
| triggers | create task, background task, multi-step, long running, check tasks, task status, stalled, resume task, complete task, task list, existing task, task control, declare plan, background_spawn, run_task_now, subagent, team, what's going on, what is going on, my priorities, operator snapshot, what have the agents done, what has everyone done, agent work, what are my subagents doing, status snapshot, what's running, morning snapshot, show me the work, internal status |
Task Lifecycle Playbook
Prometheus now has multiple execution modes plus a set of internal-state read tools. This skill covers both: pick the right execution mode for doing work, and use the right read tools for reporting on work.
If the user is asking about Prometheus's own state ("what's going on", "what are my priorities", "what have the agents done", "what's running") jump to Reading internal state below — that is the common, expensive-to-get-wrong path.
The execution modes
1) Direct inline execution
Use this when the work is quick and should happen in the current turn.
Examples:
- a few file reads
- a short edit
- one browser flow
- one shell command
- a quick lookup
If the task is straightforward and you can just do it now, do it now.
2) Interactive plan: declare_plan + complete_plan_step
Use only when the user explicitly wants a plan/checklist/steps first, or when policy requires a visible multi-step structure for a live external-action workflow.
Important current rule:
- do not default to
declare_plan for ordinary work
- do not use it for casual read-only or simple execution
- browser/desktop work is often handled directly unless a visible plan is explicitly needed
3) Ephemeral background agent: background_spawn
Use this for sidecar work that can run in parallel during the current turn.
Best for:
- repo scans
- memory/write-note side work
- focused research
- file audits
- independent analysis that does not block your next action
Key properties:
- starts immediately
- fully self-contained prompt required
- result auto-merges at turn end
- good for speeding up parallelizable work
Do not use it when the result is required before your immediate next step.
4) Durable background task: run_task_now
Use this for larger work that should run as its own persistent task and be verified before reporting back.
Best for:
- work that may take a while
- substantial research or production tasks
- jobs you want to survive restart / show in Tasks panel
- tasks where verification matters
Key properties:
- persisted task
- independent execution + verification pass
- better than
background_spawn for long or important jobs
5) Delegated single-agent work: spawn_subagent
Use for a focused specialist to do one defined job.
Best for:
- isolated research
- focused file editing
- running a specific narrow procedure repeatedly
- reusable specialist roles
Always check existing agents first with agent_list() before creating or dispatching new ones.
6) Multi-agent work: ask_team_coordinator
Use when the task truly benefits from multiple roles or parallel workstreams.
Best for:
- large research pipelines
- multi-role execution
- ongoing autonomous team efforts
- status checks on existing teams
Do not manually manage teams from main chat when the coordinator path is available.
Quick decision guide
| Situation | Best path |
|---|
| Quick work in this turn | Direct inline execution |
| Need sidecar parallel help right now | background_spawn |
| Long durable verified task | run_task_now |
| One focused specialist | spawn_subagent |
| Multi-agent coordination | ask_team_coordinator |
| User explicitly wants visible step plan | declare_plan |
Reading internal state (agents, tasks, jobs, teams, work done)
This is how Prometheus answers questions about itself — its agents, scheduled jobs, background tasks, teams, and what work has been produced. Get this right and one tool call replaces six.
Start here: automation_dashboard is the single snapshot
For almost every "what's going on / what are my priorities / what have the agents done / what's running" question, call automation_dashboard first. It returns ONE joined snapshot:
agents[] — the roster joined with each agent's scheduled jobs, background tasks, recent runs, and last produced outputteams[] — managed teams with members, their jobs, and recent tasksscheduledJobs[] — jobs with health + last resulttasks[] — background tasks with status/step/finalSummaryinternalWatches[], eventQueue[], and aggregate counts
Knobs:
depth: "full" — return untruncated output/results. Use this when the user wants to actually read the work product (drafts, approval packets, summaries). Default summary is compact.agent_id: "<id>" — focus the snapshot on a single agent (its jobs, tasks, recent runs, last output).include: ["agents","teams","outputs"] — narrow which sections to compute when you only need part of it.limit, include_done — as before.
Do NOT chain agent_list + task_control(list) + task_control(get) + schedule_job_detail + schedule_job_history to assemble this by hand. That was the old way and burns 6–10 calls. automation_dashboard already joins it. Use depth:"full" once instead of re-fetching detail tools to un-truncate output.
When to drop to the granular tools
Use these only for control/mutation or deep single-entity inspection that the snapshot doesn't cover:
| Tool | Use it for |
|---|
agent_list | Just need IDs/descriptions before spawning/dispatching (not for "what have they done"). |
agent_info | Full config of ONE agent (instructions, constraints, tool access). |
task_control(get) | Step/status metadata + control entry point for ONE task. For the produced output, use automation_dashboard(depth:"full") or schedule_job_detail. |
task_control(list/latest) | Quick task list when you explicitly don't need the agent/team join. Note: it also bundles scheduled jobs. |
task_control(resume/rerun/pause/cancel/delete) | Acting on a task. |
schedule_job_detail | Deep dive on ONE job: config, prompt, latest result, linked tasks, watches, events, schedule memory. |
schedule_job_history | Per-run history (status/duration/errors/output) for ONE job. |
schedule_job_log_search | Search run logs across jobs by text/status/date. |
schedule_job(list/create/update/...), schedule_job_patch/outputs/stuck_control | Managing/editing/unsticking jobs. |
team_manage(list) | Team config (members) when you don't need the joined rollup. |
background_status / background_progress | Polling an ephemeral background_spawn agent mid-turn (rarely needed — results auto-merge). |
Rule of thumb: snapshot for reporting, granular tools for acting.
Render it: show_agent_work
After you've gathered the snapshot, present it with the show_agent_work tool — a native operator card (greeting, summary rows, numbered priorities, team rows, active work) shown in chat. Use it when the user asks for a snapshot, priorities, "what's going on", a morning/startup status, or "what have the agents done".
Workflow:
automation_dashboard({ depth: "full" }) (or agent_id-scoped) to gather real state.- Synthesize the card from what you actually found — do not invent rows. Keep each list tight (2–6 items).
- Call
show_agent_work with the fields you have:
greeting / title — e.g. "Good morning." / "Subagent work snapshot"summaryRows[] — { icon, title, subtitle } (icons: calendar, users, clipboard, check, bolt, clock, flag, sparkles)priorities[] — { title, subtitle, status } (status: ready, running, blocked, idle, done)teams[] — { name, detail, status }activeWork[] — { title, status, progressLabel, href } for in-flight tasks/jobs
- Attach
taskId to any priority/activeWork row that maps to a real background task (you have the IDs from automation_dashboard). This makes the row clickable in the UI: it expands an inline drawer showing live status/step/summary with Resume / Pause / Restart / Delete buttons and a box to message that task's agent. Also pass jobId/agentId/proposalId when relevant. Without taskId the row is static text.
- Add a short text reply alongside the card for anything that doesn't fit the rows.
Don't call show_agent_work with fabricated data or for unrelated questions — it's for reporting real internal state. Plain text is fine when there's nothing structured to show.
Build / update status (NOT git status)
automation_dashboard returns a build field: { version, channel, updateAvailable, latestVersion, repo? }.
- When
build.updateAvailable is true, you may surface a row like "Update available → vX.Y.Z" in the snapshot. This is the only build/version signal end users should ever see.
build.repo (local git working-tree state — modified/untracked counts) exists only in dev builds and is for the developer's own use. Never put repo/git/uncommitted-files state into an operator snapshot or any user-facing card — it's dev noise and must not appear for end users.- Do not run
git status yourself to populate the snapshot. Use the build field. If you're not in a dev build there is nothing repo-related to report — show the update status instead.
background_spawn rules
Use background_spawn only when all three are true:
- the work is independent of your main tool sequence
- it can start immediately with a fully self-contained prompt
- you do not need the result before your next step
Good examples:
- while you inspect one skill, a background agent audits another
- while you edit a file, a background agent collects references
- while you complete the main request, a background agent writes a note or summary
Bad examples:
- you need the answer before deciding what file to edit
- the task depends on results from a tool call you have not made yet
- the work is the main blocking task itself
run_task_now rules
Use run_task_now when:
- work is substantial enough to outlive the current turn
- you want a proper task record
- you want verification before the result comes back
- the user asked for something that may take a while but should be completed autonomously
Prefer run_task_now over background_spawn when reliability and persistence matter more than same-turn merge speed.
task_control rules
task_control is for inspecting and managing durable tasks.
Common actions:
list — see taskslatest — get newest taskget — inspect one task deeplyresume — continue paused/stalled workrerun — run a task againpause — pause a running taskcancel — stop a taskdelete — remove task record
Dedup rule
Before creating a new durable background task, check for duplicates:
task_control({ action: "list", ... })
Only do this when you are actually about to create a task, not on every turn.
If an equivalent task already exists:
- resume it if paused/stalled
- rerun it if failed or stale
- avoid duplicate task creation
Status interpretation
Common statuses include:
queuedrunningpausedstalledneeds_assistanceawaiting_user_inputfailedcompletewaiting_subagent
Practical handling
running → usually leave it alone unless user askspaused / stalled → inspect with get, then resume if fixableneeds_assistance / awaiting_user_input → gather blocker and respond clearlyfailed → inspect root cause, then rerun or create a corrected new task
declare_plan versus task systems
Do not confuse plan UI with background task execution.
declare_plan
- lives in the current conversation
- meant for visible phase tracking
- advanced with
complete_plan_step
Background agents / tasks
- run separately
- do not use
complete_plan_step
- may use their own isolated plan mechanisms internally
- should be prompted self-contained
Important current behavior:
- unless explicitly asked otherwise, default to action rather than declaring a plan
- do not create a plan just because a task has multiple tool calls
Choosing between background_spawn and run_task_now
| Question | If yes | If no |
|---|
| Can it finish as same-turn side work? | background_spawn | consider run_task_now |
| Must it persist and survive restart? | run_task_now | background_spawn may be enough |
| Do you need verification before reporting success? | run_task_now | background_spawn may be enough |
| Is it parallel side work to your main flow? | background_spawn | maybe direct inline or run_task_now |
Choosing between spawn_subagent and team coordination
| Situation | Best path |
|---|
| One specialist, one focused job | spawn_subagent |
| Multiple roles or parallel streams | ask_team_coordinator |
| Need ongoing managed team behavior | ask_team_coordinator |
Common mistakes to avoid
- Using a background task when direct inline execution is faster
- Using
background_spawn for work that blocks the next decision
- Creating durable duplicate tasks without checking
task_control(list) first
- Treating
declare_plan as mandatory for every multi-step task
- Spawning a subagent when the work is actually multi-agent and should go to the team coordinator
- Asking a team to do what one direct tool call could do immediately
- Hand-assembling internal state with
agent_list + task_control + schedule_job_* instead of one automation_dashboard call
- Re-fetching detail tools to un-truncate output instead of passing
depth:"full" to automation_dashboard
- Calling
show_agent_work with invented rows, or using it for questions that aren't about Prometheus's own state
Bottom line
Choose the lightest execution mode that safely fits the job:
- direct execution first
background_spawn for parallel same-turn side workrun_task_now for durable verified background jobsspawn_subagent for one specialistask_team_coordinator for real multi-agent coordinationdeclare_plan only when a visible plan is actually needed
And to report on Prometheus's own state:
automation_dashboard (one joined snapshot) → optionally depth:"full" / agent_id- granular
schedule_job_* / task_control / agent_info only for control or deep single-entity inspection
show_agent_work to render the snapshot as an operator card — with real data, never invented
