Task Management Skill

This skill defines the conventions and rules for creating and managing task files in the task management system.

When to Use This Skill

Use this skill whenever you are:

•Creating a new task, idea, bug, memory, or template file
•Modifying existing task files
•Organizing or reorganizing tasks
•Generating task lists or reports

File Naming Conventions

Rules

•Use kebab-case: All lowercase with hyphens separating words
•Be descriptive: Name should clearly indicate the task content
•Keep it concise: Aim for 2-5 words maximum
•No dates in filename: Dates go in YAML frontmatter, not filename
•Use .md extension: All task files are Markdown files

Examples

✅ Good:

•implement-user-authentication.md
•fix-login-bug.md
•team-meeting.md
•research-ai-tools.md

❌ Bad:

•Task 1.md (not descriptive)
•Implement_User_Authentication.md (use kebab-case, not snake_case)
•implement-user-authentication-2026-01-30.md (no dates in filename)
•TODO.md (too generic)

File Structure

Every task file must follow this structure:

markdown

---
type: [task|idea|template|memory|bug]
[additional fields based on type]
---

# Task Title

Task description and content here.

## Optional Sections
- Checklist
- Notes
- References

YAML Frontmatter Fields

Required Fields

For All Types

•type: Must be one of: task, idea, template, memory, bug

For Tasks (type: task)

•due: Due date in YYYY-MM-DD format

Optional Fields

Common Fields

•
tags: Array of tags for categorization
- •Format: [tag1, tag2, tag3]
- •Use lowercase, kebab-case for multi-word tags
- •Examples: [development, urgent], [meeting, weekly]

Task-Specific Fields

•
completed: Completion date in YYYY-MM-DD format
- •Only add when task is completed
- •Used for archiving logic
•
recurrence: Recurrence pattern
- •Valid values: weekly, biweekly, monthly, quarterly, yearly
- •Recurring tasks are never archived
- •When completed, the due date is automatically updated to next occurrence

Idea-Specific Fields

•
status: Current status of the idea
- •Valid values: in-progress, noodling, someday
- •in-progress: Actively working on
- •noodling: Exploring, might become in-progress
- •someday: Interesting but not current priority

Bug-Specific Fields

•
priority: Bug priority level
- •Valid values: critical, high, medium, low
•
status: Bug status
- •Valid values: open, in-progress, resolved, closed

Date Format

Always use ISO 8601 format: YYYY-MM-DD

✅ Correct:

•2026-01-30
•2026-12-25

❌ Incorrect:

•01/30/2026 (US format)
•30-01-2026 (European format)
•Jan 30, 2026 (text format)
•2026-1-30 (missing leading zero)

Link Format

The system supports two link formats, configured in .agent/config/task-management.yaml:

Obsidian Format (default)

markdown

[[task-name]]
[[other-task]]

Markdown Format

markdown

[task-name](tasks/task-name.md)
[other-task](ideas/other-task.md)

Always use the format specified in the config file.

File Organization

Folder Structure

code

Tasks/
├── tasks/          # Items with due dates
├── ideas/          # Projects without due dates
├── templates/      # Reusable task templates
├── memories/       # Reference items (not actionable)
├── bugs/           # Issues to fix
├── completed/      # Archived one-time tasks
└── import/         # Staging area for triage

Where to Put Files

•tasks/: Any actionable item with a specific due date
•ideas/: Projects or concepts being explored, no specific deadline
•templates/: Reusable templates for common task types
•memories/: Reference information, documentation, notes (not actionable)
•bugs/: Issues, defects, or problems to fix
•completed/: Automatically populated by archive workflow (don't create files here manually)
•import/: Temporary staging area for new items that need to be categorized

Examples

Example 1: Simple Task

Filename: tasks/write-quarterly-report.md

markdown

---
type: task
due: 2026-02-15
tags: [reporting, quarterly]
---

# Write Quarterly Report

Prepare and submit Q1 2026 quarterly report.

## Checklist
- [ ] Gather data from all departments
- [ ] Create visualizations
- [ ] Write executive summary
- [ ] Review with manager
- [ ] Submit to leadership

Example 2: Recurring Task

Filename: tasks/team-standup.md

markdown

---
type: task
due: 2026-01-31
recurrence: weekly
tags: [meeting, team]
---

# Team Standup

Weekly team standup meeting every Monday at 10 AM.

## Agenda
- Weekend updates
- This week's priorities
- Blockers and challenges

Example 3: In-Progress Idea

Filename: ideas/ai-powered-search.md

markdown

---
type: idea
status: in-progress
tags: [ai, search, innovation]
---

# AI-Powered Search Feature

Implement intelligent search using AI to understand user intent.

## Current Progress
- [x] Research existing solutions
- [x] Prototype basic implementation
- [ ] Test with real data
- [ ] Gather user feedback

## References
- [[search-algorithm-research]]
- [[user-feedback-analysis]]

Example 4: Bug Report

Filename: bugs/login-timeout-issue.md

markdown

---
type: bug
priority: high
status: in-progress
tags: [authentication, backend]
---

# Login Timeout Issue

Users are experiencing timeout errors when logging in during peak hours.

## Symptoms
- Login requests timeout after 30 seconds
- Occurs mainly between 9-11 AM
- Affects approximately 15% of users

## Investigation
- Database query performance seems normal
- Suspect connection pool exhaustion
- Need to increase pool size

## Related
- [[database-optimization]]
- [[authentication-system]]

Example 5: Memory/Reference

Filename: memories/api-design-guidelines.md

markdown

---
type: memory
tags: [api, guidelines, reference]
---

# API Design Guidelines

Internal guidelines for designing RESTful APIs.

## Principles
1. Use nouns for resources, not verbs
2. Use HTTP methods appropriately (GET, POST, PUT, DELETE)
3. Version your APIs (e.g., /v1/, /v2/)
4. Use consistent naming conventions
5. Provide meaningful error messages

## Examples
...

Automation Rules

When Creating Tasks

•Always include type field
•For tasks, always include due date
•Use proper date format (YYYY-MM-DD)
•Use kebab-case for filenames
•Place in appropriate folder based on type
•Use configured link format for cross-references

When Completing Tasks

•Add completed: YYYY-MM-DD field with today's date
•Do NOT move file manually (let /tm-archive workflow handle it)
•For recurring tasks, the workflow will update the due date automatically

When Archiving

•Only one-time tasks (no recurrence field) should be archived
•Recurring tasks stay in tasks/ folder forever
•Archive workflow moves completed tasks to completed/ folder

Best Practices

Task Management

•Be specific: Write clear, actionable task titles
•Break down large tasks: Create subtasks or checklists for complex work
•Use tags wisely: Create a consistent tagging system
•Review regularly: Use /tm-today, /tm-this-week workflows daily/weekly
•Archive promptly: Run /tm-archive regularly to keep tasks/ folder clean

Idea Management

•Start with "noodling": New ideas should start as "noodling" status
•Promote deliberately: Only move to "in-progress" when ready to commit
•Be honest about "someday": If you won't do it soon, mark it "someday"
•Review monthly: Use /tm-ideas to review and update idea statuses

Link Management

•Link related items: Create connections between related tasks, ideas, and memories
•Use consistent format: Always use the configured link format (obsidian or markdown)
•Link to references: Connect tasks to relevant memories or documentation

Common Mistakes to Avoid

❌ Don't:

•Put dates in filenames
•Use spaces or special characters in filenames
•Create tasks without due dates
•Manually move files to completed/ folder
•Use inconsistent date formats
•Archive recurring tasks
•Create files with duplicate names

✅ Do:

•Use YAML frontmatter for all metadata
•Follow kebab-case naming convention
•Use ISO date format (YYYY-MM-DD)
•Let workflows handle archiving
•Use tags for categorization
•Create descriptive, actionable titles
•Link related items together

Integration with Workflows

This skill works in conjunction with the following workflows:

•/tm-setup: Initialize the task management system
•/tm-today: Generate today's task list
•/tm-this-week: Generate this week's tasks
•/tm-next-week: Generate next week's tasks
•/tm-archive: Archive completed tasks and update recurring tasks
•/tm-ideas: List and organize ideas by status
•/tm-clean-imports: Process files from import folder

When these workflows run, they rely on the conventions defined in this skill to properly parse, filter, and organize task files.