Roadmap

Roadmap Maintainer

Use this skill to keep the Atmos roadmap page at /roadmap accurate, up-to-date, and aligned with actual development progress.

Core Responsibilities

1. Update milestone statuses inside initiatives[].milestones[] when features ship — never promote a milestone into featured[].
2. Link milestones to changelog entries when announcements are published — but only for user-visible changes (see "No Changelog Posts for Internal-Only Refactors" below). For the post itself, use the changelog skill; this skill only owns the roadmap.js link.
3. Add new milestones as development plans evolve.
4. Update progress percentages based on milestone completion.
5. Add new quarters as time progresses.
6. Add new initiatives when strategic priorities expand.
7. Audit roadmap accuracy against recent releases.

Featured Items: Curated, Max 6, Do Not Modify

The featured: [] array in roadmap.js is a manually curated highlight reel of the top 6 strategic initiatives only. It is not the changelog and not a list of every shipped milestone.

Hard cap: 6 items. If a featured slot needs to be added, an existing entry must be removed first — and only the user can decide which.

Rule: Never add, remove, or reorder entries in featured unless the user explicitly asks ("add X to featured", "promote Y to featured", "remove Z from featured"). When you ship a milestone, update its entry inside initiatives[].milestones[]. You do not mirror it into featured.

Bar for "featured": A featured item represents a strategic, transformative capability — e.g., "Atmos AI", "Cloud Authentication", "Native CI/CD". Per-release improvements, plumbing, and incremental enhancements never qualify, even when they are shipped.

If unsure, ask the user. Do not guess.

No Changelog Posts for Internal-Only Refactors

Changelog posts in website/blog/ are user-facing release announcements. Internal refactors with no user-visible behavior change do NOT belong in the changelog, even when they are significant engineering achievements (complexity reduction, test coverage improvements, function decomposition, dependency removal, etc.).

Test: If a user upgrading Atmos would see no change in behavior, output, errors, performance, or available commands/flags, do not write a changelog post. Refactors are visible in PR descriptions and git log; that is sufficient.

Engineering wins like "function refactored to 100% coverage" or "complexity reduced 247→10" can still be milestones inside the quality initiative on the roadmap — but without a changelog: field, and without a corresponding website/blog/*.mdx post.

Key Files

Data Structure

Initiative Format

{
  id: 'unique-id',           // kebab-case identifier
  icon: 'RiIconName',        // React Icons (Remix) name
  title: 'Initiative Title',
  tagline: 'Short tagline',
  description: 'Longer description...',
  progress: 75,              // 0-100 percentage
  status: 'in-progress',     // 'completed' | 'in-progress' | 'planned'
  milestones: [...],         // Array of milestones
  issues: [1234, 5678],      // GitHub issue numbers
}

Milestone Format

{
  label: 'Feature name',
  status: 'shipped',         // 'shipped' | 'in-progress' | 'planned'
  quarter: 'q4-2025',        // Quarter ID (e.g., 'q1-2025', 'q2-2025')
  changelog: 'slug-name',    // Optional: changelog slug (links to /changelog/{slug})
  pr: 1234,                  // Optional: GitHub PR number
}

Quarter Format

{
  id: 'q4-2025',             // Format: q{1-4}-{year}
  label: 'Q4 2025',          // Display label
  status: 'current',         // 'completed' | 'current' | 'planned'
}

Featured Item Format (CURATED — DO NOT MODIFY without explicit user request)

{
  id: 'unique-id',           // kebab-case identifier
  icon: 'RiIconName',        // React Icons (Remix) name
  title: 'Initiative Title',
  tagline: 'Short tagline',
  description: 'Longer description...',
  benefits: 'User-visible benefit...',
  status: 'shipped',         // 'shipped' | 'in-progress' | 'planned'
  quarter: 'q1-2026',        // Quarter ID
  changelog: 'slug-name',    // Optional
  pr: 1234,                  // Optional
  experimental: true,        // Optional
}

Hard cap: 6 entries in featured: []. Only edit when the user explicitly asks.

Common Tasks

1. Mark Milestone as Shipped

When a feature ships:

1. Find the milestone in website/src/data/roadmap.js
2. Update status: 'shipped'
3. Add changelog: 'changelog-slug' if announcement exists
4. Recalculate initiative progress percentage

Example:

// Before
{ label: 'EKS Kubeconfig integration', status: 'in-progress', quarter: 'q4-2025' },

// After
{ label: 'EKS Kubeconfig integration', status: 'shipped', quarter: 'q4-2025', changelog: 'eks-kubeconfig-integration' },

2. Calculate Progress Percentage

Progress = (shipped milestones / total milestones) * 100

// Count milestones
const shipped = milestones.filter(m => m.status === 'shipped').length;
const total = milestones.length;
const progress = Math.round((shipped / total) * 100);

3. Add New Milestone

When adding planned work:

1. Add to the appropriate initiative's milestones array
2. Set status: 'planned'
3. Set quarter to target quarter
4. Update progress percentage (will decrease since total increased)

4. Link to Changelog

Find changelog slugs in website/blog/:

# Find changelog files
ls website/blog/*.mdx

# Check frontmatter for slug
head -20 website/blog/2025-01-15-feature-name.mdx

The slug in frontmatter becomes the changelog link path. For the post itself, use the changelog skill.

5. Add New Quarter

When a new quarter starts:

1. Add quarter to quarters array in roadmap.js
2. Update previous quarter's status to 'completed'
3. Set new quarter's status to 'current'

quarters: [
  { id: 'q3-2025', label: 'Q3 2025', status: 'completed' },
  { id: 'q4-2025', label: 'Q4 2025', status: 'current' },    // Current
  { id: 'q1-2026', label: 'Q1 2026', status: 'planned' },
],

6. Add New Initiative

When adding a new strategic initiative:

1. Add to initiatives array
2. Choose appropriate icon from React Icons (Remix set - Ri* prefix)
3. Start with progress: 0 and status: 'planned'
4. Add initial milestones

{
  id: 'new-initiative',
  icon: 'RiRocketLine',
  title: 'New Initiative',
  tagline: 'Brief tagline',
  description: 'Detailed description of the initiative goals...',
  progress: 0,
  status: 'planned',
  milestones: [
    { label: 'First milestone', status: 'planned', quarter: 'q1-2026' },
  ],
  issues: [],
},

Workflow for Updates

1. Identify what changed

   • New feature shipped? → Update milestone status
   • New changelog published? → Link milestone to changelog
   • New quarter started? → Update quarter statuses
   • New work planned? → Add milestones

2. Edit website/src/data/roadmap.js

   • Make targeted changes
   • Recalculate progress percentages

3. Verify the build

   cd website && npm run build
   

4. Preview if needed

   cd website && npm run start
   # Visit http://localhost:3000/roadmap
   

Auditing Roadmap Accuracy

Periodically verify roadmap against actual releases:

# Check recent changelog entries
ls -la website/blog/ | tail -20

# Check recent PRs for shipped features
gh pr list --state merged --limit 20 --repo cloudposse/atmos

# Search for features mentioned in roadmap
grep -r "feature-name" website/blog/

Icon Reference

Common icons (React Icons Remix set):

• RiLockLine - Authentication/Security
• RiFlashlightLine - Performance/DX
• RiSearchLine - Discoverability
• RiFlowChart - Workflows
• RiPlugLine - Extensibility
• RiBox3Line - Vendoring/Packaging
• RiGitBranchLine - CI/CD
• RiExchangeLine - Migration
• RiShieldCheckLine - Quality
• RiBookOpenLine - Documentation
• RiRocketLine - New features
• RiCodeLine - Development
• RiToolsLine - Tooling

Quality Checks

Before completing any roadmap update:

• Progress percentages are accurate (shipped/total * 100)
• Initiative status reflects milestone states
• Changelog links are valid slugs
• Quarter statuses are consistent (only one 'current')
• Website builds successfully
• Did NOT add to featured[] without explicit user request
• featured[] still contains <= 6 entries
• No changelog post for an internal-only refactor (would a user notice the change? if not, no post)

Related skills

• changelog skill — owns the blog post template, tags, authors, and style rules for the post a milestone links to. This skill only owns roadmap.js; hand off post-writing to changelog.
• pull-request skill — decides whether a roadmap update is required at all (only minor/major PRs).

Self-Maintenance

This skill should be updated when:

• Roadmap data structure changes
• New initiative categories are added
• Component structure changes

Dependencies:

• website/src/data/roadmap.js - Primary data file
• website/src/components/Roadmap/ - Component structure
• website/blog/ - Changelog entries for linking