Autonomous Agent Workflow

Relevant source files

The following files were used as context for generating this wiki page:

• CLAUDE.md
• lib/kamal/cli/main.rb
• lib/kamal/commander.rb
• lib/kamal/configuration.rb
• ROADMAP.md
• CONTRIBUTING.md

The Autonomous Agent Workflow in this project refers to the structured operational procedures used by AI agents to manage the development, maintenance, and deployment of the Kamal (specifically the dash fork) ecosystem. This workflow is codified through specific "Slash Commands" that dictate how the agent branches, plans, executes changes, and verifies code within the multi-layered architecture of the application.

The workflow ensures compliance with fork-specific constraints, such as maintaining the main branch as a pristine mirror of upstream and performing all feature development on branches rooted from dash. It leverages a tiered model approach, utilizing different AI capabilities for orchestration, planning, and implementation tasks.
Sources: CLAUDE.md:88-100, CLAUDE.md:108-112

Workflow Orchestration: Slash Commands

The agent operates through a set of specialized commands designed to handle different stages of the software development lifecycle. These commands coordinate work across the project's technical layers, from the Thor-based CLI down to the SSHKit remote execution layer.

Primary Operational Commands

Command	Category	Purpose
/lfg	Execution	Full autonomous workflow: branch, understand, plan, TDD, verify, and PR.
/plan	Strategy	Read-only planning resulting in GitHub issues or Markdown plans.
/architect	Design	Coordinating work across CLI, Commander, Commands, and Configuration.
/tdd	Quality	Enforcing Red-Green-Refactor cycles using Minitest and Mocha.
/finish-prs	Maintenance	Driving open pull requests to a merge-ready state.

Sources: CLAUDE.md:88-100, CLAUDE.md:31-37

Autonomous Execution Flow

The sequence below illustrates the standard autonomous cycle triggered by the /lfg command.

The workflow prioritizes safety by ensuring feature branches never root off main, preventing pollution of the upstream mirror.
Sources: CLAUDE.md:46-49, CLAUDE.md:89

Architectural Integration

The agent workflow is designed to navigate and modify the project's five-layer architecture. Commands typically propagate from the user-facing CLI down through target resolution to final command construction.

Layered Interaction Model

Layer 4 (CLI):* Handles Thor commands and hooks. The agent uses /architect to coordinate changes here.

• Layer 3 (Commander): A singleton (KAMAL) managing target resolution and specific host/role filtering.
• Layer 2 (Commands): Docker command builders. The agent uses /security to audit these for shell escaping and secret handling.
• Layer 1 (Configuration): Validates deploy.yml and manages secrets. Eager validation is a key R1 roadmap goal to fail fast before SSH connections.

Sources: CLAUDE.md:31-37, lib/kamal/commander.rb:1-15, ROADMAP.md:34

Verification and Quality Assurance

A critical component of the autonomous workflow is the verification phase, which uses the project's internal testing infrastructure to ensure stability.

Test Execution Workflow

The agent is required to run the full test suite before proposing any changes.

1. Unit Testing: Execution of bundle exec ruby -Itest for fast feedback on logic changes in Configuration or Command builders.
2. Integration Testing: Running bin/test which involves real deploys in Docker-in-Docker environments.
3. Linting: Parallel Rubocop execution to maintain the rubocop-rails-omakase standard.

Sources: CLAUDE.md:20-25, CONTRIBUTING.md:24-28

Fork-Specific Constraints

The agent workflow must strictly adhere to the fork identity of the dash repository. This involves specific rules regarding release management and branch hygiene.

• Pristine Upstream: The main branch is fast-forward only. The agent must never commit directly to it.
• Branching Strategy: Feature branches must always root off dash. If the agent lands on a main-rooted branch (e.g., for upstreaming), it must materialize the toolkit without committing it using git restore --source=dash --worktree -- .claude CLAUDE.md.
• Proxy Image Contract: The agent must ensure the proxy image tag matches Kamal::Configuration::Proxy::Run::MINIMUM_VERSION before releasing the gem.

Sources: CLAUDE.md:41-52, CLAUDE.md:108-112

Deployment Lifecycle Management

The agent's /lfg workflow often interacts with the core deployment methods defined in Kamal::Cli::Main. These methods represent the automated steps the agent must mimic or modify.

Method	Source File	Description
setup	lib/kamal/cli/main.rb:2-15	Bootstraps servers and performs initial deploy.
deploy	lib/kamal/cli/main.rb:20-59	Main workflow: validation, build/push, hooks, and booting.
redeploy	lib/kamal/cli/main.rb:64-96	Deployment without bootstrapping or pruning.
rollback	lib/kamal/cli/main.rb:101-120	Reverts the application to a previous version.

Sources: lib/kamal/cli/main.rb:1-120

The Autonomous Agent Workflow serves as the operational glue that maintains the project's architectural integrity while allowing for rapid, verified iterations on the dash fork's unique features, such as load balancing and enhanced proxy capabilities.