chore: decouple version source path for #320 phase A

.agents/skills/update-changelog/SKILL.md

@@ -27,15 +27,15 @@ Update the current version changelog entry without changing the version.
 - Permissions to push branch changes.
 
 ## Inputs
-- Current version from `bsctl/static/resources/constants.yaml`.
+- Current version from `resources/version.yaml` (fallback to `bsctl/static/resources/constants.yaml` during transition).
 - Summary of new work to capture (staged/unstaged changes and recent commits).
 
 ## Required context
-- Current version in `bsctl/static/resources/constants.yaml`.
+- Current version in `resources/version.yaml` (fallback to `bsctl/static/resources/constants.yaml` during transition).
 - Whether `main` already contains that version entry (use `git show origin/main:CHANGELOG.md` or GitHub UI/API).
 
 ## Steps
-1. Read the current version from `bsctl/static/resources/constants.yaml`.
+1. Read the current version from `resources/version.yaml` (fallback to `bsctl/static/resources/constants.yaml` during transition).
 2. Find the entry for that version in branch `CHANGELOG.md`.
 3. If the version exists in branch changelog (including when it is not yet merged to `main`), update that same entry in place.
 4. If branch entry is missing but `main` already has that version entry, cherry-pick/recreate that entry at the top and then update it.

.agents/skills/version-bump/SKILL.md

@@ -25,15 +25,15 @@ Keep the BasicSetup CLI version and changelog in sync for releases.
 
 ## Required context
 - Decide bump type (major/minor/patch) per semantic versioning and repo guidelines.
-- Current version lives at `bsctl/static/resources/constants.yaml` under `.BasicSetupCliVersion`.
+- Current version lives at `resources/version.yaml` under `.BasicSetupCliVersion` (mirror `bsctl/static/resources/constants.yaml` during transition).
 
 ## Steps
-1. Set the new version: `yq -i '.BasicSetupCliVersion = "X.Y.Z"' bsctl/static/resources/constants.yaml`.
+1. Set the new version: `yq -i '.BasicSetupCliVersion = "X.Y.Z"' resources/version.yaml` and mirror `bsctl/static/resources/constants.yaml` while legacy paths still exist.
 2. Create a new top `CHANGELOG.md` entry for `X.Y.Z` with today’s date (`YYYY-MM-DD`) and Keep a Changelog section headers (`### Added`, `### Changed`, `### Fixed`).
 3. Immediately run [Update Changelog Skill](../update-changelog/SKILL.md) to populate/refine and consolidate the entry from staged/working-tree changes and recent commits.
 4. Verify alignment: top changelog version matches `.BasicSetupCliVersion`; date is valid for CI validation (UTC +/- 1 day).
 5. Validate changes: at minimum `git diff`; run `make test` if code changed.
 
 ## Outputs
-- Updated `bsctl/static/resources/constants.yaml` with the new version.
+- Updated `resources/version.yaml` with the new version (and mirrored `bsctl/static/resources/constants.yaml` during transition).
 - Matching `CHANGELOG.md` entry for `X.Y.Z`.

.agents/skills/wip-pr-setup/SKILL.md

@@ -29,7 +29,7 @@ Standardize the setup flow for starting implementation work with branch manageme
 - Whether to create a minimal bootstrap commit (for example, whitespace-only `CHANGELOG.md`) when PR creation is blocked by zero diff.
 
 ## Required context
-- Repository docs/version bump requirements (`bsctl/static/resources/constants.yaml`, `CHANGELOG.md`).
+- Repository docs/version bump requirements (`resources/version.yaml` and legacy `bsctl/static/resources/constants.yaml` during transition, plus `CHANGELOG.md`).
 - Label conventions and sync rules from `sync-labels` skill.
 - Whether GitHub can create a PR for the branch yet (must have commits ahead of base).
 

.github/workflows/dependabot-autobump.yaml

@@ -9,7 +9,7 @@ name: Dependabot Auto-Bump
 #
 # HOW IT WORKS:
 # 1. Triggers only on Dependabot PRs when they are first opened
-# 2. Bumps the patch version in bsctl/static/resources/constants.yaml
+# 2. Bumps the patch version in resources/version.yaml (and mirrors legacy constants file during transition)
 # 3. Adds a new entry to CHANGELOG.md with the dependency update details
 # 4. Commits these changes back to the Dependabot PR branch
 
@@ -76,6 +76,6 @@ jobs:
         run: |
           git config --local user.email "github-actions[bot]@users.noreply.github.com"
           git config --local user.name "github-actions[bot]"
-          git add bsctl/static/resources/constants.yaml CHANGELOG.md
+          git add resources/version.yaml bsctl/static/resources/constants.yaml CHANGELOG.md
           git commit -m "chore: auto-bump version and update CHANGELOG for Dependabot PR"
           git push

.github/workflows/release.yml

@@ -6,6 +6,7 @@ on:
       - main
     paths:
       - CHANGELOG.md
+      - resources/version.yaml
       - bsctl/static/resources/constants.yaml
   workflow_dispatch:
     inputs:
@@ -70,11 +71,19 @@ jobs:
 
           version="$DISPATCH_VERSION"
           if [ -z "$version" ]; then
-            version="$(yq '.BasicSetupCliVersion' bsctl/static/resources/constants.yaml | tr -d '"')"
+            if [ -f resources/version.yaml ]; then
+              version="$(yq '.BasicSetupCliVersion' resources/version.yaml | tr -d '"')"
+            fi
+          fi
+
+          if [ -z "$version" ] || [ "$version" = "null" ]; then
+            if [ -f bsctl/static/resources/constants.yaml ]; then
+              version="$(yq '.BasicSetupCliVersion' bsctl/static/resources/constants.yaml | tr -d '"')"
+            fi
           fi
 
           if [ -z "$version" ] || [ "$version" = "null" ]; then
-            echo "Failed to determine candidate version from dispatch input or bsctl/static/resources/constants.yaml" >&2
+            echo "Failed to determine candidate version from dispatch input, resources/version.yaml, or bsctl/static/resources/constants.yaml" >&2
             exit 1
           fi
 

AGENTS.md

@@ -376,7 +376,7 @@ Follow [Semantic Versioning 2.0.0](https://semver.org/):
    - Dependency updates (Dependabot) → PATCH bump
 
 2. **Update Files**
-   - Update version in `bsctl/static/resources/constants.yaml`
+   - Update version in `resources/version.yaml` (and mirror `bsctl/static/resources/constants.yaml` during transition)
    - Add CHANGELOG entry with date and changes
    - Follow the CHANGELOG format
 

CHANGELOG.md

@@ -3,6 +3,18 @@
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 
+---
+## [0.1.21] - 2026-04-09
+
+### Added
+
+- Added `resources/version.yaml` as the primary version source for release and docs-bump automation during #320 Phase A.
+
+### Changed
+
+- Updated release/docs-bump/dependabot workflows and helper scripts to read `resources/version.yaml` first with `bsctl/static/resources/constants.yaml` fallback during the transition.
+- Updated version-related agent guidance and planning docs to treat `resources/version.yaml` as the source of truth while legacy mirroring remains in place.
+
 ---
 ## [0.1.20] - 2026-04-09
 

bsctl/scripts/workflows/dependabot-autobump_bump-version.sh

@@ -1,47 +1,52 @@
 #! /usr/bin/env bash
 
-# This script bumps the patch version in constants.yaml for Dependabot PRs
+# This script bumps the patch version in the version source for Dependabot PRs
 
 set -eo pipefail
 
-CONSTANTS_FILE="./bsctl/static/resources/constants.yaml"
+VERSION_FILE="./resources/version.yaml"
+LEGACY_CONSTANTS_FILE="./bsctl/static/resources/constants.yaml"
 
-if [ ! -f "$CONSTANTS_FILE" ]; then
-    echo "Error: Constants file not found at $CONSTANTS_FILE"
-    exit 1
+if [ ! -f "$VERSION_FILE" ] && [ ! -f "$LEGACY_CONSTANTS_FILE" ]; then
+	echo "Error: Version files not found at $VERSION_FILE or $LEGACY_CONSTANTS_FILE"
+	exit 1
 fi
 
 # Get the current version
-current_version=$(yq .BasicSetupCliVersion "$CONSTANTS_FILE")
+if [ -f "$VERSION_FILE" ]; then
+	current_version=$(yq .BasicSetupCliVersion "$VERSION_FILE")
+else
+	current_version=$(yq .BasicSetupCliVersion "$LEGACY_CONSTANTS_FILE")
+fi
 
 if [ -z "$current_version" ]; then
-    echo "Error: Failed to get current version from $CONSTANTS_FILE"
-    exit 1
+	echo "Error: Failed to get current version from $VERSION_FILE or $LEGACY_CONSTANTS_FILE"
+	exit 1
 fi
 
 # Trim any leading/trailing whitespace
 sanitized_version=$(echo "$current_version" | xargs)
 
 # Validate that the version is in the expected SemVer format: MAJOR.MINOR.PATCH (numeric)
 if ! [[ "$sanitized_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
-    echo "Error: Version '$current_version' from $CONSTANTS_FILE is not in MAJOR.MINOR.PATCH format"
-    exit 1
+	echo "Error: Version '$current_version' is not in MAJOR.MINOR.PATCH format"
+	exit 1
 fi
 
 echo "Current version: $sanitized_version"
 
 # Parse version components
-IFS='.' read -r major minor patch <<< "$sanitized_version"
+IFS='.' read -r major minor patch <<<"$sanitized_version"
 
 # Validate version components are numeric
 if [ -z "$major" ] || [ -z "$minor" ] || [ -z "$patch" ]; then
-    echo "Error: Invalid version format '$sanitized_version' (expected MAJOR.MINOR.PATCH)"
-    exit 1
+	echo "Error: Invalid version format '$sanitized_version' (expected MAJOR.MINOR.PATCH)"
+	exit 1
 fi
 
 if ! [[ "$major" =~ ^[0-9]+$ ]] || ! [[ "$minor" =~ ^[0-9]+$ ]] || ! [[ "$patch" =~ ^[0-9]+$ ]]; then
-    echo "Error: Version components must be numeric, got '$sanitized_version'"
-    exit 1
+	echo "Error: Version components must be numeric, got '$sanitized_version'"
+	exit 1
 fi
 
 # Bump patch version
@@ -51,6 +56,15 @@ new_version="${major}.${minor}.${new_patch}"
 echo "New version: $new_version"
 
 # Update the version in the file
-yq -i ".BasicSetupCliVersion = \"$new_version\"" "$CONSTANTS_FILE"
+if [ -f "$VERSION_FILE" ]; then
+	yq -i ".BasicSetupCliVersion = \"$new_version\"" "$VERSION_FILE"
+else
+	mkdir -p "$(dirname "$VERSION_FILE")"
+	printf 'BasicSetupCliVersion: "%s"\n' "$new_version" >"$VERSION_FILE"
+fi
+
+if [ -f "$LEGACY_CONSTANTS_FILE" ]; then
+	yq -i ".BasicSetupCliVersion = \"$new_version\"" "$LEGACY_CONSTANTS_FILE"
+fi
 
 echo "Version updated successfully to $new_version"

bsctl/scripts/workflows/dependabot-autobump_update-changelog.sh

@@ -5,24 +5,29 @@
 set -eo pipefail
 
 CHANGELOG_FILE="./CHANGELOG.md"
-CONSTANTS_FILE="./bsctl/static/resources/constants.yaml"
+VERSION_FILE="./resources/version.yaml"
+LEGACY_CONSTANTS_FILE="./bsctl/static/resources/constants.yaml"
 
 if [ ! -f "$CHANGELOG_FILE" ]; then
-    echo "Error: CHANGELOG file not found at $CHANGELOG_FILE"
-    exit 1
+	echo "Error: CHANGELOG file not found at $CHANGELOG_FILE"
+	exit 1
 fi
 
-if [ ! -f "$CONSTANTS_FILE" ]; then
-    echo "Error: Constants file not found at $CONSTANTS_FILE"
-    exit 1
+if [ ! -f "$VERSION_FILE" ] && [ ! -f "$LEGACY_CONSTANTS_FILE" ]; then
+	echo "Error: Version files not found at $VERSION_FILE or $LEGACY_CONSTANTS_FILE"
+	exit 1
 fi
 
-# Get the new version from constants.yaml
-new_version=$(yq .BasicSetupCliVersion "$CONSTANTS_FILE")
+# Get the new version from version source
+if [ -f "$VERSION_FILE" ]; then
+	new_version=$(yq .BasicSetupCliVersion "$VERSION_FILE")
+else
+	new_version=$(yq .BasicSetupCliVersion "$LEGACY_CONSTANTS_FILE")
+fi
 
-if [ -z "$new_version" ]; then
-    echo "Error: Failed to get version from $CONSTANTS_FILE"
-    exit 1
+if [ -z "$new_version" ] || [ "$new_version" = "null" ]; then
+	echo "Error: Failed to get version from $VERSION_FILE or $LEGACY_CONSTANTS_FILE"
+	exit 1
 fi
 
 # Get current date in YYYY-MM-DD format
@@ -33,34 +38,34 @@ pr_title="${PR_TITLE:-Dependency updates}"
 
 # Extract dependency information from PR title if it's a Dependabot PR
 if [[ "$pr_title" =~ [Bb]ump[[:space:]]+([^[:space:]]+)[[:space:]]+from[[:space:]]+([^[:space:]]+)[[:space:]]+to[[:space:]]+([^[:space:]]+) ]]; then
-    # Pattern: "Bump <dependency> from <old_version> to <new_version> ..."
-    dep_name="${BASH_REMATCH[1]}"
-    old_version="${BASH_REMATCH[2]}"
-    new_dep_version="${BASH_REMATCH[3]}"
-    changelog_entry="Bump ${dep_name} from ${old_version} to ${new_dep_version}"
+	# Pattern: "Bump <dependency> from <old_version> to <new_version> ..."
+	dep_name="${BASH_REMATCH[1]}"
+	old_version="${BASH_REMATCH[2]}"
+	new_dep_version="${BASH_REMATCH[3]}"
+	changelog_entry="Bump ${dep_name} from ${old_version} to ${new_dep_version}"
 elif [[ "$pr_title" =~ [Uu]pdate[[:space:]]+([^[:space:]]+)[[:space:]]+to[[:space:]]+([^[:space:]]+) ]]; then
-    # Pattern: "Update <dependency> to <new_version> ..."
-    dep_name="${BASH_REMATCH[1]}"
-    new_dep_version="${BASH_REMATCH[2]}"
-    changelog_entry="Update ${dep_name} to ${new_dep_version}"
+	# Pattern: "Update <dependency> to <new_version> ..."
+	dep_name="${BASH_REMATCH[1]}"
+	new_dep_version="${BASH_REMATCH[2]}"
+	changelog_entry="Update ${dep_name} to ${new_dep_version}"
 elif [[ "$pr_title" =~ ^(chore\(deps\)|build\(deps\)|chore:|build:).*[Bb]ump ]]; then
-    # Fallback for other "bump" titles with proper prefix matching
-    cleaned_title="$pr_title"
-    # Remove leading "<scope>: " if present (e.g., "chore(deps): ")
-    if [[ "$cleaned_title" == *": "* ]]; then
-        cleaned_title="${cleaned_title#*: }"
-    fi
-    # Remove leading "deps: " if present
-    if [[ "$cleaned_title" == deps:\ * ]]; then
-        cleaned_title="${cleaned_title#deps: }"
-    fi
-    # Remove directory suffix starting with " in " (e.g., " in /backend")
-    if [[ "$cleaned_title" == *" in "* ]]; then
-        cleaned_title="${cleaned_title%% in *}"
-    fi
-    changelog_entry="$cleaned_title"
+	# Fallback for other "bump" titles with proper prefix matching
+	cleaned_title="$pr_title"
+	# Remove leading "<scope>: " if present (e.g., "chore(deps): ")
+	if [[ "$cleaned_title" == *": "* ]]; then
+		cleaned_title="${cleaned_title#*: }"
+	fi
+	# Remove leading "deps: " if present
+	if [[ "$cleaned_title" == deps:\ * ]]; then
+		cleaned_title="${cleaned_title#deps: }"
+	fi
+	# Remove directory suffix starting with " in " (e.g., " in /backend")
+	if [[ "$cleaned_title" == *" in "* ]]; then
+		cleaned_title="${cleaned_title%% in *}"
+	fi
+	changelog_entry="$cleaned_title"
 else
-    changelog_entry="Updated dependencies"
+	changelog_entry="Updated dependencies"
 fi
 
 echo "Adding CHANGELOG entry for version $new_version"
@@ -77,21 +82,21 @@ new_entry="## [$new_version] - $current_date
 separator_line=$(grep -n "^---$" "$CHANGELOG_FILE" | head -1 | cut -d: -f1)
 
 if [ -z "$separator_line" ]; then
-    echo "Error: Could not find separator '---' in CHANGELOG"
-    exit 1
+	echo "Error: Could not find separator '---' in CHANGELOG"
+	exit 1
 fi
 
 # Insert the new entry after the separator line
 temp_file=$(mktemp)
-trap 'rm -f "$temp_file"' EXIT ERR  # Clean up temp file on exit or error
-head -n "$separator_line" "$CHANGELOG_FILE" > "$temp_file"
-echo "$new_entry" >> "$temp_file"
-tail -n +$((separator_line + 1)) "$CHANGELOG_FILE" >> "$temp_file"
+trap 'rm -f "$temp_file"' EXIT ERR # Clean up temp file on exit or error
+head -n "$separator_line" "$CHANGELOG_FILE" >"$temp_file"
+echo "$new_entry" >>"$temp_file"
+tail -n +$((separator_line + 1)) "$CHANGELOG_FILE" >>"$temp_file"
 
 # Atomic move to avoid corruption
 if mv "$temp_file" "$CHANGELOG_FILE"; then
-    echo "CHANGELOG updated successfully"
+	echo "CHANGELOG updated successfully"
 else
-    echo "Error: Failed to update CHANGELOG"
-    exit 1
+	echo "Error: Failed to update CHANGELOG"
+	exit 1
 fi

bsctl/scripts/workflows/docs-bump_docs-bump_CHANGELOG-bump.sh

@@ -8,7 +8,14 @@ fi
 
 branchLatestLog=$(cat CHANGELOG.md | sed -n '/---/,$p' | sed '/---/d' | grep -m1 "$line_regex")
 mainLatestLog=$(curl -L https://raw.githubusercontent.com/mrlunchbox777/basic-setup/main/CHANGELOG.md 2>/dev/null | sed -n '/---/,$p' | sed '/---/d' | grep -m1 "$line_regex")
-constantVersion=$(yq .BasicSetupCliVersion ./bsctl/static/resources/constants.yaml)
+versionFile="./resources/version.yaml"
+legacyVersionFile="./bsctl/static/resources/constants.yaml"
+
+if [ -f "$versionFile" ]; then
+	constantVersion=$(yq .BasicSetupCliVersion "$versionFile" | tr -d '"')
+else
+	constantVersion=$(yq .BasicSetupCliVersion "$legacyVersionFile" | tr -d '"')
+fi
 
 if [ -z "$mainLatestLog" ]; then
 	echo "Failed to get latest log from github"