# AI Development Introduction

This page is the entrypoint for contributors who are designing, reviewing, or maintaining AI vibe coding workflows in the Cabloy repository.

For work that must move from confirmed product intent to evidence-backed verification, use [AI Spec-Driven Development](/ai/ai-spec-driven-development). It is a disciplined specification-delivery path within AI Development, not a synonym for every AI vibe coding workflow.

The Cabloy monorepo is a good fit for AI vibe coding because the source tree already contains most of the framework knowledge an agent needs:

- root scripts for shared workflows
- Vona CLI source and command groups
- Zova CLI source and command groups
- archived docs that still capture valuable concepts
- `repo-docs-internal/` engineering docs for maintainers
- agent-neutral repository governance, generated adapters, and deterministic tools

## The main design goal

The goal is not to make AI guess Cabloy conventions more effectively.

The goal is to make AI **reuse the repo’s existing conventions directly**, especially through:

- CLI commands
- root scripts
- repo markers
- relevant `repo-docs-internal/` architecture notes
- shared public documentation

## How to approach AI work

For contributor and automation workflows in this repository, prefer this order:

1. inspect the active edition and repo markers before making UI-sensitive or workflow-sensitive assumptions
2. inspect root scripts, Vona CLI, and Zova CLI before inventing manual scaffolding or custom workflow steps
3. use public docs for durable user-facing and agent-facing guidance; consult relevant `repo-docs-internal/` records for supporting maintainer rationale
4. encode repeatable behavior in the canonical agent-governance rules, commands, or skills instead of relying on unstated habits

## The knowledge layers

### Public docs

Use `repo-docs/` for user-facing and agent-facing guidance that should remain durable and source-aligned.

For normal project usage, prefer the user-facing entry docs such as [Fullstack Quickstart](/fullstack/quickstart). This AI section focuses on repository workflows and AI vibe coding.

### `repo-docs-internal/` engineering docs

Use `repo-docs-internal/` for architecture notes, ADRs, and maintainer rationale that should not be mixed into public how-to documentation. Relevant records support a shared workflow without being prerequisites; an unavailable or irrelevant individual record must not cause its rationale to be moved into public how-to documentation automatically.

### Agent governance and adapters

Use `repo-agent-governance/` as the authored source for portable repository rules, root workflow skills, bundled references, and deterministic tools. It generates committed adapter outputs for Claude Code, Codex, and Cursor. See [Agent Governance](/ai/agent-governance) for the ownership and capability boundary.

### Platform runtime integration

`CLAUDE.md`, `.claude/commands/`, `.claude/skills/`, `AGENTS.md`, `.agents/skills/`, `.codex/`, and `.cursor/` are adapter/runtime surfaces. Hooks, permissions, local settings, credentials, and provider-specific command discovery stay platform-specific rather than becoming shared framework facts.

## AI reading paths

Use this page as the main AI-development hub, then choose the path that matches your task.

### Repo workflow path

Start here when the task is about choosing the right repo surface, docs location, or automation boundary:

- [Repo Guidance](/ai/repo-guidance)
- [Agent Governance](/ai/agent-governance)
- [Docs / Skills Mapping](/ai/docs-skills-rules-mapping)
- [CLI to Skill Map](/ai/cli-to-skill-map)
- [Skills](/ai/skills)
- [Rules and Config](/ai/rules-and-config)

### Specification planning and delivery path

Use this path to understand [AI Spec-Driven Development](/ai/ai-spec-driven-development), establish suite authority before implementation, then deliver one approved, bounded WBS increment with evidence-backed status:

- [AI Spec-Driven Development](/ai/ai-spec-driven-development)
- [Generate a Cabloy Suite Specification](/ai/playbook-spec-generation)
- [Execute an Approved Cabloy Specification Increment](/ai/playbook-spec-execution)
- [Skills](/ai/skills)
- [Repo Scripts](/reference/repo-scripts)
- [Verification](/ai/verification)

### Framework implementation path

Use this path when the task is about implementing or reviewing Cabloy code with repo-aware rules:

- [Class Placement Rule](/ai/class-placement-rule)
- [Global Bean Lookup](/ai/global-bean-lookup)
- [Playbook: Backend Module](/ai/playbook-backend-module)
- [Playbook: Frontend Page](/ai/playbook-frontend-page)
- [Playbook: Contract Regeneration](/ai/playbook-contract-regeneration)
- [Playbook: Module Removal](/ai/playbook-module-removal)
- [Playbook: Metadata Refresh](/ai/playbook-metadata-refresh)

### Verification and roadmap path

Use this path when the task is about consistency checks, verification, or future workflow planning:

- [Cabloy Editions: For AI Development](/editions/overview#for-ai-development)
- [Edition Consistency Checklist](/ai/edition-consistency-checklist)
- [Verification](/ai/verification)
- [Future Skill Roadmap](/ai/future-skill-roadmap)
- [CLI for Agents](/ai/cli-for-agents)

## Recommended AI lookup rules

For backend shorthand lookup, prefer these surfaces in order:

1. `IBeanRecordGlobal` for `this.bean.xxx`, `ctx.bean.xxx`, and `app.bean.xxx`
2. module `src/.metadata/index.ts` to map shorthand names to generated bean types
3. `src/bean` for the shorthand source file itself
4. only then re-evaluate whether the target is really a general full-name bean, a service-scene runtime-anchor, or a lib/helper class

For the full lookup workflow, read [Global Bean Lookup](/ai/global-bean-lookup).

## Common AI mistakes to avoid

- assuming Cabloy Basic and Cabloy Start are identical
- creating framework files manually when a CLI command already exists
- trusting stale legacy repo paths instead of current source
- mixing public documentation and internal rationale into one document set