Docs, Skills, Rules, and CLI Mapping

This page is for docs, skills, and workflow authors who need to decide where Cabloy AI guidance should live.

This page explains how the Cabloy AI knowledge system is divided across public docs, suite-local authority records, skills, rules, and CLI capabilities.

Why this mapping matters

Without a clear mapping, AI systems and contributors repeat the same mistakes:

• knowledge is stored in the wrong place
• CLI capabilities are documented but not reused in skills
• skills explain things that should live in docs
• rules become too large because they try to teach everything
• the same guidance drifts across multiple files

The goal is to give each layer a distinct job.

The five main layers

1. Public docs

Location:

• repo-docs/

Use public docs for:

• durable user-facing guidance
• durable agent-facing workflow guidance
• architecture explanations that people and agents should both understand
• edition-aware usage notes that need to be reviewed in prose

Public docs answer questions like:

• how does the fullstack collaboration loop work?
• how should Vona ORM and OpenAPI be understood?
• how does Zova page or model architecture work?
• what is different between Cabloy Basic and Cabloy Start?

2. Suite-local authority records

Location:

• repo-specs/<suite>/

Use suite records for the authority that governs one business suite:

• product requirements and system requirements
• WBS delivery boundaries and ATP procedures
• accepted decisions, observed evidence, and derived progress

AI Spec-Driven Development explains how these domain-scoped records form Traceable Spec Delivery. Public docs explain the method; they do not replace suite authority.

3. Internal engineering docs

Location:

• repo-docs-internal/

Use internal docs for:

• ADRs
• architecture rationale
• maintenance boundaries
• “why this design exists” notes that do not belong in public user docs

Relevant internal records answer questions like:

• why were docs and internal notes separated?
• why is AI enablement structured this way?
• what invariants should future contributors preserve?

4. Agent governance, rules, and commands

Canonical location:

• repo-agent-governance/

Generated adapter locations include:

• policy adapters: CLAUDE.md, AGENTS.md, and .cursor/rules/
• Claude-specific command adapter: .claude/commands/
• Claude-specific hook adapter: .claude/settings.json, .claude/hooks/
• Codex-specific hook adapter: .codex/hooks.json, .codex/hooks/
• Cursor-specific hook adapter: .cursor/hooks.json, .cursor/hooks/

Codex and Cursor adapter paths are configured output locations; verify active-client discovery externally before claiming that behavior is supported.

Use the canonical repository policy for concise repo-wide operational guidance and durable constraints such as edition detection and CLI-first preference. Use canonical commands for named recurring operator workflows such as release.

These layers answer questions like:

• what should an agent check first in this repo?
• when should CLI be preferred over manual scaffolding?
• what recurring workflow deserves a named command?

5. Skills

Canonical location:

• repo-agent-governance/skills/

Generated adapter locations include .claude/skills/, .agents/skills/, .codex/, and .cursor/skills/. The Codex and Cursor locations are configured output paths, not verified client-discovery claims; validate the active client version externally before relying on discovery.

Use skills for:

• procedural decision trees
• reusable workflows with branching logic
• tasks that benefit from bundled references, evals, or deterministic helpers
• repo-specific orchestration over CLI and source inspection

Skills answer questions like:

• how should an agent choose the right Cabloy workflow?
• when should it branch between Basic and Start?
• what is the right verification path after generation or refactor work?

Do not treat provider hooks, permissions, local settings, or command discovery as portable skill capabilities. These remain platform-specific adapters.

Decision rule for authors: where should a new piece of knowledge go?

Use this quick rule:

• if people and agents both need to read and understand it, put it in public docs
• if it is product, contract, delivery, ATP, decision, or observed-evidence authority for one suite, use repo-specs/<suite>/
• if it is maintainer rationale or long-lived design history, use repo-docs-internal/; shared guidance remains complete without any particular internal record
• if it is short portable repo-wide behavioral guidance, put it in repo-agent-governance/policies/ and render its adapters
• if it is a named repeatable operator action, put it in a command
• if it is a reusable procedural workflow with branching, put it in a skill

Example mappings

Example: “Always detect Basic vs Start before giving UI-sensitive advice”

• public explanation → Cabloy Editions: For AI Development
• consistency review surface → Edition Consistency Checklist
• repo-wide behavior rule → repo-agent-governance/policies/, rendered to generated policy adapters
• procedural enforcement → cabloy-workflow skill

Example: “Use Zova CLI refactors before hand-editing page params/query/component props”

• conceptual explanation → public docs in frontend and AI sections
• default agent behavior → repo-agent-governance/policies/, rendered to generated policy adapters
• step-by-step orchestration → cabloy-workflow skill or future specialized skills

Example: “How should a backend base class be placed?”

• public operational explanation → Class Placement Rule
• maintainer rationale and invariants → repo-docs-internal/
• default repo-wide behavior → repo-agent-governance/policies/, rendered to generated policy adapters
• procedural decision workflow → cabloy-workflow skill

Example: “How should AI look up a backend global bean?”

• public lookup explanation → Global Bean Lookup
• default repo-wide behavior → repo-agent-governance/policies/, rendered to generated policy adapters
• procedural lookup sequence → cabloy-workflow skill

Example: “How backend OpenAPI becomes frontend SDK”

• full explanation → Backend OpenAPI to Frontend SDK
• workflow steering → skill and rules can point to the docs and choose the right CLI path

Example: “How should one persisted resource serve Admin and Web users?”

• full architecture explanation → Admin Resource and Web Self-Service
• concise repo-wide default → repo-agent-governance/policies/repository.md, rendered to policy adapters
• contract regeneration, consumer-boundary choice, and verification routing → cabloy-contract-loop
• extend the existing contract-loop skill references and evals; do not create an Order-specific skill

Example: “How should AI remove an existing module cleanly?”

• public operational explanation → Playbook: Module Removal
• maintainer rationale and pitfalls → repo-docs-internal/
• avoid putting the full workflow in the concise canonical policy because the task needs branching, cleanup order, generated-runtime recovery, and verification
• procedural decision workflow → cabloy-module-removal skill

Example: “How should AI plan a new business domain name and structure?”

• public naming and suite-first explanation → Suites and Modules
• frontend-side naming companion → Modules and Suites
• keep the durable naming rules in docs instead of duplicating them in repo rules
• avoid putting the full branching workflow in the concise canonical policy because the task needs proposal, validation, confirmation, and CLI handoff
• procedural decision workflow → cabloy-domain-planning skill

Example: “How should AI create or maintain a repository-native suite specification?”

• public method overview → AI Spec-Driven Development
• public workflow explanation → Generate a Cabloy Suite Specification
• procedural planning, confirmation, traceability, and chart-refresh behavior → cabloy-spec-generation
• suite-specific PRD, SRS, WBS, ATP, ADR, progress, and observed evidence authority → repo-specs/<suite>/
• maintainer rationale → repo-docs-internal/
• implementation is not implied by creating planning records

Example: “How should AI deliver an approved suite task?”

• public method overview → AI Spec-Driven Development
• public workflow explanation → Execute an Approved Cabloy Specification Increment
• bounded-WBS coordination, readiness gates, evidence, and derived-status behavior → cabloy-spec-execution
• source implementation → the relevant backend, frontend, contract-loop, or shape-specific skill
• product, contract, dependency, scope, or durable-decision changes → return to specification or domain planning

Example: “What @Api.field(...) ordering rule should AI preserve when mixing helpers and zod?”

• full explanation → Entity Guide and DTO Guide
• AI workflow reminder → Playbook: Add a Backend Module
• procedural checklist reminder → backend scaffold skill references
• avoid putting the full explanation only in the concise canonical policy because this is a framework-specific authoring rule, not a short global behavior rule

Anti-patterns to avoid

Avoid these mistakes:

• putting large conceptual explanations in the concise canonical policy
• using a skill as the only place where an important architectural rule is explained
• duplicating the same workflow prose across docs and skills without giving each a distinct role
• creating a command for something that actually needs a branching decision tree
• creating a skill that re-implements an existing CLI generator manually

Why this matters for AI workflows

This mapping reduces token waste and drift.

If each layer does the right job:

• docs hold durable explanations
• rules hold short repo behavior
• commands hold named actions
• skills orchestrate real workflows
• CLI executes framework-native generation and refactor behavior

That is the AI-development model Cabloy is optimizing for.