go-cli.json

{
  "profile_id": "go-cli",
  "reviewed_on": "2026-10-23",
  "evidence_status": "documentation-reviewed; commands not executed",
  "starting_points": [
    {
      "name": "Go module plus Cobra generator",
      "when": "A new command application selects Cobra; use the standard-library flag package for a deliberately smaller CLI without a Cobra scaffold.",
      "steps": [
        "Install the project-selected Go toolchain and create an empty project directory. Replace paths and module name with real values.",
        "Initialize the module before Cobra. Set COBRA_CLI_VERSION to a selected published version (including v prefix); ensure the Go install bin directory is on PATH.",
        "Generate the command skeleton, review author/license defaults and add application logic and tests."
      ],
      "commands": [
        {
          "run": "mkdir project",
          "cwd": "/path/to/workspace (existing local source parent)",
          "purpose": "Create a new CLI source directory."
        },
        {
          "run": "go mod init example.com/project",
          "cwd": "/path/to/workspace/project",
          "purpose": "Initialize module metadata."
        },
        {
          "run": "go install github.com/spf13/cobra-cli@\"${COBRA_CLI_VERSION:?Set the selected Cobra CLI version}\"",
          "cwd": "/path/to/workspace/project",
          "purpose": "Install the selected generator version."
        },
        {
          "run": "cobra-cli init",
          "cwd": "/path/to/workspace/project",
          "purpose": "Generate main.go and cmd/root.go using Cobra."
        }
      ],
      "notes": [
        "Choose the actual project license and author; inspect ~/.cobra.yaml because it can alter output. Add --viper only if Viper is explicitly selected.",
        "If Cobra is not selected, go mod init remains required module initialization; flag and Bubble Tea do not require this Cobra scaffold."
      ]
    }
  ],
  "follow_up_generators": [
    {
      "name": "Cobra subcommand",
      "when": "When adding commands to the generated Cobra application.",
      "commands": [
        {
          "run": "cobra-cli add serve",
          "cwd": "/path/to/workspace/project (existing Cobra root)",
          "purpose": "Generate an example serve command for subsequent implementation."
        }
      ],
      "notes": [
        "Replace serve with the intended command name; review generated command registration, help and error/exit behavior."
      ]
    },
    {
      "name": "Optional Bubble Tea v2 terminal interface",
      "when": "Only when the CLI needs an interactive terminal user interface; a conventional command interface can stay with Cobra or the standard library.",
      "commands": [
        {
          "run": "go get charm.land/bubbletea/v2@latest",
          "cwd": "/path/to/workspace/project (module root)",
          "purpose": "Add Bubble Tea v2 using its current vanity module path."
        }
      ],
      "notes": [
        "Use the v2 import `tea \"charm.land/bubbletea/v2\"` and follow the v2 Model/View API: `View() tea.View`, not the v1 `View() string`. The v2 module path and API differ from `github.com/charmbracelet/bubbletea` v1; do not mix their examples or imports.",
        "Bubble Tea is a framework integration, not an application generator. Build it only when interactive screens are required; add related Charm v2 modules such as Bubbles or Lip Gloss only if selected and use their matching `/v2` module paths."
      ]
    },
    {
      "name": "GoReleaser configuration",
      "when": "Only when GoReleaser is selected for this application and no release configuration exists.",
      "commands": [
        {
          "run": "goreleaser init",
          "cwd": "/path/to/workspace/project (module root; selected GoReleaser installed)",
          "purpose": "Generate .goreleaser.yaml."
        },
        {
          "run": "goreleaser check",
          "cwd": "/path/to/workspace/project",
          "purpose": "Validate the reviewed release configuration."
        }
      ],
      "notes": [
        "Install and record the project-selected GoReleaser release first. Review build entry points, targets, hooks and publishing settings; generation does not authorize a release."
      ]
    }
  ],
  "preserve": [
    "Preserve go.mod and go.sum when generated by dependency resolution; record the Go version and resolved generator versions.",
    "go mod init creates module metadata, not source files, tests, a service structure or .gitignore. Add project-specific ignores, including OS metadata, without claiming they came from Go.",
    "Keep generator-created files as the baseline; document deliberate changes and do not replace standard defaults with a handwritten approximation.",
    "Preserve Cobra command wiring and help/completion behavior; review generator license output before adopting it."
  ],
  "verification": [
    "In the actual project, record generator versions and commands, then compare its initial files with a fresh output from the same versions and options.",
    "After source exists, run gofmt -l ., go test ./..., go vet ./... and go build ./... from the module root; a bare go.mod is not a runnable application.",
    "In a disposable copy, check candidate staging includes source and required manifests but excludes binaries, caches, local credentials and .DS_Store; inspect git add --dry-run -A before changing a real index.",
    "For Cobra, exercise go run . --help and generated command help, then test actual exit codes, stdout/stderr and noninteractive operation."
  ],
  "sources": [
    {
      "title": "Go module creation tutorial",
      "url": "https://go.dev/doc/tutorial/create-module"
    },
    {
      "title": "Bubble Tea v2 official README and tutorial",
      "url": "https://github.com/charmbracelet/bubbletea"
    },
    {
      "title": "Bubble Tea v2 upgrade guide and module/API changes",
      "url": "https://github.com/charmbracelet/bubbletea/blob/main/UPGRADE_GUIDE_V2.md"
    },
    {
      "title": "Go modules reference: go mod init",
      "url": "https://go.dev/ref/mod#go-mod-init"
    },
    {
      "title": "Cobra generator documentation",
      "url": "https://github.com/spf13/cobra-cli/blob/main/README.md"
    },
    {
      "title": "GoReleaser quick start",
      "url": "https://goreleaser.com/getting-started/quick-start/"
    }
  ],
  "integration_steps": [
    "After the selected module/Cobra baseline, resolve dependencies and record tool versions; preserve the Cobra-generated main.go and cmd/root.go command wiring. Add Bubble Tea v2 (`charm.land/bubbletea/v2`) only when interactive screens are required, and use its v2 Model/View API rather than copying v1 examples.",
    "Implement commands through the chosen command structure with injectable I/O, configuration validation, stable exit codes, cancellation and explicit noninteractive behavior. Keep application logic separate from terminal rendering.",
    "Write command tests covering malformed input, stdin, stdout/stderr, cancellation and safe retries; use isolated temporary paths and test terminal restoration when a TUI is present.",
    "When GoReleaser is selected, follow its configuration generator instructions and review/pin the generated configuration and target matrix. Preserve go.mod/go.sum; document installation, supported targets and rollback. No application setup or publishing has been executed."
  ]
}