SuperClaude/superclaude/agents/pm-agent/workflows/task-management.md

PM Agent Task Management Workflow

Purpose: Lightweight task tracking and progress documentation integrated with PM Agent's learning system.

Design Philosophy

Storage: docs/memory/tasks/ (visible, searchable, Git-tracked)
Format: Markdown (human-readable, grep-friendly)
Lifecycle: Plan → Execute → Document → Learn
Integration: PM Agent coordinates all phases

Task Management Flow

1. Planning Phase

Trigger: Multi-step tasks (>3 steps), complex scope

PM Agent Actions:

1. Analyze user request
2. Break down into steps
3. Identify dependencies
4. Map parallelization opportunities
5. Create task plan in memory

Output: Mental model only (no file created yet)

2. Execution Phase

During Implementation:

1. Execute steps systematically
2. Track progress mentally
3. Note blockers and decisions
4. Adapt plan as needed

No intermediate files - keep execution fast and lightweight.

3. Documentation Phase

After Completion (PM Agent auto-activates):

1. Extract implementation patterns
2. Document key decisions
3. Record learnings
4. Save to docs/memory/tasks/[date]-[task-name].md

Template:

# Task: [Name]
Date: YYYY-MM-DD
Status: Completed

## Request
[Original user request]

## Implementation Steps
1. Step 1 - [outcome]
2. Step 2 - [outcome]
3. Step 3 - [outcome]

## Key Decisions
- Decision 1: [rationale]
- Decision 2: [rationale]

## Patterns Discovered
- Pattern 1: [description]
- Pattern 2: [description]

## Learnings
- Learning 1
- Learning 2

## Files Modified
- file1.ts: [changes]
- file2.py: [changes]

4. Learning Phase

PM Agent Knowledge Extraction:

1. Identify reusable patterns
2. Extract to docs/patterns/ if applicable
3. Update PM Agent knowledge base
4. Prune outdated patterns

When to Use Task Management

Use When:

• Complex multi-step operations (>3 steps)
• Cross-file refactoring
• Learning-worthy implementations
• Need to track decisions

Skip When:

• Simple single-file edits
• Trivial bug fixes
• Routine operations
• Quick experiments

Storage Structure

docs/
└── memory/
    └── tasks/
        ├── 2025-10-17-auth-implementation.md
        ├── 2025-10-17-api-redesign.md
        └── README.md (index of all tasks)

Integration with PM Agent

PM Agent Activation Points:
  1. Task Planning: Analyze and break down
  2. Mid-Task: Note blockers and pivots
  3. Post-Task: Extract patterns and document
  4. Monthly: Review and prune task history

PM Agent Responsibilities:
  - Task complexity assessment
  - Step breakdown and dependency mapping
  - Pattern extraction and knowledge capture
  - Documentation quality and pruning

Comparison: Old vs New

Old Design (Serena + TodoWrite):
  Storage: ~/.claude/todos/*.json (invisible)
  Format: JSON (machine-only)
  Lifecycle: Created → Abandoned → Garbage
  Result: Empty files, wasted tokens

New Design (PM Agent + Markdown):
  Storage: docs/memory/tasks/*.md (visible)
  Format: Markdown (human-readable)
  Lifecycle: Plan → Execute → Document → Learn
  Result: Knowledge accumulation, no garbage

Example Workflow

User: "Implement JWT authentication"

PM Agent Planning:

Mental breakdown:
1. Install dependencies (parallel: jwt lib + types)
2. Create middleware (sequential: after deps)
3. Add route protection (parallel: multiple routes)
4. Write tests (sequential: after implementation)

Estimated: 4 main steps, 2 parallelizable

Execution: PM Agent coordinates, no files created

Documentation (after completion):

File: docs/memory/tasks/2025-10-17-jwt-auth.md

# Task: JWT Authentication Implementation
Date: 2025-10-17
Status: Completed

## Request
Implement JWT authentication for API routes

## Implementation Steps
1. Dependencies - Installed jsonwebtoken + @types/jsonwebtoken
2. Middleware - Created auth.middleware.ts with token validation
3. Route Protection - Applied to /api/user/* routes
4. Tests - Added 8 test cases (auth.test.ts)

## Key Decisions
- Used RS256 (not HS256) for better security
- 15min access token, 7day refresh token
- Stored keys in environment variables

## Patterns Discovered
- Middleware composition pattern for auth chains
- Error handling with custom AuthError class

## Files Modified
- src/middleware/auth.ts: New auth middleware
- src/routes/user.ts: Applied middleware
- tests/auth.test.ts: New test suite

Benefits

Visibility: All tasks visible in docs/memory/
Searchability: grep-friendly markdown
Git History: Task evolution tracked
Learning: Patterns extracted automatically
No Garbage: Only completed, valuable tasks saved

Anti-Patterns

❌ Don't: Create task file before completion ❌ Don't: Document trivial operations ❌ Don't: Create TODO comments in code ❌ Don't: Use for session management (separate concern)

✅ Do: Let PM Agent decide when to document ✅ Do: Focus on learning and patterns ✅ Do: Keep task files concise ✅ Do: Review and prune old tasks monthly