daruma: Instructions file for Codex

Guidelines for AI Coding Agents (AGENTS.md)

Welcome, agent. You are tasked with maintaining or extending Daruma (the contextual lesson-learned MCP). Please adhere to the following tactical guidelines to ensure code quality, system safety, and strict alignment across development cycles.

---

CRITICAL INSTRUCTION: Dynamic Documentation Updates

[!IMPORTANT] As features, CLI flags, database schemas, or resolver logic are updated or added, you MUST immediately update both README.md and AGENTS.md. Do not leave files lagging behind the actual implementation. State clearly in your PR or walkthrough what updates were made to these documents.

---

Technical Design Overview

Daruma resolves a developer's directory path into a multi-layered, prioritized coordinate:

1. Component Layer ((repo, component)): Folder containing descriptor files like go.mod or cargo.toml in the repository tree.
2. Repository Layer ((repo, 'root')): Root of the repository containing .git or .jj.
3. Technology Layer (tech): Detected tech stack (e.g. go, rust, python, typescript, docker) based on markers.
4. Global Layer ('global', 'global'): General, project-agnostic development patterns.

Storage Rules

• Database resides at ~/.local/share/daruma/daruma.db.
• Database Concurrency: The SQLite connection must enable WAL (Write-Ahead Logging) mode and use a normal sync flag. This ensures readers do not block writers and vice-versa, allowing safe multi-process local execution.
• Pure Functions: Ensure database and resolver functions are designed as pure, side-effect-free, easily mockable functions.

Version Control Agnosticism

• Daruma supports standard Git and Jujutsu (jj).
• Check if .jj is present in the ancestor tree. If so, invoke jj CLI wrappers instead of git for remote and log operations.

---

Coding Guidelines

1. Test-Driven Design:
   • Every core resolver or database capability must have dedicated pytest tests.
   • Use pytest parameterized tests (pytest.mark.parametrize) to enforce exhaustive boundary and type coverage.
2. Type Hinting: All Python code must utilize modern type annotations (typing.Tuple, typing.Optional, typing.List, etc.).
3. Dependency Management: Use uv add to inject external dependencies. Keep dependencies strictly to the bare minimum (mcp, click, pytest is the default).
4. CLI Development: The CLI tool (daruma) must wrap $EDITOR safely. It should write templates to temporary Markdown files and retrieve them only after the process exits successfully.