basecamp-cli: Instructions file for Claude Code

Basecamp CLI Development Context

Getting Started

See CONTRIBUTING.md for build setup, testing, and PR workflow.

The standard development loop in this repo: make changes, run bin/ci, fix what it catches, repeat until green, then push. Treat bin/ci as your inner-loop companion, not a final hurdle.

Repository Structure

basecamp-cli/
├── cmd/basecamp/     # Main entrypoint
├── internal/
│   ├── appctx/       # Application context
│   ├── auth/         # OAuth authentication
│   ├── cli/          # CLI framework
│   ├── commands/     # Command implementations
│   ├── completion/   # Shell completion
│   ├── config/       # Configuration management
│   ├── dateparse/    # Date parsing
│   ├── hostutil/     # Host utilities
│   ├── models/       # Data models
│   ├── names/        # Name resolution
│   ├── observability/ # Tracing and metrics
│   ├── output/       # Output formatting
│   ├── presenter/    # Output presentation
│   ├── resilience/   # Retry and backoff
│   ├── sdk/          # Basecamp SDK wrapper
│   ├── tui/          # Terminal UI
│   └── version/      # Version info
├── e2e/              # BATS integration tests
├── skills/           # Agent skills
├── hooks/            # Agent lifecycle hooks (both plugin agents)
├── .claude-plugin/   # Claude Code integration
└── .codex-plugin/    # Codex plugin manifest

Coding-agent integrations

Coding-agent integration lives in internal/harness (agent registry, detection, plugin and skill health checks) and internal/commands/wizard_agents.go (basecamp setup claude|codex|grok|agents). Claude Code and Codex each get a native plugin from the basecamp/claude-plugins marketplace and have registrations of their own (claude.go, codex.go). The plugin is basecamp-cli@37signals. During the deprecation window the marketplace keeps basecamp as an alias with the same source; setup treats basecamp@37signals as stale and replaces it by key, and the SessionStart hook (routed through agent-hook pre-commit-snapshot so older CLIs stay silent) tells alias installs once to switch. That is safe only while basecamp in the marketplace means this plugin: drop the isStalePluginKey / CodexLegacyPluginKey handling before the marketplace points basecamp at the hosted connector. Grok Build has no plugin: it reads the shared ~/.agents/skills/basecamp skill directly, so it is a row of harness.SkillAgent (name, id, home env var, home directory, binary) in skill_agent.go, and everything in internal/commands that touches a shared-skill agent — the setup handler, the BASECAMP_SETUP_AGENT values, doctor's remediation — loops over harness.SkillAgents() rather than naming it. A new shared-skill agent is a new row; the skill picker's (Global) row, the prose lists in the installers and the docs are the places to update by hand. setup <id> never fabricates an agent's home directory: a skill-only agent that is not detected is reported missing, not created.