Adapting Conventions

The boilerplate's AI context system is agent-agnostic at its core. Convention documents are plain Markdown files. Workplans are structured Markdown. Skills follow a simple frontmatter-plus-content format. Any AI agent that can read files can use them.

This page shows how to translate the Claude Code-native patterns to Codex, Cursor, Copilot, or any other agent — and when each agent surface provides a better fit.

Mapping CLAUDE.md to AGENTS.md

The two configuration systems serve the same purpose — project context for AI agents — but differ in structure and loading mechanism:

The key architectural difference: CLAUDE.md files are self-contained — they inline the rules directly. AGENTS.md files are referential — they point to the same convention documents but do not repeat their content. This makes AGENTS.md files shorter but requires the agent to actually read the referenced documents.

The "Read Before Coding" Pattern

Every AGENTS.md file includes a "Read Before Coding" section that lists the convention documents the agent must read before writing any code. This is the Codex equivalent of Claude Code's automatic per-directory context loading.

Backend example:

## 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
- Relevant workplan or WU in `backend/docs/milestones/` when the task is work-unit driven

Frontend example:

## Read Before Coding

- `frontend/CLAUDE.md` for Docker and frontend-specific rules
- `docs/architecture/frontend/ARCHITECTURE.md`
- `frontend/docs/architecture/TEMPLATES.md`
- `docs/api/CONTRACTS.md`
- `docs/api/ENDPOINTS.md`
- `docs/billing/BILLING.md` for checkout, plans, subscriptions, invoices, taxes, or currency flows
- Relevant workplan or WU in `frontend/docs/milestones/` when the task is work-unit driven

The pattern is deliberate: every agent session starts by reading the relevant convention documents, ensuring it has the same context regardless of which agent is being used. The agent does not guess at conventions — it reads them from the project files.

Skill Mapping: Claude Code to Codex

Claude Code ships 15 skills in .claude/skills/. Codex ships 11 skills in .agents/skills/. The mapping is not one-to-one — Codex consolidates some Claude Code skills into broader implementation skills and adds unique skills for orientation and documentation sync.

Execution Templates

Codex includes two structured templates for complex work that goes beyond a single-session task.

The Execution Plan Template

Located at docs/codex/EXECUTION-PLAN-TEMPLATE.md, this template is for complex tasks that span backend and frontend, change API contracts, touch billing, or continue an existing milestone.

The template structure:

## Header
- Task, Date, Owner, Related issue or workplan, Domains touched

## Goal
Short paragraph describing the end state, not implementation details.

## Source Of Truth
- Docs, existing code entry points, relevant routes/resources/composables/tests

## Constraints And Invariants
- tenancy, API contract, billing, i18n, performance or rollout

## Open Questions Or Blockers
- Question, blocking impact, resolution owner
- Stop implementation until blockers are resolved if they affect
  contracts, billing invariants, or tenant isolation.

## Work Units
| WU | Scope | Depends on | Files | Validation |

## WU Detail (per WU)
- Status, Goal, Files expected, Implementation notes
- Acceptance criteria (checkboxes)
- Validation commands
- Doc sync requirements
- Risks

## Final Verification
- Targeted automated checks, broader checks, manual verification

## Handoff Notes
- Residual risks, follow-ups, docs updated

Use this template when a task touches multiple areas or when you need to coordinate between team members. It creates a clear plan before any code is written.

The Feature Discovery Workplan

Located at docs/codex/DISCOVER-FEATURE-WORKPLAN.md, this process is for when you have a feature idea that is not yet decomposed into Work Units. The discover-feature-workplan skill drives this flow.

The process:

1. The skill asks you short sequential questions about the feature
2. It skips irrelevant questions when the answer is already clear
3. It produces a short synthesis for your confirmation
4. It writes an implementation-ready workplan
5. Optionally bootstraps a matching tracking file for implement-wu handoff

Starting prompt:

Use discover-feature-workplan.
Ask me one question at a time in English.
Stop when you have enough information, then show me a short synthesis
before generating the workplan.

The output is a docs/workplans/WORKPLAN-{ID}.md file plus an optional docs/workplans/CURRENT-{ID}-WU.md tracking file — ready for immediate /implement-wu execution.

Recommended Workflows

The canonical Codex usage guide defines four standard workflows. Each maps to a specific combination of agents and skills.

New Feature (Not Yet Decomposed)

1. Use the discover-feature-workplan skill
2. Answer the sequential discovery questions
3. Confirm the synthesis before the workplan is generated
4. The skill outputs a workplan file and optional tracking file
5. Use implement-wu to execute each Work Unit in order

This is the full cycle: ideation to structured execution.

Small Backend or Frontend Change

1. Read the local AGENTS.md for the area you are changing
2. Use backend-implementation or frontend-implementation skill
3. Run targeted validation (tests, lint, type checks)
4. Use docs-sync if the change touched contracts or behavior

This is the most common workflow — a single-session, focused change.

Existing WU or Milestone Slice

1. Use implement-wu
2. Read the tracking file and the milestone workplan first
3. Present the plan and wait for approval before editing
4. Implement, run quality gate, update tracking

This is the structured workflow for executing a specific Work Unit from an existing workplan. For the full five-phase process, see Workplan Execution.

Review or Handoff

1. Use the reviewer agent or reviewer skill
2. Report findings first, ordered by severity
3. Call out residual risks and skipped checks explicitly
4. If no findings remain, state that explicitly

The reviewer agent has sandbox_mode = "read-only" — it cannot accidentally modify code during review.

Git Hooks and Quality Gates

The project ships repo-managed git hooks that enforce formatting regardless of which agent or developer commits the code.

Pre-Commit Hook

.githooks/pre-commit → scripts/pre-commit.sh → scripts/format-file.sh

The pre-commit hook:

1. Collects all staged files (git diff --cached --name-only)
2. Filters for supported file types: backend/*.php, frontend/*.{js,cjs,mjs,ts,cts,mts,vue}
3. Rejects partially staged files — if a file has unstaged changes, the hook stops and asks you to stage the full file or stash the unstaged changes
4. Runs scripts/format-file.sh on all supported staged files
5. Re-stages the formatted files

is_supported_target() {
    case "$1" in
        backend/*.php|frontend/*.js|frontend/*.cjs|frontend/*.mjs|\
        frontend/*.ts|frontend/*.cts|frontend/*.mts|frontend/*.vue)
            return 0 ;;
        *) return 1 ;;
    esac
}

Install the hooks with:

make hooks

This is run automatically on make install for new setups.

Quality Gate Commands

Every implementation skill references the same validation commands:

# Code formatting
docker compose exec php vendor/bin/pint --dirty

# Static analysis (PHPStan level 9)
docker compose exec php vendor/bin/phpstan analyse --memory-limit=1G

# Targeted tests
docker compose exec php php artisan test --compact --filter=<Name>

# Linting
docker compose exec node pnpm lint

# Type checking (TypeScript strict)
docker compose exec node pnpm typecheck

# Targeted tests
docker compose exec node pnpm test:run <path-or-pattern>

# Build verification (when SSR/routing/plugins changed)
docker compose exec node pnpm build

The make check command runs all quality gates for both stacks at once — useful for CI and pre-merge verification.

Adapting for Other Agents

The convention documents are plain Markdown. Any AI agent that can read files can use them. Here is how to adapt the system for other agents.

Cursor

Cursor supports project-level rules via .cursorrules or its Rules feature:

1. Create a .cursorrules file at the project root
2. Paste the content of the root CLAUDE.md or AGENTS.md as the base context
3. For domain-specific work, include the relevant skill content in your prompt
4. Convention documents can be added as workspace context files
5. Workplans work as structured prompts in Cursor's chat

GitHub Copilot

Copilot supports project instructions via .github/copilot-instructions.md:

1. Create .github/copilot-instructions.md
2. Include essential conventions from the root CLAUDE.md — project structure, domain entities, critical rules
3. Reference convention documents in your chat prompts when working on specific domains
4. The workplan format works as structured chat input

Generic Adaptation Pattern

For any AI agent:

1. Find your agent's project-level context file — most modern agents have one (.cursorrules, copilot-instructions.md, system prompts, etc.)
2. Include the root context — copy the root CLAUDE.md or AGENTS.md content into it
3. Load domain skills on demand — when working on billing, include the billing skill content in your prompt. When working on frontend, include the frontend implementation skill.
4. Use workplans for complex tasks — the workplan Markdown format is agent-agnostic. Any agent that can follow structured instructions can execute a workplan.
5. Reference convention documents directly — the API Contracts, Backend Templates, Frontend Templates, Query Builder Guide, and Domain Glossary are all plain Markdown files that any agent can read

What's Next

• Convention Files — The six convention documents that keep AI output consistent across all agents
• Setup and Configuration — The Codex configuration surface in detail
• Skills System — Claude Code's 15 skills for comparison
• Workplan Execution — The full workplan and Work Unit execution pattern