# Roadmap

> Maintain and update the Atmos roadmap page (website/src/data/roadmap.js): milestone/initiative/quarter schema, progress-percentage math, the curated featured[] cap (max 6, never auto-modified), and the no-changelog-for-internal-refactors gate. Invoke when adding/updating milestones, initiatives, or quarters, or linking a milestone to a changelog post.

- Skill: `cloudposse/roadmap` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cloudposse/roadmap`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cloudposse/roadmap/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: cloudposse (https://skillmd.com/u/cloudposse)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cloudposse/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

| File | Purpose |
|------|---------|
| `website/src/data/roadmap.js` | **Primary data file** - All initiatives, milestones, quarters, progress |
| `website/src/components/Roadmap/` | React components (rarely need changes) |
| `website/blog/` | Changelog entries to link from milestones |

## Data Structure

### Initiative Format

```javascript
{
  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

```javascript
{
  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

```javascript
{
  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)

```javascript
{
  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:**
```javascript
// 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

```javascript
// 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/`:

```bash
# 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'`

```javascript
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

```javascript
{
  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**
   ```bash
   cd website && npm run build
   ```

4. **Preview if needed**
   ```bash
   cd website && npm run start
   # Visit http://localhost:3000/roadmap
   ```

## Auditing Roadmap Accuracy

Periodically verify roadmap against actual releases:

```bash
# 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