re:wagon

wagon /ˈwaɡən/

noun

A piece of code that works as intended despite being poorly written, messily structured, and needlessly difficult to maintain.

General

Every time I booted up a fresh session with an agent, I felt like I was starting the task with a completely new junior developer. I was having to review everything it did and constantly tell it to not do this, or to do that instead. I've spent more time doing this than I care to admit.

It made me genuinely angry to keep correcting my agents on what to do/not to do because I absolutely fucking hate reviewing code. And then I realised this was my fault. I was doing this to myself.

I was telling this poor agent over and over to fix the same repeated failures, torturing us both, but I wasn't actually recording these anywhere. I wasn't letting it "learn" from its mistakes.

This is when I decided to create re:wagon. It's my response to the constant wagonry that these agents keep writing.

re:wagon gives you the ability to create an ever expanding rule-set for agents to reference when performing tasks. With the aim to make agents start coding as if it were you writing the code yourself.

Installation

Create your rules repository

Start with thedanielgoodwin/rewagon-example. Fork it into your GitHub account, or clone it and push a copy to a new GitHub repository that you own.

To clone the example:

git clone https://github.com/thedanielgoodwin/rewagon-example.git
cd rewagon-example

If you clone it, change the origin remote to your new repository before you push. Edit the rules to suit your projects. Use your own repository for the GitHub token and GITHUB_REPOSITORY settings below.

GitHub token

Create a fine-grained personal access token for your documentation repository. Use these settings:

| Setting | Value | | --- | --- | | Token name | rewagon | | Expiration | Choose an expiry date. Replace the token before it expires. | | Resource owner | The user or organization that owns your documentation repository. | | Repository access | Only select repositories, then select only your documentation repository. | | Repository permissions: Contents | Read and write to read rules, create branches, and save proposed rules. | | Repository permissions: Pull requests | Read and write to open rule proposals. | | Repository permissions: Metadata | Read-only (GitHub adds this automatically). |

Leave all other permissions unset. If your organization requires token approval, an administrator must approve it before use. See the GitHub token guide.

Click Generate token. Copy the token into GITHUB_TOKEN in your client configuration below. Set GITHUB_REPOSITORY to the same documentation repository, in owner/repository format.

Agent instructions

Copy the following block. Then go to your client setup below to add it to the correct global instructions file or setting and configure the MCP server. Complete both steps so that the agent can use re:wagon in all projects.

If the instructions file does not exist, create it and its parent folder. If it exists, append the block. In the paths below, ~ means your home folder.

This step tells the agent to use re:wagon before it starts project work. The MCP server configuration makes the tools available, but does not tell the agent when to use them.

## Using re:wagon

Before writing or modifying code:

1. Call the `rewagon` MCP tool `list_rules` to discover available language and framework rules.
2. Identify which rules apply to the current project.
3. Call `get_rules` with the applicable rule names. If none apply, call `get_rules` without parameters to retrieve the core rules.
4. Read and follow the returned rules before making code changes.

Always call `get_rules` when writing or modifying code. You may skip the `rewagon` MCP for tasks that do not involve code changes.

After context compaction, call `list_rules` and `get_rules` again to reload the applicable rules before resuming work.

## Learning from corrections

If the user corrects your work or requests an adjustment that could be useful as a future rule:

1. Propose the rule to the user.
2. Wait for explicit approval.
3. Call `add_rule` only after the user approves the proposed rule.

Codex

Add the agent instructions to ~/.codex/AGENTS.md. If you set CODEX_HOME, use AGENTS.md in that folder. If you use AGENTS.override.md in that folder, add the block there instead. See the Codex instructions guide.

Add the following to ~/.codex/config.toml:

[mcp_servers.rewagon]
command = "npx"
args = ["-y", "rewagon@latest"]

[mcp_servers.rewagon.env]
GITHUB_REPOSITORY = "YOUR_USERNAME/YOUR_RULES_REPOSITORY"
GITHUB_TOKEN = "..."

Set GITHUB_REPOSITORY to the GitHub repository that contains your rules. Replace ... with your fine-grained GitHub token.

Use the same repository and token settings in the examples below. If a configuration file already contains servers, add the rewagon entry to the existing server object.

Claude Code

Add the agent instructions to ~/.claude/CLAUDE.md. This file applies to all projects. See the Claude Code instructions guide.

Run the following command to add re:wagon for all your projects. See the Claude Code MCP documentation.

claude mcp add --env GITHUB_REPOSITORY=YOUR_USERNAME/YOUR_RULES_REPOSITORY --env GITHUB_TOKEN=... --scope user --transport stdio rewagon -- npx -y rewagon@latest

Run /mcp in Claude Code to check the server status.

Claude Desktop

For chat, open Settings > Instructions for Claude and paste the agent instructions. Claude Desktop stores these account instructions in settings. See the Claude instructions guide.

Open Settings > Developer > Edit Config to edit claude_desktop_config.json. See the local MCP server guide.

Add the following configuration:

{
  "mcpServers": {
    "rewagon": {
      "command": "npx",
      "args": ["-y", "rewagon@latest"],
      "env": {
        "GITHUB_REPOSITORY": "YOUR_USERNAME/YOUR_RULES_REPOSITORY",
        "GITHUB_TOKEN": "..."
      }
    }
  }
}

Save the file, then fully quit and restart Claude Desktop.

Cursor

Create ~/.cursor/rules/rewagon.mdc for global instructions on this machine. Add the following at the top of the file, then paste the agent instructions below it:

---
alwaysApply: true
---

You can also paste the block into Cursor Settings > Rules > User Rules to sync it across machines. See the Cursor rules guide.

Add the following to ~/.cursor/mcp.json to use re:wagon in all your projects. See the Cursor MCP documentation.

{
  "mcpServers": {
    "rewagon": {
      "command": "npx",
      "args": ["-y", "rewagon@latest"],
      "env": {
        "GITHUB_REPOSITORY": "YOUR_USERNAME/YOUR_RULES_REPOSITORY",
        "GITHUB_TOKEN": "..."
      }
    }
  }
}

Save the file, then restart Cursor.

Documentation repository

Store your rules as markdown files in a separate GitHub repository. Set GITHUB_REPOSITORY to its owner/repository name. re:wagon reads the rules from the default branch.

Use rewagon-example to create your own rules repository. Organize your rules with this structure:

core/
  writing.md
  comments.md
frameworks/
  laravel/
    routing.md
languages/
  typescript/
    control-flow.md

For example, core/writing.md can contain this rule:

**Use Simplified Technical English.** Always use ASD-STE100 Simplified Technical English when talking or documenting things.

Rule structure

• Put rules that apply to all projects in core/. These rules are always included.
• Put language rules in languages/<language>/, for example languages/typescript/control-flow.md.
• Put framework rules in frameworks/<framework>/, for example frameworks/laravel/routing.md.

Use lowercase names for language and framework folders. Group related rules in topic files such as writing.md, comments.md, and testing.md. Reuse a suitable topic, or create one when none fits. A topic file can start with one rule. Use a bold instruction followed by a short explanation when needed. re:wagon generates headings from file names, so you do not need to repeat the topic heading inside the file. re:wagon also reads markdown files in subfolders.

Call list_rules to get core slugs and maps of language and framework names to their existing slugs:

{
  "core": ["comments", "writing"],
  "languages": { "typescript": ["control-flow"] },
  "frameworks": { "laravel": ["routing"] }
}

Slugs omit .md and list files directly inside each rule folder. Nested files are included by get_rules, but cannot be selected by add_rule.

Then call get_rules with arrays of the names that apply to the project. Use an array even for one name. For example, a project with a frontend and backend can request:

{
  "language": ["typescript", "python"],
  "framework": ["react", "django"]
}

re:wagon includes core rules first, then language rules, then framework rules. Each category follows the requested order. Names are trimmed and converted to lowercase, and duplicate names are included once per category. Unknown names are skipped. Omit both parameters or supply empty arrays to get only the core rules.

Add rules

You can edit the markdown files in the repository, or ask the agent to use add_rule. This tool opens a pull request for review. It adds the rule to an existing file or creates the file if it does not exist.

Each call proposes one rule. Supply both instruction with the rule in one imperative sentence and slug with the topic file name. Write the instruction as plain text on one line; the tool adds bold formatting. Add an optional explanation to explain why the rule matters, when it applies, or its exceptions. Omit it when the instruction is sufficient. Do not repeat the instruction or put code examples in these text fields.

Set language or framework to select a rule folder, or omit both to use core/. The slug is required and has no default. Use a suitable existing slug from list_rules in the selected folder or choose a new topic name, without .md or a path. For example, language: "typescript" and slug: "comments" select languages/typescript/comments.md.

The tool uses instruction as the pull request title and explanation as its description. If explanation is omitted, the pull request uses a short description of the target file.

Include examples when concrete code makes the rule clearer. Each pair needs a bad sample that violates the rule and a corresponding good sample that corrects it. Keep the scenario the same so the relevant change is clear. Supply raw code without markdown fences. The optional language in each pair sets syntax highlighting and does not select the rule folder. The tool keeps code indentation and appends the pairs in order, with Bad/Good labels and code fences. Omit examples when they add no useful detail.

The tool renders each rule as a bold instruction, an optional explanation, and optional code examples. The former content, title, and description parameters are no longer accepted. Use instruction and explanation for both the rule text and pull request. There are no separate pull request fields. Existing rule files need no changes.

For example, call add_rule with:

{
  "instruction": "Use specific variable names.",
  "explanation": "Choose names that explain what a value means.",
  "language": "typescript",
  "slug": "naming",
  "examples": [
    {
      "bad": "const x = users.length;",
      "good": "const userCount = users.length;",
      "language": "typescript"
    }
  ]
}

This appends the following markdown to languages/typescript/naming.md:

**Use specific variable names.** Choose names that explain what a value means.

**Bad**

```typescript
const x = users.length;
```

**Good**

```typescript
const userCount = users.length;
```