| name | vben-admin |
| description | Use when working on the Vben Admin monorepo (Vue 3 + Vite + pnpm + Turbo), including apps, packages, docs, playground, and automation. |
Vben Admin
Core Principle
This project uses document-driven iterative development. Repository docs are the source of truth; chat is temporary. Requirements, decisions, assumptions, open questions, task boundaries, verification commands, and iteration results must be written to project docs before they are treated as durable state.
Vben Framework First
- Treat the official Vben Admin skill reference at
https://github.com/vbenjs/skills as the framework guide for route, menu, access, theme, locale, login, API, and component conventions.
- Prefer existing Vben framework primitives, shared packages, and established app patterns before introducing bespoke abstractions or custom UI.
- If a task must deviate from framework conventions, record the reason and replacement pattern in the handoff.
Full-Stack Product Rule
Treat vben-admin/main + /home/mini/OpenSource/framework/base-server/master as one complete monolithic product line for feature work. When adding, modifying, or refactoring a feature, inspect the paired backend impact before editing and report both frontend and backend impact at handoff.
If frontend routes, menus, permissions, fields, request parameters, response handling, upload, SSE, or generated client usage changes, plan the matching backend contract/handler/biz/data/auth check or update in the paired base-server repo on the same version line. If no backend change is required, state why.
Do not mix in microservice branch assumptions or API prefixes unless both repos are on monorepo.
Read First
/home/mini/OpenSource/framework/AGENTS.md/home/mini/OpenSource/framework/REPO_STRUCTURE.md/home/mini/OpenSource/framework/STARTUP_AND_INTEGRATION.mdAGENTS.mddocs/project_profile.mddocs/architecture/current_architecture.mddocs/architecture/tech_stack.mddocs/planning/module_boundaries.mddocs/planning/verification.mddocs/planning/risk_register.mddocs/progress.mddocs/worklog.md
Module Boundaries
- These rules describe the frontend
main branch paired with the monolithic backend. The microservice frontend lives on monorepo.
apps/web-antd, apps/web-antdv-next, apps/web-naive, apps/web-ele, apps/web-tdesign: app-specific UI, routing, and bootstrapapps/backend-mock: dev-only mock backendplayground: integration demos and Playwright e2epackages/@core/*: low-level shared foundation, UI kit, preferences, composablespackages/effects/*: shared behavior, access, layouts, hooks, request, common UIpackages/{constants,icons,locales,preferences,stores,styles,types,utils}: shared runtime librariesinternal/*: workspace tooling and config packagesdocs/src: public VitePress docs sitedocs/*.md: durable project-state docsscripts/*: automation and release helpers
Shared High-Conflict Files
package.jsonpnpm-workspace.yamlpnpm-lock.yamlopenapi.yamlturbo.json.npmrclefthook.ymleslint.config.mjsstylelint.config.mjsvitest.config.tsapps/backend-mock/**apps/web-antd/**packages/@core/**packages/effects/**docs/src/**docs/project_profile.mddocs/architecture/**docs/planning/**docs/progress.mddocs/worklog.mdinternal/**
Only modify these when the active task explicitly authorizes it.
Verification
See docs/planning/verification.md for the current command matrix.
Use the narrowest command that covers the touched boundary first. Escalate to pnpm check only when shared packages, tooling, or cross-app behavior changed.
The active backend API prefix on main is /basic-api/*; do not introduce /auth-api/*, /user-api/*, /admin-api/*, or /common-api/* unless this repo is on monorepo.
Git Policy
- Check
git status --short --branch, current branch/ref, and worktree list before editing.
- Do not overwrite existing dirty files unless the task explicitly targets them.
- Keep commits aligned with a single task boundary.
- Do not commit generated artifacts, lockfile churn, or unrelated user work.
- Push only when the user asks.
Worktree And Subagent Discipline
- Use parallel work only for disjoint write paths.
- Do not parallelize lockfile, workspace, API contract, or global config changes with feature work.
- Reserve explicit paths before spawning workers.
- Merge one child result at a time and re-run targeted verification after each merge.
Human Escalation
Ask before changing:
- Product scope
- Public API shape or generated client contract
- Package boundaries or ownership
- UI framework choice
- Build, release, or deployment posture
- Security-sensitive configuration
Human Interrupts
- Pause the affected work immediately.
- Record the confirmed change in
docs/worklog.md and any affected project docs.
- Re-check task boundaries, parallelism, and verification before resuming.
Completion Report
Report:
- Goal result
- Active version line and frontend/backend impact
- Changed files
- Verification run
- Open risks
- Next recommended action
