Claude-Code-Workflow/.claude/commands/task/context.md

name: task-context description: Unified task context analysis, status management, and intelligent execution support usage: /task:context [task-id|--filter=] [--analyze] [--update] [--sync] [--format=<tree|list|json>] [--detailed] argument-hint: [task-id or filter] [optional: actions and format options] examples: - /task:context - /task:context IMPL-001 --analyze --detailed - /task:context --filter="status:active" --format=tree - /task:context IMPL-001 --update - /task:context --sync

🚀 Command Overview: /task:context

• Purpose: Provides unified task context analysis, status visualization, progress tracking, and intelligent execution support.
• Core Function: Acts as a central hub for understanding and managing the state of tasks within a workflow.

📜 Core Principles

• Task Management: @~/.claude/workflows/task-management-principles.md
• File Structure: @~/.claude/workflows/file-structure-standards.md
• Session Management: @~/.claude/workflows/session-management-principles.md

✨ Core Capabilities

• Context Awareness
  • Analyzes current state and progress from JSON task files.
  • Tracks hierarchical task dependencies.
  • Detects changes in JSON files and status.
  • Assesses the impact of changes across tasks and files.
  • Suggests next actions based on current context.
  • Monitors compliance with file structure standards.
• Status Management
  • Visualizes task status in tree, list, and json formats.
  • Tracks hierarchical progress from task files.
  • Performs batch operations on tasks using filters.
  • Monitors file integrity and task health.
  • Exports analysis and status data to various file formats.
  • Generates status reports and analysis documents.

🧠 Primary Operations Logic

The command's behavior is determined by the provided arguments.

FUNCTION main(arguments):
  // Options like --filter and --format modify the behavior of display functions.

  IF --sync is present:
    // Corresponds to: /task:context --sync
    run_context_synchronization()
  ELSE IF --update is present AND task_id is given:
    // Corresponds to: /task:context <task-id> --update
    run_interactive_update_for(task_id)
  ELSE IF --analyze is present AND task_id is given:
    // Corresponds to: /task:context <task-id> --analyze
    run_detailed_analysis_for(task_id)
  ELSE IF --health, --progress, --timeline, etc. are present:
    // Corresponds to specific reporting sub-commands
    generate_specific_report(report_type)
  ELSE IF task_id is provided without other primary action flags:
    // Corresponds to: /task:context <task-id>
    display_task_context_and_quick_actions(task_id)
  ELSE:
    // Default action with no arguments or only filters/formatters
    // Corresponds to: /task:context
    display_global_context_view(filters, format)
END FUNCTION

🎯 Main Usage Modes & Examples

1. Global Context View

• Command: /task:context
• Description: Provides a high-level overview of the entire workflow's task status.
• Example Output:

📊 Task Context Overview
━━━━━━━━━━━━━━━━━━━━━━
Workflow: WFS-[topic-slug]
Phase: IMPLEMENT
Progress: 45% (5/11 tasks)

Summary:
✅ Completed: 5
🔄 Active: 2
⏳ Pending: 3
🚫 Blocked: 1

Active Context:
- Current focus: IMPL-002 (In Progress)
- Dependencies clear: Yes
- Blockers: IMPL-004 blocked by IMPL-003

Critical Path:
IMPL-001 → IMPL-003 → IMPL-006

Next Actions:
1. Complete IMPL-002 (90% done)
2. Unblock IMPL-004
3. Start IMPL-005 (ready)

2. Task-Specific Analysis

• Command: /task:context IMPL-001 --analyze
• Description: Shows a detailed breakdown of a single task's context, dependencies, and related changes.
• Example Output:

📋 Task Context: IMPL-001
━━━━━━━━━━━━━━━━━━━━

Status: In Progress
Started: 2h ago
Progress: 60% (2/3 subtasks complete)

Dependencies:
✅ No upstream dependencies
⬇️ Blocks: IMPL-003, IMPL-004

Context Data:
- Requirements: [inherited from workflow]
- Scope: src/auth/*, tests/auth/*
- Agent: code-developer
- Priority: high

Related Changes:
- src/auth/login.ts modified 30m ago
- New issue: "Login timeout too short"
- Workflow update: Security requirement added

Impact if delayed:
⚠️ Will block 2 downstream tasks
⚠️ Critical path - affects timeline

3. Interactive Context Update

• Command: /task:context IMPL-001 --update
• Description: Initiates an interactive prompt to modify a task's context data.
• Example Interaction:

Current context for IMPL-001:
1. Requirements: [JWT, OAuth2]
2. Scope: [src/auth/*]
3. Priority: normal

What to update?
1. Add requirement
2. Modify scope
3. Change priority
4. Add note
> 1

Enter new requirement: Add 2FA support
✅ Context updated

4. Context Synchronization

• Command: /task:context --sync
• Description: Reconciles context across the entire task hierarchy, propagating changes and resolving conflicts.
• Example Output:

🔄 Synchronizing task contexts...
- Workflow → Tasks: Updated 3 tasks
- Parent → Children: Propagated 2 changes
- Dependencies: Resolved 1 conflict
✅ All contexts synchronized

🖥️ Display Formats (--format)

Tree Format (--format=tree)

📁 IMPLEMENT Tasks
├── ✅ IMPL-001: Authentication [Complete]
│   ├── ✅ IMPL-001.1: Design schema
│   ├── ✅ IMPL-001.2: Core implementation
│   └── ✅ IMPL-001.3: Tests
├── 🔄 IMPL-002: Database layer [60%]
│   ├── ✅ IMPL-002.1: Models
│   ├── 🔄 IMPL-002.2: Migrations
│   └── ⏳ IMPL-002.3: Seeds
├── ⏳ IMPL-003: API endpoints [Pending]
└── 🚫 IMPL-004: Integration [Blocked by IMPL-003]

List Format (--format=list)

ID       | Title                    | Status    | Progress | Agent           | Priority
---------|--------------------------|-----------|----------|-----------------|----------
IMPL-001 | Authentication          | completed | 100%     | code-developer  | normal
IMPL-002 | Database layer          | active    | 60%      | code-developer  | high
IMPL-003 | API endpoints           | pending   | 0%       | planning-agent  | normal
IMPL-004 | Integration             | blocked   | 0%       | -               | low

JSON Format (--format=json)

• Description: Outputs machine-readable JSON, suitable for scripting and tool integration.

🔍 Filtering (--filter)

• By Status:
  • status:active
  • status:pending
  • status:blocked
  • status:completed
• By Other Attributes:
  • type:feature
  • priority:high
• Combining Filters:
  • status:active,priority:high

🧠 Context Intelligence Features

• Change Detection: Automatically detects file modifications, new issues, workflow updates, and dependency status changes.
• Impact Analysis: Assesses the effect of delays or failures on downstream tasks and the overall timeline (--impact).
• Smart Recommendations: Provides actionable suggestions like which task to focus on, what can be parallelized, or which tasks need breaking down (--recommend).

📄 Context Data Structure (JSON Schema)

This is the standard schema for a task's context data stored in JSON files.

{
  "task_id": "IMPL-001",
  "title": "Build authentication module",
  "type": "feature",
  "status": "active",
  "priority": "high",
  "agent": "code-developer",

  "context": {
    "inherited_from": "WFS-[topic-slug]",
    "requirements": ["JWT authentication", "OAuth2 support", "2FA support"],
    "scope": ["src/auth/*", "tests/auth/*"],
    "acceptance": ["Module handles JWT tokens", "OAuth2 flow implemented", "2FA integration works"]
  },

  "dependencies": {
    "upstream": [],
    "downstream": ["IMPL-003", "IMPL-004"]
  },

  "execution": {
    "attempts": 1,
    "current_attempt": {
      "started_at": "2025-09-05T10:35:00Z",
      "checkpoints": ["setup", "implement", "test", "validate"],
      "completed_checkpoints": ["setup", "implement"]
    },
    "history": []
  },

  "environment": {
    "files_modified": ["src/auth/login.ts", "src/auth/middleware.ts"],
    "issues": ["ISS-001"],
    "last_activity": "2025-09-05T12:15:00Z"
  },

  "recommendations": {
    "next_action": "Complete test checkpoint",
    "risk": "low",
    "priority_adjustment": "none"
  }
}

📊 Analysis & Monitoring

• Progress Report (--progress): Shows overall progress broken down by type, priority, and velocity.
• Health Checks (--health): Reports on task health, highlighting issues like blockers, delays, and repeated failures.
• Timeline View (--timeline): Displays a chronological view of recent and upcoming task activities.

🛠️ Advanced Features

• Conflict Detection (--conflicts): Identifies potential conflicts, such as multiple tasks modifying the same file.
• Historical Context (--history): Shows the version history of a task's context data.
• Context Validation (--validate): Checks a task's context for completeness and validity against defined rules.

🚦 Status Management

• Update Status: Change a single task's status using --set. Example: /task:context IMPL-002 --set=active

• Bulk Update: Update multiple tasks matching a filter. Example: /task:context --filter="status:pending" --set=blocked --reason="Waiting for API"

• Valid Status Transitions: pending -> active -> completed pending -> blocked active -> blocked active -> failed -> pending

💾 File Output Generation

• Analysis Report (--report --save):
  • Generates a comprehensive markdown report.
  • Output: .workflow/WFS-[topic-slug]/.summaries/analysis-[timestamp].md
• Data Export (--export=<format>):
  • Exports task data to various formats (markdown, json, csv).
  • Output: .summaries/[output-name]-[timestamp].[format]
• Validation Report (--validate --save):
  • Saves the output of context validation to a file.
  • Output: .summaries/validation-report-[timestamp].md
• TODO_LIST.md Generation (--generate-todo-list):
  • Creates a TODO_LIST.md file from the current state of JSON task files.
  • Output: .workflow/WFS-[topic-slug]/TODO_LIST.md

🔗 Integration Points

• Workflow: Inherits context from the main workflow and updates session.json.
• Task Relationships: Manages parent-child and sibling dependencies, including circular dependency detection.
• Agent Context: Prepares and optimizes context data for execution by different agent types.
• TodoWrite Tool: Coordinates bidirectionally with the TodoWrite tool and TODO_LIST.md for seamless status updates (--sync-todos).

⚠️ Error Handling Examples

• No Active Workflow:
  • ❌ No workflow context found
  • → Initialize with: /workflow init
• Task Not Found:
  • ❌ Task IMPL-999 does not exist
  • → View tasks with: /task:status
• Context Conflict:
  • ⚠️ Context conflict detected
  • → Resolve with: /task:context --resolve

⚡ Quick Actions

• Description: When viewing a single task, an interactive menu of relevant actions is presented.
• Example Interaction:

/task:context IMPL-002

Quick actions available:
1. Execute task (/task:execute IMPL-002)
2. Analyze context (/task:context IMPL-002 --analyze)
3. Replan task (/task:replan IMPL-002)
4. Break down (/task:breakdown IMPL-002)

Select action: 1
→ Executing IMPL-002...

🤝 Related Commands

• /task:create: Creates new tasks.
• /task:execute: Executes a specific task.
• /task:replan: Replans a task.
• /task:breakdown: Breaks a task into subtasks.
• /task:sync: Synchronizes all file systems.
• /workflow:context: Provides overall workflow status.