Shipkit Spec Roadmap

shipkit-spec-roadmap — Spec Prioritization Roadmap

Purpose: Bridge the gap between definitions and specs by building an explicit prioritization roadmap. Scores features by goal-gate phasing, dependency depth, foundation value, and mechanism complexity to determine spec order.

Output format: JSON — structured roadmap at .shipkit/spec-roadmap.json

---

When to Invoke

User triggers:

• "What should I spec first?"
• "Prioritize the features"
• "Create a spec roadmap"
• "Spec backlog"
• "What order should I write specs?"

Before:

• /shipkit-spec (this determines WHICH spec to write next)

After:

• /shipkit-product-definition (need features to prioritize)
• /shipkit-engineering-definition (need mechanisms for effort estimation)
• /shipkit-product-goals (recommended — gates drive phasing)

Workflow position:

• After definitions are complete, before writing individual specs
• Can be re-run after new features are added or priorities change

---

Prerequisites

Required:

• .shipkit/product-definition.json — features to prioritize
• .shipkit/engineering-definition.json — mechanisms for effort estimation

Recommended:

• .shipkit/goals/*.json — gate definitions for phase mapping (especially goals/strategic.json or goals/product.json)

Optional:

• .shipkit/specs/ — detect already-specced features to mark as completed

If goals missing: Fall back to single-phase roadmap sorted by dependency + foundation value only.

---

Arguments

If $ARGUMENTS contains --update: Load existing spec-roadmap.json, refresh spec statuses, re-score, and present changes.

If $ARGUMENTS contains --regenerate: Discard existing roadmap and rebuild from scratch.

If $ARGUMENTS is empty: Check for existing file and offer choices.

---

Process

Step 0: Check Existing Roadmap

> Fork context — no user prompts. You are dispatched in a fork and have no user channel. Skip the file-exists menu entirely.

1. Read .shipkit/spec-roadmap.json (if exists)
2. If $ARGUMENTS contains --update: proceed to Step 1 with existing data as baseline
3. If $ARGUMENTS contains --regenerate or no file exists: proceed to Step 1 fresh
4. If file exists and no argument: read .shipkit/reviews/planning-assessment.json if present. If the latest review lists a gap against this artifact, archive the existing file to .shipkit/.archive/spec-roadmap.YYYY-MM-DD.json and regenerate addressing the gap. Otherwise, read the existing file and exit early with a "no changes needed" report — the reviewer already accepted it.

---

Step 1: Load Context

Read all context files in parallel (single message, multiple tool calls):

1. Read: .shipkit/product-definition.json    # Features, patterns, differentiators
2. Read: .shipkit/engineering-definition.json # Mechanisms, components, design choices
3. Read: .shipkit/goals/*.json               # Gates and criteria (glob for all goal files)
4. Read: .shipkit/why.json                   # Vision and purpose context
5. Read: .shipkit/codebase-index.json        # Existing code patterns and structure
6. Glob + Read: .shipkit/specs/**/*.json     # Existing specs (todo, active, shipped)

Extract from context:

• Features: ID, name, description, dependencies, mechanisms, mvp flag
• Mechanisms: ID, name, complexity indicators (design choices count, component count)
• Gates: ID, name, criteria list, which features map to which gate
• Existing specs: Which features already have specs (and their status)

---

Step 2: Build Feature-Mechanism-Gate Graph

For each feature in product-definition.json:

1. Map to gate: Which gate does this feature's criteria belong to? (from goals)

• If no goals exist, assign all features to a single "Default" phase

1. Map to mechanisms: Which mechanisms does this feature use? (from engineering-definition)
2. Map dependencies: What features must be specced/built before this one?
3. Map pain coverage: Which user pain points does this feature address? (from product-discovery if available)
4. Detect already-specced: Does a spec already exist in .shipkit/specs/?

---

Step 3: Score and Rank

For each unspecced feature, compute three scores:

Foundation Value (0-10): How many other features depend on this one?

• Count direct dependents + transitive dependents
• Higher score = more features unlocked by speccing this first

Pain Coverage (0-10): How many user pain points does this feature address?

• Count pain points from product-discovery.json that this feature addresses
• Weight by pain severity if available

Dependency Depth (0-N): How deep in the dependency chain is this feature?

• 0 = no dependencies (can be specced immediately)
• Higher = more prerequisites needed first

Effort Estimate (T-shirt size):

• Count mechanisms used by this feature
• Count design choices within those mechanisms
• Apply sizing:

| Size | Mechanisms | Design Choices | Typical Duration | |------|-----------|----------------|-----------------| | XS | 0 | 0 | Fork context — do not prompt for confirmation. Write the roadmap directly. The planning reviewer will flag any misalignment on the next review cycle.

---

Step 5: Write Roadmap

Use Write tool to create: .shipkit/spec-roadmap.json

JSON Schema: See references/output-schema.md for complete schema definition.

Example: See references/example.json for realistic roadmap.

---

Effort Estimation Guide

Effort is derived from mechanism complexity, NOT from implementation guesswork:

| Signal | What It Means | |--------|--------------| | Feature uses 0 mechanisms | Pure UI/content, XS effort | | Feature uses 1 mechanism with no design choices | Straightforward implementation, S | | Feature uses mechanisms with design choices | Each design choice = a decision point during implementation | | Feature has 3+ mechanisms | Cross-cutting concerns, likely L or XL | | Feature depends on unbuilt features | Effective effort includes prerequisite work |

Don't guess duration in days — use T-shirt sizes. The effortDays field is a rough midpoint for summary math only.

---

Completion Checklist

• [ ] Loaded product-definition.json and engineering-definition.json
• [ ] Loaded goals (if available) for gate-based phasing
• [ ] Detected already-specced features
• [ ] Built dependency graph with no cycles
• [ ] Scored all unspecced features (foundation, pain, depth)
• [ ] Assigned effort sizes from mechanism complexity
• [ ] Presented roadmap grouped by phase for user validation
• [ ] Wrote .shipkit/spec-roadmap.json

---

After Completion

Guardrails Check: Before moving to next task, verify:

1. Persistence - Has the roadmap been saved to .shipkit/spec-roadmap.json?
2. Next step - Suggest: "Run /shipkit-spec to start speccing the top-priority feature."
3. Session length - Long session? Consider /shipkit-work-memory for continuity.

Natural capabilities (no skill needed): Implementation, debugging, testing, refactoring, code documentation.

Suggest skill when: User needs to make decisions, create persistence, or check project status.

Success Criteria

Roadmap is complete when:

• [ ] JSON file conforms to Shipkit artifact convention ($schema, type, version, lastUpdated, source, summary)
• [ ] Every feature from product-definition.json is accounted for (either in phases or completed)
• [ ] Phases map to goal gates (or single "Default" phase if no goals)
• [ ] Priority order is defensible (dependency-first, then foundation value, then pain coverage)
• [ ] Effort sizes derived from mechanism complexity (not guessed)
• [ ] Dependency graph has no cycles and warnings are surfaced
• [ ] Already-specced features listed in completed array
• [ ] Summary counts match actual data
• [ ] File saved to .shipkit/spec-roadmap.json

---

Context Files This Skill Reads

Required (read if exist — error if missing):

• .shipkit/product-definition.json — Features to prioritize
• .shipkit/engineering-definition.json — Mechanisms for effort estimation

Recommended (read if exist):

• .shipkit/goals/*.json — Gate definitions for phase mapping
• .shipkit/why.json — Vision and purpose context
• .shipkit/codebase-index.json — Existing code patterns and structure

Optional (read if relevant):

• .shipkit/specs/**/*.json — Detect already-specced features
• .shipkit/product-discovery.json — Pain points for coverage scoring

---

Context Files This Skill Writes

Write Strategy: CREATE or UPDATE

Creates/Updates:

• .shipkit/spec-roadmap.json — Prioritized spec roadmap

Update Behavior:

• Full file replacement on each write
• Previous version is overwritten
• Use --update flag to refresh an existing roadmap

---

When This Skill Integrates with Others

Before This Skill

• /shipkit-product-definition — Defines features to prioritize (required)
• /shipkit-engineering-definition — Defines mechanisms for effort estimation (required)
• /shipkit-product-goals — Defines gates for phase mapping (recommended)

After This Skill

• /shipkit-spec — Uses roadmap to determine which feature to spec next
• /shipkit-plan — After specs are written, plans implementation

---

Remember: This skill bridges definitions and specs. It doesn't write specs — it tells you which specs to write first and why. The roadmap is a living document; re-run with --update as features get specced or priorities change.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stefan-stepzero
• Source: stefan-stepzero/shipkit
• License: MIT

Install and usage instructions live in the source repository linked above.