Codeman: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Deep implementation detail lives in docs/architecture-invariants.md. This file holds the rules that prevent mistakes; that file holds the mechanisms, file inventories, and the history behind each rule. Pointers below are written as → architecture-invariants#anchor. When the goal is raw throughput, docs/SPEEDRUN.md is the fast-execution protocol (it removes ceremony, never the safety rules here). The user-facing manual is docs/wiki/ (mirrored to the GitHub wiki by CI; see the CI note under Additional Commands), and AGENTS.md deliberately just points here.

This file is in .prettierignore on purpose. Prettier's markdown printer escapes underscores inside the glob-heavy paths used throughout (agent-*.jsonl became agent-\_.jsonl, collapsing backtick spans and corrupting a whole paragraph). Do not remove the ignore entry, and do not run prettier --write on it.

Repo root is kept short on purpose (the README sits below the file listing on GitHub). Config lives in config/ (eslint.config.js, knip.json, the vitest configs), Prettier's config is the "prettier" key in package.json, and SECURITY.md is under .github/. Root-only files are the ones tools genuinely require there: CLAUDE.md + AGENTS.md (loaded from the root by Claude Code / Codex), CHANGELOG.md (changesets writes it next to package.json), tsconfig.json, .editorconfig, .nvmrc/.npmrc, .prettierignore (resolved relative to cwd), vitest.config.ts (a one-line re-export of config/vitest.ci.config.ts: vitest finds its config by walking up from cwd, so without it a bare npx vitest ran with no setup file and wrote into the real ~/.codeman, #640), LICENSE (GitHub detection), .dockerignore (the build context is the repo root, so Docker resolves it there and nowhere else) and install.sh (its raw URL is the published install one-liner). .claude-plugin/marketplace.json is root-only for the same reason: /plugin marketplace add Ark0N/Codeman reads it from the repo root and nowhere else, which makes the repo its own plugin marketplace. The one plugin it lists is plugins/codeman/ (manifest + README + a MIRROR of skills/codeman/), and ⚠️ the plugin is a small separate directory on purpose: claude plugin install copies the plugin root into its cache, and a plugin root that carries a package.json gets an npm install at install time (measured with the repo root as plugin root: 832 MB, 511 packages and this repo's postinstall on every installer's machine), while a symlink to skills/codeman would dangle in the copy. skills/codeman/ stays the single source; scripts/sync-plugin.mjs mirrors it and writes package.json's version into both manifests inside version-packages, and test/plugin-manifest.test.ts pins the byte-identity, the versions, the absence of a package.json in the plugin root and that no other component (commands/, agents/, hooks/, .mcp.json, settings.json) rides along. npm run check:plugin runs that drift check plus both strict validations with EXPLICIT paths (plugins/codeman, .claude-plugin/marketplace.json): a bare . argument copied out of prose reads as a full stop and gets dropped, which surfaces as missing required argument 'path'. Needs the claude CLI, so it is a local check, not a CI step. Don't relocate those.