Skip to content
M MortelOS

Version 0

MortelOS Agent Standards

MortelOS-owned AI agent instructions for host apps and package-aware development.

mortelos/agent-standards carries reusable AI agent instructions for MortelOS host apps and packages. This page describes version 0.1.19.

This package is a MortelOS-owned hard-fork-style standard. Spatie's AI guidelines and Laravel community conventions are useful references, but MortelOS owns the actual rules that agents receive in AGENTS.md.

Why It Exists

Agent instructions drift when every host app edits its own long prompt. Drift makes agents inconsistent and makes reviews harder.

The standard is packaged so every host app can install one reusable source of truth, then merge it into the root AGENTS.md with mortelos/dev-tools. The rules live in the package at resources/mortelos/agent-rules/AGENTS.md.

Install In A Host App

composer require mortelos/agent-standards --dev
composer require mortelos/dev-tools --dev

Packages resolve from the MortelOS registry. Configure registry access once before installing; see Installation.

The package needs PHP 8.4 and illuminate/support 13. The service provider is auto-discovered.

Host apps should publish package rules after Composer updates:

{
  "scripts": {
    "post-autoload-dump": [
      "@php artisan package:discover --ansi",
      "@php artisan mortelos:agent-rules:publish --target=AGENTS.md --no-interaction"
    ]
  }
}

Then publish or check manually when needed:

php artisan mortelos:agent-rules:publish --target=AGENTS.md --no-interaction
php artisan mortelos:agent-rules:check --target=AGENTS.md --no-interaction

To keep a plain copy of the rules in the host, publish them with the package tag. This writes resources/mortelos/agent-rules/agent-standards.md:

php artisan vendor:publish --tag=mortelos-agent-standards-rules

Loading The Rules In Claude Code

Claude Code reads CLAUDE.md, not AGENTS.md, when both exist.

  • In a host app, keep the generated block in AGENTS.md and put @AGENTS.md in CLAUDE.md.
  • In a package, require mortelos/agent-standards as a dev dependency from the MortelOS registry, not as a symlinked path repository. Then put this line in the package CLAUDE.md:
@vendor/mortelos/agent-standards/resources/mortelos/agent-rules/AGENTS.md

An agent that works in a package from a parent directory loads that CLAUDE.md when it opens a file in the package with the Read tool.

What It Covers

Area Rule family
Working method Read repo instructions, check the registry for a package before building a capability, keep work scoped, verify before reporting completion.
Outlets first Use declared outlets before changing a package. Declare new public surfaces in the outlet manifest.
Laravel and PHP Strict types, typed values, immutable dates and strict models. Put writes in authorized Actions.
Host state and events Store auditable facts through aggregates and events. Rebuild read tables through projectors. Return Action results with undo where possible.
TALL and UI Kit first: build UI only from x-mortel:: components, picked from the decision table in vendor/mortelos/ui/COMPONENTS.md and its recipes. Never write flux: directly or raw form controls and tables. No UI components of your own, except application components under the kit's rules. Ask mortelos/ui for a missing generic piece. Colours come from the theme tokens.
Livewire 4 Use single-file components, islands, stable loop keys and scoped state. Follow the loading, polling and navigation rules.
Verify UI changes Run the guards and screen browser tests. Check request counts, layout shifts and console output, and include screenshots. Name skipped browser checks when the repo has no browser job.
Security Validate and authorize at boundaries, guard tenant scope and explicit membership, fake external calls in tests.
Version control and review Keep changes focused and respect dirty worktrees.
External sources and personal data Reuse framework channels, entities and transcript events for personal imports. Keep content private and make purges safe across replays.
Dependency and versioning Use semantic-version tags and registry caret constraints. Commit application lockfiles, keep package lockfiles out of git and wait for tags before upgrading consumers. Ask before adding a new dependency; clear Laravel Vet with bin/vet-agent.
Code language Write code, comments, commits and pull requests in English. Keep Dutch to user-facing copy and the explicit exceptions.
Dutch product copy Plain Dutch prose and no em dashes in Dutch user-facing text.

Host-Specific Rules

Keep tenant-specific instructions outside the generated block in AGENTS.md.

The generated block is owned by mortelos/dev-tools and overwritten by:

php artisan mortelos:agent-rules:publish

Use local host prose only for details that cannot live in a reusable package. If a rule should apply across all OS apps, move it into mortelos/agent-standards.

Code Language

Since 0.1.15 the rules say that all code is English. Dutch is for text a customer sees, with a short list of exceptions. CodeLanguageGuard in mortelos/dev-tools enforces the rule. See Coding guidelines.

Outlets

This package declares no outlets yet; it has no screens or seams a host plugs into.

Boundaries

mortelos/agent-standards is only instruction content. It adds no runtime behaviour: its service provider only registers the publish tag, and only in the console. Pair it with mortelos/dev-tools for publish and check commands, and pair host apps with mortelos/app-standards for Laravel runtime defaults.