gemini-cli/plans/task-tracker-implementation.md

Task Tracker Implementation Plan

This document outlines the phased implementation of the Git-backed, graph-based Task Tracker for Gemini CLI.

Phase 1: Foundation & Data Model

Goal: Establish the storage mechanism and the core task schema.

Tasks

• Storage Infrastructure:
  • Implement a TrackerService in packages/core/src/services/.
  • Create logic to manage .tracker/tasks/ directory.
  • Implement 6-character alphanumeric ID generation (hex).
• Data Model (JSON Schema):
  • id: string (6 chars)
  • title: string
  • description: string
  • type: epic | task | bug
  • status: open | in_progress | blocked | closed
  • parentId: string (optional)
  • dependencies: string[] (list of IDs)
  • subagentSessionId: string (optional)
  • metadata: object (optional)
• Graph Validation Logic:
  • Prevent closed status if dependencies are not closed.
  • Ensure no circular dependencies.

Success Criteria: Can manually create and read task files with valid schemas and basic dependency checks.

---

Phase 2: CRUD Tools & Visualization

Goal: Enable the agent to interact with the tracker via CLI tools.

Tasks

• Infrastructure:
  • Add trackerEnabled to ConfigParams and Config in packages/core.
  • Guard tracker tool registration in Config.createToolRegistry.
  • Add experimental.taskTracker to SETTINGS_SCHEMA in packages/cli.
  • Pass taskTracker setting to Config in loadCliConfig.
• Core Tools:
  • tracker_init: Setup .tracker in current workspace.
  • tracker_create_task: Create a new JSON node.
  • tracker_update_task: Modify existing node (handle status transitions).
  • tracker_get_task: Retrieve single task details.
  • tracker_list_tasks: Filtered list (by status, parent, etc.).
• Relationship Tools:
  • tracker_add_dependency: Link two existing tasks.
• CLI Visualization:
  • tracker_visualize: Render ASCII tree with emojis (⭕, 🚧, ✅, 🚫).
• Testing:
  • Implement integration tests in trackerTools.test.ts.

Success Criteria: Tools are registered and usable in the CLI; tracker_visualize shows a clear hierarchy.

---

Phase 3: System Instruction (SI) & Integration

Goal: Shift the agent's behavior to treat the tracker as the Single Source of Truth (SSOT).

Tasks

• System Instruction Update:
  • Inject the "TASK MANAGEMENT PROTOCOL" into the core prompt.
  • Mandate use of tracker_list_tasks at session start.
• Plan Mode Integration:
  • Implement tracker_hydrate(planPath) to turn a plan into tracker nodes.
• Session Restoration:
  • Modify the startup flow to check for existing .tracker and prompt the agent to resume pending tasks.

Success Criteria: Agent stops using markdown checklists and consistently uses tracker_create_task for multi-step goals.

---

Phase 4: Persistence & Advanced Features

Goal: Ensure long-term durability and multi-agent support.

Tasks

• Git Synchronization:
  • tracker_sync: Commit the .tracker directory to the current branch.
• Git Worktree (V2):
  • Implement mounting a tracker-data orphan branch to .tracker/ to allow cross-branch persistence.
• Subagent Coordination:
  • Update SubagentService to automatically update the tracker when a subagent is spawned.

Success Criteria: Task state persists across branch switches and multiple agent sessions.