# Relevant Claude Code Issues

## Introduction

This document tracks Claude Code issues that directly impact our development workflows for the MarkiTect project. Each issue section provides a clear problem description, affected workflows, related GitHub issues for monitoring, available workarounds, and resolution tracking information.

**Purpose:**
- Document blocking Claude Code issues affecting project development
- Provide centralized tracking of GitHub issues to monitor for fixes
- Maintain awareness of workarounds and their trade-offs
- Enable quick assessment of when normal workflows can resume

**Maintenance:**
- Update when new blocking issues are discovered
- Check GitHub issue status weekly and update resolution monitoring
- Remove resolved issues after confirming fixes work in our environment
- Maintained by the claude-expert subagent as part of issue tracking responsibilities

---

## Resolved Issues

### ✅ RESOLVED: Custom Subagents Not Available

### Problem Description (Historical)

Custom subagents defined in `.claude/agents/` directory were not being detected or made available as `subagent_type` options in the Task tool. This prevented the intended workflow of using specialized subagents for domain-specific tasks like project management, documentation, or Claude Code expertise.

The custom subagent system appeared completely broken, with agents not being recognized despite proper YAML frontmatter configuration.

### Resolution Details

**Resolved Date:** 2025-09-23
**Resolution Method:** Issue appears to have been fixed in current Claude Code version
**Verification:** Successfully tested the following subagents:
- ✅ `general-purpose` - Full tool access for complex multi-step tasks
- ✅ `claude-expert` - Specialized for Claude Code documentation and features
- ✅ `project-assistant` - Specialized for MarkiTect project status and development planning

**Resolution Confirmation Steps:**
1. ✅ Custom agents now appear as valid `subagent_type` options in Task tool
2. ✅ Successfully invoked custom subagents for specialized tasks
3. ✅ All intended multi-agent workflows are now functional
4. ✅ No workarounds needed - normal operation restored

### Impact of Resolution

**Restored Workflows:**
- **Specialized Task Delegation**: ✅ Custom subagents working for domain-specific tasks
- **Project Management**: ✅ project-assistant subagent functional for status tracking and planning
- **Documentation Assistance**: ✅ claude-expert subagent operational for Claude Code expertise
- **Task Decomposition**: ✅ Full subagent ecosystem available
- **Workflow Automation**: ✅ Multi-agent collaborative workflows enabled

**Workarounds No Longer Needed:**
- No need to downgrade Claude Code versions
- No need to use only built-in general-purpose agent
- No need for manual role assignment

### Related GitHub Issues (Historical Reference)

- [#4623](https://github.com/anthropics/claude-code/issues/4623) - Custom agents not being detected
- [#4728](https://github.com/anthropics/claude-code/issues/4728) - Agent discovery mechanism broken
- [#4626](https://github.com/anthropics/claude-code/issues/4626) - Custom agents missing from UI
- [#5185](https://github.com/anthropics/claude-code/issues/5185) - Agent configuration not working
- [#4182](https://github.com/anthropics/claude-code/issues/4182) - Task tool limitations for nested agents

---

## Monitoring Schedule

This document should be reviewed weekly to check for issue resolution and update status. The claude-expert subagent is responsible for maintaining this tracking and updating the project team when workflows can resume normal operation.