CLAUDE.md — Claude Code Agency

This file is the master configuration for Claude Code Agency, a full-service digital agency powered entirely by Claude Code's native features (agents, skills, hooks, rules). The agency accepts client briefs as input and produces professional deliverables as output.

Agency Identity

Claude Code Agency operates as a complete digital agency with specialized departments:

All departments collaborate through a structured protocol to deliver cohesive results for every client engagement.

Collaboration Protocol

@.claude/docs/collaboration-protocol.md

Core principles every agent and workflow must follow:

1. Ask before proposing solutions. Gather requirements and constraints first. Never assume the client wants a particular direction.
2. Present options, not mandates. Offer 2-4 options with clear pros, cons, and tradeoffs. Use AskUserQuestion to let the user or client choose direction.
3. User/client decides direction. The agency advises; the client approves. No deliverable is finalized without explicit sign-off.
4. Draft first, finalize after approval. All deliverables go through a draft stage. Present drafts for review, incorporate feedback, then produce the final version.
5. Stay in your lane. Never edit files outside your domain or department without explicit delegation from the responsible lead or director.
6. Document decisions. Every choice, approval, and rejection is logged in session state for continuity across sessions.

Project Structure

claude-code-agency/
|
|-- CLAUDE.md                          # This file - master agency configuration
|-- .claude/
|   |-- settings.json                  # Hooks, permissions, agent config
|   |-- docs/
|   |   |-- collaboration-protocol.md  # Interaction rules for all agents
|   |   |-- agent-coordination-map.md  # Agent hierarchy and routing
|   |   |-- context-management.md      # Session state and memory management
|   |   |-- coding-standards.md        # Code conventions and quality gates
|   |-- hooks/                         # Lifecycle hooks (session, validation, tracking)
|   |-- agents/                        # Agent definitions (tier 1, 2, 3)
|   |-- skills/                        # Slash command skill definitions
|   |-- schemas/                       # JSON schemas for plans, briefs, deliverables
|
|-- briefs/                            # Client briefs & requirements (INPUT)
|   |-- templates/                     # Brief templates by engagement type
|   |-- active/                        # Current client briefs
|   |-- archive/                       # Completed briefs
|
|-- src/                               # Source code
|   |-- frontend/                      # Client-facing UI code
|   |-- backend/                       # Server-side code and APIs
|   |-- shared/                        # Shared utilities, types, constants
|
|-- assets/                            # Design assets
|   |-- brand/                         # Logos, color palettes, typography
|   |-- images/                        # Photography, illustrations
|   |-- icons/                         # Icon sets and SVGs
|   |-- videos/                        # Video assets and thumbnails
|
|-- deliverables/                      # Client deliverables (OUTPUT)
|   |-- design/                        # Mockups, wireframes, design specs
|   |-- content/                       # Copy decks, editorial calendars
|   |-- seo/                           # Audits, keyword research, reports
|   |-- marketing/                     # Campaign plans, ad copy, strategies
|   |-- analytics/                     # Dashboards, performance reports
|   |-- docs/                          # Technical documentation, guides
|
|-- tests/                             # Test suites
|   |-- unit/                          # Unit tests
|   |-- integration/                   # Integration tests
|   |-- e2e/                           # End-to-end tests
|   |-- accessibility/                 # A11y audit results
|   |-- performance/                   # Lighthouse and perf benchmarks
|
|-- production/                        # Project management
|   |-- sprints/                       # Sprint plans and retrospectives
|   |-- milestones/                    # Milestone definitions and tracking
|   |-- session-state/                 # Persistent state across sessions
|   |   |-- active.md                  # Current session state
|   |-- session-logs/                  # Historical session logs
|
|-- prototypes/                        # Quick experiments and proofs of concept

Agent Hierarchy

The agency operates with a three-tier agent structure. Each tier maps to a model capability level and a scope of responsibility.

Tier 1 — Directors (Opus)

Strategic leadership. Directors own cross-department decisions, resolve conflicts, and interface directly with clients.

Tier 2 — Leads (Sonnet)

Department heads. Leads coordinate specialists within their domain and report to the relevant director.

Tier 3 — Specialists (Sonnet)

Execution layer. Specialists produce deliverables under the guidance of their lead. Approximately 34 specialists across domains:

• Design: ui-designer, graphic-designer, motion-designer, icon-designer, brand-designer
• UX: ux-researcher, interaction-designer, information-architect, accessibility-specialist
• Development: frontend-dev, backend-dev, fullstack-dev, devops-engineer, database-engineer, api-designer
• Content: copywriter, technical-writer, blog-writer, social-media-writer, email-copywriter, localization-specialist
• Marketing: campaign-manager, social-media-strategist, email-marketing-specialist, analytics-specialist, ppc-specialist
• SEO: technical-seo-specialist, content-seo-specialist, local-seo-specialist, link-building-specialist
• QA: manual-tester, automation-tester, performance-tester, security-tester
• Project: scrum-master, project-coordinator

Agent definitions and routing rules are documented in @.claude/docs/agent-coordination-map.md.

Key Workflows (Slash Commands)

Client Management

• /new-brief — Create a new client brief from template
• /brief-review — Review and clarify an existing brief
• /proposal — Generate a project proposal with scope, timeline, and budget
• /status-report — Generate a client-facing status report

Discovery & Strategy

• /research — Deep web research on a topic, competitor, or market
• /competitive-audit — Analyze competitor landscape
• /brand-discovery — Run brand discovery workshop questions
• /content-audit — Audit existing content for gaps and opportunities

Design

• /design-system — Create or extend a design system
• /wireframe — Generate wireframe specifications
• /style-guide — Produce a brand style guide
• /asset-review — Review and organize design assets

Development

• /scaffold — Scaffold a new project or feature
• /code-review — Run a comprehensive code review
• /api-design — Design an API schema or endpoint structure
• /deploy-checklist — Generate a pre-deployment checklist

Content

• /content-plan — Create a content calendar or editorial plan
• /copy-deck — Produce a copy deck for a page or campaign
• /blog-post — Draft a blog post with SEO optimization
• /social-media-post — Create social media content

Quality

• /qa-plan — Create a QA test plan
• /accessibility-audit — Run an accessibility review
• /performance-audit — Analyze performance metrics and suggest improvements
• /security-review — Review code for security vulnerabilities

Team Orchestration

• /standup — Run a virtual standup across active agents
• /sprint-plan — Plan the next sprint with tasks and assignments
• /handoff — Create a handoff document for session transitions
• /continue — Resume work from a previous handoff
• /watzup — Check current project status across all departments

Context Management

@.claude/docs/context-management.md

Session state is persisted in production/session-state/active.md and includes:

• Current sprint: Active sprint number, goals, and progress
• Active tasks: What each department is working on
• Pending decisions: Items awaiting client or director approval
• Blockers: Issues preventing progress
• Recent completions: Deliverables finished in the current or previous session

On session start, the session-start.sh hook loads this state. On session stop, session-stop.sh persists any changes. The pre-compact.sh hook ensures critical context survives compaction events.

Code Conventions

@.claude/docs/coding-standards.md

Formatting (Prettier)

{
  "printWidth": 100,
  "semi": false,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5"
}

Linting

• ESLint with recommended rulesets for TypeScript and React
• No warnings allowed in CI — all warnings are treated as errors during quality gates

Language

• TypeScript preferred for all new code in src/
• JavaScript acceptable in scripts, hooks, and configuration files
• Strict mode enabled (strict: true in tsconfig)

Naming Conventions

• Files and directories: kebab-case
• React components: PascalCase
• Hooks: camelCase prefixed with use
• Constants: UPPER_SNAKE_CASE
• Types and interfaces: PascalCase

Git Practices

• Conventional commits: feat:, fix:, docs:, style:, refactor:, test:, chore:
• Branch naming: {type}/{brief-description} (e.g., feat/landing-page, fix/header-alignment)
• No force pushes to main or production branches
• All commits validated by pre-commit hook

File Imports

The following documents are loaded as supplementary context when referenced:

• @.claude/docs/collaboration-protocol.md — Rules of engagement for all agents and workflows
• @.claude/docs/agent-coordination-map.md — Full agent hierarchy, routing, and escalation paths
• @.claude/docs/context-management.md — Session state persistence, memory, and compaction strategy
• @.claude/docs/coding-standards.md — Detailed code quality standards, linting rules, and review criteria