ccsetup 1.1.1 → 1.2.1

package/template/agents/README.md

@@ -1,189 +1,33 @@
 # Agents Directory
 
-This directory contains specialized AI agents for Claude Code, designed to enhance development workflows with domain-specific expertise.
+This directory is for documentation only. All active agents live in `.claude/agents/`.
 
-## Credits
+## Available Core Agents
 
-This collection includes:
-- **8 original agents** created for ccsetup
-- **44 specialized agents** from [wshobson/agents](https://github.com/wshobson/agents) - an amazing collection of Claude Code subagents
+These 8 agents are pre-installed in `.claude/agents/`:
 
-## Available Agents (52 total)
+- **backend** - Backend development specialist for API design, database architecture, and server-side optimization
+- **blockchain** - Blockchain and Web3 expert for smart contracts, DeFi protocols, and blockchain architecture
+- **checker** - Quality assurance and code review specialist for testing, security analysis, and validation
+- **coder** - Expert software developer for implementing features, fixing bugs, and optimizing code
+- **frontend** - Frontend development specialist for UI/UX, responsive design, and modern web frameworks
+- **planner** - Strategic planning specialist for breaking down complex problems and creating implementation roadmaps
+- **researcher** - Research specialist for both online sources and local codebases, gathering comprehensive information
+- **shadcn** - shadcn/ui component library expert for building beautiful, accessible React interfaces
 
-### Original ccsetup Agents
-These 8 agents were created specifically for the ccsetup boilerplate:
+## Adding Custom Agents
 
-- **[backend](backend.md)** - Backend development specialist for API design, database architecture, and server-side optimization
-- **[blockchain](blockchain.md)** - Blockchain and Web3 expert for smart contracts, DeFi protocols, and blockchain architecture
-- **[checker](checker.md)** - Quality assurance and code review specialist for testing, security analysis, and validation
-- **[coder](coder.md)** - Expert software developer for implementing features, fixing bugs, and optimizing code
-- **[frontend](frontend.md)** - Frontend development specialist for UI/UX, responsive design, and modern web frameworks
-- **[planner](planner.md)** - Strategic planning specialist for breaking down complex problems and creating implementation roadmaps
-- **[researcher](researcher.md)** - Research specialist for both online sources and local codebases, gathering comprehensive information
-- **[shadcn](shadcn.md)** - shadcn/ui component library expert for building beautiful, accessible React interfaces
+To add a custom agent, create a `.md` file in `.claude/agents/` with this structure:
 
-### wshobson/agents Collection (44 agents)
-
-The following 44 specialized agents are from the excellent [wshobson/agents](https://github.com/wshobson/agents) repository:
-
-#### Development & Architecture
-- **[backend-architect](backend-architect.md)** - Design RESTful APIs, microservice boundaries, and database schemas
-- **[frontend-developer](frontend-developer.md)** - Build React components, implement responsive layouts, and handle client-side state management
-- **[mobile-developer](mobile-developer.md)** - Develop React Native or Flutter apps with native integrations
-- **[graphql-architect](graphql-architect.md)** - Design GraphQL schemas, resolvers, and federation
-- **[architect-review](architect-review.md)** - Reviews code changes for architectural consistency and patterns
-
-#### Language Specialists
-- **[python-pro](python-pro.md)** - Write idiomatic Python code with advanced features and optimizations
-- **[golang-pro](golang-pro.md)** - Write idiomatic Go code with goroutines, channels, and interfaces
-- **[rust-pro](rust-pro.md)** - Write idiomatic Rust with ownership patterns, lifetimes, and trait implementations
-- **[c-pro](c-pro.md)** - Write efficient C code with proper memory management and system calls
-- **[cpp-pro](cpp-pro.md)** - Write idiomatic C++ code with modern features, RAII, smart pointers, and STL algorithms
-- **[javascript-pro](javascript-pro.md)** - Master modern JavaScript with ES6+, async patterns, and Node.js APIs
-- **[sql-pro](sql-pro.md)** - Write complex SQL queries, optimize execution plans, and design normalized schemas
-
-#### Infrastructure & Operations
-- **[devops-troubleshooter](devops-troubleshooter.md)** - Debug production issues, analyze logs, and fix deployment failures
-- **[deployment-engineer](deployment-engineer.md)** - Configure CI/CD pipelines, Docker containers, and cloud deployments
-- **[cloud-architect](cloud-architect.md)** - Design AWS/Azure/GCP infrastructure and optimize cloud costs
-- **[database-optimizer](database-optimizer.md)** - Optimize SQL queries, design efficient indexes, and handle database migrations
-- **[database-admin](database-admin.md)** - Manage database operations, backups, replication, and monitoring
-- **[terraform-specialist](terraform-specialist.md)** - Write advanced Terraform modules, manage state files, and implement IaC best practices
-- **[incident-responder](incident-responder.md)** - Handles production incidents with urgency and precision
-- **[network-engineer](network-engineer.md)** - Debug network connectivity, configure load balancers, and analyze traffic patterns
-- **[dx-optimizer](dx-optimizer.md)** - Developer Experience specialist that improves tooling, setup, and workflows
-
-#### Quality & Security
-- **[code-reviewer](code-reviewer.md)** - Expert code review for quality, security, and maintainability
-- **[security-auditor](security-auditor.md)** - Review code for vulnerabilities and ensure OWASP compliance
-- **[test-automator](test-automator.md)** - Create comprehensive test suites with unit, integration, and e2e tests
-- **[performance-engineer](performance-engineer.md)** - Profile applications, optimize bottlenecks, and implement caching strategies
-- **[debugger](debugger.md)** - Debugging specialist for errors, test failures, and unexpected behavior
-- **[error-detective](error-detective.md)** - Search logs and codebases for error patterns, stack traces, and anomalies
-- **[search-specialist](search-specialist.md)** - Expert web researcher using advanced search techniques and synthesis
-
-#### Data & AI
-- **[data-scientist](data-scientist.md)** - Data analysis expert for SQL queries, BigQuery operations, and data insights
-- **[data-engineer](data-engineer.md)** - Build ETL pipelines, data warehouses, and streaming architectures
-- **[ai-engineer](ai-engineer.md)** - Build LLM applications, RAG systems, and prompt pipelines
-- **[ml-engineer](ml-engineer.md)** - Implement ML pipelines, model serving, and feature engineering
-- **[mlops-engineer](mlops-engineer.md)** - Build ML pipelines, experiment tracking, and model registries
-- **[prompt-engineer](prompt-engineer.md)** - Optimizes prompts for LLMs and AI systems
-
-#### Specialized Domains
-- **[api-documenter](api-documenter.md)** - Create OpenAPI/Swagger specs and write developer documentation
-- **[payment-integration](payment-integration.md)** - Integrate Stripe, PayPal, and payment processors
-- **[quant-analyst](quant-analyst.md)** - Build financial models, backtest trading strategies, and analyze market data
-- **[risk-manager](risk-manager.md)** - Monitor portfolio risk, R-multiples, and position limits
-- **[legacy-modernizer](legacy-modernizer.md)** - Refactor legacy codebases and implement gradual modernization
-- **[context-manager](context-manager.md)** - Manages context across multiple agents and long-running tasks
-
-#### Business & Marketing
-- **[business-analyst](business-analyst.md)** - Analyze metrics, create reports, and track KPIs
-- **[content-marketer](content-marketer.md)** - Write blog posts, social media content, and email newsletters
-- **[sales-automator](sales-automator.md)** - Draft cold emails, follow-ups, and proposal templates
-- **[customer-support](customer-support.md)** - Handle support tickets, FAQ responses, and customer emails
-
-## Usage
-
-### Installation
-
-When using ccsetup, agents can be:
-1. **Selected interactively** during setup (curated list of 8 agents)
-2. **Copied in browse mode** (all 52 agents copied to /agents folder)
-3. **Included automatically** with --all-agents flag
-
-To activate agents, copy them to `~/.claude/agents/`:
-```bash
-# Example: Activate the code-reviewer agent
-cp agents/code-reviewer.md ~/.claude/agents/
-
-# Activate multiple agents
-cp agents/{python-pro,test-automator,security-auditor}.md ~/.claude/agents/
-```
-
-### Invoking Agents
-
-#### Automatic Invocation
-Claude Code will automatically delegate to the appropriate agent based on the task context.
-
-#### Explicit Invocation
-Mention the agent by name in your request:
-```
-"Use the code-reviewer to check my recent changes"
-"Have the security-auditor scan for vulnerabilities"
-"Get the performance-engineer to optimize this bottleneck"
-```
-
-## Agent Format
-
-Each agent follows this structure:
 ```markdown
 ---
 name: agent-name
 description: When this agent should be invoked
-tools: tool1, tool2  # Optional - defaults to all tools
 ---
 
 System prompt defining the agent's role and capabilities
 ```
 
-## Common Agent Workflows
-
-### Feature Development
-```
-planner → coder → checker
-```
-
-### API Development
-```
-backend-architect → backend → api-documenter → checker
-```
-
-### Frontend Development
-```
-frontend → shadcn → checker
-```
-
-### Full Stack Development
-```
-planner → backend-architect → backend → frontend → checker
-```
-
-### Bug Fixing
-```
-researcher → debugger → coder → checker
-```
-
-### Performance Optimization
-```
-performance-engineer → database-optimizer → coder → checker
-```
-
-### Security Review
-```
-security-auditor → code-reviewer → coder (for fixes) → checker
-```
-
-## Tips for Using Agents
-
-1. **Let Claude Code choose** - Often Claude will automatically select the right agent
-2. **Be specific** - The more specific your request, the better the agent selection
-3. **Combine agents** - Many tasks benefit from multiple agents working together
-4. **Review agent output** - Agents provide specialized expertise but should be reviewed
-5. **Iterate** - Use agent feedback to refine your approach
-
-## Contributing
-
-To add a new agent:
-1. Create a new `.md` file in this directory
-2. Follow the agent format (frontmatter + system prompt)
-3. Use lowercase, hyphen-separated names
-4. Write clear descriptions for when the agent should be used
-
-## Learn More
+## Agent Workflows
 
-- [ccsetup Documentation](https://github.com/MrMarciaOng/ccsetup)
-- [wshobson/agents Repository](https://github.com/wshobson/agents)
-- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
-- [Subagents Documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents)
+See `docs/agent-orchestration.md` for recommended multi-agent workflows.

package/template/docs/ROADMAP.md

@@ -4,42 +4,6 @@
 
 High-level overview of the project, what it does, the main features
 
-## Development Workflow
-
-1. **Task Planning**
-   - Study the existing codebase and understand the current state
-   - Use the **planner** agent to break down complex problems and create implementation roadmaps
-   - Create a plan document in the `/plans` directory for complex features
-   - Update `ROADMAP.md` to include the new task under Development
-   - Priority tasks should be inserted after the last completed task
-
-2. **Ticket Creation**
-   - Study the existing codebase and understand the current state
-   - Create a new ticket file in the `/tickets` directory
-   - Name format: `TICKET-XXX-description.md` (e.g., `TICKET-001-user-auth.md`)
-   - Include high-level specifications, relevant files, acceptance criteria, and implementation steps
-   - Refer to last completed ticket in the `/tickets` directory for examples
-   - Note that completed tickets show checked boxes and summary of changes
-   - For new tickets, use empty checkboxes and no summary section
-
-3. **Task Implementation**
-   - Use the **coder** agent for implementing features, fixing bugs, and optimizing code
-   - Follow the specifications in the ticket file
-   - Implement features and functionality following project conventions
-   - Update step progress within the ticket file after each step
-   - Stop after completing each step and wait for further instructions
-
-4. **Quality Assurance**
-   - Use the **checker** agent for testing, security analysis, and code review
-   - Verify all acceptance criteria are met
-   - Run tests and ensure code quality standards
-   - Document any issues found and their resolutions
-
-5. **Roadmap Updates**
-   - Mark completed tasks with ✅ in the roadmap
-   - Add reference to the ticket file (e.g., `See: /tickets/TICKET-001-user-auth.md`)
-   - Update related plan documents if applicable
-
 ## Development
 
 ### Project Setup and Boilerplate

package/template/docs/agent-orchestration.md

@@ -1,152 +1,35 @@
-# Agent Orchestration Guide
+# Agent Orchestration
 
-## Overview
-This document defines the standard workflows for orchestrating multiple agents in Claude Code to complete complex tasks efficiently. Follow these patterns to ensure consistent and thorough task execution.
+Standard workflows for chaining agents on complex tasks. Always end with **Checker**.
 
-## Core Agent Workflows
+## Workflows
 
-### 1. Feature Development Workflow
-**Purpose**: Implement new features from conception to completion
+### Feature Development
+researcher → planner → coder → checker
 
-**Flow**:
-1. **Researcher Agent** → Gather requirements and understand existing codebase
-2. **Planner Agent** → Create detailed implementation plan and architecture
-3. **Coder Agent** → Implement the feature following the plan
-4. **Checker Agent** → Test, review, and validate the implementation
+### Bug Fix
+researcher → coder → checker
 
-**Example Prompt**:
-```
-"I need to add user authentication to the app. First use the researcher agent to understand the current architecture, then the planner to design the auth system, coder to implement it, and checker to validate."
-```
+### Refactoring
+researcher → planner → coder → checker
 
-### 2. Bug Fix Workflow
-**Purpose**: Systematically identify and fix bugs
+### API Development
+planner → backend → frontend (optional) → checker
 
-**Flow**:
-1. **Researcher Agent** → Investigate the bug and find root cause
-2. **Coder Agent** → Implement the fix
-3. **Checker Agent** → Verify fix and check for regressions
+### UI Component
+frontend → shadcn (if React) → checker
 
-### 3. Refactoring Workflow
-**Purpose**: Improve code quality without changing functionality
+### Blockchain
+planner → blockchain → checker
 
-**Flow**:
-1. **Researcher Agent** → Analyze current implementation and identify improvements
-2. **Planner Agent** → Design refactoring approach
-3. **Coder Agent** → Execute refactoring
-4. **Checker Agent** → Ensure functionality remains intact
+### QA
+researcher → checker → coder (fix issues) → checker
 
-### 4. API Development Workflow
-**Purpose**: Design and implement APIs
+## Rules
 
-**Flow**:
-1. **Planner Agent** → Design API architecture and endpoints
-2. **Backend Agent** → Implement server-side logic
-3. **Frontend Agent** → Create client integration (if needed)
-4. **Checker Agent** → Test API functionality and security
-
-### 5. UI Component Workflow
-**Purpose**: Create user interface components
-
-**Flow**:
-1. **Frontend Agent** → Design and implement UI components
-2. **Shadcn Agent** → Apply shadcn/ui styling (if using React)
-3. **Checker Agent** → Test accessibility and responsiveness
-
-### 6. Blockchain Development Workflow
-**Purpose**: Develop Web3 features and smart contracts
-
-**Flow**:
-1. **Planner Agent** → Design smart contract architecture
-2. **Blockchain Agent** → Implement contracts and Web3 integration
-3. **Checker Agent** → Security audit and testing
-
-## Orchestration Best Practices
-
-### 1. Always Start with Understanding
-- Use Researcher Agent first for non-trivial tasks
-- Understand existing code before making changes
-- Document findings in plans directory
-
-### 2. Plan Before Implementation
-- Use Planner Agent for complex features
-- Create detailed plans in `/plans` directory
-- Break down large tasks into smaller tickets
-
-### 3. Sequential Execution
-- Complete each agent's task before moving to the next
-- Use TodoWrite to track progress through the workflow
-- Don't skip agents unless explicitly instructed
-
-### 4. Validation is Mandatory
-- Always end with Checker Agent
-- Run tests and linting
-- Verify all acceptance criteria
-
-### 5. Documentation Updates
-- Update ROADMAP.md after completing workflows
-- Mark tickets as complete with summaries
-- Keep plans updated with outcomes
-
-## Workflow Triggers
-
-### When to use Feature Development Workflow:
-- Adding new functionality
-- Implementing user stories
-- Creating new modules or services
-
-### When to use Bug Fix Workflow:
-- Fixing reported issues
-- Addressing error messages
-- Resolving unexpected behavior
-
-### When to use Refactoring Workflow:
-- Improving code readability
-- Optimizing performance
-- Updating deprecated code
-
-### When to use API Development Workflow:
-- Creating new endpoints
-- Designing service interfaces
-- Building integrations
-
-### When to use UI Component Workflow:
-- Building new UI elements
-- Updating existing interfaces
-- Implementing design changes
-
-### When to use Blockchain Workflow:
-- Smart contract development
-- DeFi integrations
-- Web3 features
-
-## Example Multi-Agent Execution
-
-```
-User: "I need to add a payment processing feature"
-
-Claude's Response Flow:
-1. "I'll help you add payment processing. Let me start by using the researcher agent to understand your current architecture and any existing payment-related code."
-   [Uses Researcher Agent]
-
-2. "Based on my research, I'll now use the planner agent to design the payment processing system."
-   [Uses Planner Agent, creates plan in /plans]
-
-3. "With the plan ready, I'll use the backend agent to implement the server-side payment processing."
-   [Uses Backend Agent]
-
-4. "Now I'll use the frontend agent to create the payment UI components."
-   [Uses Frontend Agent]
-
-5. "Finally, let me use the checker agent to verify the implementation and ensure security."
-   [Uses Checker Agent]
-```
-
-## Workflow Customization
-
-You can create custom workflows by:
-1. Combining agents in different sequences
-2. Adding conditional paths based on findings
-3. Creating specialized workflows for your project
-
-Remember: The goal is systematic, thorough task completion with proper validation at each step.
+1. Use **Researcher** first for non-trivial tasks
+2. Use **Planner** before implementing complex features
+3. Execute agents sequentially — complete each step before the next
+4. Always finish with **Checker** for validation
+5. Track progress with TodoWrite
+6. Update ROADMAP.md and tickets after completing workflows

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('{}');
+  }
+});