starred/codemap-skill
1
0
Fork 0
mirror of https://github.com/Asixa/codemap-skill.git synced 2026-08-28 17:01:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

README: unify install for Claude Code/Codex/Cursor (drop separate Codex section); rename first-build command generate -> init

Browse Source
This commit is contained in:
Xingyu Chen
2026-06-10 18:57:51 -07:00
parent 20c1c58f3c
commit 328e30b6de
4 changed files with 39 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+1 -1
View File
@@ -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**.
README.md
+33 -20
View File
@@ -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
`<project>/.codemap/config.json`. Everything it produces lives in `<project>/.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 <module>` | 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 <url> ~/.codemap`.
2. Tell the agent: *"Use the codemap tool at `<path>` 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
```
SKILL.md
+4 -4
View File
@@ -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
`<project>/.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 <id> --rev <head>`. Fresh
as `init` step 3). Apply each via `apply_audit.py --id <id> --rev <head>`. 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**:
reference/DATA_MODEL.md
+1 -1
View File
@@ -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` |