feat(agentic): vendor-neutral agentic coding framework

.github/workflows/agent-map-check.yml

@@ -0,0 +1,29 @@
+name: agent-map-check
+
+# Verifies that links inside the agentic framework (AGENTS.md, CLAUDE.md,
+# agentic/** ) still resolve. Catches drift when docs or repo structure
+# move. Markdown-link based; cheap to run.
+
+on:
+  pull_request:
+    paths:
+      - "AGENTS.md"
+      - "CLAUDE.md"
+      - "agentic/**"
+      - "docs/architecture/**"
+      - "docs/capabilities/**"
+      - "docs/getting-started/**"
+      - "docs/principles/**"
+      - ".agents/SITEMAP.md"
+      - ".github/workflows/agent-map-check.yml"
+      - "scripts/check-agent-map.sh"
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Verify agentic framework links
+        run: bash scripts/check-agent-map.sh

.github/workflows/license-headers-check.yml

@@ -0,0 +1,26 @@
+name: license-headers-check
+
+# Verifies that .js/.ts/.tsx source files CHANGED in a PR carry the repo's
+# Eclipse/MIT SPDX header. Checks only changed files so pre-existing header
+# debt doesn't block PRs.
+
+on:
+  pull_request:
+    paths:
+      - "backend/**/*.js"
+      - "frontend/**/*.ts"
+      - "frontend/**/*.tsx"
+      - "scripts/check-license-headers.sh"
+      - ".github/workflows/license-headers-check.yml"
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Verify changed source files carry the MIT SPDX header
+        run: bash scripts/check-license-headers.sh "${{ github.event.pull_request.base.sha || 'origin/main' }}"

AGENTS.md

@@ -0,0 +1,75 @@
+# AGENTS.md — AutoWRX
+
+> Vendor-neutral entry point for any AI coding agent (Claude Code, opencode, openclaw, …). Read this first.
+
+AutoWRX is a cloud-based rapid-prototyping environment for software-defined vehicle (SDV) apps. Stack: **Node.js/Express + MongoDB** backend, **React + Vite + TypeScript** frontend, **Playwright** E2E, **Docker Compose** deploy.
+
+## Start here (always load)
+
+- **Rules (must/must-not):** [`agentic/RULES.md`](./agentic/RULES.md)
+- **Conventions:** [`agentic/CONVENTIONS.md`](./agentic/CONVENTIONS.md)
+
+Key rules in one line:
+- Commit with **your own ECA-signed identity** — every contributor uses their own GitHub/email account (the one they signed the ECA with). `git commit -s`.
+- Never commit on `main`. PRs target `main`. Never commit secrets (`.env*`).
+- Don't push/deploy unless explicitly asked. Run tests before declaring done. Self-review every diff.
+
+## Understand the repo (before real work)
+
+Don't re-scan the whole repo. Run the **`understand-the-repo`** skill: load [`agentic/map/INDEX.md`](./agentic/map/INDEX.md) + [`agentic/memory/MEMORY.md`](./agentic/memory/MEMORY.md), then deep-read only the module you'll touch.
+
+Existing knowledge to lean on (do not duplicate):
+- Architecture deep-dive → [`docs/architecture/`](./docs/architecture/)
+- Capability catalog (code-grounded spec) → [`docs/capabilities/`](./docs/capabilities/)
+- Pages & feature coverage → [`.agents/SITEMAP.md`](./.agents/SITEMAP.md)
+- Getting started / local dev / contributing → [`docs/getting-started/`](./docs/getting-started/)
+- Design principles → [`docs/principles/principle.md`](./docs/principles/principle.md)
+
+## Skills (load on demand, by task)
+
+Indexed in [`agentic/skills/README.md`](./agentic/skills/README.md). The core flow:
+
+- [`understand-the-repo`](./agentic/skills/understand-the-repo.md) — orient cheaply (map + memory).
+- [`implement-feature`](./agentic/skills/implement-feature.md) — branch → understand → implement → test → review → commit → PR.
+- [`run-tests`](./agentic/skills/run-tests.md) — Jest (backend) + Playwright (`.agents/`).
+- [`code-review`](./agentic/skills/code-review.md) — self-review before commit.
+- [`security-review`](./agentic/skills/security-review.md) — for auth/data/runtime/plugin changes.
+- [`license-check`](./agentic/skills/license-check.md) — Eclipse/MIT headers + no incompatible-license code (for new/changed `.js`/`.ts`/`.tsx` or deps).
+- [`commit-and-pr`](./agentic/skills/commit-and-pr.md) — ECA, sign-off, PR template.
+- [`deploy`](./agentic/skills/deploy.md) — `instance-setup/` Docker Compose.
+- [`docs-update`](./agentic/skills/docs-update.md) — keep map/capabilities in sync with code.
+- [`learn-and-update`](./agentic/skills/learn-and-update.md) — capture best practices/trends/lessons.
+
+**Also available** (load when the task fits) — full list in [`agentic/skills/README.md`](./agentic/skills/README.md):
+[`debug`](./agentic/skills/debug.md), [`find-race-conditions`](./agentic/skills/find-race-conditions.md), [`add-endpoint`](./agentic/skills/add-endpoint.md), [`add-frontend-feature`](./agentic/skills/add-frontend-feature.md), [`db-schema-change`](./agentic/skills/db-schema-change.md), [`realtime-event`](./agentic/skills/realtime-event.md), [`add-test`](./agentic/skills/add-test.md), [`performance-review`](./agentic/skills/performance-review.md), [`dependency-upgrade`](./agentic/skills/dependency-upgrade.md), [`troubleshoot-deploy`](./agentic/skills/troubleshoot-deploy.md), [`coder-workspace`](./agentic/skills/coder-workspace.md), [`plugin-authoring`](./agentic/skills/plugin-authoring.md), [`secrets-incident`](./agentic/skills/secrets-incident.md).
+
+## Quick commands
+
+```bash
+# Backend
+cd backend && npm install && npm run dev          # dev server
+cd backend && npm test                             # Jest
+cd backend && npm run lint && npm run prettier     # lint/format
+
+# Frontend
+cd frontend && npm install && npm run dev          # Vite on :3210
+cd frontend && npm run build                       # tsc + vite build
+cd frontend && npm run lint                        # ESLint --max-warnings 0
+
+# E2E
+cd .agents && npm install && npx playwright install chromium
+cd .agents && npx playwright test                  # all specs
+
+# Deploy (instance)
+cd instance-setup && ./up.sh                       # docker compose up -d (needs .env.prod)
+```
+
+## Memory & learning
+
+- Repo-resident facts: [`agentic/memory/`](./agentic/memory/) (with `MEMORY.md` index).
+- Continuous learning: [`agentic/learning/`](./agentic/learning/). Propose updates via PR; never auto-apply to rules.
+
+## Adapters
+
+- **Claude Code:** [`CLAUDE.md`](./CLAUDE.md) imports this file via `@path` (e.g. `@AGENTS.md`). See [`agentic/SETUP.md`](./agentic/SETUP.md) to enable native skill invocation.
+- **opencode / openclaw / others:** you're reading the canonical entry. Point your tool at `AGENTS.md`.

CLAUDE.md

@@ -0,0 +1,19 @@
+# CLAUDE.md — AutoWRX (Claude Code adapter)
+
+This is a thin adapter. The canonical agent rules live in vendor-neutral files and are imported below (Claude Code `@path` syntax — they expand at launch). Do not duplicate rules here.
+
+@AGENTS.md
+@agentic/RULES.md
+@agentic/CONVENTIONS.md
+
+## Claude Code specifics
+
+- **Skills:** the repo's skill playbooks are markdown in [`agentic/skills/`](./agentic/skills/). To invoke them via Claude Code's Skill tool natively, symlink them into `.claude/skills/` (see [`agentic/SETUP.md`](./agentic/SETUP.md)). Otherwise, load the matching skill file directly when a task fits.
+- **Memory:** Claude Code's default memory is user-local (`~/.claude/...`). For this repo, prefer the **repo-resident** memory in [`agentic/memory/`](./agentic/memory/) so knowledge is shared across tools/machines and reviewable in PRs. Use user-local memory only for personal preferences.
+- **Git identity:** commit with **your own** ECA-signed identity — each contributor uses their own account (this user's personal identity lives in user-local memory, not in repo rules). Always `git commit -s`. ECA must be signed.
+- **Plan mode:** for non-trivial implementations, enter plan mode and get sign-off before coding (per Claude Code defaults).
+- **Don't push/deploy unless explicitly asked**; commit only when asked. Each is separate authorization.
+
+## Quick orientation
+
+Read [`AGENTS.md`](./AGENTS.md) → run `understand-the-repo` skill → load the task's skill → follow `implement-feature`.

agentic/CONVENTIONS.md

@@ -0,0 +1,56 @@
+# Conventions
+
+Style and structure conventions for this repo. Load always (imported by `AGENTS.md` / `CLAUDE.md`). These reflect what the codebase already does — match it.
+
+## Branches & commits
+
+- **Branch naming:** `<type>/<short-descriptive>` or `<type>/<issue>-<slug>`. Types: `feat`, `docs`, `fix`, `chore`, `refactor`. Examples: `feat/612-agentic-coding-framework`, `docs/capabilities-improvements`, `fix/project-editor-move-guard`.
+- **Commit message:** imperative summary ≤ ~72 chars; body explains the *why*. End with `Signed-off-by:` (via `git commit -s`) and, for agent-made commits, an attribution trailer — `Co-Authored-By: Claude <noreply@anthropic.com>` when running as Claude Code, or the tool's equivalent; omit if the tool has no such convention.
+- **One logical change per commit** where practical; squashing is done at PR merge, not in commits.
+
+## PRs
+
+- PRs target **`main`**.
+- Title: `<type>(<scope>): <summary>`.
+- Body: **What / Why / How verified**. Note if the change touches security, data, runtime, or plugins. Link the issue (`Closes #nnn` / `Ref #nnn`).
+- The PR pipeline currently runs the **ECA check only**; CI doesn't run tests on PRs, so the agent/author must run tests locally and state how it was verified.
+
+## Backend (`backend/`, Node.js + Express + MongoDB)
+
+- **Layering:** routes → controllers (thin) → services (logic) → models (Mongoose). Keep controllers thin; business logic lives in `services/`. See [`docs/principles/principle.md`](../docs/principles/principle.md).
+- **Routes:** versioned under `routes/v2/`. Match existing grouping (e.g. `routes/v2/user-management/`, `routes/v2/vehicle-data/`).
+- **Auth:** `auth({ optional: (req) => req.authConfig.PUBLIC_VIEWING })` pattern for public-optional reads; writes require auth; resource checks via `checkPermission` (RBAC v1, owner bypass).
+- **Tests:** Jest, colocated or under a tests dir. Run `npm test`. Match existing spec style.
+- **Lint/format:** `npm run lint`, `npm run prettier` (ESLint + Prettier; Husky pre-commit).
+
+## Frontend (`frontend/`, React + Vite + TypeScript)
+
+- **Atomic design:** `components/{atoms,molecules,organisms}`, `pages/`, `layouts/`, `stores/`, `hooks/`. Don't put page logic in atoms.
+- **State:** Zustand stores under `stores/` (`authStore.ts`, …). Permissions via `hooks/usePermissionHook.ts`.
+- **Routing:** `configs/routes.tsx`.
+- **Build/lint:** `npm run build` (`tsc && vite build`), `npm run lint` (ESLint, `--max-warnings 0`). Dev server on port **3210**.
+
+## E2E (`.agents/`, Playwright)
+
+- Specs in `.agents/tests/*.spec.ts`. Run `cd .agents && npx playwright test`.
+- Keep `.agents/SITEMAP.md` coverage status in sync when adding/changing a page feature.
+- Env via `.agents/.env` (gitignored; see `.agents/.env.example`).
+
+## Docs
+
+- All docs under `docs/`; index at [`docs/README.md`](../docs/README.md).
+- **Capability catalog** (`docs/capabilities/`) is **code-grounded**: every endpoint/status/flag claim must match the code. Format per [`docs/capabilities/README.md`](../docs/capabilities/README.md).
+- When code structure changes, update `agentic/map/` pointers and (if a capability changed) `docs/capabilities/`.
+
+## Agent config (this framework)
+
+- Canonical content in `agentic/`. Tool-specific adapters (e.g. `CLAUDE.md`) stay thin and import canonical files via `@path` (e.g. `@AGENTS.md`) — don't duplicate rules into adapters.
+- Memory: one fact per file under `agentic/memory/` + a one-line index entry in `MEMORY.md`.
+- Skills: one procedure per file; each has *When to use · Steps · Guardrails · Exit criteria*. Keep them concise.
+
+## License (Eclipse / MIT)
+
+- Repo license: **MIT**, copyright Eclipse Foundation. Every new `.js`/`.ts`/`.tsx` source file **must** start with the Eclipse/MIT header (`SPDX-License-Identifier: MIT`) — see [`skills/license-check.md`](./skills/license-check.md) for the exact block. `.sh`/`.yml`/`.md` files do not carry it (repo convention).
+- Don't remove or alter existing `Copyright`/`SPDX-License-Identifier` headers.
+- Don't introduce copyleft (GPL/AGPL/CDDL) or proprietary third-party code — MIT can't combine with it. Vendored code must be MIT-compatible and keep its original notice.
+- CI: `scripts/check-license-headers.sh` + `.github/workflows/license-headers-check.yml` check changed source files for the header.

agentic/README.md

@@ -0,0 +1,68 @@
+# AutoWRX Agentic Coding Framework
+
+A **repo-resident, vendor-neutral** framework that lets any AI coding agent — Claude Code, opencode, openclaw, or the next tool — work the same way in this repo: load the same rules, memory, skills, and repo map; follow the same implement → test → review → commit → PR → deploy flow; and avoid re-scanning the whole repo each session.
+
+> Issue: #612 · Design: [`docs/agentic-framework/PROPOSAL.md`](../docs/agentic-framework/PROPOSAL.md)
+
+## Layout
+
+```
+AGENTS.md                       vendor-neutral entry point (read by every tool)
+CLAUDE.md                       Claude Code adapter (imports AGENTS.md via `@path`)
+agentic/
+  README.md                     this file
+  RULES.md                      hard rules (must / must-not)
+  CONVENTIONS.md                naming, structure, commit, PR style
+  SETUP.md                      how to wire this repo into each tool
+  skills/                       skill playbooks (load-on-demand procedures)
+    README.md                   skill index
+    understand-the-repo.md
+    implement-feature.md
+    run-tests.md
+    code-review.md
+    security-review.md
+    commit-and-pr.md
+    deploy.md
+    docs-update.md
+    learn-and-update.md
+  memory/                       repo-resident knowledge base (facts + index)
+    MEMORY.md                   index (one line per fact)
+  map/                          repo map: pointers to the real maps + compact tree
+    INDEX.md
+    TREE.md
+  learning/                     continuous-learning layer
+    README.md
+    best-practices.md
+    trends.md
+    lessons.md
+```
+
+## How an agent uses this (the contract)
+
+1. On start, read `AGENTS.md` (and the tool's adapter, e.g. `CLAUDE.md`). It imports `agentic/RULES.md` + `agentic/CONVENTIONS.md` — these are the **always-loaded** rules.
+2. Before doing real work, run the **`understand-the-repo`** skill: load `agentic/map/INDEX.md` + `agentic/memory/MEMORY.md` instead of re-scanning the repo. Deep-read only the specific module you'll touch.
+3. For a task, load the matching **skill** from `agentic/skills/` (skills are markdown; load on demand, not all at once).
+4. Follow the canonical flow in `agentic/skills/implement-feature.md`.
+5. When you learn something durable, propose it into `agentic/memory/` or `agentic/learning/` via a PR (see `learn-and-update` skill).
+
+## What is NOT duplicated here
+
+This framework **points to** existing repo knowledge rather than copying it:
+
+- **Architecture / deep-dive** → [`docs/architecture/`](../docs/architecture/)
+- **Capability catalog** → [`docs/capabilities/`](../docs/capabilities/) (the spec/acceptance reference)
+- **Pages & feature coverage** → [`.agents/SITEMAP.md`](../.agents/SITEMAP.md)
+- **Getting started / local dev / contributing** → [`docs/getting-started/`](../docs/getting-started/)
+- **Design principles** → [`docs/principles/principle.md`](../docs/principles/principle.md)
+- **E2E tests** → [`.agents/`](../.agents/) (Playwright)
+
+`agentic/map/` is an **index of pointers** to the above, plus a compact `TREE.md`. Update pointers when docs move; don't copy their content.
+
+## Vendor neutrality
+
+Canonical content lives in `agentic/`. Tool-specific entry files are thin adapters:
+- **Claude Code** → `CLAUDE.md` uses `@path` imports (e.g. `@AGENTS.md`, `@agentic/RULES.md`) to pull in the canonical files.
+- **opencode / openclaw / others** → read `AGENTS.md` natively (agents.md spec).
+- **Skills** are plain markdown loaded on demand — every tool can read them. To get native Skill-tool invocation in Claude Code, see `SETUP.md` (symlink `agentic/skills/*` into `.claude/skills/`).
+
+See [`SETUP.md`](./SETUP.md) for per-tool wiring.

agentic/RULES.md

@@ -0,0 +1,41 @@
+# Rules (must / must-not)
+
+Hard rules for any agent working in this repo. Load always (imported by `AGENTS.md` / `CLAUDE.md`). Violating these is a defect, not a style choice.
+
+## Git & contributions
+
+- **ECA is mandatory.** Every commit author must have signed the [Eclipse Contributor Agreement](https://www.eclipse.org/legal/eca/) and commit with the **email they signed the ECA with**. Each contributor uses their own ECA-signed identity — do not assume a specific name/email repo-wide.
+- **Sign off commits:** `git commit -s` (adds `Signed-off-by:`).
+- **Never commit on `main`.** Branch off `main` first; PRs target `main`.
+- **Never force-push to shared branches.** Rebase your own feature branch only.
+- **Never commit secrets** (`.env`, `.env.prod`, tokens, keys, cookies). They are gitignored; keep them out.
+- **Co-author / attribution:** when an agent makes commits, end the message with `Co-Authored-By: Claude <noreply@anthropic.com>` (or the tool's equivalent). See `commit-and-pr` skill.
+
+## Code changes
+
+- **Do not push or deploy unless explicitly asked.** Commit only when asked; push/PR only when asked; deploy only when asked. Each is a separate authorization.
+- **Never mark a task complete if tests fail or work is partial.** Report failures honestly with output.
+- **Before deleting/overwriting a file, look at it.** If it contradicts how it was described or you didn't create it, surface that instead of proceeding.
+- **Match surrounding code:** naming, comment density, idioms. No drive-by reformatting outside the change's scope.
+- **Backend:** thin controllers, logic in services (see [`docs/principles/principle.md`](../docs/principles/principle.md)).
+- **Frontend:** atomic design (components/molecules/organisms/pages). Do not bypass the existing layering.
+
+## Verification
+
+- **Run tests before declaring done:** `backend: npm test` (Jest) and/or `cd .agents && npx playwright test` for affected flows. If you can't run them, say so.
+- **Lint where it exists:** `backend: npm run lint && npm run prettier`; `frontend: npm run lint`. Fix your own lint errors; don't disable rules silently.
+- **Self-review your diff before commit** (see `code-review` skill). Security-sensitive changes (auth, tokens, file ops, runtime, plugins) also run `security-review`.
+
+## Agent context discipline (token efficiency)
+
+- **Load the map + memory first,** not the whole repo. Use the `understand-the-repo` skill.
+- **Deep-read only the module you're touching.** Don't dump files into context you won't use.
+- **Skills are load-on-demand.** Don't preload all skills; load the one matching the task.
+- **When you learn a durable fact, write it to `agentic/memory/` or `agentic/learning/`** (propose via PR) so the next session doesn't re-learn it.
+
+## Must-not
+
+- Don't fabricate endpoints, statuses, flags, or file paths. If unsure, read the code.
+- Don't edit `docs/capabilities/*` technical claims without verifying against the route/controller code (the catalog is code-grounded).
+- Don't change the ECA/git identity rules.
+- Don't run destructive commands (`rm -rf`, `git reset --hard` on shared refs, `down.sh` on a prod env) without explicit confirmation.