agents

AGENTS.md

@@ -1,160 +0,0 @@
-# AGENTS.md
-
-Guidance for coding agents working in this repository.
-
-## Project at a glance
-- Language: Python
-- Package layout: `src/flow/`
-- Tests: `tests/` with `pytest`
-- Build backend: Hatchling (`pyproject.toml`)
-- CLI entrypoint: `flow.cli:main` (`python3 -m flow`)
-- Binary packaging: PyInstaller (`Makefile`)
-
-## Build, test, and validation commands
-
-### Setup
-```bash
-python3 -m venv .venv
-.venv/bin/pip install -e ".[dev]"
-```
-
-### Run CLI locally
-```bash
-python3 -m flow --help
-python3 -m flow --version
-```
-
-### Run all tests
-```bash
-python3 -m pytest
-```
-
-### Run a single test file
-```bash
-python3 -m pytest tests/test_cli.py
-```
-
-### Run a single test function
-```bash
-python3 -m pytest tests/test_cli.py::test_version
-```
-
-### Run a single test class
-```bash
-python3 -m pytest tests/test_commands.py::TestParseImageRef
-```
-
-### Run tests by keyword expression
-```bash
-python3 -m pytest -k "terminfo"
-```
-
-### Build standalone binary
-```bash
-make build
-```
-
-### Install local binary
-```bash
-make install-local
-```
-
-### Smoke-check built binary
-```bash
-make check-binary
-```
-
-### Clean build artifacts
-```bash
-make clean
-```
-
-### Lint/format/type-check status
-- No dedicated lint/format/type-check commands are currently configured.
-- There is no Ruff/Black/isort/mypy config in `pyproject.toml`.
-- Agents must follow existing style and keep diffs readable.
-
-## Code style conventions
-
-### Imports
-- Group imports as stdlib, third-party, then local (`flow.*`).
-- Use explicit imports; avoid wildcard imports.
-- Keep imports at module top unless a local import prevents a cycle or unnecessary load.
-
-### Formatting
-- Use 4 spaces for indentation.
-- Keep lines readable; wrap long calls/literals across lines.
-- Keep trailing commas in multiline calls/lists where helpful for cleaner diffs.
-- Match local quoting style within each file (mostly double quotes).
-
-### Typing
-- Codebase uses gradual typing, not strict typing.
-- Add type hints for new helpers, dataclasses, and public functions.
-- Follow local module style (`Optional`, `Dict`, `List` vs builtin generics).
-
-### Naming
-- `snake_case` for functions, variables, module-level helpers.
-- `PascalCase` for classes/dataclasses.
-- `UPPER_SNAKE_CASE` for constants.
-- Prefix private helpers with `_` when not part of module API.
-
-### Command module patterns
-- Each command module exposes `register(subparsers)`.
-- Subcommands bind handlers via `set_defaults(handler=...)`.
-- Runtime handler signature is typically `(ctx: FlowContext, args)`.
-- Keep parse/plan/execute steps separated when logic grows.
-
-### Error handling
-- Use concise user-facing messages via `ctx.console.error(...)`.
-- Use `sys.exit(1)` for expected CLI failures.
-- Keep `KeyboardInterrupt` behavior as exit `130`.
-- Raise `RuntimeError` in lower-level helpers for domain failures.
-- Avoid noisy tracebacks for normal user mistakes.
-
-### Subprocess safety
-- Prefer `subprocess.run([...], check=True)` when possible.
-- For shell strings, quote dynamic values (`shlex.quote`).
-- Avoid passing unchecked external input into shell commands.
-- Use `capture_output=True, text=True` when parsing command output.
-
-### Filesystem and paths
-- Prefer `pathlib.Path` for path-heavy logic.
-- Expand `~` intentionally when required.
-- Ensure parent dirs exist before write/link operations.
-
-### Tests
-- Add/update tests for behavior changes.
-- Keep tests deterministic and host-independent when possible.
-- Favor focused tests for parser/planner helper functions.
-
-## Architecture notes
-- `src/flow/cli.py`: parser wiring, context creation, top-level exception handling.
-- `src/flow/commands/`: user-facing command implementations.
-- `src/flow/core/`: shared primitives (`config`, `console`, `process`, `stow`, etc.).
-- `FlowContext` holds config, manifest, platform info, and console logger.
-
-## Behavior constraints to preserve
-- Self-hosted config/manifest priority: dotfiles path first, local fallback.
-- Manifest uses `profiles`; legacy `environments` is intentionally rejected.
-- Dotfiles link state supports v2 format only (`linked.json`).
-
-## Cursor/Copilot rule files
-No repository-level rule files were found at the time of writing:
-- `.cursorrules` not found
-- `.cursor/rules/` not found
-- `.github/copilot-instructions.md` not found
-
-If these files are later added, treat them as authoritative and update this guide.
-
-## Workspace hygiene
-- Do not commit generated outputs: `build/`, `dist/`, `*.spec`.
-- Do not commit Python bytecode/cache files: `__pycache__/`, `*.pyc`, `*.pyo`.
-- Keep changes scoped; avoid unrelated refactors.
-- Update tests/docs when user-facing behavior changes.
-
-## Agent checklist before finishing
-- Run targeted tests for touched behavior.
-- Run full suite: `python3 -m pytest`.
-- If packaging/build paths changed, run `make build`.
-- Verify no generated artifacts are staged.
-- Ensure errors are concise and actionable.