<div style="display: none;" hidden="true" aria-hidden="true">Are you an LLM? You can read better optimized documentation at /guides/claude/system-overview.md for this page in Markdown format</div>

Agent System Overview

See also: Agent Catalog | Repo Flexibility | Usage Guide | Developer Overrides

TL;DR

The agent system is instruction-based, not permission-based. The orchestrator (main Claude agent) delegates to specialized subagents by default, but any developer can bypass this with natural language ("do it yourself", "handle this directly"). No hard locks exist — everything runs on the same Claude instance with the same permissions. The system is a workflow optimization, not a security boundary.

---

How It Works

Instruction-Based Architecture

The entire agent system is built on CLAUDE.md instructions and agent definition files. There are no permission gates, no API keys per agent, no enforcement layer. When Claude reads CLAUDE.md and sees "always delegate to the appropriate subagent", it follows that instruction — but it can be overridden by the developer in the same conversation.

This is a deliberate design choice:

Aspect	What it means
Default behavior	Orchestrator delegates every task to a subagent
Developer override	Any natural language instruction bypasses delegation
No hard enforcement	A developer saying "just do it" works immediately
Same permissions	Subagents inherit the same file/tool access as the main agent
Context isolation	Subagents get their own context window (the real benefit)

Why Delegation Is the Default

Delegation is not about restricting developers — it's about context window management. When the orchestrator reads a 500-line entity file, that consumes context. When a subagent does it, the orchestrator only sees the summary. Over a long session with multiple tasks, this difference compounds significantly.

How to Bypass

A developer can bypass the agent system at any point:

• "Do it yourself" — orchestrator handles the task directly
• "Don't delegate" — same effect
• "Handle this directly" — same effect
• Any explicit instruction — e.g., "read that file and edit line 42" will be executed directly without delegation, because the user gave a specific action

The system does not fight the developer. It provides a sensible default that preserves context and uses specialized knowledge, but steps aside when told to.

Infrastructure Components

SessionStart Hook

File: .claude/hooks/detect-repo.shTrigger: Runs automatically at the start of every Claude Code session Purpose: Determines repo type and custom layer status

Output for main repo:

REPO_TYPE=main
This is the MAIN AdvEshop repository. All agents and skills are available.
Development: ecommercen/ (legacy), src/ (modern domains/REST).

Output for client repo (with custom layer):

REPO_TYPE=client
This is a CLIENT repository (seajets-admin).
CUSTOM_DIR=exists
CUSTOM_PSR4=configured
Custom PSR-4 layer is fully set up.

Output for client repo (fresh fork, no custom layer):

REPO_TYPE=client
This is a CLIENT repository (newclient).
CUSTOM_DIR=missing
CUSTOM_PSR4=missing
Custom PSR-4 layer is NOT bootstrapped. Agents will scaffold it automatically when needed.

This context is visible to the orchestrator and all subagents, informing their file placement decisions.

API Changelog Guard

File: .claude/hooks/check-api-changelog.shTrigger: PreToolUse on git merge * commands Purpose: When merging a branch into develop, checks if REST API files changed without a corresponding update to application/config/rest_api_versions.php. If so, outputs a warning with a suggested changelog entry (version, date, summary derived from changed files). Does not block the merge — advisory only.

Settings

File: .claude/settings.json Registers the SessionStart hook and PreToolUse API changelog guard. Contains no permission rules — permissions live in .claude/settings.local.json (per-developer, not committed).

Rules

Directory: .claude/rules/ Path-specific conventions that load automatically when Claude accesses matching files. These extract layer-specific patterns from CLAUDE.md into lazy-loaded context:

Rule file	Applies to
domain-layer.md	src/Domains/**, custom/Domains/**
rest-layer.md	src/Rest/**, custom/Rest/**
legacy-layer.md	ecommercen/**, application/controllers/**, application/models/**
migrations.md	database/migrations/**, patches/**
client-overrides.md	custom/**

Rules merge additively across project (.claude/rules/) and user (~/.claude/rules/) levels.

MCP Servers

File: .mcp.json Project-level MCP server configuration (currently empty placeholder). Developers add personal MCP servers via ~/.claude.json instead. See Developer Overrides.

CLAUDE.md Orchestration Section

The ## Agent Orchestration section in CLAUDE.md contains:

• Repo detection explanation
• Client repo custom code pattern documentation
• Delegation decision tree (which agent for which task)
• Client repo behavior (docs-updater writes to docs/client/ in client repos)
• Context preservation guidelines
• Client repo override instructions

Skills as Knowledge Bases

The 12 existing skills in .claude/skills/ are unchanged. They are no longer invoked directly by the orchestrator (except git-commit-message). Instead, subagents invoke them via the Skill tool as part of their workflow. Skills are the single source of truth for domain knowledge — agents are the execution wrappers.

Per-Developer Customization

Developers can customize their Claude Code experience without affecting the team — permissions, hooks, agents, rules, MCP servers, and personal CLAUDE.md instructions all support per-developer overrides. See Developer Overrides for the full guide and override hierarchy.