diff --git a/AGENTS.md b/AGENTS.md index 7841734d..4c272ae4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -82,7 +82,7 @@ Every compiled pipeline runs as three sequential jobs: │ │ │ ├── ado_aw_marker.rs # Always-on metadata marker extension (emits # ado-aw-metadata JSON) │ │ │ ├── github.rs # Always-on GitHub MCP extension │ │ │ ├── safe_outputs.rs # Always-on SafeOutputs MCP extension -│ │ │ ├── ado_script.rs # Always-on ado-script extension (gate evaluator + runtime-import resolver + exec-context-pr precompute, per-job downloads) +│ │ │ ├── ado_script.rs # Always-on ado-script extension (gate evaluator + runtime-import resolver + execution-context precomputes, per-job downloads) │ │ │ ├── exec_context/ # Always-on execution-context extension (issue #860) │ │ │ │ ├── mod.rs # ExecContextExtension; CompilerExtension impl; contributor fan-out │ │ │ │ ├── contributor.rs # Internal ContextContributor trait + Contributor enum @@ -223,12 +223,19 @@ Every compiled pipeline runs as three sequential jobs: │ ├── update-ado-agentic-workflow.md # Guide for modifying an existing agentic pipeline │ └── debug-ado-agentic-workflow.md # Guide for troubleshooting a failing agentic pipeline ├── scripts/ # Supporting scripts shipped as release artifacts -│ └── ado-script/ # TypeScript workspace for bundled gate.js, import.js, exec-context-pr.js, exec-context-pr-synth.js +│ └── ado-script/ # TypeScript workspace for bundled gate/import helpers plus execution-context bundles │ └── src/ │ ├── gate/ # Gate evaluator source (bundled to gate.js) │ ├── import/ # Runtime prompt resolver source (bundled to import.js) │ ├── exec-context-pr/ # PR-context precompute source (bundled to exec-context-pr.js) │ ├── exec-context-pr-synth/ # Synthetic-PR resolver source (bundled to exec-context-pr-synth.js) +│ ├── exec-context-manual/ # Manual-run context source (bundled to exec-context-manual.js) +│ ├── exec-context-pipeline/ # Pipeline-completion context source (bundled to exec-context-pipeline.js) +│ ├── exec-context-ci-push/ # CI/push context source (bundled to exec-context-ci-push.js) +│ ├── exec-context-workitem/ # Linked work-item context source (bundled to exec-context-workitem.js) +│ ├── exec-context-schedule/ # Scheduled-run context source (bundled to exec-context-schedule.js) +│ ├── exec-context-pr-checks/ # PR validation checks context source (bundled to exec-context-pr-checks.js) +│ ├── exec-context-repo/ # Repository identity context source (bundled to exec-context-repo.js) │ └── shared/ # Shared modules across bundles (auth, ado-client, env-facts, types.gen.ts) ├── tests/ # Integration tests and fixtures ├── docs/ # Per-concept reference documentation (see index below) @@ -241,7 +248,7 @@ Every compiled pipeline runs as three sequential jobs: - **Language**: Rust (2024 edition) - Note: Rust 2024 edition exists and is the edition used by this project - **CLI Framework**: clap v4 with derive macros - **Error Handling**: anyhow for ergonomic error propagation -- **Bundled scripts**: TypeScript + ncc (`scripts/ado-script/`) — compiled gate evaluator, runtime import resolver, PR-context precompute, and synthetic-PR resolver; see [`docs/ado-script.md`](docs/ado-script.md). +- **Bundled scripts**: TypeScript + ncc (`scripts/ado-script/`) — compiled gate evaluator, runtime import resolver, and execution-context precompute helpers; see [`docs/ado-script.md`](docs/ado-script.md). - **Async Runtime**: tokio with full features - **YAML Parsing**: serde_yaml - **MCP Server**: rmcp with server and transport-io features @@ -281,11 +288,9 @@ index to jump to the right page. - [`docs/targets.md`](docs/targets.md) — target platforms: `standalone`, `1es`, `job`, and `stage`. - [`docs/execution-context.md`](docs/execution-context.md) — built-in - `aw-context/` precompute (issue #860): PR target-branch fetch + - merge-base resolution, `base.sha`/`head.sha` artefacts, prompt - fragment with pre-filled ADO MCP identifiers, auto-extension of the - agent's bash allow-list with read-only git commands; configured via - the `execution-context:` front-matter block. + `aw-context/` precompute contributors for PR, manual, pipeline, + CI/push, work-item, scheduled, PR-check, and repository context; + configured via the `execution-context:` front-matter block. - [`docs/safe-outputs.md`](docs/safe-outputs.md) — full reference for every safe-output tool agents can use to propose actions (PRs, work items, wiki pages, comments, etc.) plus their per-agent configuration. @@ -310,7 +315,9 @@ index to jump to the right page. - [`docs/ir.md`](docs/ir.md) — typed Azure DevOps pipeline IR (`Pipeline`, jobs/stages/steps, output refs, graph pass, lowering, target builders, and the public JSON summary consumed by agent-facing tooling). - [`docs/cli.md`](docs/cli.md) — `ado-aw` CLI commands (`init`, `compile`, `check`, `mcp`, `mcp-http`, `execute`, `secrets`, `enable`, `disable`, - `remove`, `list`, `status`, `run`, `audit`; `configure` is a deprecated hidden alias). + `remove`, `list`, `status`, `run`, `audit`, `mcp-author`, `trace`, + `inspect`, `graph`, `whatif`, `lint`, `catalog`; `configure` is a + deprecated hidden alias and `export-gate-schema` is a hidden build-time tool). - [`docs/audit.md`](docs/audit.md) — `ado-aw audit`: accepted build-id / URL forms, artifact layout, cache behavior, rejection tracing, and `AuditData` report shape. @@ -335,8 +342,9 @@ index to jump to the right page. rewrite on breaking-change updates, contributor workflow for adding codemods. - [`docs/ado-script.md`](docs/ado-script.md) — `ado-script` workspace - (`scripts/ado-script/`): the bundled TypeScript runtime helpers (today: - `gate.js`, `import.js`, `exec-context-pr.js`, `exec-context-pr-synth.js`), schemars-driven type codegen, and the A2 design decision. + (`scripts/ado-script/`): the bundled TypeScript runtime helpers + (`gate.js`, `import.js`, and the execution-context `exec-context-*.js` + bundles), schemars-driven type codegen, and the A2 design decision. - [`docs/local-development.md`](docs/local-development.md) — local development setup notes. diff --git a/README.md b/README.md index 9186077b..8b7eaef3 100644 --- a/README.md +++ b/README.md @@ -271,9 +271,10 @@ the service connections. Approve the permissions and the pipeline is ready. | `teardown` | list | — | Separate job after safe outputs | | `network` | object | — | Additional allowed/blocked hosts | | `inlined-imports` | boolean | `false` | When `true`, resolves all `{{#runtime-import …}}` markers at compile time; the generated YAML is self-contained but prompt-body edits require recompilation. See [runtime-imports.md](docs/runtime-imports.md). | -| `env` | map | — | Workflow-level environment variables (reserved, not yet implemented) | -| `execution-context` | object | — | Configuration for the always-on execution-context plugin (PR context precompute). See [execution-context.md](docs/execution-context.md). | +| `env` | map | `{}` | Workflow-level environment variables (accepted by parser, not yet forwarded to compiled pipeline output) | +| `execution-context` | object | — | Configuration for the always-on execution-context plugin (`aw-context/` contributors). See [execution-context.md](docs/execution-context.md). | | `supply-chain` | object | — | Internal feed/registry mirror settings for compiler/runtime artifacts. See [supply-chain.md](docs/supply-chain.md). | +| `ado-aw-debug` | object | — | Debug-only knobs for local/dogfood diagnostics. See [ado-aw-debug.md](docs/ado-aw-debug.md). | ### Markdown Body @@ -440,7 +441,7 @@ actions, and the executor processes them after threat analysis. | `reply-to-pr-comment` | Replies to an existing PR review comment thread | | `resolve-pr-thread` | Resolves or updates the status of a PR review thread | | `submit-pr-review` | Submits a review vote on a pull request | -| `update-pr` | Updates pull request metadata (reviewers, labels, auto-complete, etc.) | +| `update-pr` | Updates pull request metadata (reviewers, labels, auto-complete, vote, update-description) | | `link-work-items` | Links two ADO work items together | | `queue-build` | Queues a pipeline build by definition ID | | `create-git-tag` | Creates a git tag on a repository ref | @@ -611,7 +612,8 @@ index to jump to the right page. - [`docs/targets.md`](docs/targets.md) — target platforms: `standalone`, `1es`, `job`, and `stage`. - [`docs/execution-context.md`](docs/execution-context.md) — built-in - `aw-context/` precompute configuration (PR context staging + merge-base facts). + `aw-context/` precompute contributors for PR, manual, pipeline, CI/push, + work-item, scheduled, PR-check, and repository context. - [`docs/safe-outputs.md`](docs/safe-outputs.md) — full reference for every safe-output tool plus their per-agent configuration. - [`docs/safe-output-permissions.md`](docs/safe-output-permissions.md) — @@ -640,8 +642,8 @@ index to jump to the right page. - [`docs/codemods.md`](docs/codemods.md) — front-matter codemod framework (detection-based source rewrites on breaking-change updates). - [`docs/ado-script.md`](docs/ado-script.md) — `scripts/ado-script/` workspace - (bundled TypeScript runtime helpers: `gate.js`, `import.js`, - `exec-context-pr.js`, `exec-context-pr-synth.js`). + (bundled TypeScript runtime helpers: `gate.js`, `import.js`, and the + execution-context `exec-context-*.js` bundles). - [`docs/extending.md`](docs/extending.md) — adding new CLI commands, compile targets, front-matter fields, typed IR extensions, safe-output tools, first-class tools, and runtimes. diff --git a/docs/ado-script.md b/docs/ado-script.md index c4a662bc..97cc1ef4 100644 --- a/docs/ado-script.md +++ b/docs/ado-script.md @@ -3,7 +3,7 @@ `ado-script` is the umbrella name for the TypeScript workspace at [`scripts/ado-script/`](../scripts/ado-script/). It produces small, ncc-bundled Node programs that the **compiler injects into every emitted -pipeline** as runtime helpers. Today it produces four bundles: +pipeline** as runtime helpers. Today it produces eleven bundles: - `gate.js` — trigger-filter gate evaluator (Setup job). - `import.js` — runtime prompt resolver described in @@ -26,6 +26,25 @@ pipeline** as runtime helpers. Today it produces four bundles: `aw-context/pipeline/upstream-*` files plus a `## Pipeline-completion context` prompt fragment (Agent job; see [`execution-context.md`](execution-context.md)). +- `exec-context-ci-push.js` — CI/push precompute that stages "since + last green build" diff context under `aw-context/ci-push/` (Agent + job; see [`execution-context.md`](execution-context.md)). +- `exec-context-workitem.js` — PR-linked work-item precompute that + stages linked work-item metadata and descriptions under + `aw-context/workitem/` (Agent job; see + [`execution-context.md`](execution-context.md)). +- `exec-context-schedule.js` — Scheduled-run precompute that stages + "since last successful scheduled run" context under + `aw-context/schedule/` (Agent job; see + [`execution-context.md`](execution-context.md)). +- `exec-context-pr-checks.js` — PR Build Validation checks precompute + that stages succeeded/failing check results under + `aw-context/pr/checks/` (Agent job; see + [`execution-context.md`](execution-context.md)). +- `exec-context-repo.js` — Repository identity precompute that stages + branch, SHA, last release tag, and commits-since-tag facts under + `aw-context/repo/` (Agent job; see + [`execution-context.md`](execution-context.md)). > **Internal-only.** `ado-script` is not a user-facing front-matter > feature. Authors never write an `ado-script:` block in their agent @@ -72,10 +91,9 @@ because the compiler always embeds an absolute marker path and not re-expanded). The bundle lives at `import.js` and ships in the same -`ado-script.zip` release asset as `gate.js`, `exec-context-pr.js`, -`exec-context-pr-synth.js`, `exec-context-manual.js`, and -`exec-context-pipeline.js`, so pipelines download it through the -same Agent-job asset flow. +`ado-script.zip` release asset as `gate.js` and the ten +`exec-context-*.js` bundles listed in the workspace layout, so +pipelines download it through the same Agent-job asset flow. `import.js` uses only the Node standard library, so the ncc bundle is small (~1.5 KB) and carries no SDK dependency. @@ -381,16 +399,36 @@ scripts/ado-script/ │ ├── exec-context-manual/ # exec-context-manual.js entry point + manual-context precompute │ │ ├── index.ts # main(): collect PARAM_* env vars → JSON snapshot → prompt fragment │ │ └── __tests__/ # unit tests for success / failure / sanitisation paths -│ └── exec-context-pipeline/ # exec-context-pipeline.js entry point + pipeline-completion precompute -│ ├── index.ts # main(): validate TriggeredBy ids → fetch upstream Build via REST → stage + prompt -│ └── __tests__/ # unit tests for validate / success / failure / sanitisation paths +│ ├── exec-context-pipeline/ # exec-context-pipeline.js entry point + pipeline-completion precompute +│ │ ├── index.ts # main(): validate TriggeredBy ids → fetch upstream Build via REST → stage + prompt +│ │ └── __tests__/ # unit tests for validate / success / failure / sanitisation paths +│ ├── exec-context-ci-push/ # exec-context-ci-push.js entry point + CI/push diff context +│ │ ├── index.ts # main(): find last green build → stage changed files / commits → prompt +│ │ └── __tests__/ # unit tests for success / fallback / sanitisation paths +│ ├── exec-context-workitem/ # exec-context-workitem.js entry point + PR-linked work-item context +│ │ ├── index.ts # main(): fetch linked WIs → stage metadata + descriptions → prompt +│ │ └── __tests__/ # unit tests for fetch / truncation / sanitisation paths +│ ├── exec-context-schedule/ # exec-context-schedule.js entry point + scheduled-run diff context +│ │ ├── index.ts # main(): find prior scheduled success → stage changed files / commits → prompt +│ │ └── __tests__/ # unit tests for success / no-baseline / sanitisation paths +│ ├── exec-context-pr-checks/ # exec-context-pr-checks.js entry point + PR validation checks context +│ │ ├── index.ts # main(): fetch policy/build checks → stage failing/succeeded JSON → prompt +│ │ └── __tests__/ # unit tests for checks filtering / sanitisation paths +│ └── exec-context-repo/ # exec-context-repo.js entry point + repository identity context +│ ├── index.ts # main(): stage branch/SHA/tag/commits-since-tag facts → prompt +│ └── __tests__/ # unit tests for identity / tag fallback / sanitisation paths ├── test/ # End-to-end smoke tests (gate, import, exec-context-pr) ├── gate.js # ncc bundle output (gitignored) ├── import.js # ncc bundle output (gitignored) ├── exec-context-pr.js # ncc bundle output (gitignored) ├── exec-context-pr-synth.js # ncc bundle output (gitignored) ├── exec-context-manual.js # ncc bundle output (gitignored) -└── exec-context-pipeline.js # ncc bundle output (gitignored) +├── exec-context-pipeline.js # ncc bundle output (gitignored) +├── exec-context-ci-push.js # ncc bundle output (gitignored) +├── exec-context-workitem.js # ncc bundle output (gitignored) +├── exec-context-schedule.js # ncc bundle output (gitignored) +├── exec-context-pr-checks.js # ncc bundle output (gitignored) +└── exec-context-repo.js # ncc bundle output (gitignored) ``` The release workflow (`.github/workflows/release.yml`) runs @@ -398,8 +436,13 @@ The release workflow (`.github/workflows/release.yml`) runs `scripts/ado-script/import.js`, `scripts/ado-script/exec-context-pr.js`, `scripts/ado-script/exec-context-pr-synth.js`, -`scripts/ado-script/exec-context-manual.js`, and -`scripts/ado-script/exec-context-pipeline.js` into the +`scripts/ado-script/exec-context-manual.js`, +`scripts/ado-script/exec-context-pipeline.js`, +`scripts/ado-script/exec-context-ci-push.js`, +`scripts/ado-script/exec-context-workitem.js`, +`scripts/ado-script/exec-context-schedule.js`, +`scripts/ado-script/exec-context-pr-checks.js`, and +`scripts/ado-script/exec-context-repo.js` into the `ado-script.zip` release asset. Pipelines download that asset at runtime by URL pinned to the compiler's `CARGO_PKG_VERSION`, verify its SHA-256 against the `checksums.txt` asset, then extract. @@ -500,10 +543,10 @@ The rows below assume the synthetic-PR resolver is **not** active |---|---|---|---| | no gate | none | (none) | (none) | | no gate | `inlined-imports: false` only | (no Setup job) | install + download + resolver | -| no gate | `on.pr` execution-context only | (no Setup job) | install + download + exec-context-pr | -| no gate | both | (no Setup job) | install + download + resolver + exec-context-pr | +| no gate | execution-context contributor(s) only | (no Setup job) | install + download + exec-context bundle(s) | +| no gate | resolver + execution-context | (no Setup job) | install + download + resolver + exec-context bundle(s) | | gate | none | install + download + gate | (none) | -| gate | any combination of resolver / exec-pr | install + download + gate | install + download + (resolver?) + (exec-context-pr?) | +| gate | any combination of resolver / exec-context | install + download + gate | install + download + (resolver?) + (exec-context bundle(s)?) | When the synthetic-PR resolver **is** active (`pr_trigger_for_synth = Some(_)`, i.e. `synthetic_pr_active()` is @@ -582,8 +625,8 @@ npm ci # one-time npm run codegen # regenerate types.gen.ts (compiles ado-aw first) npm test # vitest unit tests npm run typecheck # strict tsc --noEmit -npm run build # ncc-bundle to gate.js -npm run test:smoke # build + smoke test the bundle end-to-end +npm run build # ncc-bundle all ado-script JS helpers +npm run test:smoke # build + smoke test the bundles end-to-end ``` The Rust-side E2E gate test compiles a real agent, extracts the diff --git a/docs/execution-context.md b/docs/execution-context.md index ae07a58d..7e91680f 100644 --- a/docs/execution-context.md +++ b/docs/execution-context.md @@ -557,11 +557,16 @@ your own markdown body. - Always-on `ExecContextExtension` in `src/compile/extensions/exec_context/mod.rs` (`ExtensionPhase::Tool`). -- Internal `ContextContributor` trait in `contributor.rs`. v1 ships - one contributor: `PrContextContributor` in `pr.rs`. -- Front-matter types: `ExecutionContextConfig` and `PrContextConfig` - in `src/compile/types.rs` (`PrContextConfig` is just - `{ enabled: Option }`). +- Internal `ContextContributor` trait in `contributor.rs`; concrete + contributors live alongside it (`pr.rs`, `manual.rs`, `pipeline.rs`, + `ci_push.rs`, `workitem.rs`, `schedule.rs`, `pr_checks.rs`, and + `repo.rs`). +- Front-matter types: `ExecutionContextConfig` and the per-contributor + config structs (`PrContextConfig`, `ManualContextConfig`, + `PipelineContextConfig`, `CiPushContextConfig`, + `WorkitemContextConfig`, `ScheduleContextConfig`, + `PrChecksContextConfig`, and `RepoContextConfig`) in + `src/compile/types.rs`. - Compile tests live in `tests/compiler_tests.rs` (search for `test_execution_context_pr_*`). - The generated bash is shellchecked by `tests/bash_lint_tests.rs` diff --git a/docs/front-matter.md b/docs/front-matter.md index 99d02c9f..946b8ba4 100644 --- a/docs/front-matter.md +++ b/docs/front-matter.md @@ -65,12 +65,22 @@ runtimes: # optional runtime configuration (language enviro # # See docs/runtime-imports.md for full details. mcp-servers: my-custom-tool: # containerized MCP server (requires container field) + enabled: true container: "node:20-slim" entrypoint: "node" entrypoint-args: ["path/to/mcp-server.js"] + args: ["--pull=always"] # Docker runtime args inserted before the image + mounts: ["$(Build.SourcesDirectory):/workspace:ro"] + env: + CUSTOM_TOKEN: "" # empty string = pass through from pipeline env allowed: - custom_function_1 - custom_function_2 + remote-tool: # HTTP MCP server (see docs/mcp.md) + url: "https://mcp.example.com" + headers: + Authorization: "Bearer $(MCP_TOKEN)" + allowed: [search, fetch] safe-outputs: # optional per-tool configuration for safe outputs create-work-item: work-item-type: Task @@ -148,6 +158,23 @@ execution-context: # optional execution-context plugin (see docs/exe enabled: true # defaults to true when on.pr is configured. Set false to opt out # (also suppresses auto-adding the read-only git commands to the # agent's bash allow-list). + checks: + enabled: true # include PR Build Validation check results + manual: + enabled: true # defaults to true when parameters are declared + include-email: false + pipeline: + enabled: true # defaults to true when on.pipeline is configured + ci-push: + enabled: false # opt-in "since last green build" CI/push context + workitem: + enabled: true # defaults to true with PR context + max-items: 5 + max-body-kb: 32 + schedule: + enabled: true # scheduled-run diff context (requires on.schedule) + repo: + enabled: false # opt-in repository identity context steps: # inline steps before agent runs (same job, generate context) - bash: echo "Preparing context for agent" displayName: "Prepare context" @@ -180,6 +207,9 @@ supply-chain: # optional internal supply-chain mirror (see docs name: myacr.azurecr.io/mirror # registry host or base path (artifact names kept under it) service-connection: acr-conn # REQUIRED when registry is set (ACR has no System.AccessToken path) service-connection: shared-conn # optional shared fallback for whichever target omits its own +# ado-aw-debug: # debug-only knobs; see docs/ado-aw-debug.md +# skip-integrity: false # omit generated pipeline integrity verification +# create-issue: false # dogfood-only GitHub issue filing for debug reports parameters: # optional ADO runtime parameters (surfaced in UI when queuing a run) - name: clearMemory displayName: "Clear agent memory" @@ -193,6 +223,14 @@ parameters: # optional ADO runtime parameters (surfaced in UI Build the project and run all tests... ``` +## Debug-only `ado-aw-debug:` + +`ado-aw-debug:` is accepted in front matter for repository dogfooding and +local diagnostics. It is **not** a regular safe-output tool. Use +`skip-integrity` to omit generated pipeline integrity verification, or +`create-issue` to file a GitHub issue from debug pipelines; see +[`ado-aw-debug.md`](ado-aw-debug.md) for the full reference. + ## Workspace Defaults The `workspace:` field controls which directory the agent runs in. When it is @@ -428,4 +466,3 @@ pipeline. In this mode the compiler: Result: every PR update fires exactly one PR-typed build (`Build.Reason == PullRequest`); commit-driven CI is fully silenced. - diff --git a/docs/mcp.md b/docs/mcp.md index 7953c6a8..2cc41570 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -45,9 +45,10 @@ mcp-servers: **Container stdio servers:** - `container:` - Docker image to run (e.g., `"node:20-slim"`, `"ghcr.io/org/tool:latest"`) - `entrypoint:` - Container entrypoint override (equivalent to `docker run --entrypoint`) -- `entrypoint-args:` - Arguments passed to the entrypoint (after the image in `docker run`) +- `entrypoint-args:` - Arguments passed to the container entrypoint - `args:` - Additional Docker runtime arguments (inserted before the image in `docker run`). **Security note**: dangerous flags like `--privileged`, `--network host` will trigger compile-time warnings. - `mounts:` - Volume mounts in `"source:dest:mode"` format (e.g., `["/host/data:/app/data:ro"]`) +- `env:` - Environment variables for the MCP server process. Use `""` (empty string) for passthrough from the pipeline environment. **HTTP servers:** - `url:` - HTTP endpoint URL for the remote MCP server @@ -56,7 +57,8 @@ mcp-servers: **Common (both types):** - `enabled:` - Whether this MCP server is active (default: `true`). Set to `false` to temporarily disable an entry without removing it from the front matter. - `allowed:` - Array of tool names the agent is permitted to call. Optional — when omitted or empty, all tools from that MCP server are accessible to the agent. **Strongly recommended for security**: restrict to only the tools the agent needs. -- `env:` - Environment variables for the MCP server process. Use `""` (empty string) for passthrough from the pipeline environment. + +HTTP MCPs ignore `env:`; use `headers:` for HTTP authentication instead. ## Environment Variable Passthrough diff --git a/docs/safe-outputs.md b/docs/safe-outputs.md index abaa775a..7edd76e0 100644 --- a/docs/safe-outputs.md +++ b/docs/safe-outputs.md @@ -184,6 +184,7 @@ This hybrid approach combines: - `title` - PR title (required, 5-200 characters) - `description` - PR description in markdown (required, 10+ characters) - `repository` - Repository to create PR in: "self" for pipeline repo, or alias from `checkout:` list (default: "self") +- `labels` - Labels to add to the PR (optional; validated against `allowed-labels` when configured) Note: The source branch name is auto-generated from a sanitized version of the PR title plus a unique suffix (e.g., `agent/fix-bug-in-parser-a1b2c3`). This format is human-readable while preventing injection attacks. diff --git a/docs/schedule-syntax.md b/docs/schedule-syntax.md index adab4f00..50fa0e2e 100644 --- a/docs/schedule-syntax.md +++ b/docs/schedule-syntax.md @@ -33,13 +33,16 @@ schedule: weekly on friday around 17:00 # Friday, within ±60 min of 5 PM schedule: weekly on wednesday between 9:00 and 12:00 # Wednesday morning ``` -Valid weekdays: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday` +Valid weekdays: `sunday`, `monday`, `tuesday`, `wednesday`, `thursday`, `friday`, `saturday`. +Short aliases are also accepted: `sun`, `mon`, `tue`/`tues`, `wed`, `thu`/`thurs`, `fri`, `sat`. ### Hourly Schedules ```yaml schedule: hourly # Every hour at a scattered minute +schedule: every 1h # Equivalent to hourly schedule: every 2h # Every 2 hours at scattered minute +schedule: every 2 hours # Long form also supported schedule: every 6h # Every 6 hours at scattered minute ``` @@ -49,21 +52,29 @@ Valid hour intervals: 1, 2, 3, 4, 6, 8, 12 (factors of 24 for even distribution) ```yaml schedule: every 5 minutes # Every 5 minutes (minimum interval) +schedule: every 5 min # Singular/short forms also supported schedule: every 15 minutes # Every 15 minutes schedule: every 30m # Short form supported ``` Note: Minimum interval is 5 minutes (GitHub Actions/Azure DevOps constraint). +Accepted minute units: `minutes`, `minute`, `mins`, `min`, `m`. ### Special Periods ```yaml schedule: bi-weekly # Every 14 days at scattered time +schedule: biweekly # No-hyphen alias schedule: tri-weekly # Every 21 days at scattered time +schedule: triweekly # No-hyphen alias schedule: every 2 days # Every N days at scattered time +schedule: every 2d # Short day form schedule: every 2 weeks # Every N weeks (converted to N×7 days) at scattered time +schedule: every 2w # Short week form ``` +Accepted day/week units: `days`, `day`, `d`, `weeks`, `week`, `w`. + ### Timezone Support All time specifications support UTC offsets for timezone conversion: @@ -71,10 +82,11 @@ All time specifications support UTC offsets for timezone conversion: ```yaml schedule: daily around 14:00 utc+9 # 2 PM JST → 5 AM UTC schedule: daily around 3pm utc-5 # 3 PM EST → 8 PM UTC +schedule: daily around 09:00 utc # Bare UTC means UTC+0 schedule: daily between 9am utc+05:30 and 5pm utc+05:30 # IST business hours ``` -Supported offset formats: `utc+9`, `utc-5`, `utc+05:30`, `utc-08:00` +Supported offset formats: `utc`, `utc+9`, `utc-5`, `utc+05:30`, `utc-08:00` ### How Scattering Works diff --git a/prompts/create-ado-agentic-workflow.md b/prompts/create-ado-agentic-workflow.md index 302aabed..ddd527c9 100644 --- a/prompts/create-ado-agentic-workflow.md +++ b/prompts/create-ado-agentic-workflow.md @@ -66,7 +66,7 @@ description: "Checks for outdated dependencies and opens PRs to update them" Default engine is `copilot` (GitHub Copilot CLI). The `engine:` field is an engine identifier, not a model name. Only include `engine:` if you need to set a non-default model or timeout. -The default model is `claude-opus-4.7`. To use a different model, use the object form: +The default model is `claude-opus-4.7`. The compiler accepts any valid model identifier; the table below lists recommended choices. To use a different model, use the object form: | Model | Use when | |---|---| @@ -109,6 +109,7 @@ on: | `daily around 14:00` | Within ±60 min of 2 PM UTC | | `daily around 3pm utc+9` | 3 PM JST → converted to UTC | | `daily between 9:00 and 17:00` | Business hours | +| `weekly` | Any day, scattered time | | `weekly on monday` | Every Monday, scattered time | | `weekly on friday around 17:00` | Friday ~5 PM | | `every 2 days` | Every N days, time scattered | @@ -317,7 +318,7 @@ tools: | `reply-to-pr-comment` | Reply to an existing PR review thread | ✅ | | `resolve-pr-thread` | Resolve or update status of a PR thread | ✅ | | `submit-pr-review` | Submit a review vote on a PR | ✅ | -| `update-pr` | Update PR metadata (reviewers, labels, auto-complete, vote) | ✅ | +| `update-pr` | Update PR metadata (reviewers, labels, auto-complete, vote, update-description) | ✅ | | **Builds & Branches** | | | | `queue-build` | Queue an ADO pipeline build by definition ID | ✅ | | `create-branch` | Create a new branch from an existing ref | ✅ |