Aif Roadmap

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.