# Roadmap Refresh

> Regenerate `docs/roadmap.md` for a repo from all specs under `docs/specs/` + their frontmatter (status, tags, pr). Produces Now/Next/Recently-shipped sections. Run after creating / shipping a spec, or at the start of a new session for orientation.

- Skill: `lucassantana-dev/roadmap-refresh` (Agent Skill)
- Install (CLI): `npx skillmds@latest add lucassantana-dev/roadmap-refresh`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lucassantana-dev/roadmap-refresh/raw
- Safety review: PASS (external: skill-scanner PASS, skillspector CAUTION)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: LucasSantana-Dev (https://skillmd.com/u/lucassantana-dev)
- Updated: 2026-08-19
- Page: https://skillmd.com/skills/lucassantana-dev/roadmap-refresh

---


# roadmap-refresh

Agent-OS-style roadmap, generated — not hand-edited.

## Usage
```bash
~/.claude/rag-index/venv/bin/python ~/.claude/rag-index/specs.py roadmap --repo <path>
```

Reads every `docs/specs/*/spec.md`, buckets by `status:` frontmatter:
- **Now** = `status: active`
- **Next** = `status: proposed`
- **Recently shipped** = last 10 under `docs/specs/archived/`

Writes to `docs/roadmap.md`. Idempotent; safe to re-run.

## When to run
- After `spec-new` or `spec-ship` (automatic future: wrap via git hook).
- At session start in an unfamiliar repo — immediately shows what's live/queued/just shipped.
- Before opening a PR that references "per the roadmap".

## Why not hand-edited
Hand-curated roadmaps rot within 2 weeks. This one is **derived state** — the spec frontmatter is the source of truth.

## Editing conventions
- To move a spec from Next → Now: edit frontmatter `status: proposed → active`, re-run.
- To retire a proposed spec: `rm -rf docs/specs/<folder>` (or archive manually), re-run.
- Tags appear next to entries when set: `tags: rag,platform`.

## See also
- `spec-new`, `spec-ship`
- `backlog-mapper` — different: that scans git/PRs, this reads spec files.