Open Growth Loop

One evidence-backed maintainer action, without another noisy bot.

Open Growth Loop answers one question for maintainers: what deserves attention next, and what evidence supports it?

Point it at any repository and it combines repository hygiene with local Git state into one maintainer brief. It can preview safe scaffolds for mechanical gaps, hand judgment-heavy work to an agent, and defer to real issue or pull-request demand when the local repository already looks healthy. Local-only mode needs no account or API key and sends nothing away; an explicit --github owner/repo flag can add a bounded, read-only snapshot through the authenticated GitHub CLI.

Quickstart

pip install git+https://github.com/R3ijar/open-growth-loop
ogl audit --workspace path/to/your-repo
ogl steward --workspace path/to/your-repo
ogl steward --workspace path/to/your-repo --no-write  # read-only JSON decision
ogl steward --workspace path/to/your-repo --github owner/repo  # opt-in live public evidence

Thirty seconds later, outbox/audit/latest-audit.md holds a scorecard over 14 hygiene checks — README quality, license, install and quickstart onboarding, docs, examples, community files, changelog, CI, and release-tag cadence:

...plus nine more checks, and then the part that matters:

Every audit recommends exactly one next action, ordered by how much each gap hurts a new visitor, with a step checklist and a Codex-ready prompt — so the next focused change is one paste away. Reports stay local; add outbox/ to your .gitignore if you don't want to keep them.

Context-aware without self-certification

An example repository, template, or monorepo should not receive the same onboarding advice as a conventional package. An optional repository purpose profile lets maintainers qualify or explicitly skip a context-sensitive check with a mandatory reason. Open Growth Loop never guesses purpose from a repository name, and profiles cannot override README or license failures. Qualified and profile-skipped checks stay visible, remain in the score denominator, and never count as passes.

[audit_profile]
purpose = "example"

[audit_profile.checks.install]
disposition = "qualify"
reason = "This repository is editable tutorial material; installation is taught by the surrounding tutorial."

And when the gap is mechanical, you don't even have to write the file:

ogl fix --workspace path/to/your-repo                 # scaffold the recommended action
ogl fix --workspace path/to/your-repo --license mit   # licenses need an explicit choice

ogl fix scaffolds missing community files, changelogs, licenses, issue/PR templates, and an ecosystem-detected starter CI workflow — with TODO markers, never overwriting anything. Checks that need real judgment (README content, docs, quickstart) hand you the Codex prompt instead. A bare repository typically goes from 0% to ~70% with fixes alone; the rest is writing worth doing yourself.

Use It With Codex

The repository includes an installable repo-steward skill. It tells Codex to begin with local evidence, check live maintainer demand when available, choose exactly one bounded action, and keep pushes, releases, merges, comments, and other remote mutations behind explicit approval.

Invoke it with a request such as:

Use $repo-steward to inspect this repository and complete the safest evidence-backed maintainer action.

The skill uses ogl steward as its evidence packet and can opt in to --github owner/repo when current public issues, pull requests, CI runs, and releases should influence the decision. All GitHub commands are reads; the CLI remains useful without an agent or network access.

Maintainer Field Test

Open Growth Loop needs counterexamples more than endorsements. If you maintain a public repository, run ogl steward --no-write and tell us where its selected action was wrong. The 20-minute field test has a structured feedback form and does not require a call or ongoing commitment.

Use It As A GitHub Action

Add one workflow file and the audit runs on every push, straight into the Actions job summary:

name: Repository Audit
on:
  push:
    branches: [main]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: R3ijar/open-growth-loop@main

The action exposes ok and score-percent outputs and an optional strict gate that fails the job when README or LICENSE is missing. Full reference: docs/GITHUB_ACTION.md. This repository runs it on itself.

The Full Loop

The audit covers hygiene; the loop plans from evidence. Drop privacy-safe CSV exports into data/ — Search Console rows, aggregate event counts (date,asset,event,count only), a content inventory, an experiment ledger — and Open Growth Loop turns them into one conservative daily action:

ogl init --workspace .       # create the data files
ogl validate --workspace .   # schema and privacy-safe header checks
ogl plan --workspace .       # one action, fully explained

{
  "action_type": "release_evidence",
  "asset": "/guides/configuration-checklist",
  "confidence": "high",
  "reason": "Staged work should be proven public before creating another asset."
}

Each plan ships with a decision trace (what won, what lost and why, which thresholds applied) and a data freshness report (whether the inputs deserve trust). Completed work and its later outcomes feed back into ranking, so the loop learns locally. Browse real generated reports in the report gallery.

Planner Engine Coverage

Candidates are ranked across the maintainer surfaces that shape OSS adoption, in deliberately conservative priority order:

1. Release evidence — prove staged docs, examples, or package pages are actually public before starting anything new.
2. Outcome memory — record what happened to completed work before repeating it.
3. Funnel dropoff — public pages with enough views but weak install, try, or next-step clicks.
4. Search opportunities — near-ranking pages and low-CTR queries from Search Console exports.
5. Planned assets — the next queued guide or page, only when stronger signals are absent.

Weak evidence is labeled insufficient instead of being spun into a win. The goal is less thrash, not a content treadmill.

Commands

Full walkthroughs, data schemas, thresholds, and column aliases live in the usage guide.

Privacy Boundary

Open Growth Loop is designed around aggregate inputs. The event importer accepts only date,asset,event,count and rejects private-looking columns such as email, user, session, ip, payload, token, or secret. Local-only commands never upload analytics or project files. The optional steward --github owner/repo adapter calls gh only for repository metadata and never writes, comments, labels, merges, closes, or publishes. The project never claims a change worked from tiny samples or missing artifacts.

Documentation

• Usage guide — installation, every command, data files, configuration, and decision rules.
• Repository purpose profiles — explicit context, validation rules, score integrity, and a runnable audit fixture.
• GitHub Action reference — inputs, outputs, strict mode, and scheduled audits.
• Example workflow — a full walkthrough with the bundled sample CSVs.
• Report gallery — what the generated reports look like.
• Runnable examples — synthetic planner workspaces and a context-aware repository-audit fixture.
• Dogfooding — how this repository maintains itself with its own loop.
• Public compatibility study — a transparent ten-repository run, including two defects it exposed and the limits of the evidence.
• Evidence-backed case studies — three repository-specific decision reviews, including rejected recommendations and two regression-tested fixes.
• Adoption and design partners — run a field test and share verifiable feedback.
• Releasing — the tag-driven PyPI release process.
• Roadmap and Changelog.

Project Status

Version prepared on main: v0.3.0. See GitHub Releases for the latest published version. The project is early and is actively seeking maintainer design partners. The repository audit, purpose profiles, steward brief, fix scaffolds, and GitHub Action are ready for field testing; the CSV-driven loop remains available for small maintainer workflows.

Contributing

Issues and pull requests are welcome — CONTRIBUTING.md covers setup and expectations, and docs/NEXT_ISSUES.md lists good starting points. Please keep private product data and unverifiable adoption claims out of examples and docs; ogl privacy-scan and the release-brief guardrails exist for exactly that.

Open Growth Loop is maintained by @R3ijar, who owns scope, releases, and final review. See the design-partner outreach playbook for the public feedback process.

License

Apache-2.0