Skip to content

Cookbook: write a recipe for an agent that does not have one #111

Description

@arpanghoshal

The cookbook has 22 recipes. Each one is a single consequential action, the policy that
governs it, and a runnable example. The ones below have no recipe and would each make a good
first contribution.

Claim one in a comment before you start so two people don't write the same page.

Recipe Category The action worth gating
A subscription-cancellation agent Money Cancelling or refunding a plan mid-term, with a tier where a human answers
A price or inventory-change agent Money A price write that a fat-fingered decimal makes catastrophic
A DNS-record change agent Infrastructure An A or MX change that takes a domain off the internet
A feature-flag rollout agent Infrastructure Moving a flag to 100% of traffic
A document-sharing agent Permissions Granting access to somebody outside the organisation
A payroll-change agent Records Editing an amount that reaches a bank file

What a recipe is

Read two or three existing ones first — refund-agent.mdx
is the shortest, data-deletion-agent.mdx shows a
constraint carrying the interesting part. Each has: the action, the policy YAML, the decorated
function, what happens when the guard fires, and what CTRLRun does not do for that scenario.

Done means

  • The page is in docs/cookbook/, linked from docs/cookbook/index.mdx under its category.
  • Every fenced block marked runnable executes offline and exits 0tools/docs_audit/
    runs them in CI with a socket guard. A sample either runs or is not marked.
  • Behind every expected refusal, an else that fails. A sample that asserts a refusal
    raises on the path where the refusal did not happen. Documentation that quietly starts
    succeeding is worse than none.
  • docs/STYLE.md — run the four checks in its last section before opening the PR.
  • No compliance or standards language anywhere in it. The forbidden-words lint will tell you,
    but the rule is in CONTRIBUTING.md and it is not negotiable.

A recipe not on this list is welcome too, if it is a real action that can move money, delete
infrastructure or grant permissions. Say which one in a comment first.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedExtra attention is needed

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions