CLAUDE.md

# Claude Code Commands Documentation ** IMPORTANT - relax, you are not in a rush. NEVER take dangerous short cuts. ALWAYS do things carefully and in ways that you can be sure will not break things ** This directory contains documentation and plans for the Claude Code commands project. ## Essential Documentation ### Architecture & Patterns - @CLAUDE/CommandStructure.md - **PRIMARY REFERENCE**: Orchestrator pattern, directory structure, and command design - @scripts/CLAUDE.md - Script coding standards and conventions - @scripts/_inc/CLAUDE.md - Include file conventions (sourced components) ### Implementation Guides - @.github/ci.bash - CI enforcement rules and checks - @README.md - Project overview and command usage ### Current Plans - @CLAUDE/plan/implement-command-conventions.md - Migration plan for orchestrator pattern and new conventions ## Key Conventions ### 1. Orchestrator Pattern Commands should minimize bash calls by using orchestrator scripts that handle multiple operations internally. See CommandStructure.md for the complete pattern. ### 2. Include vs Execute - **_inc/** files: ONLY sourced, never executed (`.inc.bash` suffix) - **_common/** files: ONLY executed, never sourced - CI enforces these rules automatically ### 3. Directory Structure ``` scripts/g/command/{name}/ � {name}_orchestrate.bash # Main entry point � pre/ # Preconditions � analysis/ # Information gathering � execute/ # Main operations � post/ # Cleanup/summary ``` ### 4. Error Handling All scripts must source the error handler after setting shell options: ```bash #!/usr/bin/env bash set -euo pipefail IFS=$'\n\t' SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" source "$SCRIPT_DIR/../../../_inc/error_handler.inc.bash" ``` ### 5. Arithmetic Operations with set -e When using `set -e`, arithmetic operations can cause unexpected exits. Avoid these patterns: **❌ WRONG - causes exit when result is 0:** ```bash count=0 ((count++)) # Returns 0 (old value), triggers exit with set -e ``` **✅ CORRECT - always succeeds:** ```bash count=0 count=$((count + 1)) # Always returns non-zero exit code ``` **Why this happens:** - `((count++))` returns the OLD value of count (0) - With `set -e`, any command returning 0 (false) causes script exit - `count=$((count + 1))` performs assignment, which always succeeds ## Development Workflow 1. **Read CommandStructure.md** before creating/modifying commands 2. **Run CI checks** before committing: `bash .github/ci.bash` 3. **Follow the orchestrator pattern** for multi-step commands 4. **Minimize bash calls** - target 1-2 calls per command maximum ## CRITICAL: File Editing Policy **ALL FILE EDITS MUST BE DONE MANUALLY - NO BULK UPDATE SCRIPTS** - **NO automated bulk update scripts** - they consistently cause syntax errors and file corruption - **NO scripts that modify multiple files** - each file must be edited individually with care - **Manual editing only** - use Edit/MultiEdit tools directly on each file - **Test after each change** - verify each file works before moving to the next - **One file at a time** - never batch file modifications **Why this rule exists:** - Bulk update scripts have repeatedly caused function definitions to be mangled - Complex regex replacements often miss edge cases and create syntax errors - Manual editing allows for verification and context-aware changes - Individual file edits can be tested immediately **Approved methods:** - ✅ Edit tool for single changes - ✅ MultiEdit tool for multiple changes in ONE file - ✅ Manual review and testing of each change - ❌ Scripts that modify multiple files automatically - ❌ Bulk find-and-replace operations across files - ❌ Automated refactoring scripts ## Testing - Unit test orchestrators in isolation - Verify KEY=value output parsing - Ensure error propagation works correctly - Check that bash call reduction is achieved