Monthly Report Generator
Quick Start
- Identify the repo, date range (typically last 1–2 months), and client name.
- Determine if the repo uses worktrees. If so, locate the
master worktree.
- Run the research phase (see Workflow below) using async sub-agents.
- Compile findings into HTML and Markdown reports using the templates.
- Optionally update the project wiki.
Workflow
1. Research Phase (delegate to async sub-agents)
Dispatch 4 parallel async sub-agents to gather evidence:
| Agent |
Focus |
Key Data Sources |
| Infrastructure & Security |
Framework upgrades, dependency changes, security patches, error monitoring, queue systems |
git log on master, composer.json diffs, config/ changes |
| Frontend & UI |
Visual changes, new features, mobile fixes, content updates, search refactoring |
git log, branch diffs, PR descriptions |
| PDF & Document Systems |
PDF generation, image handling, document architecture |
git log, docs/ architecture docs, ADRs |
| Localisation & Translations |
Multi-language support, AI translation, CSV pipelines, translation fixes |
git log, lang/ files, docs/translation-* |
Each sub-agent should:
- Read commit messages and dates from
git log --oneline --since="..." --until="..." --format="%ai %h %s"
- Read PR descriptions via
gh pr list --state merged --json number,title,body,mergedAt
- Read ADR and architecture docs from
docs/adr/ and docs/
- Separate completed (merged to
master) from in-progress (unmerged branches)
2. Compile Phase
Organise findings into these themes (adjust per project):
- Infrastructure & Security — Framework upgrades, security hardening, monitoring
- Search & Navigation — Property/search refactoring, pagination, mobile menu
- PDF/Document Systems — Generation, image quality, filenames, localisation
- Content & Design — Page updates, CTAs, images, staff data, SEO
- Localisation — Translation pipeline, AI translation, new languages
- Work In Progress — Active unmerged branches clearly separated
For each item, determine:
- Status (completed/live or in-progress)
- Date (merge date or "Live since" in UK format:
Mon, 13 Jul)
- PR reference (number and branch name)
- Plain English explanation — every technical concept needs a glossary entry or lay translation
3. Generate HTML Report
Use the html-output skill and report-template.html for the design system. The HTML must be:
- Self-contained (no external dependencies)
- UK date format with day abbreviations (
Mon, 13 Jul)
Live since badges with dates on every completed card- PR boxes with stats (lines changed, merge date)
- Timeline section with chronological milestones
- Stats row (PR count, lines changed, bug fixes, features)
- Glossary callouts for technical terms
- "Work In Progress" section with branch references
4. Generate Markdown Version
Produce a Markdown version suitable for email (no images, no complex formatting, plain English). Structure:
- Executive summary (bullet points)
- By-the-numbers stats
- Themed sections matching the HTML report
- For each change: date, description in plain English, PR link
5. Update Project Wiki (Optional)
If the project has a wiki:
- Add a "Monthly Development Reports" section to the wiki homepage (
Home.md)
- Add a bullet point with the date range and a brief summary
- Commit and push the wiki repo (usually at
{project-root}/{repo-name}.wiki/)
Reference Files
- report-template.html — HTML report template with design system
- report-template.md — Markdown report template for email
1---2name: monthly-report-generator3description: Generate monthly development reports for clients using git history, PRs, and ADRs. Research commits/PRs/ADRs for a given repo and date range, then produce a plain-English HTML report for non-technical clients plus a Markdown version for email. Optionally update the project wiki. Use when user says "monthly report", "client report", "development report", "report for [client]", "summarise work", or asks you to document work done over a period.4---56# Monthly Report Generator78## Quick Start9101. Identify the repo, date range (typically last 1–2 months), and client name.112. Determine if the repo uses worktrees. If so, locate the `master` worktree.123. Run the research phase (see Workflow below) using async sub-agents.134. Compile findings into HTML and Markdown reports using the templates.145. Optionally update the project wiki.1516## Workflow1718### 1. Research Phase (delegate to async sub-agents)1920Dispatch **4 parallel async sub-agents** to gather evidence:2122| Agent | Focus | Key Data Sources |23|-------|-------|-----------------|24| **Infrastructure & Security** | Framework upgrades, dependency changes, security patches, error monitoring, queue systems | `git log` on master, `composer.json` diffs, `config/` changes |25| **Frontend & UI** | Visual changes, new features, mobile fixes, content updates, search refactoring | `git log`, branch diffs, PR descriptions |26| **PDF & Document Systems** | PDF generation, image handling, document architecture | `git log`, `docs/` architecture docs, ADRs |27| **Localisation & Translations** | Multi-language support, AI translation, CSV pipelines, translation fixes | `git log`, `lang/` files, `docs/translation-*` |2829Each sub-agent should:30- Read commit messages and dates from `git log --oneline --since="..." --until="..." --format="%ai %h %s"`31- Read PR descriptions via `gh pr list --state merged --json number,title,body,mergedAt`32- Read ADR and architecture docs from `docs/adr/` and `docs/`33- Separate **completed** (merged to `master`) from **in-progress** (unmerged branches)3435### 2. Compile Phase3637Organise findings into these themes (adjust per project):38391. **Infrastructure & Security** — Framework upgrades, security hardening, monitoring402. **Search & Navigation** — Property/search refactoring, pagination, mobile menu413. **PDF/Document Systems** — Generation, image quality, filenames, localisation424. **Content & Design** — Page updates, CTAs, images, staff data, SEO435. **Localisation** — Translation pipeline, AI translation, new languages446. **Work In Progress** — Active unmerged branches clearly separated4546For each item, determine:47- **Status** (completed/live or in-progress)48- **Date** (merge date or "Live since" in UK format: `Mon, 13 Jul`)49- **PR reference** (number and branch name)50- **Plain English explanation** — every technical concept needs a glossary entry or lay translation5152### 3. Generate HTML Report5354Use the `html-output` skill and [report-template.html](report-template.html) for the design system. The HTML must be:55- Self-contained (no external dependencies)56- UK date format with day abbreviations (`Mon, 13 Jul`)57- `Live since` badges with dates on every completed card58- PR boxes with stats (lines changed, merge date)59- Timeline section with chronological milestones60- Stats row (PR count, lines changed, bug fixes, features)61- Glossary callouts for technical terms62- "Work In Progress" section with branch references6364### 4. Generate Markdown Version6566Produce a Markdown version suitable for email (no images, no complex formatting, plain English). Structure:67- Executive summary (bullet points)68- By-the-numbers stats69- Themed sections matching the HTML report70- For each change: date, description in plain English, PR link7172### 5. Update Project Wiki (Optional)7374If the project has a wiki:75- Add a "Monthly Development Reports" section to the wiki homepage (`Home.md`)76- Add a bullet point with the date range and a brief summary77- Commit and push the wiki repo (usually at `{project-root}/{repo-name}.wiki/`)7879## Reference Files8081- [report-template.html](report-template.html) — HTML report template with design system82- [report-template.md](report-template.md) — Markdown report template for email
ceilidhboy