Advanced Claude Code Configuration with Task Management System

This repository contains a sophisticated Claude Code setup that extends the base capabilities with specialized sub-agents, custom commands, automated hooks, and a comprehensive task management system. The configuration demonstrates how Claude Code can be transformed from a general-purpose AI assistant into a highly specialized development environment tailored for complex software engineering workflows.

Overview

Claude Code is Anthropic's AI-powered development assistant that runs directly in your terminal. While powerful out of the box, its true potential emerges through customization. This configuration showcases an advanced setup that includes:

• Task Management System: Lightweight, dependency-aware task tracking
• Specialized Sub-agents: Deep code analysis with parallel processing
• Custom Commands: Common workflows and task operations
• Automated Hooks: Real-time feedback and enhanced reasoning

The architecture leverages Claude Code's ability to spawn parallel sub-agents, each with their own context window and specialized expertise. This allows for complex, multi-threaded analysis while preserving the main conversation context.

Task Management System

A comprehensive task management system enables systematic work tracking across all projects. Tasks are stored as markdown files with YAML frontmatter in project .tasks/ directories.

Features

• Dependency Management: Automatic blocking/unblocking of tasks
• Priority-based Selection: Smart task ordering (P0-P3)
• Size Estimation: XS to XL effort tracking
• Multi-agent Support: Assignee field for collaboration
• Shell Integration: Aliases for quick access

Directory Structure

project/
└── .tasks/
    ├── active/      # Current tasks (shortname-uuid.md)
    ├── archive/     # Completed tasks
    └── templates/   # Task templates

Quick Start

Shell Setup (Already configured in ~/.zshrc)

# Available aliases:
tasks           # List tasks in current project
all-tasks       # Find all projects with tasks
task-cd         # Navigate to .tasks/active
task-cat <id>   # View specific task
task-status     # Quick summary

# Scripts available globally:
~/.claude/scripts/list-tasks.sh [dir]      # List project tasks
~/.claude/scripts/list-all-tasks.sh [dir]  # Find all projects

Claude Commands

/task-list              # See all tasks with status
/task-next              # Pick highest priority task
/task-add               # Create new task interactively
/task-view <id>         # View task details
/task-status <id> <st>  # Update task status
/task-complete <id>     # Mark complete & archive
/task-deps <action>     # Manage dependencies

Task Structure

---
id: 01999792-af4f-70fb-9deb-dc96846b3c83  # UUIDv7
shortname: fix-auth-bug
title: Fix authentication bug in login flow
priority: P1        # P0=critical, P1=high, P2=medium, P3=low
size: M            # XS=<1hr, S=1-4hr, M=4-8hr, L=1-3d, XL=3+d
status: ready      # ready|in_progress|blocked|completed
tags: [security, auth]
blocks: [deploy-prod]          # Tasks that depend on this
blocked_by: [update-api]       # Tasks this depends on
assignee:
created_at: 2025-01-29T23:24:00Z
updated_at: 2025-01-29T23:24:00Z
---

# Task: Fix authentication bug in login flow

## Description
Detailed explanation...

## Acceptance Criteria
- [ ] Bug reproduced
- [ ] Fix implemented
- [ ] Tests added

## Technical Details
Implementation notes...

## Dependencies
### Blocks: [deploy-prod]
### Blocked By: [update-api]

Dependency System

Tasks track two types of dependencies:

• blocks: Tasks waiting for this one to complete
• blocked_by: Tasks that must complete before this one

The system automatically:

• Prevents starting blocked tasks
• Prioritizes tasks that unblock others
• Detects circular dependencies
• Shows dependency graphs with /task-deps graph

Task Selection Algorithm

When using /task-next, tasks are selected by:

1. Exclude blocked tasks (unmet dependencies)
2. Resume any in_progress work
3. Priority order: P0 > P1 > P2 > P3
4. Within priority: prefer smaller tasks (quick wins)
5. Prefer tasks that unblock others
6. Break ties by creation date (FIFO)

Session Management System

Sessions provide execution continuity across context compactions and work periods. When Claude's context window compacts, sessions preserve your progress, decisions, and discoveries so work can resume seamlessly.

Why Sessions?

Claude Code automatically compacts its context when approaching token limits. Without sessions:

• You lose track of what you were doing
• Decisions and their rationale are forgotten
• Discoveries made during work are lost
• Time is wasted re-understanding the codebase

Sessions create a living document that survives compactions and enables rapid context restoration.

Directory Structure

project/
└── .sessions/
    ├── active/           # Currently active sessions
    ├── archive/          # Completed/closed sessions
    └── journal/          # Per-session execution logs

Quick Start

Session Lifecycle

/session-init  →  (active work)  →  /session-close --complete
                       ↓
                 (compaction)
                       ↓
               /session-resume

Claude Commands

/session-init               # Start new session (optionally link to task)
/session-resume             # Resume after compaction
/session-log                # Add progress/decision/discovery entries
/session-checkpoint         # Save explicit checkpoint
/session-view               # View session details
/session-pause              # Pause with checkpoint
/session-close --complete   # Complete and archive session

Logging During Work

Sessions work best when Claude logs as it works:

# Log decisions with rationale
/session-log --decision "Using mutex over channels" --rationale="simpler for this case"

# Log discoveries
/session-log --discovery "Lock ordering: chain_watcher must lock before sweeper"

# Log progress
/session-log --progress "Implemented fix in sweeper.go:245-260"

# Log blockers
/session-log --blocker "Need API clarification from team"

Relationship to Tasks

Sessions and tasks are complementary:

| Aspect | Tasks (.tasks/) | Sessions (.sessions/) | |--------|-----------------|----------------------| | Purpose | What to do | How work progresses | | Lifetime | Project lifetime | Single work effort | | Granularity | Feature/bug level | Execution level | | Survives | Project history | Compactions |

Best practice: Link sessions to tasks with /session-init --task=<id>.

Hooks Integration

Sessions integrate with the hooks system:

• PreCompact Hook: Auto-saves session state before compaction
• SessionStart Hook: Displays active session TL;DR on startup
• UserPromptSubmit Hook: Detects "continue"/"resume" and injects context

For complete documentation, see SESSIONS.md.

Architecture

graph TB
    %% Core System
    Main[Claude Code Core]
    
    %% Built-in Tools
    subgraph Tools["Built-in Tools"]
        direction LR
        T1[Read/Write]
        T2[Bash]
        T3[Search]
    end
    
    %% Sub-Agents Layer
    subgraph Agents["Specialized Sub-Agents"]
        direction LR
        AA[Architecture<br/>Archaeologist]
        CS[Code<br/>Scout]
        CR[Code<br/>Reviewer]
        SA[Security<br/>Auditor]
        TE[Test<br/>Engineer]
        DD[Documentation<br/>Double-Checker]
        GD[Go<br/>Debugger]
        DC2[Debug<br/>Chronicler]
    end
    
    %% Commands Layer
    subgraph Commands["Custom Commands"]
        direction LR
        IC[Incremental<br/>Commit]
        PR[Pre-PR<br/>Review]
        CD[Code<br/>Deep Dive]
        QD[Quick<br/>Dive]
        TF[Test<br/>Forge]
        BR[Batch<br/>Review]
        DC[Doc<br/>Check]
        CF[Chronicle<br/>Fix]
        ID[Ideate]
    end
    
    %% Hooks System
    subgraph Hooks["Event Hooks"]
        direction LR
        UT[Ultrathink<br/>-u flag]
        NH[Notifications]
        SH[Stop Alerts]
    end
    
    %% Connections - organized to minimize crossings
    Main --> Tools
    Main ==> Agents
    Main ==> Commands
    
    %% Hook interactions
    UT -.->|enhances| Main
    Main -.->|triggers| NH
    Main -.->|triggers| SH
    Agents -.->|completion| SH
    
    %% Styling
    classDef core fill:#e1bee7,stroke:#4a148c,stroke-width:3px,color:#000
    classDef agents fill:#c5cae9,stroke:#1a237e,stroke-width:2px,color:#000
    classDef commands fill:#b2dfdb,stroke:#004d40,stroke-width:2px,color:#000
    classDef hooks fill:#ffccbc,stroke:#bf360c,stroke-width:2px,color:#000
    classDef tools fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000
    
    class Main core
    class AA,CS,CR,SA,TE,DD,GD,DC2 agents
    class IC,PR,CD,QD,TF,BR,DC,CF,ID commands
    class UT,NH,SH hooks
    class T1,T2,T3 tools

Components

Sub-Agents

The configuration includes eight specialized sub-agents, each designed for specific analytical tasks. These agents operate in separate context windows, allowing them to perform deep analysis without consuming the main conversation's context budget.

Architecture Archaeologist

The Architecture Archaeologist (agents/architecture-archaeologist.md) serves as your codebase cartographer. When invoked, it launches multiple parallel investigations to analyze different aspects of your code simultaneously. It excels at generating comprehensive documentation with Mermaid diagrams, tracing call graphs, identifying architectural patterns, and synthesizing findings into cohesive reports. This agent is particularly valuable when onboarding new team members or documenting legacy systems.

Code Scout

The Code Scout (agents/code-scout.md) is the speed-focused counterpart to the Architecture Archaeologist. Wh