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

Issue Category: Custom Subagents Not Available

Problem Description

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

The custom subagent system appears completely broken in current Claude Code versions, with agents not being recognized despite proper YAML frontmatter configuration.

Affected Workflows

Specialized Task Delegation: Cannot use custom subagents for domain-specific tasks
Project Management: Cannot leverage project-assistant subagent for status tracking and planning
Documentation Assistance: Cannot use claude-expert subagent for Claude Code documentation and best practices
Task Decomposition: Limited to built-in general-purpose agent only
Workflow Automation: Cannot implement intended multi-agent collaborative workflows

#4623 - Custom agents not being detected
#4728 - Agent discovery mechanism broken
#4626 - Custom agents missing from UI
#5185 - Agent configuration not working
#4182 - Task tool limitations for nested agents

Workarounds

Option 1: Downgrade Claude Code (Recommended)

npm install @anthropic-ai/claude-code@1.0.61 -g

Pros: May restore custom agent functionality
Cons: Miss out on newer features and bug fixes; version management complexity

Option 2: Use Built-in General-Purpose Agent

Pros: Immediately available, no version changes needed
Cons: Less specialized, requires manual context provision for domain expertise

Option 3: Manual Role Assignment

Ask the main Claude instance to take on specialized roles temporarily
Pros: No technical changes required
Cons: No persistent specialization, less efficient context management

Resolution Monitoring

How to Check if Resolved:

Test custom agent detection with /agents command - should show custom agents
Verify custom agents appear as subagent_type options in Task tool
Test successful invocation of custom subagents for specialized tasks

Expected Resolution Indicators:

GitHub issues marked as closed/resolved
Release notes mention agent system fixes
Community reports of working custom agents
Documentation updates reflecting working functionality

Last Updated

Date: 2025-09-22 Status: Active Issue - Custom agents completely non-functional Current Workaround: Using built-in general-purpose agent only Monitoring: Checking related GitHub issues weekly for resolution status

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.

4.1 KiB Raw Blame History