Claude Actions¶

Claude actions leverage the Claude Agent SDK for AI-powered code transformations, enabling complex multi-file analysis and intelligent code modifications that would be difficult or error-prone with traditional approaches.

Configuration¶

[[actions]]
name = "action-name"
type = "claude"
prompt = "prompts/task.md"                      # Required
validation_prompt = "prompts/validate.md"       # Optional
max_cycles = 3                                  # Optional, default: 3
on_failure = "cleanup-action"                   # Optional
ai_commit = true                                # Optional, default: true

Fields¶

prompt (required)¶

Path to Jinja2 template file containing the task prompt for Claude.

Type: string (path relative to workflow directory)

Format: Jinja2 template (.j2 extension) or plain markdown

Location: Relative to workflow directory (e.g., prompts/update-python.md)

validation_prompt (optional)¶

Path to validation prompt template. If provided, Claude will run a validation cycle after the task cycle.

Type: string (path relative to workflow directory)

max_cycles (optional)¶

Maximum number of retry cycles if transformation fails.

Type: integer

Default: 3

on_failure (optional)¶

Action name to restart from if this action fails after all retry cycles.

Type: string (action name)

ai_commit (optional)¶

Whether to use AI-generated commit messages for changes made by this action.

Type: boolean

Default: true

Prompt Context¶

Prompts have access to all workflow context variables:

Variable	Description
`workflow`	Workflow configuration
`imbi_project`	Imbi project data
`github_repository`	GitHub repository (if applicable)
`working_directory`	Execution directory path
`starting_commit`	Initial commit SHA
`commit_author`	Git commit author (from config)
`commit_author_name`	Author name only
`commit_author_address`	Author email only
`workflow_name`	Current workflow name

Examples¶

Basic Code Transformation¶

Workflow config:

[[actions]]
name = "update-python-version"
type = "claude"
prompt = "prompts/update-python.md"

Prompt (prompts/update-python.md):

# Update Python Version to 3.12

Update all Python version references in this repository to Python 3.12.

## Files to Update

1. `pyproject.toml` - Update `requires-python` field
2. `.github/workflows/*.yml` - Update GitHub Actions Python version
3. `Dockerfile` - Update base image to python:3.12
4. `README.md` - Update installation instructions if they mention Python version

## Requirements

- Maintain backwards compatibility where possible
- Update all version strings consistently
- Preserve existing configuration structure
- Do not modify other unrelated settings

## Project Context

- **Project**: {{ imbi_project.name }}
- **Type**: {{ imbi_project.project_type }}
- **Current Python**: {{ imbi_project.facts.get('Programming Language', 'unknown') }}

## Success Criteria

Create a commit with all Python version references updated to 3.12.

## Failure Indication

If you cannot complete this task, return failure with details about what prevented completion.

Multi-Cycle Transformation with Retry¶

Workflow config:

[[actions]]
name = "refactor-codebase"
type = "claude"
prompt = "prompts/refactor.md"
max_cycles = 5
on_failure = "create-issue"  # Create GitHub issue if fails

With Validator¶

Workflow config:

[[actions]]
name = "update-dependencies"
type = "claude"
prompt = "prompts/update-deps.md"
validation_prompt = "prompts/validate-deps.md"

Validator prompt:

# Validate Dependency Updates

Verify that the dependency updates were successful:

1. Check that `requirements.txt` or `pyproject.toml` has been updated
2. Verify no breaking changes were introduced
3. Confirm all imports still resolve correctly
4. Check that version constraints are reasonable

Return success if validation passes, failure otherwise with specific errors.

Complex Transformation¶

Workflow config:

[[actions]]
name = "migrate-to-pydantic-v2"
type = "claude"
prompt = "prompts/pydantic-migration.md"
max_cycles = 10

Prompt:

# Migrate to Pydantic V2

Migrate this codebase from Pydantic v1 to Pydantic v2.

## Migration Steps

1. **Update imports**: Change `pydantic` imports to v2 syntax
2. **Config classes**: Convert `Config` class to `model_config` dict
3. **Validators**: Update `@validator` to `@field_validator`
4. **Field definitions**: Update `Field(...)` syntax changes
5. **JSON methods**: Replace `.dict()` with `.model_dump()`, `.json()` with `.model_dump_json()`

## Files to Process

Scan the repository for Python files containing:
- `from pydantic import`
- `class.*\\(.*BaseModel\\)`
- `@validator`
- `.dict()` or `.json()` calls on Pydantic models

## Testing

After making changes:
1. Run tests if they exist: `pytest tests/`
2. Check for import errors
3. Verify all models still validate correctly

## Commit Message

````
Migrate from Pydantic v1 to v2

- Update imports to v2 syntax
- Convert Config classes to model_config
- Update validators to field_validator
- Replace .dict()/.json() with .model_dump()/.model_dump_json()

Project: {{ imbi_project.name }}
````

## Failure Conditions

Return failure if:
- Unable to identify Pydantic usage patterns
- Migration would break existing functionality
- Tests fail after migration
- Manual intervention required

Include specific error details and affected files in the failure response.

Prompt Best Practices¶

Clear Objectives¶

# Update Docker Base Image

**Goal**: Update the Dockerfile to use python:3.12-slim as the base image.

**Files**: `Dockerfile`, `docker-compose.yml`

**Requirements**:
- Change base image in all Dockerfiles
- Maintain multi-stage build structure if present
- Update docker-compose.yml references
- Keep existing COPY, RUN, CMD instructions

Specific Instructions¶

## Step-by-Step Process

1. Locate all Dockerfile* files in the repository
2. For each Dockerfile:
   a. Find the `FROM` instruction
   b. Replace with `FROM python:3.12-slim`
   c. Keep any `AS builder` or stage names
3. Update docker-compose.yml if it hardcodes Python version
4. Commit changes with message: "Update Python base image to 3.12"

Success/Failure Criteria¶

## Success Criteria

You must:
- ✓ Update all Dockerfiles
- ✓ Maintain working configuration
- ✓ Create a git commit
- ✓ Include descriptive commit message

## Failure Indication

Return failure if:
- No Dockerfile found in repository
- Unable to parse existing Dockerfile syntax
- Changes would break the build process
- Multiple conflicting Dockerfile versions exist

Include the specific error and list of files examined in the failure response.

Project Context Usage¶

## Project-Specific Considerations

- **Project**: {{ imbi_project.name }}
- **Type**: {{ imbi_project.project_type }}
- **Namespace**: {{ imbi_project.namespace }}

{% if imbi_project.project_type == 'api' %}
This is an API project - ensure uvicorn/fastapi configurations are preserved.
{% elif imbi_project.project_type == 'consumer' %}
This is a consumer - ensure message handling configurations are intact.
{% endif %}

{% if imbi_project.facts %}
## Known Facts
{% for key, value in imbi_project.facts.items() %}
- **{{ key }}**: {{ value }}
{% endfor %}
{% endif %}

Failure Handling¶

Failure Files¶

Claude actions detect failure through specific files created in the working directory:

File Name	Meaning
`ACTION_FAILED`	Generic action failure
`{ACTION_NAME}_FAILED`	Specific action failure
Custom names	Custom failure indicators

Prompt instructions for failure:

## Failure Indication

If you cannot complete this task, return failure with:

1. **Reason**: Why the task failed
2. **Files Examined**: List of files you checked
3. **Errors Encountered**: Specific error messages
4. **Manual Steps**: What a human would need to do
5. **Context**: Any relevant information for debugging

Example failure response:
````
Unable to parse pyproject.toml due to syntax error

Files examined: pyproject.toml, requirements.txt
Error: toml.decoder.TomlDecodeError at line 15
Manual steps: Fix toml syntax error in pyproject.toml line 15
````

Retry Mechanism¶

[[actions]]
name = "fragile-transformation"
type = "claude"
prompt = "prompts/transform.md"
max_cycles = 5        # Try up to 5 times
on_failure = "cleanup" # Run cleanup action if all cycles fail

Cycle behavior:

Execute transformation
Check for failure files
If failure detected and cycles remaining, retry
If all cycles exhausted, trigger on_failure action
Pass error context to retry attempts

Error Context in Retries¶

On retry, the prompt receives additional context:

# Appended to prompt automatically:
"""
---
You need to fix problems identified from a previous run.
The errors for context are:

{
  "result": "failure",
  "message": "Unable to update dependencies",
  "errors": ["Package X not found", "Version conflict with Y"]
}
"""

Advanced Usage¶

Conditional Prompts¶

Workflow:

[[actions]]
name = "language-specific-update"
type = "claude"
prompt = "prompts/{{ imbi_project.facts.get('Programming Language', 'unknown') | lower }}-update.md"

Multi-Stage Transformations¶

[[actions]]
name = "stage1-refactor"
type = "claude"
prompt = "prompts/stage1.md"

[[actions]]
name = "stage2-optimize"
type = "claude"
prompt = "prompts/stage2.md"

[[actions]]
name = "stage3-document"
type = "claude"
prompt = "prompts/stage3.md"

With Pre/Post Actions¶

[[actions]]
name = "backup-files"
type = "file"
command = "copy"
source = "repository:///src/"
destination = "repository:///src.backup/"

[[actions]]
name = "ai-refactor"
type = "claude"
prompt = "prompts/refactor.md"
on_failure = "restore-backup"

[[actions]]
name = "run-tests"
type = "shell"
command = "pytest tests/"
working_directory = "repository:///"

[[actions]]
name = "restore-backup"
type = "file"
command = "move"
source = "repository:///src.backup/"
destination = "repository:///src/"

Integration with Other Actions¶

Claude + Shell (Test Verification)¶

[[actions]]
name = "ai-code-update"
type = "claude"
prompt = "prompts/update.md"

[[actions]]
name = "verify-tests"
type = "shell"
command = "pytest tests/ -v"
working_directory = "repository:///"

Claude + File (Template Application)¶

[[actions]]
name = "generate-base-config"
type = "template"
source_path = "config.yaml.j2"
destination_path = "repository:///config.yaml"

[[actions]]
name = "customize-config"
type = "claude"
prompt = "prompts/customize-config.md"

Claude + Git (Commit Verification)¶

[[actions]]
name = "ai-transformation"
type = "claude"
prompt = "prompts/transform.md"

[[actions]]
name = "verify-commit"
type = "shell"
command = "git log -1 --pretty=%B"
working_directory = "repository:///"

Performance Considerations¶

API Costs: Each cycle makes Claude API calls
Execution Time: Complex transformations can take several minutes
Context Size: Large repositories may hit context limits
Rate Limiting: Respect Anthropic API rate limits

Security Considerations¶

Code Execution: Claude can execute arbitrary code in the repository context
Sensitive Data: Prompts and code are sent to Anthropic API
API Keys: Ensure API keys are properly secured
Verification: Always verify AI-generated changes before merging

Implementation Notes¶

Working directory isolated per execution
Automatic cleanup on success or failure
Full logging of Claude interactions at DEBUG level