@athanatoi94/opsx-review

OpenSpec-style AI review gates for Spec Coding workflows.

It provides two focused gates:

• /opsx:spec_review: reviews an OpenSpec design spec before implementation.
• /opsx:code_review: reviews code changes against the approved OpenSpec change.

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. Packaged review skills are used by default:

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

Run code review against a git range:

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

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 --base main --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-spec-review.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

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
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 / Claude commands:

/opsx:spec_review <change-id> [requirement|technical|testcase]
/opsx:code_review <change-id> [--base <ref>|--staged|--diff <path>]

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>]

/opsx:review and /opsx-review remain compatibility aliases 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 --skills review-skills --strict
opsx-review code_review --change "$CHANGE_ID" --base origin/main --skills review-skills --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.

Version 0.2.0

This version adds Cursor command templates, one-time global install, packaged default review skills, and DeepSeek/OpenAI-compatible runners.

Publishing

Before publishing:

npm run check
npm pack --dry-run

Publish as public scoped package:

npm publish --access public