coding-standards

When using Claude Code for complex projects, you may face these challenges:

| Challenge | Without This System | With This System |

|-----------|---------------------|------------------|

| Inconsistent quality | AI may skip tests or reviews | Enforced quality gates before completion |

| Repeated explanations | Re-explain project rules every session | Rules loaded automatically from config |

| Complex task handling | Manual breakdown of large tasks | Automatic routing to specialized agents |

| Technology switching | Different prompts for each stack | Skills adapt agents to any technology |

• [Quick Start](#quick-start)
• [Key Features](#key-features)
• [Installation](#installation)
• [Getting Started](#getting-started)
• [Configuration](#configuration)
• [Architecture Overview](#architecture-overview)
• [Reference](#reference)
• [License](#license)

```bash

# 1. Clone to ~/.claude/

git clone https://github.com/your-repo/claude-orchestration.git ~/.claude

# 2. Install yq (required for config loading)

brew install yq

# 3. Create project configuration

mkdir -p /path/to/your/project/.claude

cp ~/.claude/templates/.claude/config.yaml /path/to/your/project/.claude/

# 4. (Optional) Create CLAUDE.md for project-specific context

# Add business rules, prohibited patterns, architecture decisions

# 5. Start Claude Code

cd /path/to/your/project

claude

```

That's it! Use /dev-workflow when you need the full orchestration system.

| Feature | Description |

|---------|-------------|

| On-Demand Workflow | Invoke via /dev-workflow command - not always-on |

| Skill-Based Adaptation | Same agents work with PHP, TypeScript, React, etc. via loadable skills |

| Quality Gates | Automatic code review and acceptance criteria verification |

| Project Rules as Config | Define constraints in YAML, enforced automatically |

| Multi-Project Support | One system, multiple projects with different tech stacks |

Prerequisites

• [Claude Code](https://docs.anthropic.com/en/docs/claude-code) - Anthropic's CLI tool
• yq - YAML processor (used by skills to read config)

```bash

brew install yq # macOS

# or: pip install yq

```

Setup

```bash

# Clone this repository to ~/.claude/

git clone https://github.com/your-repo/claude-orchestration.git ~/.claude

# Verify installation

ls ~/.claude/agents/ # Should show agent definitions

ls ~/.claude/skills/ # Should show skill definitions

```

1. Create project configuration

```bash

mkdir -p /path/to/project/.claude

cp ~/.claude/templates/.claude/config.yaml /path/to/project/.claude/config.yaml

```

2. Configure your project

.claude/config.yaml - Machine-readable settings:

• Agent skill assignments (defines your tech stack)
• Test commands
• Constraints as natural language rules

(Optional) CLAUDE.md - Human-readable project context:

• Business rules with reasons and code examples
• Prohibited patterns with explanations
• Architecture decisions

3. Start Claude Code

```bash

cd /path/to/project

claude

```

By default, Claude Code operates in direct execution mode. For complex tasks, use:

```

/dev-workflow

Implement user authentication with JWT tokens.

Requirements:

• Login/logout endpoints
• Token refresh mechanism
• Session management

```

The /dev-workflow command:

1. Invokes the main-orchestrator agent
2. Classifies and routes your request
3. Enforces quality gates before completion

Configuration lives in .claude/config.yaml. Here's what each section does:

| Section | Purpose | Example |

|---------|---------|---------|

| agents.* | Which skills each agent loads | code-developer: [php/coding-standards] |

| constraints.* | Rules enforced during development | Natural language prohibitions |

| testing.* | Test execution settings | Docker command, documentation path |

| git.* | Git operation policy | auto/user_request_only/prohibited |

Example Configuration

```yaml

# Define your tech stack via agent skills

agents:

code-developer:

skills:

- php/coding-standards

- php-cakephp/code-implementer

# Project constraints (natural language rules)

constraints:

architecture:

layers:

- "Controller must not contain business logic."

dependencies:

- "No circular dependencies between Models."

testing:

prohibited:

- "Do not mock production code."

# Git settings

git:

operations:

commit: user_request_only

push: user_request_only

```

Where to Put Information

| Information | Location | Required |

|-------------|----------|----------|

| Agent skill assignments | .claude/config.yaml | Yes |

| Constraints as rules | .claude/config.yaml | Yes |

| Test commands | .claude/config.yaml | Yes |

| Business rules with code examples | CLAUDE.md (optional) | No |

The orchestration system is invoked via the /dev-workflow command. This triggers the main-orchestrator agent which coordinates the workflow below.

```mermaid

flowchart TD

subgraph Entry["🚪 Entry Layer"]

A[User Request] --> B0[main-orchestrator]

B0 --> B[quick-classifier]

end

subgraph Analysis["🔍 Analysis Layer"]

B --> C{Trivial?}

C -->|Yes| D[main-orchestrator
Direct Execution]

C -->|No| G[goal-clarifier]

G --> H{Needs
Clarification?}

H -->|Yes| I[main-orchestrator
Ask User]

I --> G

H -->|No| J[task-scale-evaluator]

end

subgraph Implementation["⚙️ Implementation Layer"]

J -->|task object| M[workflow-orchestrator]

M --> L[code-developer]

L --> N[test-executor]

N --> O{Tests Pass?}

O -->|No| P[test-failure-debugger]

P --> L

end

subgraph Quality["✅ Quality Layer"]

O -->|Yes| Q[quality-reviewer]

Q --> R[deliverable-evaluator]

R --> S{Criteria
Met?}

S -->|No| L

end

subgraph Report["📋 Report Layer"]

S -->|Yes| T[main-orchestrator
Report Results]

D --> T

T --> U[Complete]

end

style Entry fill:#e3f2fd,stroke:#1976d2

style Analysis fill:#fff8e1,stroke:#f9a825

style Implementation fill:#e8f5e9,stroke:#388e3c

style Quality fill:#fce4ec,stroke:#c2185b

style Report fill:#f3e5f5,stroke:#7b1fa2

```

Data Flow: task object (with acceptance_criteria) flows through GC → TSE → WO → DE via prompt.

How It Works

When you invoke /dev-workflow:

1. Entry: Your request is handled by main-orchestrator agent
2. Classification: quick-classifier determines if request is trivial or complex
3. Triage: Trivial tasks execute directly; complex ones go through goal-clarifier (which defines task with acceptance_criteria)
4. Implementation: task-scale-evaluator passes task object to workflow-orchestrator, which manages code-developer → test-executor
5. Quality: quality-reviewer checks code, deliverable-evaluator extracts acceptance_criteria from task and