Dot Development

Develop Dot

Change the Python CLI while retaining its observable command, archive, and installation contracts. [dot-cli](../../../skills/dot-cli/SKILL.md) owns operating the installed tool; [python-stack](../../../skills/python-stack/references/foundation/GUIDE.md) and [cli-contracts](../../../skills/cli-development/references/cli-contracts.md) own generic implementation and interface design.

Workflow

1. Find the owner: inspect git status --short, git diff, and git diff --cached, then follow the source/test map below. Read the current implementation before selecting a change boundary.
2. Define the observable change: preserve command names, aliases, help, JSON output, exit codes, stdout/stderr, and Fish completions unless the task explicitly changes them. Exercise configuration errors through the public CLI; repair commands must remain usable when ordinary config loading fails.
3. Implement through existing boundaries: reuse State and Runner for configuration, streams, and external commands. Use temporary homes and fake runners in tests so a CLI regression cannot authenticate, publish, prune real data, or modify the workstation.
4. Select proof: run relevant existing tests with uv run --frozen pytest -q dot/tests/.py; add behavioral cases for changed outcomes and realistic failures. Read [session compatibility](references/session-compatibility.md) before changing parser output, replacement rules, or stored formats.
5. Qualify the candidate: run affected static checks and reuse the focused test results above. Follow project AGENTS.md for the full-gate boundary: shared behavior, dependencies, packaging, or explicit full qualification. Isolate write-formatting checks when unrelated work is present and compare the tested candidate with the intended source before transferring proof or edits.
6. Verify the right executable: use uv run --frozen dot for checkout behavior. When installation is in scope, mise run deploy builds and selects the installed runtime; verify dot --version and the changed installed command separately. mise run verify is workstation health, not repository qualification.

Source and test map

• cli.py, command_group.py, state.py, and config.py: command discovery, configuration, and public errors; test_cli.py and test_config.py exercise the boundary.
• private_files.py: shared private-directory creation and atomic writes; test_private_files.py covers permissions, failed publication, and temporary-file cleanup.
• secrets.py: explicit credential loading and PyPI publishing; test_secrets.py covers precedence, private files, rejected overrides, child I/O, and native login preservation. Keep fixtures synthetic and never print credential values.
• auth.py and workstation.py: login, setup, cache inspection, and confirmed cleanup; test_workstation.py uses synthetic provider probes. Never run real login/setup/prune as a validation gate.
• repository.py, process.py, and system.py: repository concurrency, subprocess cancellation, completions, and workstation checks; use their matching tests and temporary homes.
• archive/parsers.py, sync.py, store.py, usage.py, pricing.py, and statistics.py: discovery, incremental capture, the session store, request accounting, subscription periods, and prompt statistics. test_archive_transaction.py covers replacement, usage retention, and the retired v2 store refusal; test_usage_periods.py covers deduplication, model changes, date boundaries, and legacy recapture; test_pricing.py covers cache accounting and unknown rates.
• agent_doctor.py and hooks.py: per-agent notify hooks, sync, and archive checks, plus notification payloads; test_agent_doctor.py and test_agent_hooks.py exercise them.

Documentation

• [Project tasks](../../../mise.toml) and [package configuration](../../../dot/pyproject.toml) own the actual gate and dependency graph.
• Releases: fmind/dot · changelog
• Companion skills: [chezmoi](../chezmoi/SKILL.md) (managed configuration), [dot-release](../dot-release/SKILL.md) (release lifecycle), [systematic-debugging](../../../skills/systematic-debugging/SKILL.md) (unknown failures).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fmind
• Source: fmind/dot
• License: MIT
• Homepage: https://fmind.dev

Install and usage instructions live in the source repository linked above.