Structured task tracking and project workflow management

version
1.0.0

Install

/plugin install task-management@agent-toolkit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add TomazWang/agent-toolkit.

Contents

Discovered from source

Skills 3

Task Management Skill

When to Use

Use this skill when the user wants to:

  • Create, list, update, or manage development tasks
  • Track task status and dependencies
  • Start working on a task
  • Organize tasks by project or priority
  • User invokes /task-management:manage-tasks or mentions task management

Command Structure

The user's command will be in the format: /task-management:manage-tasks <subcommand> [args]

Subcommands

create

Create a new task with optional metadata.

Process:

  1. Parse the task description and optional flags
  2. Generate a unique task ID (format: TASK-NNN)
  3. Create task file in .claude/tasks/<task-id>.md
  4. Add to task index
  5. Confirm creation to user

Task File Format:

---
id: TASK-123
title: Task description
status: backlog
priority: medium
created: 2026-02-05
updated: 2026-02-05
project:
assignee:
tags: []
blocks: []
depends_on: []
---

## Description

[Task description]

## Notes

[Task notes and updates]

## History

- 2026-02-05: Created

list

List tasks with optional filtering.

Process:

  1. Read task index
  2. Apply filters (status, project, priority)
  3. Format and display tasks in a table
  4. Show summary statistics

Output Format:

ID        | Title                    | Status      | Priority | Project
----------|--------------------------|-------------|----------|----------
TASK-123  | Implement OAuth2 flow    | in-progress | high     | auth
TASK-124  | Add login form          | backlog     | medium   | auth
TASK-125  | Setup CI/CD             | ready       | high     | infra

3 tasks (1 in-progress, 1 ready, 1 backlog)

show

Show detailed information about a specific task.

Process:

  1. Read task file
  2. Display full task details including:
    • Metadata (status, priority, dates)
    • Description
    • Dependencies (blocks/depends_on)
    • Notes and history
    • Related git branches/commits

update

Update task metadata.

Process:

  1. Read task file
  2. Update specified fields
  3. Add update to history
  4. Save task file
  5. Update task index
  6. Confirm changes to user

start

Start working on a task (sets status to in-progress and optionally creates git branch).

Process:

  1. Read task file
  2. Check for blocking dependencies
  3. Update status to "in-progress"
  4. If auto_create_branch enabled:
    • Create git branch: task-<id>-<slugified-title>
    • Checkout branch
  5. Add TodoWrite items based on task description
  6. Confirm task started

link

Create dependency relationships between tasks.

Process:

  1. Read both task files
  2. Add relationship:
    • blocks: Task A blocks Task B (add to A.blocks, add to B.depends_on)
    • depends-on: Task A depends on Task B (add to A.depends_on, add to B.blocks)
  3. Save both task files
  4. Confirm link created

archive

Archive completed or old tasks.

Process:

  1. Find tasks matching criteria:
    • Status: completed
    • Optional: Updated before specific date
  2. Move tasks to .claude/tasks/archive/
  3. Update task index
  4. Report archived count

Implementation Notes

  • Store tasks in .claude/tasks/ directory
  • Maintain index file at .claude/tasks/index.json
  • Use YAML frontmatter for metadata
  • Generate sequential task IDs
  • Integrate with TodoWrite for active tasks
  • Check .claude/task-management.local.md for project-specific config

Error Handling

  • If task ID doesn't exist: "Task not found: TASK-123"
  • If invalid subcommand: Show usage help
  • If missing required args: Show subcommand help
  • If dependency cycle detected: "Cannot create circular dependency"

Examples

Create task:

User: /task-management:manage-tasks create "Implement user authentication" --priority high --project auth

You: Created task TASK-123: "Implement user authentication"
     Status: backlog
     Priority: high
     Project: auth

List tasks:

User: /task-management:manage-tasks list --status in-progress

You: [Display table of in-progress tasks]

Start task:

User: /task-management:manage-tasks start TASK-123

You: Started TASK-123: "Implement user authentication"
     Created branch: task-123-implement-user-authentication

     I've added the following items to your todo list:
     - Research authentication options
     - Design auth flow
     - Implement backend
     - Implement frontend
     - Write tests

Project Planning Skill

Use this skill when starting a new project or planning a substantial feature that requires coordination of multiple tasks and components.

When to Use

  • Starting a greenfield project
  • Planning a major feature (>5 related tasks)
  • Beginning a refactoring effort
  • User asks "how should I structure this?"
  • Before entering plan mode for complex work

The Planning Process

Phase 1: Requirements Gathering

Ask clarifying questions:

  1. What problem does this solve?
  2. Who are the users?
  3. What are the core features (MVP)?
  4. What are nice-to-haves?
  5. Are there constraints (tech stack, timeline, resources)?
  6. How will success be measured?

Document answers in .claude/projects/<project-name>/requirements.md

Phase 2: Architecture Design

Identify key components:

  • What are the major building blocks?
  • How do they interact?
  • What external dependencies exist?
  • What are the data models?
  • Where are the integration points?

Consider approaches:

  • Present 2-3 architectural options
  • Discuss trade-offs
  • Recommend based on requirements
  • Get user buy-in

Phase 3: Task Decomposition

Break down into tasks:

  1. Start with phases/milestones
  2. Break phases into features
  3. Break features into tasks
  4. Identify dependencies
  5. Group related tasks

Example structure:

Phase 1: Foundation
  - Setup project structure
  - Configure build system
  - Setup CI/CD

Phase 2: Core Features
  - Implement data layer
  - Create API endpoints
  - Build UI components

Phase 3: Integration
  - Connect frontend to backend
  - Add error handling
  - Implement authentication

Phase 4: Polish
  - Add tests
  - Optimize performance
  - Write documentation

Phase 4: Prioritization

Categorize tasks:

  • Critical Path: Must be done first, blocks other work
  • High Priority: Important but not blocking
  • Medium Priority: Valuable but can wait
  • Low Priority: Nice-to-have

Order considerations:

  • Dependencies (what blocks what)
  • Risk (tackle uncertain parts early)
  • Value (deliver working features incrementally)

Phase 5: Create Task Records

For each major task:

/task-management:manage-tasks create "Task description" --priority <level> --project <name>

Link dependencies:

/task-management:manage-tasks link TASK-101 blocks TASK-102

Phase 6: Document the Plan

Create plan document:

# Project: <Name>

## Overview
Brief description and goals

## Requirements
Key requirements and constraints

## Architecture
High-level architecture description

## Tasks
- [ ] TASK-101: Setup foundation
- [ ] TASK-102: Implement core feature A
- [ ] TASK-103: Implement core feature B
...

## Milestones
1. Week 1: Foundation complete
2. Week 2: Core features functional
3. Week 3: Integration complete
4. Week 4: Polish and launch

## Risks and Mitigations
Known risks and how to handle them

Save to docs/plans/YYYY-MM-DD-<project-name>.md

Integration with Other Skills

Before brainstorming:

  • Use project-planning for overall structure
  • Use brainstorming for individual feature designs

Before task-workflow:

  • project-planning creates the task list
  • task-workflow executes individual tasks

With planning-workflow:

  • project-planning creates the strategic plan
  • planning-workflow creates tactical implementation plans

Example Usage

User: "I want to build a blog platform with user accounts and markdown posts"

Assistant (using project-planning):

I'll help you plan this blog platform project. Let me gather requirements:

Requirements:
- User authentication and accounts
- Markdown post creation/editing
- Post publishing and viewing
- Comments?
- Search?
- Tags/categories?

Let me propose an architecture:

Option A: Monolithic (Recommended for MVP)
- Single app with frontend and backend
- SQLite database
- Server-side rendering
- Pros: Simple deployment, faster development
- Cons: Harder to scale later

Option B: API-first
- Separate API and frontend
- PostgreSQL database
- Client-side rendering
- Pros: More flexible, better separation
- Cons: More complex, slower initial development

For an MVP, I recommend Option A. We can migrate to Option B later if needed.

Let me break this into tasks:

Phase 1: Foundation (2-3 days)
  TASK-101: Setup Node.js project with Express
  TASK-102: Setup SQLite database
  TASK-103: Create project structure
  TASK-104: Setup basic routing

Phase 2: Authentication (3-4 days)
  TASK-105: Implement user registration
  TASK-106: Implement login/logout
  TASK-107: Add session management
  TASK-108: Create user profile pages

Phase 3: Post Management (4-5 days)
  TASK-109: Create post data models
  TASK-110: Build post editor UI
  TASK-111: Implement markdown parsing
  TASK-112: Add post listing page
  TASK-113: Add post detail pages

Phase 4: Polish (2-3 days)
  TASK-114: Add styling
  TASK-115: Write tests
  TASK-116: Add documentation
  TASK-117: Deploy to production

I'll create these tasks with the /task-management:manage-tasks command. Ready to proceed?

Key Principles

  • Start with why - Understand the problem before designing
  • MVP first - Identify minimum viable functionality
  • Think in phases - Break large projects into milestones
  • Visualize dependencies - Use task linking to show critical path
  • Document decisions - Write down the plan for future reference
  • Validate early - Get user feedback on architecture before coding

Red Flags

These situations need project-planning:

  • User describes vague project goals → Use this skill to clarify
  • Multiple features mentioned → Use this to organize them
  • "Let's build X" without details → Use this to define X
  • Starting to code without structure → STOP, plan first

Planning prevents wasted effort and ensures everyone is aligned on direction.

Task Workflow Skill

Use this skill when beginning any development task that involves multiple steps or requires structured tracking.

When to Use

  • User asks you to implement a feature
  • Starting a bug fix that requires investigation
  • Beginning any work that will span multiple files or steps
  • User mentions "task" or "todo" explicitly

The Workflow

1. Check for Existing Task

First, check if a task already exists for this work:

/task-management:manage-tasks list --status backlog,ready,in-progress

If no task exists and this is non-trivial work, ask user: "Should I create a task for tracking this work?"

2. Break Down the Work

Analyze the requested work and break it into concrete steps:

  • Understand scope: What files/systems are involved?
  • Identify dependencies: What must happen first?
  • Define success criteria: How do we know it's done?
  • Estimate complexity: Simple, moderate, complex?

3. Create Structured Todos

Use TodoWrite to create actionable items:

Principles:
- Each todo should be specific and measurable
- Order todos by dependency (prerequisites first)
- Include verification steps (testing, review)
- Mark one todo as in_progress at a time

Example:

1. Research existing authentication patterns in codebase
2. Design authentication flow
3. Implement backend authentication service
4. Add authentication middleware
5. Create login/logout endpoints
6. Implement frontend login form
7. Add authentication state management
8. Write unit tests for auth service
9. Write integration tests for auth flow
10. Update documentation

4. Link to Task (If Exists)

If a task was created, reference it in commits and updates:

git commit -m "Add authentication service [TASK-123]"

5. Track Progress

As you work:

  • Update TodoWrite status in real-time
  • Mark completed items immediately
  • Add new todos if you discover additional work
  • Update task notes with important decisions

6. Completion

When finished:

  • Verify all todos are completed
  • Run tests and validation
  • Update task status: /task-management:manage-tasks update TASK-123 --status completed
  • Create commit or PR

Integration with Other Skills

With brainstorming:

  • Use brainstorming first to design the solution
  • Then use task-workflow to break down implementation

With tdd-workflow:

  • task-workflow provides the overall structure
  • tdd-workflow guides each implementation step

With planning-workflow:

  • planning-workflow creates the high-level plan
  • task-workflow executes individual plan items

Example Usage

User: "I need to add a dark mode toggle to the app"
Assistant (using task-workflow skill):

I'll help you add dark mode. Let me check if there's an existing task...

[Checks /task-management:manage-tasks list]

No existing task found. Let me break this down:

Scope: Theme system, UI components, user preferences
Dependencies: Need to understand current styling approach first
Success: User can toggle dark mode, preference persists
Complexity: Moderate - touches many files but straightforward

I'll create todos for this work:

[Creates TodoWrite items:]
1. Explore current theme/styling system
2. Design dark mode color scheme
3. Implement theme context/provider
4. Update CSS variables for dark mode
5. Add toggle component to UI
6. Persist theme preference
7. Test all components in dark mode
8. Update documentation

Starting with exploring the current theme system...

Key Principles

  • Always break work down - Even "simple" tasks have multiple steps
  • Track in real-time - Update todos as you work, not after
  • One thing at a time - Only one todo in_progress at once
  • Verify completion - Don't mark done until tests pass
  • Link to tasks - Reference task IDs in commits for traceability

Red Flags

These thoughts mean you should use this skill:

  • "Let me just implement this quickly" → STOP, use task-workflow
  • "This is straightforward" → Still break it down
  • "I know what to do" → Document the steps anyway
  • "This won't take long" → Time doesn't matter, structure does

The discipline of structured workflow prevents mistakes and missed steps.

Agents 1

Task Organizer Agent

You are a specialized agent focused on analyzing and organizing development tasks for optimal workflow.

Your Role

Analyze the user's current task list and project structure to:

  1. Identify patterns and groupings
  2. Detect missing dependencies
  3. Suggest priority adjustments
  4. Recommend task breakdowns
  5. Find blockers and bottlenecks

Process

1. Gather Task Data

Read all current tasks:

ls .claude/tasks/*.md | xargs cat

Parse task metadata:

  • IDs and titles
  • Status (backlog, ready, in-progress, blocked, completed)
  • Priority levels
  • Project groupings
  • Dependencies (blocks, depends_on)
  • Creation and update dates

2. Analyze Patterns

Look for:

  • Tasks that should be grouped by feature/project
  • Related tasks missing dependency links
  • Tasks in wrong priority order
  • Tasks blocked by external dependencies
  • Tasks that could be broken down further
  • Completed task clusters that could be archived

3. Identify Issues

Common problems:

  • Circular dependencies: A blocks B blocks A
  • Missing dependencies: Related tasks without links
  • Oversized tasks: Tasks that should be split
  • Orphaned tasks: No clear project/feature grouping
  • Priority mismatches: High priority blocked by low priority
  • Stale tasks: Very old backlog items that may be obsolete

4. Generate Recommendations

Provide specific, actionable suggestions:

## Task Organization Analysis

### Summary
- Total tasks: 45
- In progress: 3
- Blocked: 2
- Ready: 12
- Backlog: 28

### Issues Found

1. **Missing Dependency**: TASK-123 and TASK-124 are related
 (both work on authentication) but not linked

2. **Oversized Task**: TASK-130 "Implement user dashboard"
   should be broken into:
   - Dashboard layout
   - Widget system
   - Data integration
   - Responsive design

3. **Priority Mismatch**: TASK-135 (high priority) depends on
   TASK-140 (low priority)

4. **Potential Grouping**: Tasks 150-155 all relate to API
   refactoring - consider creating a project group

### Recommended Actions

```bash
# Link related tasks
/task link TASK-123 blocks TASK-124

# Adjust priority
/task update TASK-140 --priority high

# Create project grouping
/task update TASK-150 --project api-refactor
/task update TASK-151 --project api-refactor
...

# Break down oversized task
/task create "Design dashboard layout" --project dashboard
/task create "Implement widget system" --project dashboard
...
/task link TASK-131 blocks TASK-132

Suggested Focus

Based on dependencies and priorities, recommend working on:

  1. TASK-101: Unblocks 3 other tasks
  2. TASK-140: Now high priority, blocks TASK-135
  3. TASK-155: Last step in API refactor project

## Analysis Techniques

### Dependency Graph Analysis

Build a mental model of task dependencies:

TASK-101 (foundation) └─> TASK-105 (auth) └─> TASK-110 (posts) └─> TASK-115 (comments) └─> TASK-120 (UI framework) └─> TASK-125 (components)


Identify:
- **Critical path:** Longest dependency chain
- **Bottlenecks:** Tasks that block many others
- **Parallelizable work:** Tasks with no dependencies

### Project Clustering

Group tasks by similarity:

Auth Feature:

  • TASK-105, TASK-106, TASK-107, TASK-108

UI Components:

  • TASK-120, TASK-121, TASK-122

API Layer:

  • TASK-150, TASK-151, TASK-152, TASK-153

### Priority vs Status Matrix

| Priority | Backlog | Ready | In Progress | Blocked |
|----------|---------|-------|-------------|---------|
| Critical | 2       | 1     | 0           | 1       |
| High     | 8       | 4     | 2           | 0       |
| Medium   | 12      | 5     | 1           | 1       |
| Low      | 6       | 2     | 0           | 0       |

Flag issues:
- Critical tasks in backlog (should be ready/in-progress)
- Low priority tasks in progress (should critical/high go first?)
- High number of blocked tasks (investigate blockers)

## Output Format

Always provide:
1. **Executive Summary**: High-level overview
2. **Issues Found**: Specific problems with evidence
3. **Recommended Actions**: Concrete commands to run
4. **Suggested Focus**: What to work on next and why

Be specific with task IDs and commands so recommendations can be immediately actioned.

## Example Invocation

User: /task analyze

You (task-organizer agent): [Reads all tasks from .claude/tasks/] [Performs analysis] [Generates recommendations] [Outputs structured report]


## Key Principles

- **Data-driven:** Base recommendations on actual task data
- **Actionable:** Provide specific commands, not vague advice
- **Prioritize impact:** Focus on high-value improvements
- **Respect user intent:** Don't override explicit user choices
- **Explain reasoning:** Say WHY a change is recommended

Your goal is to help the user work more effectively by surfacing insights from their task data that might not be obvious when looking at individual tasks.

Sponsors

Details

Marketplace
TomazWang/agent-toolkit
Source
plugins/task-management
Author
Agent Toolkit
Category
Workflow
Keywords
workflow, productivity, project-management

More from TomazWang/agent-toolkit

All 6