--- name: cabloy-workflow description: This skill should be used when the main Cabloy problem is workflow routing before implementation: deciding between Vona backend scaffolding, Zova frontend scaffolding, contract-loop work, or docs/AI-enablement homes such as repo-docs, repo-docs-internal, repo-agent-governance, commands, or skills, including cases where Cabloy Basic vs Cabloy Start assumptions affect that routing. Trigger on requests to route, classify, choose a workflow, choose an edition-specific path, or decide where Cabloy guidance should live. Do not use it once the task is already clearly a backend scaffold, frontend scaffold, or contract-loop job. --- # Cabloy Workflow Use this skill to choose the right workflow before making Cabloy changes. ## Goals 1. detect whether the active repository is Cabloy Basic or Cabloy Start 2. choose the correct layer of work: fullstack, backend, frontend, docs, or AI-enablement 3. prefer Vona or Zova CLI capabilities over manual scaffolding whenever possible 4. keep public docs, internal docs, rules, and skills in the correct locations 5. finish with verification guidance that matches the scope of the task ## Step 1: Detect the active edition Check the repository root for these marker files: - `__CABLOY_BASIC__` - `__CABLOY_START__` Interpretation: - only `__CABLOY_BASIC__` present → this is Cabloy Basic - only `__CABLOY_START__` present → this is Cabloy Start - both markers present → treat the repository as ambiguous or invalid and stop before making edition-specific assumptions - neither marker present → inspect the owning package scripts and nearby repository structure, then ask before making an edition-specific assumption This matters most for frontend work, UI-layer assumptions, flavor names, suite/module availability, SSR site baselines, project assets, and edition-specific AI guidance. Documentation-root policy is independent of edition detection: - `repo-docs-internal/` is the internal documentation home in Cabloy Basic and Cabloy Start - inspect a specific internal record before recommending or reading it - treat relevant edition-local internal records as supporting maintainer material, never as a prerequisite for shared workflow routing - when a specific record is unavailable or irrelevant, continue from public docs, bundled skill references, active source, and tests ## Step 2: Identify the task layer Classify the request before proposing a workflow. ### Fullstack Use the fullstack path when the task spans backend and frontend or touches shared scripts, integration, docs architecture, or cross-stack generation. Typical signals: - "fullstack" - "Cabloy" - backend + frontend in one request - OpenAPI + SDK + DTO + page generation - docs/rules/skills that must support both Vona and Zova ### Backend (Vona) Use the backend path when the task is about: - suite, module, bean, service, controller, model, entity, DTO - CRUD generation - ORM, cache, queue, worker, schedule, auth, permissions - backend tests, build, play, or database reset ### Frontend (Zova) Use the frontend path when the task is about: - page, component, mock, bean - SSR, Web, Admin, SPA - UI-layer-sensitive work - OpenAPI SDK generation - frontend refactors such as page params, page query, component props, or model helpers ### Docs and AI-enablement Use the docs/AI path when the task is about: - `repo-docs/` - `repo-docs-internal/` - `repo-agent-governance/` - generated platform adapters such as `CLAUDE.md`, `.claude/commands/`, and `.claude/skills/` - repo guidance for AI development ## Step 3: Start from shared entrypoints Before inventing a workflow, inspect these shared surfaces: - the repository or workspace `package.json` that owns the active scripts - `npm run vona` - `npm run zova` - root `repo-agent-governance/` if present, otherwise the active generated adapter - `repo-docs/` for public guidance - `repo-docs-internal/` for supporting maintainer rationale If the request spans backend and frontend, classify it as fullstack by default unless the user clearly wants only one side. If edition markers are missing or the repo shape is ambiguous, inspect the nearby scripts and ask the user before making a strong edition-specific assumption. For deeper reference material, read: - `references/edition-detection.md` - `references/cli-strategy.md` The reason is simple: these files are where Cabloy already encodes its real workflows. ### Parallel worktree environment setup When a request involves a second worktree, concurrent Vona/Zova development, isolated ordinary tests, or managed clean E2E, classify it as fullstack workflow setup. Read [Parallel Worktree Environment](../../../repo-docs/fullstack/parallel-worktree-environment.md), the canonical shared recipe maintained in Cabloy Basic for both editions. This routing skill provides read-only guidance only. Do not infer an `APP_NAME` or ports, edit local overrides, or run `npm run init` from a generic worktree request. When the user wants confirmation-gated local environment setup, ask them to explicitly invoke `/cabloy-worktree-environment`. The invoked skill detects Basic or Start to select the active root scripts and managed clean-E2E command. It uses Git worktree metadata, fixed Vona/Zova port baselines, and the worktree basename to recommend the complete standard tuple for confirmation: `APP_NAME`, `SERVER_LISTEN_PORT`, `DEV_SERVER_PORT`, `DEV_SERVER_HMR_PORT`, and an `API_BASE_URL` derived from the Vona port. After confirmation, it writes both `vona/env/.env.local` and `zova/env/.env.local`; never use flavor-, mode-, app-mode-, or runtime-specific `.env.*.local` files. It does not inspect environment-file content or allocate/reserve a live port. The shared environment is Vona + Zova development: Admin and Web are alternative commands using the same configuration, and they must not run concurrently in one worktree. Concurrent use requires separately configured linked worktrees. ## Step 4: Prefer CLI-first workflows Whenever the task maps to an existing generator, initializer, refactor, or metadata command, prefer the CLI. ### Vona CLI families Typical families: - `bin:*` - `create:*` - `init:*` - `tools:*` Typical use cases: - scaffold suite/module/bean/test resources - initialize config/locale/constant/error/assets/types - generate CRUD-related artifacts - refresh metadata or dependency-related output - run backend verification flows ### Zova CLI families Typical families: - `bin:*` - `create:*` - `init:*` - `refactor:*` - `tools:*` - `openapi:*` Typical use cases: - scaffold suite/module/page/component/mock/bean resources - initialize app/system assets and typing helpers - run focused refactors for page/component patterns - generate OpenAPI-related output - refresh metadata or dependency-related output ## Step 5: Choose where the knowledge belongs When the user is asking for guidance or automation assets, route the work to the correct home. ### Public docs Use `repo-docs/` for: - user-facing explanations - reusable AI-facing workflow guidance - edition-aware public documentation ### `repo-docs-internal/` Use `repo-docs-internal/` for: - ADRs - architecture notes - maintainer rationale - invariants and design boundaries Relevant internal records support routing and implementation but do not block them: shared public guidance remains complete, and individual records may be unavailable or irrelevant in the active edition. ### Root rules and commands Use `repo-agent-governance/policies/` and `commands/` as the authored source for: - concise operational guidance - named recurring workflows - repo-wide behavior for Claude ### Skills Use `repo-agent-governance/skills/` for: - procedural workflows that benefit from reusable instructions - edition-aware decision trees - CLI-first orchestration paths - future bundled references or deterministic helper scripts When the request is specifically about master-detail or nested-detail aggregate scaffolding, aggregate-owned detail resources, `:tools:masterDetail`, or nested detail DTO naming/placement in a scaffolding context, route to the dedicated `cabloy-master-detail` skill instead of treating it as generic backend scaffolding. ### Class-placement questions When the request is about whether a backend base class belongs in `src/lib`, `src/service`, or the global bean shorthand surface, apply the A / B1 / B2 rule. - **A**: pure helper base -> `src/lib` - **B1**: subclass-only base -> evaluate case by case, often `src/lib` - **B2**: runtime-anchor base that still needs container-managed or selector/class-token behavior but should not be a global bean -> prefer `src/service` with `@Service()` For these requests: - put the durable operational explanation in `repo-docs/` - put supporting rationale and invariants in `repo-docs-internal/`; preserve the public operational explanation when a particular internal record is unavailable or irrelevant - keep canonical repository policy short and behavioral, then render adapters - do not treat `@Service()` as a business-layer naming decision only; for B2 it is a runtime-anchor placement choice ### Service underscore files When a backend base class should move into `src/service`, do not treat the file name as a cosmetic choice. Prefer `src/service/*_.ts` when the class: - should remain container-managed - mainly acts as a runtime-anchor base, selector anchor, or class-token contract - should not participate in the general full-name registration surface - may need to keep meaningful `@Virtual()` semantics Prefer a normal `src/service/*.ts` file when the service-scene class itself should remain part of the general full-name surface. Do not apply this mechanically to all concrete beans or all abstract classes. Judge by runtime role and registration surface. ### Bean-scene and global shorthand Treat `src/bean` as the structural definition of the global shorthand surface. For these requests: - do not treat `@Virtual()` as a reason to exclude a bean-scene class from `IBeanRecordGlobal` - if a class in `src/bean` should not be global shorthand, re-evaluate placement first - prefer B1/B2 relocation over metadata exceptions or manual `IBeanRecordGlobal` patching - use `IBeanRecordGlobal` as the static authoring-surface registry for global shorthand, not as a full runtime-container inventory ### Global bean lookup workflow When backend code references `this.bean.xxx`, `ctx.bean.xxx`, or `app.bean.xxx`, prefer this lookup sequence: 1. check `IBeanRecordGlobal` in the relevant module `src/.metadata/index.ts` 2. map the shorthand name to the generated bean type 3. jump from the generated type to the source file in `src/bean` 4. only if the shorthand is not found, re-evaluate whether the target is actually a general full-name bean, a service-scene runtime-anchor, or a lib/helper class Use `IBeanRecordGeneral` for general full-name beans and `src/service` or service metadata for runtime-anchor/service-scene lookup. Do not treat `IBeanRecordGlobal` as a full container inventory. ## Step 6: Apply edition-aware branching When the task is frontend-sensitive or examples differ between editions, branch explicitly. ### Cabloy Basic Bias toward: - the public framework/reference edition - current public monorepo source - the default `npm create cabloy` project route - public docs examples - the Basic repo marker - current Basic frontend flavors, module layout, and DaisyUI + Tailwind CSS UI assumptions ### Cabloy Start Bias toward: - the public MIT-licensed edition maintained in its own repository - the Start repo marker - the active Start repository source - Vuetify-sensitive examples - Start-specific frontend flavor names - Start-specific suites/modules, SSR site baselines, project assets, and separate-repository structure Do not silently reuse Basic examples when Start-specific assumptions matter. ## Step 7: Verification Always finish with a verification plan that matches the work. ### For docs or AI-asset changes Verify: - referenced paths exist - command names still exist - public docs, `repo-docs-internal/` rationale, and rules tell a consistent story - edition-specific notes point to the right repo assumptions ### For backend/frontend workflow changes Prefer the narrowest useful checks first, then broader checks when needed. Typical shared checks include: - root scripts such as `npm run tsc`, `npm run test`, `npm run build` - command help or discovery output from `npm run vona` / `npm run zova` - targeted build/dev/typecheck flows for the affected side ## Response pattern When you use this skill, structure the response around these points when helpful: 1. detected edition 2. detected task layer 3. recommended CLI or repo entrypoint 4. files or directories likely involved 5. verification steps Keep the response practical. The value of this skill is not extra prose. The value is choosing the right Cabloy workflow quickly and accurately.