Roadmap and Epic Planning

Status: Emerging Type: Organizational (Recommended)

Problem

Coding agents work effectively when a task has explicit scope and acceptance criteria, but repositories often lack the layer that connects product intent to the next independently deliverable change. Work then lives in chat history, issue trackers, or oversized planning documents, and every session has to reconstruct priorities, dependencies, and delivery boundaries.

A repository needs a compact planning model that preserves medium-term direction without turning .context/ into a second project-management system.

Context

When to Use This Pattern

• A repository has several related changes that need sequencing over weeks or months.
• Humans and coding agents collaborate across multiple implementation sessions.
• Work benefits from explicit outcomes, dependencies, acceptance criteria, and delivery boundaries.
• A pull request needs a stable link to the planning context that motivated it.

When NOT to Use This Pattern

• A trivial repository has no meaningful medium-term plan.
• A one-off change is fully described by an issue or pull request and does not belong to a broader initiative.
• The organization-wide roadmap belongs outside a single repository. This pattern covers repo-local planning context, not portfolio management.

Audience & Scope

This pattern governs repository-local roadmaps and epics stored under .context/. Repository Context Directory defines where those artifacts live; this pattern defines their identity, metadata, contents, lifecycle, and delivery conventions.

Solution

Use three planning levels, each answering a different question:

Roadmap                  Where are we going and why?
└── Phase                What intermediate outcome must become true?
    └── Epic             What atomic change will we deliver?
        └── Tasks        What implementation work remains?

• A roadmap describes a medium-term outcome and sequences the intermediate outcomes needed to reach it.
• A phase is a section inside a roadmap describing one verifiable intermediate outcome. It is not a separate file or a time box.
• An epic is an atomic, independently reviewable and deliverable unit of development, normally implemented by one pull request.
• Tasks are the operational decomposition of an epic. They live in plan.md or, when separation improves readability, in an optional tasks.md.

Roadmaps reference epics; they do not contain epic directories. An epic keeps its identity when priorities or phase ordering change.

Structure

.context/
├── roadmaps/
│   └── YYYYMMDD-<slug>.md
└── epics/
    └── YYYYMMDD-<slug>/
        ├── spec.md                 # Required: delivery contract
        ├── plan.md                 # Required: implementation approach
        ├── design.md               # Optional: alternatives and detailed design
        ├── tasks.md                # Optional: extracted work queue
        └── handoff.md              # Optional: continuation state between sessions

All paths stored in metadata are relative to the repository root. Markdown links in document bodies remain relative to the document containing them.

Identity and Naming

Roadmaps and epics MUST use YYYYMMDD-<slug> as their identifier:

20260710-multi-tenant-platform
20260714-organization-domain-model

• YYYYMMDD MUST be the artifact creation date, not its target or delivery date.
• <slug> MUST be a short, descriptive kebab-case name.
• The identifier MUST NOT change when scheduling, status, phase, or delivery dates change.
• A roadmap's id MUST equal its filename without .md.
• An epic's id MUST equal its directory name.

The date and slug together are the complete identifier. No independent sequence number is required.

Common Metadata

Every roadmap and epic MUST begin with YAML frontmatter containing this common core:

---
id: 20260710-multi-tenant-platform
title: Multi-tenant platform
status: active
created: 2026-07-10
related:
  - .context/prd/current.md
  - .context/architecture/overview.md
---

related provides context; it does not express execution order. Dependencies between epics belong in depends_on.

When progress cannot continue, preserve the lifecycle state and add a blocking condition:

blocked:
  since: 2026-07-18
  reason: Waiting for approval of the data isolation strategy

Both since and reason are required when blocked is present. Remove the block when progress can resume.

Shared Lifecycle

Roadmaps and epics MUST use the same lifecycle states:

The normal flow is:

proposed → planned → active → completed
     └───────────────→ cancelled

blocked is not a lifecycle state. External workflow states such as draft, in review, approved, or merged also MUST NOT be added to this lifecycle; they belong to the delivery system.

Roadmaps

A roadmap is one Markdown file containing its phases as sections. It MUST describe:

• The outcome the roadmap intends to achieve.
• Relevant context and current state.
• Success criteria for the roadmap as a whole.
• Constraints, dependencies, risks, and explicit exclusions.
• An ordered set of phases.

Each phase MUST define:

• A stable kebab-case slug used by epic metadata.
• An intermediate outcome, expressed as an observable system capability or property.
• Completion criteria.
• The epics currently expected to produce that outcome.
• Phase-specific dependencies, risks, or exclusions when relevant.

Phases SHOULD be headings in the roadmap rather than separate files:

## Phase: Domain foundations

`phase: domain-foundations`

### Outcome

The system can represent organizations and associate owned resources with them.

### Completion criteria

- Every persisted resource has an organization owner.
- Existing data can be migrated without ownership ambiguity.

### Epics

- [Organization domain model](../epics/20260714-organization-domain-model/spec.md)

Phase numbering MAY be displayed for readability, but the phase slug is its stable reference. Reordering phases MUST NOT require changing epic metadata.

Epics

An epic is the smallest unit managed by this planning model. It MAY span multiple tasks, commits, agent sessions, or contributors, but it MUST produce one coherent delivery.

An epic MUST:

• Have an observable outcome and verifiable acceptance criteria.
• Be reviewable and integrable independently.
• Declare its scope, exclusions, constraints, and dependencies.
• Avoid bundling multiple changes that could deliver value independently.
• Normally map to one branch and one pull request.

Epic Metadata

The canonical metadata lives in spec.md:

---
id: 20260714-organization-domain-model
title: Organization domain model
type: feat
status: planned
created: 2026-07-14
roadmap: 20260710-multi-tenant-platform
phase: domain-foundations
depends_on: []
related:
  - .context/architecture/overview.md
delivery:
  type: pull-request
---

In addition to the common metadata:

An epic MAY exist outside a roadmap, for example for emergent maintenance. In that case omit both roadmap and phase.

delivery is an extensible object:

delivery:
  type: pull-request
  url: https://github.com/ontopix/example/pull/42

Before the pull request exists, omit url. Non-code epics MAY use another explicit delivery type and path or URL.

Epic Types

Epic types MUST use the closed set defined by Git & Commit Conventions, which is the canonical source for the available types and their meaning.

The epic type describes the primary intent of the complete delivery. Individual commits MAY use different types when that more accurately describes each commit. A breaking change is expressed with breaking: true, never with a separate type.

spec.md

spec.md is required and is the delivery contract. It SHOULD contain:

• Outcome and motivation.
• Scope and explicit out of scope.
• Functional and non-functional requirements where applicable.
• Acceptance criteria.
• Constraints and dependencies.
• Delivery or rollout considerations.
• Links to the roadmap, phase, and relevant context.

plan.md

plan.md is required before an epic becomes planned. It SHOULD contain:

• The implementation approach.
• Relevant findings from the current repository.
• Components and interfaces expected to change.
• Ordered implementation tasks, or a link to tasks.md.
• Validation strategy.
• Compatibility, migration, or rollout work.
• Implementation risks and open questions.

Supporting documents SHOULD contain only a back-reference to the canonical epic metadata:

---
epic: 20260714-organization-domain-model
---

Optional design.md

Create design.md when alternatives, diagrams, prototypes, or substantial technical reasoning would obscure the delivery contract. Decisions that remain authoritative beyond the epic MUST be promoted to the repository's architecture decisions rather than left only in design.md.

Optional tasks.md

Tasks normally live in plan.md. Extract them to tasks.md when the work queue is long, contains a non-trivial dependency graph, or benefits from frequent updates independent of the implementation narrative.

Tasks MUST live in plan.md or tasks.md, not be duplicated in both. When tasks.md exists, plan.md MUST link to it.

Optional handoff.md

Create handoff.md when an active epic will continue in another session. It captures volatile continuation state, not durable requirements or design decisions:

---
epic: 20260714-organization-domain-model
updated: 2026-07-18
---

It MUST state the current implementation state, work completed in the session, one concrete next action, validation performed and still required, Git and delivery state, and any blockers or decisions needed. Remove it when the epic is completed; Git retains its history.

Branches, Workspaces, and Pull Requests

Branch and workspace naming is governed by Git & Commit Conventions. Applying that pattern to an epic produces:

<type>/<epic-id>

For example:

feat/20260714-organization-domain-model

A filesystem workspace uses the corresponding sanitized name:

feat-20260714-organization-domain-model

Pull request titles, final squash commits, and intermediate commits follow the same canonical Git pattern. This planning pattern only supplies the epic type and stable identifier used by that convention.

The epic remains active while its delivery is being implemented or reviewed. Mark it completed only after the delivery is integrated and its acceptance criteria are verified.

Planning Status

Tooling MAY derive a planning status view from roadmap and epic metadata, roadmap references, dependencies, tasks, delivery information, and handoffs. A derived view MUST NOT become a second source of truth or be committed as a manually maintained status document.

A useful status capability SHOULD show:

• Active, planned, blocked, completed, and cancelled work by roadmap and phase.
• Completed epic count without presenting it as an effort percentage.
• Broken references or invalid metadata before recommendations.
• Active work and its next action.
• Planned epics whose dependencies are completed.

When recommending the next work, prefer an unblocked active epic, then an unblocked planned epic with completed dependencies, following roadmap phase and epic order. Tool-specific implementations MAY expose this capability as a skill, command, or user interface.

Epic Session Protocol

Start Epic

Starting an epic means beginning or resuming a work session; it does not create a second epic lifecycle. Before implementation, a human or agent MUST:

1. Validate the epic identity, metadata, roadmap, phase, dependencies, and blocking condition.
2. Read spec.md, plan.md, optional supporting files, an existing handoff.md, the relevant roadmap phase, and necessary related context.
3. Inspect the current repository, expected branch and workspace, delivery state, and uncommitted work.
4. Confirm the plan still matches the code and run an appropriate validation baseline.
5. Safely reuse or create the branch defined by Git conventions.
6. Change planned to active only when implementation actually begins.
7. State the session objective, expected stopping point, scope, and next action before editing code.

The start operation MUST stop without destructive Git actions when local state, dependencies, blockers, or invalid context make the session unsafe to begin.

End Epic

Ending an epic means closing the current work session; it does not automatically complete the epic. Before ending, a human or agent MUST:

1. Review the complete diff and confirm it belongs to the epic.
2. Run relevant validations and distinguish passing, failing, and not-run checks.
3. Update task checkboxes in tasks.md when present, otherwise in plan.md.
4. Update status, delivery, and blocking metadata only when supported by actual state.
5. Promote durable knowledge to architecture, patterns, operations, or API documentation.
6. When work remains, create or update handoff.md so another session can continue without conversation history.
7. Record a single concrete next action and surface uncommitted or unpushed Git state.
8. Revalidate the planning context before reporting the session outcome.

An incomplete epic remains active; a blocked condition is added separately. An epic becomes completed only after its delivery is integrated and its acceptance criteria are verified.

Retention and Promotion

Completed epics MAY remain while they provide useful context for an active roadmap or the current system. Before removing an epic, promote durable knowledge to its canonical home:

• Architectural decisions to architecture/decisions/.
• Reusable conventions to patterns/.
• Operational knowledge to operations/.
• Current contracts to api/ or architecture documentation.

Do not create archive directories. Git and the delivery system retain historical versions after an epic no longer contributes current context.

Implementation

1. Create .context/roadmaps/ and .context/epics/ when the repository first needs medium-term planning.
2. Add one YYYYMMDD-<slug>.md roadmap and define its outcome, success criteria, and phases.
3. Create an epic directory for each independently deliverable change.
4. Write spec.md, then prepare plan.md before marking the epic planned.
5. Create the <type>/<epic-id> branch and deliver the epic through its declared mechanism.
6. Update status and delivery metadata as work progresses.
7. Verify acceptance criteria before marking the epic and its containing roadmap outcomes completed.
8. Promote durable knowledge before deleting planning artifacts that no longer provide current context.

Consequences

Applies Principles

• Human-AI Collaboration — agents receive bounded, persistent, executable context.
• Simplicity First — phases stay inside one roadmap file and optional files appear only when useful.
• Ownership & Responsibility — each epic has explicit outcomes, dependencies, lifecycle, and delivery.
• Long-Term Thinking — durable knowledge is promoted out of temporary planning artifacts.
• Consistency — identifiers and metadata connect planning to Git and delivery workflows.

Related Patterns

• Repository Context Directory — canonical location and semantics for repository-local context.
• Git & Commit Conventions — canonical epic types, branch naming, pull request titles, and squash commits.
• AI Agent Entrypoint — operational entrypoint agents use before loading task-specific context.
• Pattern Authoring — rules for evolving this organizational standard.

References

• Conventional Commits 1.0.0 — commit type and breaking-change semantics.
• Core Engineering Principles — values applied by this pattern.