OpenAURA
§ 00 — Thesis
AI project status reports for GitHub repos —
evidence-backed Markdown briefs generated every week.
OpenAURA is an open-source CLI that turns GitHub activity into weekly AI project reports. It reads pull requests, issues, commits, releases, CI runs, and delivery metrics, then writes a Markdown brief your team can review, edit, and keep in version control.
InputPRs · issues · commits · CI
AnalysisSignals scored by subagents
CadenceWeekly · on-merge · manual
OutputVersioned Markdown briefs
§ 01 — What it is
OpenAURA makes engineering updates verifiable.
Definition · use cases · output
Definition
What is OpenAURA?
OpenAURA is an AI reporting tool for software teams that need reliable weekly project updates from GitHub activity. It converts repository signals into a concise Markdown status report with evidence for shipped work, blockers, risks, and next focus.
Best for
Who uses it?
OpenAURA is built for founders, engineering leads, product managers, and open-source maintainers who want a repeatable status ritual without asking every contributor to rewrite the week from memory.
What it reads
Which signals matter?
The report is grounded in pull requests, merged commits, open and closed issues, releases, CI results, stale work, and declared delivery metrics. Missing data is marked as unknown instead of treated as zero activity.
What it writes
Where does the report live?
OpenAURA writes each update to aura-docs/*.md so the project history stays reviewable, diffable, and close to the code. Teams can commit the brief automatically or edit it before publishing.
§ 02 — Quickstart
Install it, declare the signals, get the weekly brief.
Python 3.11+ · CI-nativeAdd OpenAURA to a repo and let it summarize the work already happening there.
The first brief lands on your chosen schedule.
1. pip install open-aura
2. Create aura.config.yml at your repo root — declare project, trigger, model, signals.
3. Copy the bundled GitHub Actions workflow into .github/workflows/aura.yml and set ANTHROPIC_API_KEY (or OPENAI_API_KEY) as a repo secret.
4. Commit & push. A structured Markdown brief lands in aura-docs/ on the next cadence tick.
aura runFull pipeline: gather → score → summarize → write markdownaura run --dry-runPrint the JSON brief instead of writing to diskaura validateCheck config + env vars; no API or LLM callsaura manifestoPrint the bundled AURA Protocol manifesto
zsh — openaura
~/your-repo
$ pip install open-aura
↳ installed open-aura-0.9.2
$ aura init
↳ wrote aura.config.yml
↳ wrote aura.md # project context
↳ wrote .github/workflows/aura.yml
$ aura validate
✓ config schema ok
✓ ANTHROPIC_API_KEY present
✓ output path writable: aura-docs/
$ aura run --since=last-friday
↳ gatherer | 182 signals collected
↳ scorer | 6 KPIs · 2 risks flagged
↳ summarizer | brief drafted
✓ wrote aura-docs/2026-04-17-brief.md
↳ committed to main · sha e4f1a2c
$ aura manifesto
10 rules loaded · open method · real signals
§ 03 — The AURA Protocol
The manifesto.
10 rules for evidence-backed updates10 rules for evidence-backed
project updates.
The AURA Protocol is a lightweight method for turning repository activity into trustworthy weekly status reports. It keeps every claim tied to a signal, separates facts from recommendations, and preserves the final brief as Markdown in the repo.
R.01Source
The repo is the source of truth.
Each update starts where the work happened: pull requests, issues, commits, releases, work items, CI runs, and declared metrics. Repository evidence outranks memory, meetings, and vibes.
R.02Evidence
Every claim needs a signal.
If a brief says something shipped, slipped, blocked, improved, or regressed, it should identify the signal behind that claim so the reader can trace the conclusion.
R.03Coverage
Missing data is not zero.
No signal means "unknown", not "nothing happened". OpenAURA separates measured inactivity from missing coverage so teams know whether the project is quiet or the instrumentation is thin.
R.04Cadence
Updates must be repeatable.
The same repository, configuration, and time window should produce the same kind of brief every run. The ritual works because it is small enough to survive every week.
R.05Scale
Keep the brief human-sized.
A useful project report is short enough to read and specific enough to act on. It says what changed, what matters, what is blocked, and what decision is needed.
R.06Separation
Separate facts from recommendations.
Findings describe what the signals show. Next focus describes what the team should do about it. Keeping those layers separate makes the reasoning visible.
R.07Accountability
Risks stay visible.
Blockers, failed pipelines, stale pull requests, and unresolved decisions belong in the weekly brief even when they are uncomfortable. OpenAURA reports delivery reality, not optics.
R.08Context
Shared metrics need local context.
Common delivery metrics help, but each repository should declare what "healthy" means for its own domain. A KPI without a local threshold is decoration.
R.09Artifact
Markdown is the artifact.
The canonical update should live beside the work as versioned Markdown. Dashboards can help, but the durable project history should be reviewable, diffable, and owned by the repo.
R.10Authority
Humans decide.
OpenAURA gathers signals, scores delivery health, drafts the summary, and recommends next focus. It does not replace the team; it makes the evidence clearer.
Open method. Real signals.
Weekly clarity.
§ Tweaks
Theme
Signal accent
Hero scale