Playbooks

A playbook is a goal Cofounder defines, such as creating a brand identity or generating a video. Cofounder writes and maintains each playbook's instructions, so improvements reach every company on its next routine run.

A playbook run is your company pursuing one playbook. It is one agent in a sandbox that has the cofounder CLI, signed in as the person who started the run. The agent works in routine runs: each one is a turn of that same agent, so it keeps its context and sandbox from one routine run to the next. Routine runs happen on the run's schedule, or right away when you continue the run. The agent keeps its progress in two places: Library files people read, and progress notes it posts to the company's event log, tagged with the run's id, which cofounder events list --attribute run_id=<id> returns. When the goal is met, the backend completes goal-driven runs automatically and future routine runs stop. A company can have several playbook runs, of the same playbook too.

Find a playbook and start a run

start creates the run, starts its first routine run right away, and schedules the rest on the playbook's default schedule. It spends model usage. Omit --request-id and the server assigns one, which becomes the run's id. To retry safely after a lost response, send your own --request-id <uuid> and reuse it: it never starts a second run. Without one, a retry starts a second run.

Set --max-routine-turns <count> and/or --deadline-at <timestamp> on start or update to bound a run. The deadline must include a timezone. The turn limit includes the first turn, scheduled turns, and manual continue requests; replaying the same request does not use another turn. A failed or interrupted launch still counts once it has been admitted, because the runner may have accepted it. Historical successful turns count too.

Both limits default to unlimited. Updating one leaves omitted fields unchanged; an explicit JSON null in the update API clears that limit. Reusing a start request returns the existing run and does not change its limits.

At the limit or deadline, no new turn starts and scheduling switches off. The run stays incomplete, with its files and progress intact. Work already running, including verification, may finish. Raise or clear the limit and re-enable scheduling to resume; manual continuation also checks the limits.

Every run also has a budget: a lifetime cap on the company credits it may spend, set with --budget-cents <cents> on start. Without it, a run gets its playbook's default_budget_cents, which list and get show: $50 (5000) unless the playbook sets its own. The paid operations the run's agent performs draw from the company's credit balance as usual, and so do the agent's own model calls, at cost plus 20%. Both count against the budget, net of refunds, along with holds for work still in progress. A charge that would take the run past its budget is refused, a model call is charged only up to the budget, and either way the run pauses with reason budget_exhausted. A paused run's agent stops before its next model call. Raise the budget with update --budget-cents <cents>, then resume the run with runs resume, which is refused while the run's spend is at or above its budget. Lowering a budget to the run's spend or below pauses the run. A paused run's limits and budget can change, but its schedule changes only once it runs again.

list and get include each playbook's prerequisite guidance and structured prerequisite_checks, with recovery instructions for requirements the backend enforces. If a prerequisite is missing, start returns a 409 error with missing_prerequisites before creating a run or schedule or launching the agent. Fix the missing input and retry with the same request id.

Company playbook preferences

Meta ads and organic social expose typed company-wide preferences through cofounder playbooks settings get --playbook-key <key>. Other playbooks return no configurable groups. Run budgets, schedules, deadlines, and approvals retain their existing operations.

For Meta ads, a local JSON settings file can contain:

{"optimization": {"target_cost_per_visit_cents": 125}}

Append it with:

cofounder playbooks settings overrides create --playbook-key meta-ads --request-id <uuid> --settings-file <path>
``` Omitted fields do not
change; lists replace prior lists. Reuse the request ID after an uncertain
response. Writes preserve actor, authority, time, and immutable sparse history.

Founder preferences win over main-agent preferences, which win over playbook-agent
preferences. The latest record wins per field within its tier. A saved value can
be masked by a higher authority: inspect the returned effective values and sources.
Playbook agents may change only fields marked `agent_writable`; resource selection
requires the founder or main agent.

To release your authority's claim, use the same operation with
`--release-field optimization.target_cost_per_visit_cents` (repeat the flag for
multiple fields). API/MCP callers use `release_fields` containing declared paths. Release falls back to lower-priority overrides
or catalog defaults; it does not resurrect older claims at the released tier.
The dashboard distinguishes release from setting the current catalog default.

Preferences apply across the company's runs of that playbook on their next turn.
The backend renders their resolved values, sources, and revision into the private
agent document. They do not automatically revise scheduled posts, resume runs,
or grant approval. These preferences are agent guidance; actual billing and
provider restrictions still apply.

## Manage a run

| MCP | CLI | API |
| --- | --- | --- |
| `playbooks_runs_list` | `cofounder playbooks runs list` | `GET /cofounder-cli/v1/playbooks/runs` |
| `playbooks_runs_get` | `cofounder playbooks runs get --run-id <id>` | `GET /cofounder-cli/v1/playbooks/runs/{run_id}` |
| `playbooks_runs_update` | `cofounder playbooks runs update --run-id <id>` | `PATCH /cofounder-cli/v1/playbooks/runs/{run_id}` |
| `playbooks_runs_cancel` | `cofounder playbooks runs cancel --run-id <id>` | `POST /cofounder-cli/v1/playbooks/runs/{run_id}/cancel` |

`runs get` shows a run's status (`running`, `paused`, `completed`, or `cancelled`),
why a paused run is paused, its limits, budget and spend, schedule, and next
routine run time.
`update` changes the `--schedule`, a standard
five-field cron expression (minute, hour, day of month, month, day of week)
evaluated in the run creator's timezone, or turns scheduled routine runs on
and off with `--enabled`. The run's agent posts progress notes to the company
event log with `events post`; each playbook describes what its notes carry,
and they read back through `events list --attribute run_id=<id>`.
`cancel` permanently stops future routine turns and records `cancelled`, preserving
files and verification history. Work already admitted may finish, but cannot mark
the run completed. Repeating cancellation is safe. A completed or cancelled run
cannot be reopened; start a new run to pursue the goal again.

Completion requires the nonempty Library files listed in the run's
`required_outputs`, plus passing results for every required verification criterion.
Saved Library files must still match their reviewed revisions. Editing a stage's
files requires verification again. Missing files or unfinished, failed, or
uncertain required judgments leave the run open. Optional criteria do not block
completion. The backend checks after relevant Library writes, after judges finish,
and before launching another turn.
Disable a run's schedule with `update --enabled false` to pause it, or use
`cancel` to end the run. For a playbook without verification
criteria, completion checks that outputs were delivered, not their quality.

Required **user_judge** stages must pass before the run can complete.
Approval passes a stage. Rejection fails it and gives the agent your feedback.
Without a response, the stage waits.

## Verification from a playbook agent

These commands require the company API key bound to a playbook run. Ordinary
company keys and signed-in user sessions cannot call them. The backend selects
the company and run from the credentials; do not supply a run ID.

```bash
cofounder playbooks verification show
cofounder playbooks verification show --stage voice
cofounder playbooks verification submit --stage voice

show returns the stages and statuses, or one stage's criteria, evidence, findings, and attempts. submit queues evaluation without waiting. Independent agent judges read the stage's saved Library files through Cofounder CLI and return a verdict and reason for each criterion. They run in their own sandboxes. Unchanged files reuse the same submission; interrupted jobs reconnect to the same judge. Binary checks and human reviews retain their configured Library inputs. Read the updated board with show. not_configured means no evaluation was queued, not that the stage passed.

Each run exposes a dated library_folder, for example general/playbooks/find-customers/2026-10-06_153000.000000Z. Save each stage under its key, such as .../icp/. The backend inserts this guidance in the run's goal.md. Choose useful filenames; the judge does not require a file schema or citation format. Keep canonical company documents in their usual locations and copy the inputs needed for this review into the stage folder. File revisions are recorded automatically. If they change, show asks for a new submission and the old pass cannot complete the run.

The commands appear in CLI help, but access is enforced on every backend request. They are not exposed as MCP tools.

Review a playbook's work

The playbook defines its review question and evidence in code. When the agent requests verification, Cofounder saves the submitted evidence. By default, the run creator gets an email linking to the dashboard review. Once the reviewer subscribes their dot to playbook.review.requested for the company, new reviews go to the dot while that subscription and its connection remain active. Without an active subscription, notifications use email. Signing in or installing the plugin alone does not switch delivery, and subscribing later does not replace email for an earlier review. The dot presents the question and saved evidence, then asks you to Approve or Reject with an optional comment. The decision is saved to the same verification attempt: Eve reads the pass/fail result and your feedback with cofounder playbooks verification show.

Only that person's signed-in session can submit the decision, through the dashboard, CLI, or an authenticated MCP connection. A dot can present the request and record your explicit decision and comment. Company API keys, including the playbook agent's key, cannot approve the work. The dashboard shows the saved version, decision, comment, and decision time. A new submission replaces the pending request when its evidence changes. Replaced requests cannot receive a decision.

Use --decision reject to return feedback for revision. Repeating the same decision and comment is safe; a conflicting decision is refused.

For notifications in a dot or Work chat, connect the plugin and ask it to monitor playbook.review.requested for your company after the rollout flag is enabled. Plugin setup offers this subscription after selecting a company. Installation alone does not subscribe. The event contains the company, run, review, and attempt IDs; the dot reads the saved evidence before asking you to decide. It never treats the event as approval. New subscriptions cover new requests; playbooks_reviews_list finds earlier pending requests. With the flag on but no subscription, the request remains pending until you read and decide it; email is not an automatic fallback. Turning the flag off stops dot delivery and restores email for new review notifications. The dashboard continues to show saved requests and decisions.

Brand launch-post rounds

New brand identity runs end with launch-post variants from one canonical brand. Existing runs keep their saved stages. Each variant contains a styled image and caption or description. The playbook creates three variants by default. Each submission accepts one to six variants. It uses existing business documents and a brand kit. A built product or live website is not required.

Every new round requests an independent agent assessment and user review of the same saved evidence. The agent records each variant's verdict and comment, and recommends Pass or Iterate for the round. Its assessment is recorded for comparison and is not shown in the review UI. It does not control completion or replace your guidance.

Approve or reject any number of variants. Add feedback, including required guidance for each rejected variant. Choose Complete to approve this stage, or See more to continue. The dashboard saves your variant votes and feedback with this explicit round decision. Individual variant approvals do not pass the stage. New runs require only the launch-post stage and the saved canonical outputs to complete.

Eve reads your feedback on its next turn. Guidance that changes the brand must change canonical documents and assets first. Eve generates new variants from the updated sources. Requests for more expressions can reuse the current canonical brand. Changed sources or artifacts require a new submission. Saved rounds retain both judgments for comparison.

The agent acts as the run's creator through one company API key, named Playbook run <id> in cofounder company api-keys list. Each routine run keeps it valid for another 24 hours; a run that stops lets it expire. Because the agent acts with the creator's access, only the creator can update, continue, or cancel a run; any company member can list and read it. The agent itself can do anything the creator can do in the company except change billing, start, update, or resume a run, or decide approvals, so it cannot raise its own budget.

Continue a run and check its routine runs

continue starts one routine run right away, outside the schedule, and spends model usage like a scheduled one. Send your own --request-id <uuid> and reuse it if the response gets lost; without one, a retry starts a second routine run. A routine run is starting until the runner accepts it, then started; one the runner could not take is failed, with the reason. An attempt blocked by the turn limit or deadline is skipped, with reason turn_limit_reached or deadline_reached. A reclaimed launch that may already have reached the runner is also skipped with already_admitted. What it produced shows up in the run's progress events and the Library files it writes.

Prerequisites are checked again before every manual or scheduled turn. If an input has been removed or archived, that routine run fails with a recovery message without launching the agent. Restore the input and continue with a new request id, or wait for the next scheduled turn.

Approvals

A run's agent asks for a decision by creating an approval: a social_post, email_draft, spend_request, or other, with a title and a JSON --payload holding what the decider needs to see. Only a playbook run's own agent can create one, through the CLI, and it belongs to that agent's run. A blocking approval (--blocking; --no-blocking queues it) pauses the run: no routine run starts, on demand or on schedule, until it is decided and the run is resumed. A non-blocking approval queues while the run keeps going.

approve and reject only record the decision and optional --feedback; the agent acts on them in a later routine run. A decision is final; repeating it the same way changes nothing. Once no blocking approval is pending, the decision's next step is runs resume, which sets the run running and starts a routine run. The first routine run after a pause lists every approval decided since, with its feedback, even if an interrupted resume has to be retried. Resume spends model usage like continue, and its routine run still counts against the run's turn limit and deadline. A paused run can still be cancelled. Only the run's creator can decide approvals or resume a run, and the run's own agent can do neither. Anyone in the company can list a run's approvals and their history.

A spend_request asks to spend company money. Its payload says what for (spend_type, such as ads), how much (amount_usd), and what the spend applies to, such as the drafts' campaign_ids. Playbooks ask with a blocking spend_request and spend only after it is approved.

The playbooks

Sign up for a service (service-signup) uses the company's managed AgentMail email and Zernio SMS number. Save the service URL, approved profile details, requested credentials, and any authorized purchase terms in general/playbooks/service-signup-request.json before starting.

GLM 5.3 drives the Eve agent with shell, internet, Cofounder CLI, and a Browserbase Verified session. It uses standard Playwright for DOM or mouse and keyboard interaction, with Kimi K3 screenshot interpretation when needed. The agent discovers the site's flow, handles verification, validates credentials, and saves them with cofounder secrets set. Those writes can redeploy the app. There are no service-specific browser actions or credential-capture helpers.

Routine runs default to every ten minutes. After checking the requested result, the agent writes general/playbooks/<run id>/service-signup-receipt.json, which completes the run. Interrupted work is resumed by inspecting the current account and browser state. Unsupported signup methods or missing approvals are reported as blockers. Browserbase and vision-provider charges are separate from the company-credit budget.

Log in to a service (service-login) uses the same GLM 5.3 Eve agent, Browserbase Verified browser, and Kimi K3 screenshot review. Save the login URL, existing account identity, and saved credential names in general/playbooks/service-login-request.json. Use password_secret to name the account password saved during signup, or omit it for a passwordless account. Optional mfa_secret names saved MFA material. Keep secret values out of the request.

The agent retrieves saved passwords from the managed app through cofounder hosting credentials create --json and Vercel environment export; cofounder secrets list exposes only metadata. Set request.hosting_resource when the credentials belong to a specific managed app. Email and SMS challenges use the account's managed AgentMail inbox and Zernio number. Missing credentials or unavailable verification methods block completion.

An optional after_login task runs in the same signed-in browser. Otherwise the agent verifies the account and closes the browser. It writes general/playbooks/<run id>/service-login-receipt.json after verification and browser release, which completes the run. Routine runs default to every ten minutes. Each later run logs in again; this does not provide a shared browser session for other agents. Login alone does not request new API keys, reset passwords, or authorize purchases.

The brand playbooks run as a chain: Brand identity → Brand voice → Design system. Each consumes the previous playbook's canonical document and does not redefine it.

Brand identity (brand-identity) creates the company's canonical marketing/brand_identity.md. It requires general/ICP.md, general/product.md, general/value.md, general/pain.md, and general/mission-vision.md to already contain substantive business context. It does not create these prerequisite documents. The backend requires them to be active Library files with nonempty stored content before creating a run and before each new turn. Missing inputs return specific recovery instructions; Eve and the verification judges check whether the answers are substantive and consistent. It does not need a brand kit. Its routine runs happen daily at 08:00 until the identity stage passes and the backend completes the run.

Brand voice (brand-voice) creates marketing/brand_voice.md from the identity and the business documents. It requires marketing/brand_identity.md and completes when the voice stage passes.

Design system (design-system) builds the design system inside the company's product repository after Brand voice. It requires the identity, the voice, and a product repository. An agent judge reviews the rendered components, one review sheet per component group, against DESIGN.md. The run completes when the judge passes them. Eve leaves a pull request for the coding agent to review and merge. The coding agent then builds the website in the product repository, using GUI.md, DESIGN.md, and the shared components. The review.js bundle is saved in the run's folder for stepping through. Once the website works, run improve-design for visual review.

Improve design (improve-design) improves an existing website using its design system. It requires the identity, voice, and a product repository. The playbook also instructs Eve to check that the website and design system exist before starting. These content checks are instructions, not automatic repository checks.

Eve opens a separate pull request and submits one frozen desktop screenshot to the Taste design judge. Capture exactly 1440 × 900, with full-page capture disabled. Taste does not support mobile or full-page screenshots. The desktop screenshot must receive accept before the Taste stage passes. A separate design-copy agent judge checks the screenshot and recorded page copy against the brand voice. It rejects demo labels, defensive disclaimers, implementation notes, and decorative eyebrows. Both stages share one review folder and must pass before the run completes. The saved Taste result includes the verdict, margin, threshold, and judged image URL. Provider errors do not count as acceptance. The pull request and company events show the work and verification results. The coding agent reviews and merges the pull request.

Legal documents (legal-documents) is separate from the brand chain. The agent asks you for your legal name, entity type, jurisdiction, a public address, and a public contact email, reads your product repository to see what data it collects and who processes it, and drafts legal/privacy-policy.md and legal/terms-of-service.md marked as AI-drafted, not legal advice. It then pauses on a blocking other approval whose payload holds the full text; the approved text is what shadcn add @cofounder/legal installs as /privacy and /terms. The legal stage then checks the approved text against the evidence.

Working notes, audits, candidate drafts, and trial responses stay in Eve's sandbox. The Library holds canonical company documents and reusable assets. Existing runs keep the stages saved when they started. Runs of the retired design-kit playbook were cancelled when it was removed.

Generate ad images (ad-image-gen) makes the image ads the user asked for. Its routine runs happen daily at 08:00: each finds the newest ad image request in the company's events and makes a round of image ads, each an image and its ad copy (a headline and primary text). It saves your brief to general/playbooks/<run id>/ad-brief.md and lists the round in general/playbooks/<run id>/ad-image-variants.json.

The required ad-images stage is judged by an agent, not by you. The judge inspects each frozen image and its copy against the brief, gives each ad a pass or fail verdict, and passes the stage only when every ad is ready to run. After a failed round, the playbook fixes the failing ads and submits again. Once the stage passes, the backend completes the run automatically if the saved work still matches the judged round. The meta-ads playbook runs only image ads that passed here.

Ad creatives (ad-creatives) makes three 9:16 Meta video ads for your product. Its routine runs happen daily at 09:00. It researches hooks in live Meta ads with ads research and tests them as cheap drafts before it generates footage. It composes each ad in HyperFrames from your real product visuals, then checks every frame against Reels safe zones and mechanical quality gates. It saves general/playbooks/<run id>/ad-1.mp4 through ad-3.mp4, the brief in ad-brief.md, and hooks, scripts, and Meta copy in ad-copy.md. It never launches ads or spends ad budget. Footage and research cost about $5 per finished ad.

The run has no review stage. Each ad must pass the mechanical quality gates and score at least 8 out of 10 on the ad evaluator rubric before it is saved, and the backend completes the run once all three ads and ad-copy.md are saved.

Writing improvement (writing-improvement) rewrites a draft until it no longer reads as machine-written. Save the request in general/playbooks/writing-improvement-request.json before starting: the writing as source_path (a Library text file) or text, plus optional kind, audience, keep (passages that must stay exactly as written), and notes. The run copies the source on its first turn, so wait for its first progress note before replacing the request for another run.

The agent checks the draft with cofounder writing check, rewrites only the flagged paragraphs, and checks again, for up to eight rounds a turn. It saves the untouched source to general/playbooks/<run id>/writing-source.md and the rewrite to general/playbooks/<run id>/writing-improved.md, and never changes the source file. The required writing stage has two agent judges, each in its own session: one runs the writing check on the submitted rewrite and passes only when nothing is flagged, and the other confirms the rewrite keeps the source's facts, keep items, and purpose. Routine runs happen every ten minutes until both pass; most runs finish in their first turn. A flag that cannot be fixed without breaking a keep item leaves the run open with that blocker named; cancel it with playbooks runs cancel and start a new run with a changed request.