eng-weekly

A one-page weekly engineering report for your CEO, generated by Claude Code — 5–10 minutes of your Friday instead of an hour.

If you're a CTO or Head of Engineering, you probably owe someone a weekly summary of what your team shipped, who's working on what, and what's at risk. Writing it by hand means re-reading a week of PRs, boards, and meeting notes. This repo automates the mechanical part and delegates the editorial part to Claude Code, producing a print-ready one-pager like this:

Acme · Engineering Weekly — executive summary, KPI strip (PRs merged, releases, mobile build), curated themes with status pills, per-person team focus, releases, risks, next week. See template/sample-report.html.

How it works

inputs/<YYYY-Wnn>/            ← one folder per week (drop zone)
  auto/                       ← collected by scripts/collect.sh (PRs, issues, ArgoCD, Trello)
  meeting-notes*.md           ← pasted meeting summaries (richest signal)
  slack-issues.md             ← pasted Slack threads, rough format fine
  week-config.yaml            ← manual facts: themes, mobile build, next-week intent
        │
        ▼
  Claude Code session: "generate the weekly report for 2026-W28"
        │  reads REPORT-STANDARD.md + inputs, synthesizes
        ▼
reports/2026-W28.html         ← the deliverable
reports/2026-W28-page1.pdf    ← via scripts/render-pdf.sh → send it

The core design decision: deterministic collection, editorial model. Anything API-shaped and mechanical (fetch, paginate, normalize) is a script — repeatable, no hallucination risk. Anything editorial (synthesizing notes, business-language rewriting, deciding what the CEO needs to know, the HTML itself) is Claude Code following REPORT-STANDARD.md as a contract. Collectors emit raw normalized JSON, never prose — pre-summarizing would throw away detail before the editorial step. There is no app to maintain: the standard doc is the spec.

Requirements

• Claude Code — the report generator
• gh authenticated against your org (gh auth login) + jq
• Chrome or Chromium, for PDF rendering
• Optional: kubectl with access to your ArgoCD cluster (release data), Go (Trello collector)

Quick start

git clone https://github.com/jamesreate/eng-weekly.git && cd eng-weekly
cp settings.example.yaml settings.yaml   # edit: company, github org, team roster
cp .env.example .env                     # only if you use Trello

# Collect this week's data (say week 28 of 2026):
scripts/collect.sh 2026-W28

# Drop in the human signal:
#   inputs/2026-W28/meeting-notes-mon.md   (paste your standup/meeting summaries)
#   inputs/2026-W28/slack-issues.md        (paste relevant threads)
cp template/week-config.yaml inputs/2026-W28/week-config.yaml   # edit themes

# Generate:
claude   # then ask: "Generate the weekly report for 2026-W28"

# Render and send:
scripts/render-pdf.sh 2026-W28   # → reports/2026-W28.pdf + -page1.pdf

Everything except GitHub is optional. No ArgoCD? Delete that section from settings.yaml and it's skipped. Same for Trello and mobile releases.

The two ideas that make the report good

1. Themes are curated, not derived. You maintain 3–5 named workstreams in week-config.yaml and carry them week to week, updating status. PR data supports the themes; it doesn't define them. This is what keeps the report readable to a CEO — it tracks goals, not repositories.

2. Not everyone's work is in GitHub. The team roster in settings.yaml supports a sources hint per person. Your project coordinator who runs testing, unblocks vendors, and coordinates across departments may make zero PRs — their week is visible in Trello, meeting notes, and Slack instead. The generator is required to look there, because leadership and unblocking work is reportable work. Without this, data-driven reports silently erase your most important non-coding people.

Configuration

File	Committed?	Contents
settings.yaml	no (gitignored)	company name, GitHub org, team roster, ArgoCD context, Trello boards
.env	no (gitignored)	Trello API key/token
inputs/, reports/	no (gitignored)	your company's data — meeting notes, issue threads, generated reports
REPORT-STANDARD.md	yes	the report contract — edit it to change what gets generated

Start from settings.example.yaml; every section is commented. The gitignore defaults mean you can fork this publicly and your company data stays local. If you want your inputs/reports version-controlled, do it in a private fork and edit .gitignore.

Weekly operating procedure (5–10 min)

1. scripts/collect.sh <week> — pulls PRs, issues, ArgoCD state, Trello into inputs/<week>/auto/.
2. Paste meeting notes and Slack issues into the week folder; copy last week's week-config.yaml and update theme statuses (or just answer Claude's questions in chat).
3. In Claude Code: "Generate the weekly report for <week>". Review, tweak wording.
4. scripts/render-pdf.sh <week> → send reports/<week>-page1.pdf (one-pager) or the full PDF with addendum.

Customizing

The report's structure, voice, and styling all live in REPORT-STANDARD.md — it's prose, not code. Want a different section order, a security KPI, a dark theme, Linear instead of Trello? Edit the standard (and settings.yaml), and the next generation follows it. template/sample-report.html is the visual reference; regenerate it if you change the layout rules.

Adding a data source is usually a few lines in scripts/collect.sh (emit normalized JSON into inputs/<week>/auto/) plus a sentence in the standard telling the generator what to do with it. The Go collector (collector/) is there for sources that need real API work — Trello today; Linear/Jira would follow the same pattern.

License

MIT