# Execution Roadmaps

## Purpose

This directory tracks agent execution roadmaps for substantial multi-step work.

These files are not project-level design roadmaps.
They are execution traces that make active work, partial progress, and unfinished state visible to the next agent.

## Directory Layout

- `active/`: in-progress, blocked, or paused workstreams
- `archive/`: completed workstreams kept for historical traceability
- `TEMPLATE.md`: starting point for new roadmap files

## Workflow

1. Before starting substantial multi-step work, create or adopt one roadmap file under `active/`.
2. Write the intended work as checklist items.
3. Update the checklist and status as work progresses.
4. If the work pauses or remains unfinished, leave the file in `active/` with the latest next step.
5. When the work is complete, add a completion summary and move the file to `archive/`.

## Naming

- use stable slug filenames
- prefer one roadmap file per workstream
- avoid creating a new roadmap file for trivial single-step actions

Example filename:

```text
docs/roadmaps/active/add-inbox-skill-tests.md
```

## Required Sections

Each roadmap file should include:

- `Title`
- `Status`
- `Owner`
- `Started At`
- `Goal`
- `Scope`
- `Checklist`
- `Files`
- `Decisions`
- `Blockers`
- `Next Step`
- `Completion Summary`

## Checklist Rule

- use Markdown checkboxes
- break work into concrete verifiable steps
- mark completed items with `- [x]`
- leave incomplete items visible rather than deleting them silently

## Relationship To Other Roadmaps

- use [../implementation-roadmap.md](../implementation-roadmap.md) for project-level implementation state
- use [../tests/inbox/ROADMAP.md](../tests/inbox/ROADMAP.md) for inbox test-plan state
- use this directory for per-workstream execution tracking