CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

aif-roadmap

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".

Quality

77%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./skills/aif-roadmap/SKILL.md
SKILL.md
Quality
Evals
Security

Roadmap - Strategic Project Planning

Runtime-aware questions

Apply this contract whenever the workflow asks the user to decide:

  • AskUserQuestion and Questions below describe the intended interaction, not a required tool name. Use only a question tool actually exposed and permitted in the current session/mode, with its advertised schema. Do not guess aliases, probe unavailable tools, or assume questionnaire exists. A frontmatter entry alone does not make a tool available.
  • Ask one focused question at a time with clearly labelled options. Batch independent questions only if the actual tool schema supports it; respect its field names, limits, and selection semantics. For open-ended input, use native free-text support or plain text if the schema cannot represent the question. Use the resolved UI language.
  • If no usable question tool exists (or it reports unavailable in this mode), ask the same question in plain text with numbered options and allow a free-text answer. Pause work that depends on that answer; independent read-only investigation may continue. Missing UI does not make the session autonomous.
  • An empty/cancelled response, a preselected option, or elapsed time is not an answer or approval. Reuse an answer already given in the session instead of asking again.
  • In a subagent/background run or explicit non-interactive mode (including HANDOFF_MODE=1), do not prompt the user directly. Use declared defaults only for optional preferences within the authorized scope and report assumptions. If a required decision, approval, or material scope/behavior choice remains unresolved, stop dependent work and return the missing decision and options to the parent/caller using its existing blocked/failure contract. Never invent consent or select a new scope to avoid blocking.

This delivery policy applies to this skill and its linked references. Preserve workflow-specific question scope, required confirmations, approval boundaries, and blocked-result rules.

Shared project skill-context

Before mode routing or work, read existing files relative to the current project root in this order (reuse them if already loaded):

  1. .ai-factory/skill-context/global-skill-context.md — all bundled skills.
  2. .ai-factory/skill-context/aif-roadmap/SKILL.md — this skill.

Missing files are skipped; an existing unreadable file stops dependent work with its path. Precedence: individual > build (when applicable) > global > skill defaults; retain non-conflicting instructions and check all outputs against the effective rules. These layers customize workflow; they do not replace the project's rules/architecture hierarchy or relax explicit requirements, ownership, scope, safety/privacy, validation, or approval boundaries. Report conflicts with those boundaries instead of overriding them. global is a project-local layer, not home-directory configuration. Custom/extension skills do not automatically use it.

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
Repository

lee-to/ai-factory

Path

skills/aif-roadmap/SKILL.md

Last updated
First committed

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.