dit-skill

name	dit-skill
description	Teach AI coding assistants how to install, verify, and operate the local dit-commandline CLI in this repository. Use when the task is to run `dit` commands, set up a Dit repository, inspect available CLI commands/options, or choose the right local invocation mode (`uv run dit`, `uv run --package dit-commandline dit`, or plain `dit`).
compatibility	Designed for Claude Code or similar harnesses in this Dit monorepo. Requires Python >=3.12, uv, and git. Git LFS is optional because `dit init --no-lfs` is supported.

Dit skill

What Dit is

Dit is a git-backed document repository engine. The dit-commandline package is the local CLI surface for working with Dit repositories from a terminal.

Scope of this skill

Use this skill to help an AI harness operate the CLI in this repo:

• install and verify the local dit entrypoint
• initialize and inspect Dit repositories
• stage, commit, diff, and inspect history
• manage branches
• run round workflows
• inspect lineage
• check conflicts and run merges

Do not use this skill as a general guide to the whole monorepo, backend service, web app, or architecture layers. Keep the focus on packages/dit-commandline/ and on invoking dit correctly.

Default operating procedure

1. Work from the repo root unless the task clearly targets an already-initialized Dit repository elsewhere.
2. If dependencies may not be installed yet, run uv sync from the repo root.
3. Prefer uv run dit ... for command execution in this workspace.
4. If you need to force the package-scoped entrypoint, use uv run --package dit-commandline dit ....
5. Use plain dit ... only when the environment is already activated and the entrypoint is confirmed to be available on PATH.
6. Verify the CLI is available with uv run dit --help before assuming commands will work.

Invocation modes

Mode	When to use	Example
uv run dit ...	Default in this repo	uv run dit status
uv run --package dit-commandline dit ...	Fallback when you want to target the CLI package explicitly	uv run --package dit-commandline dit round --help
dit ...	Only after confirming the command is already installed/active in the shell	dit log -n 5

CLI surface

Top-level commands:

• init
• add
• commit
• status
• log
• diff
• merge
• conflicts
• branch
• round
• lineage

Top-level utility options:

• --install-completion
• --show-completion
• --help

How to approach common tasks

Install or verify the CLI

• Read references/commands.md and use the install/verification section.
• Default to uv sync followed by uv run dit --help.
• Do not assume the package is published externally; this repo already exposes the dit script from packages/dit-commandline/pyproject.toml.

Start using Dit in a folder

• Use dit init [PATH] to create a repository.
• Use --description when the user wants metadata.
• Use --no-lfs when LFS setup should be skipped or the environment does not support it.
• After init, use add, commit, status, log, and diff for normal repository work.

Run a round workflow

• Register departments first with dit round add-dept.
• Start a round with dit round start.
• Use --dispatch-mode parallel|sequential|hybrid as requested.
• Use dit round status, done, skip, list, and close to drive the lifecycle.
• For exact syntax and a smoke flow, read references/commands.md.

Inspect history and lineage

• Use dit log for commit history.
• Use dit lineage show <file> for document history.
• Use dit lineage who <file> to see authors who touched a file.

Manage branches and merges

• Use dit branch to list branches.
• Use dit branch create|switch|delete for branch operations.
• Use dit conflicts before or during round merge work.
• Use dit merge <branch> to merge a named branch, or dit merge --round <n> / dit merge for round-oriented merge flows.

Common pitfalls

• If dit is not found, do not guess at packaging. Run uv sync, then retry with uv run dit --help.
• If a command fails because the current directory is not a Dit repository, initialize one with dit init or change to the correct repository directory.
• dit commit requires --message/-m unless the caller intentionally wants an empty commit with --allow-empty.
• dit round start needs departments: either register them first with dit round add-dept or pass repeatable --dept/-d values.
• Only one active round is allowed at a time.
• dit round close requires all assignments to be done or skipped.
• Prefer PowerShell examples when showing commands to the user in this repo.

When to load the reference file

Read references/commands.md when you need:

• exact installation/setup commands
• the supported command list and option syntax
• ready-to-run PowerShell examples
• a manual smoke flow for basic repository work or round lifecycle checks

Validation

If you changed the CLI package or want to verify command behavior, run:

uv run --all-packages pytest .\packages\dit-commandline\tests

Then do a manual smoke flow with the local dit entrypoint from references/commands.md.