1 · Machine setup (once per machine)

Everything on this page is workspace-global — it installs to /usr/local/bin, ~/.config/, or your OS package manager’s global location. None of it touches a specific project. Run it once per machine; every project you ever build reuses it.

Idempotency rule — verify before install

Every step here may already be done from an earlier project. Always check before installing — re-installing can overwrite config, bump versions, or invalidate auth sessions. The pattern throughout:

if command -v <tool> &>/dev/null; then
  echo "✅ <tool> already installed ($(<tool> --version 2>/dev/null | head -1))"
else
  echo "⚙️  Installing <tool>..."
  brew install <tool>   # or npm / direct download
fi

Run from any terminal — including the agent’s — since nothing here is project-specific.

1. GitHub CLI — gh (required)

gh lets the agent create repos, open PRs, and manage issues directly from the terminal with no MCP needed.

# Install if missing
command -v gh &>/dev/null && echo "gh present: $(gh --version | head -1)" || brew install gh

# Authenticate if not already
gh auth status &>/dev/null || gh auth login   # GitHub.com → HTTPS → login with browser

Verify: gh auth status reports Logged in to github.com as <you>.

2. MCP servers (optional but recommended)

MCP (Model Context Protocol) servers give the agent native tools for infrastructure, browsers, docs, and payments. Add them at user scope (-s user) so they’re available across all projects. A browser OAuth step (👤) is needed for some — the agent can’t click “Authorize.”

MCP	Why	Setup
DNS / CDN (e.g. Cloudflare)	DNS records, SSL, cache, WAF in later deploy phases	claude mcp add --transport http <name> <url> -s user then authorize in browser 👤
Hosting provider	Domains, databases, SSL, cron on your host	Per provider docs — usually claude mcp add <name> -e <API_TOKEN_ENV> -- npx -y <provider-mcp>
Playwright	Browser automation, screenshots, E2E checks	Usually a Claude Code plugin — no setup; else claude plugin add playwright
Context7	Current Laravel/Livewire/Tailwind docs in-session	Plugin or claude.ai integration
Stripe	Payment setup + verification	Stripe CLI (brew install stripe/stripe-cli/stripe → stripe login 👤) + Stripe MCP via OAuth
Gmail	Confirm transactional email actually arrives	claude.ai integration

Stripe agent-safety — internalize these once

The stripe login OAuth flow stores an unrestricted sk_* key in ~/.config/stripe/config.toml in plaintext. Treat that as your personal “default developer key” and never copy it elsewhere. The universal rules (same on every project):

1. Separate keys by actor — app key (broad, lives in server .env), agent key (narrow, lives in MCP config), developer key (narrow, lives in ~/.zshrc). Never the same key in two places.
2. sk_* never in shell env — only a narrowly-scoped test-mode rk_test_dev_* belongs in ~/.zshrc.
3. Human-gate every live-mode write — refunds, cancellations, deletions, bulk mutations always pause for confirmation.
4. Sandbox before live, always.
5. Conservative tool permissions in live mode.
6. Rotate keys on team changes and quarterly.

These get seeded into each project’s .claude/rules/ later (so the agent auto-loads them), but you only need to learn them once.

Laravel Boost is per-project, not here

Laravel Boost is a Composer package needing a Laravel project — install it in Phase 3 after the app is extracted (composer require laravel/boost --dev → php artisan boost:install). The project-level .mcp.json that registers it is covered in Cursor & other IDEs.

Never hardcode or print secrets

When you add a token to ~/.zshrc, verify it by length only — never echo its characters into an AI-assisted session:

[ -n "$CF_API_TOKEN" ] && echo "✅ token present (${#CF_API_TOKEN} chars, hidden)" || echo "❌ missing"

After editing ~/.zshrc, fully quit and reopen your editor (a “reload window” does not refresh env vars in the agent’s shell).

3. The permission-mode switcher (claude-mode)

The kit ships a claude-mode system — three permission presets (strict / medium / yolo) plus a set-claude-mode.sh switcher and a block-destructive.sh hook. It’s wired per-project in Claude config, but you may also keep the switcher on your PATH for convenience. The full presets and the precedence model are documented there.

4. The deploy orchestrator skill (optional, global)

The deployment pipeline is driven by an orchestrator skill that walks all phases interactively with built-in safety rules (tinker, migrations, vendor handling, secret handling). Install it once into your user-global commands so it’s available in every project:

mkdir -p ~/.claude/commands
# Copy the orchestrator template from the kit (or your guides checkout) into the global commands dir:
cp <kit-or-guides>/deploy-codecanyon.md ~/.claude/commands/deploy-codecanyon.md

Restart Claude Code, then run /deploy-codecanyon in any project to confirm it loads. The kit’s skills folder includes the orchestrator so the project-local copy travels with the repo too.

Verify the machine is ready

echo "=== Workspace verification ==="
gh auth status &>/dev/null && echo "PASS: gh authenticated" || echo "FAIL: gh not authenticated"
[ -n "$CF_API_TOKEN" ] && echo "PASS: DNS token present" || echo "SKIP: DNS token not set (optional)"
command -v jq &>/dev/null && echo "PASS: jq present (needed for permission-mode merge)" || echo "WARN: install jq (brew install jq)"

Then in an agent session, smoke-test each MCP you configured (“list my zones”, “navigate to example.com and screenshot”, “look up Laravel docs”, “get Stripe account info”).

Gate

✅ gh authenticated. Optional MCPs you chose respond. jq installed. → Continue to Project constitution.