AGENTS.md

Operating guide for AI coding agents (and humans) working in azure-functions-agents-runtime. Read this first. It defines how we make changes so features stay aligned with the architecture and each other.

• What this project is: a markdown-first programming model that turns an agent project (*.agent.md + config) into an azure.functions.FunctionApp, powered by the Microsoft Agent Framework (MAF).
• Design source of truth: docs/architecture.md. This file governs process; that file governs design. Keep both in sync.

0. Golden rule

Every change starts with triage + a dedicated worktree. Never commit feature work directly on main. Classify the change, size it, then follow the matching lane below. When in doubt about scope or design, stop and ask.

1. Feature development lifecycle

Classify the change first, then pick a lane:

The medium+ pipeline (phases)

Run these phases in order. Each has an exit gate; do not advance until it is met.

Phases 2 and 4 are explicit review checkpoints. Treat them as separate passes (ideally a dedicated review sub-agent): an architecture review that judges the FRD, and a testing review that judges coverage. Do not let the author's implementation context bias the review.

Tooling: the add-feature workflow skill (.github/skills/add-feature/SKILL.md) automates phases 1–5, and FRDs use the template at docs/frds/_template.md. When told to "use the add-feature skill," follow that playbook; §4 below is the FRD outline.

2. Worktree convention

One worktree per change, branched off main:

git worktree add \
  ../copilot-worktrees/azure-functions-agents-runtime/<user>-<slug> \
  -b <user>/<slug> main

• Branch: <user>/<slug> (e.g. vrdmr/agents-folder-indexing).
• Directory: mirrors the branch under copilot-worktrees/azure-functions-agents-runtime/.
• Remove the worktree after the PR merges: git worktree remove <path>.

3. Canonical commands (the gate)

These mirror CI's lint/type-check/test steps (eng/templates/jobs/ci-tests.yml; Python 3.13 and 3.14). All three must pass before a PR is ready. The --cov-report=xml flag is what CI runs; drop it (or use the fast loop below) for everyday local runs.

# One-time setup (editable install with dev extras)
python -m pip install --upgrade pip
python -m pip install -U -e .[dev]
# Lint
python -m ruff check src tests

# Type-check (strict)
python -m mypy src

# Test (with coverage, matching CI exactly)
python -m pytest --cache-clear --cov=./src/azure_functions_agents --cov-report=xml --cov-branch tests

# Fast local test loop
python -m pytest tests -q

samples/ is intentionally excluded from ruff and mypy. tests/ is linted but excluded from strict mypy.

4. FRD: Feature Requirements Document

Required for medium+ features. Location: committed to the repo at docs/frds/<NNNN>-<slug>.md (zero-padded sequence, e.g. docs/frds/0001-agents-folder-indexing.md) — treated like a lightweight ADR so the Decisions log is durable history. Start from docs/frds/_template.md; see docs/frds/README.md for numbering. FRDs describe intended feature behavior and acceptance, never delivery discussion, PR/slice scope, sequencing, ownership, schedule, or rollout plans. Keep those in PR descriptions or a separate delivery plan. Recommended sections:

1. Summary — one paragraph: what and why.
2. Motivation / problem — the pain today (e.g. AgentApps with many agents).
3. Goals / Non-goals — explicit scope boundaries.
4. Proposed design — modules touched, mapped to the docs/architecture.md stages (discover → translate → register → execute).

5. Decisions log — append-only feature-contract choices; record who decided, not delivery decisions:

   #	Decision	Options considered	Choice	Decided by	Date
   1	…	A / B / C	B	Human / Agent	…

6. Test plan — new/changed tests; fixtures under tests/fixtures/config_scenarios/ when config behavior changes.
7. Docs impact — which docs/* and README.md sections change.
8. Status — Draft → In review → Finalized.

5. Code conventions

Grounded in pyproject.toml and current code:

• Python ≥ 3.13. Strict typing everywhere in src/ (mypy --strict, pydantic.mypy plugin).
• Type aliases use PEP 695: type Foo = Bar (not Foo: TypeAlias = Bar); ruff UP040 enforces this. See src/azure_functions_agents/discovery/mcp.py.
• Ruff rules: E,F,I,B,UP,SIM,RUF,N; line-length 100 (E501 ignored). Imports sorted via ruff isort; first-party = azure_functions_agents.
• Pydantic v2 for all config models (config/schema.py). When a field + validator is shared across provider/sub-models, declare it once on the common base class rather than duplicating per subclass.
• MAF remains the default production runtime. The only migration exception is the internal, app-level AZURE_FUNCTIONS_AGENTS_ENABLE_COPILOT preview (sample and limits). Keep harness dispatch behind that once-per-app boundary; no per-agent selectors, mixed-harness roles, or automatic fallback. The legacy runtime: frontmatter field stays ignored (one-time warning).
• Logging goes through the shared azure_functions_agents._logger.logger.
• Respect the pipeline boundaries (architecture.md §2): discovery is read-only; registration is the only Azure-aware stage; the runner executes lazily. Don't re-parse YAML/front matter in registration — trust ResolvedAgent / AgentCapabilities.

6. Testing conventions

• Tests live in tests/ and mirror source modules (tests/test_<module>.py). tests/conftest.py puts src/ on sys.path.
• Config/authoring behavior is covered by scenario fixtures under tests/fixtures/config_scenarios/. Add a new scenario folder when you change how *.agent.md, agents.config.yaml, mcp.json, skills/, or tools/ are interpreted.
• For bug fixes, add a failing regression test first, then fix.

7. Documentation conventions

• docs/architecture.md is the design source of truth — its module map and pipeline stages must stay accurate. Update it in the same PR as behavior changes (lifecycle phase 5).
• docs/front-matter-reference.md is auto-generated from src/azure_functions_agents/config/schema.py via eng/scripts/generate_config_reference.py. Never edit manually. Pre-commit hooks regenerate it when schema.py changes; CI validates it stays current.
• docs/front-matter-spec.md documents the .agent.md authoring format with examples and patterns. When schema.py changes, use the update-schema-docs skill (.github/skills/update-schema-docs/SKILL.md) to generate usage examples for new fields and sync with the reference.
• docs/triggers.md documents trigger types. Update when trigger surface changes.
• README.md is the user-facing quickstart — update examples when public behavior changes.
• The published GitHub Pages docs site is built from docs/ with MkDocs (mkdocs.yml, .github/workflows/docs.yml). docs/index.md (landing/feature bullets) and docs/getting-started.md (quickstart walkthrough) are the site's onboarding pages and duplicate parts of README.md — the update-schema-docs skill also keeps these in sync when a schema change adds a new user-facing capability. Preview locally with mkdocs serve; see CONTRIBUTING.md.

Schema change workflow

When modifying src/azure_functions_agents/config/schema.py:

1. Make schema changes (new fields, models, validators)
2. Run python eng/scripts/generate_config_reference.py → regenerates reference
3. Use the update-schema-docs skill → adds examples to spec, reviews architecture, and syncs docs/index.md / docs/getting-started.md when the change is user-facing
4. Human review of architectural concerns and PR checklist
5. Commit all doc updates together with implementation

8. Definition of Done

• Change made in a dedicated worktree off main.
• (medium+) FRD finalized with a completed Decisions log.
• ruff, mypy, and pytest all green locally (§3).
• New behavior is tested (regression test for bugs).
• docs/architecture.md + relevant docs/* / README.md updated.
• (schema changes) front-matter-reference.md regenerated + update-schema-docs skill run.
• Diff is surgical — no unrelated changes.
• Worktree removed after merge.