Agent Skills & Task Management

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• tasks/todo.md
• tasks/done.md
• tasks/records/001-pre-workflow-migration.md
• issues/013-apple-native-catchup.md

The Dotorixel project utilizes a structured Task Workflow to manage the development of its cross-platform pixel art editor. This system integrates specialized AI "skills" with a file-based tracking mechanism to ensure incremental, traceable progress across milestones. By leveraging predefined scripts and markdown-based registries, the project maintains a clear audit trail of implementation decisions, architectural changes, and completed features.

Task Infrastructure

Development tasks are organized into a tiered file system within the tasks/ directory. This structure allows the AI agent and developers to synchronize on the current state of the project without overhead.

Task Registries

The project uses three primary files to track the lifecycle of a feature:

File	Purpose
tasks/todo.md	The master backlog containing all planned items for current and future milestones.
tasks/progress.md	Tracks the immediate context: what is currently active, what was last finished, and what is prioritized next.
tasks/done.md	A chronological log of every completed task, including the completion date and links to relevant issue records.

Sources: CLAUDE.md:27-33, tasks/todo.md:1-5

Automated Workflows (Agent Skills)

The project defines two core "skills"—/task-start and /task-done—which automate the transition between development states and ensure consistency in documentation and version control.

Task Start Workflow

When initiating work, the /task-start skill is executed to establish context. The agent performs the following logic:

1. Reads tasks/progress.md to identify the current project state.
2. If multiple items are in "Next Up," it requests user prioritization.
3. Routes the task to a specialized sub-workflow (e.g., PRD writing, Issue creation, or TDD implementation).

Sources: CLAUDE.md:35-40

Task Completion Workflow

The /task-done skill formalizes the end of a task and synchronizes the repository state. This automation is critical for maintaining the integrity of the tasks/ and issues/ directories.

The following sequence diagram illustrates the operations performed during task completion:

The /task-done skill ensures that every code change is paired with a corresponding documentation update in a single atomic commit.

Sources: CLAUDE.md:42-49

Development Constraints

Branch Management

A strict branch policy is enforced to maintain the stability of the main branch.

• Work Branches: All implementation tasks must be performed on a dedicated work branch. The agent is required to verify the current branch is not main before writing code.
• Exceptions: Tasks that only modify design files (.pen files) are permitted to commit directly to main as they do not affect the application runtime.

Sources: CLAUDE.md:51-56

Implementation Principles

• Atomicity: Work is restricted to one task item at a time. Simultaneous work on multiple items is prohibited.
• Documentation: Significant information and diagrams must be grounded in source files with specific citations.
• Conventional Commits: All commits must follow the standard format (type: subject), ensuring a readable and parsable project history.

Sources: CLAUDE.md:58-69, tasks/records/001-pre-workflow-migration.md:1-5

Milestone-Based Progression

Tasks are grouped into milestones that define the project's evolution. Currently, the project is transitioning from Milestone 1 (Usable Editor) to Milestone 2 (Production UI/UX).

Active Milestone Structure (Milestone 2)

The current focus involves enhancing the editor for production readiness through several specialized tracks:

• Multi-image workflow: Implementing saved work browsers and reopening past work.
• Export & Sharing: Adding SVG support and URL-based sharing.
• Apple Native Catch-up: A phased strategy to bring the SwiftUI/Metal shell to feature parity with the web version.

Sources: tasks/todo.md:7-21, issues/013-apple-native-catchup.md:75-100

Conclusion

The Agent Skills & Task Management system in Dotorixel provides a robust framework for managing a complex, multi-platform codebase. By codifying the relationship between task tracking and AI assistance, the project ensures that development remains organized, documented, and aligned with the overarching milestones. This structure is essential for the planned transition toward serious work features such as layer systems and animation tools in future milestones.