project-roadmap-manager

Project Roadmap Manager

Maintain ROADMAP.md in the project root as the canonical roadmap record. Prefer updating existing sections over appending duplicates, and keep Current Milestone synchronized with the latest accepted plan.

Workflow

1. Load active customization config:
   • Prefer <skill_root>/config/customization.yaml.
   • Fall back to <skill_root>/config/customization.template.yaml.
   • Apply settings under settings to roadmap generation and update decisions.
   • Treat missing sub-milestone keys in user config as template defaults.
2. Identify project root and target file:
   • Use <project_root>/ROADMAP.md.
   • If root is ambiguous, infer from repository root.
3. Ensure ROADMAP.md exists:
   • If missing, create it using the template in this skill.
4. Classify the request into one of these event types:
   • Project bootstrap.
   • Plan acceptance/completion.
   • Milestone/version roadmap set or changed.
   • Milestone reached/blocked/de-scoped.
   • Roadmap reference/query.
5. Apply the event-specific update rules.
6. Keep all sections internally consistent:
   • Current Milestone matches active milestone in Milestones.
   • Plan History includes accepted plan snapshots.
   • Change Log captures each roadmap mutation with date and reason.
   • When sub-milestones are enabled, parent/child linkage and ID uniqueness are valid.

Customization Workflow

When a user asks to customize this skill, use this deterministic flow:

1. Read active config from config/customization.yaml; if missing, use config/customization.template.yaml.
2. Confirm target profile and desired behavior for:
   • milestoneIdStyle
   • targetStyle
   • statusValues
   • sub-milestone enablement, ID style, and status model
   • owner/dependency fields
   • plan history and changelog verbosity
3. Propose 2-4 option bundles with one recommended default.
4. Create or update config/customization.yaml from the template and set:
   • schemaVersion: 1
   • isCustomized: true
   • profile: <selected-profile>
5. Apply the selected settings immediately to roadmap output behavior.
6. Validate with a dry-run roadmap update and report changed keys plus behavior deltas.

Customization Reference

• Detailed knobs and examples: references/customization.md
• YAML schema and allowed values: references/config-schema.md

ROADMAP.md Template

Use this structure when creating a new roadmap:

# Project Roadmap

## Current Milestone
- ID: M1
- Name: Initial Setup
- Status: Planned
- Target Version: v0.1.0
- Last Updated: YYYY-MM-DD
- Summary: One-paragraph summary of the currently accepted plan.

## Milestones
| ID | Name | Target Version | Status | Target Date | Notes |
| --- | --- | --- | --- | --- | --- |
| M1 | Initial Setup | v0.1.0 | Planned | YYYY-MM-DD | Bootstrap milestone |

<!-- Include this section only when settings.enableSubMilestones is true. -->
## Sub-Milestones
| ID | Parent Milestone | Name | Status | Target Date | Notes |
| --- | --- | --- | --- | --- | --- |
| M1.1 | M1 | First deliverable | Planned | YYYY-MM-DD | Optional child milestone |

## Plan History
### YYYY-MM-DD - Accepted Plan (v0.1.0 / M1)
- Scope:
- Acceptance Criteria:
- Risks/Dependencies:

## Change Log
- YYYY-MM-DD: Initialized roadmap.

Event Handling Rules

Project Bootstrap

• Create ROADMAP.md if absent.
• Add an initial milestone (M1 unless user provides a different identifier).
• If enableSubMilestones is true and initial child milestones are provided, generate IDs deterministically from style settings.
• Add a changelog entry indicating roadmap initialization.

Plan Acceptance or Completion

• Update Current Milestone to reflect the accepted plan.
• Add or update corresponding row in Milestones.
• If enableSubMilestones is true, add or update affected child entries under the active milestone.
• Append an Accepted Plan entry in Plan History with scope and acceptance criteria.
• Add a changelog entry summarizing what changed and why (include parent + child transition details when child entries changed).

Milestone or Version Roadmap Set/Update

• Update existing milestone by ID/version if it exists.
• Add milestone only when no matching milestone exists.
• Avoid duplicate milestones for the same ID or target version.
• When enableSubMilestones is true:
  • Avoid duplicate child IDs within the same parent milestone.
  • Keep child status values inside subMilestoneStatusValues (or inherit statusValues when child list is absent).
  • Use deterministic ID generation rules from settings:
    • hierarchical: <milestoneID><delimiter><n> (default M2.1).
    • letter: <milestoneID><letter> (for example M2a).
    • ticket: <prefix><delimiter><zero-padded n> and render with parent context (for example M2-T01).
    • external: accept tracker IDs only when allowExternalTrackerIds is true.
• If the updated milestone is active, sync Current Milestone.

Milestone Reached/Changed

• Update milestone status (Completed, In Progress, Blocked, De-scoped, or Planned).
• Update Current Milestone if active milestone changed.
• If enableSubMilestones is true, keep child transitions and parent/child linkage consistent.
• Add a dated note in Change Log that captures transition and reason (include parent + child details when children are involved).

Roadmap Reference Requests

• Point explicitly to <project_root>/ROADMAP.md.
• Cite the relevant section name (Current Milestone, Milestones, Plan History, or Change Log).
• If file is missing, create it first, then reference it.

Quality Bar

• Preserve existing useful roadmap content.
• Use ISO date format (YYYY-MM-DD) for all dated fields.
• Keep edits minimal and deterministic.
• Never leave conflicting milestone statuses across sections.
• If sub-milestones are disabled, do not require or mutate any sub-milestone section.
• If sub-milestones are enabled, enforce deterministic child ID style and unique IDs within parent scope.

Automation Templates

Use $project-roadmap-manager inside automation prompts so Codex consistently applies the roadmap update rules.

For ready-to-fill Codex App and Codex CLI (codex exec) templates, including bounded-edit guardrails and placeholders, use:

• references/automation-prompts.md

References

• Automation prompt templates: references/automation-prompts.md
• Customization guide: references/customization.md
• Customization schema: references/config-schema.md