ai-workflow-skill/docs/tests/orch/README.md

Orch Markdown Test Plan

Purpose

This directory contains the human-readable Markdown test plan for the orch CLI.

It complements automated Go tests. The goal is to preserve the user-visible scheduler contract in a form that can be reviewed, extended, and executed manually without re-deriving command behavior from implementation code.

Directory Rules

• one folder per orch leaf command or shared area
• each folder keeps a README.md entrypoint
• command folders use README.md as an index only
• each command test case lives in its own Markdown file named after the case slug
• no numeric test IDs
• each command case is identified by its concrete file path

Case file naming pattern:

<case-slug>.md

Authoring Principles

• focus on externally visible CLI behavior rather than store internals
• prefer stable command sequences that a new agent can replay against a temp database
• document both success contracts and failure boundaries
• reuse scenarios from automated orch integration tests before inventing new cases
• keep terminology consistent with the scheduler concepts exposed by orch: run, task, dependency, attempt, blocked task, worktree, and council review

Common Execution Model

Most cases in this directory assume the same baseline:

1. create an isolated temporary directory
2. choose a database path such as TMPDIR/coord.db
3. run the target orch command sequence with --db TMPDIR/coord.db --json
4. when a case needs worker-side state transitions, drive them through inbox against the same database

Unless a case says otherwise:

• commands should use --json
• assertions should check both exit code and JSON payload
• orch may be pointed at an empty database path; schema bootstrapping happens automatically on open

Folder Map

• README.md: global conventions and glossary
• ROADMAP.md: document progress, planned case backlog, and authored-case register
• _shared/README.md: reusable fixtures, JSON assertions, exit-code rules, and worktree conventions
• workflows/README.md: cross-command end-to-end scenarios
• per-command folders: one leaf-command directory per implemented orch command surface

Glossary

• run: one coordinated execution for a user request
• task: one schedulable unit of work inside a run
• dependency: an edge that gates one task on another
• attempt: one execution try for a task
• dispatch: the act of materializing a task into an inbox thread
• workspace: the branch and worktree assigned to a code-writing attempt
• blocked task: a task whose active attempt requires clarification or another external decision
• council review: a higher-level workflow built on top of orch that dispatches fixed reviewer roles and tallies recommendations

Relationship To Automated Tests

The current best executable reference is integration_test.go.

When this Markdown plan expands:

• prefer matching an existing automated scenario first
• record any additional manual-only contract coverage explicitly in the relevant command case file
• keep ROADMAP.md synchronized with authored files and case slugs