# lazytask (`lt`)
A task manager built for the age of AI coding agents.
Tasks live as plain markdown files on disk visible to humans, readable by `grep`, and trivially diffable in git. AI agents operate through a strict CLI with stable JSON envelopes. Humans get a keyboard-driven TUI. Both interfaces share the same storage and rules: no sync, no server, no database.
The design principle is **sophisticated simplicity**: if you can't do it on a whiteboard, you can't do it in lazytask. Tight WIP limits force focus, flat-file storage ensures observability, and a minimal command surface keeps agent behavior predictable.
## How it works
Tasks normally flow through three primary status buckets, each a directory:
- `.tasks/todo/` — todo (max 20)
- `.tasks/in-progress/` — active work (max 3)
- `.tasks/done/` — completed
- `.tasks/discard/` — optional side bucket for intentionally excluded/irrelevant tasks (not part of normal completion flow)
Each task is a single `.md` file that moves between directories as its status changes. This makes state changes visible in `git diff` and file explorers without any tooling.
When agents complete tasks, they record learnings. `lt learn` surfaces unconsumed learnings so agents can reflect and propose improvements to docs, workflows, or code.
## Command surface
Human entry points:
- `lt` — opens the TUI (requires TTY)
- `lt init` — creates `.tasks` layout + appends agent guidance to `AGENTS.md`/`CLAUDE.md`
- `lt init --upgrade` — refreshes generated `lazytask.toml` + AGENTS guidance defaults without overwriting `.tasks/`
AI commands (see xml tag below).
## Important documents/files
- `src/tui/` Terminal User Interface implementation
- `src/config/` single authority for runtime config/constants, workspace-root config loading, internal defaults, and prompt assets under `src/config/prompts/`
## Project map
- `src/domain/` core task models, validation, and shared formatting/parsing helpers
- `src/storage/` markdown task file IO, bucket layout, and persistence mechanics
- `src/services/` task workflows and business rules on top of storage
- `src/cli/` clap command parsing and JSON output envelopes for AI usage
- `src/tui/` keyboard-driven terminal UI (actions, app state, rendering, components)
- `src/config/` runtime config loading/defaults and prompt assets
## Path handling
- `lt init` writes generated artifacts (`.tasks/`, `lazytask.toml`, and AGENTS guidance) at the workspace root that `lt` resolves.
- When `lazytask` runs inside a project, workspace root resolves to the nearest `.git` ancestor if present; otherwise it uses the current working directory.
## Taskfile.yml
This project uses taskfile for commands. Examples:
```sh
task fix # Linting and formatting. Use frequently
task test # Full test suite
```
## Engineering rules
- When developing and experimenting, use e.g. `cargo run -- create --help`
- Layers stay separate: domain, storage, services, CLI, TUI.
- No hidden magic in mode switching. TTY = TUI, non-TTY = JSON error with guidance.
- No backwards compatibility — move fast, keep the surface small.
- Keep code lean and DRY.
- Keep non-test Rust modules small: target `<200` lines of production code per file.
- Structure larger areas as directory modules with a thin `mod.rs` entrypoint and focused behavior files (e.g. parsing, IO, dispatch, rendering).
- Hard rule: Do not "whack-a-mole" fix things. Understand the larger scope before fixes.
## Testing guardrails
- Default to TDD for non-trivial changes.
- Prefer integration/e2e tests over mock-heavy unit pyramids.
- Keep assertions intentional and minimal.
- Split large test cases before shipping.
## Collaboration rules
- All `CLAUDE.md` files are symlinks to `AGENTS.md`. Only ever edit `AGENTS.md`.
lazytask `lt` usage guide for agents below.
!!IMPORTANT: This project develops lazytask itself. As such use `cargo run --` not `lt`.
The instructions below are generated by `cargo run -- init`
Bad: `lt create ...`
Good: `cargo run -- create ...`
Do not edit code within tags below.
<EXTREMELY_IMPORTANT>
ALWAYS use lazytask (`lt`) for task and bug tracking in this project.
Check existing tasks before starting work (`lt list`). Track all non-trivial work as tasks.
Do NOT create tasks for very quick few-line fixes
Task titles: ~5 words, imperative, specific (e.g. "Add retry logic to API client").
Task details (3-10 sentences): current behavior, expected behavior, and relevant code (`api/auth.py` style paths).
Don't repeat the title. Include enough context that work can start without a research phase.
Commands (all return JSON):
lt list [--type task|bug] [--show-done]
lt get '<title>' ['<title2>' ...]
lt done '<title>'
lt discard '<title>' --discard-note '<short why>' # won't do
lt learn '<title>' --learning '<text>'
lt learn --review
After `lt done`, follow the `next_step` field in the response to capture learnings.
When `lt learn --review` prompts a review, follow its instructions to convert learnings into project improvements.
</EXTREMELY_IMPORTANT>