claude-init 1.0.53 → 1.0.54

package/.claude/settings.json

@@ -1,7 +1,9 @@
 {
   "permissions": {
     "allow": [
-      "WebSearch"
+      "WebSearch",
+      "Skill(codex-review-code)",
+      "Skill(codex-review-plan)"
     ],
     "deny": [
       "Read(**/.env*)",
@@ -17,5 +19,18 @@
     "type": "command",
     "command": "npx ccusage statusline"
   },
-  "alwaysThinkingEnabled": true
+  "alwaysThinkingEnabled": true,
+  "hooks": {
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "CHANGED=$(git diff --name-only HEAD 2>/dev/null; git ls-files --others --exclude-standard 2>/dev/null); if [ -n \"$CHANGED\" ]; then echo '{\"decision\":\"block\",\"reason\":\"Uncommitted changes since last commit. Run the codex-review-code skill to get a Codex review of these changes before proceeding.\"}'; fi",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
 }

package/.claude/skills/codex-review-code/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: codex-review-code
+description: Get a second-opinion code review from OpenAI Codex CLI (GPT-5.4 xhigh). Use when the user asks for a code review, wants a second pair of eyes, or you want to validate significant changes.
+allowed-tools:
+  - Bash
+  - Read
+  - Glob
+  - Grep
+  - Edit
+  - Write
+  - AskUserQuestion
+---
+
+Get an independent code review from OpenAI's Codex CLI using GPT-5.4 with maximum reasoning effort. Codex acts as a principal engineer providing a second opinion. You have more context than Codex — use your own judgment to decide what feedback to incorporate.
+
+## Invoking Codex
+
+Use `codex exec` to run a one-shot review. Always write output to a temp file for reliable capture.
+
+```bash
+TMPFILE=$(mktemp /tmp/codex-review.XXXXXXXX)
+[ -f "$HOME/.codex/.env" ] && . "$HOME/.codex/.env"
+codex exec \
+  -m gpt-5.4 \
+  -c 'model_reasoning_effort="xhigh"' \
+  -s read-only \
+  --ephemeral \
+  -o "$TMPFILE" \
+  "$PROMPT"
+cat "$TMPFILE"
+rm "$TMPFILE"
+```
+
+**Flags explained:**
+- `-m gpt-5.4` — model selection (always use this for reviews)
+- `-c 'model_reasoning_effort="xhigh"'` — maximum thinking effort, principal-engineer level
+- `-s read-only` — Codex can read the codebase but cannot modify any files (critical for reviews)
+- `--ephemeral` — no conversation persistence, clean context
+- `-o "$TMPFILE"` — write output to file (avoids noisy stdout metadata)
+
+**Critical — temp file creation:** You MUST use `mktemp` exactly as shown above. On macOS, `mktemp` only replaces the X's when they are the **last characters** of the template. Do NOT add a file extension (e.g., `.md`) after the X's — this causes `mktemp` to use the template literally without substitution, creating a file literally named with X's. The template `/tmp/codex-review.XXXXXXXX` (no extension) is correct and must be used verbatim.
+
+**Error handling:** If codex returns a non-zero exit code, read stderr for the error message. Report the error to the user and do not retry automatically — there may be an auth or config issue the user needs to resolve.
+
+## Telling Codex what to review
+
+Codex has shell access — it can run git commands and read files itself. Don't bloat the prompt by embedding diffs or file contents. Instead, tell Codex *what* to do in the prompt and let it retrieve the code.
+
+### Git diff (most common — review uncommitted changes)
+Tell Codex to run `git diff` (or `git diff --cached` for staged changes).
+
+### Git commit(s)
+Tell Codex the commit hash(es) and to run `git show <hash>` or `git log -p <hash1>..<hash2>`.
+
+### Specific files or directory
+Tell Codex the file paths or directory to review and to read them itself.
+
+### Scoping the review
+To narrow what Codex reviews, pass the scope in the prompt itself. For example:
+- "Run `git diff -- src/api/routes.py src/api/middleware.py` and review those changes"
+- "Read the files in `src/auth/` and review them"
+- "Run `git show abc1234 -- lib/` and review only the lib changes"
+
+Codex handles the filtering — no need to embed content.
+
+### Important:
+- Always tell Codex it can run git commands if it needs more context beyond what you asked it to review.
+- Always tell Codex to return an error message (not silently fail) if it cannot access something.
+
+## Constructing the prompt
+
+The prompt to Codex must include these sections:
+
+### 1. Context summary (required)
+A brief summary of what the code changes are for and the goal. This prevents Codex from optimizing for the wrong thing.
+
+### 2. What to review (required)
+Tell Codex what to review — a git command to run, file paths to read, or (rarely) embedded code.
+
+### 3. Focus areas (optional but recommended)
+If you or the user have specific concerns, list them. Examples: "pay special attention to error handling", "check for SQL injection", "verify the caching logic is correct".
+
+### 4. Output format instructions (required)
+Tell Codex exactly how to structure its response:
+
+```
+Return your review as plain text in this format:
+
+## Critical Issues
+Issues that must be fixed — bugs, security vulnerabilities, data loss risks.
+List each with: file, line/section, issue description, and what should change.
+If none, write "None found."
+
+## Improvements
+Code quality, performance, readability, or maintainability suggestions.
+Tag each with a severity: [high] (real impact on correctness, performance, or security if left), [medium] (meaningful quality improvement), [low] (nitpick or style preference).
+List each with: severity tag, file, line/section, what to improve, and why.
+
+Be token-efficient. Use whichever is most concise: a brief description, a function/variable name, a short code snippet, or a one-liner fix. Don't rewrite large blocks of code — describe the change instead.
+
+## Positive Notes
+Things done well that should be kept.
+
+## Summary
+2-3 sentence overall assessment.
+
+Do NOT include metadata, conversation artifacts, or commentary outside this format.
+If you cannot access a file or run a command, say so clearly in your response instead of silently skipping it.
+```
+
+### Example full prompt
+
+```
+You are reviewing code changes in a git repository. Here is the context:
+
+**Goal:** Adding rate limiting middleware to the Express API to prevent abuse of the /api/search endpoint.
+
+**Focus areas:** Check that the rate limit configuration is correct, that the middleware ordering is right, and that error responses follow our existing API format.
+
+You have access to git and the filesystem. If you need more context, run git commands to explore. If you cannot access something, say so clearly.
+
+**What to review:** Run `git diff` to see the uncommitted changes, then review them.
+
+Return your review as plain text in this format:
+[... format instructions from above ...]
+```
+
+## Processing Codex's response
+
+### 1. Read and assess the feedback yourself
+Do NOT blindly apply Codex's suggestions. You have far more context about:
+- The broader codebase and its conventions
+- The user's intent and constraints
+- What has already been tried or discussed
+- Project-specific patterns and trade-offs
+
+For each piece of feedback, decide:
+- **Incorporate** — the feedback is correct and valuable
+- **Adapt** — the spirit is right but the specific suggestion needs adjustment for this codebase
+- **Discard** — the feedback is wrong, irrelevant, or conflicts with known constraints
+
+### 2. Fix what you can
+If Codex identified real issues that you agree with and can fix, fix them before reporting to the user. Don't make the user do work you can handle.
+
+### 3. Report to the user
+Present a clear summary structured as:
+
+**Codex Review Summary:**
+- Brief overview of what Codex found
+
+**My Assessment:**
+- Which feedback points you're incorporating and why
+- Which you're discarding and why
+- Any points you're unsure about and want the user's input on
+
+**Changes Made:**
+- What you fixed based on the review
+- Why those changes improve the code
+
+**For Your Decision:**
+- Any feedback points that require the user's judgment (e.g., architectural trade-offs, business logic questions)
+
+### 4. If Codex returns errors
+If Codex couldn't complete the review (auth issues, timeout, can't access files):
+- Report the error clearly to the user
+- Do NOT retry automatically
+- Suggest what the user might check (codex auth, file permissions, etc.)
+
+## What NOT to do
+
+- Do not treat Codex's feedback as authoritative. It is a second pair of eyes, not the final word.
+- Do not call Codex repeatedly in a loop trying to get different answers.
+- Do not send the entire repository — keep reviews focused on the relevant changes.
+- Do not skip your own assessment. The user is relying on your judgment to filter and contextualize Codex's raw feedback.

package/.claude/skills/codex-review-plan/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: codex-review-plan
+description: Send the current plan to OpenAI Codex CLI for iterative review. Claude and Codex go back-and-forth until Codex approves the plan.
+user_invocable: true
+---
+
+# Codex Plan Review (Iterative)
+
+Send the current implementation plan to OpenAI Codex for review. Claude revises the plan based on Codex's feedback and re-submits until Codex approves. Max 5 rounds.
+
+---
+
+## When to Invoke
+
+- When the user runs `/codex-review-plan` during or after plan mode
+- When the user wants a second opinion on a plan from a different model
+
+## Agent Instructions
+
+When invoked, perform the following iterative review loop:
+
+### Step 1: Generate Session ID
+
+Generate a unique ID to avoid conflicts with other concurrent Claude Code sessions:
+
+```bash
+REVIEW_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | head -c 8)
+```
+
+Use this for all temp file paths: `/tmp/claude-plan-${REVIEW_ID}.md` and `/tmp/codex-review-plan-${REVIEW_ID}.md`.
+
+### Step 2: Capture the Plan
+
+Write the current plan to the session-scoped temporary file. The plan is whatever implementation plan exists in the current conversation context (from plan mode, or a plan discussed in chat).
+
+1. Write the full plan content to `/tmp/claude-plan-${REVIEW_ID}.md`
+2. If there is no plan in the current context, ask the user what they want reviewed
+
+### Step 3: Initial Review (Round 1)
+
+Run Codex CLI in non-interactive mode to review the plan:
+
+```bash
+[ -f "$HOME/.codex/.env" ] && . "$HOME/.codex/.env"
+codex exec \
+  -m gpt-5.4 \
+  -s read-only \
+  -o /tmp/codex-review-plan-${REVIEW_ID}.md \
+  "Review the implementation plan in /tmp/claude-plan-${REVIEW_ID}.md. Focus on:
+1. Correctness - Will this plan achieve the stated goals?
+2. Risks - What could go wrong? Edge cases? Data loss?
+3. Missing steps - Is anything forgotten?
+4. Alternatives - Is there a simpler or better approach?
+5. Security - Any security concerns?
+
+Be specific and actionable. If the plan is solid and ready to implement, end your review with exactly: VERDICT: APPROVED
+
+If changes are needed, end with exactly: VERDICT: REVISE"
+```
+
+**Capture the Codex session ID** from the output line that says `session id: <uuid>`. Store this as `CODEX_SESSION_ID`. You MUST use this exact ID to resume in subsequent rounds (do NOT use `--last`, which would grab the wrong session if multiple reviews are running concurrently).
+
+**Notes:**
+- Use `-m gpt-5.4` as the default model (configured in `~/.codex/config.toml`). If the user specifies a different model (e.g., `/codex-review-plan o4-mini`), use that instead. Store the resolved model name as `MODEL` and use it in all output headers.
+- Use `-s read-only` so Codex can read the codebase for context but cannot modify anything.
+- Use `-o` to capture the output to a file for reliable reading.
+
+### Step 4: Read Review & Check Verdict
+
+1. Read `/tmp/codex-review-plan-${REVIEW_ID}.md`
+2. Present Codex's review to the user:
+
+```
+## Codex Review — Round N (model: ${MODEL})
+
+[Codex's feedback here]
+```
+
+3. Check the verdict:
+   - If **VERDICT: APPROVED** → go to Step 7 (Done)
+   - If **VERDICT: REVISE** → go to Step 5 (Revise & Re-submit)
+   - If no clear verdict but feedback is all positive / no actionable items → treat as approved
+   - If max rounds (5) reached → go to Step 7 with a note that max rounds hit
+
+### Step 5: Revise the Plan
+
+Based on Codex's feedback:
+
+1. **Revise the plan** — address each issue Codex raised. Update the plan content in the conversation context and rewrite `/tmp/claude-plan-${REVIEW_ID}.md` with the revised version.
+2. **Briefly summarize** what you changed for the user:
+
+```
+### Revisions (Round N)
+- [What was changed and why, one bullet per Codex issue addressed]
+```
+
+3. Inform the user what's happening: "Sending revised plan back to Codex for re-review..."
+
+### Step 6: Re-submit to Codex (Rounds 2-5)
+
+Resume the existing Codex session so it has full context of the prior review:
+
+```bash
+[ -f "$HOME/.codex/.env" ] && . "$HOME/.codex/.env"
+codex exec resume ${CODEX_SESSION_ID} \
+  -o /tmp/codex-review-plan-${REVIEW_ID}.md \
+  "I've revised the plan based on your feedback. The updated plan is in /tmp/claude-plan-${REVIEW_ID}.md.
+
+Here's what I changed:
+[List the specific changes made]
+
+Please re-review. If the plan is now solid and ready to implement, end with: VERDICT: APPROVED
+If more changes are needed, end with: VERDICT: REVISE"
+```
+
+Then go back to **Step 4** (Read Review & Check Verdict).
+
+**Important:** If `resume ${CODEX_SESSION_ID}` fails (e.g., session expired), fall back to a fresh `codex exec` call with `-s read-only` and context about the prior rounds included in the prompt. **Capture the new session ID** from the fresh exec output and update `CODEX_SESSION_ID` so subsequent rounds resume from the correct session.
+
+**Error handling:** If Codex returns a non-zero exit code or the output file is empty, report the error to the user and do not continue the loop automatically. Check stderr for auth failures, transport errors, or timeout messages.
+
+### Step 7: Present Final Result
+
+Once approved (or max rounds reached):
+
+```
+## Codex Review — Final (model: ${MODEL})
+
+**Status:** ✅ Approved after N round(s)
+
+[Final Codex feedback / approval message]
+
+---
+**The plan has been reviewed and approved by Codex. Ready for your approval to implement.**
+```
+
+If max rounds were reached without approval:
+
+```
+## Codex Review — Final (model: ${MODEL})
+
+**Status:** ⚠️ Max rounds (5) reached — not fully approved
+
+**Remaining concerns:**
+[List unresolved issues from last review]
+
+---
+**Codex still has concerns. Review the remaining items and decide whether to proceed or continue refining.**
+```
+
+### Step 8: Cleanup
+
+Remove the session-scoped temporary files:
+```bash
+rm -f /tmp/claude-plan-${REVIEW_ID}.md /tmp/codex-review-plan-${REVIEW_ID}.md
+```
+
+## Loop Summary
+
+```
+Round 1: Claude sends plan → Codex reviews → REVISE?
+Round 2: Claude revises → Codex re-reviews (resume session) → REVISE?
+Round 3: Claude revises → Codex re-reviews (resume session) → APPROVED ✅
+```
+
+Max 5 rounds. Each round preserves Codex's conversation context via session resume.
+
+## Rules
+
+- Claude **actively revises the plan** based on Codex feedback between rounds — this is NOT just passing messages, Claude should make real improvements
+- Default model is `gpt-5.4`. Accept model override from the user's arguments (e.g., `/codex-review-plan o4-mini`)
+- Always use read-only sandbox mode — Codex should never write files
+- Max 5 review rounds to prevent infinite loops
+- Show the user each round's feedback and revisions so they can follow along
+- If Codex CLI is not installed or fails, inform the user and suggest `npm install -g @openai/codex`
+- If a revision contradicts the user's explicit requirements, skip that revision and note it for the user

package/.claude/skills/codex-usage-check/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: codex-usage-check
+description: Check Codex CLI account usage by running `codexbar usage --source cli` and interpreting the output. Use when the user asks about Codex usage, remaining session/weekly quota, reset times, burn rate, pace, or whether Codex is close to running out.
+---
+
+# Codex Usage Check
+
+Use this skill to inspect Codex CLI usage quickly and report the important numbers in plain language.
+
+## Quick Start
+
+Run:
+
+```bash
+codexbar usage --source cli
+```
+
+Prefer reporting these fields when present:
+- Session remaining percentage
+- Session reset time
+- Weekly remaining percentage
+- Weekly reset time
+- Pace / deficit / expected usage
+- Estimated time until exhaustion
+- Credits remaining
+
+## Workflow
+
+1. Run `codexbar usage --source cli`.
+2. Read the output exactly as shown; do not invent missing fields.
+3. Summarize the status in short, user-friendly language.
+4. If the user wants details, include the raw lines or a tighter breakdown.
+
+## Interpretation Guide
+
+- `Session: 90% left` means the short-term session budget is mostly available.
+- `Weekly: 54% left` means a bit over half of the weekly budget remains.
+- `Pace: 22% in deficit | Expected 24% used` means current consumption is slightly better than the expected burn curve.
+- `Runs out in 2d` is an estimate, not a guarantee.
+- `Credits: 0 left` means no extra credits remain beyond the tracked allowance.
+
+## Output Style
+
+Default to a concise summary such as:
+
+- Session: 90% left, resets in 1h 33m
+- Weekly: 54% left, resets in 5d 7h
+- Pace: 22% under expected burn, estimated exhaustion in 2d
+- Credits: 0 left
+
+If the command fails, report the failure briefly and include the error text.
+
+## Notes
+
+- Use the command output as the source of truth.
+- Do not assume plan type or hard quota limits unless the output states them.
+- If the output format changes, still extract only what is explicitly visible.

package/.claude/skills/codex-usage-check/scripts/check-codex-usage.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+codexbar usage --source cli

package/README.md

@@ -41,6 +41,7 @@ Running `npx claude-init` sets up your current directory with:
 - `.devcontainer/` - Development container configuration (also added `codex-cli` and `spec-kit`.)
 - `.claude/settings.json` - Claude-specific settings
 - `.claude/commands/` - Custom Claude commands
+- `.claude/skills/` - Reusable skill configurations
 - `.claude/agents/` - Specialized agent configurations
 
 ### What It Does
@@ -69,6 +70,13 @@ Running `npx claude-init` sets up your current directory with:
   - Answer **Yes** to replace your customized `.md` files with fresh templates (while still adding any missing files)
   - Answer **No** (default) to keep your existing `.md` files and only add missing files
 
+#### 🧩 .claude/skills
+- **Interactive prompt**: You'll be asked whether to install `.claude/skills` files
+  - Answer **Yes** (default) to install skill files
+  - Answer **No** to skip skills entirely
+- **If missing**: Creates complete directory with all skill configurations
+- **If exists**: Skips entirely to preserve your setup
+
 #### 🤖 .claude/agents
 - **Interactive prompt**: You'll be asked whether to install `.claude/agents` files
   - Answer **Yes** (default) to install/update agent files
@@ -90,7 +98,13 @@ When running interactively (in a terminal), `claude-init` will ask you:
    - If **Yes**: Replaces existing `.md` files with templates, still adds missing files
    - If **No**: Keeps your existing files, only adds missing files
 
-3. **Install .claude/agents?**
+3. **Install .claude/skills?**
+   - Prompt: `Install .claude/skills files? (Y/n):`
+   - Default: **Yes** (installs skills)
+   - If **Yes**: Creates skills directory with all skill files
+   - If **No**: Skips skills entirely (shown in summary)
+
+4. **Install .claude/agents?**
    - Prompt: `Install .claude/agents files? (Y/n):`
    - Default: **Yes** (installs agents)
    - If **Yes**: Installs/updates agents as normal
@@ -99,6 +113,7 @@ When running interactively (in a terminal), `claude-init` will ask you:
 **Non-interactive mode (CI/scripts)**: When `process.stdin.isTTY` is false (e.g., in CI pipelines), prompts are skipped and defaults are used:
 - `.claude/settings.json` is **not** overwritten (preserves custom settings)
 - `.claude/commands/*.md` files are **not** overwritten (preserves customizations)
+- `.claude/skills` **is** installed (matches current behavior)
 - `.claude/agents` **is** installed (matches current behavior)
 
 ## Example Output
@@ -109,12 +124,14 @@ When running interactively (in a terminal), `claude-init` will ask you:
 🚀 Claude Environment Initializer
 Initializing in: /path/to/your/project
 
+Install .claude/skills files? (Y/n): y
 Install .claude/agents files? (Y/n): y
 
 ✓ Created new CLAUDE.md
 ✓ Created .devcontainer directory
 ✓ Created .claude/settings.json
 ✓ Created .claude/commands with 5 files
+✓ Created .claude/skills directory
 ✓ Created .claude/agents with 3 files
 
 📊 Summary:
@@ -131,6 +148,7 @@ Install .claude/agents files? (Y/n): y
 Initializing in: /path/to/your/project
 
 Overwrite existing .claude/commands/*.md with template versions? (y/N): n
+Install .claude/skills files? (Y/n): n
 Install .claude/agents files? (Y/n): n
 Overwrite existing .claude/settings.json with template version? (y/N): n
 
@@ -144,6 +162,7 @@ Overwrite existing .claude/settings.json with template version? (y/N): n
    Updated: 1 items
    Skipped: 3 items (already exist)
    Files added: 1
+   - .claude/skills skipped by user
    - .claude/agents skipped by user
 
 ✅ Claude environment is already up to date!
@@ -156,9 +175,10 @@ Overwrite existing .claude/settings.json with template version? (y/N): n
 Initializing in: /path/to/your/project
 
 ✓ Created new CLAUDE.md
-✓ Created .devcontainer directory  
+✓ Created .devcontainer directory
 ✓ Created .claude/settings.json
 ↻ Added 2 missing files to .claude/commands (2 files)
+✓ Created .claude/skills directory
 - All files in .claude/agents are up to date
 
 📊 Summary:
@@ -182,6 +202,7 @@ your-project/
 └── .claude/
     ├── settings.json            # Claude settings
     ├── commands/                # Custom commands
+    ├── skills/                  # Reusable skills
     └── agents/                  # Specialized agents
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-init",
-  "version": "1.0.53",
+  "version": "1.0.54",
   "description": "Initialize Claude development environment with configurations and templates",
   "type": "module",
   "bin": {

package/src/cli.js

@@ -83,6 +83,12 @@ export async function cli() {
     }
   }
 
+  // Determine if we should install .claude/skills
+  const includeSkills = await promptYesNo(
+    'Install .claude/skills files?',
+    true
+  );
+
   // Determine if we should install .claude/agents
   const includeAgents = await promptYesNo(
     'Install .claude/agents files?',
@@ -155,6 +161,14 @@ export async function cli() {
     });
   }
 
+  // Conditionally add .claude/skills task
+  if (includeSkills) {
+    tasks.push({
+      name: '.claude/skills',
+      handler: () => handleDirectoryMirror(targetDir, '.claude/skills')
+    });
+  }
+
   // Conditionally add .claude/agents task
   if (includeAgents) {
     tasks.push({
@@ -208,6 +222,10 @@ export async function cli() {
     console.log(chalk.gray(`   - devcontainer skipped by user`));
   }
 
+  if (!includeSkills) {
+    console.log(chalk.gray(`   - .claude/skills skipped by user`));
+  }
+
   if (!includeAgents) {
     console.log(chalk.gray(`   - .claude/agents skipped by user`));
   }

package/.claude/commands/codex-usage.md

@@ -1 +0,0 @@
-!codexbar usage --source cli

package/.claude/commands/summarize.md

@@ -1 +0,0 @@
-!npx -y @steipete/summarize "$ARGUMENTS" --length xl