Semantic Version Manager - Agent Guidelines

Quick Start Commands

Local pipeline:
```
task pipeline:local
```
- Runs format, lint, build, test, coverage, and docs
Show version:
```
task version:show:full
```
- Displays current version
Bump version:
```
task version:bump:patch
```
(or
```
minor
```
/
```
major
```
)
Release:
```
task release:patch
```
(or
```
minor
```
/
```
major
```
) - Full release pipeline
Build binary:
```
task build:release
```
- Creates universal binary (arm64 + x86_64)

Build/Test Commands

Build debug:
```
swift build
```
or
```
task build:debug
```
Build release:
```
task build:release
```
- Creates optimized universal binary
Test all:
```
swift test --parallel
```
or
```
task test
```

Test single:

swift test --filter <TestName>

(e.g.,

swift test --filter SemanticVersionTests

)

Format:

task format

swift package plugin --allow-writing-to-package-directory format-source-code

Lint:

task lint

swift package plugin lint-source-code

Coverage:
```
task test:coverage
```
(requires 85% threshold)
Documentation:
```
task document
```
- Generates DocC documentation in
```
./docs
```

Version Management

Version file:
```
version.json
```
- Contains semantic version components
Version bumping: Use
```
task version:bump:[patch|minor|major]
```
(auto-commits)
Pre-release:
```
task version:set:prerelease -- alpha.1
```
Build metadata:
```
task version:set:build -- 20250514.3
```
Git tags: Created automatically during release (
```
task release:*
```
)

Release Process

Prepare release:
```
task release:dry-run
```
- Test without pushing
Create release:
```
task release:[patch|minor|major]
```
- Full automated release
- Bumps version and commits
- Builds universal binary
- Generates Homebrew formula with SHA256
- Creates GitLab package and release
- Tags and pushes to main
Rollback:
```
task release:rollback
```
- Reverts last release if needed

GitLab CI/CD Pipeline

The

.gitlab-ci.yml

defines automated workflows:

Stages

build: Compiles project and runs initial checks
test: Runs test suite with coverage
package: Creates release artifacts (manual trigger)
release: Publishes to GitLab registry (manual trigger)

Pipeline Jobs

build-job: Format, lint, and build debug version
test-job: Run tests with 85% coverage requirement
package-job: Build universal binary and generate Homebrew formula
release-job: Upload to GitLab package registry

Artifacts

Test coverage reports (Cobertura format)
Universal binary:
```
.build/release/semantic-version-manager
```
Homebrew formula:
```
Formula/semantic-version-manager.rb
```

Code Style

Swift version: 6.1, macOS 14+ minimum
Formatting: 2-space indentation, 100 char line length, 1 blank line max (via .swift-format.json)
Imports: Foundation first, then external packages, then internal modules
Naming: PascalCase for types, camelCase for variables/functions, SCREAMING_SNAKE for constants
Access control: Explicit
```
public
```
/
```
internal
```
/
```
private
```
, prefer
```
let
```
over
```
var
```
Error handling: Use custom errors (e.g.,
```
SemanticVersionError
```
), throw specific errors
Testing: Use Swift Testing framework (
```
@Test
```
,
```
@Suite
```
), descriptive test names
File structure: Sources/[Module]/ for code, Tests/[Module]Tests/ for tests
Dependencies: Check Package.swift before adding new packages
Documentation: Swift DocC for public APIs with
```
AllPublicDeclarationsHaveDocumentation
```
rule enabled

Task Automation (Taskfile.yml)

The project uses Task for automation. Key task groups:

Version Tasks

version:show:[core|full|major|minor|patch|prerelease|build]

- Display version components

```
version:bump:[patch|minor|major]
```
- Increment version with git commit

version:set:[major|minor|patch|prerelease|build]

- Set specific version values

Build Tasks

```
build:debug
```
- Debug build with code coverage
```
build:release
```
- Optimized universal binary (arm64 + x86_64)

Quality Tasks

```
format
```
- Auto-format code
```
lint
```
- Check code style
```
test
```
- Run test suite
```
test:coverage
```
- Generate coverage report
```
document
```
- Generate DocC documentation

Pipeline Tasks

```
pipeline:local
```
- Complete local validation
```
pipeline:ci
```
- GitLab CI pipeline steps

Release Tasks

```
release:prepare
```
- Generate Homebrew formula
```
release:create
```
- Create GitLab release
```
release:dry-run
```
- Test release without pushing
```
release:patch|minor|major
```
- Complete release workflow
```
release:rollback
```
- Undo last release

GitLab Integration

Registry: Packages published to

${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/semantic-version-manager

Releases: Created via GitLab API with binary and formula as assets
Protected branches: Release jobs require protected branch/tag
Manual triggers: Package and release stages require manual approval

Important Notes

Always run
```
task pipeline:local
```
before committing
Documentation comments required for all public APIs
Universal binaries built with
```
lipo
```
for both architectures
Homebrew formula auto-generated with SHA256 checksums
Git commits automated for version bumps (use
```
--no-commit
```
to disable)

Semantic Version Manager - Agent Guidelines

Quick Start Commands

Local pipeline:
```
task pipeline:local
```
- Runs format, lint, build, test, coverage, and docs
Show version:
```
task version:show:full
```
- Displays current version
Bump version:
```
task version:bump:patch
```
(or
```
minor
```
/
```
major
```
)
Release:
```
task release:patch
```
(or
```
minor
```
/
```
major
```
) - Full release pipeline
Build binary:
```
task build:release
```
- Creates universal binary (arm64 + x86_64)

Build/Test Commands

Build debug:
```
swift build
```
or
```
task build:debug
```
Build release:
```
task build:release
```
- Creates optimized universal binary
Test all:
```
swift test --parallel
```
or
```
task test
```

Test single:

swift test --filter <TestName>

(e.g.,

swift test --filter SemanticVersionTests

)

Format:

task format

swift package plugin --allow-writing-to-package-directory format-source-code

Lint:

task lint

swift package plugin lint-source-code

Coverage:
```
task test:coverage
```
(requires 85% threshold)
Documentation:
```
task document
```
- Generates DocC documentation in
```
./docs
```

Version Management

Version file:
```
version.json
```
- Contains semantic version components
Version bumping: Use
```
task version:bump:[patch|minor|major]
```
(auto-commits)
Pre-release:
```
task version:set:prerelease -- alpha.1
```
Build metadata:
```
task version:set:build -- 20250514.3
```
Git tags: Created automatically during release (
```
task release:*
```
)

Release Process

Prepare release:
```
task release:dry-run
```
- Test without pushing
Create release:
```
task release:[patch|minor|major]
```
- Full automated release
- Bumps version and commits
- Builds universal binary
- Generates Homebrew formula with SHA256
- Creates GitLab package and release
- Tags and pushes to main
Rollback:
```
task release:rollback
```
- Reverts last release if needed

GitLab CI/CD Pipeline

The

.gitlab-ci.yml

defines automated workflows:

Stages

build: Compiles project and runs initial checks
test: Runs test suite with coverage
package: Creates release artifacts (manual trigger)
release: Publishes to GitLab registry (manual trigger)

Pipeline Jobs

build-job: Format, lint, and build debug version
test-job: Run tests with 85% coverage requirement
package-job: Build universal binary and generate Homebrew formula
release-job: Upload to GitLab package registry

Artifacts

Test coverage reports (Cobertura format)
Universal binary:
```
.build/release/semantic-version-manager
```
Homebrew formula:
```
Formula/semantic-version-manager.rb
```

Code Style

Swift version: 6.1, macOS 14+ minimum
Formatting: 2-space indentation, 100 char line length, 1 blank line max (via .swift-format.json)
Imports: Foundation first, then external packages, then internal modules
Naming: PascalCase for types, camelCase for variables/functions, SCREAMING_SNAKE for constants
Access control: Explicit
```
public
```
/
```
internal
```
/
```
private
```
, prefer
```
let
```
over
```
var
```
Error handling: Use custom errors (e.g.,
```
SemanticVersionError
```
), throw specific errors
Testing: Use Swift Testing framework (
```
@Test
```
,
```
@Suite
```
), descriptive test names
File structure: Sources/[Module]/ for code, Tests/[Module]Tests/ for tests
Dependencies: Check Package.swift before adding new packages
Documentation: Swift DocC for public APIs with
```
AllPublicDeclarationsHaveDocumentation
```
rule enabled

Task Automation (Taskfile.yml)

The project uses Task for automation. Key task groups:

Version Tasks

version:show:[core|full|major|minor|patch|prerelease|build]

- Display version components

```
version:bump:[patch|minor|major]
```
- Increment version with git commit

version:set:[major|minor|patch|prerelease|build]

- Set specific version values

Build Tasks

```
build:debug
```
- Debug build with code coverage
```
build:release
```
- Optimized universal binary (arm64 + x86_64)

Quality Tasks

```
format
```
- Auto-format code
```
lint
```
- Check code style
```
test
```
- Run test suite
```
test:coverage
```
- Generate coverage report
```
document
```
- Generate DocC documentation

Pipeline Tasks

```
pipeline:local
```
- Complete local validation
```
pipeline:ci
```
- GitLab CI pipeline steps

Release Tasks

```
release:prepare
```
- Generate Homebrew formula
```
release:create
```
- Create GitLab release
```
release:dry-run
```
- Test release without pushing
```
release:patch|minor|major
```
- Complete release workflow
```
release:rollback
```
- Undo last release

GitLab Integration

Registry: Packages published to

${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/packages/generic/semantic-version-manager

Releases: Created via GitLab API with binary and formula as assets
Protected branches: Release jobs require protected branch/tag
Manual triggers: Package and release stages require manual approval

Important Notes

Always run
```
task pipeline:local
```
before committing
Documentation comments required for all public APIs
Universal binaries built with
```
lipo
```
for both architectures
Homebrew formula auto-generated with SHA256 checksums
Git commits automated for version bumps (use
```
--no-commit
```
to disable)

Semantic Version Manager - Agent Guidelines

Related Skills

Markdown Converter

Nano Banana Pro

1password