ccsetup 1.2.0 → 1.2.1

package/README.md

@@ -3,7 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/ccsetup.svg)](https://www.npmjs.com/package/ccsetup)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-One-command setup for Claude Code projects. Creates a ready-to-use project structure with 8 core agents, orchestration workflows, ticket system, and planning tools.
+One-command setup for Claude Code and Codex projects. Creates a ready-to-use project structure with planning tools, review workflows, and optional AI-specific project setup.
 
 ## Quick Start
 
@@ -22,17 +22,21 @@ npx ccsetup .
 
 ```
 my-project/
-├── CLAUDE.md              # Project instructions for Claude
+├── CLAUDE.md              # Project instructions for Claude (Claude/Both)
+├── AGENTS.md              # Project instructions for Codex (Codex/Both)
 ├── CONTRIBUTING.md        # Contribution guidelines
 ├── GEMINI.md              # Gemini setup (optional)
 ├── .claude/
 │   ├── agents/            # 8 core agents
-│   ├── skills/            # /prd and /ralph slash commands
-│   └── settings.json
+│   ├── skills/            # /prd, /ralph, /codex-review, and /secops skills
+│   └── settings.json      # Claude permissions and optional hook wiring
+├── .codex/
+│   └── skills/            # Project-local Codex skills: prd, ralph, codex-review
 ├── agents/
 │   └── README.md          # Agent documentation
 ├── scripts/
-│   └── ralph/             # Autonomous agent loop
+│   ├── ralph/             # Autonomous agent loop for Claude Code or Codex
+│   └── codex-review/      # Codex CLI review script
 ├── docs/
 │   ├── ROADMAP.md         # Development roadmap
 │   └── agent-orchestration.md
@@ -48,6 +52,10 @@ backend, blockchain, checker, coder, frontend, planner, researcher, shadcn
 
 - **/prd** — Scans your codebase (tech stack, quality gates, architecture), then generates a structured PRD with real file paths and auto-detected quality criteria
 - **/ralph** — Converts a PRD into `prd.json` format for autonomous execution, with exact quality check commands and file hints per story
+- **/codex-review** — Reviews plans, validates implementations against plans, or reviews code changes via Codex CLI. Auto-detects mode from context, up to 3 iterative rounds
+- **/secops** — Claude-only security skill that blocks dependency installs until `osv-scanner` checks the package or lockfile for known vulnerabilities
+
+Claude projects also ship with `osv-scanner` Bash permissions preconfigured in `.claude/settings.json` so the `/secops` workflow can run without extra permission prompts.
 
 ## Key Options
 
@@ -55,25 +63,13 @@ backend, blockchain, checker, coder, frontend, planner, researcher, shadcn
 npx ccsetup my-project --agents        # Interactive agent selection
 npx ccsetup my-project --all-agents    # Include all agents
 npx ccsetup my-project --no-agents     # Skip agent selection entirely
-npx ccsetup . --scan-context           # Scan existing project for context
-npx ccsetup --scan-only                # Only scan and update CLAUDE.md
 npx ccsetup my-project --dry-run       # Preview without creating files
 npx ccsetup my-project --force         # Skip prompts, overwrite existing
 npx ccsetup my-project --browse        # Enhanced template browsing UI
 npx ccsetup --install-hooks            # Install workflow selection hooks (advanced)
 ```
 
-### Repository Scanning
-
-Scan existing projects to auto-generate CLAUDE.md context:
-
-```bash
-ccsetup scan                           # Scan current directory
-ccsetup scan --update                  # Update existing CLAUDE.md
-ccsetup scan --update --merge-strategy replace       # Replace CLAUDE.md entirely
-```
-
-Detects languages, frameworks, project structure, and commands from package.json/Makefile/Docker Compose.
+During setup, `ccsetup` asks whether to generate a `Claude`, `Codex`, or `Both` project environment.
 
 ## Agent Workflows
 
@@ -104,6 +100,67 @@ export CCSETUP_WORKFLOW=1
 
 When active, the hook suggests workflows like "Feature Development: Researcher → Planner → Coder → Checker" and asks if you'd like to follow it. When the env var is unset, the hook exits silently and Claude uses its default behavior.
 
+## Codex Review — Plan, Implementation, and Code Review
+
+Get a second opinion from OpenAI's Codex CLI. The script auto-detects what to review:
+
+| Context | Review Mode |
+|---------|-------------|
+| Plan file, no code changes | **Plan review** — architectural soundness |
+| Plan file + git changes | **Implementation review** — validates code against the plan |
+| No plan file, git changes | **Code review** — bugs, security, quality |
+
+### Usage
+
+```
+/codex-review                              # Auto-detect from context
+/codex-review plans/my-feature-plan.md     # Review a specific plan
+```
+
+### What happens
+
+1. Detects available context (plan file and/or git changes)
+2. Sends to Codex CLI with a mode-appropriate review prompt
+3. Presents structured feedback (architecture, compliance, risks, suggestions)
+4. Asks if you want to apply fixes and re-review
+5. Repeats for up to 3 iterations
+
+### Direct script usage
+
+```bash
+# Plan review (no git changes)
+./scripts/codex-review/codex-review.sh plans/my-plan.md
+
+# Implementation review (plan + git changes auto-detected)
+./scripts/codex-review/codex-review.sh plans/my-plan.md
+
+# Code review (no plan, just git changes)
+./scripts/codex-review/codex-review.sh
+
+# Override the model
+./scripts/codex-review/codex-review.sh plans/my-plan.md --model o3-mini
+
+# From stdin
+cat plans/my-plan.md | ./scripts/codex-review/codex-review.sh -
+```
+
+### Prerequisites
+
+1. **Codex CLI installed:** `npm install -g @openai/codex`
+2. **Authenticated:** `codex login` or set `OPENAI_API_KEY`
+
+### Codex Review Hook (Optional)
+
+An optional hook that suggests running `/codex-review` when plan files are 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.
+
 ## Ralph — Autonomous Agent Loop
 
 Ralph is an autonomous coding agent that implements user stories from a PRD one at a time, with built-in subagent verification.
@@ -115,17 +172,20 @@ Ralph is an autonomous coding agent that implements user stories from a PRD one
 3. **Run Ralph** — Launch the autonomous loop:
 
 ```bash
-# Default: 10 iterations using amp
+# Default: 10 iterations using Claude Code
 ./scripts/ralph/ralph.sh
 
-# Use Claude Code instead of amp
+# Use Claude Code explicitly
 ./scripts/ralph/ralph.sh --tool claude
 
+# Use Codex CLI instead of Claude Code
+./scripts/ralph/ralph.sh --tool codex
+
 # Specify model and max iterations
 ./scripts/ralph/ralph.sh --tool claude --model opus 20
 
-# Quick run with sonnet
-./scripts/ralph/ralph.sh --tool claude --model sonnet 5
+# Quick Codex run
+./scripts/ralph/ralph.sh --tool codex --model gpt-5 5
 ```
 
 ### What happens each iteration
@@ -143,18 +203,25 @@ Ralph is an autonomous coding agent that implements user stories from a PRD one
 
 | Flag | Default | Description |
 |------|---------|-------------|
-| `--tool amp\|claude` | `amp` | Which AI tool to use |
-| `--model opus\|sonnet\|haiku` | (default) | Model selection (Claude only) |
+| `--tool claude\|codex` | `claude` | Which AI tool to use |
+| `--model <model>` | (default) | Model selection for the chosen tool |
 | `[number]` | `10` | Max iterations |
 
 ### Archiving
 
 Ralph auto-archives previous runs when the branch changes. Archives are saved to `scripts/ralph/archive/YYYY-MM-DD-feature-name/`.
 
+### Prerequisites
+
+1. **`jq` installed** for PRD parsing and branch tracking
+2. **Claude Code CLI** for the default runner
+3. **Codex CLI** if you want `--tool codex`: `npm install -g @openai/codex`
+
 ## Documentation
 
 - [Agent Orchestration](docs/agent-orchestration.md)
 - [Available Agents](template/agents/README.md)
+- [Codex Setup](docs/codex-setup.md)
 - [Ticket System](docs/ticket-system.md)
 
 ## Credits
@@ -163,6 +230,8 @@ Born from discussions in TechOverflow with [vichannnnn](https://github.com/vicha
 
 Agent collection from [wshobson/agents](https://github.com/wshobson/agents).
 
+Security workflow and `/secops` skill contribution by [Ciaran Hughes](https://github.com/Ciaran-Hughes).
+
 ## License
 
 MIT