From 328e30b6dedef2ec755acdab0145ccaea59a073f Mon Sep 17 00:00:00 2001 From: Xingyu Chen Date: Wed, 10 Jun 2026 18:57:51 -0700 Subject: [PATCH] README: unify install for Claude Code/Codex/Cursor (drop separate Codex section); rename first-build command generate -> init --- AGENTS.md | 2 +- README.md | 53 +++++++++++++++++++++++++---------------- SKILL.md | 8 +++---- reference/DATA_MODEL.md | 2 +- 4 files changed, 39 insertions(+), 26 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4e47c7a..3833ad2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,7 +6,7 @@ Claude Code skill, but the engine is tool-agnostic — **Codex, Cursor, Aider, o agent that can read instructions and spawn sub-tasks can drive it.** ## Read these first -- **`SKILL.md`** — the full workflow and the `generate / check / update / test / fix` +- **`SKILL.md`** — the full workflow and the `init / check / update / test / fix` commands. Follow it exactly. - **`reference/STANDARDS.md`** — the fixed scoring rubric, smell taxonomy (with per-language equivalents), severity levels, and the **exact per-module audit prompt**. diff --git a/README.md b/README.md index 2d7e302..f81c653 100644 --- a/README.md +++ b/README.md @@ -74,32 +74,56 @@ per-language form (e.g. `any-escape` = `as any` / `dynamic` / `void*` / `reinter ## Requirements - **Python 3** — standard library only. No `pip install`, no external packages. -- **An AI coding agent** to drive the audit/fix/test steps: **Claude Code** (native skill) - or **any agent that reads instructions and spawns sub-tasks**, e.g. OpenAI **Codex** - (see [Using with Codex](#using-with-codex--other-agents)). +- **An AI coding agent** to drive the audit/fix/test steps — **Claude Code**, **Codex**, + **Cursor**, or any agent that reads instructions and spawns sub-tasks (see Install). - A browser to open the generated HTML. That's it. ## Install -A Claude Code skill is just a folder under `~/.claude/skills/`: +codemap is one self-contained folder. Clone it once, then wire it into whichever agent you +use — the engine (Python scripts + the `SKILL.md` / `AGENTS.md` / `reference/STANDARDS.md` +workflow) is identical for all of them. + +**Claude Code** — skills live under `~/.claude/skills/`, so clone it straight there: ```bash git clone https://github.com/Asixa/codemap-skill ~/.claude/skills/codemap ``` -(Windows PowerShell: `git clone https://github.com/Asixa/codemap-skill $env:USERPROFILE\.claude\skills\codemap`.) +Restart Claude Code; it shows up as **`/codemap`**. -Restart Claude Code (or start a new session). The skill appears as **`/codemap`**. +**OpenAI Codex** — Codex auto-reads `AGENTS.md`. Clone the repo, then add one line to your +project's `AGENTS.md` (or `~/.codex/AGENTS.md`): + +```bash +git clone https://github.com/Asixa/codemap-skill ~/.codemap +``` +> For architecture maps / code audits, use the codemap tool at `~/.codemap` — follow its `AGENTS.md`. + +**Cursor** — clone it, then add a project rule at `.cursor/rules/codemap.mdc`: + +```bash +git clone https://github.com/Asixa/codemap-skill ~/.codemap +``` +> Use the codemap tool at `~/.codemap` for architecture maps / code audits — follow its `AGENTS.md`. + +**Any other agent** (Windsurf, Aider, Cline, …) or **by hand** — clone it anywhere and tell +the agent: *"Use the codemap tool at `~/.codemap`; follow its `SKILL.md`, and score each +module with a separate sub-task per `reference/STANDARDS.md`."* The deterministic scripts +(`scan` / `query` / `render` / `apply_audit`) also run standalone with no agent at all. + +> Windows PowerShell: replace `~` with `$env:USERPROFILE` (e.g. `$env:USERPROFILE\.claude\skills\codemap`). ## Usage -Talk to Claude in plain language, or use the subcommands. On the first run, codemap asks -your preferences (UI language, output location, project title) and saves them to +Talk to your agent in plain language, or use the subcommands (shown as Claude Code slash +commands — say the same verb to any other agent). On the first run, codemap asks your +preferences (UI language, output location, project title) and saves them to `/.codemap/config.json`. Everything it produces lives in `/.codemap/`. | Command | Does | |---|---| -| `/codemap generate` | first build: ask prefs → decompose into modules → scan → audit every module → render | +| `/codemap init` | first build: ask prefs → decompose into modules → scan → audit every module → render | | `/codemap check` | read-only: is the map stale? shows commits since last run + drifted / new / deleted modules | | `/codemap update` | incremental + git-aware: re-audit only changed modules, re-render | | `/codemap test ` | generate a regression-net of tests for a module | @@ -123,17 +147,6 @@ python3 $S/scripts/render.py --state .codemap/modules.json --template $S/assets/ > On Windows use `python` instead of `python3`. -## Using with Codex / other agents - -The skill mechanism is Claude-specific, but the **engine is tool-agnostic** — four -deterministic stdlib-Python scripts plus a Markdown workflow and rubric. **OpenAI Codex** -auto-reads the shipped **`AGENTS.md`**. To use codemap from Codex (or Cursor, Aider, …): - -1. Clone this repo somewhere the agent can read, e.g. `git clone ~/.codemap`. -2. Tell the agent: *"Use the codemap tool at `` to map/audit this project — follow - its `SKILL.md`; score each module with a separate sub-task per `reference/STANDARDS.md`."* -3. It runs the same `scan → audit → apply_audit → render` loop, using `query.py` to target. - ## How it works ``` diff --git a/SKILL.md b/SKILL.md index 800abba..8f5e8ee 100644 --- a/SKILL.md +++ b/SKILL.md @@ -54,7 +54,7 @@ prompt) and `standard.json` (the machine copy) in sync if you change the default - `codemap.html` + `codemap.md` — the generated outputs (default). The output location is a user preference: if they want the HTML/MD committed/visible, - let them point it at `docs/` instead (ask — see `generate` step 0). Set + let them point it at `docs/` instead (ask — see `init` step 0). Set `meta.htmlPath` / `meta.mdPath` to wherever the outputs land so the reciprocal links are correct (both outputs sit in the same dir, so the in-page link uses the basename). - A re-render command (run after any state change): @@ -113,9 +113,9 @@ per-module subagent loop — never load the full `modules.json` just to pick tar --- -## Command: `generate` (first build) +## Command: `init` (first build) -Use when no `modules.json` exists yet (this is also "init"). +Use when no `modules.json` exists yet. (Also accepts `generate` as an alias.) 0. **Ask the user for preferences first** (use the AskUserQuestion tool), then save them to `/.codemap/config.json`: @@ -182,7 +182,7 @@ uses git to show recent history and scope the work. (plus any uncommitted edits), so re-audit `needs_audit`. If `git` is null the project isn't a git repo — fall back to content-hash staleness only. 3. **Re-audit only those modules**, each with its own independent subagent (same protocol - as `generate` step 3). Apply each via `apply_audit.py --id --rev `. Fresh + as `init` step 3). Apply each via `apply_audit.py --id --rev `. Fresh modules keep their cached audit — that is the whole point of the content hash. 4. **Refresh `reportThemes`** if the changes are material (otherwise keep them). 5. **Render**, then **stamp the baseline**: diff --git a/reference/DATA_MODEL.md b/reference/DATA_MODEL.md index d342dbc..dbd9254 100644 --- a/reference/DATA_MODEL.md +++ b/reference/DATA_MODEL.md @@ -79,7 +79,7 @@ subagents edit it) and re-render. | Field | Written by | When | |---|---|---| -| `meta.*`, `bands`, `spine`, `coupling`, `deps`, `desc`, `paths`, `label`, `id`, `band` | **model** (decomposition) | `generate`, and when structure changes | +| `meta.*`, `bands`, `spine`, `coupling`, `deps`, `desc`, `paths`, `label`, `id`, `band` | **model** (decomposition) | `init`, and when structure changes | | `loc`, `contentHash`, `meta.tracked_*` | `scan.py --write` | every scan | | `score`, `grade`, `tags`, `findings`, `auditedHash/At/Rev` | `apply_audit.py` (from an **auditor subagent**) | each (re)audit | | `tests` | **test-author subagent** | `test`, and the baseline step of `fix` |