feat(cli): standardize version conventions (F110)

.gitignore

@@ -54,6 +54,13 @@ site/node_modules/
 .gemini/
 .codex/
 
+# tower workspace dir: the sled index (db/) is regenerated by the scan and the
+# extension binaries (extensions/) are built/deployed from the `extensions/` crates —
+# both are machine-specific and stay out of git. The hand-authored project config is
+# shared, so it is the one tracked file.
+.tower/*
+!.tower/config.toml
+
 # Built plugin binaries (compiled artifacts of examples/plugins/*)
 examples/plugins/*/awf-plugin-*
 !examples/plugins/*/awf-plugin-*.go

README.md

@@ -128,7 +128,7 @@ AWF is a powerful orchestration tool that grants AI agents and workflows direct
 | `awf status <id>` | Check workflow status |
 | `awf config show` | Display project configuration |
 | `awf plugin list` | List installed plugins |
-| `awf plugin install <owner/repo>` | Install a plugin from GitHub Releases |
+| `awf plugin install <owner/repo[@version]>` | Install a plugin from GitHub Releases |
 | `awf plugin update [name]` | Update an installed plugin |
 | `awf plugin verify [name]` | Verify plugin binary integrity (check/update SHA-256 checksums) |
 | `awf plugin remove <name>` | Remove an installed plugin |
@@ -137,18 +137,20 @@ AWF is a powerful orchestration tool that grants AI agents and workflows direct
 | `awf plugin disable <name>` | Disable a plugin |
 | `awf workflow list` | List installed workflow packs |
 | `awf workflow info <name>` | Display detailed pack information |
-| `awf workflow install <owner/repo>` | Install a workflow pack from GitHub Releases |
+| `awf workflow install <owner/repo[@version]>` | Install a workflow pack from GitHub Releases |
 | `awf workflow update [name]` | Update an installed workflow pack |
 | `awf workflow remove <pack>` | Remove an installed workflow pack |
 | `awf workflow search [query]` | Search for workflow packs on GitHub |
 | `awf serve` | Start HTTP API server for remote workflow execution and monitoring |
 | `awf tui` | Launch the interactive terminal UI |
-| `awf upgrade` | Upgrade AWF to the latest version |
-| `awf version` | Show version information |
+| `awf upgrade [version]` | Upgrade AWF to the latest version or an exact SemVer release |
+| `awf --version` | Show binary version information |
 | `awf completion <shell>` | Generate shell autocompletion |
 
 See [Command Reference](docs/user-guide/commands.md) for all options.
 
+**BREAKING:** Use `--verbose` instead of `-v`. Version selection now follows standard CLI conventions: `awf --version`, `awf upgrade [version]`, `awf plugin install owner/repo[@version]`, and `awf workflow install owner/repo[@version]`.
+
 ## Example Workflow
 
 ```yaml

docs/getting-started/installation.md

@@ -35,7 +35,7 @@ curl -fsSL https://raw.githubusercontent.com/awf-project/cli/main/scripts/instal
 To install a specific version:
 
 ```bash
-AWF_VERSION=v1.0.0 curl -fsSL https://raw.githubusercontent.com/awf-project/cli/main/scripts/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/awf-project/cli/main/scripts/install.sh | AWF_VERSION=v1.0.0 sh
 ```
 
 The script detects your OS and architecture, downloads the appropriate binary, verifies its SHA256 checksum, and installs it to `/usr/local/bin`.
@@ -71,12 +71,14 @@ The binary will be available at `./bin/awf` after building.
 ## Verify Installation
 
 ```bash
-awf version
+awf --version
 ```
 
 Expected output:
 ```
 awf version X.Y.Z
+commit: <commit>
+built: <build-date>
 ```
 
 ## Shell Completion

docs/getting-started/quickstart.md

@@ -159,7 +159,7 @@ This will store state files in `/custom/path/states/` and history in `/custom/pa
 |------|-------------|
 | `--input, -i` | Pass input values (key=value) |
 | `--output, -o` | Output mode: silent, streaming, buffered |
-| `--verbose, -v` | Enable verbose output |
+| `--verbose` | Enable verbose output |
 | `--quiet, -q` | Suppress non-error output |
 | `--dry-run` | Show execution plan without running |
 | `--interactive` | Step-by-step execution with prompts |

docs/user-guide/commands.md

@@ -20,7 +20,7 @@ title: "CLI Commands"
 | `awf error [code]` | Look up error code documentation |
 | `awf history` | Show workflow execution history |
 | `awf plugin list` | List installed plugins |
-| `awf plugin install <owner/repo>` | Install a plugin from GitHub releases |
+| `awf plugin install <owner/repo[@version]>` | Install a plugin from GitHub releases |
 | `awf plugin update [name]` | Update an installed plugin |
 | `awf plugin verify [name]` | Verify plugin binary integrity (check/update SHA-256 checksums) |
 | `awf plugin remove <name>` | Remove an installed plugin |
@@ -29,16 +29,15 @@ title: "CLI Commands"
 | `awf plugin disable <name>` | Disable a plugin |
 | `awf workflow list` | List installed workflow packs |
 | `awf workflow info <name>` | Display detailed pack information |
-| `awf workflow install <owner/repo>` | Install a workflow pack from GitHub Releases |
+| `awf workflow install <owner/repo[@version]>` | Install a workflow pack from GitHub Releases |
 | `awf workflow update [name]` | Update an installed workflow pack |
 | `awf workflow remove <name>` | Remove an installed workflow pack |
 | `awf workflow search [query]` | Search for workflow packs on GitHub |
 | `awf config show` | Display project configuration |
 | `awf serve` | Start HTTP API server for remote execution and monitoring |
-| `awf upgrade` | Upgrade AWF to the latest version |
+| `awf upgrade [version]` | Upgrade AWF to the latest version or an exact SemVer release |
 | `awf upgrade --check` | Check for available updates without installing |
-| `awf upgrade --version <tag>` | Install a specific version |
-| `awf version` | Show version info |
+| `awf --version` | Show binary version info |
 | `awf completion <shell>` | Generate shell autocompletion |
 
 ## Global Flags
@@ -47,7 +46,7 @@ These flags work with all commands:
 
 | Flag | Description |
 |------|-------------|
-| `--verbose, -v` | Enable verbose output (displays tool-use markers during agent execution) |
+| `--verbose` | Enable verbose output (displays tool-use markers during agent execution) |
 | `--quiet, -q` | Suppress non-error output |
 | `--no-color` | Disable colored output |
 | `--no-hints` | Disable error hint suggestions |
@@ -171,7 +170,7 @@ awf run <workflow> [flags]
 | `streaming` | Real-time output with [OUT]/[ERR] prefixes; for agent steps, displays human-readable text (or raw NDJSON if `output_format: json`) |
 | `buffered` | Show output after each step completes; for agent steps, displays filtered text in post-execution summary (or raw NDJSON if `output_format: json`) |
 
-**Note:** For agent steps, the `output_format` field controls display filtering: `text` or omitted (default) shows human-readable output; `json` shows raw NDJSON. See [Output Formatting](agent-steps.md#streaming-output-display) for details.
+**Note:** For agent steps, the `output_format` field controls display filtering: `text` or omitted (default) shows human-readable output; `json` shows raw NDJSON. See [Output Formatting](agent-steps.md#output-formatting) for details.
 
 ### Execution Summary
 
@@ -810,7 +809,7 @@ awf validate <workflow> [flags]
 awf validate deploy
 
 # Validate with verbose output
-awf validate deploy -v
+awf validate deploy --verbose
 
 # Skip plugin validators
 awf validate deploy --skip-plugins
@@ -1096,27 +1095,28 @@ awf plugin list --details
 Install a plugin from a GitHub repository.
 
 ```bash
-awf plugin install <owner/repo> [flags]
+awf plugin install <owner/repo[@version]> [flags]
 ```
 
 ### Arguments
 
 | Argument | Description |
 |----------|-------------|
-| `owner/repo` | GitHub repository in `owner/repo` format (not a URL) |
+| `owner/repo[@version]` | GitHub repository in `owner/repo` format with optional exact SemVer version suffix |
 
 ### Flags
 
 | Flag | Description |
 |------|-------------|
-| `--version` | Version constraint (e.g. `">=1.0.0 <2.0.0"`) |
 | `--pre-release` | Include pre-release versions (alpha, beta, rc) |
 | `--force` | Overwrite existing installation |
 
 ### Description
 
 Downloads the latest compatible release from the GitHub repository, verifies the SHA-256 checksum, extracts the `.tar.gz` archive, validates the plugin manifest, and installs atomically. The plugin is enabled automatically after installation.
 
+Explicit versions use `owner/repo@version` syntax and must be exact SemVer values. Both `1.2.3` and `v1.2.3` are accepted; ranges such as `>=1.0.0` are rejected.
+
 Release assets must follow the naming convention: `awf-plugin-<name>_<os>_<arch>.tar.gz` with a corresponding `checksums.txt` file.
 
 ### Examples
@@ -1125,8 +1125,8 @@ Release assets must follow the naming convention: `awf-plugin-<name>_<os>_<arch>
 # Install a plugin
 awf plugin install myorg/awf-plugin-jira
 
-# Install with version constraint
-awf plugin install myorg/awf-plugin-jira --version ">=1.0.0 <2.0.0"
+# Install an exact version
+awf plugin install myorg/awf-plugin-jira@v1.2.3
 
 # Include pre-release versions
 awf plugin install myorg/awf-plugin-jira --pre-release
@@ -1573,27 +1573,28 @@ No installed workflow packs to update.
 Install a workflow pack from a GitHub repository.
 
 ```bash
-awf workflow install <owner/repo> [flags]
+awf workflow install <owner/repo[@version]> [flags]
 ```
 
 ### Arguments
 
 | Argument | Description |
 |----------|-------------|
-| `owner/repo` | GitHub repository in `owner/repo` format (not a URL) |
+| `owner/repo[@version]` | GitHub repository in `owner/repo` format with optional exact SemVer version suffix |
 
 ### Flags
 
 | Flag | Description |
 |------|-------------|
-| `--version` | Version constraint (e.g., `">=1.0.0 <2.0.0"` or `"1.2.0"` for exact version) |
 | `--global` | Install to global user-level directory (`~/.local/share/awf/workflow-packs/`) instead of local project |
 | `--force` | Overwrite existing installation |
 
 ### Description
 
 Downloads the latest compatible release from the GitHub repository, verifies the SHA-256 checksum, extracts the `.tar.gz` archive, validates the `manifest.yaml`, checks AWF version compatibility, and installs atomically. The pack directory structure is created with source metadata.
 
+Explicit versions use `owner/repo@version` syntax and must be exact SemVer values. Both `1.2.3` and `v1.2.3` are accepted; ranges such as `>=1.0.0` are rejected.
+
 Release assets must include a single `.tar.gz` archive (e.g., `awf-workflow-<name>_<version>.tar.gz`) with a corresponding `checksums.txt` file. Workflow packs are platform-independent — no OS/architecture suffix is needed.
 
 **Pack manifest validation:**
@@ -1615,11 +1616,8 @@ If the manifest declares required plugins via the `plugins:` field, warnings are
 # Install a workflow pack (latest version)
 awf workflow install myorg/awf-workflow-speckit
 
-# Install with specific version
-awf workflow install myorg/awf-workflow-speckit --version "1.2.0"
-
-# Install with version constraint
-awf workflow install myorg/awf-workflow-speckit --version ">=1.0.0 <2.0.0"
+# Install an exact version
+awf workflow install myorg/awf-workflow-speckit@v1.2.0
 
 # Install globally (available to all projects)
 awf workflow install myorg/awf-workflow-speckit --global
@@ -1794,12 +1792,12 @@ Project Configuration (.awf/config.yaml)
 
 ---
 
-## awf version
+## awf --version
 
-Show version information.
+Show binary version information.
 
 ```bash
-awf version
+awf --version
 ```
 
 ---

docs/user-guide/plugins.md

@@ -330,16 +330,17 @@ The `SOURCE` column shows the GitHub `owner/repo` for plugins installed via `awf
 Install an external plugin from GitHub Releases:
 
 ```bash
-awf plugin install owner/repo
+awf plugin install owner/repo[@version]
 ```
 
 AWF downloads the latest release, verifies the SHA-256 checksum, extracts the archive, validates the manifest, and installs atomically.
 
+Explicit versions use `owner/repo@version` syntax and must be exact SemVer values. Both `1.2.3` and `v1.2.3` are accepted; ranges such as `>=1.0.0` are rejected.
+
 **Flags:**
 
 | Flag | Description |
 |------|-------------|
-| `--version` | Version constraint (e.g. `">=1.0.0 <2.0.0"`) |
 | `--pre-release` | Include alpha/beta/rc versions in resolution |
 | `--force` | Overwrite an existing installation |
 
@@ -349,8 +350,8 @@ AWF downloads the latest release, verifies the SHA-256 checksum, extracts the ar
 # Install latest stable release
 awf plugin install myorg/awf-plugin-jira
 
-# Install with version constraint
-awf plugin install myorg/awf-plugin-jira --version ">=1.0.0 <2.0.0"
+# Install an exact version
+awf plugin install myorg/awf-plugin-jira@v1.2.3
 
 # Include pre-release versions
 awf plugin install myorg/awf-plugin-jira --pre-release
@@ -359,7 +360,7 @@ awf plugin install myorg/awf-plugin-jira --pre-release
 awf plugin install myorg/awf-plugin-jira --force
 ```
 
-The `owner/repo` argument must be a GitHub repository path (not a URL). The repository must contain GitHub Releases with `.tar.gz` assets matching the AWF naming convention (see [Release Asset Naming](#release-asset-naming)).
+The `owner/repo[@version]` argument must be a GitHub repository path (not a URL). The repository must contain GitHub Releases with `.tar.gz` assets matching the AWF naming convention (see [Release Asset Naming](#release-asset-naming)).
 
 #### Update a Plugin
 

docs/user-guide/tracing.md

@@ -434,7 +434,7 @@ workflow.run [data-pipeline]
 2. **Check endpoint configuration:**
    ```bash
    export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
-   awf run my-workflow --otel-exporter=otlp -v
+   awf run my-workflow --otel-exporter=otlp --verbose
    ```
 
 3. **Verify service name:**

docs/user-guide/upgrade.md

@@ -23,10 +23,10 @@ Downloads the latest stable release, verifies its SHA256 checksum, and replaces
 ## Install a Specific Version
 
 ```bash
-awf upgrade --version v0.5.0
+awf upgrade v0.5.0
 ```
 
-Installs the specified version, allowing both upgrades and downgrades.
+Installs the specified exact SemVer release, allowing both upgrades and downgrades. Both `0.5.0` and `v0.5.0` are accepted; ranges such as `>=0.5.0` are rejected.
 
 ## Force Upgrade
 
@@ -35,7 +35,7 @@ awf upgrade --force
 ```
 
 Skips version comparison and package manager detection. Required when:
-- Running a development build (`awf version` shows "dev")
+- Running a development build (`awf --version` shows "dev")
 - Binary is installed via a package manager (homebrew, snap, nix)
 - You want to reinstall the same version
 
@@ -56,7 +56,6 @@ AWF also tries `gh auth token` automatically if the GitHub CLI is installed.
 |------|-------------|
 | `--check` | Check for updates without installing |
 | `--force` | Force upgrade (skip version/package manager checks) |
-| `--version` | Install a specific version (e.g., `v0.5.0`) |
 
 ## Troubleshooting
 

docs/user-guide/workflow-packs.md

@@ -59,10 +59,7 @@ Install packs from GitHub Releases:
 awf workflow install myorg/awf-workflow-speckit
 
 # Install specific version
-awf workflow install myorg/awf-workflow-speckit@1.2.0
-
-# Install with version constraint
-awf workflow install myorg/awf-workflow-speckit --version ">=1.0.0 <2.0.0"
+awf workflow install myorg/awf-workflow-speckit@v1.2.0
 
 # Install globally (available to all projects)
 awf workflow install myorg/awf-workflow-speckit --global
@@ -73,6 +70,8 @@ awf workflow install myorg/awf-workflow-speckit --force
 
 AWF downloads the release archive, verifies the SHA-256 checksum, validates the manifest (including AWF version compatibility), and installs atomically.
 
+Explicit versions use `owner/repo@version` syntax and must be exact SemVer values. Both `1.2.0` and `v1.2.0` are accepted; ranges such as `>=1.0.0` are rejected.
+
 ### Installation Locations
 
 | Scope | Directory | Flag |

internal/interfaces/cli/doc.go

@@ -26,7 +26,7 @@
 //   - App: Dependency injection container with Config and Formatter
 //   - NewApp: Creates application with loaded configuration
 //   - NewRootCommand: Builds cobra command tree with global flags
-//   - newVersionCommand: Displays AWF version, commit, and build date
+//   - --version: Displays AWF version, commit, and build date
 //
 // Global flags:
 //   - --no-color: Disable colorized output