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.

1. Title + date. # Agent Orchestrator — Week of {Mon DD, YYYY}. Use the Monday of the report week, not the run day.
2. 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.
3. 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.
4. By the Numbers. Four bullets: commits, merged PRs, contributors, star delta. Format as Commits: 42 etc.
5. Install. Fenced block with the current install command for the latest version.
6. Links. Release page, full changelog, repo, Discord.
7. 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.
8. 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.
9. 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:

1. Open a PR against main with the change.
2. Run python3 run.py --mode on-demand locally against the real repo to sanity-check the output.
3. Diff the output against last week's post — unintended style regressions are easy to miss.
4. After merge, the next Thursday run picks it up automatically. To preview immediately, trigger an on-demand run from the bot.