vibe-async-task-queue
npx machina-cli add skill ash1794/vibe-engineering/async-task-queue --openclawvibe-async-task-queue
Not everything needs to be done right now. But "I'll do it later" only works if "later" actually happens.
When to Use This Skill
- You identify work that should be done but isn't blocking the current task
- During code review, you find issues that aren't urgent
- Tests reveal non-critical flakiness
- Documentation needs updating but not right now
- "TODO" comments that should become tracked tasks
When NOT to Use This Skill
- Blocking work that must be done now
- Tasks already tracked in an issue tracker (GitHub Issues, Jira, etc.)
- One-off tasks in the current session (just do them)
Queue Format
Tasks are stored in a JSON file at a project-specific location (e.g., .claude/task-queue.json):
{
"tasks": [
{
"id": "vibe-001",
"created": "2026-02-28",
"priority": "medium",
"status": "pending",
"description": "Add error handling to parseConfig edge cases",
"target_files": ["internal/config/parser.go"],
"acceptance": "go test ./internal/config/... -run TestParseConfigEdge -v passes",
"context": "Discovered during fuzz testing session"
}
]
}
Steps
Adding a Task
- Identify the work
- Write a clear description with:
- What needs to be done
- Which files are affected
- How to verify it's done (acceptance command)
- Why it was deferred (context)
- Append to queue file
Processing the Queue
- Read queue file
- Pick highest-priority pending task
- Set status to
in_progress - Do the work
- Run acceptance test
- If pass: set status to
completed, commit - If fail: set status to
pending, add notes about what went wrong
Reviewing the Queue
List all tasks with status counts. Identify stale tasks (>7 days pending).
Output Format
Task Queue Status
Pending: X | In Progress: Y | Completed: Z | Failed: W
| ID | Priority | Description | Age | Status |
|---|---|---|---|---|
| vibe-001 | high | Add auth token refresh | 2d | pending |
| vibe-002 | medium | Fix flaky test in utils | 5d | pending |
Stale Tasks (>7 days)
- [task IDs that need attention or should be closed]
Source
git clone https://github.com/ash1794/vibe-engineering/blob/master/skills/async-task-queue/SKILL.mdView on GitHub Overview
vibe-async-task-queue tracks work that isn’t blocking current tasks and should be done later. It stores tasks in a project-local JSON queue to enable background and future-session tracking, helping teams capture non-urgent issues from code reviews, flaky tests, or documentation updates.
How This Skill Works
Tasks are persisted in a project-local JSON file (e.g., .claude/task-queue.json). New tasks are appended with id, created, priority, status, description, target_files, acceptance, and context. Processing selects the highest-priority pending task, marks it in_progress, executes the work, runs the acceptance test, and then marks it completed or re-pends it with notes if the acceptance fails.
When to Use It
- You identify work that should be done but isn't blocking the current task
- During code review, you find issues that aren't urgent
- Tests reveal non-critical flakiness
- Documentation needs updating but not right now
- "TODO" comments that should become tracked tasks
Quick Start
- Step 1: Identify the work and write a clear description with what to do, affected files, acceptance command, and context for deferral.
- Step 2: Append the task to the project queue file (e.g., .claude/task-queue.json) with id, created, priority, status, description, target_files, acceptance, and context.
- Step 3: Process the queue by reading the file, selecting the highest-priority pending task, updating status to in_progress, performing the work, running acceptance, and marking as completed or re-pending with notes on failure.
Best Practices
- Write a clear task description with what needs to be done, which files are affected, how to verify it (acceptance command), and why it was deferred (context).
- Store the queue in a project-specific location (e.g., .claude/task-queue.json) and commit changes.
- Use explicit priority and track status transitions (pending -> in_progress -> completed or pending with notes).
- Regularly review stale tasks (pending for more than 7 days) and prune or escalate as needed.
- Avoid duplicating work that’s already tracked in external issue trackers (GitHub Issues, Jira, etc.).
Example Use Cases
- vibe-001 Add error handling to parseConfig edge cases
- vibe-002 Fix flaky test in utils
- vibe-003 Update user guide section on configuration loading
- vibe-004 Address non-blocking TODO comments from code review
- vibe-005 Improve logs for config parsing to aid debugging
