Kitaru Dev

Kitaru Development, CLI, and PR Workflow

Use this when you need the command catalog beyond the daily loop in the root AGENTS.md, or when adding CLI commands, analytics events, or PR descriptions.

Python Workflows

• uv sync: install the base SDK and development dependencies
• uv sync --extra cli: include the optional CLI
• uv sync --extra mcp: include the optional native MCP server
• uv sync --extra server: include server components
• uv sync --extra worker: include worker components
• uv sync --extra otel: include OpenTelemetry integrations
• just check: run formatting, lint, OpenAPI freshness, changelog fragments, typecheck, typos, YAML, actions lint, and links
• just openapi-check: verify that the committed OpenAPI specification matches the application schema
• just changelog-check: validate the changelog fragments under changelog.d/
• just fix: auto-fix formatting, lint issues, and YAML
• just test: run the full pytest suite
• just test tests/test_file.py::test_name: run one targeted test
• just lint: lint only
• just typecheck: type check only
• just typos: typo check only
• just format-check: check formatting without modifying files
• just yaml-check: check YAML formatting
• just actions-lint: lint GitHub Actions workflows; requires actionlint
• just zizmor: audit GitHub Actions workflow security with zizmor
• just audit: audit Python dependencies with pip-audit and the documented ignore list
• just links: check Markdown links offline; requires lychee
• just links-external: check links including external URLs; slow
• just example-coverage-audit: validate examples/example-coverage.yaml metadata and waivers
• just build: build wheel and sdist locally
• just cli-artifact-smoke: verify clean CLI wheel and source installations
• just plugin-artifact-smoke: build every default-plugin wheel, load its configured entrypoints, and verify default registration
• just mcp-schema-check: verify public MCP registry budgets and committed snapshots
• just mcp-wheel-smoke: verify clean base and [mcp] installs from the wheel under dist/
• just migration-check: compare Alembic migrations with the ORM schema; requires PostgreSQL

There is no v2 kitaru init command or local extra. Do not carry the v1 .kitaru/ project-marker setup into v2 instructions or tests.

When resolving pyproject.toml or uv.lock conflicts, do not regenerate the whole lockfile: that silently reverts intentional dependency-security bumps. Upgrade only the packages involved and run just audit before pushing.

New Distribution Integration Review

Before opening a PR that creates an independently published package, trace how it will be built, installed, discovered, and released. This applies to a new adapter, importer, evaluator, or other Python distribution; adding an evaluator inside the existing kitaru-evaluator wheel does not create a new distribution. For substantial packages, ask a bounded independent subagent to review the integration points and omissions, then verify its findings against the code. Record the applicable paths and any deliberate exclusions in Reviewer Notes or Release context so a reviewer can check the complete package path.

• Add the package manifest, source, tests, README, changelog, plugin workspace lock entry, and a row in plugins/README.md. Add artifact import metadata for a non-default package, and check whether plugins/pyproject.toml needs an update.
• Add every new Python distribution to release/release-units.toml and the expected inventory in tests/scripts/test_release_units.py. Check that the release workflow and CI matrix discover it; edit fixed selections only when they actually exclude the new package.
• Add every new PyPI kitaru-* distribution to src/kitaru/worker/process.py::_FIRST_PARTY_KITARU_PACKAGES, including packages outside the default server catalog. Run the inventory-based test in tests/worker/test_process.py; the server catalog is not the worker's package list.
• Decide separately whether the server should offer the package by default. Set default-catalog in the release inventory accordingly, and change DEFAULT_PLUGIN_DEFINITIONS and its tests only for an approved default. Do not add adapters to the server catalog.
• Inspect package-specific selections and exclusions, including candidate-wheel builds, example dependencies, and the quickstart's --no-install-package list in .github/workflows/ci.yml. There is no global plugin ignore list; those exclusions apply to their particular example or build. Update them only when the new package enters that path.
• Check the required core version, release order, documentation, and runnable examples. For worker-installed exact pins, test candidate-wheel resolution with a cutoff predating the package, verify that supported uv accepts the package exception, and verify that older uv retains the prior command and warns. Only a postpublication registry install proves the published wheel resolves under that cutoff. Run the focused package tests, release-inventory test, and just plugin-artifact-smoke before handoff.

Use plugins/DEVELOPMENT.md for package and candidate-server commands, and the kitaru-release skill for version selection and publication. Do not treat registration metadata or a local wheel as proof that the published package can be installed by a worker.

Docs Workflows

These require Node 22+ and pnpm.

• just docs: preview docs locally at localhost:3000
• just docs-build: build the static docs export
• just docs-validate: validate the export as served under /docs
• just generate-docs: regenerate the SDK and CLI reference content

scripts/generate_sdk_docs.py extracts the v2 SDK reference through a PUBLIC_API allowlist. Edit that allowlist and tests/scripts/test_generate_sdk_docs.py together; the test compares each published module against its __all__. The generator needs the fumapy bridge after installing the docs dependencies. scripts/generate_cli_docs.py generates CLI reference content from the offline kitaru schema contract rather than a hardcoded command list.