Large Admin Ia

Structure large admin apps via IA and CRUD stubs.

Skill metadata

Source	Bundled (installed by default)
Path	skills/web-development/large-admin-ia
Version	1.0.0
Author	VibeOS
License	MIT
Platforms	linux, macos, windows
Tags	admin, ia, cms, crud, nextjs, roles, permissions, web
Related skills	internet-starter, cinematic-web, site-map-crawl, browser-e2e, page-agent

Reference: full SKILL.md

info

The following is the complete skill definition that VibeOS loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.

Large Admin IA Skill

Plan and scaffold a separate large management / admin app: entities, information architecture, roles, permissions, and CRUD stubs — not a marketing landing and not an extension of the VibeOS dashboard.

Hard boundary. Customer CMS / ops consoles ship as their own Next (or existing target) app. Do not add routes under vibeos dashboard / web/src/pages for this work.

Optional NL in admin

After the separate admin app exists, you may embed optional-skill page-agent (vibeos skills install official/web-development/page-agent) so end-users drive that app’s UI with natural language. Embed only in the customer admin app — never in the VibeOS dashboard. page-agent is in-page (client DOM); it is not VibeOS browser automation (browser-e2e / browser tools).

When to Use

• User wants a multi-entity admin, CMS, or ops console (list/detail/forms)
• Need screens, nav tree, roles, and a permissions matrix before coding
• After internet-starter (or an existing target dir) — never the VibeOS dashboard
• Verify smoke with browser-e2e / browser tools; map routes with site-map-crawl

Prerequisites

• Node.js 20+ and npm when scaffolding Next (terminal)
• Write access for entities.yaml, IA.md, and app stubs in the target app
• Backend from brief: Convex or FastAPI + SQL stubs — do not force one
• Browser tools for smoke: browser_navigate, browser_snapshot
• Templates under this skill: templates/, references/permissions-matrix.md

How to Run

1. Capture a short brief (domain, actors, must-have entities, backend preference).
2. Author entities.json from templates/entities.example.json (or YAML example).
3. Generate stubs in a separate out dir: python3 scripts/scaffold_admin.py --entities templates/entities.example.json --out ./admin-app Optional FastAPI in-memory CRUD (separate from VibeOS dashboard): python3 scripts/scaffold_admin.py --entities templates/entities.example.json --out ./admin-app --with-api That writes api/requirements.txt, api/app/main.py (/health + per-entity list/get/create/update/delete), and api/README.md (uvicorn on port 8000). Optional Convex schema + CRUD stubs (files only; no npm install): python3 scripts/scaffold_admin.py --entities templates/entities.example.json --out ./admin-app --with-convex That writes convex/schema.ts, convex/<slug>.ts (list / get / create / update / remove), convex/tsconfig.json, and convex/README.md (npx convex dev). Flags can combine: --with-api --with-convex. Optional page-agent NL stub (this admin only): python3 scripts/scaffold_admin.py --entities … --out ./admin-app --with-page-agent → components/PageAgentEmbed.tsx + PAGE_AGENT.md. Same flags via CLI: vibeos web scaffold admin ./admin --with-api --with-convex --with-page-agent.
4. Review generated IA.md + permissions.md; refine roles/screens by hand.
5. Wire a real data layer (Convex or FastAPI+SQL) — stubs are shells only. With --with-api, start from the generated FastAPI stub and replace the dict stores with a real database. With --with-convex, run npx convex dev and wire the Next stubs to the generated functions. With --with-page-agent, follow PAGE_AGENT.md (npm install page-agent, mount <PageAgentEmbed />, set NEXT_PUBLIC_PAGE_AGENT=1).
6. Checklist empty / error / loading on every primary screen; then browser-e2e.

If paths are unknown: search_files for large-admin-ia/.

Quick Reference

Artifact	Role
Brief	Scope, actors, backend choice (Convex | FastAPI+SQL)
entities.yaml	Entities, fields, relations
IA.md	Screens, nav tree, roles, state notes
Permissions matrix	role × entity × list/read/create/update/delete
App scaffold	Separate Next (or target dir) — not VibeOS dashboard
CRUD stubs	List, detail, form shells per entity

Tool	Use
read_file	Brief, templates, existing target code
patch	Write YAML/MD/stubs in the target app
terminal	Scaffold, install, npm run dev, API stubs
browser_navigate / browser_snapshot	Smoke key screens

Do	Don't
Separate customer admin app	Extend web/src/pages / vibeos dashboard
Choose backend from brief	Invent CMS core tools
Cover empty/error/loading	Ship list pages with no empty state

Procedure

1. Brief — Domain, primary jobs, roles (e.g. admin/editor/viewer), backend preference (Convex or FastAPI+SQL), and out-of-scope (no dashboard merge).
2. Entities — Copy templates/entities.example.yaml → project entities.yaml. Name entities, scalar fields, and relations (belongs_to / has_many).
3. IA — Copy templates/IA.example.md → IA.md. List screens, nav tree, role gates, and notes for empty / error / loading per major view.
4. Permissions — Fill the matrix in references/permissions-matrix.md (or a project copy). Mark allow/deny for list, read, create, update, delete.
5. Scaffold — New Next app via internet-starter / terminal, or use the user-named target directory. Refuse patches into VibeOS dashboard sources. Prefer scripts/scaffold_admin.py (optional --with-api / --with-convex).
6. Backend stubs — Per brief: Convex schema + queries/mutations stubs (--with-convex), or FastAPI routers + SQL models/migrations stubs (--with-api gives an in-memory FastAPI starting point). Keep stubs aligned to entities.
7. CRUD UI stubs — For each entity: list, detail, create/edit shells; nav from IA; gate actions by the matrix (hide or disable, don't only comment).
8. States checklist — Empty, error, and loading on every primary screen.
9. Smoke — terminal start app → browser_navigate + browser_snapshot on home, one list, one detail, one denied-role path if feasible. Optional: site-map-crawl for route inventory; browser-e2e for deeper flows.
10. Later (optional) — see Optional NL in admin (page-agent in this app only). Do not conflate with cinematic marketing sites (cinematic-web).

Pitfalls

• Zero new core CMS tools — use read_file, patch, terminal, browser tools.
• Never treat VibeOS dashboard / web/src/pages as the customer CMS shell.
• Do not force Convex or FastAPI; pick from the brief and stub only that path.
• Permissions without UI gates leave editors seeing admin actions — wire both.
• Skip empty/error/loading and lists look broken on day one.
• Marketing scroll landings belong to cinematic-web, not this skill.

Verification

• entities.yaml and IA.md exist in the target app (or agreed paths)
• Permissions matrix filled for every entity × role
• App is a separate scaffold/target — not vibeos dashboard
• CRUD stubs + nav match IA; backend stubs match brief choice
• Empty / error / loading checklist done for primary screens
• Browser smoke via browser_navigate + browser_snapshot (or browser-e2e)