From 91cc08614d03aaef6e7444c34890d8f6eeffe86d Mon Sep 17 00:00:00 2001
From: yisroel <tech@bhbsdventures.com>
Date: Wed, 6 May 2026 14:37:39 +0300
Subject: [PATCH] init: agent context files

---
 AGENTS.md              |  7 +++++
 ai/backend-context.md  | 49 ++++++++++++++++++++++++++++++
 ai/frontend-context.md | 36 ++++++++++++++++++++++
 ai/shared.md           | 69 ++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 161 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 ai/backend-context.md
 create mode 100644 ai/frontend-context.md
 create mode 100644 ai/shared.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5dea88b
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,7 @@
+# Project context
+
+Read these on every session. Rules in them override defaults.
+
+@ai/shared.md
+@ai/backend-context.md
+@ai/frontend-context.md
diff --git a/ai/backend-context.md b/ai/backend-context.md
new file mode 100644
index 0000000..3d9201a
--- /dev/null
+++ b/ai/backend-context.md
@@ -0,0 +1,49 @@
+# Backend context
+
+> Read `ai/shared.md` first. This file only covers backend-specific rules.
+
+## Project Context
+
+**Stack:** PHP 8.4, Laravel 12, PHPUnit, Composer.
+**Architecture:** Domain-Driven Design. Code is organized by domain entity into
+Entities, DTOs, Repositories, Use Cases, and Fakes (in-memory repos for tests).
+
+## Code patterns
+
+- Look at similar entities (e.g. `AgendaSlot`, `Event`) for reference
+- Entities: constructor with properties, getters
+- DTOs: simple data containers for creation
+- Repositories: interfaces that define data access
+- Use cases: business logic with Request objects
+  - When throwing exceptions, add `@throws` docblock
+- Fakes: in-memory implementations for testing
+  - Look at `tests/Fakes/` for examples
+  - Find/lookup methods must return a new instance of the entity, not the
+    stored reference
+- Tests: follow existing patterns in `tests/Unit/[Entity]/UseCases/`
+  - In `setUp`, only use fake repositories for entities under test - construct
+    dependency objects directly with `new` (e.g.
+    `new Event(id: 0, slug: 'test')`) instead of creating them through their
+    fake repositories
+
+## PHP rules
+
+- Imports: always put `use` statements at the top of the file, never use inline
+  imports (e.g. `\App\Foo\Bar::class`)
+- Closures: never use arrow functions (`fn () =>`) - always use regular
+  anonymous functions (`function () { return ...; }`)
+- Defaults: never use default values for function or constructor parameters -
+  every argument must be passed explicitly at every call site, including
+  nullable params (write `?Foo $bar` not `?Foo $bar = null`)
+
+## Seeders
+
+- Split `database/seeders/` one file per domain entity (e.g. `UserSeeder`,
+  `StartupUserProfileSeeder`), not one per scenario
+- `DatabaseSeeder` stays as the orchestrator - calls sub-seeders via
+  `$this->call([...])` in dependency order
+- Resolve cross-entity coupling with `findByX` lookups in later seeders
+
+## Pre-commit
+
+Run `composer cs:fix` on worked-on directories before committing.
diff --git a/ai/frontend-context.md b/ai/frontend-context.md
new file mode 100644
index 0000000..0517fc6
--- /dev/null
+++ b/ai/frontend-context.md
@@ -0,0 +1,36 @@
+# Frontend context
+
+> Read `ai/shared.md` first. This file only covers frontend-specific rules.
+
+## Project Context
+
+**Stack:** Vue 3.5 (Composition API, `<script setup lang="ts">`), TypeScript
+strict, Vite 8, Vue Router 5, Pinia 3, vanilla CSS (no framework). Path alias
+`@` → `./src`.
+
+**Design tokens:** Font: Inter/system-sans. Colors: text `#0a0a0a`, secondary
+`#6b6b6b`, border `#e5e5e5`, accent `#0062ff`, bg `#fff`, button `#000` / hover
+`#222`. Inputs/buttons: 36px height, 6px radius, 1px border → black on focus.
+Spacing: 8px base unit.
+
+## Code patterns
+
+- Look at similar components/views for reference before writing anything
+- **Views:** `src/views/PascalCasePage.vue`, register in `src/router/index.ts`
+- **Components:** `src/components/PascalCase.vue`
+- **Stores:** `useXxxStore` with composition style -
+  `defineStore('name', () => { ... return {...} })`
+- **Styling:** `<style scoped>` only, vanilla CSS, reuse design tokens above
+- **TypeScript:** strict mode, no `any`
+- **Testing:** Cypress E2E only, mirror `cypress/e2e/login_page.cy.ts` style
+
+## Pre-commit
+
+Run `npm run format && npm run lint` on worked-on files before committing.
+
+## Note on commit granularity
+
+Frontend changes are often single-file (a new view, a new component), so
+commits will frequently land as one file each. That is a consequence of the
+shared "one logical change per commit" rule, not a separate per-file rule -
+see `shared.md`.
diff --git a/ai/shared.md b/ai/shared.md
new file mode 100644
index 0000000..cab4fa9
--- /dev/null
+++ b/ai/shared.md
@@ -0,0 +1,69 @@
+# Shared rules
+
+Rules that apply to both backend and frontend work in this repo. Stack-specific
+guides (`backend-context.md`, `frontend-context.md`) extend these.
+
+## Process (TDD)
+
+0. Before editing any file, ensure you are on a feature branch
+   (`git status` to confirm). If on master/main, create a branch
+   first.
+1. Write the test first
+2. Run the test to confirm it fails
+3. Commit the failing test (the "tests committed first" rule in
+   action - the test commit precedes the implementation commit, not
+   merely the implementation lines)
+4. Implement the code to make the test pass
+5. Run the test to confirm it passes
+6. Commit the implementation
+7. Repeat for each new behavior
+
+## Code style
+
+- Lines should not exceed 80 columns, but should use up to 80 columns when
+  possible - do not split lines unnecessarily
+- Variable names: use explicit, descriptive names - never single-letter or
+  abbreviated variables (e.g. `$sponsorship` not `$s`, `$event` not `$e`)
+- First, explore the codebase to understand existing patterns - look at similar
+  files for reference before writing anything
+- Never use em dashes (—) in code, comments, or docblocks - use hyphens (-)
+  instead
+
+## Git commit style
+
+- Present tense, imperative mood (add, create, wire, fix, test)
+- Lowercase
+- Short (3-6 words)
+- Match patterns found in git history
+- Do not add any section mentioning claude as a coauthor
+- Add a commit body when the subject alone cannot convey the change - e.g.
+  non-obvious motivation, multi-file coordination, or notable complexity
+- Body: wrap at ~72 columns, separated from subject by a blank line, explain
+  the why and any non-obvious what
+- Skip the body for trivial or self-explanatory commits
+
+## Git commits
+
+- Tests should be committed first, before implementation
+- One logical change per commit - a commit may span multiple files when they
+  form a single logical unit (e.g. a use case with its request and exception,
+  or a component with its store wiring)
+- Keep commits focused: not one file per commit, not unrelated work batched
+- Make commits frequent - commit each meaningful logical step as you go
+- Commits are for reviewing and documenting the development of code
+- When the formatter or linter modifies files outside your intended
+  change, either `git restore` them or land them as a separate
+  `format <area>` / `lint <area>` commit - never bundle drive-by
+  formatter churn into a feature commit
+- If pre-commit lint fails on code you did not touch, do not bundle
+  the fix - either land the unrelated fix as its own commit first, or
+  note the pre-existing failure and proceed
+
+## Branching
+
+- Use kebab-case (e.g. `presenting-track`, `agenda-slots`, `auth-store`)
+- Use descriptive feature names
+- Or use type/description: `feature/presenting-track`, `fix/bug-name`
+- NEVER work directly on master/main - always create and work on a branch
+
+Do not push anything. Make commits as you go.