Automation Builder

Generate Claude Code automation infrastructure: commands (.claude/commands/*.md), scripts (.claude/scripts/bash/*.sh), and templates (.claude/templates/*.md).

Workflow

Discovery → Design → Generate → Validate → Integrate

1. Discovery: Analyze codebase, gather requirements through questions
2. Design: Plan components needed (commands, scripts, templates)
3. Generate: Create the automation files
4. Validate: Test generated artifacts
5. Integrate: Set up handoffs between commands

Discovery Phase

Codebase Analysis

First, understand the project structure:

# Identify project type and existing automation
find . -name "package.json" -o -name "pyproject.toml" -o -name "Cargo.toml" 2>/dev/null | head -5
ls -la .claude/ 2>/dev/null || echo "No .claude directory"
find . -name "*.sh" -path "*/scripts/*" 2>/dev/null | head -10

Look for:

• Project type (monorepo, library, application)
• Existing .claude/ structure
• Current automation patterns (Makefiles, scripts, CI configs)
• Technology stack and frameworks

Requirements Questions

Ask these targeted questions based on what the user needs:

Task Scope:

• What workflow or task needs automation?
• Is this repeatable or one-time?
• What are the inputs and outputs?

Execution Model:

• Interactive (requires decisions) or fully automated?
• What validation is needed?
• How should errors be handled?

Integration:

• Should this connect to other commands via handoffs?
• Are there existing patterns to follow?
• Any compliance or standards requirements?

Design Phase

Component Selection

Need	Component	Location
Interactive workflow with decisions	Command	.claude/commands/task.md
Deterministic automation	Script	.claude/scripts/bash/task.sh
Structured output format	Template	.claude/templates/output.md

Architecture Patterns

Command-First (interactive): Command calls scripts, uses templates Script-First (automation): Script generates output from templates
Hybrid (orchestrated): Command coordinates multiple scripts with checkpoints

Generate Phase

Command Structure

Commands in .claude/commands/*.md:

---
description: One-line description for command discovery
handoffs:
  - label: Next Step
    agent: target-command
    prompt: Context for handoff
---

## User Input

```text
$ARGUMENTS

[Parse user arguments here]

Purpose

[What this command does and when to use it]

Workflow

1. Step Name: Description
   • Decision points with outcomes

Completion Criteria

• Success condition

See `references/command-patterns.md` for detailed examples.

### Script Structure

Scripts in `.claude/scripts/bash/*.sh`:

```bash
#!/usr/bin/env bash
# Description of what script does
#
# Usage: ./script.sh [OPTIONS] [ARGS]
#
# OPTIONS:
#   --json    Output JSON for command parsing
#   --help    Show help

set -e

# Parse arguments
JSON_MODE=false
for arg in "$@"; do
    case "$arg" in
        --json) JSON_MODE=true ;;
        --help|-h) sed -n '2,/^[^#]/p' "$0" | sed 's/^# \?//'; exit 0 ;;
    esac
done

# Main logic here

# Output results
if $JSON_MODE; then
    echo '{"status":"success","data":{}}'
else
    echo "Results..."
fi

See references/script-patterns.md for detailed examples.

Template Structure

Templates in .claude/templates/*.md:

# Template Title

<!--
Purpose: What this template is for
Updated by: Which command/script populates this
-->

**Last Updated**: [TIMESTAMP]
**Status**: [STATUS]

---

## Section

| Field | Value |
|-------|-------|
| Item  | [PLACEHOLDER] |

<!-- Guidance for complex sections -->

See references/template-patterns.md for detailed examples.

Validate Phase

After generating, validate:

1. Command YAML: Check frontmatter syntax
2. Script syntax: Run bash -n script.sh or shellcheck script.sh
3. Cross-references: Verify handoff targets exist
4. Template placeholders: Ensure consistency

Integrate Phase

Handoff Configuration

Connect commands in YAML frontmatter:

handoffs:
  - label: "Continue"
    agent: next-command
    prompt: "Context message"
    send: true  # Auto-execute

Script References

Reference scripts from commands:

Run `.claude/scripts/bash/check.sh --json` from project root.

Parse response:
```json
{"status":"success|error","data":{}}

### Memory/State Files

For persistent state across command runs:

.claude/memory/ ├── status.md # Progress tracking └── decisions.md # Decision log

## Directory Layout

.claude/ ├── commands/ │ ├── task.md │ └── task-subtask.md ├── scripts/ │ ├── bash/ │ │ ├── common.sh │ │ ├── setup-.sh │ │ └── check-.sh │ └── python/ │ └── helpers.py ├── templates/ │ └── *-template.md └── memory/ └── *.md

## Resources

### References

- `references/command-patterns.md` - Command authoring patterns
- `references/script-patterns.md` - Bash/Python script patterns
- `references/template-patterns.md` - Template design patterns

### Scripts

- `scripts/init-automation.sh` - Initialize .claude/ structure
- `scripts/validate-automation.sh` - Validate generated artifacts

### Assets

- `assets/command-template.md` - Starter command template
- `assets/script-template.sh` - Starter script template
- `assets/output-template.md` - Starter output template