ccsetup 1.1.1 → 1.2.1

package/README.md

@@ -1,434 +1,236 @@
 # ccsetup
 
 [![npm version](https://img.shields.io/npm/v/ccsetup.svg)](https://www.npmjs.com/package/ccsetup)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/marcia-ong/ccsetup/pulls)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![npm downloads](https://img.shields.io/npm/dm/ccsetup.svg)](https://www.npmjs.com/package/ccsetup)
 
-Quick setup for Claude Code projects with built-in 50+ agents, ticket system, planning tools and agent orchestration workflow.
+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.
 
-## Installation
+## Quick Start
 
 ```bash
-# Create a new project
+# Interactive mode
+npx ccsetup
+
+# Create new project
 npx ccsetup my-project
 
 # Setup in current directory
 npx ccsetup .
-
-# Install globally (optional)
-npm install -g ccsetup
-ccsetup my-project
 ```
 
-## Command Line Options
+## What You Get
 
-```bash
-ccsetup [project-name] [options]
-
-Options:
-  --force, -f     Skip all prompts and overwrite existing files
-  --dry-run, -d   Show what would be done without making changes
-  --agents        Interactive agent selection mode
-  --all-agents    Include all agents without prompting
-  --no-agents     Skip agent selection entirely
-  --browse-agents Copy all agents to /agents folder for browsing
-  --help, -h      Show help message
-
-Examples:
-  ccsetup                      # Create in current directory
-  ccsetup my-project           # Create in new directory
-  ccsetup . --force            # Overwrite files in current directory
-  ccsetup my-app --dry-run     # Preview changes without creating files
-  ccsetup --agents             # Interactive agent selection only
-  ccsetup my-app --all-agents  # Include all agents automatically
-  ccsetup --browse-agents      # Copy all agents for manual selection
+```
+my-project/
+├── 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, /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 for Claude Code or Codex
+│   └── codex-review/      # Codex CLI review script
+├── docs/
+│   ├── ROADMAP.md         # Development roadmap
+│   └── agent-orchestration.md
+├── tickets/               # Task tracking
+└── plans/                 # Planning documents
 ```
 
-## What's Included
-
-The boilerplate template creates:
-
-- **CLAUDE.md** - Project instructions for Claude
-- **GEMINI.md** - (Optional) Waterfall Architect prompt for comprehensive task planning - optimized for Gemini's larger context window
-- **agents/** - Specialized AI agents (planner, coder, checker, etc.)
-- **tickets/** - Task tracking system
-- **plans/** - Project planning documents
-- **docs/** - Documentation with ROADMAP.md and agent-orchestration.md
-- **.claude/** - Claude Code specific directory structure (created automatically)
-
-## Key Features
-
-- 🎯 **Interactive Agent Selection** - Choose which agents to include during setup
-- 📚 **Browse Mode** - Copy all 50+ agents to explore and manually select later
-- 🔄 **Agent Orchestration Workflows** - Pre-defined workflows that automatically coordinate multiple agents for complex tasks
-- 🔒 **Smart Conflict Resolution** - Handle existing files with skip/rename/overwrite options
-- 📁 **.claude Directory Support** - Automatic creation of Claude Code directory structure
-- 🏃 **Dry Run Mode** - Preview changes before applying them
-- ⚡ **Force Mode** - Skip all prompts for automated workflows
-- 🎨 **Standalone Agent Preview** - Explore available agents without setup
-- 🎭 **Systematic Task Execution** - Agents work in sequence, building on each other's outputs
-
-## Project Structure
-
-- **templates/** - The boilerplate templates that will be copied to user's project
-- **bin/** - CLI executable for ccsetup
-- **agents/**, **docs/**, **plans/**, **tickets/** - Working files for ccsetup development (not part of the template)
-
-## Usage
-
-1. Create a new project:
-
-   ```bash
-   npx ccsetup my-awesome-project
-   cd my-awesome-project
-   ```
-
-2. Edit `CLAUDE.md` with your project-specific instructions
-
-3. Update `docs/ROADMAP.md` with your project goals
-
-4. Start creating tickets in `tickets/` directory
-
-## Claude Code Integration
-
-ccsetup seamlessly integrates with Claude Code:
-
-- **Automatic Detection** - Checks if Claude Code is initialized in your project
-- **.claude Directory** - Creates Claude Code directory structure automatically
-- **Agent Installation** - Copies agents to `.claude/agents/` for native Claude Code support
-- **Smart Initialization** - Offers to create `.claude` directory if Claude Code isn't detected
-
-When running in the current directory (`npx ccsetup .`), it will check for Claude Code and provide instructions if not found. For new projects, ccsetup will remind you to initialize Claude Code after setup.
-
-## Using Agents
-
-The boilerplate includes 50+ specialized agents covering all aspects of development:
-
-### Core Development Agents
-
-- **planner.md** - Strategic planning and task breakdown
-- **coder.md** - Implementation and development
-- **checker.md** - Testing and quality assurance
-- **researcher.md** - Research and information gathering
-
-### Language Specialists
-
-- **python-pro.md**, **golang-pro.md**, **rust-pro.md**, **javascript-pro.md**, **c-pro.md**, **cpp-pro.md**, **sql-pro.md**
-
-### Infrastructure & Operations
-
-- **devops-troubleshooter.md**, **cloud-architect.md**, **terraform-specialist.md**, **database-admin.md**, **network-engineer.md**
-
-### Quality & Security
-
-- **code-reviewer.md**, **security-auditor.md**, **test-automator.md**, **performance-engineer.md**
-
-### And Many More!
+### Core Agents
 
-Over 50 specialized agents for frontend, backend, blockchain, ML/AI, business analysis, and more!
+backend, blockchain, checker, coder, frontend, planner, researcher, shadcn
 
-📖 **[View all agents with detailed descriptions →](https://github.com/MrMarciaOng/ccsetup/blob/main/template/agents/README.md)**
+### Skills (Slash Commands)
 
-### Interactive Agent Selection
+- **/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
 
-During setup, ccsetup will prompt you to either:
+Claude projects also ship with `osv-scanner` Bash permissions preconfigured in `.claude/settings.json` so the `/secops` workflow can run without extra permission prompts.
 
-1. **Browse Mode** - Get all 50+ agents to explore later
-2. **Select Specific Agents** - Choose from curated list
+## Key Options
 
 ```bash
-🤖 How would you like to set up agents for your Claude Code project?
-
-Use arrow keys to navigate, Enter to select
-
-> Browse Mode - Copy all 50+ agents to /agents folder (explore later)
-  Select Agents - Choose specific agents to include now
-  Skip - Don't include any agents
-
-# If you choose "Select Agents":
-🤖 Select agents to include in your Claude Code project
-
-Use arrow keys to navigate, space to select/deselect, 'a' to toggle all
-
-Choose your agents:
-◯ backend - Backend development specialist for API design and server optimization
-◯ blockchain - Web3 and smart contract development expert
-◯ checker - Quality assurance and code review specialist
-◯ coder - Expert software developer for implementation
-◯ frontend - Frontend development specialist for UI/UX
-◯ planner - Strategic planning specialist for complex problems
-◯ researcher - Research specialist for documentation and code analysis
-◯ shadcn - shadcn/ui component library expert
+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 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)
 ```
 
-You can also use flags to control agent selection:
+During setup, `ccsetup` asks whether to generate a `Claude`, `Codex`, or `Both` project environment.
 
-- `--all-agents` - Include all available agents
-- `--no-agents` - Skip agent selection entirely
-- `--agents` - Preview available agents without creating a project
+## Agent Workflows
 
-Example:
+Pre-configured multi-agent workflows:
 
-```bash
-# Include all agents without prompting
-npx ccsetup my-project --all-agents
+- **Feature Development**: Researcher → Planner → Coder → Checker
+- **Bug Fix**: Researcher → Coder → Checker
+- **API Development**: Planner → Backend → Frontend → Checker
+- **UI Components**: Frontend → Shadcn → Checker
 
-# Create project without any agents
-npx ccsetup my-project --no-agents
+See [docs/agent-orchestration.md](docs/agent-orchestration.md) for details.
 
-# Preview available agents only
-npx ccsetup --agents
-```
+### Workflow Selector Hook (Optional)
 
-### Browse Mode - New Feature! 📚
+An optional hook that analyzes your prompts and suggests the best agent workflow for the task. Claude will ask before applying the suggestion.
 
-With 50+ specialized agents available, browse mode lets you explore all agents at your leisure:
+**During setup**, you'll be asked if you want to install it. You can also install it later:
 
 ```bash
-# Copy all agents to /agents folder for browsing
-npx ccsetup my-project --browse-agents
+npx ccsetup --install-hooks
 ```
 
-In browse mode:
-
-- All 50+ agents are copied to your project's `/agents` folder
-- You can read through each agent to understand their capabilities
-- Manually copy the ones you want to `~/.claude/agents` when ready
-- No overwhelming selection process during setup!
-
-Example workflow:
+**To activate**, set the environment variable:
 
 ```bash
-# 1. Create project with browse mode
-npx ccsetup my-project --browse-agents
-
-# 2. Explore agents
-cd my-project/agents
-ls  # See all available agents
-
-# 3. Read agent descriptions
-cat code-reviewer.md
-
-# 4. Copy desired agents to activate them
-cp code-reviewer.md ~/.claude/agents/
-cp python-pro.md ~/.claude/agents/
+export CCSETUP_WORKFLOW=1
 ```
 
-This approach is perfect when you:
-
-- Want to explore all available agents
-- Prefer to choose agents based on your project needs as they arise
-- Don't want to be overwhelmed with 50+ choices during setup
-
-### Conflict Resolution
+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.
 
-When existing files are detected, ccsetup offers smart conflict resolution:
+## Codex Review — Plan, Implementation, and Code Review
 
-```bash
-⚠️  File conflicts detected. You will be asked how to handle each category.
+Get a second opinion from OpenAI's Codex CLI. The script auto-detects what to review:
 
-📄 CLAUDE.md conflicts:
-  - CLAUDE.md
+| 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 |
 
-Conflict resolution options:
-  1) skip      (s) - Keep your existing files
-  2) rename    (r) - Save template files with -ccsetup suffix
-  3) overwrite (o) - Replace with template versions
+### Usage
 
-Your choice for CLAUDE.md [s/r/o]:
 ```
-
-Categories are handled separately:
-
-- **CLAUDE.md** - Project instructions (warns before overwriting)
-- **Agents** - AI agent files
-- **Documentation** - docs/ folder files
-- **Plans** - plans/ folder files
-- **Tickets** - tickets/ folder files
-
-## Agent Orchestration Showcase
-
-The template includes powerful agent orchestration workflows that guide Claude through complex tasks systematically. Here are real-world examples:
-
-### 🚀 Feature Development Example
-
-**Scenario**: Building a user authentication system
-
-```bash
-# In Claude Code, you would say:
-"I need to add user authentication to my app. Use the feature development workflow to guide me through this."
-
-# Claude will automatically orchestrate:
-1. Researcher Agent → Analyzes existing codebase, identifies auth patterns
-2. Planner Agent → Creates detailed implementation plan with JWT, sessions, etc.
-3. Coder Agent → Implements auth endpoints, middleware, and UI components
-4. Checker Agent → Tests security, validates implementation, checks edge cases
+/codex-review                              # Auto-detect from context
+/codex-review plans/my-feature-plan.md     # Review a specific plan
 ```
 
-### 🐛 Bug Fix Example
+### What happens
 
-**Scenario**: Users report login failures after 5 minutes
+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
-# You tell Claude:
-"Users are getting logged out after 5 minutes. Use the bug fix workflow to investigate and fix this."
+# Plan review (no git changes)
+./scripts/codex-review/codex-review.sh plans/my-plan.md
 
-# Claude orchestrates:
-1. Researcher Agent → Investigates session handling, token expiry, logs
-2. Coder Agent → Fixes token refresh logic, updates session timeout
-3. Checker Agent → Verifies fix, tests edge cases, ensures no regressions
-```
+# Implementation review (plan + git changes auto-detected)
+./scripts/codex-review/codex-review.sh plans/my-plan.md
 
-### 🏗️ API Development Example
+# Code review (no plan, just git changes)
+./scripts/codex-review/codex-review.sh
 
-**Scenario**: Building a REST API for a blog platform
+# Override the model
+./scripts/codex-review/codex-review.sh plans/my-plan.md --model o3-mini
 
-```bash
-# You request:
-"Help me build a complete REST API for blog posts with CRUD operations. Follow the API development workflow."
-
-# Claude coordinates:
-1. Planner Agent → Designs RESTful endpoints, database schema, auth strategy
-2. Backend Agent → Implements controllers, models, middleware, validation
-3. Frontend Agent → Creates API client, integration examples (if needed)
-4. Checker Agent → Tests all endpoints, validates OpenAPI spec, security audit
+# From stdin
+cat plans/my-plan.md | ./scripts/codex-review/codex-review.sh -
 ```
 
-### 🎨 UI Component Example
+### Prerequisites
 
-**Scenario**: Creating a responsive dashboard with shadcn/ui
+1. **Codex CLI installed:** `npm install -g @openai/codex`
+2. **Authenticated:** `codex login` or set `OPENAI_API_KEY`
 
-```bash
-# You ask:
-"Create a dashboard with charts and stats cards using shadcn. Use the UI component workflow."
+### Codex Review Hook (Optional)
 
-# Claude executes:
-1. Frontend Agent → Designs component structure, responsive layout
-2. Shadcn Agent → Implements with shadcn/ui components, themes, animations
-3. Checker Agent → Tests responsiveness, accessibility, performance
-```
+An optional hook that suggests running `/codex-review` when plan files are modified or code changes are detected. Triggers on the `Stop` event.
 
-### 🔍 Quality Assurance Example
-
-**Scenario**: Comprehensive review before deployment
+**To activate:**
 
 ```bash
-# You request:
-"Run full QA on the authentication feature we just built."
-
-# Claude performs:
-1. Researcher Agent → Analyzes all changes, identifies test requirements
-2. Checker Agent → Runs security scans, performance tests, accessibility checks
-3. Coder Agent → Fixes any issues found
-4. Checker Agent → Final validation, generates QA report
+export CCSETUP_CODEX_REVIEW=1
 ```
 
-### 💡 How to Use Agent Orchestration
-
-1. **Read the orchestration guide**:
-
-   ```
-   "Read docs/agent-orchestration.md to understand available workflows"
-   ```
-
-2. **Choose your workflow**:
+When unset, the hook is inactive and produces no output.
 
-   - Feature Development: Complex new features
-   - Bug Fix: Investigating and fixing issues
-   - Refactoring: Improving code quality
-   - API Development: Building APIs
-   - UI Components: Frontend development
-   - Blockchain: Web3 features
-   - QA: Quality assurance
+## Ralph — Autonomous Agent Loop
 
-3. **Let Claude guide you**:
+Ralph is an autonomous coding agent that implements user stories from a PRD one at a time, with built-in subagent verification.
 
-   ```
-   "I need to [your task]. Which workflow should we use?"
-   ```
+### Workflow
 
-4. **Follow the flow**:
-   - Claude will automatically use agents in the correct sequence
-   - Each agent builds on the previous one's work
-   - You get systematic, thorough results
+1. **Create a PRD** — Use `/prd` in Claude Code to generate a codebase-aware PRD
+2. **Convert to Ralph format** — Use `/ralph` to generate `scripts/ralph/prd.json` with quality checks and file hints
+3. **Run Ralph** — Launch the autonomous loop:
 
-The orchestration ensures nothing is missed and follows best practices automatically!
-
-## Getting Started with Claude Code
-
-After setting up your project with `ccsetup`:
-
-1. **Open Claude Code** in your project directory:
-
-   ```bash
-   cd my-awesome-project
-   claude
-   ```
-
-2. **Let Claude understand your project** by asking:
+```bash
+# Default: 10 iterations using Claude Code
+./scripts/ralph/ralph.sh
 
-   - "Read the CLAUDE.md file to understand this project"
-   - "Check the roadmap in docs/ROADMAP.md"
-   - "What agents are available in the agents directory?"
-   - "Read the README files in docs, tickets, and plans folders to understand the workflow"
+# Use Claude Code explicitly
+./scripts/ralph/ralph.sh --tool claude
 
-3. **Start working** with Claude:
+# Use Codex CLI instead of Claude Code
+./scripts/ralph/ralph.sh --tool codex
 
-   - Use the planner agent: "Use the planner agent to help me design a user authentication system"
-   - Create tickets: "Create a ticket for implementing user login"
-   - Implement features: "Use the coder agent to implement the login functionality"
-   - Review code: "Use the checker agent to review the code we just wrote"
+# Specify model and max iterations
+./scripts/ralph/ralph.sh --tool claude --model opus 20
 
-4. **Important setup steps**:
+# Quick Codex run
+./scripts/ralph/ralph.sh --tool codex --model gpt-5 5
+```
 
-   - **Update ROADMAP.md**: Define your project's goals, features, and development phases
-   - **Read folder documentation**: Each folder (docs/, tickets/, plans/) has a README explaining its purpose and format
-   - **Customize CLAUDE.md**: Add project-specific instructions, commands, and context
+### What happens each iteration
 
-5. **Workflow tips**:
-   - Always start with planning for complex features
-   - Create tickets to track progress
-   - Use the appropriate agent for each task
-   - Keep CLAUDE.md updated with project-specific instructions
-   - Follow the workflow defined in docs/ROADMAP.md
+1. Reads `prd.json` and picks the next incomplete story
+2. Reads story `notes` for file hints (pre-populated by `/ralph`)
+3. Implements the story
+4. Runs exact quality check commands from `prd.json` (`qualityChecks` field)
+5. Spawns a **checker subagent** to independently verify the implementation against acceptance criteria
+6. If reviewer approves → commits. If not → fixes and re-verifies (up to 3 cycles)
+7. Updates `prd.json` (`passes: true`) and appends to `progress.txt`
+8. Exits when all stories pass, or after max iterations
 
-## Features
+### Options
 
-### Core Features
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--tool claude\|codex` | `claude` | Which AI tool to use |
+| `--model <model>` | (default) | Model selection for the chosen tool |
+| `[number]` | `10` | Max iterations |
 
-- ✅ Pre-configured project structure for Claude Code
-- 🤖 50+ specialized agents from the [wshobson/agents](https://github.com/wshobson/agents) collection - [view all →](https://github.com/MrMarciaOng/ccsetup/blob/main/template/agents/README.md)
-- 🎫 Built-in ticket and planning system
-- 📋 Ready-to-use boilerplate with best practices
-- 📁 Automatic .claude directory integration
+### Archiving
 
-### CLI Features
+Ralph auto-archives previous runs when the branch changes. Archives are saved to `scripts/ralph/archive/YYYY-MM-DD-feature-name/`.
 
-- 🎯 Interactive agent selection with descriptions
-- 🔄 Smart conflict resolution (skip/rename/overwrite)
-- 👀 Dry-run mode to preview changes
-- ⚡ Force mode for CI/CD pipelines
-- 🎨 Standalone agent preview mode
-- 🛡️ Security validations for file operations
+### Prerequisites
 
-### Agent Orchestration
+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`
 
-The template includes `docs/agent-orchestration.md` which defines workflows for:
+## Documentation
 
-- **Feature Development** - Researcher → Planner → Coder → Checker
-- **Bug Fixes** - Researcher → Coder → Checker
-- **Refactoring** - Researcher → Planner → Coder → Checker
-- **API Development** - Planner → Backend → Frontend → Checker
-- **UI Components** - Frontend → Shadcn → Checker
-- **Blockchain** - Planner → Blockchain → Checker
-- **Quality Assurance** - Researcher → Checker → Coder → Checker
+- [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
 
-Born from our discussions in TechOverflow with [vichannnnn](https://github.com/vichannnnn) and [nasdin](https://github.com/nasdin)
+Born from discussions in TechOverflow with [vichannnnn](https://github.com/vichannnnn), [MrMarciaOng](https://github.com/MrMarciaOng), and [nasdin](https://github.com/nasdin).
+
+Agent collection from [wshobson/agents](https://github.com/wshobson/agents).
 
-The 44 specialized agents collection is from [wshobson/agents](https://github.com/wshobson/agents) - an amazing collection of Claude Code subagents for every development need!
+Security workflow and `/secops` skill contribution by [Ciaran Hughes](https://github.com/Ciaran-Hughes).
 
 ## License