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

Usage Guide

See also: System Overview | Agent Catalog | Repo Flexibility | Developer Overrides

TL;DR

Start a session, the hook auto-detects your repo. Ask for what you need in plain English — the orchestrator delegates to the right agent. Say "do it yourself" to bypass delegation. Chain agents for multi-step tasks. Use /clear between unrelated tasks to free context.

---

Getting Started

Session Start

Every session begins with the detect-repo.sh hook running automatically. You'll see output like:

REPO_TYPE=main
This is the MAIN AdvEshop repository...

or

REPO_TYPE=client
This is a CLIENT repository (clientname)...
CUSTOM_DIR=exists
CUSTOM_PSR4=configured

No action needed — this is informational context for the agents.

Basic Interaction

Just describe what you need. The orchestrator matches your request to the right agent:

You: "Create a domain for the adv_coupons table"
→ Delegates to domain-generator

You: "Add POST and PUT endpoints for the Coupon REST API"
→ Delegates to rest-crud-writer

You: "Create a migration to add a discount_type column to adv_coupons"
→ Delegates to migration-writer

You: "Review the code I just generated"
→ Delegates to code-reviewer

You: "Write tests for CouponService"
→ Delegates to test-writer

You: "Commit these changes"
→ Uses git-commit-message skill directly (no subagent)

Bypassing Delegation

Any of these phrases make the orchestrator handle the task directly:

• "Do it yourself"
• "Don't delegate"
• "Handle this directly"
• Or just give a specific direct instruction: "Open src/Domains/Coupon/Service.php and change the return type on line 42"

You can also mix: use agents for heavy generation, then handle small tweaks yourself.

Common Workflows

New Domain Feature (Full Chain)

The most common workflow chains multiple agents sequentially:

1. "Analyze the schema for adv_loyalty_points and adv_loyalty_points_mui"
   → schema-analyzer

2. "Generate the domain and REST API for LoyaltyPoints"
   → domain-generator (includes schema analysis internally)

3. "Add CRUD endpoints for LoyaltyPoints"
   → rest-crud-writer

4. "Register the DI container for the new domain"
   → container-writer

5. "Write tests for LoyaltyPointsService"
   → test-writer

6. "Review all the code we just generated"
   → code-reviewer

7. "Commit these changes"
   → git-commit-message skill

Or shortcut: "Generate a complete domain with CRUD for the adv_loyalty_points table" — the orchestrator will chain the relevant agents.

Schema Change

1. "Add a redemption_limit column to adv_loyalty_points"
   → migration-writer

2. "Update the LoyaltyPoints entity to include the new field"
   → domain-generator or direct edit

3. "Commit"
   → git-commit-message

Quick Legacy Fix (Client Repo)

1. "Fix the shipping calculation in the checkout controller"
   → legacy-developer (works in application/)

2. "Commit"
   → git-commit-message

New Client Integration

1. "Create a job that syncs products from the Acme ERP API"
   → job-writer (creates in application/libraries/)

2. "Create a migration for the sync log table"
   → migration-writer

3. "Commit"
   → git-commit-message

Client Custom Domain (First Time)

On a fresh client fork with no custom/ directory:

1. "Generate a domain for the adv_ships table"
   → domain-generator detects CUSTOM_DIR=missing
   → Scaffolds: creates custom/, adds PSR-4 mapping, composer dump-autoload
   → Then generates Custom\Domains\Ship\... in custom/Domains/Ship/

Subsequent domain generation reuses the existing custom/ layer.

Agent Behavior Expectations

What Agents Return

Every agent returns a concise summary to the orchestrator:

• Files created/modified with paths
• Manual steps needed (route registration, etc.)
• Warnings about missing dependencies or unusual patterns
• Blocked status if a prerequisite is missing (e.g., job-writer reports missing domain)

When Agents Stop and Report Back

Agents don't blindly proceed when prerequisites are missing:

Agent	Stops when...	Reports...
job-writer	Job needs a custom domain that doesn't exist	"Domain entity needs to be created first — delegate to domain-generator"
rest-crud-writer	No existing read-only layer to add CRUD to	"Domain/REST layer needs to be generated first"
domain-generator	Schema not provided or not parseable	"Please provide the DDL or table name"
container-writer	No services to register	"No new services found — container is already up to date"

Context Preservation

The orchestrator stays lean by delegating heavy file reading to subagents. Best practices:

• Use /clear between unrelated tasks — frees the context window
• Don't repeat information — if you told a subagent something, the orchestrator has the summary
• Chain agents for multi-step tasks — each agent gets fresh context

File Reference

File	Purpose
.claude/settings.json	SessionStart hook + PreToolUse API changelog guard
.claude/hooks/detect-repo.sh	Repo type detection script
.claude/hooks/check-api-changelog.sh	API changelog guard (warns on merge to develop)
.claude/agents/*.md	12 subagent definitions
.claude/skills/	12 skill knowledge bases (consumed by agents)
CLAUDE.md	Orchestrator instructions (delegation rules, repo patterns)
.claude/settings.local.json	Per-developer permissions (not committed)

Customization

Each developer can customize their Claude Code setup without affecting the team. Common customizations include auto-allowing commands, disabling unused agents, adding personal MCP servers, and adding personal rules or CLAUDE.md instructions.

See the full guide: Per-Developer Overrides

Key files:

• .claude/settings.local.json — your permissions (gitignored)
• ~/.claude/agents/*.md — personal agent overrides
• ~/.claude/rules/*.md — personal rules
• ~/.claude.json — personal MCP servers

---

Troubleshooting

Agent not delegating

The orchestrator might handle a task directly if:

• Your request is very simple/specific (e.g., "change line 42 in file X")
• You previously said "do it yourself" in the session
• The request doesn't match any agent's description

Solution: Be explicit — "use the migration-writer to create a migration for..."

Wrong repo type detected

If the hook misidentifies the repo:

• Check git remote get-url origin
• Main repo must contain devteamadvisable/adveshop4 in the URL
• Override by telling the orchestrator: "This is a client repo" or "This is the main repo"

Custom layer bootstrap failed

If composer dump-autoload fails or the custom directory isn't set up right:

• Check composer.json has "Custom\\": "custom/" in the autoload.psr-4 section
• Verify custom/ directory exists
• Run composer dump-autoload manually
• Check application/config/container/modules.php has the custom module entries