Chapter 8 of 15

Teaching the Project

Every new thread starts the same way: the agent knows nothing about Freddy's project except what it can read. He has typed the same three sentences into six threads. This chapter is where they go instead.

The problem

An agent begins each task cold. It does not know that tests run with a particular command, that a folder is generated and must not be edited, or that your team prefers one pattern over another. You find out when it breaks the convention, correct it, and it is correct for the rest of that conversation. The next thread starts from zero.

The hard way

Paste the same paragraph at the top of every task. Or keep an instructions file that one agent happens to read, and discover that the other agents you use ignore it. The instructions drift, because they live in your clipboard.

The Context tab

The Context tab in the tools panel (⇧⌘I) collects everything around the active thread. Some of it belongs to one thread, and some to the whole project; the difference is the point of this chapter.

What belongs to one thread

  • Notes: a notepad for the thread, saved as you type. The agent does not see it. It is for you: the thing you must remember to check, the link you will need later.
  • Recap: Generate asks the agent for a short summary of the conversation: the goal, what is done, decisions made and what is left. Refresh writes a new one. The recap is saved with the thread and used when you hand the thread off to another provider (chapter 6), so it is worth refreshing before you do.
  • Pinned messages: hover a message in the conversation and press the pin. Pinned messages are listed here, so important answers are easy to find. Unpin them here or in the conversation.

Project instructions

Instructions that every agent in the project gets, in addition to its normal system prompt: conventions, commands to run, or things to avoid. They apply from the next message, in every thread of the project. Claude Code, Codex, Elyra and Pi support this. ACP agents do not take extra instructions.

Freddy writes three lines: the command that runs his tests, that src/generated is not edited by hand, and that he wants small commits. They are now the first thing every agent in freddy-notes is told, and he has stopped typing them.

Rules agents learn

You do not have to write all of that in advance. When you correct an agent (“no, we always validate with Form Requests”), it can propose that as a rule: a card in the thread with the rule and what taught it.

  • Add to AGENTS.md puts it under Learned rules in the repository's AGENTS.md (or CLAUDE.md, when that is what the project has), so every agent and your team get it. Commit it with your changes.
  • Add to project instructions keeps it in Workspace only.
  • Dismiss drops it.

The choice between the first two is a choice about who the rule is for. A convention the whole team follows belongs in the repository. A preference of your own belongs in Workspace.

One setup for every agent

Claude Code reads a project's .mcp.json and its skills itself. Workspace gives them to the other agents (Codex, Elyra, Pi and ACP agents) too, so switching agents keeps the same tools.

  • MCP servers in .mcp.json, in Claude Code's format: command, args, env, or url and headers. ${VAR} and ${VAR:-default} are filled in from the environment.
  • Skills in .claude/skills/<name>/SKILL.md and .agents/skills/…, in the project and in your home folder. The other agents get a list of them (name, description, path) and read a skill's SKILL.md when a task matches it. ACP agents do not take extra instructions, so they do not get the list.
This is a trust decision, and Workspace makes you take it. The .mcp.json file comes with the repository, and its commands run on your Mac. So they are only passed on after you press Allow for every agent. If the file changes, allow it again. Stop sharing takes it back, and agents get the change from their next message. Read a repository's .mcp.json before you allow it; you are agreeing to run what it says.

Local servers

Development servers running from the thread's folder, for example npm run dev in the terminal or a server the agent started. Each one is listed with its port and process. Click the address to open it in the thread's browser (chapter 10), or press the refresh button to look again.

Grove

When Elyra Grove runs the project as an app (Laravel, PHP or a proxied dev server, not a folder it only parks), a Grove box shows its address, such as https://shop.test, which opens in the thread's browser; whether grove dev runs the app's dev processes (Vite, queue worker…), with Start and Stop; and how many mails Grove has caught, when there are any. Workspace asks the grove command line, from your PATH or ~/.grove/bin. Without Grove, nothing changes.

Try it: write three lines of project instructions, then start a new thread and ask the agent what it has been told about the project. Correct it once on something small, and when the rule card appears, choose Add to project instructions.

What you learned

  • What belongs to one thread (notes, recap, pinned messages) and what belongs to the project
  • That the agent does not see your notes
  • How project instructions work, and which agents support them
  • How a correction becomes a rule, and the difference between AGENTS.md and project instructions
  • How .mcp.json and skills are shared with every agent, and why you must allow it first
Next: in Chapter 9 you give an agent a goal, a budget, and a check command, so that done means green.