AI-Powered Development Workflow

This repository contains the configuration files for a team development workflow powered by Claude Code (orchestrator) and Codex CLI (code executor).

This repo is a starter template, not a production-ready drop-in. Fill in the > TODO: sections in CLAUDE.md and AGENTS.md before using it as the source of truth for a real project.

---

How It Works

Claude Code is the brain. It understands context, routes tasks to subagents, applies skills, and makes decisions about what needs to be done.

Codex CLI is the hands. It receives scoped, specific instructions from Claude and executes them — writing files, implementing features, making fixes.

Developers interact with Claude Code. Claude delegates code changes to Codex. Humans review and approve before anything is merged or deployed.

---

Repository Structure

├── CLAUDE.md                          # Claude Code configuration (fill in your project details)
├── AGENTS.md                          # Codex CLI configuration (fill in your project details)
│
├── sub-agents/
│   ├── pr-review-agent.md             # Automated PR review
│   ├── feature-planner-agent.md       # Break features into Codex tasks
│   ├── codebase-navigator-agent.md    # Architecture explanation and onboarding
│   ├── documentation-agent.md        # Auto-generate and update docs
│   ├── test-qa-agent.md               # Test coverage analysis and test generation
│   └── security-audit-agent.md       # Security vulnerability scanning
│
└── skills/
    ├── understand_codebase.md         # Deep repo analysis
    ├── explain_function.md            # Plain-English function explanation
    ├── trace_data_flow.md             # Follow data through the system
    ├── scaffold_feature.md            # Generate feature boilerplate
    ├── refactor_code.md               # Identify and delegate refactors
    ├── write_tests.md                 # Design and delegate test writing
    ├── review_pr_diff.md              # Structured PR review
    ├── summarize_pr.md                # PR summary for changelogs and stakeholders
    ├── create_adr.md                  # Architecture Decision Records
    ├── generate_readme.md             # Auto-generate README
    ├── write_api_docs.md              # API documentation
    └── onboarding_guide.md            # New developer onboarding guide

---

Setup Instructions

Step 1: Copy Files Into Your Project

Copy the following into the root of your project repository:

• CLAUDE.md
• AGENTS.md

Copy the sub-agents/ and skills/ folders into your project (or a shared team repo that all projects reference).

Step 2: Fill In the TODOs

Both CLAUDE.md and AGENTS.md contain > TODO: sections. Fill these in before committing. Until those placeholders are replaced, treat the docs as examples rather than authoritative operating instructions.

• Project name and stack
• Coding conventions your team follows
• Commands to install, run, test, and build
• Files that should never be modified by agents
• Team contacts for the onboarding guide

Step 3: Install Claude Code and Codex CLI

# Install Claude Code
npm install -g @anthropic-ai/claude-code

# Install Codex CLI
npm install -g @openai/codex

Set your API keys:

export ANTHROPIC_API_KEY=your_key_here
export OPENAI_API_KEY=your_key_here

Step 4: Start with Claude Code

# In your project directory
claude

# Claude will automatically read CLAUDE.md and understand your project

Step 5: Set Codex Approval Mode

Choose based on your team's confidence level:

# Suggest mode (recommended to start — shows changes before applying)
codex --approval-mode suggest

# Auto-edit mode (applies changes automatically, review before commit)
codex --approval-mode auto-edit

auto-edit only means Codex can apply changes in the local workspace without pausing for every edit. It does not replace human review, and it should not be treated as approval to merge or deploy automatically.

---

Common Usage Examples

Plan and implement a feature:

You: "I need to add email notifications when a user's subscription expires"
Claude: [Runs Feature Planner Agent, produces subtask list]
Claude: "I'll hand these tasks to Codex. Shall I proceed?"
You: "Yes"
Claude: [Delegates each subtask to Codex CLI for implementation]

Review a pull request:

You: "Review the open PR for the billing module"
Claude: [Runs PR Review Agent with review_pr_diff skill]
Claude: [Produces structured review with severity ratings and Codex fix tasks]

Understand the codebase:

You: "Walk me through how authentication works in this repo"
Claude: [Runs Codebase Navigator Agent with understand_codebase skill]
Claude: [Produces step-by-step explanation with file references]

Onboard a new developer:

You: "Generate an onboarding guide for this repo"
Claude: [Runs Documentation Agent with onboarding_guide skill]
Claude: [Delegates file creation to Codex, produces docs/ONBOARDING.md]

---

Team Rollout Plan

Week 1–2: Foundation

• Install Claude Code and Codex CLI for all engineers
• Copy and fill in CLAUDE.md and AGENTS.md for each repo
• Run a team workshop: basic Claude Code usage + Codex for simple tasks
• Start with low-risk tasks: explaining code, reviewing small PRs

Week 3–4: Subagents and Skills

• Wire PR Review Agent to GitHub Actions
• Run Documentation Agent on main repos
• Practice: Feature Planner → Codex implementation → Claude review

Week 5–6: Full Integration

• Sub-agents available in CI/CD with human review gates still enforced for merge and deploy
• Define human review checkpoints for your team
• Document team-specific workflows in your project's CLAUDE.md

Ongoing

• Weekly review of agent outputs — refine prompts and skills as needed
• Track metrics: PR review time, onboarding time, test coverage
• Expand Codex autonomy as team confidence grows

---

Key Principles

1. Claude thinks, Codex acts. Claude never writes production code directly. Codex never makes architectural decisions.

2. Humans stay in the loop. Every workflow has a human review checkpoint before merging or deploying.

3. CLAUDE.md is the source of truth. Keep it updated. It controls how Claude behaves in your repo.

4. Start narrow, expand gradually. Begin with suggest mode and simple tasks. Graduate to auto-edit as trust builds, but keep human merge and deploy approval in place.

5. Skills are living documents. Treat the skills library like production code — version control it, review changes, improve it over time.

---

Contributing to This Workflow

When a subagent or skill needs improvement:

1. Identify the specific behavior that needs to change
2. Edit the relevant .md file
3. Test with a real scenario before merging
4. Update this README if the structure changes