Enhancement: Document --agent mode requirement and generate shell alias for orchestrator

[Cpicon]

Summary

The orchestrator agent generated by /generate-debugger can only dispatch specialist subagents when run via claude --agent <name> (main thread mode). When dispatched as a subagent from a normal conversation, it cannot spawn sub-subagents — Claude Code enforces a maximum nesting depth of 1.

This is not a bug in the plugin, but users are not told about this constraint and naturally try to use the orchestrator as a subagent, which silently fails to delegate.

Evidence

Official Claude Code documentation (code.claude.com/docs/en/sub-agents):

"Subagents cannot spawn other subagents. If your workflow requires nested delegation, use Skills or chain subagents from the main conversation."

"Agent(agent_type) has no effect in subagent definitions."

Current Behavior

1. User generates agents with /generate-debugger
2. User tries to use the orchestrator from a normal Claude Code session (dispatched as subagent)
3. Orchestrator cannot dispatch specialists (nesting blocked)
4. Orchestrator falls back to investigating directly
5. User doesn't understand why specialists aren't being used

Recommended Changes

1. Document the --agent mode requirement

Add clear documentation in the generated orchestrator's system prompt and in the command output:

The orchestrator must be run via: claude --agent project-debugger
It CANNOT dispatch specialists when run as a subagent from a normal session.

2. Generate a shell alias

After generating the orchestrator, offer to create a shell alias:

alias claudebug='claude --agent project-debugger'

And prompt the user to add it to their .zshrc/.bashrc.

3. Update the orchestrator's description

The description should clarify that the agent is designed for --agent mode:

description: |
  Debugging orchestrator for [project]. Run via 'claude --agent project-debugger'
  to enable specialist subagent dispatching. Cannot dispatch specialists when
  run as a subagent from a normal session.

4. Consider generating a Skill as alternative entry point

Skills run in the main conversation context and CAN dispatch subagents. A /debug skill could serve as an alternative entry point that:

• Reads the user's problem description
• Dispatches the appropriate specialists directly from the main session
• Follows the orchestration patterns defined in the debugger's system prompt

This would give users two options:

• claude --agent project-debugger for dedicated debugging sessions
• /debug for quick debugging within an existing session

Impact

Users who don't know about --agent mode will never see the multi-agent orchestration working. The feature silently degrades to single-agent behavior.

Environment: Claude Code v2.1.79, macOS
Related: Split from #8

[Cpicon]

Additional Concern: Agent naming must be deterministic for the alias to work

The proposed shell alias (alias claudebug='claude --agent project-debugger') assumes the orchestrator is always named project-debugger. But /generate-debugger could produce different names depending on the project context — e.g., azpot-debugger, my-project-debugger, app-debugger.

If the name doesn't match, the alias fails silently with no useful error.

Options to consider

Option	Approach	Tradeoff
A. Enforce a fixed name	Always name the orchestrator project-debugger regardless of project	Predictable, alias always works. But name collisions if user has multiple projects with orchestrators
B. Convention-based name	Always use the pattern {project}-debugger and generate the alias dynamically	Flexible, but user must remember per-project aliases
C. Wrapper script instead of alias	Generate a script that auto-detects the debugger agent in .claude/agents/ by scanning for a marker (e.g., a role: orchestrator field in frontmatter)	Works regardless of name. More complex but zero-config
D. Claude Code native support	Use claude --agent .claude/agents/project-debugger.md (path-based instead of name-based)	No naming dependency at all. Requires checking if --agent supports file paths

Recommendation

Option A (fixed name project-debugger) is the simplest and most reliable. The /generate-debugger command should always produce an agent named exactly project-debugger — this is the orchestrator convention, not a project-specific name. The specialists underneath can have project-specific names (e.g., itadp-ci-pipeline-expert), but the entry point should be stable.

This also means the alias can be added to the user's global shell config once and work across all projects — each project's .claude/agents/project-debugger.md will be loaded based on which project directory claude is invoked from.