[FEAT] Replace Makefile with CLI driven by Pi Agent

[ryaneggz]

Summary

Replace the root Makefile with a Python CLI (sandbox or sb) that wraps all sandbox lifecycle operations (quickstart, build, shell, stop, clean, list, heartbeat) and is driven by Pi Agent for interactive orchestration.

Motivation

• The Makefile is hitting limits: variable scoping is fragile (ifdef NAME), error messages are ad-hoc, and extending it (flags, subcommands, config files) requires increasingly brittle shell.
• A proper CLI enables richer UX: --help per subcommand, tab completion, config file support, colored output, progress bars, and structured error handling.
• Pi Agent integration means the CLI can be invoked conversationally — "spin up a new agent for Zoho CRM" triggers the same provisioning flow as sb quickstart --name zoho-crm.
• Opens the door to a plugin/skill system where agents can extend the CLI with new subcommands.

Proposed Implementation

CLI Framework

• Python CLI using click or typer (TBD during planning)
• Entry point: sandbox (or sb) installed via pip install -e . at repo root
• Subcommands mirror current Make targets: quickstart, build, run, shell, stop, clean, list, heartbeat sync|stop|status|migrate

Pi Agent Integration

• CLI exposes a pi subcommand (or runs as a Pi skill) so the agent can invoke sandbox operations programmatically
• Agent can call CLI subcommands with structured args instead of shelling out to Make

Migration Path

1. Build CLI alongside Makefile (both work during transition)
2. Validate parity: each Make target has a CLI equivalent with identical behavior
3. Remove Makefile once CLI is validated

---

Agent Assignment

Metadata

IMPORTANT: The very first step should ALWAYS be validating this metadata section to maintain a CLEAN development workflow.

agent: "TBD"
branch: "feat/cli"
worktree_path: ".worktrees/feat/cli"
pull_request: "FROM feat/cli TO development"

Workflow

# Work on feat/cli branch
cd .worktrees/feat/cli
# Develop CLI, test against existing Make targets
# When complete — PR from feat/cli to development

---

Acceptance Criteria

• CLI installed via pip install -e . with sandbox entry point
• All current Makefile targets have CLI equivalents with identical behavior
• sandbox --help documents all subcommands
• Pi Agent can invoke CLI subcommands programmatically
• Makefile removed after CLI parity validated
• No regressions to existing sandbox functionality
• PR targets development branch

[ryaneggz]

Closing as completed.