feat(agentic): vendor-neutral agentic coding framework - #613
Merged
Conversation
…ork (#612) Proposal only — no implementation. Defines a repo-resident, vendor-neutral agentic coding framework (.agent/ + AGENTS.md/CLAUDE.md adapters) so any AI agent (Claude Code, opencode, openclaw, …) loads the same rules, memory, skills, and repo map; follows the same implement/test/review/commit/PR/deploy flow; and avoids re-scanning the repo each session (token savings). Includes a continuous-learning layer, per-tool mapping, phased migration, and open decisions for review. Co-Authored-By: Claude <noreply@anthropic.com>
Add a repo-resident, vendor-neutral agentic coding framework so any AI agent (Claude Code, opencode, openclaw, …) loads the same rules, memory, skills, and repo map; follows the same implement → test → review → commit → PR → deploy flow; and avoids re-scanning the whole repo each session (token savings). Entry points: - AGENTS.md — vendor-neutral entry (agents.md convention), read by any tool - CLAUDE.md — Claude Code adapter (@imports AGENTS.md + rules) Canonical content under agentic/ (distinct from the existing .agents/ E2E suite): - RULES.md, CONVENTIONS.md — always-loaded hard rules + style - SETUP.md — per-tool wiring (Claude Code / opencode / openclaw) - skills/ — 9 playbooks: understand-the-repo, implement-feature, run-tests, code-review, security-review, commit-and-pr, deploy, docs-update, learn-and-update (load-on-demand) - memory/ — repo-resident knowledge base (facts + index); supersedes user-local memory for shared knowledge - map/ — INDEX.md + TREE.md: pointers to the real maps, not duplicates - learning/ — continuous-learning layer (best-practices, trends, lessons) The framework wires into existing repo knowledge rather than duplicating: docs/architecture/, docs/capabilities/, .agents/SITEMAP.md, docs/getting-started/, docs/principles/. CI: scripts/check-agent-map.sh + .github/workflows/agent-map-check.yml verify all framework markdown links resolve (drift detection). Verified clean locally (28 files, all links resolve). Proposal updated: docs/agentic-framework/PROPOSAL.md marked implemented. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: NhanLuongBGSV <nhan.luongnguyen@vn.bosch.com>
…review fixes The framework wrongly hardcoded one user's identity (NhanLuongBGSV / nhan.luongnguyen@vn.bosch.com) as a repo-wide commit rule. Identity is personal — each contributor commits with their own ECA-signed account. Repo rules now say "commit with your own ECA-signed identity"; the personal identity stays in user-local memory, not committed files. Self-review (dogfooded the framework's own understand-the-repo + code-review skills to validate the framework against the real repo): - Removed the hardcoded identity from AGENTS.md, CLAUDE.md, RULES.md, memory/verified-facts.md, skills/commit-and-pr.md, skills/implement-feature.md, PROPOSAL.md. Drift check still clean; no identity refs remain. - Verified memory claims against code: authLimiter is defined+exported in backend/src/middlewares/rateLimiter.js and unused (gotchas.md ✓); routes/v2 has exactly 4 domains content/system/user-management/vehicle-data (verified-facts.md ✓); no Jest/Playwright runs on PRs (gotchas.md ✓). - Corrected gotchas.md: PR CI now also runs agent-map-check for agentic/+ docs changes (this PR adds it), so "ECA-only" was stale. - Corrected security-review.md: /security-review is a Claude Code built-in harness skill (available in any repo), not something this repo ships. - Confirmed all 9 skills have the 4 required sections, all TREE.md paths exist, MEMORY.md index matches its files, and all markdown links resolve. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: NhanLuongBGSV <nhan.luongnguyen@vn.bosch.com>
…ll + CI) The framework had a security-review skill but no license check — a gap for an Eclipse project where source license headers matter. This adds the license half and wires both into the flow. - agentic/skills/license-check.md — new skill: verify changed .js/.ts/.tsx carry the repo Eclipse/MIT SPDX header, no existing headers stripped, no copyleft/proprietary vendored code, deps MIT-compatible. - scripts/check-license-headers.sh + .github/workflows/license-headers-check.yml — CI gate that checks only CHANGED source files vs the PR base (pre-existing header debt elsewhere doesn't block). Verified clean on this branch. - CONVENTIONS.md — License (Eclipse/MIT) section: header requirement, no copyleft, CI pointer. - skills/README.md + AGENTS.md + implement-feature.md + code-review.md — wire license-check into the core flow alongside security-review. Ran the round on this PR's own diff (dogfood): no .js/.ts/.tsx changed → license-headers OK; no real secrets in committed files (only prose rules); check-agent-map.sh is pure os.path (no injection); workflow uses actions/checkout@v4, no secrets exposed. Security + license: clean. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: NhanLuongBGSV <nhan.luongnguyen@vn.bosch.com>
…ax + citations Adversarial self-review of the whole framework (read every file, verified claims against the repo). Findings + fixes: - CLAUDE.md used `@import ./file` — wrong. Claude Code's import syntax is `@path` (e.g. `@AGENTS.md`); `@import` would not expand. Fixed to `@AGENTS.md` / `@agentic/RULES.md` / `@agentic/CONVENTIONS.md`. Verified the imported chain has no stray `@` tokens (no unintended nested imports). Updated 9 prose references across SETUP/README/AGENTS/CONVENTIONS/decisions/ best-practices/PROPOSAL to say `@path`, not `@import`. - memory/verified-facts.md cited `frontend/vite.config.ts` for the dev port; the port (3210) is actually in `frontend/package.json`'s `dev` script. Fixed citation. - SETUP.md skill-symlink loop also symlinked README.md as a skill; now skips the index. Verified accurate (no change needed): deploy.md env keys match .env.prod.sample exactly; security-review reference docs (docs/reference/csp.md, authentication-cookie-handling.md, architecture/plugin-system.md) exist; memory facts (4 route domains, authLimiter unused, tsc&&vite build) match code; map/TREE.md paths exist; all 9 skills have the 4 required sections; drift check + license-headers check pass; no @import remains. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: NhanLuongBGSV <nhan.luongnguyen@vn.bosch.com>
…s label
Third adversarial self-review pass (verified every concrete technical claim
in the skills against the code; scanned for contradictions + vendor leaks).
Verified accurate against code (no change needed):
- security-review.md plugin claims all real: window.DAPlugins
(PluginPageRender.tsx), PluginAPI, POST /v2/plugin/upload/:slug
(plugin.route.js:36), system unzip via spawn('unzip',...) (plugin.controller.js:140).
- Branch naming + PR title format consistent across CONVENTIONS.md,
implement-feature.md, commit-and-pr.md (types feat/docs/fix/chore/refactor).
- backend/src/typedefs and backend/src/docs dirs exist.
Fixes:
- Vendor-neutrality leak: Co-Authored-By: Claude <noreply@anthropic.com> was
hardcoded in CONVENTIONS.md and commit-and-pr.md. Now conditional — Claude
Code uses that trailer; other tools use their equivalent or omit. RULES.md
already had the "(or the tool's equivalent)" caveat. commit-and-pr exit
criteria softened to not require the Co-Authored-By trailer.
- map/TREE.md: typedefs/ labeled "TS-style type defs" but backend is JS —
corrected to "shared JSDoc @typedef definitions".
Drift check (29 files) + license-headers check still pass.
Co-Authored-By: Claude <noreply@anthropic.com>
Signed-off-by: NhanLuongBGSV <nhan.luongnguyen@vn.bosch.com>
…, ops, plugins, secrets) Scanned the codebase, docs, and capability catalog to identify recurring work + risk areas not covered by the original 10 skills, then authored 13 new skill playbooks grounded in real repo paths/commands: Debug & correctness: - debug.md — symptom→where-to-look decision tree (winston/morgan, Docker/pm2 logs, browser console [no ErrorBoundary], Socket.IO frames, Playwright trace) + a common-symptoms table (401 loop, empty workspace-tree, 503, CACHE_URL staleness, 6bd6ccb seed race, 500 bypass, StrictMode double-call). - find-race-conditions.md — concurrency hunt for the no-transactions codebase (doc-level atomicity only; read-modify-write→findOneAndUpdate; counters; token single-flight; Socket.IO ordering; seed-vs-save; CACHE_URL eventual consistency). Build (add/change): - add-endpoint.md — v2 endpoint procedure (domain route → service → thin controller → model → auth gating → Joi validation → register in domain index.js → Jest → capability doc → SITEMAP). - add-frontend-feature.md — atomic-design placement, configs/routes.tsx, Zustand store, usePermissionHook, API client, E2E spec. - db-schema-change.md — safe Mongoose evolution (additive fields, indexes/TTL citing the Token TTL gap, backfill scripts; no migration tool/transactions). - realtime-event.md — adding a Socket.IO event (config/socket.js, kit-server relay via RUNTIME_SERVER_URL, subscribe→run→stop lifecycle). - add-test.md — Jest (backend) + Playwright (.agents helpers/fixtures/snapshot policy). Review & health: - performance-review.md — Mongo N+1/populate/indexes, external CACHE_URL/ LOG_URL calls, frontend bundle (rollup-plugin-visualizer), Socket.IO fan-out. - dependency-upgrade.md — npm audit/Dependabot, breaking-change check, tests, license compatibility (450 vulns flagged on the repo). Deploy & ops: - troubleshoot-deploy.md — unhappy-path symptom→cause→fix (env, ports, Mongo, PROTOTYPES_PATH bind-mount [d6807b4], host.docker.internal/CODER_URL). - coder-workspace.md — VS Code-in-browser integration (instance-setup/coder + plans, workspace lifecycle). Specialized: - plugin-authoring.md — window.DAPlugins/PluginAPI, unsandboxed model, e2e-simple-plugin fixture, upload. - secrets-incident.md — leaked-secret response (identify, blast radius, rotate-at-source, scrub, incident note). Wiring: skills/README.md index reorganized into categories (23 skills) with an expanded core-flow diagram; AGENTS.md points to the full index. Verified: all 13 skills have the 4 required sections; drift check passes (42 framework files, all links resolve); license-headers check passes; spot-checked debug.md + add-endpoint.md claims against code (validations/ <area>.validation.js + index.js, middlewares/validate.js, socket.js:31 handshake.query.access_token, routes/v2/index.js aggregation — all real). Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: NhanLuongBGSV <nhan.luongnguyen@vn.bosch.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #612.
What
A repo-resident, vendor-neutral agentic coding framework so any AI agent — Claude Code, opencode, openclaw, or the next tool — loads the same rules, memory, skills, and repo map; follows the same implement → test → review → commit → PR → deploy flow; and avoids re-scanning the whole repo each session (token savings).
Entry points
AGENTS.md— vendor-neutral entry (agents.md convention), read by any tool.CLAUDE.md— Claude Code adapter (@importsAGENTS.md+ rules).Canonical content under
agentic/(chosen over
.agent/to avoid colliding with the existing.agents/E2E suite)RULES.md/CONVENTIONS.md— always-loaded hard rules + style.SETUP.md— per-tool wiring (Claude Code / opencode / openclaw).skills/— 9 load-on-demand playbooks:understand-the-repo,implement-feature,run-tests,code-review,security-review,commit-and-pr,deploy,docs-update,learn-and-update.memory/— repo-resident knowledge base (facts +MEMORY.mdindex); shared across tools/machines, reviewable in PRs (supersedes user-local memory for shared knowledge).map/—INDEX.md+TREE.md: pointers to the real maps, not duplicates.learning/— continuous-learning layer (best-practices, trends, lessons).Wires into existing knowledge (no duplication)
docs/architecture/,docs/capabilities/,.agents/SITEMAP.md,docs/getting-started/,docs/principles/.CI drift check
scripts/check-agent-map.sh+.github/workflows/agent-map-check.ymlverify every framework markdown link resolves (catches drift when docs/structure move). Verified clean locally (28 files, all links resolve).How verified
scripts/check-agent-map.sh→agent-map OK).backend/src/{routes/v2/<domain>,controllers/<area>.controller.js,services/<area>.service.js,middlewares/rateLimiter.js}).authLimiterdefined inbackend/src/middlewares/rateLimiter.jsbut unused; PR CI is ECA-only).NhanLuongBGSV/nhan.luongnguyen@vn.bosch.com,git commit -s, ECA-signed.Design decisions (resolved per #612)
dir
agentic/· reusedocs/capabilities/as the map · committed map + CI drift check · learning included (manual trigger) · full scope (no phasing). Seedocs/agentic-framework/PROPOSAL.md.🤖 Generated with Claude Code