doc: add design spec for azd ai agent routine commands

[huimiu]

Summary

Adds the design spec for the new routine command subtree (cli/azd/docs/design/ai-routine-design-spec.md). A routine pairs one trigger (when) with one action (what) on a Foundry project, for example "every weekday at 8 AM UTC, invoke the daily report agent", without standing up Logic Apps, Functions, or cron infra.

Related issues:

• Feature: Add azd ai routine create/update/show/list/delete (plus enable, disable, dispatch, and run subcommands) to manage and run Foundry Routines from any directory #8159
• Follow up: Support creating routines from a file #8187 (--file for routine create)

Key points

• Placement: lives in the existing azure.ai.agents extension. Today the commands surface as azd ai agent routine …; they become azd ai routine … after the planned extension split (registration only). No azure.yaml or registry.json impact, no new persistent state.
• v1 surface: create, update, show, list, delete, enable, disable, dispatch, and run list. run show and run delete are deferred until the data plane lands them.
• Endpoint resolution: reuses the standard 5 level cascade and works standalone outside an azd project, matching connection, toolbox, and skill. The Routines=V1Preview opt in header is sent on every call.
• Create vs. update: the data plane is a single idempotent PUT; the CLI splits it for usability. create fails on existing (or upserts with --force). update is GET then PUT preserving untouched fields, with type switching of --trigger / --action rejected client side.
• enable / disable / dispatch: dedicated idempotent verbs hide the wire format. dispatch is sync by default and streams the agent response; --async switches to the async route.
• Wire mapping: kebab case CLI aliases (recurring, agent-response, agent-invoke) read naturally and absorb upstream API renames via a single mapping table.
• Telemetry and tests: one event per command (no PII), plus unit coverage for flag to wire mapping, update merge semantics, and dispatch route selection, with an E2E smoke covering the create through delete loop.

[github-actions]

📋 Prioritization Note

Thanks for the contribution! The linked issue isn't in the current milestone yet.
Review may take a bit longer — reach out to @rajeshkamal5050 or @kristenwomack if you'd like to discuss prioritization.

[Copilot]

Pull request overview

Adds a design specification for the proposed azd ai agent routine command subtree in the azure.ai.agents extension, covering command behavior, endpoint resolution, wire mappings, telemetry, and tests.

Changes:

• Adds the routine command design spec and v1 command surface.
• Documents endpoint resolution, API routes, output shapes, telemetry, and test plan.
• Adds a cspell override for terminology in the new design doc.

Reviewed changes

Copilot reviewed 1 out of 1 changed files in this pull request and generated 8 comments.

File	Description
cli/azd/docs/design/ai-routine-design-spec.md	New design spec for routine commands.
cli/azd/.vscode/cspell.yaml	Adds a file-specific spelling override for the new doc.

[lindazqli]

Reviewed against TypeSpec PR #43186 (adding routines, now merged into feature/foundry-release). Six issues found — four are blockers before shipping v1:

1. [Line 56] TypeSpec PR reference is stale (#42779 → should be #43186).
2. [Line 165] enable/disable should call the dedicated :enable / :disable routes that already exist in the TypeSpec, not GET-then-PUT.
3. [Line 173] No sync :dispatch route exists in TypeSpec — only POST :dispatch_async. The "sync by default" contract has no API backing.
4. [Line 249] --agent-id / agent_id should be --agent-name / agent_name to match the TypeSpec field name.
5. [Line 201] --orderby has no orderBy query param in ListRoutineRunsParameters.
6. [Line 239] GitHub trigger: --owner serializes to owner but TypeSpec field is assignee; --event-action has no TypeSpec counterpart.

[lindazqli]

Correction: the previous review was submitted as REQUEST_CHANGES by mistake — please treat all inline comments as informational notes for discussion, not as blockers. The comments remain valid observations to align the spec with TypeSpec PR #43186.

[jongio]

Spec follows the extension's existing patterns well for endpoint resolution, flag naming, and prompt/no-prompt behavior. The TypeSpec alignment feedback from existing reviews is the main thing to address before implementation.

One gap: error behavior isn't defined for any of the 9 commands. See inline comment.

[huimiu]

Thanks everyone for the careful review! Here's what changed to address all the feedback:

TypeSpec alignment (Linda's feedback against PR #43186)

• Updated all stale #42779 refs to #43186.
• enable / disable now call the dedicated :enable / :disable routes directly — no more GET-then-PUT (avoids the TOCTOU race you flagged).
• dispatch (both default and --async) now hits :dispatch_async. There's no sync route in TypeSpec, so the flag just controls client-side waiting/streaming.
• Renamed --agent-id → --agent-name everywhere (spec body, command summary, telemetry) to match the agent_name TypeSpec field.
• Dropped --orderby from v1 — no orderBy query param exists yet.
• GitHub trigger: --owner → --assignee, removed --event-action.
• Added a heads-up note in §5.1 for the upcoming generic + strong-typed triggers.
• Clarified --input is plain text (not parsed as JSON), and added an inline pointer that --trigger is an enum, not free-form.
• Noted that the run show API now exists in #43186 — keeping registration deferred for v1 but called out in §4.8.

Error behavior + --file (John and Jon's feedback)

• @jongio: added a new §4.9 Error Behavior section with a scenario → type/code/suggestion table covering 409 (create without --force), 404s (show/delete/dispatch/enable/disable on missing routine), the update GET-succeeds-then-PUT-404 race, type-switch, auth, endpoint resolution, and 5xx. Reuses the existing connection/toolbox typed-error pattern. Test plan updated with negative cases.
• @therealjohn: pulled --file back into v1 scope. New §4.1.1 covers the file shape, mutual exclusion with --trigger, flag-level override semantics, and points to Support creating routines from a file #8187 for the schema details. update --file is supported too. Command summary, telemetry (hasFile), and test plan updated to match.