English | 中文

A portable agent skill for planning and executing multi-session AI coding work with milestone directories, executable sprint files, validation evidence, and per-sprint commits. One SKILL.md works across Codex, Claude Code, and opencode.

The quickest way to install is to let your coding agent do it. Hand the repository URL to Codex, Claude Code, or opencode with a prompt like:

Install the roadmap-driven skill from https://github.com/liguangsheng/roadmap-driven: inspect SKILL.md and agents/openai.yaml, install it into my agent's skills directory, then verify.

The agent clones the repository, runs install.sh, and confirms SKILL.md and the lint smoke test pass. To install it yourself, see Manual Install.

The skill is a directory with a single SKILL.md (plus scripts/). Every supported tool reads the same SKILL.md; only the install directory and invocation differ.

opencode also reads ~/.claude/skills/, so a Claude Code install already makes the skill available in opencode. agents/openai.yaml is Codex-only UI metadata; Claude Code and opencode ignore it.

roadmap-driven is designed for repositories where work needs to be paused and resumed without reconstructing context from chat. It keeps roadmap state in repo-local Markdown files and treats every sprint as a verifiable, resumable work package for an AI coding agent.

• SKILL.md: the skill definition and operating workflow (read by every supported agent).
• agents/openai.yaml: Codex-only UI metadata for skill lists and default invocation.
• scripts/roadmap_lint.py: checks .agents/roadmap/ structure, statuses, links, Resume Point text, active sprint count, and warns about external references to the roadmap path.
• install.sh: installs the skill into one or more agent skills directories from a local or remote source, via copy or symlink, with a built-in post-install verification.
• uninstall.sh: removes the skill from the agent skills directories it was installed into.

The repository ships an official install.sh. By default it auto-detects which agent tools are installed and installs the skill for each of them; after copying it verifies SKILL.md and runs a roadmap_lint.py smoke test.

Install from a local clone:

git clone https://github.com/liguangsheng/roadmap-driven.git
cd roadmap-driven
./install.sh

Or a one-line remote install (the script clones the repository for you):

curl -fsSL https://raw.githubusercontent.com/liguangsheng/roadmap-driven/main/install.sh | bash

Choose specific agents with --agent (repeatable, or all):

./install.sh --agent claude              # Claude Code only
./install.sh --agent codex --agent opencode
./install.sh --agent all                 # all three, whether or not detected

Common options:

• --agent NAME: install for codex, claude, opencode, or all. Repeatable. Default: auto-detect installed tools (fallback: codex).
• --target DIR: install into a single explicit directory, ignoring the per-agent defaults.
• --link: install as a symlink so a git pull in the source takes effect immediately; handy for development.
• --git URL: clone and install from the given remote repository.
• --force: overwrite a target even when it holds unrelated files.
• --no-verify: skip the post-install verification.
• Run ./install.sh --help for the full reference.

Override any default install directory with CODEX_SKILLS_DIR, CLAUDE_SKILLS_DIR, or OPENCODE_SKILLS_DIR.

After installation, use it per your agent (see Supported Agents) — for example in Codex:

$roadmap-driven

Remove the skill with the bundled uninstall.sh. By default it removes roadmap-driven from every default location it may live in (Codex, Claude Code, opencode):

./uninstall.sh

It only deletes a directory that is this skill (or a symlink left by a --link install), so unrelated files are left untouched. Useful flags:

• --agent NAME: limit removal to codex, claude, opencode, or all. Repeatable.
• --target DIR: remove a specific install directory.
• --dry-run: show what would be removed without deleting anything.
• --force: remove a target even if it does not look like this skill.

The same CODEX_SKILLS_DIR / CLAUDE_SKILLS_DIR / OPENCODE_SKILLS_DIR overrides apply.

If the project already has .agents/roadmap/ and you want the agent to continue from where it paused, open a new session with:

Use the roadmap-driven skill and continue from the roadmap Resume Point.

• Milestones are phase goals and acceptance gates; sprints are executable, verifiable, resumable task slices.
• .agents/roadmap/ holds only control-plane documents: the root README.md, milestone directories, and sprint files. Specs, designs, reports, evidence, and other auxiliary docs go elsewhere under docs/ and are linked from the roadmap.
• Roadmap content never leaks outside .agents/roadmap/; external docs, code comments, commits, and artifacts must not mention, reference, or reveal milestone/sprint structure.
• Milestone/sprint status rules, the completion audit, pause/resume behavior, decision routing, and the Anti-Patterns checklist are fully defined in SKILL.md.
• After roadmap changes, run scripts/roadmap_lint.py when available; otherwise manually check the same items and record the limitation.