AgentCLI Task System

A lightweight, static, file-based task management system embedded directly in the repository. Tasks are permanent history — once created, they are never deleted. This system exists to help AI agents and humans manage project complexity with a simple CLI that needs no database, no server, and no internet.

This is separate from any runtime/ephemeral task tools you may have. Those are temporary — they disappear when the session ends. This task system lives in the repository. Its tasks are kept forever.

Core Philosophy

• Static, file-based, in-repo — Three files in tasks/: inbox.md, tasks.yaml, closed.yaml. No database, no service, no setup beyond tasks init.
• Tasks are permanent history — Nothing is ever deleted. Tasks flow from tasks.yaml (active) to closed.yaml (archive). Once a task is created, its record persists for the life of the repository.
• Purpose: manage project complexity — Track what needs doing, what is in progress, what is done. Keep the agent and human aligned on priorities without losing context across sessions.
• 12 statuses, any lifecycle — Tasks can hold any of 12 statuses: todo, in-progress, done, blocked, postponed, cancelled, review, waiting, parked, deferred, backlog, abandoned. You move between them freely with tasks update --status <name> — there are no restrictions on transitions.
• Counter-based IDs — Tasks get TSK-NNNN IDs (e.g. TSK-0001). Auto-incrementing, no gaps are guaranteed (skipped IDs on concurrent writes are acceptable).
• Newest-first ordering — Recent tasks appear at the top of the active list. Closed tasks are oldest-first (chronological append).
• Growing complexity only when needed — The system intentionally started minimal. New features are added only when a real need emerges.

⚠️ Golden Rule: YAML files are CLI-only. Inbox.md is free-form.