J-Star Reviewer

When to Use

Use this skill when the user wants to:

install J-Star from npm in any repository
set up .env.local, .jstar/, and .gitignore
initialize or refresh the local code index
run review and audit as separate required steps
use J-Star in automation with --json or --headless
validate the package repo before publishing to npm

Core Rule

review and audit are separate steps.

If the user is serious about a change set, run both:

review for hybrid deterministic + LLM code review
audit for deterministic security audit

Do not present one as a substitute for the other.

Command Prefix

Pick one command prefix and use it consistently for the rest of the session:

Global install: jstar
One-off npm usage: npx jstar-reviewer
Package repo development: pnpm run

Examples below use <cmd> for the global or npx forms.

Consumer Install Flow

Use this in a repository that wants to consume the published npm package.

1. Prerequisites

Node.js 18+
Git repository
Gemini API key
Groq API key

2. Install

Preferred:

pnpm add -g jstar-reviewer

Fallback:

npm install -g jstar-reviewer

No global install:

npx jstar-reviewer --help

3. Set up the repo

<cmd> setup

This should create or update:

.jstar/
.env.example
.gitignore

4. Create `.env.local`

PowerShell:

Copy-Item .env.example .env.local

POSIX shell:

cp .env.example .env.local

Required variables:

GEMINI_API_KEY=your_gemini_key
GROQ_API_KEY=your_groq_key

Optional but useful:

GEMINI_EMBEDDING_MODEL=gemini-embedding-001
REVIEW_MODEL_NAME=moonshotai/kimi-k2-instruct-0905

5. Build the local index

<cmd> init

If indexing fails with a Google 404 for an embedding model, use:

GEMINI_EMBEDDING_MODEL=gemini-embedding-001

Maintainer Flow

Use this inside the jstar-reviewer package repo itself before publishing.

pnpm install
pnpm build
pnpm test
pnpm run index:init
pnpm run audit --json

If you need to test the interactive review path inside the package repo:

git add .
pnpm run review

Required Usage Flow

Before commit or push

git add .
<cmd> review
<cmd> audit

After the commit already exists

<cmd> review --last
<cmd> audit --last

Branch or PR scope

<cmd> review --pr
<cmd> audit --pr

Review Commands

Main review targets:

<cmd> review
<cmd> review --last
<cmd> review --commit <hash>
<cmd> review --range <start> <end>
<cmd> review --pr
<cmd> review --pr --base <branch>

Review outputs:

.jstar/last-review.md
.jstar/session.json

Audit Commands

Main audit targets:

<cmd> audit
<cmd> audit --path src
<cmd> audit --last
<cmd> audit --commit <hash>
<cmd> audit --range <start> <end>
<cmd> audit --pr
<cmd> audit --pr --base <branch>

Audit outputs:

.jstar/audit_report.md
.jstar/audit_report.json

False positives are handled with:

.jstar/audit-ignore.json

Automation Mode

For machine-readable review output:

<cmd> review --json
<cmd> audit --json

For issue debate:

<cmd> chat --headless

Headless commands:

{"action":"list"}
{"action":"debate","issueId":0,"argument":"..."}
{"action":"ignore","issueId":0}
{"action":"accept","issueId":0}
{"action":"exit"}

Decision Rules for the AI

If the repo is missing .jstar/storage, run init before review.
If the user asks for a serious verification pass, run both review and audit.
If the user only wants deterministic security checks, run audit.
If the user only wants code-review findings and fix prompts on a diff, run review.
If review says there are no staged changes, either stage files or switch to --last, --range, or --pr.

jstar-reviewer