docs: add execution roadmap workflow

docs/roadmaps/README.md

@@ -0,0 +1,64 @@
+# 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

docs/roadmaps/TEMPLATE.md

@@ -0,0 +1,50 @@
+# Title
+
+## Status
+
+- `in_progress`
+
+## Owner
+
+- agent or workstream owner
+
+## Started At
+
+- `YYYY-MM-DD`
+
+## Goal
+
+- one or two sentences describing the intended outcome
+
+## Scope
+
+- what is in scope
+- what is explicitly out of scope if needed
+
+## Checklist
+
+- [ ] define the concrete work items
+- [ ] implement or document the next step
+- [ ] validate the result
+- [ ] update any required project-level roadmap
+
+## Files
+
+- list the primary files expected to change
+
+## Decisions
+
+- record key decisions and why they were taken
+
+## Blockers
+
+- list current blockers
+- write `none` if there are no blockers
+
+## Next Step
+
+- describe the next action another agent should take
+
+## Completion Summary
+
+- fill this in when moving the file to `archive/`

docs/roadmaps/active/.gitkeep

@@ -0,0 +1 @@
+

docs/roadmaps/archive/.gitkeep

@@ -0,0 +1 @@
+

docs/roadmaps/archive/add-execution-roadmap-workflow.md

@@ -0,0 +1,61 @@
+# Add Execution Roadmap Workflow
+
+## Status
+
+- `completed`
+
+## Owner
+
+- codex
+
+## Started At
+
+- `2026-03-19`
+
+## Goal
+
+- introduce a repository-level execution-roadmap workflow so substantial agent work leaves a durable trace while active and a completion record after archiving
+
+## Scope
+
+- update `AGENTS.md` with active/archive roadmap rules
+- create `docs/roadmaps/README.md`
+- create `docs/roadmaps/TEMPLATE.md`
+- create tracked `active/` and `archive/` directories
+- update `docs/implementation-roadmap.md`
+
+## Checklist
+
+- [x] define the execution-roadmap workflow and naming rules
+- [x] update `AGENTS.md` to require active roadmap files for substantial multi-step work
+- [x] add `docs/roadmaps/README.md`
+- [x] add `docs/roadmaps/TEMPLATE.md`
+- [x] create tracked `docs/roadmaps/active/` and `docs/roadmaps/archive/`
+- [x] update `docs/implementation-roadmap.md`
+
+## Files
+
+- `AGENTS.md`
+- `docs/roadmaps/README.md`
+- `docs/roadmaps/TEMPLATE.md`
+- `docs/roadmaps/active/.gitkeep`
+- `docs/roadmaps/archive/.gitkeep`
+- `docs/implementation-roadmap.md`
+
+## Decisions
+
+- use `docs/roadmaps/active/` and `docs/roadmaps/archive/` rather than a single mixed directory
+- keep project-level roadmaps separate from per-workstream execution traces
+- require one roadmap file per substantial workstream rather than one file per tiny action
+
+## Blockers
+
+- none
+
+## Next Step
+
+- use `docs/roadmaps/TEMPLATE.md` as the starting point for the next substantial multi-step task
+
+## Completion Summary
+
+- the repository now has a documented execution-roadmap workflow, tracked directories for active and archived workstreams, and a reusable template for future agents