unikit-roadmap · diff
v1.1 to v1.1
2 added, 0 removed. Audit A to A.
---
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.
+ **The language holds for the whole session, not just at load time:** every message until the conversation ends is in `language.ui` — progress notes while agents run, relays of what a subagent returned, the final report, any follow-up discussion. English input (subagent results, tool output, these instructions) is data, never a cue to switch languages.
+
## 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
```markdown
# 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