Setup and Configuration

SaaS4Builders ships a complete Codex configuration alongside its Claude Code setup. While CLAUDE.md files provide context for Claude Code, the Codex surface uses AGENTS.md files, TOML-configured agents, and a parallel skills directory. Both systems reference the same underlying convention documents, so AI output stays consistent regardless of which agent you use.

This page covers the Codex-specific configuration surface. For Claude Code, see the Claude Code section.

The AGENTS.md Hierarchy

The project ships four AGENTS.md files at strategic locations. Each file provides scoped guidance for Codex agents working in that part of the codebase.

Root AGENTS.md

The root file is a routing table. It directs the agent to the right local file and lists every source-of-truth document in the project:

## Start Here

- Backend or API work: `backend/AGENTS.md`
- Frontend or Nuxt work: `frontend/AGENTS.md`
- Specs, workplans, docs, or migration notes: `docs/AGENTS.md`
- Billing anywhere in the repo: read `docs/billing/BILLING.md` first

It also defines the standard workflow that every agent follows:

1. Load the closest AGENTS.md plus the canonical docs for the area
2. For complex work, start from the Execution Plan Template or use implement-wu
3. Implement the smallest coherent slice
4. Run targeted validation before broad checks
5. Sync canonical docs when behavior, contracts, or architecture changed

The global rules section enforces consistency: do not invent undocumented endpoints, do not duplicate canonical docs, follow code plus the canonical doc when docs drift.

backend/AGENTS.md

The backend file covers Laravel-specific conventions:

"Read Before Coding" — A list of documents the agent must read before writing any code:

## Read Before Coding

- `backend/CLAUDE.md` for Docker and Laravel Boost specifics
- `docs/api/CONTRACTS.md`
- `docs/api/ENDPOINTS.md`
- `docs/architecture/backend/ARCHITECTURE.md`
- `backend/docs/architecture/TEMPLATES.md`
- `docs/billing/BILLING.md` and `docs/billing/CURRENCY-RULES.md` before any billing change

Architecture — The request flow that every endpoint follows:

Request → toDto() → Action or Query → Resource → Response

Critical guardrails — Rules the agent must not break:

• Do not add undocumented endpoints or response shapes
• Do not put QueryBuilder in Controllers or Actions
• Tenant-scoped resources require isolation coverage
• Billing changes must preserve Stripe authority, webhook-driven lifecycle, currency immutability

Validation commands — The exact docker compose exec commands to run for formatting, static analysis, and tests.

frontend/AGENTS.md

The frontend file covers Nuxt-specific patterns:

Architecture facts:

• Shared code lives in frontend/common/
• Layer rule: product -> core/foundation/common, core -> foundation/common, foundation -> common
• Feature internals stay private; import public APIs through index.ts

Data and API rules:

• Authenticated data fetching uses useAuthenticatedAsyncData()
• Feature composables do not call $fetch or useFetch directly — go through a feature API module and useApiClient()
• Backend payloads are snake_case; useApiClient() transforms them to camelCase before Zod parsing

UI and i18n rules:

• All user-facing text in 4 locales: en, fr, es, it
• Reuse existing Nuxt UI patterns

docs/AGENTS.md

The documentation file covers canonical doc management:

• Maps change types to their canonical document (API surface changes go to the contracts file, billing changes go to the billing doc, architecture decisions go to the decision log)
• Documentation rules: update the canonical doc, don't create parallel summaries, reference existing docs instead of restating them
• Workplan rules: complex work starts from the Execution Plan Template, use implement-wu for existing WUs

Custom Agents

The project ships three pre-configured agents in .codex/agents/. Each agent has a specific scope, reasoning level, and set of instructions that keep it focused on its area.

Agent Configuration Format

Codex agents are defined as TOML files with the following structure:

backend-dev Agent

The backend agent owns all Laravel API work. It reads the backend AGENTS.md and convention documents before editing, follows the thin-controller architecture, and runs targeted validation after changes.

name = "backend-dev"
description = "Backend-only Laravel agent for API endpoints, Actions, Queries, DTOs, policies, billing, tenancy, and backend validation."
model_reasoning_effort = "medium"
nickname_candidates = ["Forge", "Query", "Ledger"]
developer_instructions = """
Own backend work only.

Scope:
- Modify backend files freely when the task requires it.
- Modify root docs, AGENTS, scripts, or repo config only when they are a direct backend dependency.
- Do not modify frontend files. If the task needs frontend work, report the required follow-up instead of editing frontend code.

Before editing:
- Read backend/AGENTS.md.
- Read docs/api/CONTRACTS.md and docs/api/ENDPOINTS.md for endpoint or payload work.
- Read docs/architecture/backend/ARCHITECTURE.md.
- Read docs/billing/BILLING.md for any billing-related change.
- Load the project skills backend-implementation, billing-guardrails, and api-contracts when relevant.

Execution rules:
- Keep controllers thin.
- Follow Request -> DTO -> Action or Query -> Resource.
- Do not invent undocumented endpoints or response shapes.
- Do not bypass tenancy, billing, or webhook guardrails.

Validation:
- Prefer targeted backend checks first.
- Run:
  - docker compose exec php php artisan test --compact --filter=<Name>
  - docker compose exec php vendor/bin/pint --dirty
  - docker compose exec php vendor/bin/phpstan analyse --memory-limit=1G
- Escalate to broader checks only when the scope justifies it.

Handoff:
- Call out residual risks.
- Call out doc sync requirements.
- Call out any frontend follow-up instead of implementing it yourself.
"""

Key design decisions: the agent is scoped to backend files only. If a task requires frontend changes, it reports the follow-up instead of editing frontend code. This prevents cross-stack mistakes.

frontend-dev Agent

The frontend agent owns all Nuxt work. It respects layer boundaries, routes data through feature API modules, and hands off backend or doc changes.

name = "frontend-dev"
description = "Frontend-only Nuxt agent for pages, composables, feature APIs, Zod schemas, i18n, and targeted frontend validation."
model_reasoning_effort = "medium"
nickname_candidates = ["Canvas", "Schema", "Pulse"]
developer_instructions = """
Own frontend work only.

Scope:
- Modify frontend files only.
- Do not modify backend or docs files. If the task needs backend or doc changes, report the required follow-up instead of editing them.

Before editing:
- Read frontend/AGENTS.md.
- Read docs/api/CONTRACTS.md and docs/api/ENDPOINTS.md for API-dependent work.
- Read docs/architecture/frontend/ARCHITECTURE.md.
- Read docs/billing/BILLING.md for billing UI, checkout, invoices, or currency work.
- Load the project skills frontend-implementation and api-contracts, plus billing-guardrails when relevant.

Execution rules:
- Respect layer boundaries.
- Route data through feature API modules and useApiClient().
- Use useAuthenticatedAsyncData() for authenticated feature fetches.
- Do not invent backend behavior or undocumented endpoints.

Validation:
- Prefer targeted frontend checks first.
- Run:
  - docker compose exec node pnpm test:run <path-or-pattern>
  - docker compose exec node pnpm lint
  - docker compose exec node pnpm typecheck
- Run docker compose exec node pnpm build when SSR, routing, plugins, or rendering changed.

Handoff:
- Call out residual risks.
- Call out backend or docs follow-up instead of implementing it yourself.
"""

reviewer Agent

The reviewer is a read-only agent. It cannot modify files — it can only analyze code and produce structured review reports.

name = "reviewer"
description = "Read-only reviewer focused on correctness, contracts, billing, tenancy, architecture, and missing test coverage."
model_reasoning_effort = "high"
sandbox_mode = "read-only"
nickname_candidates = ["Atlas", "Delta", "Echo"]
developer_instructions = """
Review code like an owner and stay read-only.

Before reviewing:
- Read the closest AGENTS.md files for the scope.
- Read docs/api/CONTRACTS.md and docs/api/ENDPOINTS.md for API-related work.
- Read docs/billing/BILLING.md for billing changes.
- Load the project reviewer skill.

Review priorities:
- correctness and behavioral regressions
- contract drift
- billing invariants
- tenant isolation and auth boundaries
- missing or weak tests
- layer-boundary violations

Output rules:
- Lead with findings, ordered by severity.
- Use red, yellow, and green markers.
- Cite exact files or areas when possible.
- Avoid style-only comments unless they hide a real bug.
- If no findings remain, state that explicitly and list residual risks or skipped checks.

Do not modify files.
"""

Notice two key differences: sandbox_mode = "read-only" prevents any file modifications, and model_reasoning_effort = "high" gives the agent more time to think through complex review scenarios.

Agent Summary

Project Skills

The project ships 11 skills for Codex agents in .agents/skills/. These provide focused domain knowledge and workflows, similar to the Claude Code skills in .claude/skills/.

Where Skills Live

.agents/skills/
├── api-contracts/SKILL.md
├── backend-implementation/SKILL.md
├── billing-guardrails/SKILL.md
├── discover-feature-workplan/SKILL.md
│   ├── references/
│   │   ├── question-flow.md
│   │   ├── tool-variant.md
│   │   └── example-feature-to-workplan.md
│   └── assets/
│       ├── feature-synthesis-template.md
│       ├── workplan-template.md
│       └── current-wu-template.md
├── docs-sync/SKILL.md
├── frontend-implementation/SKILL.md
├── implement-wu/SKILL.md
├── repo-orientation/SKILL.md
├── review-validation/SKILL.md
├── reviewer/SKILL.md
└── workplan-execution/SKILL.md

Skill Inventory

Skill Format

Each skill is a SKILL.md file with YAML frontmatter and structured Markdown:

---
name: backend-implementation
description: Implement or modify Laravel backend features in SaaS4Builders. Use for
  Actions, Queries, DTOs, Requests, Resources, routes, migrations, policies,
  tenant-scoped models, and backend API endpoints.
---

The body follows a consistent pattern:

• Read First — Documents the agent must read before starting
• Default Flow — Step-by-step workflow for the task
• Guardrails — Rules the agent must not break
• Validation — Commands to run after implementation
• Related Skills — Other skills to load when the scope expands

MCP Server Configuration

The backend includes a Model Context Protocol (MCP) server configuration that gives agents direct access to Laravel tooling:

[mcp_servers.laravel-boost]
command = "php"
args = ["artisan", "boost:mcp"]
cwd = "/path/to/project/backend"

This connects the agent to Laravel Boost, which provides tools like tinker, database queries, schema inspection, and documentation search — all within the agent's context. The cwd is set to the backend directory so Artisan commands execute in the right location.

Key Differences from Claude Code

Both agent systems work with the same project conventions. The difference is how they access and load that context:

What's Next

• Adapting Conventions — How to map Claude Code patterns to Codex and other agents
• Convention Files — The six convention documents that keep AI output consistent
• CLAUDE.md Configuration — The Claude Code equivalent for comparison
• Skills System — Claude Code's 15 skills in detail