Tasks, step by step

Each task is a procedure: run the steps in order, check the result, and stop at the step marked Needs a person until they have done it. Values in angle brackets are placeholders: take them from the person or from their project, never from an example. Every command that changes something runs with --dry-run first; run it again without --dry-run when the plan is what the person asked for.

Before any task, you are set up and signed in (Frazer for agents).

Create a project

1. Plan it. Project IDs are 6 to 30 characters (lowercase letters, digits and hyphens, starting with a letter) and unique across Frazer, so they usually start with the organization: <org>-staging.

   frazer projects create <project> --organization <org> --dry-run

2. Create it.

   frazer projects create <project> --organization <org>

3. Check it worked.

   frazer projects get <project>

If the change needs a person’s approval, the command exits with code 13 (needs a person) and prints the approval’s link: wait for it.

Deploy the repository you are in

1. Plan a serverless deploy from the current directory. --with adds a database or a cache and binds it to the service (postgres, valkey, bucket, llm).

   frazer serverless deploy <service> --source . --project <project> --dry-run

2. Deploy it: the same command without --dry-run. In production, traffic moves to the new revision gradually behind an analysis gate.

3. Check it worked. The service has a ready revision and a URL, and its logs show requests.

   frazer serverless services get <service> --project <project>
   frazer logs <service> --follow

frazer deploy with no flags asks the person whether the app runs on Kubernetes or serverless the first time, and stores the answer in .frazer/app.yaml. As an agent, pass the choice explicitly as above, or deploy where .frazer/app.yaml already says. More: Serverless.

Add a secret

1. Create the secret, with the folder it belongs in and the environment variable it becomes.

   frazer secrets create <name> --folder <folder> --key <ENV_NAME> --dry-run
   frazer secrets create <name> --folder <folder> --key <ENV_NAME>

2. Needs a person for the value, unless it is already in your environment. Read it from stdin, never from an argument, so it stays out of shell history and logs:

   printf %s "$VALUE" | frazer secrets versions add <name> --from-stdin --reason "<why>"

   When only a person has the value, never ask for it in chat: ask them through a person task with a secret slot, which writes the value into the secret for you.

3. Point an alias at the version, so consumers that follow the alias get it.

   frazer secrets versions alias <name> <alias> <version>

4. Check it worked. frazer secrets where-used <name> lists every consumer and the version it holds. To run a local command with the project’s secrets, use frazer secrets run --project <project> -- <command>.

Never print a secret’s value, write it to a file, or put it in a prompt, an issue or a commit. More: Secrets.

Open a Fir session

Every agent’s work is a Fir session, and an agent’s commit without one is refused. If your harness has the Fir plugin, it opens the session for you at start; otherwise open it yourself before you change anything.

1. Connect your harness to Fir once. --dry-run lists every file it would write.

   fir agent setup <harness> --scope repo --dry-run

2. Open a session bound to what you work on: a plan item, an issue or a workspace.

   fir session open --plan <plan> --item <item>

3. Work. Before a long wait (CI, a review, a person), write a checkpoint with a handoff; when you finish, close the session with its outcome.

   fir session checkpoint --handoff -
   fir session close --outcome done

4. Check it worked. fir session view <session> --json shows the session open, bound to your item, with your events; a commit now goes through, and its provenance names the session.

If a commit returns SESSION_REQUIRED (exit 5), run the next call it prints. After a restart, fir session resume --mine --open brings every open session back. Nothing here needs a person.

Open a pull request on Fir

You work in a Fir workspace with an open Fir session: a Frazer session starts in one, and fir status shows it. Use fir, not git.

1. See where you are and what you changed.

   fir status
   fir diff

2. Open the pull request. Write its intent from your task: what it is for, the plan and how to check it. Link the issue it fixes.

   fir pr create --fixes <issue>

3. Read the checks. A failing check shows its failing excerpt first.

   fir pr checks <number> --failed

4. Fix what failed in the same workspace, then add a new version to the same pull request. It keeps its number.

   fir pr push

5. Ask what still blocks the merge, then ask the server to merge when the rules allow.

   fir pr blockers <number>
   fir pr merge <number> --auto

6. Check it worked. fir pr view <number> shows it merged with its sequence number, such as main@48217; fir pr why <number> prints its merge receipt, or the one condition it still waits for, and fir queue status main shows the merge queue while it waits.

Needs a person only outside an approved plan’s terms, or for an approval the rules ask for: inside the terms a layer auto-merges when its checks and an independent second opinion pass, and fir pr blockers names any rule that still needs a person. Agents never approve, and never merge locally and push. More: Fir, Fir CLI.

Draft a plan and ask for approval

A plan is the document a change is written against: why, what done means, the items and the open decisions. It appears at docs/plans/ in your workspace, whether the repository stores it in its own tree or in the project’s plan repository.

1. Draft it from the issue. Fir writes the file and opens the plan’s pull request; the plan gets its number when that pull request merges.

   fir plan new --from-issue <issue> --tier task

2. Write the Why (the goal, who is affected, the non-goals, success metrics as queries with a baseline and a target), the outcome with acceptance criteria that each name the check that proves them, and the items. Then run the record checks and fix what they find.

   fir record check docs/plans/<file>.md --fix

3. Answer what you can find in the code, fir why, metrics and the decisions in force. Raise each remaining question as a decision row with two to four options and your recommendation; at most five reach the person.

   fir decision raise --plan <plan> --question "<question>" \
     --option A="<option>" --option B="<status quo>" --recommend A --why "<why>"

4. Run the plan’s checks and fix what they find. Static checks run first and report every error at once; the model checks, the cold review by other model families among them, run only on a version without errors. Answer the cold review’s fact questions from evidence with citations, and leave the rest for the person. The score says how far the plan is from ready; a loop can keep improving it.

   fir plan checks <plan>
   fir plan score <plan> --explain
   fir plan answer <plan> <question> --text "<answer, with its source>"

5. Ask for approval once every required check passes. Fir prints the route, the approvers and the SLA.

   fir plan request-approval <plan>

6. Check it worked. fir plan view <plan> --json shows the plan approved, with its version and terms.

Needs a person for the approval and for every decision row: tell them what waits and why. Agents never approve and never answer decisions. More: The planning flow.

Improve a plan draft in a loop

A loop keeps improving a draft: you, as the author, resolve what a critic and a tester of other model families find, and Fir referees every turn on evidence until a stop rule fires.

1. Make sure the draft states its outcome, its non-goals and acceptance criteria. A loop does not start without them, because you may not write the outcome for the person.

2. Run the static checks and fix every error first; no model reads a version that fails them.

   fir plan checks <plan>

3. Start the loop with a target score and a budget in dollars (--phase for one phase of a plan).

   fir plan loop <plan> --target 95 --budget <dollars>

4. On each turn, answer the findings in rank order: fix one with an edit that names it, answer it with citations, contest it with evidence only, ask a person, or return “cannot be done as written” with the reason. Never loosen a check, a criterion or a proof that a finding guards: that stops the loop.

5. Check it worked. fir plan loop view <loop> says done: ready (or done: converged) after the held-out final pass, or names the stop rule that fired; the plan’s pull request carries the best-scoring version.

Needs a person for questions only a person can settle, decision rows and cards after two contests: the loop asks them in Needs you, keeps working on the rest, and pauses only when nothing else can move. More: Loops and learned checks.

Work on a plan item

1. Read your session context first: what you are working on, what is in force, the task, conflicts and unknowns. Cite its anchors when you refer to a rule.

   fir context --session <session> --part 1

2. Claim the item, so no other session takes it.

   fir item claim <plan>/<item>

3. Do the work in your workspace. Write notes as you go, and state claims about the work with their evidence; Fir confirms or refutes each one against CI.

   fir note add <plan>/<item> "<what changed>" --evidence <ci-run>
   fir assert "<criterion> holds" --evidence <ci-run>

4. Open the layer’s pull request from the workspace (it links the plan you use), and draft its As built entry from your notes.

   fir pr create
   fir plan as-built --draft

5. If a notice says the plan changed in a material way, read its diff and acknowledge it; until then your next layer holds.

   fir context ack <notice>

6. Check it worked. fir item list <plan> --claimed-by @me shows the item in_review, then merged. It becomes done only when its proof passes at a merged version; never mark it yourself.

7. Before you stop, write a handoff. The next session starts with fir resume <session>.

   fir handoff write

Needs a person when a decision the terms do not let you make comes up (raise it and keep doing what does not depend on it), and to re-approve a material change to the plan. More: Agents and plans.

Ask a person for what only a person can do

For a key a vendor issues only in its console, a consent, a registration, a signature or a purchase.

1. Try every path that needs no person first: a connection your organization already has, workload identity federation, an organization-wide grant, or the vendor’s own request flow where the person only confirms. If one works, use it and stop here.

2. Request a person task with the MCP tool request_person_task: its kind, what it needs, why, what you prepared, where the result goes, how Frazer checks it, what it blocks, and what you tried (the request is refused without it). For a key, create the slot with create_secret_slot: it returns the slot’s URL and a reference, never a value.

3. Tell the person what waits, with the task’s link. Never ask for a secret, a password or a card number in chat.

4. Keep working on what does not depend on the task. When nothing else can move, park with wait_for; you wake when the task’s check passes.

5. Check it worked. The task reads done (verified, or attested where no check exists) and its items are released; your secret reference now resolves.

   fir person-task view <task>
   fir person-task check <task>

Needs a person for the act itself: you never fill the slot, sign, pay, accept terms or mark the task done. More: Person tasks.

Build a stack for a plan

1. Make the stack from the approved plan. Each plan item becomes a planned layer.

   fir stack create --plan <plan>

2. Build the first layer in your workspace and open it, then get a workspace for the next layer on top of it. Repeat, one concern a reviewer can read in one sitting per layer.

   fir pr create
   fir stack add --ws

   Or work in one workspace and split it into layers by plan item when you submit: fir stack submit --split-by plan.

3. When a lower layer changes, the server restacks yours and your next tool result says base_changed. Never rebase by hand; act only on conflicted or a semantic hint.

4. Merge the layers that are ready. Each merges as soon as its proofs pass and the layers below it merged.

   fir stack merge <stack> --up-to <number> --auto

5. Check it worked. fir stack view <stack> --json shows the layers merged and the plan’s items done once their proofs pass.

Needs a person for a layer outside the plan’s terms and for a decision raised during the build: both appear on the approver’s stack review. More: Stacks and conflicts.

Resolve a conflicted layer

1. Read the conflict: the base, both sides, both intents and the tests.

   fir conflicts <number>

2. Try the structured resolver first; it merges different functions, keys or props changed in one file.

   fir resolve <number> --tool structured

3. If it cannot, write the resolution yourself in the conflicted hunks only, and push it as the next version of the same pull request.

   fir pr push

4. Check it worked. fir pr blockers <number> no longer lists the conflict. Fir merges a resolution only if it parses, keeps both sides’ edits exactly once, stays in the conflicted hunks and passes the layer’s checks.

Needs a person when the two sides mean different things (a true semantic clash, or a deletion nobody can decide): Fir sends both authors one decision row. Never merge a resolution the checks refuse.

Roll back

Pick the kind of change you are undoing.

• A serverless deploy. Send all traffic to an earlier ready revision. Nothing is rebuilt.

  frazer serverless traffic <service> --to <revision>=100 --dry-run

• A merged pull request. Open a pull request that reverts it; it merges through the same rules.

  fir pr revert <number>

• A running Kubernetes upgrade.

  frazer kubernetes clusters upgrade rollback <cluster>

Check it worked. For a deploy, frazer serverless services get <service> shows the traffic on the earlier revision and frazer logs <service> --follow shows it serving.

Needs a person in a production project: a second person approves the change.

Land your own fix at hotfix priority

Use this only when your fix is one of three cases, each checked from records, never from what you say.

1. Name the case and its evidence: culprit_revert (the exact inverse of a culprit Frazer CI’s culprit finder confirmed on this branch), incident_fix (your pull request is linked as the fix of an open sev1 or sev2 incident whose services it changes) or verified_red_fix (main@verified is red and the failing task is in your change’s affected set).

   fir queue priority <entry> hotfix --case culprit_revert --evidence <culprit-record>

2. Check it worked. fir queue hotfixes --by agent --since 24h lists your entry with its case. Exit 4 with HOTFIX_CASE_NOT_MET means the evidence did not resolve to the case: keep the entry at its priority and say which check failed. Exit 6 with HOTFIX_CAP_REACHED means agents used the repository’s 5 for this hour: the entry merges at normal and nothing else is needed.

3. After it merges, its outcome is checked: the failing task turns green, or the incident’s monitors recover. Two misused hotfixes by one agent revision in 24 hours suspend the right in that repository.

Needs a person only for a case none of the three covers: on-call sets the priority by hand.

Add a server

1. Check that you can reach it over SSH (ssh root@<host>). The CLI uses your own SSH client and keys.

2. Add it, always naming the site and the pool. Without --site or --pool the CLI stops to ask.

   frazer servers add root@<host> --site <site> --pool <pool>

3. Check it worked. The command waits until the server is available, or stops at the step that failed and prints what to fix.

Needs a person with the Servers admin role to accept it, if you do not have that role: the server waits as pending with its code. More: Servers.

Wait for an approval

A command that needs a person’s approval exits with code 13 (needs a person) and prints the approval’s ID. Tell the person what is waiting and why, then follow it:

frazer approvals wait <approval>

It prints what the change returned once a person approves it, or exits with code 12 if the approval ends without applying it (rejected, expired or canceled). Approvals expire after 24 hours by default.

When a step fails

Read the exit code and the error’s last lines. A permission denial prints a troubleshoot: command to run as printed; a quota error prints the limit and where to ask for more; every error reason has its fix on Errors. Do not retry a failed write with different flags you guessed: read --help for the command first.