Skip to main content

Feature Maps

A coordination layer above epics for orchestrating large programs with inter-epic dependencies and wave-based dispatch.

When Epics Outgrow Themselves

SPOQ epics work well for focused initiatives — 5 to 20 tasks, one dependency graph, one validation pass. But some programs span multiple subsystems, each deserving its own epic with its own architecture, tasks, and success criteria. Forcing everything into a single epic produces a monolith: hard to validate, impossible to resume, and fragile under parallel execution.

Maps solve this by defining a DAG of epics instead of a DAG of tasks. Each epic retains full autonomy — its own EPIC.md, task YAMLs, validation scores, and execution history. The map purely orchestrates which epics can execute in parallel and which must wait for upstream deliverables.

Like epics, maps follow a 3-tier lifecycle: backlog, active, and complete. A backlog map (spoq/maps/backlog/) captures planned programs that are not yet ready for execution. Promoting a map to active signals that its constituent epics should be planned and dispatched. This tiered approach lets teams stage large initiatives without cluttering the active execution pipeline.

Anatomy of a MAP.md

Every map lives in its own directory under spoq/maps/active/ and contains a single MAP.md file. The format mirrors EPIC.md but operates at a higher abstraction level.

Vision

Program-level objective spanning all epics (2-5 sentences)

Program Structure

ASCII diagram showing epic relationships and data flow

Epics

Per-epic entries with slug, status, hours, dependencies, and summary

Epic Dependencies

ASCII DAG of inter-epic relationships

Dispatch Strategy

Which epics execute in which waves, with rationale

Success Criteria

Program-level acceptance criteria spanning epic boundaries

Estimated Effort

Per-epic hours, wave assignments, and critical path duration

Risk Assessment

Cross-epic integration risks with likelihood and mitigation

How Maps Coordinate Epics

1. Define the Program

Create a MAP.md listing each epic by slug with its estimated hours and dependencies. Use spoq_generate_map_skeleton to scaffold the initial structure, or write it manually from the template at .claude/skills/epic-planning/assets/map-template.md.

2. Validate the DAG

spoq_validate_map checks that all required sections exist, dependency references point to real epic slugs, and the inter-epic graph is acyclic. No false starts.

3. Compute Waves and Critical Path

spoq_compute_epic_waves applies topological sort at the epic level, producing wave assignments. The critical path analysis identifies the minimum completion time regardless of parallelism.

4. Plan and Execute Each Epic

Epics within each wave are planned and executed independently using the standard /epic-planning and /agent-execution workflows. The map tracks progress across all epics via spoq_get_map_status.

5. Track Program Progress

Status rolls up from individual task completions through each epic into the map. The overall progress percentage reflects how many tasks across all epics have been completed — giving a single number for the entire program.

MCP Tools for Map Management

Eight MCP tools mirror the epic tool set at the inter-epic level. All are available automatically via the SPOQ MCP server.

spoq_parse_map

Extract metadata, resolve epics against disk, aggregate stats

spoq_validate_map

Check structure, dependencies, and detect cycles in the inter-epic DAG

spoq_compute_epic_waves

Topological sort producing epic-level wave assignments

spoq_analyze_map_dag

Critical path analysis, parallelism metrics, and effort estimation

spoq_estimate_map_effort

Per-wave and total effort breakdown across epics

spoq_get_map_status

Per-epic task rollup with overall program completion percentage

spoq_list_maps

Scan active and completed map directories

spoq_generate_map_skeleton

Generate a MAP.md template with auto-wired epic entries across waves

When to Use Maps vs. Single Epics

Use a Single Epic When
  • Total scope is under 20 tasks
  • All tasks share one architecture and codebase area
  • Dependencies form a single connected graph
  • One validation pass covers the whole deliverable
Use a Map When
  • Scope exceeds 20 tasks across distinct subsystems
  • Work streams can execute independently per wave
  • Each subsystem needs its own architecture and success criteria
  • Program-level coordination is needed across epic boundaries

Getting Started with Maps

# Generate a map skeleton

/epic-planning --map "My Program Name"

# Or via MCP tool directly

spoq_generate_map_skeleton(name="my-program", epic_count=4)

# Validate the map

spoq_validate_map(map_path="spoq/maps/active/my-program")

# Analyze the program DAG

spoq_analyze_map_dag(map_path="spoq/maps/active/my-program")