ai-workflow-skill/docs/roadmaps/README.md

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:

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 for project-level implementation state
• use ../tests/inbox/ROADMAP.md for inbox test-plan state
• use this directory for per-workstream execution tracking