Imported from vangberg/pdit (AGENTS.md). Install upstream with npx skills add vangberg/pdit. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

• pdit/ contains the FastAPI backend, CLI, and execution engine; pdit/_static/ holds built frontend assets for local runs.
• fe/ contains the Vite/React frontend source (TypeScript).
• tests/ contains Python tests; frontend tests live alongside the frontend in fe/.
• examples/ contains sample scripts for manual runs and demos.

Build, Test, and Development Commands

• uv sync --dev installs Python dependencies and dev tools.
• uv run pdit script.py runs the server and opens the editor on port 8888.
• uv run honcho start runs backend + frontend with hot reload (recommended).
• cd fe && npm run build builds frontend assets into pdit/_static/ for local verification.
• uv run pytest runs Python tests; cd fe && npm test runs Vitest and starts a backend automatically with token auth disabled.

Coding Style & Naming Conventions

• Python is formatted with Black (line length 100) and linted with Ruff; keep new code consistent.
• Type hints are required for new Python functions (mypy is strict with disallow_untyped_defs).
• Use snake_case for Python modules/functions and PascalCase for React components (e.g., Editor.tsx).

Testing Guidelines

• Pytest naming: tests/test_*.py, Test* classes, test_* functions (configured in pyproject.toml).
• Example targeted run: uv run pytest tests/test_server.py::test_health -v.
• Frontend tests use Vitest: cd fe && npm test (auto-starts backend with token auth disabled).

Commit & Pull Request Guidelines

• Commit messages are short, imperative, and sentence case (e.g., “Remove uv.lock from version control”).
• Use jj for version control workflows (git-compatible).
• PRs should include a concise summary, test results, and screenshots for UI changes.

Notes for Contributors

• Built assets in pdit/_static/ are not versioned; do not commit build output.

Ticks

This project uses tk for issue tracking. Use ticks for work that spans sessions, has dependencies, or is discovered during other work. Use TodoWrite for simple single-session tasks.

Essential commands:

tk next                  # next ready tick
tk next EPIC_ID          # next ready tick in epic
tk create "title"        # create issue
tk update ID --status in_progress
tk note ID "message"     # log progress
tk close ID              # mark done

Dependencies & epics:

tk next --epic           # next ready epic
tk block ID BLOCKER_ID   # ID is blocked by BLOCKER_ID
tk create "task" --parent EPIC_ID
tk update ID --parent EPIC_ID  # move to epic

Agent-Human workflow:

tk update ID --awaiting approval   # hand off to human
tk update ID --awaiting=           # return to agent queue

Awaiting states: work, approval, input, review, content, escalation, checkpoint. Use --requires approval at creation for tasks needing sign-off before close.

Commands show your ticks by default. Use --all to see everyone's (e.g. tk next --all).

All commands support --help for options.