ai-todo / rules

---
description: "Development workflow for ai-todo (Python/MCP)"
alwaysApply: true
---
# Development Workflow

**Primary Language:** Python 3.14+
**Primary Interface:** MCP Server

## Repository Context

-   **Root:** `ai_todo/` (Python package source)
-   **CLI Entry:** `ai_todo/cli/main.py`
-   **MCP Entry:** `ai_todo/mcp/server.py`
-   **Core Logic:** `ai_todo/core/` (Shared logic for CLI and MCP)

## Development Rules

1.  **Python First:** All new features must be implemented in the Python package (`ai_todo/`).
2.  **File Operations:** ALWAYS use `ai_todo.core.file_ops.FileOps` for reading/writing `TODO.md`.
    -   This class handles checksums, shadow copies, and atomic updates.
    -   **NEVER** use `open()` or `write()` on `TODO.md` directly.
3.  **Linting:**
    -   After editing Python files, run `uv run ruff check <file>` explicitly.
4.  **Testing:**
    -   Run unit tests: `uv run pytest`
    -   Test MCP tools via the MCP Inspector or Cursor.
5.  **Installation/Migration:**
    -   Installation logic resides in `ai_todo/cli/system_ops.py` (or dedicated modules).
    -   Migrations are handled by `ai_todo.core.migrations`.
6.  **Development Methodology:**
    -   Whenever you are asked to develop something, always create subtasks that cover:
        analysis, design, implementation, creating unit and integration tests, verify and document
    -   Whenever you are working on analysis or design always create a document with the findings and
        options and stop for human review and approval. Always add the file link to the description
        of the task or sub task that created it.
    -   Use the task and subtask descriptions to provide high level summaries of the individual steps
    -   Use tags to categorize individual steps

## File Integrity & Tamper Detection

ai-todo uses a simple tamper detection system to protect `TODO.md` integrity.

-   **State Directory:** `.ai-todo/state/` contains critical integrity files (checksums, shadow copies).
-   **RESTRICTION:** This directory is **OFF LIMITS** to agents. Never read, write, or modify files in this directory directly.
-   **Tamper Mode:** Configured in `config.yaml` (`security.tamper_proof`).

**Developer Warning:** Never edit `TODO.md` manually during development unless you are specifically testing the tamper detection logic.