aif-roadmap

name	aif-roadmap
description	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".
argument-hint	[check | project vision or requirements]
allowed-tools	Read Write Edit Glob Grep Bash(git *) AskUserQuestion Questions
disable-model-invocation	true

Roadmap - Strategic Project Planning

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, language.artifacts for generated content

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

> <project vision — one-liner from DESCRIPTION.md or user input>

## 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

3.3: Report findings

## Roadmap Progress Check

✅ Done (ready to mark):
- **User Authentication** — found: src/auth/, JWT middleware, login/register routes
- **Database Setup** — found: migrations/, models/, seed scripts

🔨 In Progress:
- **Payment Integration** — found: src/payments/ exists but Stripe webhook handler missing

⏳ Not Started:
- **Admin Dashboard**
- **Email Notifications**

Mark completed milestones? (2 milestones)

3.4: Apply changes (if confirmed)

• Mark done milestones [x]
• Add entries to Completed table with today's date
• Leave partial and not-started milestones unchanged

Show updated summary:

Completed: X/N milestones
Next up: **Milestone Name**

---

ROADMAP.md Format

# Project Roadmap

> <project vision — one-liner>

## Milestones

- [ ] **Name** — short description
- [ ] **Name** — short description
- [x] **Name** — short description

## Completed

| Milestone | Date |
|-----------|------|
| Name | YYYY-MM-DD |

Critical Rules

1. Milestones are high-level — each represents a major feature or capability, not a task
2. ROADMAP.md is the source of truth — always read before modifying
3. Never remove milestones silently — always confirm with user before removing
4. Completed table tracks history — every checked milestone gets a date entry
5. NO implementation — this skill only plans, use $aif-plan to start a feature and $aif-implement to execute
6. Ownership boundary — this command owns roadmap structure/content; $aif-implement may only mark milestones completed when implementation evidence is clear