/run - Execute Tasks with Agents

ai cagents claude run execution workflow

Created: March 27, 2026 | Modified: March 27, 2026

This is Part 3 of a 10-part series on cAgents. Previous: /designer - Design Before You Build | Next: /team - Parallel Multi-Agent Execution

/run is the workhorse. Give it a task - implement this feature, write this article, fix this bug, refactor this module - and it hands the work off to a coordinated set of agents that plan, execute, and validate the result. You describe what you want. They figure out how to do it.

Most of the time, this is the command you reach for. I use it more than all the other cAgents commands combined - it handles the full lifecycle from "here's what I need" to "here's the finished work," without you needing to babysit each step.

When to Use This

/run is the right choice for single-scope tasks with a clear output:

Implement a specific feature or component
Write a piece of content (article, report, spec, email)
Fix a bug or resolve a specific error
Refactor or clean up a module
Generate tests for an existing function or file
Set up a configuration or scaffolding

Use /team instead when you have three or more independent items that could run in parallel - for example, building three separate pages, or writing five blog posts. /run handles them sequentially; /team runs them at the same time.

Use /org instead when the work spans multiple business domains - engineering and marketing and legal, for example. /run operates within one domain. /org coordinates across many.

When in doubt, start with /run. It's the right call far more often than not.

How the Pipeline Works

When you run a task, cAgents moves it through a multi-stage pipeline automatically. The simplified view:

1. Orchestrator - Reads your task and enriches it with context. It pulls in your CLAUDE.md, notes the current state of the project, and packages everything the downstream agents need to understand the job.

2. Planner - Creates a structured plan: the objective, the steps, and the acceptance criteria. This is the "here's how we're going to do this" stage. The plan runs before any work begins.

3. Decomposer + Prompt Engineer - Breaks the plan into granular work items and crafts the delegation prompts that each execution agent will receive. This stage is invisible to you but accounts for a lot of the quality difference between cAgents and raw prompting.

4. Controller - Coordinates execution. It delegates work to specialist agents (a backend developer, a technical writer, a QA engineer - whatever the task calls for), tracks progress, and handles follow-ups between agents.

5. Validator - Checks the finished work against the acceptance criteria from the plan. If something doesn't pass, it flags it for revision before returning the result to you.

You don't configure any of this. The pipeline runs automatically, and the agents selected at each stage depend on what your task actually needs.

You can see the plan before execution starts using --dry-run. This is useful when you want to sanity-check the approach before committing to it - especially on longer tasks.

Walkthrough -- Building a Homepage

In the previous article, /designer produced a spec for a personal portfolio site: a homepage with a hero section, a short bio, featured work, and a navigation bar linking to About, Portfolio, and Blog pages. Now it's time to build.

/run Build the homepage and navigation from the design spec in design-spec.md

The orchestrator picks up the design spec from the project context. The planner produces a task list:

Plan: Homepage and Navigation

Tasks:
  1. Scaffold homepage layout (Next.js App Router structure)
  2. Implement navigation component with links to About, Portfolio, Blog
  3. Build hero section with headline and CTA button
  4. Build bio section with placeholder content
  5. Build featured work grid (3-item layout, placeholder cards)
  6. Wire up responsive mobile nav (hamburger menu)
  7. Apply theme colors and typography from design spec
  8. Validate against design spec acceptance criteria

Estimated: 8 tasks

The controller assigns the work: a frontend developer agent handles the component implementation, a second agent applies the theme, and a third validates the output against the spec. Each agent works on its assigned tasks, reports back to the controller, and hands off cleanly.

When it's done, you have a working homepage and navigation - files written, structure in place, matching the spec. The validator's report tells you which acceptance criteria passed and flags anything that still needs attention.

If the spec from /designer is saved as a file in your project, pass it explicitly with --from-designer design-spec.md. This gives the orchestrator a direct reference instead of relying on it to find the file.

Walkthrough -- Writing a Blog Post

After /designer produced a content strategy - audience personas, topic pillars, and a publishing cadence - the next step is to start executing on it. The first deliverable: the flagship "pillar" post that anchors the whole content plan.

/run Write the first blog post based on the content strategy in strategy.md.
Topic: "Why most small teams over-invest in tooling and under-invest in process."
Audience: technical founders, 1000-1500 words, practical and direct tone.

The planner breaks this down:

Plan: Pillar Blog Post - Tooling vs. Process

Tasks:
  1. Research: pull key points from strategy.md relevant to this topic
  2. Draft outline: intro, 3 main arguments, actionable takeaways, conclusion
  3. Write full draft
  4. Apply tone guidelines from strategy (practical, direct, no jargon)
  5. Add internal links per content strategy linking plan
  6. Validate: word count, tone match, aligns with pillar topic goals

A content strategist agent reads the strategy, a writer agent drafts the post, an editor agent reviews tone and structure, and the validator checks alignment with the content plan.

The result is a complete draft, ready for your review. Not a bullet-point outline - a full article with the structure, tone, and focus described in the brief.

The clearer the brief, the better the output. /run doesn't guess at intent - it works from what you give it. A task that specifies audience, word count, and tone produces a more useful first draft than "write a blog post about X."

Key Flags

Flag	What It Does
`--dry-run`	Shows the execution plan without running it. Useful for reviewing the approach on complex tasks before committing.
`--interactive`	Pauses at each task and asks for your confirmation before proceeding. Useful when you want to stay in the loop on a sensitive or unfamiliar task.
`--from-designer`	Passes a `/designer` output document directly into the orchestrator's context. Use this when chaining `/designer` → `/run`.
`--resume`	Resumes an interrupted session from the last completed task. cAgents checkpoints progress, so if a long session gets cut off, `--resume` picks up where it left off rather than starting over.

Tips & Gotchas

Scope your tasks to one deliverable. /run works best when the task has a single clear output - one component, one document, one bug fix. If you find yourself writing "and also..." in the task description, split it into two /run calls, or consider /team if the items are independent.

Use --dry-run on anything longer than 5 tasks. Reviewing the plan before execution is free. It takes 10 seconds to read and can save you from realizing mid-run that the agents are solving a slightly different problem than the one you had in mind.

Follow-up adjustments reset the validator. If you run /run, review the output, and ask for a change, cAgents treats the follow-up as a new task and re-validates from scratch. This is usually what you want - but it means small tweaks ("change the heading color") go through the full pipeline. For trivial edits, making the change yourself is faster.

Don't lose progress to an interrupted session. cAgents checkpoints as it goes, but if your terminal closes mid-run, use --resume to pick up where it left off. Running the same task again from scratch wastes work. You don't need to dig through directories yourself - just ask Claude "find the last session for X" and it will locate the right one and resume it for you.

What's Next

The homepage and first blog post are done. Next up: the remaining pages of the website - About, Portfolio, and Blog - plus the next month's content calendar. These are multiple independent pieces, which means they're a natural fit for parallel execution.

Part 4: /team - Parallel Multi-Agent Execution covers how to run multiple tasks simultaneously with wave-based quality gates, and when that's faster than running them one at a time.

Series navigation: Previous: /designer - Design Before You Build | Next: /team - Parallel Multi-Agent Execution