# Workflow Expectation Templates

This directory contains **general-purpose expectation documents** — one per
agentic-devtools *initiate workflow* command — together with an accompanying
[Mermaid](https://mermaid.js.org/) diagram for each.

They exist so that an AI agent auditing a workflow command (typically via the
[`agdt.test-workflow`](../../.github/prompts/agdt.test-workflow.prompt.md) agent)
can start from a comprehensive, code-accurate baseline and **specialize it**
for the exact command and flags under test, instead of reverse-engineering the
behavior from scratch every time.

## Purpose

Each document describes, in a reproducible and reviewable way:

- Every CLI flag and state key that changes the command's behavior.
- The branching decision points and the paths the command can take.
- The generalized execution flow.
- The observable side effects (files, state keys, worktrees, API calls, issues).
- The success criteria used to judge a correct run.
- The **AI agent session choreography** — how the Copilot agent is guided
  through the workflow *after* the session starts: which prompt opens the
  session, which prompts are presented at each step, which `agdt-*` commands the
  agent is expected to run, which subagents/handoffs are involved, and what
  event triggers each transition.
- A Mermaid flowchart that visualizes the decision tree. Multi-step workflows
  also include a second *Agent Session Choreography Diagram* that visualizes the
  agent's guided journey through the workflow steps.

Because these documents are general, they cover **all** paths a command can
take — not one specific invocation. A specialized expectations document (for a
single real run) is derived from the matching general template.

## How auditing agents use these templates

These files are **templates**, not run reports. The intended workflow is:

1. Identify the command under test (for example,
   `agdt-initiate-pull-request-review-workflow`).
2. Open the matching general template in this directory
   (`agdt-initiate-pull-request-review-workflow.md`).
3. Copy it to `.agdt-temp/EXPECTATIONS-<command-slug>.md`.
4. **Specialize** the copy for the exact command and flags being run: prune the
   paths that do not apply, fill in concrete identifiers, and trim the Mermaid
   diagram to the selected path.
5. Have a rubber-duck subagent review the specialized document, then proceed
   with the audit (execute, observe, fix, verify).

The general template is the **starting point**; the specialized copy under
`.agdt-temp/` is the per-run artifact.

## Directory layout

```text
docs/workflow-expectations/
  README.md                                                  <- this file
  agdt-initiate-pull-request-review-workflow.md
  agdt-initiate-work-on-jira-issue-workflow.md
  agdt-initiate-create-jira-issue-workflow.md
  agdt-initiate-create-jira-epic-workflow.md
  agdt-initiate-create-jira-subtask-workflow.md
  agdt-initiate-update-jira-issue-workflow.md
  agdt-initiate-apply-pr-suggestions-workflow.md
  agdt-initiate-optimize-issue-for-ai-agent-workflow.md
  agdt-initiate-break-down-issue-into-subtasks-workflow.md
```

## Covered workflows

| Command | Template |
|---------|----------|
| `agdt-initiate-pull-request-review-workflow` | [agdt-initiate-pull-request-review-workflow.md](agdt-initiate-pull-request-review-workflow.md) |
| `agdt-initiate-work-on-jira-issue-workflow` | [agdt-initiate-work-on-jira-issue-workflow.md](agdt-initiate-work-on-jira-issue-workflow.md) |
| `agdt-initiate-create-jira-issue-workflow` | [agdt-initiate-create-jira-issue-workflow.md](agdt-initiate-create-jira-issue-workflow.md) |
| `agdt-initiate-create-jira-epic-workflow` | [agdt-initiate-create-jira-epic-workflow.md](agdt-initiate-create-jira-epic-workflow.md) |
| `agdt-initiate-create-jira-subtask-workflow` | [agdt-initiate-create-jira-subtask-workflow.md](agdt-initiate-create-jira-subtask-workflow.md) |
| `agdt-initiate-update-jira-issue-workflow` | [agdt-initiate-update-jira-issue-workflow.md](agdt-initiate-update-jira-issue-workflow.md) |
| `agdt-initiate-apply-pr-suggestions-workflow` | [agdt-initiate-apply-pr-suggestions-workflow.md](agdt-initiate-apply-pr-suggestions-workflow.md) |
| `agdt-initiate-optimize-issue-for-ai-agent-workflow` | [agdt-initiate-optimize-issue-for-ai-agent-workflow.md](agdt-initiate-optimize-issue-for-ai-agent-workflow.md) |
| `agdt-initiate-break-down-issue-into-subtasks-workflow` | [agdt-initiate-break-down-issue-into-subtasks-workflow.md](agdt-initiate-break-down-issue-into-subtasks-workflow.md) |

## Shared concepts

Most initiate workflows share a common bootstrapping shape, traced from
[`agentic_devtools/cli/workflows/commands.py`](../../agentic_devtools/cli/workflows/commands.py),
[`preflight.py`](../../agentic_devtools/cli/workflows/preflight.py),
[`base.py`](../../agentic_devtools/cli/workflows/base.py), and
[`worktree_setup.py`](../../agentic_devtools/cli/workflows/worktree_setup.py):

- **Scope bootstrap**: identity and worktree scope are resolved before any
  state I/O, so state lands in `.agdt/workflows/{identity}/{worktree_key}/`
  rather than the `_unscoped` fallback.
- **Pre-flight check**: `check_worktree_and_branch()` validates that the current
  repo-root folder name and the current git branch both contain the issue key
  (case-insensitive). PR-review-style workflows also accept an exact match on
  the PR source branch.
- **Auto-setup (preflight fail)**: `perform_auto_setup()` spawns a background
  task that creates a worktree, injects VS Code settings, runs the repo setup
  script, optionally runs a nested auto-execute command, opens VS Code, and
  starts a Copilot session.
- **In-context path (preflight pass)**: the command renders the workflow's
  initiate prompt via `initiate_workflow()`, sets the workflow state, and
  (for most workflows) starts a Copilot session.
- **Common flags**: `--interactive`, `--model`, and `--skip-copilot-session`
  are present on every initiate command. `--skip-copilot-session` is used by
  the nested auto-execute invocation to run setup synchronously without
  spawning a duplicate session.

The per-command documents capture where each workflow diverges from this shape.

## AI agent session choreography (shared shape)

The initiate command is only the **bootstrap**. After it starts a `gh copilot`
session, the hosted AI agent is guided through the workflow by **prompt
templates** under
[`agentic_devtools/prompts/`](../../agentic_devtools/prompts/), advanced by the
state machine in
[`manager.py`](../../agentic_devtools/cli/workflows/manager.py). Each
per-command document has an **AI Agent Session Choreography** section describing
this guided journey. The common shape is:

- **Session entrypoint** — the rendered prompt that becomes the agent's opening
  message (resolved via `_WORKFLOW_PROMPT_FILENAMES` and the
  `_start_copilot_session_for_*` helpers in `worktree_setup.py`).
- **Step prompts** — each workflow step renders
  `temp-<workflow>-<step>-prompt.md` into the state directory and prints it when
  the workflow enters that step.
- **Advancement** — *immediate auto-advance* (the triggering `agdt-*` command
  prints the next prompt), *deferred auto-advance* (the agent calls
  `agdt-get-next-workflow-prompt` once a required background task completes), or
  *manual advance* (`agdt-advance-workflow <step>`). Some workflows also **hand
  off to a Copilot Chat subagent** (for example `@agdt.advance-workflow`) or
  **invoke a nested workflow** (for example break-down → create-subtask).
- **Single-step workflows** — the create/update/optimize/break-down workflows
  render one self-contained prompt that the agent follows top-to-bottom in a
  single session; some create paths instead **hand off to the update-jira-issue
  workflow** after creating a placeholder issue.

## Hard requirement — keep these docs in sync with the code

> **These documents and their Mermaid diagrams are part of the source of truth
> for how the initiate workflows behave. They MUST be kept in sync with the
> code.**

Whenever an initiate workflow's behavior, parameters, or decision paths change
(in `agentic_devtools/cli/workflows/**` or the related prompt templates under
`agentic_devtools/prompts/**`):

1. Update the matching `docs/workflow-expectations/<command-name>.md` document
   **in the same pull request**.
2. Update its Mermaid `## Workflow Diagram` to match the new paths.
3. Reviewers MUST verify that the document and diagram match the code before
   approving.

This requirement is mandated by the project constitution
([`.specify/memory/constitution.md`](../../.specify/memory/constitution.md),
principle *Living Workflow Expectation Docs*) and enforced via the
path-specific instructions in
[`.github/instructions/workflow-expectations.instructions.md`](../../.github/instructions/workflow-expectations.instructions.md).
