Imported from robinbeier/forscherhaus-appointments (AGENTS.md). Install upstream with npx skills add robinbeier/forscherhaus-appointments. Copyright stays with the author.

AGENTS.md - Forscherhaus Appointments

Purpose: durable repo instructions for Codex. Keep this file short; long or topic-specific details belong in canonical docs.

Canonical Sources

• README.md: onboarding, local setup, services, shortest operator path.
• WORKFLOW.md: agent runtime, Linear states, Codex Workpad, and ticket-to-merge flow.
• SECURITY.md: security boundaries, required properties, and evidence limits.
• code_review.md: canonical review priorities, findings format, and repo-specific review checks.
• docs/agent-harness-index.md: routing across CI, architecture, ownership, and specialist docs.
• .github/workflows/ci.yml: source of truth for CI triggers, blocking status, and artifacts.

Hard Rules

• Keep production code in application/.
• Do not edit system/ unless applying an explicit upstream patch.
• Use CodeIgniter migrations for DB schema changes, including rollback.
• Never commit secrets or local credentials; keep config.php local.
• Caller-supplied flags, IDs, hashes, tokens, or paths never create public update authority; verify authority server-side and fail closed before any mutation. Keep the detailed contract in docs/ci-write-contracts.md.
• Treat services.attendants_number as fixed to 1 unless product scope changes explicitly.
• If docs/maps/component_ownership_map.json marks a component as single-owner or manual_approval_required, keep changes narrow and conservative.
• Prefer small, mergeable, low-risk diffs over broad rewrites, speculative cleanup, or wide refactors.
• Parallel work means disjoint local implementation only: use a common verified base, separate worktrees, at most two writer lanes, and one primary external single writer. Integration and landing remain serial; see WORKFLOW.md.
• Delegate concrete, bounded, independently verifiable implementation, test, and documentation slices to the registered implementation_worker contract by default. The primary agent retains architecture, integration, review, Git, Linear, merge, and production authority; WORKFLOW.md is canonical for runtime and model details.

Review Default

• Use one independent read-only reviewer with enough code context; add a specialist when the actual risk warrants one. Follow code_review.md.
• Standard review and PR creation do not require a separate CLI login or bootstrap. Keep current blocking CI and reviewed-head checks; WORKFLOW.md defines landing and authorization.

Default Path

Start here for most review-ready changes:

./scripts/setup-worktree.sh
PRE_PR_RUN_COVERAGE=1 bash ./scripts/ci/pre_pr_full.sh

The full gate includes the Composer test through its quick-gate stage.

Faster local gate:

bash ./scripts/ci/pre_pr_quick.sh

Topic Routing

• Docker stack, local services, dump restore, PDF renderer, LDAP: docs/docker.md
• Console commands: docs/console.md
• Write-path contracts: docs/ci-write-contracts.md
• Defense Factory cycles and evidence handoffs: docs/defense-factory.md
• Release gates: docs/release-gate-dashboard.md, docs/release-gate-booking-confirmation-pdf.md, docs/release-gate-provider-ui-smoke.md, docs/release-gate-customers-ui-smoke.md, docs/release-gate-zero-surprise.md
• Observability and ops monitors: docs/observability.md, scripts/ops/README.md
• Production SSH operations harness: docs/ops/agent-operations.md
• Architecture and ownership: docs/architecture-map.md, docs/ownership-map.md, docs/maps/component_ownership_map.json

Working Defaults

• composer test may create config.php from config-sample.php if missing.
• DB_HOST='mysql' is the Docker-default path; host-side PHP needs host-compatible DB config.
• With host PHP and Docker PDF renderer, set PDF_RENDERER_URL=http://localhost:3003.
• Use a unique Docker Compose project name per worktree.
• For standalone checks in temporary worktrees, use bash scripts/ci/run_focused_test.sh SERVICE COMMAND [ARG ...] (php-fpm or pdf-renderer, no dependencies); it owns and cleans its temporary project. Use the full gate for database-dependent tests.
• Prefer bash scripts/ci/run_focused_test.sh php-fpm composer deptrac:analyze over host composer deptrac:analyze. Raw docker compose run --rm removes its container, not its network.
• Hook setup and refresh: see the README hook note.
• bash ./scripts/ci/pre_pr_full.sh enables LDAP guardrails only when LDAP/runtime paths changed; override explicitly via PRE_PR_INCLUDE_LDAP_GUARDRAIL=1 or 0.
• On cold local Docker stacks, bash ./scripts/ci/pre_pr_full.sh may need longer Playwright startup via PRE_PR_INTEGRATION_SMOKE_BROWSER_BOOTSTRAP_TIMEOUT=600 and PRE_PR_INTEGRATION_SMOKE_BROWSER_OPEN_TIMEOUT=60.
• For deterministic LDAP fixtures, run bash ./scripts/ldap/reset_directory.sh and bash ./scripts/ldap/smoke.sh.
• For local production dump restore, run bash ./scripts/import_prod_backup.sh (or append --core-services-only to keep only mysql/php-fpm/nginx running).
• For conservative local cleanup, run bash ./scripts/cleanup_local_artifacts.sh; append --with-deps only when you also want to remove reproducible dependency directories.

Validation Expectations

• Before review, follow the behavior-based local validation decision in WORKFLOW.md; the highest-risk applicable rule wins for mixed changes.
• Bei Bugfixes nach Moeglichkeit einen passenden Regressionstest ergaenzen.
• Update docs when setup, behavior, validation expectations, or routing change.
• CI truth lives in .github/workflows/ci.yml; do not duplicate long job lists here.
• If a validation flow needs detailed repro steps, keep them in the topic doc and link from here.

PR Expectations

• Keep commits short, imperative, and scoped.
• Publish, integrate, and land multi-PR work sequentially even when explicitly approved disjoint implementation lanes run locally in parallel.
• Link infrastructure PRs to Linear only when they truly belong to that issue.
• For UI-visible changes, update supporting docs or evidence when the repo workflow expects it.

Agent Notes

• WORKFLOW.md is the canonical source for Linear states, publish/merge flow, and Codex Workpad behavior.
• README.md stays operator-first.
• code_review.md defines the durable review rubric for /review and normal Codex turns.
• docs/agent-harness-index.md stays the routing map.
• Use nested AGENTS.md files only when a subtree genuinely needs stricter local rules than the repo root.

Harness Guardrails

• Keep references between README.md, WORKFLOW.md, AGENTS.md, and docs/agent-harness-index.md intact.
• When CI truth changes, update .github/workflows/ci.yml first and then only the shortest necessary summaries here.
• Do not remove the docs/agent-harness-index.md reference from this file.
• Do not turn this file back into a duplicate command matrix or CI explainer.

Anti-Drift Rule

Keep this file as a compact operating contract. If a section turns into a long checklist, command matrix, troubleshooting guide, or CI explainer, move that detail into the canonical topic doc and leave only a short summary plus link here.