AO Weekly Release Notes
Automated weekly release notes for ComposioHQ/agent-orchestrator. The cron job pulls main, runs run.py, and posts the output to Discord. No manual redeployment — PRs merged into main take effect on the next run.
When this runs
- Scheduled: Every Thursday 10:00 IST (
30 4 * * 4 UTC). Invoked with --mode scheduled.
- On-demand: Anyone with bot access can trigger a run with
--mode on-demand (e.g. for a mid-week recap or to preview a release post before cutting it).
The two modes produce the same output; the flag is recorded in the footer so readers know whether the post was automatic or manually requested.
How to run
python3 skills/release-notes/ao-weekly-release/run.py --mode scheduled
python3 skills/release-notes/ao-weekly-release/run.py --mode on-demand
python3 skills/release-notes/ao-weekly-release/run.py --mode on-demand --since 2026-04-07
Requirements: gh CLI authenticated against ComposioHQ/agent-orchestrator, python3 ≥ 3.9. No other dependencies — the runner only uses the stdlib and shells out to gh.
Flags:
| Flag |
Default |
Purpose |
--mode |
scheduled |
scheduled or on-demand. Recorded in the footer. |
--since |
7 days ago |
ISO date. Overrides the default weekly window. |
--repo |
ComposioHQ/agent-orchestrator |
Target repo. |
--output |
stdout |
Write the markdown to a file instead of stdout. |
Exit codes: 0 success, 1 input/validation error, 2 gh query failure, 3 no activity in the window (the cron should post a short "quiet week" message instead of the full template).
Output format
The output is a single markdown document. Section order is fixed — do not reorder. The reference post the style is calibrated against is surajmarkup.in/research/ao-april-release.
- Title + date.
# Agent Orchestrator — Week of {Mon DD, YYYY}. Use the Monday of the report week, not the run day.
- Positioning line. One sentence, no more than 25 words, describing what this week delivered. Factual, not marketing. No "excited to announce", no "we're thrilled", no rocket emojis.
- Highlights. 8–14 bullets. Each bullet is one short sentence, past tense, references the PR number inline. Group by theme (features → fixes → refactors → docs) but do not add sub-headers. If fewer than 8 merged PRs exist, list every merged PR and add a one-line note that the week was quiet.
- By the Numbers. Four bullets: commits, merged PRs, contributors, star delta. Format as
Commits: 42 etc.
- Install. Fenced block with the current install command for the latest version.
- Links. Release page, full changelog, repo, Discord.
- Full release command checklist. The exact commands a maintainer would run to cut a release —
pnpm changeset version, pnpm -r build, pnpm -r publish, gh release create. Keep these copy-pasteable.
- Operator checklist. Checkbox-style (
- [ ]) items the operator should verify before publishing externally: changelog reviewed, PR titles cleaned, screenshots attached, Discord announcement drafted, tweet drafted. At least 6 items.
- Footer.
_Generated {ISO timestamp} • mode: {scheduled|on-demand} • window: {YYYY-MM-DD}..{YYYY-MM-DD}_
Style constraints
- Tone: professional, factual, understated. Match the April release post. No hype language, no exclamation marks, no emoji in bullets (emoji is fine in the Discord message wrapper, not the markdown body).
- Voice: third person or imperative. Never "we shipped", prefer "Shipped …" or "The runtime now …".
- Tense: past tense for highlights ("Added", "Fixed", "Refactored"), imperative for the release commands.
- PR references: inline
(#1234) at the end of each highlight bullet. Never link the PR title.
- Numbers: bare integers. No "we merged a whopping 42 PRs".
- Length: the full post should fit in a single Discord message after wrapping (under ~2000 characters of plaintext body, excluding the fenced code blocks). If over, the runner truncates the Highlights section and appends
… and N more — see the full changelog.
Error handling
The runner is deterministic and must never fabricate data. Specific failure modes:
| Failure |
Behavior |
gh not on PATH or not authenticated |
Exit 2 with a clear stderr message. No partial output. |
| No merged PRs in the window |
Exit 3. Cron posts the "quiet week" Discord message instead. |
| GitHub API rate-limited |
Retry once after 30s, then exit 2. |
| A single PR query fails |
Skip that PR, note the count in stderr, continue. Do not fail the whole run over one bad entry. |
| Star count unavailable |
Render Stars: (unavailable). Do not block the post. |
Commit count mismatch between gh and git log |
Prefer git log — the local checkout is the source of truth. |
The runner never invents PR numbers, contributor names, or summary text. Every data point in the output must be traceable to a gh or git command in run.py.
Skill update workflow
All changes go through PRs to skills/release-notes/ao-weekly-release/. The cron pulls latest main before each run (git fetch origin && git checkout main && git reset --hard origin/main), so merged changes take effect on the next scheduled execution. No manual redeployment.
When editing this skill:
- Open a PR against
main with the change.
- Run
python3 run.py --mode on-demand locally against the real repo to sanity-check the output.
- Diff the output against last week's post — unintended style regressions are easy to miss.
- After merge, the next Thursday run picks it up automatically. To preview immediately, trigger an on-demand run from the bot.
Source: ComposioHQ/agent-orchestrator — distributed by TomeVault.
1---2name: ao-weekly-release3description: Generate the weekly Agent Orchestrator release notes. Runs every Thursday 10:00 IST from the bot cron, or on-demand. Queries the GitHub API for the latest release, merged PRs, commits, contributors, and star counts, and produces a publishable markdown post in the house style. Output is posted to Discord by the cron job after this skill returns. Use when this capability is needed.4---56# AO Weekly Release Notes78Automated weekly release notes for `ComposioHQ/agent-orchestrator`. The cron job pulls `main`, runs `run.py`, and posts the output to Discord. No manual redeployment — PRs merged into `main` take effect on the next run.910## When this runs1112- **Scheduled:** Every Thursday 10:00 IST (`30 4 * * 4` UTC). Invoked with `--mode scheduled`.13- **On-demand:** Anyone with bot access can trigger a run with `--mode on-demand` (e.g. for a mid-week recap or to preview a release post before cutting it).1415The two modes produce the same output; the flag is recorded in the footer so readers know whether the post was automatic or manually requested.1617## How to run1819```bash20python3 skills/release-notes/ao-weekly-release/run.py --mode scheduled21python3 skills/release-notes/ao-weekly-release/run.py --mode on-demand22python3 skills/release-notes/ao-weekly-release/run.py --mode on-demand --since 2026-04-0723```2425Requirements: `gh` CLI authenticated against `ComposioHQ/agent-orchestrator`, `python3` ≥ 3.9. No other dependencies — the runner only uses the stdlib and shells out to `gh`.2627Flags:2829| Flag | Default | Purpose |30|---|---|---|31| `--mode` | `scheduled` | `scheduled` or `on-demand`. Recorded in the footer. |32| `--since` | 7 days ago | ISO date. Overrides the default weekly window. |33| `--repo` | `ComposioHQ/agent-orchestrator` | Target repo. |34| `--output` | stdout | Write the markdown to a file instead of stdout. |3536Exit codes: `0` success, `1` input/validation error, `2` `gh` query failure, `3` no activity in the window (the cron should post a short "quiet week" message instead of the full template).3738## Output format3940The output is a single markdown document. Section order is fixed — do not reorder. The reference post the style is calibrated against is [surajmarkup.in/research/ao-april-release](https://surajmarkup.in/research/ao-april-release/).41421. **Title + date.** `# Agent Orchestrator — Week of {Mon DD, YYYY}`. Use the Monday of the report week, not the run day.432. **Positioning line.** One sentence, no more than 25 words, describing what this week delivered. Factual, not marketing. No "excited to announce", no "we're thrilled", no rocket emojis.443. **Highlights.** 8–14 bullets. Each bullet is one short sentence, past tense, references the PR number inline. Group by theme (features → fixes → refactors → docs) but do not add sub-headers. If fewer than 8 merged PRs exist, list every merged PR and add a one-line note that the week was quiet.454. **By the Numbers.** Four bullets: commits, merged PRs, contributors, star delta. Format as `Commits: 42` etc.465. **Install.** Fenced block with the current install command for the latest version.476. **Links.** Release page, full changelog, repo, Discord.487. **Full release command checklist.** The exact commands a maintainer would run to cut a release — `pnpm changeset version`, `pnpm -r build`, `pnpm -r publish`, `gh release create`. Keep these copy-pasteable.498. **Operator checklist.** Checkbox-style (`- [ ]`) items the operator should verify before publishing externally: changelog reviewed, PR titles cleaned, screenshots attached, Discord announcement drafted, tweet drafted. At least 6 items.509. **Footer.** `_Generated {ISO timestamp} • mode: {scheduled|on-demand} • window: {YYYY-MM-DD}..{YYYY-MM-DD}_`5152## Style constraints5354- **Tone:** professional, factual, understated. Match the April release post. No hype language, no exclamation marks, no emoji in bullets (emoji is fine in the Discord message wrapper, not the markdown body).55- **Voice:** third person or imperative. Never "we shipped", prefer "Shipped …" or "The runtime now …".56- **Tense:** past tense for highlights ("Added", "Fixed", "Refactored"), imperative for the release commands.57- **PR references:** inline `(#1234)` at the end of each highlight bullet. Never link the PR title.58- **Numbers:** bare integers. No "we merged a whopping 42 PRs".59- **Length:** the full post should fit in a single Discord message after wrapping (under ~2000 characters of plaintext body, excluding the fenced code blocks). If over, the runner truncates the Highlights section and appends `… and N more — see the full changelog.`6061## Error handling6263The runner is deterministic and must never fabricate data. Specific failure modes:6465| Failure | Behavior |66|---|---|67| `gh` not on PATH or not authenticated | Exit `2` with a clear stderr message. No partial output. |68| No merged PRs in the window | Exit `3`. Cron posts the "quiet week" Discord message instead. |69| GitHub API rate-limited | Retry once after 30s, then exit `2`. |70| A single PR query fails | Skip that PR, note the count in stderr, continue. Do not fail the whole run over one bad entry. |71| Star count unavailable | Render `Stars: (unavailable)`. Do not block the post. |72| Commit count mismatch between `gh` and `git log` | Prefer `git log` — the local checkout is the source of truth. |7374The runner never invents PR numbers, contributor names, or summary text. Every data point in the output must be traceable to a `gh` or `git` command in `run.py`.7576## Skill update workflow7778All changes go through PRs to `skills/release-notes/ao-weekly-release/`. The cron pulls latest `main` before each run (`git fetch origin && git checkout main && git reset --hard origin/main`), so merged changes take effect on the next scheduled execution. No manual redeployment.7980When editing this skill:81821. Open a PR against `main` with the change.832. Run `python3 run.py --mode on-demand` locally against the real repo to sanity-check the output.843. Diff the output against last week's post — unintended style regressions are easy to miss.854. After merge, the next Thursday run picks it up automatically. To preview immediately, trigger an on-demand run from the bot.8687---88> Source: [ComposioHQ/agent-orchestrator](https://github.com/ComposioHQ/agent-orchestrator) — distributed by [TomeVault](https://tomevault.io).89<!-- tomevault:4.0:skill_md:2026-06-20 -->
tomevault-io