# 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 agent-claude-documentation subagent as part of issue tracking responsibilities

**🎯 CRITICAL WORKFLOW REMINDER:**
When discussing project issues (not Claude Code issues), ALWAYS fetch from Gitea first. Gitea is the source of truth for all issue assessment, feasibility evaluation, and implementation planning. Local files are insufficient for decision-making about issues. See ISSUE_WORKFLOW_REMINDER.md for complete workflow.

---

## 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
- ✅ `agent-claude-documentation` - Specialized for Claude Code documentation and features
- ✅ `agent-project-management` - 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**: ✅ agent-project-management subagent functional for status tracking and planning
- **Documentation Assistance**: ✅ agent-claude-documentation 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 agent-claude-documentation subagent is responsible for maintaining this tracking and updating the project team when workflows can resume normal operation.
