docs: add versioning and release process documentation

.github/workflows/ci.yml

@@ -23,7 +23,7 @@ jobs:
           version: "latest"
 
       - name: Set up Python
-        run: uv python install 3.12
+        run: uv python install 3.13
 
       - name: Install dependencies
         run: uv sync --all-extras
@@ -46,7 +46,7 @@ jobs:
           version: "latest"
 
       - name: Set up Python
-        run: uv python install 3.12
+        run: uv python install 3.13
 
       - name: Install dependencies
         run: uv sync --all-extras
@@ -55,12 +55,8 @@ jobs:
         run: uv run mypy src/
 
   test:
-    name: Test (Python ${{ matrix.python-version }})
+    name: Test
     runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
 
@@ -70,7 +66,7 @@ jobs:
           version: "latest"
 
       - name: Set up Python
-        run: uv python install ${{ matrix.python-version }}
+        run: uv python install 3.13
 
       - name: Install dependencies
         run: uv sync --all-extras
@@ -79,25 +75,42 @@ jobs:
         run: uv run pytest tests/ --cov=src --cov-report=xml --cov-report=term-missing
 
       - name: Upload coverage to Codecov
-        if: matrix.python-version == '3.12'
         uses: codecov/codecov-action@v4
         with:
           files: ./coverage.xml
           fail_ci_if_error: false
         env:
           CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
 
+  version-check:
+    name: Version Consistency
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Check version consistency
+        run: uv run python scripts/check_version.py
+
   all-checks:
     name: All Checks Passed
     runs-on: ubuntu-latest
-    needs: [lint, typecheck, test]
+    needs: [lint, typecheck, test, version-check]
     if: always()
     steps:
       - name: Check all jobs passed
         run: |
           if [[ "${{ needs.lint.result }}" != "success" ]] || \
              [[ "${{ needs.typecheck.result }}" != "success" ]] || \
-             [[ "${{ needs.test.result }}" != "success" ]]; then
+             [[ "${{ needs.test.result }}" != "success" ]] || \
+             [[ "${{ needs.version-check.result }}" != "success" ]]; then
             echo "One or more jobs failed"
             exit 1
           fi

.github/workflows/release.yml

@@ -0,0 +1,57 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    name: Semantic Release
+    runs-on: ubuntu-latest
+    # Only run on main branch and skip if commit message contains [skip ci]
+    if: github.ref == 'refs/heads/main' && !contains(github.event.head_commit.message, '[skip ci]')
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+          persist-credentials: true  # Needed for semantic-release to push tags
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Run semantic-release
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          uv run semantic-release version --print
+          uv run semantic-release publish
+
+      - name: Verify version consistency
+        if: success()
+        run: uv run python scripts/check_version.py

CHANGELOG.md

@@ -0,0 +1,38 @@
+# CHANGELOG
+
+All notable changes to this project will be documented in this file.
+
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and follows the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+## [Unreleased]
+
+### Added
+- Version consistency validation CI check to prevent version drift
+- Comprehensive release process documentation in RELEASING.md
+- Python-semantic-release integration for automated versioning
+- CHANGELOG.md for tracking project changes
+
+### Changed
+- Updated CI workflow to include version validation step
+
+## [0.1.0] - 2024-12-22
+
+### Added
+- Core workspace management functionality
+- Git worktree integration for isolated workspaces
+- CLI commands: `workspace create`, `workspace list`, `workspace remove`
+- Agent launching capabilities
+- Template system for project scaffolding
+- Documentation generation from design templates
+- Python virtual environment support per workspace
+- Metadata tracking for workspace configuration
+
+### Infrastructure
+- Structured logging with structlog
+- Type-safe configuration with Pydantic
+- Comprehensive test suite with pytest
+- Code quality tooling (ruff, mypy)
+- CI/CD pipeline with GitHub Actions
+
+[Unreleased]: https://github.com/ckrough/agentspaces/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/ckrough/agentspaces/releases/tag/v0.1.0

CLAUDE.md

@@ -108,15 +108,60 @@ uv run mypy src/                       # Type check
 
 ## Conventions
 
-- Python 3.12+
+- Python 3.13
 - Type hints on all functions
 - Google-style docstrings
 - `ruff` for linting/formatting
 - `mypy --strict` for type checking
 - 80% test coverage target
 
+## Versioning and Releases
+
+### Commit Messages
+
+Use [Conventional Commits](https://www.conventionalcommits.org/) for all commit messages:
+
+```
+<type>(<scope>): <description>
+```
+
+**Common types:**
+- `feat`: New feature (triggers minor version bump)
+- `fix`: Bug fix (triggers patch version bump)
+- `docs`: Documentation only changes
+- `refactor`: Code refactoring without behavior change
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks
+
+**Breaking changes:**
+Add `!` after type to trigger major version bump:
+```
+feat!: change workspace create to require branch argument
+```
+
+### CHANGELOG
+
+- **CHANGELOG.md** is automatically updated by semantic-release on each release
+- Entries are generated from conventional commit messages
+- Unreleased changes are tracked in the `[Unreleased]` section
+- Never manually edit the automated sections
+- For manual releases, update CHANGELOG.md before tagging
+
+### Release Process
+
+Releases are automated via GitHub Actions when commits are pushed to `main`:
+1. Commit with conventional commit message
+2. Push to main (or merge PR)
+3. GitHub Actions analyzes commits and creates release if needed
+4. Version is bumped, CHANGELOG is updated, and tag is created
+
+See [RELEASING.md](RELEASING.md) for full details on versioning and releases.
+
 ## Documentation
 
 - [TODO.md](TODO.md) - Active task list
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Development guide
+- [RELEASING.md](RELEASING.md) - Version management and release process
+- [CHANGELOG.md](CHANGELOG.md) - Project changelog (auto-generated)
 - [docs/design/architecture.md](docs/design/architecture.md) - System design
 - [docs/adr/](docs/adr/) - Architecture decisions

CONTRIBUTING.md

@@ -6,7 +6,7 @@ This guide covers development setup, project architecture, and contribution guid
 
 ### Prerequisites
 
-- Python 3.12+
+- Python 3.13
 - Git
 - [uv](https://docs.astral.sh/uv/) for Python package management
 
@@ -181,7 +181,7 @@ uv run pytest
 
 ### Python Version
 
-Target Python 3.12+. Use modern Python features:
+Target Python 3.13. Use modern Python features:
 
 - Type hints on all function signatures (including `-> None`)
 - `collections.abc` types for abstract containers
@@ -405,6 +405,10 @@ docs: update README with new commands
 test: add coverage for edge cases in naming
 ```
 
+## Releasing
+
+For version management and release procedures, see [RELEASING.md](RELEASING.md).
+
 ## Questions?
 
 Open an issue on GitHub for questions about contributing.

README.md

@@ -14,7 +14,7 @@ Workspace orchestration for AI coding agents. Manage isolated workspaces for par
 
 ### Prerequisites
 
-- Python 3.12+
+- Python 3.13
 - Git
 - [uv](https://docs.astral.sh/uv/) (Python package manager)