Craftspace agent setups

Connects your coding agents to your team's Craftspace company brain (shared Pages, Skills, and Decisions over MCP) and makes sure decisions and learnings actually get written back.

A bare MCP connection is advisory: agents routinely finish a session having made a real decision without ever recording it. Two shared hooks fix that:

• SessionStart primes the read-first / write-back rules directly into context (not a truncatable server string).
• Stop blocks the end of a substantive session that recorded nothing and tells the model to record the decision (upsert_decision), note (upsert_page), or procedure (upsert_skill) — or explicitly decline. Nudges once, fails open, and understands both the Claude Code and Codex transcript formats.

Claude Code

Install once, and it keeps itself up to date. Two one-time steps:

1. Register the marketplace with auto-update on. Add this to your ~/.claude/settings.json (create the file if it does not exist, and merge into extraKnownMarketplaces if you already have one):

{
  "extraKnownMarketplaces": {
    "craftspace": {
      "source": { "source": "github", "repo": "abuaboud/craftspace-plugin" },
      "autoUpdate": true
    }
  }
}

"autoUpdate": true is the load-bearing part. Third-party marketplaces default to auto-update off, so installing without this line leaves you frozen on whatever commit you installed and you never get another update. With it, Claude Code pulls the latest commit at startup on its own.

2. Install the plugin.

claude plugin install craftspace@craftspace

This installs the house rules, the /grill-me skill, and both hooks. It carries no MCP server of its own, on purpose: the plugin is global, so a bundled server could not know which org a given repo means, and one shared /mcp would resolve to whichever org your stored credential last got pinned to — silently cross-writing the moment you belong to more than one org. The org lives in the project instead.

3. Connect a repo to its brain. Run this from the repo you want connected (once per repo):

claude mcp add --transport http --scope project craftspace-<org-slug> https://craftspace.app/mcp/<org-slug>

--scope project writes the server into that repo's .mcp.json, and putting <org-slug> in both the server name and the URL keeps every project pinned to its own org — a second org in another repo can't overwrite it. Your slug is the one in the app URL, /o/<org-slug>. Your browser opens to sign in the first time; after that /mcp shows craftspace- connected.

Installing the plugin is one time; connecting is once per repo. The plugin tracks its git HEAD (no pinned version), so every new commit reaches you at your next Claude Code startup with no further action.

Codex

Merge setups/codex/config.example.toml into ~/.codex/config.toml and setups/codex/hooks.json into ~/.codex/hooks.json (replace the path placeholder with your checkout path). Codex speaks HTTP MCP with OAuth (codex mcp login craftspace) or a cst_ member-token header.

Cursor

Drop setups/cursor/mcp.json and setups/cursor/hooks.json into ~/.cursor/. Unverified — Cursor is GUI-only with no headless CLI, so it isn't covered by the test harness.

Claude.ai / Desktop

Add https://craftspace.app/mcp/<org-slug> as a custom connector (your slug is the one in the app URL, /o/<org-slug>; a bare /mcp is refused for accounts in more than one org). There's no client hook surface, so write-back rides the server's own nudge.

Testing

setups/run-setup-tests.mjs drives each installed CLI (Claude Code, Codex) through a decision task and a page task and asserts the record landed. See setups/README.md.

Releasing

The plugin carries no version field, so Claude Code resolves it to the current git commit. Every commit pushed to the default branch is immediately live for everyone who installed with autoUpdate: true — push equals ship, there is no version to bump. Keep the default branch always-shippable: do risky work on a branch and merge only when it is safe to distribute. There is no per-teammate rollback; the recovery path is a forward-fixing commit.

Nothing here is secret: just the public MCP endpoint and small hook scripts. The source of truth is the Craftspace monorepo; this repo is the published mirror.