ccsetup 1.1.1 → 1.2.0

package/template/.claude/skills/ralph/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: ralph
+description: "Convert PRDs to prd.json format for the Ralph autonomous agent system. Use when you have an existing PRD and need to convert it to Ralph's JSON format. Triggers on: convert this prd, turn this into ralph format, create prd.json from this, ralph json."
+---
+
+# Ralph PRD Converter
+
+Converts existing PRDs to the prd.json format that Ralph uses for autonomous execution. Scans the codebase to populate quality checks, file hints, and story notes automatically.
+
+---
+
+## The Job
+
+1. **Scan the codebase** to detect quality commands and relevant file paths
+2. Read the PRD (markdown file or text) — check for a Tech Context section first
+3. Convert to `scripts/ralph/prd.json` with codebase-informed stories
+4. Initialize `scripts/ralph/progress.txt` if it doesn't exist
+
+**Important:** Do NOT start implementing. Just create the prd.json.
+
+---
+
+## Step 1: Codebase Reconnaissance
+
+Before converting, silently scan the project using Claude Code tools.
+
+### If PRD has a Tech Context section
+The improved `/prd` skill generates a Tech Context section with stack, quality gates, and relevant file paths. If present, use it directly — no need to re-scan.
+
+### If PRD has no Tech Context section
+Scan manually:
+
+**Detect quality commands** — Read `package.json` scripts, config files, Makefiles:
+- Look for: `typecheck`, `tsc`, `check-types` → record the exact script (e.g., `npm run typecheck`)
+- Look for: `lint`, `eslint`, `biome check` → record exact script (e.g., `npm run lint`)
+- Look for: `test`, `vitest`, `jest`, `pytest` → record exact script (e.g., `npm test`)
+- Look for: `build` → record exact script (e.g., `npm run build`)
+
+**Scan relevant files** — Use Glob to find files related to each user story:
+- Database: `**/schema.prisma`, `**/models/**`, `**/migrations/**`
+- API: `**/api/**`, `**/routes/**`, `**/app/**/route.*`
+- Components: `**/components/**`
+- Utilities: `**/hooks/**`, `**/utils/**`, `**/lib/**`
+
+These become `notes` on each story — giving Ralph file-level hints for where to work.
+
+---
+
+## Step 2: Output Format
+
+```json
+{
+  "project": "[Project Name]",
+  "branchName": "ralph/[feature-name-kebab-case]",
+  "description": "[Feature description from PRD title/intro]",
+  "qualityChecks": {
+    "typecheck": "npm run typecheck",
+    "lint": "npm run lint",
+    "test": "npm test",
+    "build": "npm run build"
+  },
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Story title]",
+      "description": "As a [user], I want [feature] so that [benefit]",
+      "acceptanceCriteria": [
+        "Criterion 1",
+        "Criterion 2",
+        "Typecheck passes",
+        "Lint passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": "Relevant files: prisma/schema.prisma, src/app/api/tasks/route.ts"
+    }
+  ]
+}
+```
+
+### The `qualityChecks` field
+
+This is **new and critical**. It tells Ralph the exact commands to run, so each iteration doesn't have to guess. Only include checks that actually exist in the project:
+
+```json
+"qualityChecks": {
+  "typecheck": "npm run typecheck",
+  "lint": "npm run lint"
+}
+```
+
+If a project has no typecheck, don't include it. If it uses `make check`, use that. Be exact.
+
+### The `notes` field
+
+Pre-populate with **file hints** from your codebase scan — relevant files the story will likely touch or extend:
+
+```
+"notes": "Relevant files: prisma/schema.prisma (Task model), src/components/TaskCard.tsx (extend with badge)"
+```
+
+This gives each Ralph iteration a head start instead of scanning the codebase from scratch.
+
+---
+
+## Story Size: The Number One Rule
+
+**Each story must be completable in ONE Ralph iteration (one context window).**
+
+Ralph spawns a fresh instance per iteration with no memory of previous work. If a story is too big, the LLM runs out of context before finishing and produces broken code.
+
+### Right-sized stories:
+- Add a database column and migration
+- Add a UI component to an existing page
+- Update a server action with new logic
+- Add a filter dropdown to a list
+
+### Too big (split these):
+- "Build the entire dashboard" — Split into: schema, queries, UI components, filters
+- "Add authentication" — Split into: schema, middleware, login UI, session handling
+- "Refactor the API" — Split into one story per endpoint or pattern
+
+**Rule of thumb:** If you cannot describe the change in 2-3 sentences, it is too big.
+
+---
+
+## Story Ordering: Dependencies First
+
+Stories execute in priority order. Earlier stories must not depend on later ones.
+
+**Correct order:**
+1. Schema/database changes (migrations)
+2. Server actions / backend logic
+3. UI components that use the backend
+4. Dashboard/summary views that aggregate data
+
+**Wrong order:**
+1. UI component (depends on schema that does not exist yet)
+2. Schema change
+
+---
+
+## Acceptance Criteria: Must Be Verifiable
+
+Each criterion must be something Ralph can CHECK, not something vague.
+
+### Good criteria (verifiable):
+- "Add `status` column to tasks table with default 'pending'"
+- "Filter dropdown has options: All, Active, Completed"
+- "Clicking delete shows confirmation dialog"
+
+### Bad criteria (vague):
+- "Works correctly"
+- "User can do X easily"
+- "Good UX"
+- "Handles edge cases"
+
+### Quality criteria — use what the project actually has
+
+Append the quality checks detected in Step 1. Examples:
+
+- Project has typecheck + lint → append `"Typecheck passes"`, `"Lint passes"`
+- Project has only tests → append `"Tests pass"`
+- Project has a build step → append `"Build passes"`
+
+Do **not** hardcode "Typecheck passes" if the project has no typecheck.
+
+### For stories that change UI, also include:
+```
+"Verify in browser using dev-browser skill"
+```
+
+---
+
+## Conversion Rules
+
+1. **Each user story becomes one JSON entry**
+2. **IDs**: Sequential (US-001, US-002, etc.)
+3. **Priority**: Based on dependency order, then document order
+4. **All stories**: `passes: false`
+5. **notes**: Pre-populate with relevant file paths from codebase scan
+6. **branchName**: Derive from feature name, kebab-case, prefixed with `ralph/`
+7. **qualityChecks**: Populated from detected project commands (Step 1)
+8. **Quality criteria on stories**: Match what `qualityChecks` contains
+
+---
+
+## Splitting Large PRDs
+
+If a PRD has big features, split them:
+
+**Original:**
+> "Add user notification system"
+
+**Split into:**
+1. US-001: Add notifications table to database
+2. US-002: Create notification service for sending notifications
+3. US-003: Add notification bell icon to header
+4. US-004: Create notification dropdown panel
+5. US-005: Add mark-as-read functionality
+6. US-006: Add notification preferences page
+
+Each is one focused change that can be completed and verified independently.
+
+---
+
+## Example
+
+**Input PRD with Tech Context:**
+```markdown
+# PRD: Task Status Feature
+
+## Tech Context
+- **Stack:** Next.js 14 (App Router) + TypeScript + Tailwind CSS
+- **DB:** Prisma with PostgreSQL (`prisma/schema.prisma`)
+- **UI:** shadcn/ui in `src/components/ui/`
+- **Quality gates:** Typecheck (`tsc --noEmit`), Lint (`eslint`), Tests (`vitest`)
+- **Relevant code:**
+  - Task model: `prisma/schema.prisma`
+  - Task list: `src/components/TaskList.tsx`
+  - Task card: `src/components/TaskCard.tsx`
+  - Badge: `src/components/ui/Badge.tsx`
+  - API: `src/app/api/tasks/`
+
+## User Stories
+### US-001: Add status field to database ...
+### US-002: Display status badge on task cards ...
+### US-003: Add status toggle ...
+### US-004: Filter tasks by status ...
+```
+
+**Output prd.json:**
+```json
+{
+  "project": "TaskApp",
+  "branchName": "ralph/task-status",
+  "description": "Task Status Feature - Track task progress with status indicators",
+  "qualityChecks": {
+    "typecheck": "npx tsc --noEmit",
+    "lint": "npm run lint",
+    "test": "npx vitest run"
+  },
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Add status field to tasks table",
+      "description": "As a developer, I need to store task status in the database.",
+      "acceptanceCriteria": [
+        "Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
+        "Generate and run migration successfully",
+        "Typecheck passes",
+        "Lint passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": "Relevant files: prisma/schema.prisma (Task model)"
+    },
+    {
+      "id": "US-002",
+      "title": "Display status badge on task cards",
+      "description": "As a user, I want to see task status at a glance.",
+      "acceptanceCriteria": [
+        "Each task card shows colored status badge",
+        "Badge colors: gray=pending, blue=in_progress, green=done",
+        "Typecheck passes",
+        "Lint passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 2,
+      "passes": false,
+      "notes": "Relevant files: src/components/TaskCard.tsx (extend), src/components/ui/Badge.tsx (reuse with color variants)"
+    },
+    {
+      "id": "US-003",
+      "title": "Add status toggle to task list rows",
+      "description": "As a user, I want to change task status directly from the list.",
+      "acceptanceCriteria": [
+        "Each row has status dropdown or toggle",
+        "Changing status saves immediately via PATCH /api/tasks/[id]",
+        "UI updates without page refresh",
+        "Typecheck passes",
+        "Lint passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 3,
+      "passes": false,
+      "notes": "Relevant files: src/components/TaskList.tsx, src/app/api/tasks/[id]/route.ts"
+    },
+    {
+      "id": "US-004",
+      "title": "Filter tasks by status",
+      "description": "As a user, I want to filter the list to see only certain statuses.",
+      "acceptanceCriteria": [
+        "Filter dropdown: All | Pending | In Progress | Done",
+        "Filter persists in URL params",
+        "Typecheck passes",
+        "Lint passes",
+        "Tests pass",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 4,
+      "passes": false,
+      "notes": "Relevant files: src/components/TaskList.tsx (add filter dropdown)"
+    }
+  ]
+}
+```
+
+---
+
+## Archiving Previous Runs
+
+**Before writing a new prd.json, check if there is an existing one from a different feature:**
+
+1. Read the current `prd.json` if it exists
+2. Check if `branchName` differs from the new feature's branch name
+3. If different AND `progress.txt` has content beyond the header:
+   - Create archive folder: `archive/YYYY-MM-DD-feature-name/`
+   - Copy current `prd.json` and `progress.txt` to archive
+   - Reset `progress.txt` with fresh header
+
+**The ralph.sh script handles this automatically** when you run it, but if you are manually updating prd.json between runs, archive first.
+
+---
+
+## Checklist Before Saving
+
+Before writing prd.json, verify:
+
+- [ ] Ran codebase reconnaissance or read PRD's Tech Context (Step 1)
+- [ ] `qualityChecks` populated with exact commands from the project
+- [ ] **Previous run archived** (if prd.json exists with different branchName, archive it first)
+- [ ] Each story is completable in one iteration (small enough)
+- [ ] Stories are ordered by dependency (schema → backend → UI)
+- [ ] Story quality criteria match what `qualityChecks` contains (not hardcoded)
+- [ ] UI stories have "Verify in browser using dev-browser skill" as criterion
+- [ ] Acceptance criteria are verifiable (not vague)
+- [ ] Story `notes` pre-populated with relevant file paths
+- [ ] No story depends on a later story

package/template/CLAUDE.md

@@ -15,9 +15,12 @@
 ```
 .
 ├── CLAUDE.md          # This file - project instructions for Claude
-├── .claude/           # Claude Code configuration (auto-generated)
-│   └── agents/        # Project-specific agent overrides
-├── agents/            # Custom agents for specialized tasks
+├── .claude/
+│   ├── agents/        # 8 core agents (backend, blockchain, checker, coder, frontend, planner, researcher, shadcn)
+│   └── skills/        # /prd and /ralph slash commands
+├── agents/            # Documentation only — see .claude/agents/ for active agents
+├── scripts/
+│   └── ralph/         # Autonomous agent loop (ralph.sh + agent instructions)
 ├── docs/              # Project documentation
 ├── plans/             # Project plans and architectural documents
 └── tickets/           # Task tickets and issues
@@ -58,24 +61,44 @@
 
 ## Agents
 
-See @agents/README.md for available agents and their purposes
+8 core agents are pre-installed in `.claude/agents/`. See @agents/README.md for the full list and instructions for adding custom agents.
+
+## Skills (Slash Commands)
+
+- **/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.
+
+## 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 --tool claude --model opus 20  # Specify model + iterations
+```
+
+Typical workflow: `/prd` → `/ralph` → `./scripts/ralph/ralph.sh`
 
 ## Agent Orchestration
 
-After adding the agents you want to in `./claude/agents` folder, setup the workflow for Claude code to follow
+See @docs/agent-orchestration.md for detailed workflow patterns on how to chain agents effectively.
+
+## Workflow Selector Hook (Optional)
+
+An optional hook that suggests agent workflows based on your prompt. Claude will ask before applying.
+
+To activate after installation:
+```bash
+export CCSETUP_WORKFLOW=1
+```
+
+When unset, the hook is inactive and Claude uses its default behavior. Install the hook with `npx ccsetup --install-hooks`.
 
 ## Tickets
 
 See @tickets/README.md for ticket format and management approach
 
-### Ticket Management
-- **Ticket List**: Maintain @tickets/ticket-list.md as a centralized index of all tickets
-- **Update ticket-list.md** whenever you:
-  - Create a new ticket (add to appropriate priority section)
-  - Change ticket status (update emoji and move if completed)
-  - Complete a ticket (move to completed section with date)
-- **Status Emojis**: 🔴 Todo | 🟡 In Progress | 🟢 Done | 🔵 Blocked | ⚫ Cancelled
-
 ## Plans
 
 See @plans/README.md for planning documents and architectural decisions
@@ -88,14 +111,9 @@ See @plans/README.md for planning documents and architectural decisions
 
 ## Important Instructions
 
-Before starting any task:
-
-1. **Confirm understanding**: Always confirm you understand the request and outline your plan before proceeding
-2. **Ask clarifying questions**: Never make assumptions - ask questions when requirements are unclear
-3. **Create planning documents**: Before implementing any code or features, create a markdown file documenting the approach
-4. **Use plans directory**: When discussing ideas or next steps, create timestamped files in the plans directory (e.g., `plans/next-steps-YYYY-MM-DD-HH-MM-SS.md`) to maintain a record of decisions
-5. **No code comments**: Never add comments to any code you write - code should be self-documenting
-6. **Maintain ticket list**: Always update @tickets/ticket-list.md when creating, updating, or completing tickets to maintain a clear project overview
+- Ask clarifying questions when requirements are unclear
+- Self-documenting code — no code comments
+- For complex features, consider creating a plan document in `/plans` before implementing
 
 ## Additional Notes
 

package/template/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+## 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

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.