cc-agentic-framework 1.14.1

package/framework/modules/core/skills/managing-versions/SKILL.md

@@ -0,0 +1,260 @@
+---
+id: managing-versions
+name: managing-framework-versions
+description: Manage framework versioning including bumping versions, querying versions, and running affected tests. Use when working with framework version management.
+scope: apmr
+applicable-projects: apm-r-ai-agentic-framework
+module: core
+capabilities-provided:
+  - version-management
+---
+
+# Managing Framework Versions
+
+## When to Use This Skill
+
+Use this skill when you need to:
+- **Bump module versions** (major/minor/patch) manually or automatically
+- **Run affected tests** for modules with changes
+- **Query current module versions** from `.agentic-framework.json`
+- **Understand when to use major/minor/patch** bumps
+
+This skill is **framework-specific** - only works with apm-r-ai-agentic-framework repository.
+
+**For git commit practices, branch naming, and PR workflows** → use the `committing-code` skill.
+
+---
+
+## Key Concepts
+
+### Independent Module Versioning
+
+Each module has its own independent version, stored in two places:
+1. **`framework/modules/<module>/module.json`** - Module's own version file
+2. **`.agentic-framework.json`** - Project-wide module version tracking
+
+This allows:
+- Independent version lifecycles per module
+- Precise change tracking
+- Targeted version bumps based on actual changes
+
+### Version Storage
+
+**Module manifest** (`framework/modules/core/module.json`):
+```json
+{
+  "name": "core",
+  "version": "1.4.1"
+}
+```
+
+**Project config** (`.agentic-framework.json`):
+```json
+{
+  "modules": {
+    "core": "1.4.1",
+    "backlog": "1.0.1",
+    "jira": "1.0.1"
+  }
+}
+```
+
+---
+
+## CLI Commands
+
+### `bump-version` Command
+
+Bump versions for modules, either manually or automatically based on affected detection.
+
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--major` | Increment major version (X.0.0) |
+| `--minor` | Increment minor version (X.Y.0) |
+| `--patch` | Increment patch version (X.Y.Z) - default |
+| `--module <name>` | Target specific module |
+| `--auto` | Auto-detect affected modules from git diff |
+| `--base-branch <branch>` | Base branch for comparison (default: main) |
+| `--stage` | Stage version files after update |
+| `--dry-run` | Preview changes without executing |
+
+**Examples:**
+
+```bash
+# Bump specific module
+agentic-framework bump-version --module core --patch
+agentic-framework bump-version --module backlog --minor
+
+# Auto-bump all affected modules
+agentic-framework bump-version --auto
+
+# Preview what would be bumped
+agentic-framework bump-version --auto --dry-run
+```
+
+### `test` Command
+
+Run tests selectively based on affected modules.
+
+**Flags:**
+
+| Flag | Description |
+|------|-------------|
+| `--affected` | Run tests only for affected modules |
+| `-m, --module <name>` | Run tests for specific module |
+| `--base-branch <branch>` | Base branch for detection (default: main) |
+| `--bail` | Bail on first failure |
+| `--dry-run` | Show what would run |
+
+**Examples:**
+
+```bash
+# Run tests for affected modules only
+agentic-framework test --affected
+
+# Run tests for specific module
+agentic-framework test --module backlog
+
+# Preview what tests would run
+agentic-framework test --affected --dry-run
+```
+
+---
+
+## When to Bump Versions
+
+### Major Version (X.0.0)
+
+**Use when:** Breaking changes, architecture refactoring
+
+**Examples:**
+- Change module API contract
+- Restructure module file organization
+- Remove deprecated functionality
+
+**Command:**
+```bash
+agentic-framework bump-version --module core --major
+```
+
+### Minor Version (X.Y.0)
+
+**Use when:** New features, enhancements (backward compatible)
+
+**Examples:**
+- Add new skill to module
+- Add new CLI command
+- Enhance existing capabilities
+
+**Command:**
+```bash
+agentic-framework bump-version --module backlog --minor
+```
+
+### Patch Version (X.Y.Z)
+
+**Use when:** Bug fixes, documentation, small improvements
+
+**Examples:**
+- Fix bug in existing code
+- Update documentation
+- Correct metadata
+
+**Command (default):**
+```bash
+agentic-framework bump-version --module jira --patch
+```
+
+---
+
+## Pre-Commit Hook Integration
+
+The framework's pre-commit hook automatically handles versioning:
+
+1. **Build** - Compile TypeScript CLI
+2. **Test** - Run tests for affected modules (`--bail`)
+3. **Version** - Auto-bump patch versions for affected modules
+4. **Sync** - Sync deployment files to `.claude/`
+
+**Configuration (environment variables):**
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `RUN_AFFECTED_TESTS` | `true` | Run affected tests |
+| `AUTO_BUMP_VERSIONS` | `true` | Auto-bump patch versions |
+| `BASE_BRANCH` | `main` | Base for comparison |
+
+**Skip version bumping:**
+```bash
+AUTO_BUMP_VERSIONS=false git commit -m "message"
+```
+
+---
+
+## Affected Module Detection
+
+### How It Works
+
+1. **Git diff analysis** - Compares current branch to base branch (main)
+2. **File-to-module mapping** - Maps changed files to their owning modules
+3. **Module aggregation** - Groups changes by module
+
+### File-to-Module Mapping
+
+| File Pattern | Module |
+|--------------|--------|
+| `framework/modules/backlog/` | backlog |
+| `framework/modules/jira/` | jira |
+| `framework/modules/core/` | core |
+| `framework/cli/src/commands/backlog/` | backlog |
+| `framework/cli/src/lib/jira/` | jira |
+| `framework/cli/` (generic) | core |
+
+---
+
+## Troubleshooting
+
+### Wrong Version Bump Type
+
+If auto-bump was patch but you need minor:
+```bash
+# 1. Undo commit
+git reset HEAD~1
+
+# 2. Manual bump
+agentic-framework bump-version --module <name> --minor
+
+# 3. Commit again
+git add . && git commit -m "message"
+```
+
+### Module Not Detected as Affected
+
+Check file-to-module mapping in `framework/cli/src/lib/affected-modules.ts`.
+
+---
+
+## See Also
+
+### Related Skills
+- **[committing-code](../committing-code/SKILL.md)** - Git commit practices, branch naming, PR workflows
+
+### Supporting Files
+- [Examples](EXAMPLES.md) - Version bump scenarios
+- [Standards](STANDARDS.md) - Semantic versioning rules
+- [CLI Reference](SCRIPTS-REFERENCE.md) - Detailed CLI documentation
+
+### Framework Resources
+- **Affected Modules Library:** `framework/cli/src/lib/affected-modules.ts`
+- **Bump Version Command:** `framework/cli/src/commands/bump-version.ts`
+- **Test Command:** `framework/cli/src/commands/test.ts`
+
+---
+
+**Skill Version:** 2.1
+**Status:** Complete - Ready for use
+**Token Budget:** ~2000 tokens
+**Updated:** 2026-01-12
+**Framework Version:** 1.4.1+

package/framework/modules/core/skills/managing-versions/STANDARDS.md

@@ -0,0 +1,231 @@
+# Version Management Standards
+
+Standards and rules for framework versioning with independent module versioning.
+
+**For git commit message standards** → see `committing-code` skill.
+
+---
+
+## Independent Module Versioning
+
+### Core Principle
+
+Each module maintains its own version independently. This allows:
+- **Precise tracking** - Only bumped modules reflect changes
+- **Independent lifecycles** - Modules can be at different version stages
+- **Targeted updates** - Users know exactly what changed
+
+### Version Storage
+
+Versions are stored in two locations (kept in sync automatically):
+
+**1. Module Manifest** (`framework/modules/<module>/module.json`)
+```json
+{
+  "name": "backlog",
+  "version": "1.0.1"
+}
+```
+
+**2. Project Config** (`.agentic-framework.json`)
+```json
+{
+  "modules": {
+    "core": "1.4.1",
+    "backlog": "1.0.1",
+    "jira": "1.0.1"
+  }
+}
+```
+
+---
+
+## Semantic Versioning Rules
+
+### Version Format
+
+**Format:** `MAJOR.MINOR.PATCH`
+
+**Example:** `1.4.1`
+
+- **MAJOR**: Breaking changes, architecture refactoring (1.x.x → 2.0.0)
+- **MINOR**: New features, enhancements (1.4.x → 1.5.0)
+- **PATCH**: Bug fixes, documentation (1.4.1 → 1.4.2)
+
+### When to Increment
+
+#### MAJOR Version (X.0.0)
+
+**Increment when:**
+- Breaking changes to module API
+- Incompatible changes to file formats
+- Removal of deprecated functionality
+- Major restructuring of module content
+
+**Typical cadence:** As needed for breaking changes
+
+#### MINOR Version (X.Y.0)
+
+**Increment when:**
+- New features added (backward compatible)
+- New skills introduced
+- New agents added
+- Enhanced existing capabilities
+- New CLI commands
+
+**Typical cadence:** When completing feature milestones
+
+#### PATCH Version (X.Y.Z)
+
+**Increment when:**
+- Bug fixes (no new features)
+- Documentation corrections
+- Minor improvements
+- Metadata corrections
+
+**Typical cadence:** Automatic on every commit (default)
+
+---
+
+## Version Bump Decision Tree
+
+```
+Is it a breaking change?
+├── Yes → MAJOR (manual: --major)
+└── No
+    ├── Is it a new feature?
+    │   ├── Yes → MINOR (manual: --minor)
+    │   └── No → PATCH (auto or --patch)
+```
+
+### Breaking Change Examples
+- Removing a skill
+- Changing skill YAML frontmatter schema
+- Renaming required fields
+- Changing CLI command interface
+
+### Non-Breaking Examples
+- Adding new skill
+- Adding new agent
+- Enhancing existing functionality
+- Fixing bugs
+
+---
+
+## Atomic Updates
+
+### Requirement
+
+Both version storage locations must be updated together:
+- `framework/modules/<module>/module.json`
+- `.agentic-framework.json`
+
+### How CLI Ensures This
+
+1. Read current versions from both files
+2. Calculate new version
+3. Update both files in memory
+4. Write both files atomically
+5. If either write fails, rollback both
+
+**Manual edits are NOT recommended** because they can cause inconsistencies.
+
+---
+
+## Pre-Commit Hook Phases
+
+The pre-commit hook automates versioning:
+
+```
+Phase 1: Build CLI
+Phase 2: Run Affected Tests (--bail)
+Phase 3: Auto-Bump Patch Versions
+Phase 4: Sync Deployment Files
+```
+
+### Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `RUN_AFFECTED_TESTS` | `true` | Run affected tests |
+| `AUTO_BUMP_VERSIONS` | `true` | Auto-bump patch versions |
+| `BASE_BRANCH` | `main` | Base for comparison |
+
+---
+
+## Affected Module Detection
+
+### File-to-Module Mapping
+
+Files are mapped to modules using patterns:
+
+| Pattern | Module |
+|---------|--------|
+| `framework/modules/backlog/` | backlog |
+| `framework/modules/jira/` | jira |
+| `framework/modules/core/` | core |
+| `framework/cli/src/commands/backlog/` | backlog |
+| `framework/cli/src/lib/jira/` | jira |
+| `framework/cli/` (generic) | core |
+
+### Detection Algorithm
+
+1. Get git diff from merge-base to HEAD
+2. Include any uncommitted changes
+3. Map each file to its module
+4. Aggregate unique modules
+5. Return affected module list
+
+---
+
+## Best Practices
+
+### DO
+
+- **Use automation**: Let pre-commit hook handle patch bumps
+- **Use CLI for manual bumps**: `agentic-framework bump-version`
+- **Run dry-run first**: `--dry-run` to preview changes
+- **Follow semver**: Use correct increment type
+
+### DON'T
+
+- **Manual edits**: Don't edit version numbers manually
+- **Skip hooks entirely**: Avoid `git commit --no-verify`
+
+---
+
+## Module Version Lifecycle
+
+### Initial Release
+
+New modules start at `1.0.0`:
+```json
+{
+  "name": "new-module",
+  "version": "1.0.0"
+}
+```
+
+### Development Cycle
+
+```
+1.0.0 → 1.0.1 → 1.0.2  (patches)
+      ↓
+    1.1.0              (minor: new feature)
+      ↓
+    2.0.0              (major: breaking change)
+```
+
+### Cross-Module Changes
+
+When changes span modules:
+- Each affected module gets its own bump
+- Modules are bumped independently
+- No coupling between module versions
+
+---
+
+**Standards Version:** 2.1
+**Updated:** 2026-01-12
+**Framework Version:** 1.4.1+
+**Reference:** Semantic Versioning 2.0.0