[FEATURE] Hierarchical Goal Tracking System for Long-Horizon Development Tasks

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Feature Request: Hierarchical Goal Tracking System for Long-Horizon Development Tasks

Summary

Upgrade Claude Code's current flat todo list to a hierarchical goal tracking system that maintains coherent long-term development objectives across sessions. This addresses documented limitations in maintaining strategic consistency during complex, multi-step projects.

Problem Statement

When working on projects that span multiple sessions or involve complex multi-step development goals, Claude Code's current todo list is insufficient for maintaining strategic coherence. Users are forced to track higher-level objectives externally (in .md files, personal notes, etc.) and repeatedly re-orient Claude Code to the broader context.

Observed Limitations

A recent peer-reviewed study (Wang et al., 2025) systematically evaluated Claude Code on complex multi-step tasks and documented three specific limitations:

1. Failure to maintain coherent plans: Claude Code "does not follow a consistent, strategic sequence of actions, leading to repeated work, abandoned partial attempts, and unstable performance." The authors observed that "its decision-making tends to execute whatever actions come to 'mind' first" rather than following a structured approach.

1. Difficulty with long-term reasoning: Claude Code may "skip enumeration or investigation steps and jump directly to generating [solutions] based on internal knowledge," leading to "hallucinated steps, inconsistent performance, and unnecessary token usage."

1. Erratic path selection: The system "may initially [pursue one approach], then abruptly switch to [another]. Even after [making progress], it may suddenly abandon that path to [start something else] or pursue an unrelated [direction]."

User Impact

For development projects with goals like:

• "Refactor authentication system to use OAuth2"
• "Migrate from REST to GraphQL across 12 microservices"
• "Implement comprehensive test coverage for the payment module"

...the current todo list provides no mechanism to:

• Track which sub-goals have been completed vs. abandoned
• Maintain dependencies between tasks
• Persist strategic context across sessions
• Prevent circular revisiting of already-completed work

Proposed Solution

Proposed Solution

Implement a hierarchical goal tracking system inspired by the "Planner-Executor-Perceptor" (PEP) architecture, adapted from automated planning research to software development workflows.

Core Concepts

1. Goal Hierarchy (DAG Structure)

Replace the flat todo list with a directed acyclic graph of goals:

[HIGH-LEVEL GOAL] Migrate authentication to OAuth2
├── [MILESTONE] Design OAuth2 flow architecture
│   ├── [TASK] Document current auth flow
│   ├── [TASK] Select OAuth2 provider strategy
│   └── [TASK] Design token refresh mechanism
├── [MILESTONE] Implement OAuth2 backend
│   ├── [TASK] Add OAuth2 dependencies
│   ├── [TASK] Implement token endpoint
│   └── [TASK] Update user session handling
└── [MILESTONE] Migrate existing endpoints
    ├── [TASK] Identify all authenticated endpoints
    ├── [TASK] Update middleware
    └── [TASK] Add integration tests

2. Explicit Preconditions and Effects

Each task/milestone has:

• Preconditions: What must be true before this can start
• Effects: What becomes true when this completes
• Status: pending | in-progress | completed | blocked | abandoned (with reason)

This prevents Claude Code from attempting tasks out of order or re-doing completed work.

3. Persistent State File

A .claude/goals.json (or similar) that persists across sessions:

{
  "project_goal": "Migrate authentication to OAuth2",
  "created": "2025-12-15T10:00:00Z",
  "last_updated": "2025-12-19T14:30:00Z",
  "milestones": [
    {
      "id": "m1",
      "name": "Design OAuth2 flow architecture",
      "status": "completed",
      "completed_at": "2025-12-16T16:00:00Z",
      "tasks": [...]
    },
    {
      "id": "m2", 
      "name": "Implement OAuth2 backend",
      "status": "in-progress",
      "preconditions": ["m1.completed"],
      "tasks": [
        {
          "id": "t2.1",
          "name": "Add OAuth2 dependencies",
          "status": "completed"
        },
        {
          "id": "t2.2",
          "name": "Implement token endpoint",
          "status": "in-progress",
          "context": "Working on refresh token logic, see src/auth/oauth.py"
        }
      ]
    }
  ]
}

4. Session Resumption

When starting a new session, Claude Code would:

1. Load the goal state
2. Display current status: "Resuming: Migrate authentication to OAuth2. Currently on: Implement token endpoint (Milestone 2/3, Task 2/3)"
3. Understand what's been done without user re-explanation

Proposed Commands

/goals                    # Show current goal hierarchy and status
/goals new <description>  # Create new high-level goal, interactively build milestones
/goals status             # Detailed progress report
/goals focus <id>         # Set active focus to specific milestone/task
/goals complete <id>      # Mark task/milestone complete with summary
/goals block <id> <reason># Mark as blocked, record why
/goals abandon <id> <reason> # Explicitly abandon with documented reason
/goals export             # Export goal tree as markdown for external sharing

Key Behaviors

1. Strategic Consistency: Before executing any significant action, check alignment with current goal focus. If user requests something orthogonal, confirm: "This seems unrelated to your current goal (OAuth2 migration). Should I add it as a new goal, or continue with the current focus?"

1. Progress Tracking: After completing substantive work, prompt to update goal status rather than letting completions go untracked.

1. Anti-Drift Protection: If Claude Code finds itself re-implementing something marked complete, surface it: "Note: 'Add OAuth2 dependencies' was marked complete on Dec 16. Are we revisiting this intentionally?"

1. Dependency Enforcement: Don't start tasks whose preconditions aren't met without explicit user override.

Benefits

| Current State | With Goal Tracking |
|--------------|-------------------|
| User manually tracks progress externally | Progress persists in project |
| Each session starts from scratch contextually | Sessions resume with full strategic context |
| Easy to drift between approaches | Explicit structure prevents erratic switching |
| Completed work may be revisited unknowingly | Completion status prevents redundant work |
| No visibility into abandoned paths | Abandoned paths documented with reasons |

Implementation Considerations

• Backwards Compatible: The existing todo list could remain as a lightweight option; goal tracking would be opt-in for complex projects
• File-Based State: Using a dotfile (.claude/goals.json) keeps state with the project and version-controllable
• LLM-Assisted Planning: Goal decomposition could leverage Claude's reasoning to suggest milestone/task breakdowns, while the structure itself is maintained deterministically

References

• Wang, L., et al. (2025). "Automated Penetration Testing with LLM Agents and Classical Planning." arXiv:2512.11143. https://arxiv.org/abs/2512.11143
• Provides systematic evaluation of Claude Code's planning limitations and demonstrates that hybrid classical-planning + LLM systems outperform pure LLM approaches on long-horizon tasks

---

This feature would transform Claude Code from a capable tactical executor into a strategic development partner capable of maintaining coherent progress on complex, multi-session projects.

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

Other

Use Case Example

_No response_

Additional Context

Reference: Wang et al., 2025