Task Management Workflows
Relevant source files
The following files were used as context for generating this wiki page:
Task Management Workflows in this repository define a structured, decentralized approach to tracking development progress across a monorepo architecture. Instead of relying on external issue trackers, the project utilizes local Markdown-based task lists and specific CLI commands to manage work items directly within the codebase.
The system is designed to provide high visibility into the state of individual packages and applications while maintaining a standardized format for task lifecycle management, from planning ("Next") to completion ("Done").
Sources: AGENTS.md:120-124, CLAUDE.md:120-124
Task Tracking Structure
Each package or application within the workspace maintains its own set of work items. This localized approach ensures that tasks are closely coupled with the relevant code.
File Location and Format
Tasks are tracked in a specific file located at <package-or-app>/docs/TASKS.md. These files are only created for packages with active work.
The internal structure of a TASKS.md file follows a strict three-section hierarchy:
| Section | Description | Format |
|---|---|---|
| Next | Upcoming tasks to be picked up | - [ ] Task description |
| In Progress | Tasks currently being worked on | - [ ] Current task |
| Done | Completed tasks | - [x] Completed task |
Sources: AGENTS.md:126-141, CLAUDE.md:126-141, packages/color-contrast/CLAUDE.md:10-11
Formatting Rules
To maintain consistency across the monorepo, several rules apply to task entries:
- Checkboxes: All tasks must use standard Markdown checkbox format (
- [ ]or- [x]). - Dependencies: Task dependencies are expressed inline using the notation
(depends on: Task X). - Sub-tasks: Complex items are broken down using nested checkboxes.
- Reference Material: Sections for "Spec References" or "Notes" are permitted below the "Done" section.
Sources: AGENTS.md:143-147, CLAUDE.md:143-147
Workflow Lifecycle
The workflow moves tasks through states using standardized automation commands. This process ensures that the status of work items remains accurate as developers progress through their duties.
The following diagram illustrates the lifecycle of a task within the repository:
This diagram shows the transition of work items between status headers in TASKS.md.
Sources: AGENTS.md:149-152, CLAUDE.md:149-152
Automation Commands
The project employs specific slash commands to automate the movement of tasks between sections:
/task-start [package-name]: Triggers the selection of a task from the "Next" section and moves it to "In Progress"./task-done: Marks a task in the "InProgress" section as complete by moving it to the "Done" section and updating the checkbox.
Sources: AGENTS.md:149-152, CLAUDE.md:149-152
Integration with Development Tools
Task management is supported by a robust set of development tools and scripts defined in the root and package-level configurations.
Build and Test Orchestration
Turborepo handles the execution of tasks related to the code being changed during a task's lifecycle. Tasks in the workflow often require running specific build or test scripts to verify completion.
This sequence diagram demonstrates the interaction between task state management and the build system.
Sources: package.json:13-16, turbo.json:5-24
Code Quality Enforcement
Before a task can be considered "Done," it must pass static analysis and formatting checks. The repository uses Biome and Lefthook to ensure that completed tasks meet the project's quality standards.
| Command | Purpose |
|---|---|
bun run static-check | Runs TypeScript type checking and Biome linting |
biome check . --write | Automatically fixes formatting and linting issues |
lefthook install | Sets up git hooks for pre-commit Biome checks |
Sources: AGENTS.md:14-27, package.json:18-20, CLAUDE.md:14-27
Summary
The Task Management Workflow provides a decentralized, file-based system for tracking progress within the web-projects monorepo. By utilizing localized TASKS.md files and automation commands, the project maintains a clear record of work without external dependencies. This system, integrated with Turborepo for execution and Biome for quality, ensures that every task marked as "Done" satisfies both the functional requirements and the codebase's structural standards.