---
applyTo: "agentic_devtools/cli/workflows/**,agentic_devtools/prompts/**,docs/workflow-expectations/**"
---

# Living Workflow Expectation Docs

The `docs/workflow-expectations/` directory holds general-purpose expectation
documents — one per agentic-devtools *initiate workflow* command — each with a
Mermaid `## Workflow Diagram`. They are a source of truth for how the initiate
workflows behave and are the canonical starting point for the
`agdt.test-workflow` agent (which copies and specializes them per command +
flags).

This requirement is mandated by the project constitution
(`.specify/memory/constitution.md`, principle
*XV. Living Workflow Expectation Docs*).

## For coding agents

Whenever you change an initiate workflow's behavior, parameters, or decision
paths — for example in `agentic_devtools/cli/workflows/**` (commands, preflight,
worktree setup, engine resolution, base) or the related prompt templates under
`agentic_devtools/prompts/**` — you MUST, in the **same pull request**:

1. Update the matching `docs/workflow-expectations/<command-name>.md` document so
   its Parameters & State Keys, Decision Points / Paths, Execution Flow,
   Observable Side Effects, Success Criteria, and **AI Agent Session
   Choreography** (entrypoint prompt, per-step prompts, expected `agdt-*`
   commands, subagent/nested-workflow handoffs, and transition triggers) reflect
   the new behavior.
2. Update that document's Mermaid `## Workflow Diagram` (and, for multi-step
   workflows, the `## Agent Session Choreography Diagram`) to match the new
   paths, and validate that the diagrams are syntactically correct.
3. Keep the document accurate to the code — trace the actual execution path
   rather than guessing.

If you add a **new** initiate workflow, add a new
`docs/workflow-expectations/<command-name>.md` document (with a diagram) and link
it from `docs/workflow-expectations/README.md`.

## For reviewing agents

When reviewing a pull request that touches `agentic_devtools/cli/workflows/**` or
`agentic_devtools/prompts/**`, you MUST confirm that:

- The matching `docs/workflow-expectations/<command-name>.md` document was updated
  in the same pull request when the workflow's behavior, parameters, or decision
  paths changed.
- The document's **AI Agent Session Choreography** section still accurately
  describes how the AI agent is guided through the workflow (entrypoint prompt,
  per-step prompts, expected `agdt-*` commands, subagent/nested-workflow
  handoffs, and transition triggers).
- The document's Mermaid `## Workflow Diagram` (and any
  `## Agent Session Choreography Diagram`) matches the updated code paths.
- Any new initiate workflow ships with a corresponding document and a README link.

Treat a behavior, parameter, or path change without a corresponding documentation
update as a review blocker.
