# Setup Expectation Documents

This directory contains **general-purpose expectation documents** for
agentic-devtools one-shot setup and configuration commands.

## Scope

Documents here cover **one-shot setup/configuration commands** — commands that
run to completion in a single invocation without multi-step workflow state.
Unlike `docs/workflow-expectations/`, this directory intentionally omits:

- State machine steps and workflow transitions.
- Agent session choreography (prompt sequencing, subagent handoffs).
- Workflow advancement events and deferred transitions.

The structural template (TL;DR, Phases, Parameters & State Keys, Decision
Points / Paths, Execution Flow, Observable Side Effects, Exit Codes, Report
Schema, Decision Flowchart, Success Criteria) is otherwise identical to
`docs/workflow-expectations/`, ensuring AI agents can consume both directories
with the same parsing expectations.

## Relationship to `docs/workflow-expectations/`

| Aspect | `docs/workflow-expectations/` | `docs/setup-expectations/` |
|--------|-------------------------------|----------------------------|
| Command type | Multi-step initiate workflows | One-shot setup commands |
| State machine | Yes (workflow steps, transitions) | No |
| Agent choreography | Yes (prompt sequence, subagents) | No |
| Mermaid diagram | Workflow + choreography diagrams | Single decision flowchart |
| Sync-gate enforcement | `.github/instructions/workflow-expectations.instructions.md` | `expectations_validator.py` |

## How auditing agents use these documents

These files serve as **general-purpose baselines** for AI agents auditing or
testing setup commands. The intended workflow:

1. Identify the setup command under test (e.g., `agdt-setup`).
2. Open the matching expectations document in this directory
   (`agdt-setup.md`).
3. Use the document as the authoritative reference for expected behavior:
   phases, exit codes, decision paths, and observable side effects.
4. Specialize the expectations for the exact flags and environment being
   tested (prune inapplicable paths, fill in concrete values).
5. Execute the command and verify observable outcomes against the specialized
   expectations.

## Sync-gate enforcement

The expectations validator
([`agentic_devtools/cli/setup/expectations_validator.py`](../../agentic_devtools/cli/setup/expectations_validator.py))
enforces that `agdt-setup.md` stays in sync with the source code. It checks:

- The `## Phases` section lists phases matching the `PHASES` tuple in
  `agentic_devtools/cli/setup/phases.py` (names and order).
- The `## Exit Codes` table matches the `ExitCode` enum and
  `ALL_EXIT_CODES` dict in `agentic_devtools/cli/setup/exit_codes.py`
  (numeric values and symbolic names).
- The `## Report Schema` section is present.
- A fenced mermaid code block (```` ```mermaid ````) is present.

This validator runs as part of the CI pipeline to prevent code-doc drift.

## Directory Layout

```text
docs/setup-expectations/
  README.md           <- this file
  agdt-setup.md       <- agdt-setup command expectations
```
