# GUIDE: how to use the orchestrator
Version 1.1. Read it once, end to end. It takes about ten minutes.

## 1. What this file does to your agent (read before installing)

`CLAUDE.md` is an instruction file. Your agent reads it on its own every time you start a session in the folder that holds it, and in any folder below that one. You do not paste it anywhere. That is also the risk: a folder with this file changes how every session started there behaves, even months later when you have forgotten it is there.

- **It applies to:** every session you start in this folder or in a folder inside it. Claude Code also loads instruction files from the folders above the one you start in, so do not put this file in your home folder unless you want it everywhere.
- **How to tell it is active:** start a session and type `good morning`. An active orchestrator either starts the interview or answers with a plan of at most 10 lines built from `CONTEXT.md`. In Claude Code, the `/memory` command also lists the instruction files that are loaded.
- **How to turn it off:** start your agent in a different folder, or rename the file (for example to `CLAUDE.off.md`). Nothing else is installed, so nothing else needs removing.

## Before you start / What you need

- **An AI coding agent** (required): Claude Code (https://code.claude.com/docs/en/setup), Codex CLI (https://developers.openai.com/codex/cli) or Cursor (https://cursor.com/docs), signed in with your own account. Nothing else needs an account.
- **Sub-agents** (optional): built into Claude Code, https://code.claude.com/docs/en/sub-agents. Without them the orchestrator does the work itself, slower.
- **WSL or Git Bash** (Windows only): https://learn.microsoft.com/windows/wsl/install or https://git-scm.com/downloads/win, to run the install commands below.

The orchestrator asks for everything about your business in the first-run interview. You do not prepare anything else.

## 2. Install in three steps

You need a coding agent that reads a markdown instruction file from the working folder. Claude Code reads `CLAUDE.md`. Codex and Cursor read `AGENTS.md`.

Step 1. Create a folder and go into it:
```
mkdir -p ~/orchestrator && cd ~/orchestrator
```

Step 2. Copy two files from this pack into the folder, and rename the context template:
```
cp /path/to/pack/CLAUDE.md ./CLAUDE.md
cp /path/to/pack/CONTEXT.template.md ./CONTEXT.md
```
For Codex or Cursor, name the first file `AGENTS.md` instead of `CLAUDE.md`. The line `@CONTEXT.md` is an import in Claude Code; other tools ignore it, and the file itself tells the agent to read `CONTEXT.md` at the start of each session.

Step 3. Start the agent in this folder and say hello:
```
cd ~/orchestrator && claude
```
Type `good morning`. The agent starts the interview: 12 questions, one at a time. Answer the way you would answer a colleague. "I don't know yet" is a good answer. At the end the agent shows the filled-in `CONTEXT.md` and asks what to fix.

The first time, your agent asks permission before it writes the file. That is normal: a well-configured agent never writes a file silently. Approve writes for this folder.

On Windows, run these commands in Git Bash or WSL.

From now on, always start the agent from the same folder.

## 3. How to talk to it

The agent is a very good employee who needs a manager. It is not an oracle. Three habits change the results:

**Say what should exist at the end, not what it should do.** "I want 3 versions of the product description for X to choose from, each under 80 words" instead of "help me with the description".

**Say how you will know it is good.** "Good means: the price is visible in the first sentence, and the word 'revolutionary' appears nowhere."

**Do not give up after the first weak answer.** Say in one sentence what is wrong. The second answer is usually the right one. Most failures are failures of the request, not of the model.

`CLAUDE.md` tells the agent to restate your task in one sentence first. If the restatement is wrong, correct it immediately. It is the cheapest moment to fix a misunderstanding.

## 4. Steering delegation and verification

The orchestrator hands work to sub-agents on its own (cheaper models execute, the strongest judges) and verifies it on its own. You do not need to ask. You can still steer:

- "Split this up and run the parts in parallel" when a task has independent pieces (for example, research on three competitors).
- "Have a separate agent check this before you show me" when the result goes to a customer.
- "Use a stronger model" when the result is flat. The agent should do this anyway; you can speed it up.
- "Show me the evidence" when a report says "done". Evidence is a file, a number or a link, not the sentence "I did it".

## 5. The daily loop

Two commands replace a whole planning routine:

`good morning` → a plan for the day in 10 lines: the goal, 1 to 3 things for today, open items, and one question if something is blocked.

`end of day` → a report: what was planned, what got done with evidence, what did not and why, what is new, which decisions are waiting. At the end the agent asks whether anything in your business changed. Answer it. That is how `CONTEXT.md` stays current.

Five minutes in the morning, five in the evening, on every working day.

## 6. Ten requests: weak and strong

| # | Weak | Strong |
|---|---|---|
| 1 | "Help me grow the shop" | "Ad traffic brings a steady trickle of orders. I want a plan to double it in 60 days. Start with the questions you need answered" |
| 2 | "Write a post" | "A social post about the new colour of product X. Under 60 words, no emoji, tone as in CONTEXT. Show 3 versions" |
| 3 | "What do you think of my price?" | "My price sits in the middle of the range my competitors charge. Check 3 competitors and tell me whether to change it. Give sources" |
| 4 | "Do some research" | "Find 5 shops in my country selling X. For each: price, number of products, where their traffic comes from. A table" |
| 5 | "Fix this text" | "Cut this text in half, keep the price and the delivery time. Do not change the tone" |
| 6 | "Sort out my tasks" | "Here are my tasks. Split them into: today, this week, never. Justify each 'never' in one sentence" |
| 7 | "Send this email to customers" | "Prepare an email to the customers who bought X. Show it to me. I send it" |
| 8 | "Delete old files" | "Find the files in this folder older than a year and move them to an archive folder. Show me the list before you touch anything" |
| 9 | "What is my best product?" | "Here is a three-month sales export (CSV). Which product has the highest margin times units sold? Show the calculation" |
| 10 | "Make me an ad" | "An ad for X. Research first: what 3 competitors do. Then 5 hooks. I pick one, you write the full version" |

The pattern: **the result + the constraints + how to tell it is good + who decides**.

## 7. When you get stuck

- The agent guesses instead of asking → write: "Do not guess. Write 'no data' and ask." It is already in `CLAUDE.md`, and the reminder helps.
- The agent writes walls of text → "Report in 10 lines. The rest goes to a file."
- The agent forgot who you are → check that you started it in the right folder. To redo the interview, put the line `STATUS: not filled in` back into `CONTEXT.md` and type `good morning`.
- The agent did something you did not want → say what went wrong, and add it to the "NEVER do without asking" section of `CONTEXT.md`.
- A new session does not remember the last one → that is normal. `CONTEXT.md` is the memory. Everything important belongs there; `end of day` does it for you.
- A long conversation starts to lose the thread → type `end of day`, clear the conversation, then `good morning`. The context comes back from the file.
- The sub-agent feature does not work in your installation → the agent says so once and does the work itself with the same loop. Slower, but it works.

## 8. How to extend it

Work with it unchanged for a month first. Then:

1. **Add to `CONTEXT.md`** everything the agent should always know: new products, new rules, new accounts. It is the most important file.
2. **Add your own files to the folder**: a price list, product descriptions, examples of text that sounds like you. The agent can see them. Mention each one in `CONTEXT.md` in one sentence.
3. **Add your own rules to `CLAUDE.md`** in section 3 when you catch yourself giving the same instruction a third time. Keep each short: what to do, why, and when not to.
4. Only after that, if you feel something is missing: your own sub-agents, custom commands, automations. Do not start there. Start with the context file.

Note for Claude Code: a personal instruction file in your user folder loads together with the one in this folder, not instead of it. Keep only rules that should apply to every project there.

## 9. Safety barriers

Without your "yes", the agent NEVER spends money, publishes, deletes, does anything irreversible, invents facts, or saves passwords.

Your side of the deal: do not paste passwords or access keys into the conversation. Read what the agent shows you before you say "yes". "Yes" to one expense is not "yes" to the next. If the agent does anything on this list without asking, that is a bug: add the case to `CONTEXT.md` and start a new session.