Workflow Guides

This section describes common usage patterns that combine the CLI tools and code agent skills into end-to-end development workflows.

Tasks

The full task lifecycle — capturing ideas quickly, wrapping ad-hoc work into tracked tasks, decomposing large items into children, and consolidating overlap.

• Capturing Ideas — Quickly capture task ideas without breaking your flow.
• Retroactive Tracking — Wrap ad-hoc changes into the aitasks framework after the fact.
• Follow-Up Tasks — Creating follow-up tasks, querying existing tasks, and updating them with new findings.
• Creating Tasks from Code — Browse source files, select a line range, and spawn a task pre-seeded with a file reference.
• Task Decomposition — Breaking complex tasks into manageable child subtasks.
• Task Consolidation — Merging overlapping or duplicate tasks into a single actionable task.
• Exploration-Driven — Start with codebase exploration, create tasks from findings.

Parallel

Running multiple tasks side by side, front-loading planning work, and farming out execution to remote web sandboxes.

• Parallel Development — Working on multiple tasks simultaneously with concurrency safety.
• Crash Recovery — Resume a task whose prior agent died mid-implementation, with a survey of leftover work before deciding to reclaim or drop.
• Parallel Planning — Front-load complex task design work while other implementations run in parallel.
• Multi-Project — Coordinate work across linked projects with the project registry and cross-repo task creation.
• Cross-Project Dependencies — Block, read, update, and plan tasks across linked projects with cross-repo dependencies and the --project flag.
• Claude Code Web — Running tasks on Claude Code Web with sandboxed branch access.

Review & Quality

Keeping the codebase correct and understandable — structured code review, test coverage analysis, and tracing why existing code exists.

• Code Review — Systematic code review using review guides, separate from implementation.
• QA and Testing — Systematic test coverage analysis and follow-up task creation.
• Upstream Defect Follow-up — Automatic prompt to spawn a follow-up bug task when diagnosis surfaces a separate, pre-existing defect.
• Manual Verification — Human-checked verification items (TUI flows, live agent launches, artifact inspection) as first-class gated tasks.
• Risk Evaluation — Opt-in planning step that rates code-health and goal-achievement risk, then offers before/after mitigation follow-ups.
• Explain — Use code evolution history to rebuild understanding of why code exists.

Git

Round-tripping with issue trackers, pull requests, upstream contributions, releases, and reverts — the flows that cross aitasks’ boundary with the wider git ecosystem.

• Issue Tracker — Round-trip workflow between issue trackers (GitHub, GitLab, Bitbucket) and aitasks.
• PR Import — End-to-end guide for creating aitasks from pull requests.
• Contributions — Sharing changes back upstream and managing incoming contributions with aitasks.
• Releases — Automated changelog generation and release pipeline from task data.
• Revert Changes — Reverting features or changes that are no longer needed.

Maintenance

• Repository Maintenance — Periodic upkeep: archiving old tasks, pruning explain caches, changelog/release prep, diagnosing the task-data worktree, and upgrading the framework.

Next: Code Agent Skills