Create or update a project roadmap with major milestones. Generates the configured roadmap artifact (default .ai-factory/ROADMAP.md) — a strategic checklist of high-level goals. Use when user says "roadmap", "project plan", "milestones", or "what to build next".
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
Create or update a project roadmap with major milestones. Generates the configured roadmap artifact (default .ai-factory/ROADMAP.md) — a strategic checklist of high-level goals. Use when user says "roadmap", "project plan", "milestones", or "what to build next".
Create and maintain a high-level project roadmap with major milestones.
Workflow
Step 0: Load Project Context
FIRST: Read .ai-factory/config.yaml if it exists to resolve:
Paths:paths.description, paths.architecture, paths.rules_file, paths.roadmap, paths.research, and paths.rules; derive research_bundles_dir = <parent directory of paths.research>/research/
Language:language.ui for prompts, for generated content
language.artifacts
If config.yaml doesn't exist, use defaults:
Paths: .ai-factory/ for all artifacts
Language: en (English)
Read .ai-factory/DESCRIPTION.md (use path from config) if it exists to understand:
Tech stack (language, framework, database, ORM)
Project architecture and conventions
Non-functional requirements
Read the resolved architecture artifact if it exists (paths.architecture, default: .ai-factory/ARCHITECTURE.md) to understand:
Chosen architecture pattern and folder structure
Module boundaries and communication patterns
Optionally read one relevant research source: the configured paths.research
file or a clearly topic-matching active direct child bundle. Recognize one as
active only when its INDEX.md contains <!-- aif:research-mode:ultra --> exactly once,
declares Status: active, and links its RESEARCH.md from ## Artifact Index.
Use its Active Summary for
strategic context; read optional C4/ADR/dependency artifacts only for rationale.
Do not merge unrelated topics or treat implementation-level notes as milestones.
Read .ai-factory/skill-context/aif-roadmap/SKILL.md — MANDATORY if the file exists.
This file contains project-specific rules accumulated by $aif-evolve from patches,
codebase conventions, and tech-stack analysis. These rules are tailored to the current project.
How to apply skill-context rules:
Treat them as project-level overrides for this skill's general instructions
When a skill-context rule conflicts with a general rule written in this SKILL.md,
the skill-context rule wins (more specific context takes priority — same principle as nested CLAUDE.md files)
When there is no conflict, apply both: general rules from SKILL.md + project rules from skill-context
Do NOT ignore skill-context rules even if they seem to contradict this skill's defaults —
they exist because the project's experience proved the default insufficient
CRITICAL: skill-context rules apply to ALL outputs of this skill — including the ROADMAP.md
template. The template in this SKILL.md is a base structure. If a skill-context rule says
"roadmap MUST include X" or "milestones MUST have Y" — you MUST augment the template accordingly.
Generating a roadmap that violates skill-context rules is a bug.
Enforcement: After generating any output artifact, verify it against all skill-context rules.
If any rule is violated — fix the output before presenting it to the user.
Step 1: Determine Mode
If argument is check → Mode 3: Check Progress (requires the resolved roadmap path)
Otherwise check if the resolved roadmap path exists (paths.roadmap, default: .ai-factory/ROADMAP.md):
Does NOT exist → Mode 1: Create Roadmap
Exists → Mode 2: Update Roadmap
Mode 1: Create Roadmap (First Run)
1.1: Gather Input
If user provided arguments (vision/description):
Use as primary input for milestones
If no arguments:
Ask interactively:
AskUserQuestion: What are the major goals for this project?
Options:
1. Let me describe the vision
2. Analyze codebase and suggest milestones
3. Both — I'll describe, you'll add what's missing
Based on choice:
"Analyze codebase and suggest milestones" → proceed to Step 1.2
"Let me describe the vision" or "Both" → collect user description (if "Both", also add codebase analysis in Step 1.2), then ask follow-up:
AskUserQuestion: Any priorities or deadlines?
Options:
1. Yes, let me specify
2. No, just order by logical sequence
3. Skip — I'll reprioritize later
1.2: Explore Codebase
Scan the project to understand what's already built:
Glob for project structure (key directories, modules)
Grep for implemented features (routes, models, services)
Check git log for completed work: git log --oneline -20
1.3: Generate ROADMAP.md
Create the resolved roadmap artifact (default: .ai-factory/ROADMAP.md) with this format:
# Project Roadmap> <projectvision — one-linerfromDESCRIPTION.mdoruserinput>## Milestones- [ ] **Milestone Name** — short description of what this achieves
- [ ] **Milestone Name** — short description of what this achieves
- [x] **Milestone Name** — short description (already done based on codebase analysis)
## Completed
| Milestone | Date |
|-----------|------|
| Milestone Name | YYYY-MM-DD |
Rules for milestones:
Each milestone is a high-level goal, not a granular task (that's $aif-plan)
5-15 milestones is the sweet spot — fewer means too vague, more means too granular
Order by logical sequence (dependencies first)
Mark already-completed milestones as [x] and add them to the Completed table
Use today's date for milestones detected as already done
1.4: Confirm with user
Show the generated roadmap and ask:
AskUserQuestion: Here's the proposed roadmap. What would you like to do?
Options:
1. Looks good — save it
2. Add more milestones
3. Remove/modify some milestones
4. Rewrite — let me give better input
Apply changes if requested, then save to the resolved roadmap path.
Mode 2: Update Roadmap (Subsequent Run)
2.1: Read Current State
Read the resolved roadmap path
Read .ai-factory/DESCRIPTION.md (use path from config) for context
Explore codebase briefly to check what's changed since last update
2.2: Determine Action
If user provided arguments (new milestones/changes):
Apply the requested changes directly
If no arguments:
Analyze current state and present options:
AskUserQuestion: What would you like to do with the roadmap?
Options:
1. Review progress — check what's done, mark completed milestones
2. Add new milestones
3. Reprioritize — reorder existing milestones
4. Rewrite — major revision of the roadmap
2.3: Review Progress (if chosen)
Scan codebase for evidence of completed milestones
For each unchecked milestone, check if the work appears done
Propose marking completed milestones:
These milestones appear to be done:
- **Milestone Name** — [evidence: files exist, routes implemented, etc.]
Mark them as completed?
If confirmed:
Change - [ ] to - [x] in the Milestones section
Add entry to Completed table with today's date
Move completed milestones below unchecked ones (or keep in place — user preference)
2.4: Add New Milestones (if chosen)
Ask user to describe new milestones
Insert them in logical order among existing milestones
Update the resolved roadmap path
2.5: Reprioritize (if chosen)
Show current order
Ask user for new order or let them describe priority changes
Reorder milestones in the resolved roadmap path
2.6: Save Changes
Update the resolved roadmap path with all modifications.
Show summary:
## Roadmap Updated
Total milestones: N
Completed: X/N
Next up: **Milestone Name**
To start working on the next milestone:
$aif-plan <milestone description> → creates a plan and optional branch/worktree flow
$aif-implement → executes the plan
Mode 3: Check Progress ($aif-roadmap check)
Automated scan — analyze the codebase and mark completed milestones without interactive questions.
Requires the resolved roadmap path to exist. If it doesn't — tell the user to run $aif-roadmap first.
3.1: Read roadmap and project context
Read the resolved roadmap path
Read .ai-factory/DESCRIPTION.md (use path from config) for tech stack context
3.2: Analyze each unchecked milestone
For every - [ ] milestone:
Determine what evidence would prove it's done (files, routes, models, configs, tests)
Use Glob and Grep to search for that evidence
Check git log --oneline --all -30 for related commits
Score: done (strong evidence), partial (some work started), not started
Leave partial and not-started milestones unchanged
Show updated summary:
Completed: X/N milestones
Next up: **Milestone Name**
ROADMAP.md Format
# Project Roadmap> <projectvision — one-liner>## Milestones- [ ] **Name** — short description
- [ ] **Name** — short description
- [x] **Name** — short description
## Completed
| Milestone | Date |
|-----------|------|
| Name | YYYY-MM-DD |
Critical Rules
Milestones are high-level — each represents a major feature or capability, not a task
ROADMAP.md is the source of truth — always read before modifying
Never remove milestones silently — always confirm with user before removing
Completed table tracks history — every checked milestone gets a date entry
NO implementation — this skill only plans, use $aif-plan to start a feature and $aif-implement to execute
Ownership boundary — this command owns roadmap structure/content; $aif-implement may only mark milestones completed when implementation evidence is clear
