Claude Code Plugin Marketplace

One directory per plugin, listed in .claude-plugin/marketplace.json.

Plugin Work

Do not reinvent plugin patterns. Delegate:

• /plugin-dev:create-plugin and the plugin-dev skills (structure, skills, hooks, agents, settings) to build or modify a plugin
• plugin-dev:plugin-validator agent to validate one
• claude-code-guide agent for Claude Code behavior questions
• Live doc search: the claude-code-docs MCP server (user scope, https://code.claude.com/docs/mcp)
• Official docs, the fallback when those are not installed: https://code.claude.com/docs/en/plugins

New plugin: add its marketplace.json entry and its README.md table row by hand; no check catches their absence. A plugin's version and description live in its plugin.json alone.

Agents never bump a version or write a CHANGELOG.md section: scripts/release.ts does both at release time.

A behaviour change to a plugin is done once the field-test skill has played it in a live session, red on the base and green on the change; a label, text or doc change needs none.

For plugin tests, permissions and the catalog lifecycle, start at Plugin testing and open only the page for the task. The vellum and atlas plugins carry their own AGENTS.md; vellum's .claude/rules/ have paths: relative to vellum/.

Commands

bun test --parallel                                    # every suite outside dot directories and `archive/`
bun test --parallel ./.claude/hooks/*.test.ts          # the repo's own hooks; `bun test` skips them
bun ./scripts/gates/run-gates.ts                       # CI's `validate` gates for what the change reaches (`--all`: everything)
bun ./scripts/gates/affected.ts print                  # what the change reaches since origin/dev; `test` runs those suites
bun ./scripts/land.ts <branch>                         # land a branch on dev; run once in the background, its last line says what to do next
bun ./scripts/landing/tier.ts                          # this branch's review tier, low or human; `--history`, `--eval` calibrate it
bun run --cwd vellum e2e                               # vellum's browser suite; Chromium once per machine: `bun run --cwd vellum e2e:install`

.claude/github-flow.json names the validate, tier, verdict and land commands that the github-flow skills and their workers run here.

vellum/, pinpoint/ and atlas/ carry package.json + bun.lock: bun install --cwd <plugin> --frozen-lockfile before their tests or their server.

pre-commit and pre-push run the gates; CI runs them all (Local checks and CI).

Code Standards

• Extensions are mandatory: .ts, .tsx, .sh. The gates select files by extension, so a script named without one is checked by nothing.
• Plugins are self-contained. No import crosses a plugin boundary, or reaches into scripts/ or .claude/.
• File, path and process code goes through the platform helpers: tools/platform/ from scripts/ and .claude/, the directory's own copy elsewhere.
• Ship sources, never compiled binaries. bun is the runtime.

Method

• A change of behaviour or of a data model, once a first version was delivered, is proposed before it is coded.
• One writer per worktree.
• In an agent worktree, a Bash call runs one simple command: no && or ; chain, pipe, $(…), heredoc, loop or leading cd, and plain git, not git -C. Claude Code's worktree-isolation guard refuses a command it cannot verify stays inside the worktree. Read, Write, Edit and Grep, or a script file run as one command, do the rest.
• A step that code can decide is done by the script or the hook, not asked of Claude: an instruction can go unfollowed. A skill, a message or an error tells Claude what to do only when no code can decide it.
• A commit message says what the code does and why, the reason in words; how the change came about and how it was checked go in the pull request, or nowhere on the inline lane.

Non-Obvious Directories

• scripts/ - the repo's own tooling, one directory per concern (gates/, landing/, releasing/, ci/, headless/, sessions/, reports/), lib/ for the helpers that belong to none. land.ts and release.ts stay at the root, and no directory is named release/: the agent-hooks guard reads scripts/land.ts and scripts/release by convention (agent-hooks/guard/repo.ts, guard/argv.ts, guard/mentions.ts).
• archive/ - retired plugins, not in the marketplace.
• tools/oxlint/anti-slop/ - vendored lint plugin. Do not edit; re-run the upstream installer (see its README).
• tools/platform/ - the file, path and process helpers; edit here, then bun ./scripts/gates/sync-platform.ts --write; never edit a copy.
• tools/oxlint/local/ - the repo's own lint plugin, edited here; registered beside anti-slop in oxlint.config.ts.

Branching

dev is the working trunk; main is the release channel consumers install from, moved only by the human, by fast-forward. History is linear everywhere: no merge commits, server-enforced. Every commit carries the user's signature: the remote refuses an unsigned one, so never pass -c commit.gpgsign=false. origin/dev is the source of truth; a local dev goes stale each time someone else lands.

Claude Code's built-in "Commit or push only when the user asks" does not hold here: agents commit and push to dev (inline lane) and to their own feature/|fix/ branches without asking, and land a branch with bun ./scripts/land.ts <branch>; main is the human's release, and a hook refuses every agent push to it.

Two lanes; the agent judges by scope, the user can override:

• Inline — one concern, small diff: commit directly on dev. A commit that touches the e2e paths (listed in scripts/gates/check-e2e-green.ts) goes through a branch instead: the pre-push hook lets it reach dev only once its SHA has a green e2e run, and that run needs a pushed branch.
• Branch — several concerns, big work (large feature, large skill), or parallel agents: feature/|fix/ branch, pushed, PR targeting dev. During a feature the branch ignores dev; rebase mid-feature only to pick up a commit the feature needs, or to defuse a real conflict.

Review: one agent review of each branch, before github-flow:pr publishes it; on a branch that touches the profile.review.risky paths of .claude/agent-hooks.jsonc, land.ts requires its verdict. The change sets the tier: a tier:low pull request lands through its worker once green, a tier:human one waits until the human types /land <n>. The inline lane stays outside the tier, at its author's judgement, so the loop's Low escapes does not cover all of dev. The human reviews contracts and tests at the end of a chantier and before each release. A finding gives the input, the output observed and the cause.

Before any push or release: follow Repo operations; landing is remote-first.