DOCSEARCHbyAlgolia
Submit Docs

Claude Code Agents Wizard v2

repository·main·Indexed 43 days ago

https://github.com/incomestreamsurfer/claude-code-agents-wizard-v2

A multi-agent orchestration system for Claude Code featuring a hierarchical model with Coder, Tester, and Stuck subagents. It integrates Playwright MCP for visual testing and enforces mandatory human oversight by routing errors through a specialized Stuck agent to prevent silent failures.

Tokens
1.1K
Snippets
3
Records
5
Agent score
7%

What's inside Claude Code Agents Wizard

  1. Understand the specialized subagents

    main

    The system relies on four distinct roles to manage software development:

    AgentRoleContextKey Responsibility
    Claude (Orchestrator)Project Manager200k ContextMaintains the todo list, project state, and delegates tasks.
    CoderDeveloperFresh ContextImplements one specific todo at a time. Never uses fallbacks; calls stuck on error.
    TesterQA EngineerFresh ContextUses Playwright MCP for screenshot-based verification and interaction testing.
    StuckHuman EscalationFresh ContextThe only agent allowed to ask the user questions. Blocks progress until a decision is made.

    Note on the 'No Fallbacks' Rule: Unlike traditional AI that might attempt a workaround when hitting an error, every agent in this system is hardwired to invoke the stuck agent to ensure human oversight.

  2. How the Agent Orchestration Workflow works

    main

    The system uses a hierarchical orchestration model where the main Claude instance manages the project lifecycle by delegating tasks to specialized subagents. This ensures that individual tasks are handled in clean, isolated context windows while the main orchestrator maintains the big picture.

    The Workflow Loop

    1. Orchestrator (Claude): Receives your requirement and creates a detailed todo list using TodoWrite.
    2. Coder Subagent: Invoked by Claude for a specific todo. It works in a fresh context to implement the feature.
    3. Tester Subagent: Invoked after coding is complete. It uses Playwright MCP to perform visual testing and verification via screenshots.
    4. Stuck Subagent: If the Coder or Tester encounters an error, they are hardwired to invoke the Stuck agent. This agent pauses progress and asks the human user for a decision, preventing silent failures or incorrect workarounds.
    5. Completion: Once the Tester verifies success, Claude marks the todo as complete and moves to the next item.

  3. Install the Claude Code Agent Orchestration System

    main

    To use this orchestration system, you must have the Claude Code CLI and Node.js installed. The agents are automatically loaded from the .claude/ directory once you start Claude in the repository root.

    Prerequisites

    • Claude Code CLI installed
    • Node.js (required for the Playwright MCP integration)

    Installation Steps

    1. Clone the repository:
      git clone https://github.com/IncomeStreamSurfer/claude-code-agents-wizard-v2.git
cd claude-code-agents-wizard-v2
    2. Start Claude Code in the directory:
      claude
    git clone https://github.com/IncomeStreamSurfer/claude-code-agents-wizard-v2.git
cd claude-code-agents-wizard-v2
claude

  4. Start a new project with Claude Code Agents

    main

    To begin building, simply provide a high-level requirement to Claude once you have started the session in the repository directory.

    Example Command:

    You: "Build a todo app with React and TypeScript"

    Claude will then take over the orchestration, creating the todo list and managing the coder and tester subagents automatically.

  5. Reference the repository structure

    main

    The orchestration logic and agent definitions are stored in the following directory structure:

    . 
├── .claude/ 
│   ├── CLAUDE.md              # Orchestration instructions for the main Claude orchestrator 
│   └── agents/ 
│       ├── coder.md          # Definition for the Coder subagent 
│       ├── tester.md         # Definition for the Tester subagent 
│       └── stuck.md          # Definition for the Stuck subagent 
├── .mcp.json                  # Playwright MCP configuration for visual testing 
├── .gitignore 
└── README.md 
    .
├── .claude/
│   ├── CLAUDE.md              # Orchestration instructions for main Claude
│   └── agents/
│       ├── coder.md          # Coder subagent definition
│       ├── tester.md         # Tester subagent definition
│       └── stuck.md          # Stuck subagent definition
├── .mcp.json                  # Playwright MCP configuration
├── .gitignore
└── README.md