Add shell completion command

[clawsweeper]

Summary

• Add spogo completion bash|zsh|fish using kong-completion rather than maintaining shell-specific command models.
• Derive commands, flags, aliases, and enum arguments from the existing Kong model.
• Handle completion requests before Spotify config, authentication, or profile validation.
• Document session and persistent shell setup.

Fixes #32.

Validation

• GOTOOLCHAIN=go1.25.0 go test -race ./...
• ./scripts/check-coverage.sh 90 (90.5%)
• go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.7.2 run
• go vet ./...
• go run golang.org/x/tools/cmd/deadcode@v0.45.0 -test ./...
• go run golang.org/x/vuln/cmd/govulncheck@latest ./...
• make docs-site
• Generated Bash, Zsh, and Fish script syntax checks
• Fish end-to-end completion checks for root, nested, and shell arguments

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 27, 2026, 6:07 PM ET / 22:07 UTC.

Summary
The PR adds spogo completion fish, a custom fish completion generator, dispatch before config/profile validation, regression tests, and README/docs/spec entries.

Reproducibility: not applicable. this is a feature PR rather than a reported bug. Source inspection shows current main lacks a completion command, while the PR adds one.

Review metrics: 2 noteworthy metrics.

• Diff surface: 8 files changed, +408/-8. The change is bounded to CLI dispatch, completion generation, tests, and docs, but adds a new user-facing command surface.
• CI status: 2 successful build checks. GitHub reports both CI build checks succeeded on the latest PR head, leaving product acceptance as the main remaining gate.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #32
Summary: This PR is the candidate implementation for the linked shell-completion feature request.

Members:

• canonical: Shell completions with a completion command #32 - The PR body uses closing syntax for the open shell-completion request, and GitHub reports it as the source issue.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• none.

Risk before merge

• [P1] Maintainers still need to decide whether introducing a fish-only completion command is the intended supported CLI surface.
• [P1] The generated output is covered by focused Go tests and CI, but there is no live fish-shell smoke evidence in the PR discussion.

Maintainer options:

1. Accept fish-first completion
   Maintainers can accept spogo completion fish as the initial supported shell-completion surface and merge once exact-head checks remain clean.
2. Pause for shell scope
   If fish-only support is not the intended product shape, keep the PR open and define the desired shell matrix in the linked feature request before merging.

Next step before merge

• [P2] No narrow automated repair remains; maintainers need to decide whether to ship the new fish-only completion command.

Security
Cleared: The diff adds Go CLI completion code, docs, and tests without dependency, workflow, package metadata, secrets, permissions, or downloaded-code changes.

Review details

Best possible solution:

Land the narrow completion fish command if maintainers accept the fish-first surface, and track any broader shell matrix separately.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a feature PR rather than a reported bug. Source inspection shows current main lacks a completion command, while the PR adds one.

Is this the best way to solve the issue?

Yes, subject to maintainer product acceptance: the patch adds a narrow top-level command and keeps completion output independent of auth/profile setup. The remaining question is supported-shell scope, not a concrete code defect found in this review.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against d797bd04e6ee.

Label changes

Label justifications:

• P3: This is a low-risk CLI ergonomics feature rather than a broken core workflow, security issue, or data problem.
• merge-risk: 🚨 other: Green CI does not settle the product decision to expose a new fish-only supported CLI command.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The PR is authored by repository automation, so the external contributor real-behavior proof gate does not apply.

Evidence reviewed

What I checked:

• Target policy check: No AGENTS.md exists inside the spogo checkout; the only AGENTS.md found was outside the target repository and was not applied as spogo policy. (d797bd04e6ee)
• Current main lacks completion command: The current CLI registry lists auth, search, info, playback, queue, library, device, and user commands, with no Completion command field. (internal/cli/cli.go:19, d797bd04e6ee)
• Current main validates profile before command execution: The current executable parses args and then proceeds into settings/context/profile validation with no completion-generation bypass. (cmd/spogo/main.go:38, d797bd04e6ee)
• Latest release lacks completion command: The v0.10.0 tag has the same CLI registry shape with no completion command. (internal/cli/cli.go:19, 10eed143b736)
• PR adds command registration: The PR head adds Completion CompletionCmd and restricts the shell positional argument to fish. (internal/cli/cli.go:23, 079a3ffb6a1e)
• PR bypasses auth/profile setup for completion: The PR dispatches cli.WriteCompletion immediately after parse and before settings/profile setup. (cmd/spogo/main.go:46, 079a3ffb6a1e)

Likely related people:

• Peter Steinberger: The current command registry, executable parser path, README, and spec content blame to the v0.10.0 release commit, with the latest main commit also from Peter Steinberger. (role: original CLI introducer and recent command-surface contributor; confidence: high; commits: 10eed143b736, d797bd04e6ee; files: internal/cli/cli.go, cmd/spogo/main.go, docs/spec.md)
• kk-spartans: The linked feature request was opened by kk-spartans, and Karthikeyan KK authored adjacent CLI/auth work touching internal/cli/cli.go. (role: source requester and adjacent CLI contributor; confidence: medium; commits: b396bf1408c1; files: internal/cli/cli.go, internal/cli/auth_import.go, internal/cli/auth_store.go)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

[clawsweeper]

🦞✅
ClawSweeper autofix is complete for this exact head.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper verdict: pass (sha=079a3ffb6a1ef8081ede9c6c27052dde3a77ff6f)
Head: 079a3ffb6a1e

No actionable findings remain. I removed the repair-loop label and left the PR open for maintainer review and merge.

Automerge progress:

• 2026-06-25 10:15:28 UTC validation and review 1 7fad80f6098f (complete) in 2m 59s Run: https://github.com/openclaw/clawsweeper/actions/runs/28162865231 already-current

• 2026-06-25 10:17:03 UTC repair completed 7fad80f6098f (branch updated) in 4m 34s Run: https://github.com/openclaw/clawsweeper/actions/runs/28162865231 initial automerge rebase is delegated to Codex repair

• 2026-06-25 10:17:02 UTC review queued 7fad80f6098f (after repair)

• 2026-06-25 10:22:02 UTC automerge wait 7fad80f6098f (blocked) in 9m 33s Run: https://github.com/openclaw/clawsweeper/actions/runs/28162865231 exact-head ClawSweeper review requires another repair

• 2026-06-25 10:22:03 UTC repair finished 7fad80f6098f (pushed) in 9m 34s Run: https://github.com/openclaw/clawsweeper/actions/runs/28162865231 repair_contributor_branch

• 2026-06-25 10:27:20 UTC review requested repair 7fad80f6098f (structured ClawSweeper marker: fix-required (finding=review-feedback sha=7fad80...)

• 2026-06-25 10:23:50 UTC repair started (running) in 1s Run: https://github.com/openclaw/clawsweeper/actions/runs/28162923816 automerge-openclaw-spogo-33

• 2026-06-25 10:23:54 UTC validation plan (passed) in 4s Run: https://github.com/openclaw/clawsweeper/actions/runs/28162923816 git diff --check

• 2026-06-25 10:24:10 UTC Codex write preflight (passed) in 20s Run: https://github.com/openclaw/clawsweeper/actions/runs/28162923816 danger-full-access

• 2026-06-25 10:26:54 UTC Codex edit 1 7fad80f6098f (complete) in 3m 4s Run: https://github.com/openclaw/clawsweeper/actions/runs/28162923816 exit 0

• 2026-06-25 10:27:14 UTC validation and review 1 079a3ffb6a1e (complete) in 3m 24s Run: https://github.com/openclaw/clawsweeper/actions/runs/28162923816 already-current

• 2026-06-25 10:28:49 UTC repair completed 079a3ffb6a1e (branch updated) in 4m 59s Run: https://github.com/openclaw/clawsweeper/actions/runs/28162923816 initial automerge rebase is delegated to Codex repair

• 2026-06-25 10:28:48 UTC review queued 079a3ffb6a1e (after repair)

• 2026-06-25 10:33:32 UTC automerge wait 079a3ffb6a1e (ready) in 9m 42s Run: https://github.com/openclaw/clawsweeper/actions/runs/28162923816 checks and exact-head review are ready

• 2026-06-25 10:33:25 UTC review passed 079a3ffb6a1e (structured ClawSweeper verdict: pass (sha=079a3ffb6a1ef8081ede9c6c27052dde3a77f...)

• 2026-06-25 10:33:33 UTC repair finished 079a3ffb6a1e (pushed) in 9m 43s Run: https://github.com/openclaw/clawsweeper/actions/runs/28162923816 repair_contributor_branch