Skip to main content
An instruction is an agent’s own standing guidance, kept in its AGENT.md. A rule is a named piece of standing guidance at workspace, project or agent scope. Pinework reads both each time a run starts.

​
Standing guidance lives in five places

Only people can write workspace rules. An agent can write its own agent rules. An agent’s change to a project rule waits for your approval.

​
Instructions say who the agent is

Each agent has one instructions document. It says what the agent does and how. An empty one gives the agent a single line built from its name, role and description. An agent can edit its own instructions without approval. Its edit to another agent’s instructions waits for your approval. Every save lands in the agent’s history. agent revert puts back what one history entry changed.
An agent’s save must pass --base with the hash that agent identity printed. The save fails if the instructions changed after the agent read them.

​
Rules add up and nothing overrides

All scopes apply together. Pinework never merges or overrides rules by name. It lists them in one block: workspace rules, then project rules, then agent rules. Older rules come first within each scope. The agent sees each rule’s content, not its name. You can turn a workspace rule off for one agent. Open the rule’s menu in the agent’s Instructions section and choose Disable for this agent. Project and agent rules have no off switch. You delete them instead.
A task with no project gets no project rules. A conversation with no project gets none either. Workspace and agent rules still apply. Pinework does not trim rules to fit. Each rule costs tokens on each run it reaches, so keep rules short.

​
Guidance reaches the run through the harness

When a run starts, Pinework reads the workspace context, rules and instructions again. It hands them to the harness through the harness’s own instruction channel. Claude Code gets them as an appended system prompt. Codex gets them as developer instructions. Cursor gets an always-on rule file. OpenCode gets an instructions file. On a device, Cursor and OpenCode get the rules inside the prompt instead. The prompt then adds wiki and file references. Pinework marks those as reference, not instructions. The message that woke the agent comes last.

​
Changes apply from the next run

A change reaches the next run. A run already going keeps what it started with. A message you send into a live run does not reload the rules.

​
Imported files and learnings are not live rules

Import copies your CLAUDE.md and AGENTS.md into workspace rules once. Later edits to those files do not sync. Approving a learning does not create a rule. It creates a task to write the learning into the wiki. The wiki then reaches runs as reference, not as instructions.

Import

Bring your CLAUDE.md and AGENTS.md in as workspace rules.

Agents

Where instructions sit among an agent’s settings.

Wiki and learnings

How reference knowledge reaches a run.

Plugins and skills

Skills travel to a run separately from rules.