Contributing¶

CAFleet is developed using its own CAFleet-orchestrated skills — the repository dogfoods the spec-driven-development flow it ships. This document covers the project layout, the local development loop, and the contribution path.

Project structure¶

Tech stack¶

• Language: Python 3.12+, managed with uv
• Server: FastAPI (admin WebUI)
• Database: SQLAlchemy 2.x (sync pysqlite driver) + SQLite
• CLI: click
• Admin frontend: Vite + Bun (SPA served at /)
• Task runner: mise

Development¶

Clone the repo and use mise for all common tasks:

git clone https://github.com/himkt/cafleet.git
cd cafleet

mise //:uv-sync
mise //cafleet:install    # editable uv tool install of the cafleet CLI
cafleet setup --skip claude --skip codex --skip opencode   # migrate the database schema only (idempotent)

mise //cafleet:lint       # ruff check + ruff format --check
mise //cafleet:format     # ruff check --fix + ruff format
mise //cafleet:typecheck  # ty
mise //cafleet:test       # pytest

mise //admin:build        # build the WebUI (required before / is served)
mise //admin:dev          # WebUI dev server (Vite)
mise //admin:install      # reinstall WebUI deps from the committed lockfile

To change the WebUI's dependencies, edit admin/package.json and run plain bun install inside admin/ to regenerate admin/bun.lock — mise //admin:install installs with --frozen-lockfile and cannot update the lockfile.

Installing the skills from your checkout¶

cafleet setup installs the assets from a published Release, so it is the end-user (installed-CLI) path. Contributors working from a clone install the skills from the working tree instead:

mise //:skill-install

This runs gh skill install ./ --from-local --agent <backend> --force --scope user for each of the three backends (claude-code, codex, opencode), placing the skills from your checkout (not a Release) into the three agent homes.

Building docs locally¶

Build the documentation site (this site) locally with:

mise //:docs-build

That task is a thin wrapper around uv run zensical build --clean and is the same command the GitHub Actions workflow runs.

Contributing changes¶

CAFleet uses its own design-doc-driven development skills to evolve the codebase. Some tips for new contributors:

1. Invoke the cafleet-design-doc skill (create workflow) with a one-line description — orchestrates a Director / Drafter / Reviewer team to produce a design doc under design-docs/NNNNNNN-<slug>/.
2. Invoke the cafleet-design-doc skill (interview workflow) with the path design-docs/NNNNNNN-<slug> — fine-grained Q&A pass that annotates the doc with COMMENT(user-relay) markers for the create workflow's resume mode to absorb.
3. Invoke the cafleet-design-doc skill (execute workflow) with the path design-docs/NNNNNNN-<slug> — TDD-cycle implementation pass (Director / Programmer / Tester / optional Verifier, plus a fresh Reviewer at review time).

See your coding-agent's skill documentation for the literal invocation syntax. Existing design documents under design-docs/ are real examples produced by this loop.

Documentation style¶

When editing docs/ or README.md, follow these conventions:

• Audience split: docs/ is written for human developers and operators; skills/ is written for coding agents. Do not mix the registers.
• Voice: second person ("you"), active voice, present tense. Lead each page with what the reader accomplishes, not with architecture.
• Terms: link a term's first use on a page to the Core terms table in the concepts overview; do not re-define it.
• Examples: every CLI example is a runnable command using the standard sample-id cast — fleet 1, root Director 2, members 3+ — followed by an expected-output block matching the output shapes in CLI options. Never use shell variables to hold ids.
• SSOT: one fact, one home. When another page needs the fact, link; when a fact serves no install/configure/use/understand purpose, delete.