@athanatoi94/opsx-review

OpenSpec-style AI review gates for Spec Coding workflows.

It provides two focused gates:

• /prompts:opsx-spec-review: reviews an OpenSpec design spec before implementation in Codex CLI.
• /prompts:opsx-code-review: reviews code changes against the approved OpenSpec change in Codex CLI.
• /prompts:opsx-ci: runs deterministic CI checks for a change in Codex CLI.
• /prompts:opsx-approve-plan: optional local acknowledgement only; it is not a multi-person approval gate.

Both gates support Chinese and English output via --lang zh|en and produce:

• structured JSON for machines and CI
• Markdown reports for humans and PR comments
• quality gates with decision, scores, risks, evidence, owners and close conditions

Requirements

• Node.js 18+
• Local codex CLI available in PATH, or a DeepSeek/OpenAI-compatible endpoint
• Run codex login first if your local Codex CLI is not authenticated
• An OpenSpec-style project with openspec/changes/<change-id>/

Quick Use

Run spec review without installing. The core review rubric is built in; pass --skills <dir> only for repository-specific additions:

npx @athanatoi94/opsx-review spec_review --change add-dark-mode --flow requirement 

Run code review against the current working tree (git diff HEAD by default):

npx @athanatoi94/opsx-review code_review --change add-dark-mode

Run English reports:

npx @athanatoi94/opsx-review spec_review --change add-dark-mode --flow requirement --lang en
npx @athanatoi94/opsx-review code_review --change add-dark-mode --lang en

One-time global install for local tools:

npm install -g @athanatoi94/opsx-review
opsx-review install-global

This installs global command templates for supported tools where possible:

~/.cursor/commands/opsx-spec-review.md
~/.cursor/commands/opsx-code-review.md
~/.codex/prompts/opsx-propose.md
~/.codex/prompts/opsx-apply.md
~/.codex/prompts/opsx-spec-review.md
~/.codex/prompts/opsx-ci.md
~/.codex/prompts/opsx-code-review.md
~/.claude/commands/opsx-spec-review.md
~/.claude/commands/opsx-code-review.md
~/.opsx-review/commands/deepseek/*.md

Project initialization is optional. Use it only when the project should own local command templates, review skills, and npm scripts:

npm install -D @athanatoi94/opsx-review
npx opsx-review init

Install only the command templates for the tool your team uses:

npx opsx-review init --tools codex
npx opsx-review init --tools cursor
npx opsx-review init --tools claude

When --tools codex is selected, the reusable opsx-minimal-change Skill is also installed at .codex/skills/opsx-minimal-change/.

Multiple tools are comma-separated (--tools codex,claude). The review skills and npm scripts are shared and are installed for every selection. When --tools is omitted, all supported command templates are installed for backward compatibility.

Then run either the project scripts or the global CLI:

npm run openspec:spec-review -- --change add-dark-mode --flow requirement --strict
npm run openspec:code-review -- --change add-dark-mode --base main --strict
 npm run openspec:approve-plan -- --change add-dark-mode --by "Alice" --confirm
 npm run openspec:ci -- --change add-dark-mode --profile npm --strict
opsx-review spec_review --change add-dark-mode --flow requirement --strict
opsx-review code_review --change add-dark-mode --base main --strict

Slash Commands

After opsx-review init, project-level command templates are installed for Codex, Claude, and Cursor.

Codex commands:

/prompts:opsx-propose <change-id> [description]
/prompts:opsx-apply <change-id>
/prompts:opsx-spec-review <change-id> [requirement|technical|testcase]
/prompts:opsx-ci <change-id>
/prompts:opsx-code-review <change-id> [--base <ref>|--staged|--diff <path>]
/prompts:opsx-ci <change-id>

Cursor commands use hyphenated names because Cursor command names come from .cursor/commands/*.md filenames:

/opsx-spec-review <change-id> [requirement|technical|testcase]
/opsx-code-review <change-id> [--base <ref>|--staged|--diff <path>]

/prompts:opsx-review remains a compatibility alias for spec review. For English output, add --lang en.

Spec Review

Review an OpenSpec change before implementation:

opsx-review spec_review --change <change-id> --flow requirement
opsx-review spec_review --change <change-id> --flow technical --project-path .
opsx-review spec_review --change <change-id> --flow testcase

Review standalone files:

opsx-review spec_review --file docs/prd.md --flow requirement

Default outputs for --change <id>:

openspec/changes/<change-id>/spec-review.json
openspec/changes/<change-id>/spec-review.md

Code Review

Review code changes against an OpenSpec change:

opsx-review code_review --change <change-id> --base main
opsx-review code_review --change <change-id> --base main --head feature/add-dark-mode
opsx-review code_review --change <change-id> --staged
opsx-review code_review --change <change-id> --diff /path/to/change.diff

Default behavior without --base, --staged, or --diff is git diff HEAD.

Default outputs for --change <id>:

openspec/changes/<change-id>/code-review.json
openspec/changes/<change-id>/code-review.md

DeepSeek and Local Models

Use hosted DeepSeek:

export DEEPSEEK_API_KEY=<your-key>
opsx-review spec_review --change <change-id> --runner deepseek --model deepseek-chat --strict
opsx-review code_review --change <change-id> --base main --runner deepseek --model deepseek-chat --strict

Use a local OpenAI-compatible endpoint, such as a local DeepSeek model exposed at /v1/chat/completions:

opsx-review spec_review --change <change-id> --runner local-deepseek --api-base http://localhost:11434/v1 --model deepseek-r1:7b --strict
opsx-review code_review --change <change-id> --base main --runner local-deepseek --api-base http://localhost:11434/v1 --model deepseek-r1:7b --strict

You can also configure defaults with environment variables:

export OPSX_REVIEW_RUNNER=deepseek
export DEEPSEEK_API_KEY=<your-key>
export DEEPSEEK_MODEL=deepseek-chat

CI Gates

Use strict mode to fail unless the decision is 准入:

opsx-review spec_review --change "$CHANGE_ID" --flow requirement --strict
opsx-review code_review --change "$CHANGE_ID" --base origin/main --strict

Init

opsx-review init

This writes the following into the target project:

review-skills/*.md
review-skills-en/*.md
.codex/prompts/opsx-review.md
.codex/prompts/opsx-spec-review.md
.codex/prompts/opsx-code-review.md
.claude/commands/opsx-review.md
.claude/commands/opsx-spec-review.md
.claude/commands/opsx-code-review.md
.cursor/commands/opsx-review.md
.cursor/commands/opsx-spec-review.md
.cursor/commands/opsx-code-review.md
openspec/OPSX_REVIEW.md
package.json scripts.openspec:review
package.json scripts.openspec:spec-review
package.json scripts.openspec:code-review

Options

spec_review          Review OpenSpec documents before implementation.
code_review          Review code changes against an OpenSpec change.
--change <id>        Review openspec/changes/<id> as one spec bundle.
--file <path>        Review a single markdown/text file. Can be repeated for spec_review.
--root <dir>         Target project root. Defaults to current working directory.
--flow <flow>        requirement, technical, testcase, or Chinese flow name.
--skills <dir>       Append markdown files in a skills directory.
--lang <zh|en>       Output language. Defaults to zh.
--project-path <dir> Add target project context for technical spec review.
--diff <path>        Read a pre-generated diff file for code_review.
--base <ref>         Git base ref for code_review. Defaults to HEAD when omitted.
--head <ref>         Git head ref for code_review. Used with --base.
--staged             Review staged changes with git diff --cached.
--out <path>         Write structured JSON result.
--report <path>      Write markdown report. Defaults beside JSON output.
--runner <runner>    codex, deepseek, local-deepseek, or openai-compatible. Defaults to codex.
--api-base <url>     Chat completions API base for openai-compatible runners.
--api-key <key>      API key. Defaults to DEEPSEEK_API_KEY or OPENAI_API_KEY.
--model <name>       Model for openai-compatible runners.
--strict             Exit 1 unless decision_status is pass.

Decision Status

review.decision_status is the stable machine field used by --strict:

pass         Gate passed.
conditional  Gate can pass after listed issues are addressed.
hold         Gate should not pass yet.

review.decision is localized for humans, for example 准入 in Chinese or Pass in English.

One-command delivery loop

After opsx-review init --tools codex in a project, the developer-facing interface in Codex CLI is only /prompts:opsx-*. The npm commands below are implementation details used by those prompts; developers do not need to type them directly.

# 1. AI quality review of proposal/design (optional but recommended)
/prompts:opsx-spec-review <change-id> technical

# 2. AI implementation; for a solo developer, /prompts:opsx-apply is the approval-to-implement action
/prompts:opsx-apply <change-id>

# 3. AI-orchestrated CI/test gate
/prompts:opsx-ci <change-id>

# 4. AI first code review
/prompts:opsx-code-review <change-id>

# 5. Human final code review and merge (manual; no CLI bypass)

The optional acknowledgement command is not part of the normal developer flow. For multi-person technical review, use the repository's PR/DevOps approval rules. /prompts:opsx-ci records reproducible test evidence and /prompts:opsx-code-review produces the AI first-review report. Human review remains the final merge gate.

Version 0.3.1

This version makes minimal change the default design, implementation, and review policy; loads extra review skills only when requested; and removes the package self-dependency.

Publishing

Before publishing:

npm run check
npm pack --dry-run

Publish as public scoped package:

npm publish --access public