ccsetup 1.2.0 → 1.2.1

package/template/AGENTS.md

@@ -0,0 +1,43 @@
+# Codex Project Instructions
+
+## Project Overview
+
+[Brief description of your project goes here]
+
+## Primary Working Files
+
+- `AGENTS.md` — project-specific guidance for Codex
+- `.codex/skills/` — project-local Codex skills for this project (`prd`, `ralph`, `codex-review`)
+- `docs/codex-setup.md` — Codex setup notes for this repo
+- `docs/ROADMAP.md` — project goals and status
+- `tickets/` — task tracking
+- `plans/` — implementation and architecture plans
+
+## Working Expectations
+
+- Read this file before making changes.
+- Check `docs/ROADMAP.md` and relevant tickets before starting non-trivial work.
+- Prefer small, reviewable changes.
+- Run the project quality checks before finishing.
+
+## Repo Workflow
+
+- Use plans in `plans/` for larger features.
+- Track implementation work in `tickets/`.
+- Use `scripts/codex-review/codex-review.sh` when you want a second-opinion review from Codex CLI.
+- Use `scripts/ralph/ralph.sh --tool codex` for Ralph runs through Codex CLI.
+
+## Codex Skills
+
+This project ships project-local Codex skills in `.codex/skills/`, mirroring the Claude skill set:
+
+- `prd`
+- `ralph`
+- `codex-review`
+
+Keep these skills in the repository alongside `AGENTS.md` and the project docs.
+
+## Project Conventions
+
+- Update this file when you discover project-wide rules that future Codex sessions should know.
+- Keep project-specific conventions here, and put reusable workflow guidance into project-local skills.

package/template/CLAUDE.md

@@ -17,10 +17,12 @@
 ├── CLAUDE.md          # This file - project instructions for Claude
 ├── .claude/
 │   ├── agents/        # 8 core agents (backend, blockchain, checker, coder, frontend, planner, researcher, shadcn)
-│   └── skills/        # /prd and /ralph slash commands
+│   ├── skills/        # /prd, /ralph, and /codex-review slash commands
+│   └── hooks/         # Workflow selector and codex-review hooks
 ├── agents/            # Documentation only — see .claude/agents/ for active agents
 ├── scripts/
-│   └── ralph/         # Autonomous agent loop (ralph.sh + agent instructions)
+│   ├── ralph/         # Autonomous agent loop (ralph.sh + Claude/Codex instructions)
+│   └── codex-review/  # Codex CLI review script (plans, implementations, code changes)
 ├── docs/              # Project documentation
 ├── plans/             # Project plans and architectural documents
 └── tickets/           # Task tickets and issues
@@ -67,19 +69,24 @@
 
 - **/prd** — Scans the codebase, then generates a structured PRD with real file paths and auto-detected quality criteria. Saves to `tasks/prd-[feature-name].md`.
 - **/ralph** — Converts a PRD into `scripts/ralph/prd.json` for autonomous execution with quality checks and file hints per story.
+- **/codex-review** — Reviews plans, validates implementations against plans, or reviews code changes. Auto-detects what to review based on context. Iterates up to 3 times.
+- **/secops** — **NEVER install packages without running this first.** Scans dependencies for vulnerabilities using OSV Scanner. Use before any `pip`, `npm`, `cargo`, `gem`, or other package manager install.
 
 ## Ralph — Autonomous Agent Loop
 
 Ralph implements user stories from a PRD one at a time in a loop, with subagent verification after each story.
 
 ```bash
-./scripts/ralph/ralph.sh                          # Default: 10 iterations with amp
-./scripts/ralph/ralph.sh --tool claude             # Use Claude Code
+./scripts/ralph/ralph.sh                          # Default: 10 iterations with Claude Code
+./scripts/ralph/ralph.sh --tool claude            # Use Claude Code explicitly
+./scripts/ralph/ralph.sh --tool codex             # Use Codex CLI
 ./scripts/ralph/ralph.sh --tool claude --model opus 20  # Specify model + iterations
 ```
 
 Typical workflow: `/prd` → `/ralph` → `./scripts/ralph/ralph.sh`
 
+Prerequisites: `jq` plus the CLI for whichever runner you use (`claude` by default, or `codex` for `--tool codex`).
+
 ## Agent Orchestration
 
 See @docs/agent-orchestration.md for detailed workflow patterns on how to chain agents effectively.
@@ -95,6 +102,17 @@ export CCSETUP_WORKFLOW=1
 
 When unset, the hook is inactive and Claude uses its default behavior. Install the hook with `npx ccsetup --install-hooks`.
 
+## Codex Review Hook (Optional)
+
+An optional hook that suggests running `/codex-review` when a plan file is modified or code changes are detected. Triggers on the `Stop` event.
+
+To activate:
+```bash
+export CCSETUP_CODEX_REVIEW=1
+```
+
+When unset, the hook is inactive and produces no output.
+
 ## Tickets
 
 See @tickets/README.md for ticket format and management approach
@@ -118,3 +136,87 @@ See @plans/README.md for planning documents and architectural decisions
 ## Additional Notes
 
 [Any other important information for Claude to know about this project]
+
+---
+
+# 🔒 CRITICAL SECURITY - OSV-Scanner Requirement
+
+> **MANDATORY SECOPS POLICY**: All dependency installations MUST be scanned with `osv-scanner` BEFORE installation. **NEVER install packages without scanning first. No exceptions.**
+
+### Security Workflow - ALWAYS Follow This Order
+
+**BEFORE installing ANY dependencies:**
+
+1. **Query the OSV API to check the package before installing:**
+
+   ```bash
+   curl -s -X POST "https://api.osv.dev/v1/query" \
+     -H "Content-Type: application/json" \
+     -d '{"package": {"name": "PACKAGE_NAME", "ecosystem": "ECOSYSTEM"}, "version": "VERSION"}'
+   ```
+
+   | Package Manager | Ecosystem |
+   |---|---|
+   | pip | `PyPI` |
+   | npm/yarn/pnpm | `npm` |
+   | cargo | `crates.io` |
+   | go get | `Go` |
+   | gem | `RubyGems` |
+   | composer | `Packagist` |
+   | nuget | `NuGet` |
+   | maven | `Maven` |
+
+   - Empty `{}` = no known vulnerabilities → proceed
+   - Response contains `vulns` = **STOP**. Report to user, suggest safe version.
+
+2. **Prepare the lockfile for scanning:**
+
+   ```bash
+   osv-scanner scan -r .
+
+   # Or specific lockfile:
+   osv-scanner scan -L requirements.txt
+   osv-scanner scan -L package-lock.json
+   osv-scanner scan -L Cargo.lock
+   osv-scanner scan -L go.sum
+   ```
+
+3. **Review the scan results:**
+
+   - ❌ **If vulnerabilities are found:** STOP - Do NOT install. Report findings to the user and discuss mitigation options.
+   - ✅ **If scan is clean:** Proceed with installation.
+
+4. **Only after clean scan, install dependencies.**
+
+5. **After installation, rescan the entire project:**
+
+   ```bash
+   osv-scanner scan -r .
+   ```
+
+### Critical Rules
+
+1. **NEVER bypass osv-scanner** - This is a security requirement, not a suggestion
+2. **NEVER install packages without scanning first** - No exceptions
+3. **NEVER ignore osv-scanner warnings** - Always report vulnerabilities to the user
+4. **ALWAYS rescan after installation** - Verify the installed state is secure
+
+### Reporting Format
+
+When vulnerabilities are found, present them clearly and block installation:
+
+```
+⚠️ Found 2 vulnerabilities — installation blocked pending review:
+
+CRITICAL: lodash@4.17.20
+  - GHSA-35jh-r3h4-6jhm: Prototype Pollution
+  - Fix: upgrade to 4.17.21
+
+HIGH: axios@0.21.1
+  - CVE-2021-3749: SSRF
+  - Fix: upgrade to 0.21.2
+
+Upgrade affected packages?
+```
+
+Use `/secops` for the full workflow including lockfile generation and vulnerability ignoring.

package/template/docs/codex-setup.md

@@ -0,0 +1,32 @@
+# Codex Setup
+
+## Overview
+
+This project can be used with Codex CLI as well as Claude Code.
+
+The Codex-facing project instructions live in `AGENTS.md`.
+
+## Project-Local Skills
+
+Project-local Codex skills are stored in:
+
+```text
+.codex/skills/
+```
+
+The project-local skill set mirrors the Claude template:
+
+- `prd`
+- `ralph`
+- `codex-review`
+
+Keep these files in the project so Codex has project-specific workflow context alongside `AGENTS.md`.
+
+## Suggested Workflow
+
+1. Read `AGENTS.md`
+2. Review `docs/ROADMAP.md`
+3. Check relevant tickets and plans
+4. Implement the change
+5. Run the quality checks
+6. Use `scripts/codex-review/codex-review.sh` for review when useful

package/template/hooks/codex-review/index.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const { execSync } = require('child_process');
+
+// Environment variable toggle — exit early if not enabled
+// Enable with: export CCSETUP_CODEX_REVIEW=1
+const enabled = process.env.CCSETUP_CODEX_REVIEW;
+if (!enabled || (enabled !== '1' && enabled.toLowerCase() !== 'true')) {
+  console.log('{}');
+  process.exit(0);
+}
+
+const PLAN_DIRS = ['plans'];
+const PLAN_PATTERN = /plan.*\.md$/i;
+const RECENCY_THRESHOLD_MS = 60 * 1000;
+
+function findRecentlyModifiedPlans() {
+  const now = Date.now();
+  const recentPlans = [];
+
+  for (const dir of PLAN_DIRS) {
+    const fullDir = path.join(process.cwd(), dir);
+    if (!fs.existsSync(fullDir)) continue;
+
+    try {
+      const files = fs.readdirSync(fullDir);
+      for (const file of files) {
+        if (!file.endsWith('.md')) continue;
+        const filePath = path.join(fullDir, file);
+        const stats = fs.statSync(filePath);
+        if (now - stats.mtimeMs < RECENCY_THRESHOLD_MS) {
+          recentPlans.push(filePath);
+        }
+      }
+    } catch (err) {
+      // Skip directories we can't read
+    }
+  }
+
+  // Also check for *plan*.md files in the project root
+  try {
+    const rootFiles = fs.readdirSync(process.cwd());
+    for (const file of rootFiles) {
+      if (PLAN_PATTERN.test(file)) {
+        const filePath = path.join(process.cwd(), file);
+        const stats = fs.statSync(filePath);
+        if (stats.isFile() && now - stats.mtimeMs < RECENCY_THRESHOLD_MS) {
+          recentPlans.push(filePath);
+        }
+      }
+    }
+  } catch (err) {
+    // Skip if we can't read root
+  }
+
+  return recentPlans;
+}
+
+function hasGitChanges() {
+  try {
+    execSync('git diff HEAD --quiet', { stdio: 'pipe' });
+    return false;
+  } catch (err) {
+    // Exit code 1 = diff found changes; other codes = command failed (e.g., no HEAD, not a repo)
+    if (err.status === 1) return true;
+    return false;
+  }
+}
+
+// Main — reads from stdin as Claude Code provides
+let inputData = '';
+
+process.stdin.on('data', (chunk) => {
+  inputData += chunk;
+});
+
+process.stdin.on('end', () => {
+  try {
+    const recentPlans = findRecentlyModifiedPlans();
+    const gitChanges = hasGitChanges();
+    let output = {};
+
+    if (recentPlans.length > 0 && gitChanges) {
+      const planNames = recentPlans.map(p => path.basename(p)).join(', ');
+      output = {
+        message: `Plan updated with code changes. Run /codex-review to validate implementation. (${planNames})`
+      };
+    } else if (recentPlans.length > 0) {
+      const planNames = recentPlans.map(p => path.basename(p)).join(', ');
+      output = {
+        message: `Plan created. Run /codex-review for a second opinion from Codex CLI. (${planNames})`
+      };
+    } else if (gitChanges) {
+      output = {
+        message: `Code changes detected. Run /codex-review for a code review from Codex CLI.`
+      };
+    }
+
+    console.log(JSON.stringify(output));
+  } catch (error) {
+    console.log('{}');
+  }
+});

package/template/scripts/codex-review/codex-review.sh

@@ -0,0 +1,266 @@
+#!/bin/bash
+# codex-review.sh — Review plans, implementations, or code changes via Codex CLI
+# Usage: codex-review.sh [plan-file-or--] [--model <model>]
+#   No arguments: reviews git changes (code review)
+#   With plan file: reviews plan, or plan+implementation if git changes exist
+#
+# Exit codes:
+#   0 = success
+#   1 = codex CLI not installed / nothing to review
+#   2 = auth/API error
+#   3 = timeout
+
+set -euo pipefail
+
+PLAN_FILE=""
+PLAN_CONTENT=""
+DIFF_CONTENT=""
+MODEL="${CODEX_REVIEW_MODEL:-}"
+TIMEOUT=120
+MAX_DIFF_CHARS=50000
+
+if command -v timeout &>/dev/null; then
+  TIMEOUT_CMD="timeout"
+elif command -v gtimeout &>/dev/null; then
+  TIMEOUT_CMD="gtimeout"
+else
+  TIMEOUT_CMD=""
+fi
+
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --model)
+      MODEL="$2"
+      shift 2
+      ;;
+    --model=*)
+      MODEL="${1#*=}"
+      shift
+      ;;
+    -)
+      PLAN_FILE="-"
+      shift
+      ;;
+    *)
+      if [[ -z "$PLAN_FILE" ]]; then
+        PLAN_FILE="$1"
+      fi
+      shift
+      ;;
+  esac
+done
+
+# Check prerequisites
+if ! command -v codex &>/dev/null; then
+  echo "Error: codex CLI is not installed. Install it with: npm install -g @openai/codex" >&2
+  exit 1
+fi
+
+# Read plan content (optional — only when a plan file is provided)
+if [[ "$PLAN_FILE" == "-" ]]; then
+  PLAN_CONTENT=$(cat)
+elif [[ -n "$PLAN_FILE" && -f "$PLAN_FILE" ]]; then
+  PLAN_CONTENT=$(cat "$PLAN_FILE")
+elif [[ -n "$PLAN_FILE" ]]; then
+  echo "Error: Plan file not found: $PLAN_FILE" >&2
+  exit 1
+fi
+
+# Gather git diff (silently skips if git unavailable or not in a repo)
+gather_git_diff() {
+  if ! command -v git &>/dev/null; then return; fi
+  if ! git rev-parse --is-inside-work-tree &>/dev/null 2>&1; then return; fi
+
+  DIFF_CONTENT=$(git diff HEAD 2>/dev/null || true)
+
+  if [[ -z "$DIFF_CONTENT" ]]; then
+    DIFF_CONTENT=$(git diff HEAD~1..HEAD 2>/dev/null || true)
+  fi
+
+  # Fallback for initial commit (no HEAD yet) or staged-only changes
+  if [[ -z "$DIFF_CONTENT" ]]; then
+    DIFF_CONTENT=$(git diff --cached 2>/dev/null || true)
+  fi
+
+  if [[ -n "$DIFF_CONTENT" && ${#DIFF_CONTENT} -gt $MAX_DIFF_CHARS ]]; then
+    DIFF_CONTENT="${DIFF_CONTENT:0:$MAX_DIFF_CHARS}
+
+[... diff truncated at ${MAX_DIFF_CHARS} characters ...]"
+  fi
+}
+
+gather_git_diff
+
+# Must have at least a plan or git changes to review
+if [[ -z "$PLAN_CONTENT" && -z "$DIFF_CONTENT" ]]; then
+  echo "Error: No plan file or git changes found. Nothing to review." >&2
+  echo "Usage: codex-review.sh [plan-file-or--] [--model <model>]" >&2
+  exit 1
+fi
+
+CMD_ARGS=()
+if [[ -n "$MODEL" ]]; then
+  CMD_ARGS+=(--model "$MODEL")
+fi
+
+# Build prompt based on available inputs
+if [[ -n "$PLAN_CONTENT" && -n "$DIFF_CONTENT" ]]; then
+  # Implementation review: validate code changes against the plan
+  REVIEW_PROMPT="You are a senior architect reviewing an implementation against its plan. Validate that the code changes correctly fulfill the plan requirements.
+
+## Plan
+
+$PLAN_CONTENT
+
+---
+
+## Implementation (git diff)
+
+$DIFF_CONTENT
+
+---
+
+Provide a structured review covering:
+
+## Plan Compliance
+- Which plan requirements are correctly implemented?
+- Which plan requirements are missing or incomplete?
+- Any divergence from the planned approach?
+
+## Acceptance Criteria
+- For each acceptance criterion in the plan, is it met by the implementation?
+- List any unmet criteria explicitly
+
+## Code Quality
+- Are there bugs or logic errors in the implementation?
+- Security concerns in the changed code?
+- Performance issues?
+
+## Suggestions
+- Specific issues to fix before merging
+- Missing tests or validation
+- Improvements to better match the plan
+
+Be direct and specific. Reference exact file paths and line ranges from the diff."
+
+elif [[ -n "$PLAN_CONTENT" ]]; then
+  # Plan review: architectural review of the plan itself
+  REVIEW_PROMPT="You are a senior architect reviewing this plan. Provide a structured review covering:
+
+## Architecture Review
+- Are the technical choices sound?
+- Are there simpler alternatives?
+- Any missing dependencies or integration concerns?
+
+## Risk Assessment
+- What could go wrong?
+- What edge cases are unhandled?
+- Any security or performance concerns?
+
+## Suggestions
+- Specific improvements with rationale
+- Missing acceptance criteria
+- Implementation order concerns
+
+Be direct and specific. Reference exact sections of the plan.
+
+---
+
+Plan to review:
+
+$PLAN_CONTENT"
+
+else
+  # Code review: standalone review of git changes
+  REVIEW_PROMPT="You are a senior engineer performing a code review. Review the following code changes for quality, correctness, and best practices.
+
+## Code Changes (git diff)
+
+$DIFF_CONTENT
+
+---
+
+Provide a structured review covering:
+
+## Bugs and Correctness
+- Logic errors or incorrect behavior
+- Missing null/error handling
+- Off-by-one errors or boundary conditions
+
+## Security
+- Injection vulnerabilities
+- Exposed secrets or credentials
+- Missing input validation
+
+## Performance
+- Unnecessary computations or allocations
+- Inefficient patterns
+- Missing caching opportunities
+
+## Code Quality
+- Naming and readability
+- Adherence to existing code conventions
+- Dead code or unnecessary complexity
+
+## Suggestions
+- Specific improvements with rationale
+- Missing tests
+- Documentation gaps
+
+Be direct and specific. Reference exact file paths and line ranges from the diff."
+fi
+
+# Run codex exec with timeout (if available)
+# Temporarily disable exit-on-error to capture the actual exit code before
+# checking it. Using "if ! OUTPUT=$(cmd)" sets $? to 0 inside the then-block
+# (the negated result), making timeout detection (exit 124) impossible.
+set +e
+if [[ -n "$TIMEOUT_CMD" ]]; then
+  OUTPUT=$($TIMEOUT_CMD "${TIMEOUT}s" codex exec ${CMD_ARGS[@]+"${CMD_ARGS[@]}"} "$REVIEW_PROMPT" 2>&1)
+else
+  OUTPUT=$(codex exec ${CMD_ARGS[@]+"${CMD_ARGS[@]}"} "$REVIEW_PROMPT" 2>&1)
+fi
+EXIT_CODE=$?
+set -e
+
+if [[ $EXIT_CODE -ne 0 ]]; then
+  if [[ $EXIT_CODE -eq 124 ]]; then
+    echo "Error: Codex review timed out after ${TIMEOUT}s. Try a shorter plan or increase TIMEOUT." >&2
+    exit 3
+  fi
+
+  if echo "$OUTPUT" | grep -qi "login\|log in\|sign in\|authenticate first"; then
+    echo "Error: Codex CLI requires login. Run 'codex login' first." >&2
+    exit 2
+  fi
+
+  if echo "$OUTPUT" | grep -qi "auth\|unauthorized\|api.key\|invalid.*key\|forbidden\|permission denied"; then
+    echo "Error: Codex authentication failed. Check your OpenAI API key." >&2
+    echo "$OUTPUT" >&2
+    exit 2
+  fi
+
+  if echo "$OUTPUT" | grep -qi "rate.limit\|too many requests\|429\|quota\|exceeded.*limit"; then
+    echo "Error: Rate limited by OpenAI API. Wait a moment and try again." >&2
+    echo "$OUTPUT" >&2
+    exit 2
+  fi
+
+  if echo "$OUTPUT" | grep -qi "network\|connect\|ECONNREFUSED\|ENOTFOUND\|DNS\|resolve\|unreachable\|timed out"; then
+    echo "Error: Network error. Check your internet connection." >&2
+    echo "$OUTPUT" >&2
+    exit 2
+  fi
+
+  if echo "$OUTPUT" | grep -qi "model.*not found\|does not exist\|invalid.*model\|unknown model"; then
+    echo "Error: Invalid model '${MODEL:-default}'. Check available models with 'codex --help'." >&2
+    echo "$OUTPUT" >&2
+    exit 2
+  fi
+
+  echo "Error: Codex review failed (exit code $EXIT_CODE)" >&2
+  echo "$OUTPUT" >&2
+  exit 2
+fi
+
+echo "$OUTPUT"

package/template/scripts/ralph/CODEX.md

@@ -0,0 +1,76 @@
+# Ralph Agent Instructions for Codex
+
+You are an autonomous coding agent working on a software project through the Codex CLI.
+
+## Your Task
+
+1. Read the PRD at `prd.json` in this directory.
+2. Read the progress log at `progress.txt` and check the `## Codebase Patterns` section first.
+3. Check out or create the branch named in `prd.json` under `branchName`.
+4. Pick the highest-priority user story where `passes` is `false`.
+5. Read the story's `notes` for file hints and context.
+6. Implement exactly that one story.
+7. Run every exact quality check command from `prd.json` → `qualityChecks`.
+8. Independently verify the implementation against the acceptance criteria.
+9. If verification passes, commit all changes with `feat: [Story ID] - [Story Title]`.
+10. If verification fails, fix the issues, rerun quality checks, and verify again.
+11. Update `prd.json` to set `passes: true` and replace `notes` with what was actually done.
+12. Add reusable learnings to nearby `AGENTS.md` files when they would help future work.
+13. Append a progress entry to `progress.txt`.
+
+## Quality Checks
+
+- Use the exact commands in `qualityChecks`. Do not guess or substitute.
+- If `qualityChecks` is missing, detect commands from project config files before proceeding.
+- All quality checks must pass before verification.
+
+## Verification
+
+Verification must be independent from implementation. Review your changes against:
+
+- every acceptance criterion in the selected story
+- the exact files changed in the working tree
+- the results of all quality checks
+
+Report verification in your reasoning and in `progress.txt` as either:
+
+- `APPROVED`
+- `CHANGES_REQUESTED`
+
+If changes are requested, fix them and repeat. Stop after 3 review cycles for one story. If it still fails, log the issues in `progress.txt` and leave `passes` as `false`.
+
+For UI stories that include "Verify in browser using dev-browser skill", perform that verification if browser tools are available. Otherwise note that manual browser verification is still needed.
+
+## Progress Entry Format
+
+Append to `progress.txt`:
+
+```text
+## [Date/Time] - [Story ID]
+- What was implemented
+- Files changed
+- Review result: [APPROVED / CHANGES_REQUESTED → fixed → APPROVED]
+- Review cycles: [1-3]
+- Learnings for future iterations:
+  - Patterns discovered
+  - Gotchas encountered
+  - Useful context
+  - Reviewer catches
+---
+```
+
+If you discover a reusable rule for future iterations, add it to the `## Codebase Patterns` section at the top of `progress.txt`.
+
+## Stop Condition
+
+After completing one story, check whether all stories in `prd.json` have `passes: true`.
+
+- If all stories pass, output exactly `<promise>COMPLETE</promise>`.
+- Otherwise end normally so the next iteration can continue.
+
+## Important
+
+- Work on one story per iteration.
+- Commit only after verification approves the changes.
+- Keep the repository green with the exact quality check commands.
+- Read both `progress.txt` patterns and story `notes` before making changes.