Add Codex change review command

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 ## Unreleased
 
+- Add `codex-maintainer-kit review` for human maintainer review briefs from current working-tree changes.
+
 ## 0.2.0 - 2026-06-15
 
 - Add `codex-maintainer-kit audit` for OSS maintenance health scoring and prioritized next actions.

README.md

@@ -33,6 +33,7 @@ Codex can help with that work, but it needs clear repository context and human r
 - Creates starter maintainer files with `init`.
 - Turns readiness gaps into `CODEX_TASKS.md`, JSON, and GitHub issue Markdown files with `tasks`.
 - Adds suggested labels, verification commands, and maintainer review checklists to generated issue drafts.
+- Generates `CODEX_REVIEW.md` from the current working-tree changes so maintainers can review AI-assisted diffs before merge.
 
 ## Installation
 
@@ -74,6 +75,12 @@ Generate Codex-ready maintenance tasks:
 codex-maintainer-kit tasks /path/to/repo --output CODEX_TASKS.md
 ```
 
+Generate a human maintainer review brief for current changes:
+
+```bash
+codex-maintainer-kit review /path/to/repo --output CODEX_REVIEW.md
+```
+
 Generate machine-readable tasks:
 
 ```bash
@@ -129,6 +136,7 @@ See:
 - [examples/MAINTAINER_BRIEF.generated.md](examples/MAINTAINER_BRIEF.generated.md), generated from this repository
 - [examples/CODEX_TASKS.example.md](examples/CODEX_TASKS.example.md)
 - [examples/CODEX_TASKS.generated.md](examples/CODEX_TASKS.generated.md), generated from this repository
+- [examples/CODEX_REVIEW.example.md](examples/CODEX_REVIEW.example.md)
 - [examples/codex-maintainer-kit.toml](examples/codex-maintainer-kit.toml)
 - [schema/codex-tasks.schema.json](schema/codex-tasks.schema.json)
 
@@ -159,8 +167,9 @@ Codex Maintainer Kit focuses on a narrower workflow: creating a practical mainte
 4. Run `codex-maintainer-kit tasks`.
 5. Convert the generated task file or issue drafts into scoped maintenance work.
 6. Ask Codex to make the smallest useful change.
-7. Run tests and inspect the diff.
-8. Merge only after human review.
+7. Run `codex-maintainer-kit review` to create a focused review brief for the current diff.
+8. Run tests and inspect the diff.
+9. Merge only after human review.
 
 ## Development
 
@@ -176,6 +185,7 @@ Run the CLI without installing:
 PYTHONPATH=src python3 -m codex_maintainer_kit.cli brief . --output /tmp/maintainer-brief.md
 PYTHONPATH=src python3 -m codex_maintainer_kit.cli audit . --output /tmp/oss-maintenance-audit.md
 PYTHONPATH=src python3 -m codex_maintainer_kit.cli tasks . --output /tmp/codex-tasks.md
+PYTHONPATH=src python3 -m codex_maintainer_kit.cli review . --output /tmp/codex-review.md
 ```
 
 ## License

docs/superpowers/plans/2026-06-15-review-command.md

@@ -0,0 +1,51 @@
+# Review Command Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a `review` command that turns the current working-tree changes into a human maintainer review brief.
+
+**Architecture:** Reuse `scan_repository()` for changed files and repository hints. Add `review.py` for risk classification, checklist generation, and Markdown rendering. Wire the CLI in `cli.py` with optional configured verification commands.
+
+**Tech Stack:** Python 3.9+, argparse, pytest.
+
+---
+
+### Task 1: Review Report Contract
+
+**Files:**
+- Create: `tests/test_review.py`
+- Modify: `tests/test_cli.py`
+
+- [ ] Write failing tests for clean repositories, source+test changes, workflow/security-sensitive changes, Markdown rendering, and CLI file output.
+- [ ] Run targeted tests and confirm they fail because `codex_maintainer_kit.review` and the CLI command do not exist.
+
+### Task 2: Review Implementation
+
+**Files:**
+- Create: `src/codex_maintainer_kit/review.py`
+- Modify: `src/codex_maintainer_kit/cli.py`
+
+- [ ] Add dataclasses for changed-file review items and review reports.
+- [ ] Classify changed files into docs, tests, source, config, CI, and security-sensitive groups.
+- [ ] Generate a risk level, focused checklist, verification command, and Codex review prompt.
+- [ ] Add `codex-maintainer-kit review` with optional `--output`.
+
+### Task 3: Public Documentation
+
+**Files:**
+- Modify: `README.md`
+- Modify: `CHANGELOG.md`
+- Create: `examples/CODEX_REVIEW.example.md`
+
+- [ ] Document the `review` command and where it fits in the maintainer workflow.
+- [ ] Add an example review report that demonstrates a realistic changed-file set.
+- [ ] Update changelog with the unreleased review feature.
+
+### Task 4: Verification
+
+**Files:**
+- All changed files.
+
+- [ ] Run `python3 -m pytest -p no:cacheprovider tests -q`.
+- [ ] Run `codex-maintainer-kit review` against this repository.
+- [ ] Run `git diff --check` and inspect `git status --short`.

examples/CODEX_REVIEW.example.md

@@ -0,0 +1,36 @@
+# Codex Change Review
+
+Repository: `/path/to/example-repo`
+Git state: `dirty`
+Risk level: **high**
+
+3 changed file(s) detected across: ci, security-sensitive, tests.
+
+## Changed Files
+
+| File | Category | Review note |
+| --- | --- | --- |
+| `.github/workflows/tests.yml` | ci | Confirm the workflow does not require unexpected secrets or broad permissions. |
+| `src/auth/token_store.py` | security-sensitive | Inspect auth, token, permission, or secret-handling behavior carefully. |
+| `tests/test_token_store.py` | tests | Confirm tests cover behavior and would fail for a real regression. |
+
+## Maintainer Review Checklist
+
+- [ ] Read the actual diff, not only this generated summary.
+- [ ] Confirm the change is scoped to one maintenance goal.
+- [ ] Run the verification command or explain why it cannot be run.
+- [ ] Tests were changed: confirm they would fail for the bug or missing behavior.
+- [ ] CI or security-sensitive files changed: confirm permissions, secrets, tokens, and external calls.
+- [ ] Do not auto-merge AI-generated changes without human review.
+
+## Verification Commands
+
+- `python3 -m pytest -p no:cacheprovider tests -q`
+
+## Suggested Codex Review Prompt
+
+Review the changed files above as an OSS maintainer. Focus on correctness, scope control, tests, documentation accuracy, security-sensitive changes, and whether the diff is small enough for human review. Do not approve the change unless the verification commands are practical and the remaining risks are named.
+
+## Human Review Rule
+
+This report is a review aid, not an approval. A human maintainer must inspect the actual diff before merge.

src/codex_maintainer_kit/cli.py

@@ -7,6 +7,7 @@
 from codex_maintainer_kit.audit import build_audit_report, render_audit_markdown
 from codex_maintainer_kit.config import load_config
 from codex_maintainer_kit.renderer import render_maintenance_brief
+from codex_maintainer_kit.review import build_review_report, render_review_markdown
 from codex_maintainer_kit.scanner import scan_repository
 from codex_maintainer_kit.tasks import build_tasks, render_issue_markdown, render_tasks_json, render_tasks_markdown
 
@@ -63,6 +64,8 @@ def main(argv: list[str] | None = None) -> int:
         return _brief(args)
     if args.command == "init":
         return _init(args)
+    if args.command == "review":
+        return _review(args)
     if args.command == "tasks":
         return _tasks(args)
 
@@ -90,6 +93,10 @@ def _build_parser() -> argparse.ArgumentParser:
     init.add_argument("--dry-run", action="store_true", help="List files that would be written.")
     init.add_argument("--force", action="store_true", help="Overwrite existing files.")
 
+    review = subparsers.add_parser("review", help="Generate a human maintainer review brief for current changes.")
+    review.add_argument("repo", nargs="?", default=".", help="Repository path to inspect.")
+    review.add_argument("--output", "-o", help="Write Markdown to this file instead of stdout.")
+
     tasks = subparsers.add_parser("tasks", help="Generate Codex-ready maintenance tasks.")
     tasks.add_argument("repo", nargs="?", default=".", help="Repository path to inspect.")
     tasks.add_argument("--output", "-o", help="Write task output to this file instead of stdout.")
@@ -142,6 +149,20 @@ def _init(args: argparse.Namespace) -> int:
     return 0
 
 
+def _review(args: argparse.Namespace) -> int:
+    scan = scan_repository(args.repo)
+    config = load_config(scan.root)
+    report = build_review_report(scan, verification_command=config.verification_command)
+    markdown = render_review_markdown(report)
+    if args.output:
+        output = Path(args.output)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(markdown, encoding="utf-8")
+    else:
+        print(markdown)
+    return 0
+
+
 def _tasks(args: argparse.Namespace) -> int:
     scan = scan_repository(args.repo)
     config = load_config(scan.root)