Agent Workspace Setup¶

Overview¶

This guide provides minimal steps for bootstrapping the agent development workspace quickly.

Prerequisites¶

Git installed and configured
Code editor with Amazon Q plugin (VS Code, Zed, etc.)
Terminal/command line access
agentctl installed (see below)

Install agentctl¶

# macOS/Linux
brew tap geronimo-iia/agent && brew install agentctl

# Windows
choco install agentctl

# or via asdf (version manager)
asdf plugin add agentctl https://github.com/geronimo-iia/asdf-agentctl.git
asdf install agentctl latest
asdf global agentctl latest

# or via cargo
cargo install agent-ctl

Verify: agentctl --version

Installation Process¶

Step 1: Create Workspace Directory¶

# Create workspace directory
mkdir agent-workspace
cd agent-workspace

Step 2: Clone Agent Repositories¶

# Clone core agent repositories
git clone https://github.com/geronimo-iia/agent-foundation.git agent-foundation
git clone https://github.com/geronimo-iia/agent-skills.git agent-skills
git clone https://github.com/geronimo-iia/agent-software.git agent-software

Step 3: Configure IDE Integration¶

Amazon Q Plugin¶

Install Amazon Q plugin in your IDE
Open the agent-workspace directory
Copy rule templates to .amazonq/rules/ for automatic context activation:
From agent-foundation/rules/templates/ (documentation and workspace standards)
From agent-software/rules/templates/ (development standards)
Customize the templates for your workspace structure
The .amazonq/rules/ directory will automatically apply workspace standards

Step 4: Setup Agent Skills Hub (Optional)¶

# Add the agent-skills hub registry
agentctl hub add --type skills agent-skills https://raw.githubusercontent.com/geronimo-iia/agent-skills/main/index.json --git-url https://github.com/geronimo-iia/agent-skills

# List available skills
agentctl skill list

# Install useful development skills
agentctl skill install agentctl          # agentctl management skill
agentctl skill install python-scaffold  # Python project scaffolding
agentctl skill install semantic-commit  # Semantic commit helpers

Step 5: Ready to Use¶

The workspace is now ready for development:

agent-foundation/ - Reference stable specifications
agent-skills/ - Available skills for agent use
agent-software/ - Software development standards and engineering practices
agentctl - Validate and generate hub indexes
Workspace rules - Automatically enforce standards through Amazon Q

For detailed usage, explore the specifications in each repository.