ClaudeBox Documentation

The Adaptive Agentic Workflow Orchestrator is a meta-prompting system designed for Claude Code to enable autonomous, self-improving coding workflows. It manages complex tasks by combining an initial planning phase with dynamic multi-agent execution and continuous evaluation loops.

Key capabilities include:

• Plan Mode Integration: Uses Claude Code's Plan Mode for read-only project analysis and solution outlining before any code is written.
• Polymorphic Variable System: Tracks state, progress, and learnings through evolving variables that allow the workflow to adapt across iterations.
• Iterative Self-Improvement: Employs an 'infinite-agentic-loop' where solutions are generated, evaluated by unbiased agents, and refined based on feedback.
• Hybrid Autonomy: Switches between fully autonomous operation for well-defined tasks and interactive dialogue for ambiguous tasks.
• MCP (Model-Context Protocol) Support: Automatically detects and connects to relevant MCP servers (e.g., GitHub, filesystem, databases) to enrich context.
• Quality Enforcement: Continuously runs tests and performance checks, looping until quality thresholds are met.

The refactor command follows a structured 7-step workflow to minimize risk and maximize impact:

1. Assess current code: Read the code, identify boundaries, and run existing tests.
2. Impact assessment: Categorize code as High impact (frequent changes + complexity), Medium impact, or Low impact.
3. Risk assessment: Evaluate risk based on test coverage. High risk code (poor coverage + complex changes) requires characterization tests first.
4. Code smell detection: Identifies long functions (>20 lines), deep nesting (>3 levels), magic numbers/strings, feature envy, and shotgun surgery.
5. ROI prioritization: Prioritizes code based on immediate value (active modification), future value, team value, or maintenance value.
6. Context integration: Reviews recent commits and PR feedback for recurring patterns.
7. Incremental changes: Executes one improvement at a time, running tests after each step and committing incrementally.

The /index-docs task organizes the docs/index.md file using a specific hierarchical structure. It uses level 1 headings for the main title, level 2 headings (##) for folder sections, and level 3 headings (###) for individual document entries.

Structure Rules:

• Root Documents: Listed first under a ## Root Documents section.
• Folders: Each subfolder gets its own ## Folder Name section.
• Sorting: Folders are sorted alphabetically. Within each section, documents are sorted alphabetically by title.
• Sharded Documents: If a folder contains its own index.md, that folder's index.md title is used as the section title, and its contents are listed as subsections.

# Documentation Index

## Root Documents

### [Document Title](./document.md)

Brief description of the document's purpose and contents.

## Folder Name

Documents within the `folder-name/` directory:

### [Document in Folder](./folder-name/document.md)

Description of this document.

The /create-deep-research-prompt task produces a structured markdown prompt. A complete prompt includes the following sections:

• Research Objective: A clear statement of what the research aims to achieve and success criteria.
• Background Context: Relevant information extracted from provided inputs (briefs, brainstorming, etc.).
• Research Questions: Divided into Primary Questions (must answer) and Secondary Questions (nice to have).
• Research Methodology: Specifies Information Sources, Analysis Frameworks, and Data Requirements (quality, recency, credibility).
• Expected Deliverables: Outlines the Executive Summary, Detailed Analysis, and Supporting Materials (tables, matrices).
• Success Criteria: How to evaluate if the research objectives were met.
• Timeline and Priority: Any time constraints or phasing requirements.

## Research Objective
[Clear statement of what this research aims to achieve]

## Background Context
[Relevant information from project brief, brainstorming, or other inputs]

## Research Questions
### Primary Questions (Must Answer)
1. [Specific, actionable question]

### Secondary Questions (Nice to Have)
1. [Supporting question]

## Research Methodology
### Information Sources
- [Specific source types and priorities]

### Analysis Frameworks
- [Specific frameworks to apply]

### Data Requirements
- [Quality, recency, credibility needs]

## Expected Deliverables
### Executive Summary
- Key findings and insights

### Detailed Analysis
[Specific sections needed based on research type]

### Supporting Materials
- Data tables
- Comparison matrices

## Success Criteria
[How to evaluate if research achieved its objectives]

## Timeline and Priority
[If applicable]

ClaudeBox uses a stateless, mandatory critic loop to ensure high-fidelity outputs. This mechanism is used both during workflow design and during the execution of individual phases.

The Loop Mechanism:

• Statelessness: Critics are provided ONLY with the specific output to review and the workflow contract/spec. They do not see the process, prior instructions, or previous critiques.
• Verdicts: A critic must return one of two verdicts:
  • APPROVE: The loop terminates for that phase/agent.
  • ITERATE: The agent must revise the output based on the provided actionable issues.
• Iteration Limits: There is no upper limit on iterations unless explicitly defined in the workflow configuration or contract. The loop continues until APPROVE is received.
• Artifact Logging: Every iteration is preserved for auditability:
  • Agent outputs: .../phase{N}/history/{agent}_output_iter{I}.md
  • Critic evaluations: .../evaluations/history/phase{N}_{agent}_eval_iter{I}.md

When a section in a YAML template has elicit: true, the workflow enters a hard stop requiring mandatory user interaction. The system is prohibited from using yes/no questions or any format other than the numbered 1-9 options.

The Mandatory 1-9 Format

For every elicited section, the system must:

1. Present the drafted section content.
2. Provide a detailed rationale (explaining trade-offs, assumptions, and decisions).
3. Present exactly nine numbered options:
   • Option 1: "Proceed to next section"
   • Options 2-9: Specific methods selected from data/elicitation-methods.
4. End the prompt with: Select 1-9 or just type your question/feedback:
5. Wait for user response before proceeding.

Elicitation Results Flow

Once a user selects an elicitation method (Options 2-9):

1. The system executes the chosen method from data/elicitation-methods.
2. It presents the results along with insights.
3. It offers the following follow-up options:
   • 1. Apply changes and update section
   • 2. Return to elicitation menu
   • 3. Ask any questions or engage further with this elicitation

# Example section configuration in a YAML template
section_name:
  instruction: "Draft the system architecture"
  elicit: true
  permissions:
    owner: "architect-agent"
    editors: ["dev-agent"]

When using prompts generated by this task (or writing your own for AI coding tools), follow this four-part framework to ensure high-quality, predictable code generation:

1. High-Level Goal: A clear, concise summary of the objective (e.g., "Create a responsive user registration form...").
2. Detailed, Step-by-Step Instructions: A granular, numbered list of sequential actions (e.g., "1. Create file X. 2. Use hook Y."). This is the most critical component.
3. Code Examples, Data Structures & Constraints: Provide concrete API contracts, JSON payloads, or existing code snippets. Crucially, include negative constraints (what the AI should not do).
4. Define a Strict Scope: Explicitly state which files can be modified and which must remain untouched to prevent unintended side effects in the codebase.

1. High-Level Goal: "Create a responsive user registration form with client-side validation and API integration."

2. Detailed, Step-by-Step Instructions:
   1. Create a new file named `RegistrationForm.js`.
   2. Use React hooks for state management.
   3. Add styled input fields for 'Name', 'Email', and 'Password'.
   4. For the email field, ensure it is a valid email format.
   5. On submission, call the API endpoint defined below.

3. Code Examples, Data Structures & Constraints:
   Use this API endpoint: `POST /api/register`.
   The expected JSON payload is `{ "name": "string", "email": "string", "password": "string" }`.
   Do NOT include a 'confirm password' field.
   Use Tailwind CSS for all styling.

4. Define a Strict Scope:
   You should only create the `RegistrationForm.js` component and add it to the `pages/register.js` file.
   Do NOT alter the `Navbar.js` component or any other existing page or component.

The ClaudeBox CLI uses a 'four-bucket' architecture to classify arguments. This ensures that flags are handled by the correct component (the host machine or the Docker container) and prevents unpredictable behavior.

When you run a command, arguments are sorted into one of these four categories:

1. Host-only flags: Settings that affect the ClaudeBox host script itself (e.g., verbosity or tmux wrapping).
2. Control flags: Environmental settings that are passed into the Docker container to modify its runtime behavior (e.g., enabling sudo).
3. Script commands: High-level management commands handled entirely on the host (e.g., creating slots, managing profiles, or installing packages).
4. Pass-through: Any arguments not matching the above are forwarded directly to the underlying Claude CLI (e.g., update or config).

# Example of how arguments are categorized conceptually
# claudebox [Host-only] [Control] [Script command] [Pass-through]
claudebox --verbose --enable-sudo shell "Hello Claude"