# CLI Development Use when adding or changing Go CLI commands, flags, handlers, interactive TUIs, domain packages, or any mutating behavior. ## Before Starting - Search for the closest existing command pattern instead of guessing APIs from memory or documentation. - List affected command, domain, test, schema, documentation, and Web API files. - Define acceptance criteria before changing public behavior. Ask only when ambiguity would materially change scope or interfaces. - Use TDD: create a reproducible failing test, then write the smallest implementation that passes it. ## Command Layering `cmd/skillshare/.go` should contain only flag parsing, validation, and mode dispatch. When a handler approaches roughly 300 lines or mixes concerns, split it using existing suffixes: | Suffix | Responsibility | |---|---| | `_handlers.go` | Core orchestration | | `_project.go` | Project-mode behavior | | `_render.go` / `_format.go` | Output rendering and formatting | | `_prompt.go` / `_prompt_tui.go` | Decisions and prompts | | `_tui.go` | Full-screen Bubble Tea UI | | `_batch.go` | Batch orchestration | | `_resolve.go` | Target/resource resolution | | `_context.go` | Mode-specific context | Put testable core logic in `internal//`. Do not let the CLI, Web API, and UI implement separate versions of the same business logic. ## Global and Project Mode Most commands route through `parseModeArgs()` for global (`-g`) or project (`-p`) mode. Before changing behavior, verify: - whether the modes use different configuration, registry, source, or target paths; - whether project mode needs a separate handler; - whether their flag sets are actually the same; - whether tests cover mode precedence, working directory, and missing configuration. ## Output and Interaction - Reuse `internal/ui` and existing Bubble Tea components instead of introducing another prompt framework. - Preserve dispatch order: structured JSON → TUI when interactive and allowed → empty state → plain text. - Structured-output stdout must remain machine-readable; progress, spinners, and diagnostics must not contaminate JSON. - When adding or changing a flag, inspect `--help`, completions, website command documentation, and tests. - Completions are five hand-written scripts (`cmd/skillshare/completion_{bash,zsh,fish,powershell,nushell}.go`) that do not read the CLI's dispatch, so they drift silently. Any new or renamed command, subcommand, or flag must be added to all five in the same change; the literal-content check in `tests/integration/completion_test.go` should name it. Installed completions are a copy, so users only see changes after rerunning `skillshare completion --install`. - Noninteractive automation should use explicit flags. Never treat `--force` as a universal prompt bypass. ## Mutating Behavior Operations that change configuration, sources, targets, or managed files must: - follow existing dry-run, backup, rollback, and conflict-handling patterns; - write an oplog entry to `operations.log` with the operation, status, duration, and necessary arguments; - send security scan events to the audit log rather than the regular operation log; - preserve path validation, scope checks, and ownership checks; - use domain uninstall/remove flows for managed state rather than replacing them with filesystem deletion. ## Tests Integration tests use `internal/testutil.NewSandbox(t)` and `RunCLI` or `RunCLIInDir`: ```go func TestFeature_BasicCase(t *testing.T) { sb := testutil.NewSandbox(t) defer sb.Cleanup() sb.CreateSkill("test-skill", map[string]string{ "SKILL.md": "---\nname: test-skill\n---\n# Content", }) result := sb.RunCLI("command", "args...") result.AssertSuccess(t) result.AssertOutputContains(t, "expected output") } ``` For a bug fix, prove that the test fails before the fix. Add an E2E runbook in `ai_docs/tests/_runbook.md` for new commands, install/uninstall/sync flows, security behavior, multi-step workflows, or OS/network/permission cases that integration tests cannot cover. All command execution and isolation rules live in `testing`. Never run the CLI or tests on the host. ## Web API When a dashboard endpoint is needed: 1. Use existing `writeJSON` and `writeError` helpers in `internal/server/handler_.go`. Decode request bodies with `decodeJSON` or `decodeJSONWith` (`internal/server/json_body.go`), which cap the body size and return 413 when it is too large; do not call `json.NewDecoder(r.Body)` directly. 2. Register the method and route in `internal/server/server.go`. 3. Handle scope explicitly through `s.IsProjectMode()` or the existing guards. 4. Add handler tests and verify UI client types and query invalidation. 5. Share an `internal/` package when the CLI and API expose the same operation; do not shell out between them. Sync is the main example: the CLI and the server both run per-target sync through `internal/sync` (`SyncSkillTarget`, `RunAgentSync`, `RunExtraTargets`). Both follow CLI semantics: every target runs, and a failed target is reported as a partial failure instead of stopping the loop. Change sync behavior in these runners, not in a command or handler loop. ## Completion Criteria - The failing test now passes, along with proportionate neighboring tests. - Handler split, dual-mode behavior, structured output, oplog, Web API, and all five shell completions were reviewed. - Public behavior changes were synchronized after loading `documentation`. - Commands were verified inside the devcontainer using `testing` guidance.