/run - Execute Tasks with Agents
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.
--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
/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.
/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
/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.
/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."Walkthrough -- Building a Course Materials Package
/designer produced a semester redesign for Maya, a 10th-grade US History teacher converting from lectures to project-based learning. The spec defined 6 three-week units, each built around a major project with peer-review stages. It caught a grading-load problem she hadn't named -- 125 projects to evaluate per cycle -- and restructured the whole plan around assessment efficiency. Now it's time to build the first unit.
/run Build the complete materials package for Unit 1 from the course design spec.
Unit: "The Constitution: Compromise and Conflict." Include: project brief,
15 daily lesson plans, 4 primary source documents with guided questions,
assessment rubric, and parent communication letter.
The planner breaks this down:
Plan: Unit 1 Materials Package - The Constitution
Tasks:
1. Write the project brief (deliverables, timeline, group formation rules)
2. Build 15 daily lesson plans (structured debates, small-group activities,
scaffolded research days)
3. Select and annotate 4 primary source documents with guided reading questions
4. Design the assessment rubric with peer-review integration
5. Write the parent communication letter explaining the PBL format
6. Validate all materials against Ohio state standards
A curriculum designer agent writes the project brief and lesson plans. The lesson plans aren't "read chapter 3" -- they include structured debate formats, small-group document analysis activities, and scaffolded research days where students build toward the project incrementally. A second agent handles the primary sources, selecting documents at appropriate reading levels and writing questions that build from comprehension to analysis. A third agent designs the rubric with specific criteria ("identifies 3 causes of the Great Compromise and explains each") rather than vague language ("demonstrates understanding").
The parent letter is the piece Maya dreaded most. It explains what project-based learning is, why it produces better outcomes than lecture-and-test, and exactly how grades will work -- anticipating the question every parent asks first. The validator runs a standards alignment check and flags one lesson plan that doesn't explicitly connect to any Ohio standard. It's revised before delivery.
The result is a complete, teach-ready package for 3 weeks of class. Maya needs Units 2-6 next -- all independent, all following the same structure. That's a job for /team.
/run handles complex single-scope work well. "Build one unit's complete materials" is one deliverable, even though it contains lesson plans, documents, and a rubric. If Maya had asked for all 6 units at once, /team would be the better choice.Walkthrough -- Building a Restaurant Operations Playbook
/designer produced an expansion plan for David, a restaurant owner opening a second location of his Nigerian restaurant. The spec identified his real risk -- the original location's quality depends on him being there -- and proposed a reduced 12-item launch menu after pushing back on David's instinct to replicate the full 22-item menu. It mapped the backward timeline from an October opening and produced a phased plan with staffing requirements and a budget breakdown. Now it's time to build the operations playbook that the new kitchen will run on.
/run Create the operations playbook for the Decatur location based on the
expansion plan. Include: opening/closing checklists, daily prep schedule,
weekly inventory ordering procedure, and recipe cards for all 12 launch menu
items scaled for the Decatur kitchen (45 seats vs. Midtown's 70).
The planner breaks this down:
Plan: Decatur Location Operations Playbook
Tasks:
1. Write opening and closing checklists (kitchen, front-of-house, management)
2. Build the daily prep schedule with time estimates per station
3. Design the weekly inventory ordering procedure with par levels
4. Create 12 recipe cards with scaled quantities and plating instructions
5. Add allergen flags and cross-contamination notes to all recipe cards
6. Validate recipe scaling math and checklist completeness
An operations specialist agent builds the checklists and procedures. A second agent handles the recipe cards -- and this is where domain knowledge matters. Recipe scaling isn't linear. A batch of jollof rice that serves 70 doesn't scale to 64% for 45 seats because sauce reduction rates change with pot size, and stew yield curves aren't proportional. The agent builds per-recipe scaling factors instead of applying a flat ratio.
The prep schedule accounts for the new kitchen team's learning curve. Experienced cooks at the Midtown location prep jollof rice in 20 minutes; the schedule gives the Decatur team 35 minutes initially, with a note to tighten timing after the first month. The inventory ordering procedure sets par levels based on Midtown's sales data, adjusted downward for projected lower volume in the first 3 months.
The validator confirms all 12 recipes have complete ingredient lists, allergen flags, and plating instructions. The result is a playbook David can hand to a kitchen manager on day one. Next, he needs a staffing plan, training manual, and menu design built in parallel -- a natural fit for /team.
Walkthrough -- Building a Press Kit and Steam Page
/designer produced a 10-week launch strategy for Sadie, a solo indie game developer preparing to release her narrative puzzle game on Steam. The spec reframed her thinking: the 8 weeks before launch matter more than launch day itself, because Steam's algorithm rewards launch-week velocity. It mapped a backward countdown -- trailer and Steam page overhaul first, then press outreach, then community building and demo release, then launch. Now it's time to execute Phase 1: the store page and press kit that everything else depends on.
/run Build the press kit and rewrite the Steam page copy based on the launch
strategy. Game: "Meridian" - a narrative puzzle game about memory and loss.
Include: Steam description (short + long), 6 screenshot captions, press kit
fact sheet, developer bio, and a press-ready game summary (200 words).
The planner breaks this down:
Plan: Meridian Press Kit and Steam Page
Tasks:
1. Write the Steam short description (tagline + hook, 300 chars)
2. Write the Steam long description (features, tone, what makes it different)
3. Write 6 screenshot captions that sell the experience, not the mechanics
4. Build the press kit fact sheet (platforms, price, playtime, content warnings)
5. Write the developer bio in third person for press use
6. Validate all copy against Valve's Steam store content guidelines
A content strategist agent identifies that narrative games sell on feeling, not features. The Steam description leads with an emotional hook -- "What would you remember if you could only keep seven memories?" -- rather than a mechanics list. The long description follows the same principle: what the player experiences, then what makes it different from other puzzle games, then the feature details at the bottom for people who scroll that far.
The press kit fact sheet includes the specific data journalists actually need: platforms, price point, release date, estimated playtime, content warnings, and comparison titles ("for fans of Return of the Obra Dinn and What Remains of Edith Finch"). The developer bio tells a story -- Sadie's path from hobbyist to solo developer, what the game means to her -- written in third person so journalists can drop it directly into coverage.
The validator checks every line of Steam copy against Valve's content guidelines: no superlatives ("the best"), no misleading claims about features not in the game, no review quotes before launch. One line is flagged and revised.
The result is a launch-ready store page and a press kit Sadie can send to journalists as-is. Next up: the trailer script, community posts, and press outreach emails -- three independent workstreams that run in parallel with /team.
Walkthrough -- Building Vendor RFPs and Guest Communications
/designer produced a wedding concept and logistics framework for Rosa, a wedding planner coordinating a destination wedding in Todos Santos, Mexico. The spec confronted the budget tension head-on -- "rustic elegance" as the couple defined it costs $85-95K, not $65K -- and produced three budget scenarios with strategic substitutions. It surfaced cross-border logistics Rosa hadn't fully mapped: vendor deposits in pesos, exchange rate risk, liquor import restrictions, and passport reminders for US guests. Now it's time to build the vendor packages and guest communications that get the planning in motion.
/run Build the complete vendor RFP package (8 vendors) and guest communication
suite from the wedding design spec. RFPs need to be bilingual (English/Spanish).
Guest communications in English only. Include the budget ceiling for each
vendor category.
The planner breaks this down:
Plan: Vendor RFPs and Guest Communication Suite
Tasks:
1. Write bilingual RFPs for 8 vendors (florist, caterer, photographer, DJ,
officiant, lighting designer, hair/makeup, transportation)
2. Adapt business communication tone for Mexican Spanish formal conventions
3. Build travel info page (flights, ground transport, health advisory, packing guide)
4. Write accommodation guide with hotel room block details
5. Create guest FAQ (visa questions, currency, cell coverage, dress code)
6. Validate that all 8 RFP budget ceilings sum within total budget
The planner recognizes that bilingual RFPs aren't a translation task -- Mexican Spanish business correspondence uses different formal conventions than the English versions. The agent handles this as a cultural adaptation, not a word swap.
The RFPs themselves are specific. Not "we need a florist" but "we need ceremony arrangements for a beach arch (wind-resistant construction required), 10 centerpieces in the rustic-elegant style (reference photos attached), and bouquets for bride + 4 bridesmaids. Budget ceiling: $4,200." Each RFP includes the event date, venue details, setup access times, and the specific deliverables expected -- everything a Todos Santos vendor needs to quote accurately on the first pass.
The guest communication suite handles the logistics that destination wedding guests actually worry about. The travel info page covers flight options to SJD airport, ground transportation from the airport to Todos Santos, a vaccination and health advisory, cell coverage notes, and a packing guide for a beach wedding in Baja. The FAQ answers the questions Rosa knows guests will ask -- currency exchange, tipping customs, whether they need a visa, and what "beach formal" actually means.
The validator checks that all 8 RFP budget ceilings sum to less than the total budget. They do -- Rosa allocated 15% contingency, and the math holds. The result is a package Rosa can send to vendors this week and a communication suite that answers guest questions before they ask. The ceremony script, reception timeline, and day-of coordination documents come next -- three independent deliverables that run in parallel with /team.
Walkthrough -- Writing a Podcast Pilot Episode Script
/designer produced a show format for Jordan, a podcast producer launching a narrative nonfiction show about overlooked moments in labor history. The spec identified the sustainability constraint Jordan hadn't mapped -- a 30-minute narrative episode takes 40-60 production hours, which means monthly releases at 12 hours per week, not the biweekly cadence Jordan had assumed. It proposed a hybrid format: full narrative episodes monthly, with shorter interview-based "sidebar" episodes in between. Now it's time to write the first episode.
/run Write the full production script for Episode 1: "The Bread and Roses Strike."
Narrative nonfiction format per the show design spec. 28-32 minutes. Include:
narration text, source citations for every factual claim, interview segment
placeholders (3 segments), music/sound cues, and pacing notes.
The planner breaks this down:
Plan: Episode 1 Production Script - The Bread and Roses Strike
Tasks:
1. Research the 1912 Lawrence textile strike (primary + secondary sources)
2. Design the narrative arc and episode structure
3. Write the full narration script with inline production notes
4. Write 3 interview segment placeholders with suggested questions
5. Add source citations for every factual claim
6. Validate script length, source reliability, and production note completeness
The planner identifies that the script needs a narrative frame, not a chronological retelling. A researcher agent compiles the source material. A writer agent builds the script around a structural choice: open with a present-day scene at the Bread and Roses monument in Lawrence, Massachusetts, then work backward to the strike itself. This isn't an essay -- it's a production document. The script includes inline cues throughout: [MUSIC: subtle tension build, strings] before the first confrontation scene, [PACE: slow here -- let the quote breathe for 3 seconds before narration resumes] after a key passage, [SFX: factory ambient -- looms, steam] to set the scene.
The interview placeholders are specific enough to be useful. Not "interview a historian" but "Interview Segment 2: labor historian on why the strike is under-taught. Suggested question: What does the erasure of the Bread and Roses Strike tell us about how we choose which labor stories to remember?" Jordan still needs to book and record the interviews, but the placeholders define exactly what each segment needs to accomplish in the episode's arc.
Every factual claim is footnoted. The validator flags one claim that relies on a single secondary source and recommends Jordan verify it against a primary source before recording. The script comes in at 30 minutes estimated runtime.
The result is a script Jordan can record from -- not a document that needs to be rewritten into a recording format. Episodes 2-4 need research packages and scripts next, and since they're independent episodes, they're a natural fit for /team.
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
/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.--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./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.--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 is built, the blog post is drafted, Maya has her first unit's materials, David has his operations playbook, Sadie has her Steam page ready, Rosa's vendor RFPs are out, and Jordan has a script to record. Each task was a single deliverable handed to /run. But every one of them has follow-up work -- Maya needs Units 2-6, David needs staffing and training and menu design, Sadie needs a trailer script and press outreach and community posts. Multiple independent pieces, all ready at the same time. That's 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