Guilde Lite - Modern Dev Environment

Reproducible, automated development environment for AI/Agent development.

Mise-First Policy

This setup prefers mise for runtimes and CLI tools, and uses Homebrew only for system apps (GUI tools, fonts, container runtime). If a tool exists in both, mise is the default; Homebrew is fallback when mise doesn’t support it.

Quick Start

# Clone the repo
git clone https://github.com/YOUR_ORG/guilde-lite.git ~/guilde-lite
cd ~/guilde-lite

# Run bootstrap (choose one)
./install.sh              # Default: all Homebrew + runtimes + configs
./install.sh minimal      # Core + CLI + runtimes only
./install.sh developer    # Minimal + terminal + containers
./install.sh full         # Everything including AI and databases

Staged Installation

Install incrementally to test each step:

# Run stages individually
task stage:1              # Core (git, jj, just, mise, task)
task stage:2              # CLI tools (ripgrep, fd, bat, etc.)
task stage:3              # Terminal (Ghostty, tmux, fonts)
task stage:4              # Containers (OrbStack, kubectl, helm)
task stage:5              # Database clients (psql, redis-cli)
task stage:6              # Cloud/AWS (awscli, granted)
task stage:7              # AI tools (Cursor)
task stage:8              # Security (age, sops, trivy)
task stage:9              # Build tools (cmake, ninja)
task stage:runtimes       # Languages (Go, Python, Rust, Bun)
task stage:configs        # Config files (shell, git, tmux)
task stage:databases      # Start database containers
task stage:ai-tools       # Claude Code

# Verify any stage
task stage:1:verify
task stage:2:verify
# etc.

# See all stages
task help:stages

Preset Bundles

Bundle	What's Included
setup:minimal	Core + CLI + runtimes
setup:developer	Minimal + terminal + containers + build
setup:full	Everything including AI and databases

What's Included

Modern Tooling (Native Drop-in Replacements)

Legacy	Modern	Purpose
nvm/pyenv/goenv	mise	Universal runtime version manager
npm/yarn	bun	JS runtime + package manager
pip/pip-tools	uv	Fast Python package manager
Docker Desktop	OrbStack	Lightweight container engine
grep	ripgrep	Fast search
find	fd	Fast file finder
cat	bat	Syntax-highlighted file viewer
ls	eza	Modern file listing
make	Task	Go-based task runner

Languages & Runtimes

• Go (latest) - Orchestration, CLI tools, agents
• Rust - Systems programming, performance-critical code
• Python (latest) - AI/ML, scripting, data processing
• Bun - JavaScript/TypeScript runtime
• Deno - Secure JS/TS runtime

AI Coding Tools

• Claude Code - Anthropic's CLI assistant
• Cursor - AI-native editor
• Gemini CLI - Google Gemini CLI
• OpenAI Codex - OpenAI CLI assistant
• OpenCode - OpenCode CLI assistant
• Global install option: task mise:global:setup (see docs/GLOBAL-AI-TOOLS.md)

Databases (with Vector Extensions)

• PostgreSQL 16 + pgvector - Relational + vector similarity
• Redis Stack - Cache + RediSearch + vector search
• MongoDB - Document store
• Qdrant - Purpose-built vector DB
• ChromaDB - Embedding database

Multi-Agent Workflow System

Guilde Lite includes a comprehensive multi-agent orchestration system for AI-assisted development, packaged as a Claude Code plugin.

Loading the Plugin

# Start Claude Code with the guilde-workflows plugin
claude --plugin-dir .

# Or add an alias to ~/.zshrc for convenience
alias claude-guilde='claude --plugin-dir /path/to/guilde-lite'

Quick Start

Once the plugin is loaded, use these commands:

/guilde-workflows:conductor-status      # View current track and progress
/guilde-workflows:conductor-new-track   # Start a new implementation track
/guilde-workflows:conductor-implement   # Work on current phase with TDD
/guilde-workflows:conductor-checkpoint  # Mark phase complete

Key Features

Feature	Description
12 Specialized Agents	Research (haiku), Development (sonnet), Review (opus)
10 Skills	Context loading, TDD phases, code review pipeline
7 Hookify Rules	Safety, TDD enforcement, doc sync reminders
Telemetry	OpenTelemetry metrics with Grafana dashboards

Agent Tiers

• Research (haiku): context-explorer, docs-researcher, codebase-analyzer
• Development (sonnet): spec-builder, frontend-developer, test-automator, database-optimizer
• Review (opus): code-reviewer, security-auditor, architect-reviewer

See docs/MULTI-AGENT-WORKFLOW.md for full documentation.

Commands

task              # List all commands
task -l           # List all commands with descriptions
task setup        # Full environment setup
task verify       # Verify installation
task db:up        # Start databases
task db:down      # Stop databases
task lint         # Run all linters
task test         # Run all tests
task update:all   # Update Homebrew + mise tools

Maintenance

# Update everything
task update:all

# Show tool status summary
task tools:status

Claude Flow

# Initialize claude-flow in this repo
task claude-flow:init

# Install claude-flow globally (bun)
task claude-flow:install

# Show claude-flow version
task claude-flow:version

# Quick claude-flow smoke check
task claude-flow:doctor

# Start the MCP server
task claude-flow:mcp:start

# Run any claude-flow command
task claude-flow:run -- --help

Uses claude-flow@latest. Included in task setup:full via task claude-flow:install.

AI Agent Sandboxing

Three levels of isolation to prevent AI agents from doing anything nefarious:

# Level 1: Basic (file/network restrictions)
task sandbox:basic -- claude

# Level 2: Container isolation
task sandbox:container -- claude

# Level 3: Full VM isolation
task sandbox:vm -- claude

CI/CD

# Run CI locally
task ci:local

# Setup self-hosted runner (local Mac)
task ci:runner:local

# Launch ephemeral runner on AWS
task ci:runner:aws

Directory Structure

guilde-lite/
├── Brewfile              # System dependencies (Homebrew)
├── mise.toml             # Runtime versions
├── Taskfile.yml          # Automation engine
├── install.sh            # Bootstrap script
├── config/
│   ├── ghostty.conf      # Terminal config
│   └── tmux.conf         # tmux config
├── sandbox/
│   ├── basic.sb          # macOS sandbox profile
│   ├── claude-settings.json  # Claude Code restrictions
│   └── Dockerfile.agent  # Container sandbox
├── docker/
│   └── docker-compose.yml    # Database stack
├── ci/
│   ├── runner-local.sh   # Self-hosted runner (Mac)
│   └── runner-aws.yaml   # SkyPilot runner (AWS)
└── .github/
    └── workflows/
        └── ci.yml        # GitHub Actions workflow

Configuration

Ghostty

Copy config to Ghostty's config directory:

task config:ghostty

tmux

Prefix key: Ctrl+Space

Key bindings:

• Prefix + | - Split vertical
• Prefix + - - Split horizontal
• Prefix + t - Floating terminal
• Prefix + g - Lazygit popup
• Prefix + d - Lazydocker popup
• Ctrl+h/j/k/l - Navigate panes

AWS

# Login via Granted (modern aws-vault replacement)
task aws:login

# Connect to EC2 via SSM (no SSH keys needed)
task aws:ssm -- i-instanceid

Security Considerations

AI Agent Restrictions

The sandbox/claude-settings.json file blocks dangerous commands:

• Destructive operations (rm -rf, mkfs, etc.)
• System modifications (launchctl, networksetup)
• Credential/secret access
• Force pushes to main/master
• Package publishing

Allowed Network Domains

AI agents can only access:

• API endpoints (anthropic, openai, github)
• Package registries (npm, pypi, crates.io, pkg.go.dev)

Audit Logging

All tool uses are logged to /tmp/claude-audit.log

Customization

Adding New Runtimes

Edit mise.toml:

[tools]
java = "21"
ruby = "3.3"

Adding System Tools

Edit Brewfile:

brew "new-tool"
cask "new-app"

Then run:

task brew

Troubleshooting

mise not found after install

source ~/.zshrc
# or restart terminal

Docker/OrbStack not responding

orb restart

Databases not starting

task db:reset  # Warning: destroys data

Claude Code Plugin Issues

If plugins fail to load or /doctor reports errors:

# Check plugin structure
ls -la ~/.claude/plugins/cache/<marketplace>/<plugin>/

# View debug logs
tail -100 ~/.claude/debug/*.txt | grep "<plugin-name>"

Known Issues:

• business-analytics plugin: Upstream missing required files. See PLUGIN-FIX-SUMMARY.md for fix.

For detailed plugin troubleshooting, see docs/PLUGIN-FIX-BUSINESS-ANALYTICS.md.

Contributing

1. Fork the repository
2. Create a feature branch
3. Run tests: task ci:local
4. Submit a pull request

License

MIT