unikit-roadmap

name	unikit-roadmap
description	Create or update a strategic project roadmap with major milestones. Generates .unikit/ROADMAP.md — a high-level checklist of project goals. Use when user says "roadmap", "project plan", "milestones", "what to build next", "strategic goals", or wants to see big-picture progress. Also use when the user asks to check which milestones are done or wants to plan the overall project direction.
argument-hint	[check | project vision or requirements]
allowed-tools	["Read","Write","Edit","Glob","Grep","Bash(git *)","AskUserQuestion","Agent"]
disable-model-invocation	true
user-invocable	true
metadata	{"author":"unikit","version":"1.1","category":"planning"}

Roadmap — Strategic Project Planning

Create and maintain a high-level project roadmap with major milestones.

Language Awareness — BLOCKING PRE-REQUISITE

BEFORE producing ANY output, silently read .unikit/system/LANGUAGE_RULES.md and apply its rules to ALL subsequent output. If the file is missing or unreadable, fall back to English. Do not produce any user-facing output until language rules are loaded. Do not announce, confirm, or mention the language setting.

Workflow

Step 0: Load Project Context

Read .unikit/DESCRIPTION.md if it exists to understand:

• Tech stack (engine, framework, DI, async patterns)
• Project architecture and conventions
• Non-functional requirements

Read .unikit/ARCHITECTURE.md if it exists to understand:

• Chosen architecture pattern and folder structure
• Module boundaries and communication patterns

Read .unikit/skill-context/unikit-roadmap/SKILL.md — MANDATORY if the file exists.

This file contains project-specific rules accumulated by /unikit-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)
• 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 ROADMAP.md)

Otherwise check if .unikit/ROADMAP.md exists:

• 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 — first classify each argument:

• File path (contains /, \, or ends with a known extension like .md, .txt, .json, .pdf, .docx) → treat as a reference document. Read the file content and use it as context for generating milestones. Store the path for the References section.
• Plain text → treat as vision/description input for milestones.

Arguments can be mixed — e.g., a description string plus one or more file paths.

If reference documents were detected:

• Read each document via Read tool
• Extract key goals, requirements, features, and priorities from the document content
• Use extracted information as primary input for milestone generation
• Track which milestones were derived from which documents — this mapping will be recorded in the ## References section

If only plain text arguments provided:

• 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:

• Describe vision → ask follow-up about priorities (next question)
• Analyze codebase → proceed to Step 1.2 (Explore Codebase), auto-generate milestones
• Both → ask for description, then enrich with codebase analysis

If user chooses option 1 or 3, 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

Based on choice:

• Yes → ask user for priorities/deadlines, incorporate into milestone ordering
• No → order milestones by logical dependency sequence
• Skip → proceed without priority ordering

1.2: Explore Codebase

Scan the project to understand what's already built:

• Glob for project structure (key directories, modules)
• Grep for implemented features (controllers, systems, views, installers)
• Check git log for completed work: git log --oneline -20

1.3: Generate ROADMAP.md

Create .unikit/ROADMAP.md using the format defined in the ROADMAP.md Format section below.

Rules for milestones:

• Each milestone is a high-level goal, not a granular task (that's /unikit-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

Based on choice:

• Save → write to .unikit/ROADMAP.md
• Add more → ask for additional milestones, regenerate, re-confirm
• Remove/modify → ask which to change, apply edits, re-confirm
• Rewrite → ask for new input, regenerate from scratch

---

Mode 2: Update Roadmap (Subsequent Run)

2.1: Read Current State

• Read .unikit/ROADMAP.md
• Read .unikit/DESCRIPTION.md for context
• Explore codebase briefly to check what's changed since last update

2.2: Determine Action

If user provided arguments — classify each argument (same rules as Mode 1 Step 1.1):

• File path → read document, use content as context, add to ## References section (append to existing references, avoid duplicates)
• Plain text → treat as new milestones or change instructions

If arguments contain reference documents:

• Read each document, extract goals/requirements
• Generate new milestones from the document content and append to the roadmap
• Add document paths to the References section

If only plain text arguments:

• 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

Based on choice:

• Review progress → scan codebase for completed milestones, propose updates (Step 2.3)
• Add milestones → ask for new milestones, append to roadmap (Step 2.4)
• Reprioritize → present current order, ask for new order (Step 2.5)
• Rewrite → major revision, ask for new vision

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:

AskUserQuestion: These milestones appear to be done:
- **Milestone Name** — [evidence: files exist, systems implemented, etc.]

Mark them as completed?

Options:
1. Yes — mark all as completed
2. No — skip

Based on choice:

• Yes → change - [ ] to - [x] for listed milestones, add to Completed table with today's date
• No → skip, proceed to next step

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 .unikit/ROADMAP.md

2.5: Reprioritize (if chosen)

• Show current order
• Ask user for new order or let them describe priority changes
• Reorder milestones in .unikit/ROADMAP.md

2.6: Save Changes

Update .unikit/ROADMAP.md with all modifications.

Show summary:

## Roadmap Updated

Total milestones: N
✅ Completed: X/N
▶ Next up: **Milestone Name**

To start working on the next milestone:
/unikit-plan <milestone description>  → creates plan
/unikit-implement                     → executes the plan

---

Mode 3: Check Progress (/unikit-roadmap check)

Automated scan — analyze the codebase, detect completed milestones, and propose marking them (with user confirmation).

Requires .unikit/ROADMAP.md to exist. If it doesn't — tell the user to run /unikit-roadmap first.

3.1: Read roadmap and project context

• Read .unikit/ROADMAP.md
• Read .unikit/DESCRIPTION.md for tech stack context

3.2: Analyze each unchecked milestone

For every - [ ] milestone:

• Determine what evidence would prove it's done (files, systems, 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):
- **Trading System** — found: TradeController, TradeOffer, trade installers, tests
- **Customer Behaviour** — found: CustomerFSM, NodeCanvas trees, customer spawning

🔄 In Progress:
- **Mini-Games System** — found: MiniGameLauncher exists but SliderGame incomplete

⏳ Not Started:
- **Night Market**
- **Dynamic Events**

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

## References

| Document | Description | Milestones |
|----------|-------------|------------|
| `relative/path/to/document.md` | Brief description of contents | Milestone A, Milestone B |

## Completed

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

References section rules:

• Include ## References only when reference documents were provided as arguments
• If no documents were passed — omit the section entirely (do not include an empty table)
• Store paths relative to the project root
• Description column: a short summary of what the document covers (extracted during reading)
• Milestones column: comma-separated names of milestones that were derived from or informed by this document. When generating milestones from a document, track which milestones came from which source. A milestone may appear in multiple rows if it was informed by several documents.
• On subsequent updates (Mode 2): append new documents, never remove existing references unless user explicitly asks. When new milestones are added from existing references, update the Milestones column accordingly.

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 /unikit-plan to start a feature and /unikit-implement to execute
6. Ownership boundary — this command owns .unikit/ROADMAP.md. /unikit-implement may only mark milestones completed when implementation evidence is clear
7. Respond in the configured language — use language.ui from .unikit/config.yaml (default: English) for all user-facing messages
8. References are append-only — never remove document references unless explicitly asked by the user
9. References require documents — only add the ## References section when actual documents were provided; never generate it with empty content