From b110bb24d9d129577504e05d546da7537ea6eac9 Mon Sep 17 00:00:00 2001 From: kurihada Date: Thu, 19 Mar 2026 12:52:02 +0800 Subject: [PATCH] docs: add execution roadmap workflow --- AGENTS.md | 11 ++++ docs/implementation-roadmap.md | 1 + docs/roadmaps/README.md | 64 +++++++++++++++++++ docs/roadmaps/TEMPLATE.md | 50 +++++++++++++++ docs/roadmaps/active/.gitkeep | 1 + docs/roadmaps/archive/.gitkeep | 1 + .../archive/add-execution-roadmap-workflow.md | 61 ++++++++++++++++++ docs/tests/inbox-skill/README.md | 49 ++++++++++++++ 8 files changed, 238 insertions(+) create mode 100644 docs/roadmaps/README.md create mode 100644 docs/roadmaps/TEMPLATE.md create mode 100644 docs/roadmaps/active/.gitkeep create mode 100644 docs/roadmaps/archive/.gitkeep create mode 100644 docs/roadmaps/archive/add-execution-roadmap-workflow.md diff --git a/AGENTS.md b/AGENTS.md index 523ae78..ce26598 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,6 +10,7 @@ Before starting substantial work, read the roadmap that matches the task: - implementation work: [docs/implementation-roadmap.md](/home/kurihada/project/ai-workflow-skill/docs/implementation-roadmap.md) - inbox Markdown test-plan work: [docs/tests/inbox/ROADMAP.md](/home/kurihada/project/ai-workflow-skill/docs/tests/inbox/ROADMAP.md) +- execution-trace workflow: [docs/roadmaps/README.md](/home/kurihada/project/ai-workflow-skill/docs/roadmaps/README.md) ## Roadmap Update Rule @@ -25,6 +26,16 @@ Required behavior: - when a test case is written, update authored-case tracking and pending backlog - when a planned item is no longer needed, mark it as removed or deferred instead of silently dropping it +For substantial multi-step work, also keep an execution roadmap under [docs/roadmaps/active/](/home/kurihada/project/ai-workflow-skill/docs/roadmaps/active/) while the work is in progress, then move it to [docs/roadmaps/archive/](/home/kurihada/project/ai-workflow-skill/docs/roadmaps/archive/) when the work is complete. + +Required behavior for execution roadmaps: + +- before starting substantial multi-step work, create or adopt one roadmap file under [docs/roadmaps/active/](/home/kurihada/project/ai-workflow-skill/docs/roadmaps/active/) +- write the intended task as checklist items and keep them updated as work progresses +- if work is unfinished, blocked, or paused, leave the roadmap in `active/` with current status and next step +- when all checklist items are complete, add a completion summary and move the file to `archive/` in the same change +- use stable slug filenames and prefer one roadmap file per workstream rather than one file per tiny action + ## Inbox Test-Plan Specific Rule For `docs/tests/inbox/`: diff --git a/docs/implementation-roadmap.md b/docs/implementation-roadmap.md index 75bed4e..8222b5b 100644 --- a/docs/implementation-roadmap.md +++ b/docs/implementation-roadmap.md @@ -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 diff --git a/docs/roadmaps/README.md b/docs/roadmaps/README.md new file mode 100644 index 0000000..5cb3daa --- /dev/null +++ b/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 diff --git a/docs/roadmaps/TEMPLATE.md b/docs/roadmaps/TEMPLATE.md new file mode 100644 index 0000000..4a91492 --- /dev/null +++ b/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/` diff --git a/docs/roadmaps/active/.gitkeep b/docs/roadmaps/active/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/docs/roadmaps/active/.gitkeep @@ -0,0 +1 @@ + diff --git a/docs/roadmaps/archive/.gitkeep b/docs/roadmaps/archive/.gitkeep new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/docs/roadmaps/archive/.gitkeep @@ -0,0 +1 @@ + diff --git a/docs/roadmaps/archive/add-execution-roadmap-workflow.md b/docs/roadmaps/archive/add-execution-roadmap-workflow.md new file mode 100644 index 0000000..8bf4036 --- /dev/null +++ b/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 diff --git a/docs/tests/inbox-skill/README.md b/docs/tests/inbox-skill/README.md index bb3ddcf..ac7fed8 100644 --- a/docs/tests/inbox-skill/README.md +++ b/docs/tests/inbox-skill/README.md @@ -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: