docs: add execution roadmap workflow

2026-03-19 12:52:02 +08:00
parent 72d7caa552
commit b110bb24d9
8 changed files with 238 additions and 0 deletions
@@ -23,6 +23,7 @@ As of now:
 - a human-readable inbox command test-plan set has been authored under `docs/tests/inbox/`
 - a reusable Codex skill package for `inbox` now exists under `skills/inbox/`, with a formal `SKILL.md`, `agents/openai.yaml`, and a bundled CLI binary asset
 - an inbox skill forward-test plan directory now exists under `docs/tests/inbox-skill/`, with a shared execution template and multiple scenario cases
+- an execution-roadmap workflow now exists under `docs/roadmaps/active/` and `docs/roadmaps/archive/` for agent-level work traces and completion archives
 - `orch` currently exists as a command skeleton only
 - no scheduler workflows have been implemented yet

@@ -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
@@ -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/`
@@ -0,0 +1 @@
+
@@ -0,0 +1 @@
+
@@ -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
@@ -29,6 +29,55 @@ Use these defaults unless a case file explicitly overrides them:
 - require every agent to coordinate through the bundled CLI and shared SQLite DB instead of ordinary chat
 - validate the final inbox state independently from the main thread after the agents stop

+## How An Agent Runs These Cases
+
+Use one test-runner agent to execute each case.
+
+The test-runner agent is responsible for:
+
+- reading this `README.md` first, then one specific case file
+- creating an isolated temporary directory and SQLite DB path for that run
+- launching the role agents described in `Agent Topology`
+- injecting the same `skills/inbox/` bundle into every role agent
+- passing each role agent the prompt text from the case file with concrete values substituted for `SKILL_PATH`, `TMPDIR`, and `THREAD_ID` when needed
+- coordinating launch order or parallel start according to the case file
+- collecting agent final summaries as evidence
+- resolving the final `THREAD_ID`
+- running the `Validation Commands` from the main thread after the role agents stop
+- comparing the observed results against `Expected Outcomes` and `Assertions`
+- returning a final pass/fail judgment with concrete evidence
+
+The role agents are responsible for:
+
+- acting only within the role assigned in the case file
+- using the injected inbox skill rather than ad hoc repository discovery
+- coordinating through the bundled CLI and shared DB
+- reporting the concrete thread id, key command outcomes, and final observed state back to the test-runner agent
+
+The test-runner agent should treat a case as passed only when:
+
+- all role agents reach a final state without violating the case contract
+- the independent validation commands succeed
+- the final inbox state matches the assertions in the case file
+
+The test-runner agent should treat a case as failed when:
+
+- any role agent times out or stalls
+- a required inbox action is skipped
+- a role agent falls back to ordinary chat for critical coordination
+- the final inbox state conflicts with the documented assertions
+
+The test-runner agent should report results in this shape:
+
+- `case`
+- `db_path`
+- `thread_id`
+- `result`: `pass` or `fail`
+- `agent_summaries`
+- `validation_evidence`
+- `assertion_checklist`
+- `notes`
+
 ## Default Timeouts

 Use these defaults unless a case file explicitly overrides them: