{"id":49073368,"url":"https://github.com/tim-projects/tasks-ai","last_synced_at":"2026-04-20T08:30:45.167Z","repository":{"id":346951701,"uuid":"1173707989","full_name":"tim-projects/tasks-ai","owner":"tim-projects","description":"Use BRUTE FORCE to ship code using light LLM models with AI-powered git-backed project management: state machines, quality gates, audit trails - all in your repo","archived":false,"fork":false,"pushed_at":"2026-04-18T13:44:40.000Z","size":7981,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T14:40:28.736Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tim-projects.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-05T17:00:10.000Z","updated_at":"2026-04-18T14:12:13.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tim-projects/tasks-ai","commit_stats":null,"previous_names":["tim-projects/tasks-ai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tim-projects/tasks-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tim-projects%2Ftasks-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tim-projects%2Ftasks-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tim-projects%2Ftasks-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tim-projects%2Ftasks-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tim-projects","download_url":"https://codeload.github.com/tim-projects/tasks-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tim-projects%2Ftasks-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32039847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"online","status_checked_at":"2026-04-20T02:00:06.527Z","response_time":94,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-20T08:30:42.756Z","updated_at":"2026-04-20T08:30:45.158Z","avatar_url":"https://github.com/tim-projects.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ship Faster with AI-Powered Git-Backed Project Management\n\n`tasks` gives your project a complete project management system that dones IN your repo. State machines, quality gates, audit trails, full automation - all powered by git worktrees, designed for AI agents.\n\n## 🚀 One-Line Install\n\n### Local (No Sudo)\nInstalls to `~/.local/bin/tasks`.\n```bash\ncurl -sSL https://raw.githubusercontent.com/tim-projects/tasks/main/install.sh | bash\n```\n\n### System-Wide (Global)\nInstalls to `/usr/local/bin/tasks`.\n```bash\ncurl -sSL https://raw.githubusercontent.com/tim-projects/tasks/main/install.sh | sudo bash -s -- -g\n```\n\n## 🛠️ Getting Started\n\nTo enable autonomous task management in your project, add the following directive to your `AGENTS.md` file:\n\n\u003e **Directive**: \"Manage project tasks using the `tasks` command. Run `tasks -h` to discover the interface and operational protocol.\"\n\nThe agent will then autonomously:\n1. Initialize the system (`tasks init`)\n2. Discover or create tasks (`tasks list` / `tasks create`)\n3. Manage work-in-progress and promotions through the Git-native state machine\n\n## The Problem\n\nAI agents working on code need to know what exists, track progress, meet quality gates, handle blockers, and report results reliably. Without structure, they improvise, skip steps, lose track, and can't communicate status.\n\n## The Solution\n\n`tasks` gives you a deterministic state machine with quality gates. Agents follow the lifecycle, meeting criteria at each step before advancing - no shortcuts, no surprises.\n\n### The State Machine\n\n```\nBACKLOG → READY → PROGRESSING → TESTING → REVIEW → STAGING → DONE → ARCHIVED\n                                          ↓        ↑\n                                     (regression check needed)\n                                          ↓\n                                     (back to fix if fails)\n```\n\nEach transition has rules:\n- Can't move to PROGRESSING without complete story/tech/criteria/plan\n- Can't move to TESTING without passing your own verification\n- Can't move to REVIEW without tests passing and branch pushed\n- **Can't move to STAGING without passing regression check (Rc)** — review diff at `.tasks/review/\u003cid\u003e/diff.patch`, if regressions found move task back to PROGRESSING/TESTING to fix\n- Can't move to DONE without being merged to main\n- Can't move to ARCHIVED without merged to main (or REJECTED)\n\n## Why It's Different\n\n| Instead of... | tasks gives you... |\n|--------------|-------------------|\n| Scattered notes \u0026 PR comments | Everything in one place, git-backed |\n| Manual status updates | State machine with enforced gates |\n| Lost context when switching tasks | Full audit trail, every change logged |\n| Wondering \"what's ready to ship?\" | Clear pipeline: testing → staging → done |\n| No parallel agent coordination | Atomic IDs, branch-per-task, blockers |\n| Disconnected tooling | Integrated: lint, test, typecheck, format - all in one command |\n| Fragile project state | Self-healing: auto-restore from remote |\n\n## Commands Overview\n\n### Task Management\n\n```bash\ntasks init                          # Initialize task system\ntasks list                          # List all tasks with Id, Priority, Summary\ntasks create \"Task title\"           # Create new task (requires 10+ char title)\ntasks create \"Issue title\" --type issue --repro \"Steps to reproduce\"\ntasks show \u003cid\u003e                     # Show full task details\ntasks show \u003cid\u003e story               # Show only story section\ntasks show \u003cid\u003e progress            # Show active progress notes\ntasks current                       # Show active task\ntasks checkpoint                    # Sync commits/notes to task record\n```\n\n### State Transitions\n\n```bash\ntasks move \u003cid\u003e PROGRESSING         # Start working (creates branch)\ntasks move \u003cid\u003e TESTING             # Move to testing\ntasks move \u003cid\u003e REVIEW              # Move to review\ntasks move \u003cid\u003e STAGING             # Move to staging\ntasks move \u003cid\u003e DONE                # Move to done (requires merged to main)\ntasks move \u003cid\u003e ARCHIVED -y         # Archive (pushes branch, deletes local)\n\n# Multi-step moves - chain multiple states\ntasks move \u003cid\u003e READY,PROGRESSING,TESTING  # Backlog to Testing in one command\n```\n\n### Dependencies \u0026 Links\n\n```bash\ntasks link \u003cid\u003e \u003cblocker-id\u003e        # Block task until blocker resolved\ntasks unlink \u003cid\u003e \u003cblocker-id\u003e      # Remove blocker relationship\n```\n\n### Modification\n\n```bash\ntasks modify \u003cid\u003e --story \"...\"     # Update story\ntasks modify \u003cid\u003e --plan \"1. Step\"  # Update implementation plan\ntasks modify \u003cid\u003e --priority 1      # Change priority\ntasks modify \u003cid\u003e --regression-check # Mark regression check as passed (enables STAGING)\ntasks undo \u003cid\u003e                     # Undo last operation on task\n```\n\n### Cleanup \u0026 Maintenance\n\n```bash\ntasks cleanup --dry-run             # Preview what would be cleaned\ntasks cleanup                       # Clean merged branches, push to remote, delete local\ntasks reconcile                     # Scan for tasks with merged branches (dry-run)\ntasks reconcile --all               # Clean up merged branches and archive tasks\ntasks doctor                        # Diagnose task data and git state\n```\n\n### Development Tools\n\n```bash\ncheck lint                      # Run linter\ncheck test                      # Run tests\ncheck typecheck                 # Run type checker\ncheck format                    # Run formatter\ncheck all                       # Run all checks\ncheck lint --fix               # Auto-fix lint errors\n```\n\n### Validation \u0026 Tools\n\n```bash\ntasks run lint                      # Run linter (config: repo.lint)\ntasks run test                      # Run tests (config: repo.test)\ntasks run typecheck                 # Run type checker (config: repo.type_check)\ntasks run format                    # Run formatter (config: repo.format)\ntasks run all                       # Run all checks\n\ntasks config list                   # Show current configuration\ntasks config detect                 # Auto-detect project tools\ntasks config set repo.test pytest   # Set test tool\n```\n\n### Repository Integration\n\n```bash\nrepo merge \u003csrc\u003e to \u003ctarget\u003e  # Merge with compliance checks\nrepo promote \u003cid\u003e            # Promote through pipeline: testing → staging → main\nrepo sync                    # Sync: testing → staging → main\nrepo status                  # Show current branch and pending changes\nrepo branch list             # List all branches\n```\n\n## Task File Structure\n\nTasks are stored as markdown files with YAML frontmatter:\n\n```yaml\n---\nId: 42\nTi: Fix login bug\nSt: PROGRESSING\nTy: issue\nCr: 2024-01-15\nUp: 2024-01-16\nPr: 1\nLb: [bug, login, security]\n---\n## Story\nAs a user I cannot log in with special characters in password...\n\n## Technical\nThe password validation regex doesn't handle Unicode...\n\n## Criteria\n- [ ] User can log in with any valid password\n- [ ] Invalid passwords show clear error message\n\n## Plan\n1. Update password validation regex\n2. Add tests for Unicode passwords\n3. Update error messages\n\n## Progress\n- Found the issue in auth.py line 42\n- Created fix, running tests\n```\n\n## Workflow Example\n\n```bash\n# Agent initializes on first run\ntasks init\n\n# Agent creates work with full specification\ntasks create \"Add user login\" \\\n  --story \"As a user I want to log in...\" \\\n  --tech \"Use OAuth2 with GitHub provider...\" \\\n  --criteria \"User can log in with GitHub\" \\\n  --plan \"1. Register OAuth app\" \"2. Implement OAuth flow\" \"3. Add session management\"\n\n# Agent starts working (creates branch automatically)\ntasks move 1 PROGRESSING\n\n# Agent writes progress notes and checkpoints\n# ... work happens ...\ntasks checkpoint\n\n# Agent verifies and moves to testing\ntasks run test\ntasks move 1 TESTING\n\n# Agent moves to review (auto-generates diff, requires regression check)\ntasks move 1 REVIEW\n\n# Agent reviews .tasks/review/1/diff.patch for regressions\n# If regressions found, task moves back to PROGRESSING/TESTING to fix:\ntasks move 1 PROGRESSING  # Fix issues\n\n# Once clean, agent marks regression check passed\ntasks modify 1 --regression-check\n\n# Now can promote to staging\ntasks move 1 STAGING\n\n# Once PR merged to main, archive\ntasks move 1 ARCHIVED -y\n```\n\n## Regression Check\n\nWhen a task enters REVIEW, the system automatically generates a unified diff patch at `.tasks/review/\u003ctask_id\u003e/diff.patch`. This diff includes:\n- All commits on the task branch that are not in `main`\n- Any unstaged working tree changes\n\n**Agent workflow:**\n1. On `REVIEW` entry, read the diff file\n2. Inspect for potential regressions, breaking changes, or unwanted side effects\n3. If regressions found → move task back to `PROGRESSING` or `TESTING` for fixes\n4. If diff is clean → run `tasks modify \u003cid\u003e --regression-check` to mark as passed\n5. STAGING promotion is blocked until `--regression-check` is confirmed\n\nThis gate ensures code with regressions never reaches STAGING.\n\n## Why This Over Alternatives?\n\n- **No external services** - Everything in your repo\n- **No setup** - Single Python file, zero deps\n- **Git-native** - Leverages existing infrastructure\n- **Enforced quality** - Can't bypass gates\n- **Agent-optimized** - JSON output, clear protocols, deterministic behavior\n- **Full project lifecycle** - From backlog to done with proper gates\n- **Self-healing** - Auto-restore branches, circular dependency prevention\n- **Comprehensive audit** - Activity logging, undo, checkpoint\n\n## Configuration\n\nTasks auto-detects your project's tools. Configure manually:\n\n```bash\ntasks config set repo.lint ruff\ntasks config set repo.test pytest\ntasks config set repo.type_check pyright\ntasks config set repo.format ruff\n```\n\n## Documentation\n\n- [TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) - Common issues and solutions\n- [AGENTS.md](AGENTS.md) - Agent directives and protocols# test\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftim-projects%2Ftasks-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftim-projects%2Ftasks-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftim-projects%2Ftasks-ai/lists"}