{"id":50931613,"url":"https://github.com/goonobu-dot/codex-maintainer-kit","last_synced_at":"2026-06-17T05:02:25.343Z","repository":{"id":364795742,"uuid":"1269143945","full_name":"goonobu-dot/codex-maintainer-kit","owner":"goonobu-dot","description":"CLI that helps OSS maintainers route real maintenance work to OpenAI Codex — brief, tasks, and human-reviewed merges.","archived":false,"fork":false,"pushed_at":"2026-06-14T12:28:58.000Z","size":33,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T16:09:57.274Z","etag":null,"topics":["cli","codex","maintainer","open-source","openai","oss-tools","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goonobu-dot.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-14T11:03:58.000Z","updated_at":"2026-06-14T12:29:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/goonobu-dot/codex-maintainer-kit","commit_stats":null,"previous_names":["goonobu-dot/codex-maintainer-kit"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/goonobu-dot/codex-maintainer-kit","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goonobu-dot%2Fcodex-maintainer-kit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goonobu-dot%2Fcodex-maintainer-kit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goonobu-dot%2Fcodex-maintainer-kit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goonobu-dot%2Fcodex-maintainer-kit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goonobu-dot","download_url":"https://codeload.github.com/goonobu-dot/codex-maintainer-kit/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goonobu-dot%2Fcodex-maintainer-kit/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34434496,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-17T02:00:05.408Z","response_time":127,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","codex","maintainer","open-source","openai","oss-tools","python"],"created_at":"2026-06-17T05:02:24.526Z","updated_at":"2026-06-17T05:02:25.335Z","avatar_url":"https://github.com/goonobu-dot.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Codex Maintainer Kit\n\nCodex Maintainer Kit prepares open source repositories for Codex-assisted maintenance.\n\nIt scans a local repository, identifies basic maintenance gaps, and generates a `MAINTAINER_BRIEF.md` that a human maintainer can hand to Codex before asking it to improve docs, tests, issue templates, release notes, or repository instructions.\n\nThe goal is not to replace maintainers. The goal is to make recurring maintenance work easier to review, delegate, and verify.\n\n## Why This Exists\n\nOpen source maintenance is rarely just writing new code. Maintainers spend time on:\n\n- keeping README and contribution docs accurate\n- adding tests before refactors\n- preparing releases and changelogs\n- reviewing pull requests\n- making issue reports easier to act on\n- deciding what AI-generated changes are safe to merge\n\nCodex can help with that work, but it needs clear repository context and human review rules. This kit creates that starting context.\n\n## What It Does\n\n- Detects common maintainer files such as `README.md`, `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`, `AGENTS.md`, issue templates, CI workflows, and tests.\n- Detects simple project hints such as Python, JavaScript, Go, Rust, Ruby, PHP, Java, .NET, and Swift markers.\n- Summarizes current Git working-tree changes.\n- Generates an OSS maintenance audit with a health score, maintainer essentials checklist, and prioritized next actions.\n- Generates a Markdown maintainer brief with:\n  - repository readiness checklist\n  - Codex task queue\n  - suggested Codex prompt\n  - human review rule\n- Creates starter maintainer files with `init`.\n- Turns readiness gaps into `CODEX_TASKS.md`, JSON, and GitHub issue Markdown files with `tasks`.\n- Adds suggested labels, verification commands, and maintainer review checklists to generated issue drafts.\n- Generates `CODEX_REVIEW.md` from the current working-tree changes so maintainers can review AI-assisted diffs before merge.\n\n## Installation\n\nFrom a local checkout:\n\n```bash\npython3 -m pip install -e .\n```\n\n## GitHub Action\n\nUse [`codex-maintainer-action`](https://github.com/goonobu-dot/codex-maintainer-action) when you want GitHub Actions to generate maintenance artifacts automatically:\n\n```yaml\n- uses: goonobu-dot/codex-maintainer-action@v0.2.0\n  with:\n    output-dir: codex-maintenance\n```\n\nThe action runs this CLI, writes a GitHub Actions job summary, and uploads `OSS_MAINTENANCE_AUDIT.md`, `MAINTAINER_BRIEF.md`, `CODEX_TASKS.md`, `codex-tasks.json`, and `CODEX_REVIEW.md` as workflow artifacts.\n\n## Usage\n\nGenerate an OSS maintenance audit:\n\n```bash\ncodex-maintainer-kit audit /path/to/repo --output OSS_MAINTENANCE_AUDIT.md\n```\n\nGenerate a maintainer brief:\n\n```bash\ncodex-maintainer-kit brief /path/to/repo --output MAINTAINER_BRIEF.md\n```\n\nGenerate Codex-ready maintenance tasks:\n\n```bash\ncodex-maintainer-kit tasks /path/to/repo --output CODEX_TASKS.md\n```\n\nGenerate a human maintainer review brief for current changes:\n\n```bash\ncodex-maintainer-kit review /path/to/repo --output CODEX_REVIEW.md\n```\n\nGenerate machine-readable tasks:\n\n```bash\ncodex-maintainer-kit tasks /path/to/repo --format json --output codex-tasks.json\n```\n\nThe JSON output shape is documented in [schema/codex-tasks.schema.json](schema/codex-tasks.schema.json).\n\nGenerate GitHub issue drafts:\n\n```bash\ncodex-maintainer-kit tasks /path/to/repo --github-issues-dir .github/generated-maintenance-issues\n```\n\nCustomize task output with a local config file:\n\n```toml\n# codex-maintainer-kit.toml\nproject_name = \"Example OSS Project\"\nverification_command = \"python3 -m pytest -p no:cacheprovider tests -q\"\nrelease_command = \"gh release create vX.Y.Z --title vX.Y.Z --notes-file CHANGELOG.md\"\ndefault_labels = [\"maintenance\", \"codex\"]\n```\n\nCurrently, `tasks` uses `verification_command` and `default_labels` when generating Markdown, JSON, and GitHub issue drafts. Unknown keys are ignored to keep the config format forwards-compatible.\n\nPreview starter files:\n\n```bash\ncodex-maintainer-kit init /path/to/repo --dry-run\n```\n\nCreate starter files:\n\n```bash\ncodex-maintainer-kit init /path/to/repo\n```\n\nThe `init` command creates:\n\n- `AGENTS.md`\n- `CONTRIBUTING.md`\n- `.github/ISSUE_TEMPLATE/maintenance.md`\n\nExisting files are skipped unless `--force` is passed.\n\n## Example Output\n\nSee:\n\n- [examples/OSS_MAINTENANCE_AUDIT.generated.md](examples/OSS_MAINTENANCE_AUDIT.generated.md), generated from this repository\n- [examples/MAINTAINER_BRIEF.example.md](examples/MAINTAINER_BRIEF.example.md)\n- [examples/MAINTAINER_BRIEF.generated.md](examples/MAINTAINER_BRIEF.generated.md), generated from this repository\n- [examples/CODEX_TASKS.example.md](examples/CODEX_TASKS.example.md)\n- [examples/CODEX_TASKS.generated.md](examples/CODEX_TASKS.generated.md), generated from this repository\n- [examples/CODEX_REVIEW.example.md](examples/CODEX_REVIEW.example.md)\n- [examples/codex-maintainer-kit.toml](examples/codex-maintainer-kit.toml)\n- [schema/codex-tasks.schema.json](schema/codex-tasks.schema.json)\n\n## Codex for Open Source\n\nThis project was created for maintainers who want to use Codex in open source workflows without removing human review.\n\nThe application notes and publishing checklist live in:\n\n- [docs/CODEX_FOR_OSS_APPLICATION.md](docs/CODEX_FOR_OSS_APPLICATION.md)\n- [docs/PUBLISHING_CHECKLIST.md](docs/PUBLISHING_CHECKLIST.md)\n- [docs/RELEASE_WORKFLOW.md](docs/RELEASE_WORKFLOW.md)\n\n## How This Differs From Existing Tools\n\nThis project is intentionally not a replacement for mature repository health or security tools.\n\n- [OpenSSF Scorecard](https://github.com/ossf/scorecard) measures open source security posture.\n- [Repolinter](https://github.com/todogroup/repolinter) linted repository metadata and policy files.\n\nCodex Maintainer Kit focuses on a narrower workflow: creating a practical maintenance brief, turning gaps into Codex-ready tasks, generating issue drafts, and keeping human review as the final checkpoint.\n\n## Maintainer Workflow\n\n1. Run `codex-maintainer-kit audit` to understand the repository's maintenance health.\n2. Run `codex-maintainer-kit brief`, or run `codex-maintainer-action` in GitHub Actions.\n3. Review the generated checklist.\n4. Run `codex-maintainer-kit tasks`.\n5. Convert the generated task file or issue drafts into scoped maintenance work.\n6. Ask Codex to make the smallest useful change.\n7. Run `codex-maintainer-kit review` to create a focused review brief for the current diff.\n8. Run tests and inspect the diff.\n9. Merge only after human review.\n\n## Development\n\nRun tests:\n\n```bash\npython3 -m pytest tests -q\n```\n\nRun the CLI without installing:\n\n```bash\nPYTHONPATH=src python3 -m codex_maintainer_kit.cli brief . --output /tmp/maintainer-brief.md\nPYTHONPATH=src python3 -m codex_maintainer_kit.cli audit . --output /tmp/oss-maintenance-audit.md\nPYTHONPATH=src python3 -m codex_maintainer_kit.cli tasks . --output /tmp/codex-tasks.md\nPYTHONPATH=src python3 -m codex_maintainer_kit.cli review . --output /tmp/codex-review.md\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoonobu-dot%2Fcodex-maintainer-kit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoonobu-dot%2Fcodex-maintainer-kit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoonobu-dot%2Fcodex-maintainer-kit/lists"}