AgentHero AI Skill (V2.0)

Comprehensive orchestration utilities for managing hierarchical multi-agent systems with PM coordination, state management, and topic-based organization.

Overview

This skill provides Python-based utilities for:

• State Management: Create, read, update state files for orchestration (V2.0)
• Topic Lifecycle: Initialize, resume, archive project topics
• Task Coordination: Manage sub-agent tasks and dependencies
• Token Tracking: Monitor and report token usage across agents
• SessionStart Hook: Display active topics on Claude Code startup

When Claude Should Use This Skill

Auto-activate when:

• PM orchestrator needs to manage state files
• Creating or updating topic metadata
• Initializing sub-agent task states
• Archiving completed topics
• Reading orchestration state for resume

Directory Structure (V2.0)

.claude/
├── agents/
│   ├── agenthero-ai/                    # PM agent
│   │   ├── agent.md
│   │   └── orchestrated-sub-agent-template.md
│   └── state/                            # Runtime state
│       └── agenthero-ai/                # V2.0 namespace
│           ├── topics.json               # ✅ Single source of truth
│           ├── topics/                   # Topic directories
│           │   └── {topic-slug}/
│           │       ├── task-{id}-{name}.json
│           │       └── messages.json
│           └── archive/                  # Completed topics
│
└── skills/
    └── agenthero-ai/
        ├── skill.md                      # This file
        ├── scripts/                      # Python utilities (V2.0)
        │   ├── topic_manager.py          # Topic lifecycle
        │   ├── state_manager.py          # State CRUD operations
        │   ├── utils.py                  # Shared utilities
        │   ├── setup_project_structure.py # Directory setup
        │   ├── finalize_topic.py         # Topic completion
        │   ├── check_topics_file.py      # Validation
        │   └── get_topics_quiet.sh       # SessionStart hook
        └── templates/
            └── state-templates.json      # State file schemas

Python Utilities (V2.0)

1. Topic Manager (scripts/topic_manager.py)

Purpose: Manage topic lifecycle (V2.0 - uses topics.json)

Commands:

• create_topic <title> - Initialize new topic in topics.json
• list_active_topics - List non-completed topics
• list_completed_topics - List completed topics
• get_topic_status <slug> - Get topic progress and metrics
• touch_topic <slug> - Update last active time
• update_topic_progress <slug> - Recalculate progress from tasks
• archive_topic <slug> - Move topic to archive directory
• resume_topic <slug> - Update last active and return status
• get_active_topics_summary - Get summary for SessionStart hook
• complete_topic <slug> - Mark as completed and archive
• delete_topic <slug> - Delete topic (use with caution)

Usage Examples:

# Create new topic (V2.0)
python .claude/skills/agenthero-ai/scripts/topic_manager.py \
  create_topic \
  "Add JWT authentication" \
  --description "Implement JWT-based auth with tokens and middleware"

# List active topics
python .claude/skills/agenthero-ai/scripts/topic_manager.py \
  list_active_topics

# Get topic status (reads from topics.json)
python .claude/skills/agenthero-ai/scripts/topic_manager.py \
  get_topic_status \
  "auth-system-jwt"

# Archive completed topic
python .claude/skills/agenthero-ai/scripts/topic_manager.py \
  archive_topic \
  "auth-system-jwt"

# Get active topics summary (SessionStart hook)
python .claude/skills/agenthero-ai/scripts/topic_manager.py \
  get_active_topics_summary

2. State Manager (scripts/state_manager.py)

Purpose: CRUD operations for state files (V2.0)

Commands:

• create_state_file <path> <template> - Initialize state file from template
• read_state <path> <field> - Read specific field from state
• update_state <path> <field> <value> - Update state field
• append_log <path> <level> <message> - Append log entry
• set_task_status <path> <status> - Update task status
• track_file_change <path> <file> <change_type> - Track file change
• update_progress <path> <progress> - Update progress (0-100)
• validate_state <path> - Validate JSON structure
• set_blocking_question <path> <question> - Set blocking question
• answer_question <path> <answer> - Answer blocking question
• set_task_result <path> <result> - Set task completion result

Usage Examples:

# Create new task state
python .claude/skills/agenthero-ai/scripts/state_manager.py \
  create_state_file \
  ".claude/agents/state/agenthero-ai/topics/auth-system/task-001-backend.json" \
  "task-state"

# Append log entry
python .claude/skills/agenthero-ai/scripts/state_manager.py \
  append_log \
  ".claude/agents/state/agenthero-ai/topics/auth-system/task-001-backend.json" \
  "info" \
  "Starting database schema design"

# Read current status
python .claude/skills/agenthero-ai/scripts/state_manager.py \
  read_state \
  ".claude/agents/state/agenthero-ai/topics/auth-system/task-001-backend.json" \
  "status"

# Update progress
python .claude/skills/agenthero-ai/scripts/state_manager.py \
  update_progress \
  ".claude/agents/state/agenthero-ai/topics/auth-system/task-001-backend.json" \
  50

3. Utility Functions (scripts/utils.py)

Purpose: Shared helper functions

Functions:

• find_project_root() - Find project root by locating .claude directory
• slugify(text) - Convert text to URL-safe slug
• generate_task_id(topic_slug) - Generate unique task ID
• timestamp_iso() - Get ISO 8601 timestamp with timezone
• atomic_write(path, content) - Atomic file write (supports dict/list/str)
• ensure_directory(path) - Create directory if needed
• read_json_file(path) - Read and parse JSON file
• read_json_field(path, field) - Read specific JSON field
• update_json_field(path, field, value) - Update JSON field
• append_json_array(path, field, value) - Append to JSON array
• validate_json(path) - Validate JSON structure

Usage (imported by other scripts):

from utils import (
    find_project_root, slugify, timestamp_iso,
    atomic_write, read_json_file
)

# Generate slug
slug = slugify("Add JWT Authentication")
# Returns: "add-jwt-authentication"

# Atomic write (prevents corruption)
atomic_write("state.json", {"status": "completed"})

# Find project root
project_root = find_project_root()
# Returns: Path to directory containing .claude/

4. Setup Project Structure (scripts/setup_project_structure.py)

Purpose: Create initial directory structure for topics

Usage:

# Create Project-tasks/{slug}/ structure
python .claude/skills/agenthero-ai/scripts/setup_project_structure.py \
  "landing-page-builder"

# Creates:
# - Project-tasks/landing-page-builder/
# - Project-tasks/landing-page-builder/spec/
# - Project-tasks/landing-page-builder/deliverables/

5. Finalize Topic (scripts/finalize_topic.py)

Purpose: Mark topic as completed and archive

Usage:

# Finalize topic (V2.0)
python .claude/skills/agenthero-ai/scripts/finalize_topic.py \
  "landing-page-builder"

# Actions:
# 1. Marks status as "completed" in topics.json
# 2. Sets completedAt timestamp
# 3. Archives topic directory

6. Check Topics File (scripts/check_topics_file.py)

Purpose: Validate topics.json structure

Usage:

# Validate topics registry (V2.0)
python .claude/skills/agenthero-ai/scripts/check_topics_file.py --summary

# Returns summary of topics.json health

7. SessionStart Hook (scripts/get_topics_quiet.sh)

Purpose: Display active topics on Claude Code startup

Usage (configured in .claude/settings.local.json):

bash .claude/skills/agenthero-ai/scripts/get_topics_quiet.sh

# Output (if topics exist):
# Found 2 active topic(s):
#   • Landing Page Builder (45% complete, 3/5 tasks)
#   • API Integration (20% complete, 1/4 tasks)

# Output (if no topics):
# No pending topics - ready for new work!

State File Templates (V2.0)

Templates are stored in templates/state-templates.json:

Task State Template

{
  "taskId": "",
  "focusArea": "",
  "agentName": "",
  "status": "pending",
  "assignedAt": "",
  "startedAt": null,
  "completedAt": null,
  "progress": 0,
  "currentOperation": null,
  "logs": [],
  "filesCreated": [],
  "filesModified": [],
  "blockingQuestion": null,
  "result": null,
  "error": null,
  "tokenUsage": {
    "total": 0,
    "operations": []
  }
}

Integration with PM Orchestrator

The PM agent (agenthero-ai) uses these utilities for:

1. Topic Initialization

# PM creates new topic (V2.0)
python .claude/skills/agenthero-ai/scripts/topic_manager.py \
  create_topic "User login feature" \
  --description "Create login with validation"

# Returns: user-login-feature (slug)

2. Directory Setup

# PM creates Project-tasks structure
python .claude/skills/agenthero-ai/scripts/setup_project_structure.py \
  "user-login-feature"

3. Task State Management

# PM initializes sub-agent task
python .claude/skills/agenthero-ai/scripts/state_manager.py \
  create_state_file \
  ".claude/agents/state/agenthero-ai/topics/login-feature/task-001-frontend.json" \
  "task-state"

4. Progress Monitoring

# PM reads task status
python .claude/skills/agenthero-ai/scripts/state_manager.py \
  read_state \
  ".claude/agents/state/agenthero-ai/topics/login-feature/task-001-frontend.json" \
  "status"

5. Topic Completion

# PM finalizes topic (V2.0)
python .claude/skills/agenthero-ai/scripts/finalize_topic.py \
  "login-feature"

Integration with Sub-Agents

Sub-agents use state_manager for logging and updates:

# Sub-agent logs progress
python .claude/skills/agenthero-ai/scripts/state_manager.py \
  append_log \
  "$STATE_FILE" \
  "info" \
  "Creating LoginForm component"

# Sub-agent updates progress
python .claude/skills/agenthero-ai/scripts/state_manager.py \
  update_progress \
  "$STATE_FILE" \
  40

# Sub-agent tracks file changes
python .claude/skills/agenthero-ai/scripts/state_manager.py \
  track_file_change \
  "$STATE_FILE" \
  "src/components/LoginForm.tsx" \
  "created"

Best Practices

1. Always validate JSON before writing (automatic in atomic_write)
2. Use atomic writes to prevent corruption (built-in)
3. Log regularly (every 30-60 seconds minimum)
4. Update progress milestones (25%, 50%, 75%, 100%)
5. Track file changes in state files
6. Archive completed topics for history (automatic via finalize_topic.py)

Error Handling

All scripts include error handling:

• Validate input parameters
• Check file existence
• Verify JSON structure (automatic validation)
• Return meaningful error codes (0 = success, 1 = error)
• Log errors to stderr (colored output)

Performance

State operations are optimized:

• Atomic writes prevent corruption
• Minimal file I/O
• Path resolution caches project root
• JSON validation only when needed

Security

State files may contain sensitive data:

• Gitignored by default (.claude/agents/state/)
• File permissions: 644 (owner read/write)
• No credentials stored in state
• Audit trail via logs array

Troubleshooting

Invalid JSON error:

# Validate state file
python .claude/skills/agenthero-ai/scripts/state_manager.py \
  validate_state \
  ".claude/agents/state/agenthero-ai/topics/my-topic/task-001.json"

State file not found:

# Check topics registry
cat .claude/agents/state/agenthero-ai/topics.json | python -m json.tool

Wrong directory created:

# Ensure scripts run from project root OR
# Use absolute paths (scripts auto-detect project root via find_project_root())

Version

Version: 2.0.0 Created: 2025-10-22 Updated: 2025-10-24 (Python migration complete)

Migration Notes (V1 → V2)

Key Changes:

• ✅ Bash scripts → Python scripts
• ✅ Individual topic.json files → Single topics.json registry
• ✅ Relative paths → Absolute path resolution
• ✅ Manual JSON handling → Atomic write with validation
• ✅ List support added to atomic_write()

Support

For issues:

1. Check JSON validity: python -m json.tool < file.json
2. Validate topics.json: check_topics_file.py --summary
3. Review state structure: See STATE-STRUCTURE-V2.md
4. Verify directory structure exists
5. Check file permissions

---

Part of: Hierarchical Multi-Agent Orchestration System V2.0 Related: agenthero-ai agent, orchestrated-sub-agent-template