Cabloy Workflow

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, 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.