automation-builder

name

automation-builder

description

Analyze codebases and generate Claude Code automation infrastructure including commands, scripts, and templates for systematic task execution. Use when the user wants to create reusable automation workflows, generate .claude/commands files, create supporting bash/python scripts, build markdown templates for structured outputs, or establish multi-step task execution frameworks that work across projects.

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