roadmapsmith — Claude Code plugin: what it does, how to install
roadmapsmith keeps ROADMAP.md honest: one command writes it, the other proposes edits backed by real code and waits for your ok.
MIT ★ 1,596 updated 2026-10-29
/plugin marketplace add hashgraph-online/awesome-codex-plugins
/plugin install roadmapsmith@awesome-codex-pluginsWhat roadmapsmith does
Two slash commands come with this plugin. /roadmap-init asks for the project name, the problem and the user, scans the repository, then writes ROADMAP.md with tasks split by phase (P0/P1/P2) and by code area. An existing ROADMAP.md is left untouched.
/roadmap-update walks the code looking for proof behind each task and posts a diff in the chat before touching the file: tasks it would tick, tasks already ticked with nothing behind them, tasks found in code but missing from the roadmap. Nothing is written until you reply ok. full-scan re-reads the whole repo, short-circuit leans on the context of the current session.
The plugin runs on Claude and Codex; the repo carries a native .codex-plugin/plugin.json manifest declaring the same skills. A global CLI installed back in the pre-v1.0.0 days via npm i -g roadmapsmith can stay — skills live on a separate path and that old binary will not update with them.
What it helps with
- generate
ROADMAP.mdwith tasks grouped by phase and code area - tick a task off only where the code proves it
- spot tasks marked done with nothing behind them
- review the diff before the file is rewritten
- pull newly written code into the roadmap
Example prompts for the agent
- Run
/roadmap-initand buildROADMAP.mdgrouped by P0/P1/P2 phases. - Run
/roadmap-updatewithfull-scanand show me the diff before writing. - Update
ROADMAP.mdthrough/roadmap-update, but do not flip[ ]to[x]without evidence.
How to install roadmapsmith
Plugin marketplace
/plugin marketplace add hashgraph-online/awesome-codex-plugins/plugin install roadmapsmith@awesome-codex-pluginsStep by step, with commands for each platform: Claude Code plugins: marketplaces, installing, and building your own
Questions about roadmapsmith
How do I install roadmapsmith in Claude Code?
From the plugin marketplace: run /plugin marketplace add hashgraph-online/awesome-codex-plugins, then /plugin install roadmapsmith@awesome-codex-plugins.
What does roadmapsmith do?
It keeps ROADMAP.md matching the code. /roadmap-init builds the file once when a repo starts, /roadmap-update proposes edits and waits for your ok before writing.
What happens if a task is already ticked but no code backs it?
It appears in the proposed diff as a warning about a checked task without evidence. The file stays as it is until you approve the change.
Source text
roadmapsmith · MIT
# roadmapsmith [](https://skills.sh/PapiScholz/roadmapsmith) Un skill para agentes de IA (Claude Code, Codex, y cualquier host que lea `SKILL.md`) que mantiene tu `ROADMAP.md` coherente con lo que hay en el código. Dos slashcommands: uno para crearlo, otro para actualizarlo — el agente escanea el repo, pide evidence real antes de marcar `[x]`, y te pasa un diff antes de escribir. ## El problema - Los `ROADMAP.md` se pudren: alguien marca `[x]` una task que no está terminada, o deja `[ ]` algo que ya se shippeó, y a los dos meses el archivo miente. - Chequear a mano cada task contra el código no escala: el agente puede leer todo el repo en segundos y proponerte el diff. - Marcar completado sin evidence verificable es autoengaño — este skill nunca flipea `[ ] → [x]` sin encontrar el archivo/símbolo que respalda la task. ## Cómo funciona (dos slashcommands) ``` /roadmap-init # una vez, al arrancar un repo /roadmap-update # cuando querés reflejar tu progreso ``` - **`/roadmap-init`** — Te hace 3 preguntas mínimas (nombre, problema, usuario), escanea el repo, y genera `ROADMAP.md` con tasks agrupadas por fase (P0/P1/P2) y área del código. Nunca sobreescribe un `ROADMAP.md` existente. - **`/roadmap-update`** — Releva el código en busca de evidence, te propone un diff (tareas a marcar, warnings de checked-sin-evidence, tareas nuevas detectadas), y espera tu `ok` antes de escribir. Modo `full-scan` (determinístico) o `short-circuit` (usa el contexto de la sesión si alcanza). Full spec de cada uno: [`skills/roadmap-init/SKILL.md`](skills/roadmap-init/SKILL.md) · [`skills/roadmap-update/SKILL.md`](skills/roadmap-update/SKILL.md) ## Cómo se ve Antes: ```markdown ## Phase 0 — Baseline ### auth - [ ] [P0] Add login endpoint - [ ] [P0] Hash passwords with bcrypt - [ ] [P0] Session cookies ``` Después de `/roadmap-update` (ya implementaste dos): ```markdown ## Phase 0 — Baseline ### auth - [x] [P0] Add login endpoint <!-- evidence: src/auth/login.ts:14 --> - [x] [P0] Hash passwords with bcrypt <!-- evidence: src/auth/hash.ts:8 --> - [ ] [P0] Session cookies ``` El diff se te muestra en el chat antes de escribir. Si el agente marcó algo sin evidence real, aparece como `⚠️ checked pero sin evidence` en la propuesta. ## Install Un comando: ```bash npx skills add PapiScholz/roadmapsmith ``` Detecta el agente (Claude Code, Codex, 70+ más) e instala los dos skills en el lugar correcto. Nada más. <details> <summary>Otras vías de instalación</summary> ```bash # Ver qué skills declara el repo antes de instalar npx skills add PapiScholz/roadmapsmith --list # Buscar por keyword (una vez que skills.sh indexa el repo, ~1h después del primer add) npx skills find roadmap ``` - **Web:** [`https://skills.sh/PapiScholz/roadmapsmith`](https://skills.sh/PapiScholz/roadmapsmith) - **Shim legacy** (equivalente, delega al `skills add` de arriba): `npx github:PapiScholz/roadmapsmith` - **Codex plugin nativo:** el manifest `.codex-plugin/plugin.json` en la raíz declara los mismos skills — instalación vía Codex plugin marketplace funciona sin pasos extra. </details> ## Update ```bash npx skills update ``` Actualiza todos los skills instalados. Para actualizar solo uno: `npx skills update roadmap-init` o `npx skills update roadmap-update` (nombres de los skills, no del repo). > **Warning esperado** — vas a ver `the following skills appear to have been deleted upstream` listando ~19 nombres viejos (`roadmap-sync`, `audit`, `zero`, `road`, etc.) y una cascada de `No matching skills found`. Es ruido cosmético del catálogo público de skills.sh, que todavía cachea entries de pre-v1.3.0. Ya está reportado upstream — respondé `Yes` para limpiar, los `No matching skills found` que siguen son no-ops porque nunca los tuviste instalados. ### ¿Ya tenías el CLI viejo instalado global? Pre-v1.0.0 el paquete era un CLI y se instalaba con `npm i -g roadmapsmith`. Si `roadmapsmith --version` te devuelve `0.14.x`, tenés ese binario colgado — la instalación de skills es una ruta paralela y no lo pisa. Podés dejarlo (no molesta) o limpiarlo: ```bash npm uninstall -g roadmapsmith ``` Post-v1.0.0 la única "instalación" que necesitás es la de skills; ya no hay CLI global que actualizar. ## Estado Herramienta personal, sin roadmap comercial. Feedback y bug reports bienvenidos vía [issues](https://github.com/PapiScholz/roadmapsmith/issues). MIT. Mantenimiento y flujo de release: [`docs/RELEASING.md`](docs/RELEASING.md). <details> <summary>Legacy — CLI v0.15 (deprecated)</summary> La versión previa (v0.10 a v0.15) era un CLI en Node con validator, audit engine, drift detection y 312 tests. Todo eso vive en [`legacy/`](legacy/) sin desarrollo activo — ver [`legacy/README.md`](legacy/README.md). El pivote a v1.0.0 tiró la ceremonia (validator, tests, marketing) y dejó solo lo que el user original quería: un skill, dos slashcommands, `ROADMAP.md` al día. </details>
© PapiScholz · MIT · hashgraph-online/awesome-codex-plugins