---
applyTo: "agentic_devtools/cli/setup/**,agentic_devtools/skill_injector.py,agentic_devtools/cli/setup/script_generators/**,docs/setup-expectations/**"
---

# Setup-Expectations Sync Gate

The `docs/setup-expectations/` directory holds living documentation describing
the observable behaviour of `agdt-setup` — phases, exit codes, flags, and
report schema.  A CI and pre-push drift gate enforces that **any change to
setup source files is accompanied by a same-PR update** under
`docs/setup-expectations/`.

## For coding agents

Whenever you change behaviour in any of the following paths:

- `agentic_devtools/cli/setup/**`
- `agentic_devtools/skill_injector.py`
- `agentic_devtools/cli/setup/script_generators/**`

you **MUST**, in the **same pull request**, add or update at least one file
under `docs/setup-expectations/` to reflect the change.

Failing to do so will cause the drift check (`scripts/check_setup_expectations_drift.py`)
to fail in both CI (`python -m agentic_devtools.cli.checks`) and the local
pre-push hook.

## For reviewing agents

When reviewing a pull request that touches any of the paths listed above,
confirm that `docs/setup-expectations/` was updated in the same PR.  Treat a
setup-source change without a corresponding documentation update as a review
blocker.

## Scope

This instruction file is **separate** from
`.github/instructions/workflow-expectations.instructions.md`.  Do not widen or
overload the workflow-expectations instruction with setup-expectations
concerns, and do not add setup paths to the workflow-expectations `applyTo`
glob.
