aios-core 2.1.6 → 2.2.1

package/.aios-core/development/tasks/github-devops-version-management.md

@@ -1,483 +1,483 @@
-# version-management.md
-
-**Task**: Semantic Version Management (Repository-Agnostic)
-
-**Purpose**: Analyze changes, recommend version bumps, and manage semantic versioning for ANY repository using AIOS.
-
-**When to use**: Before creating a release, to determine appropriate version number based on changes.
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: githubDevopsVersionManagement()
-responsável: Gage (Automator)
-responsavel_type: Agente
-atomic_layer: Organism
-
-**Entrada:**
-- campo: task
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Must be registered task
-
-- campo: parameters
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Valid task parameters
-
-- campo: mode
-  tipo: string
-  origem: User Input
-  obrigatório: false
-  validação: yolo|interactive|pre-flight
-
-**Saída:**
-- campo: execution_result
-  tipo: object
-  destino: Memory
-  persistido: false
-
-- campo: logs
-  tipo: array
-  destino: File (.ai/logs/*)
-  persistido: true
-
-- campo: state
-  tipo: object
-  destino: State management
-  persistido: true
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Task is registered; required parameters provided; dependencies met
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check task is registered; required parameters provided; dependencies met
-    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Task completed; exit code 0; expected outputs created
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify task completed; exit code 0; expected outputs created
-    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Task completed as expected; side effects documented
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert task completed as expected; side effects documented
-    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** task-runner
-  - **Purpose:** Task execution and orchestration
-  - **Source:** .aios-core/core/task-runner.js
-
-- **Tool:** logger
-  - **Purpose:** Execution logging and error tracking
-  - **Source:** .aios-core/utils/logger.js
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** execute-task.js
-  - **Purpose:** Generic task execution wrapper
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/execute-task.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Task Not Found
-   - **Cause:** Specified task not registered in system
-   - **Resolution:** Verify task name and registration
-   - **Recovery:** List available tasks, suggest similar
-
-2. **Error:** Invalid Parameters
-   - **Cause:** Task parameters do not match expected schema
-   - **Resolution:** Validate parameters against task definition
-   - **Recovery:** Provide parameter template, reject execution
-
-3. **Error:** Execution Timeout
-   - **Cause:** Task exceeds maximum execution time
-   - **Resolution:** Optimize task or increase timeout
-   - **Recovery:** Kill task, cleanup resources, log state
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 5-15 min (estimated)
-cost_estimated: $0.003-0.010
-token_usage: ~3,000-10,000 tokens
-```
-
-**Optimization Notes:**
-- Break into smaller workflows; implement checkpointing; use async processing where possible
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - automation
-  - workflow
-updated_at: 2025-11-17
-```
-
----
-
-
-## Prerequisites
-- Git repository with commit history
-- package.json with current version
-- Understanding of semantic versioning (MAJOR.MINOR.PATCH)
-
-## Semantic Versioning Rules
-
-- **MAJOR** (v4.0.0 → v5.0.0): Breaking changes, API redesign
-- **MINOR** (v4.31.0 → v4.32.0): New features, backward compatible
-- **PATCH** (v4.31.0 → v4.31.1): Bug fixes only
-
-## Keywords for Detection
-
-**Breaking Changes** (MAJOR):
-- `BREAKING CHANGE:`
-- `BREAKING:`
-- `!` in commit type (e.g., `feat!:`)
-- API redesign
-- Removed functionality
-- Incompatible changes
-
-**New Features** (MINOR):
-- `feat:`
-- `feature:`
-- New capability
-- Enhancement
-
-**Bug Fixes** (PATCH):
-- `fix:`
-- `bugfix:`
-- `hotfix:`
-- Patch
-
-## Workflow Steps
-
-### Step 1: Detect Repository Context
-
-```javascript
-const { detectRepositoryContext } = require('./../scripts/repository-detector');
-const context = detectRepositoryContext();
-
-if (!context) {
-  throw new Error('Unable to detect repository context. Run "aios init" first.');
-}
-
-console.log(`📦 Analyzing version for: ${context.packageName}`);
-console.log(`Current version: ${context.packageVersion}`);
-```
-
-### Step 2: Get Last Git Tag
-
-```bash
-git describe --tags --abbrev=0
-```
-
-If no tags exist, use `v0.0.0` as baseline.
-
-### Step 3: Analyze Commits Since Last Tag
-
-```bash
-git log <last-tag>..HEAD --oneline
-```
-
-Parse each commit message:
-- Count breaking changes
-- Count features
-- Count fixes
-
-### Step 4: Recommend Version Bump
-
-**Logic**:
-1. If `breakingChanges > 0` → MAJOR bump
-2. Else if `features > 0` → MINOR bump
-3. Else if `fixes > 0` → PATCH bump
-4. Else → No version bump needed
-
-### Step 5: User Confirmation
-
-Present recommendation:
-
-```
-📊 Version Analysis
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Current version:  v4.31.0
-Recommended:      v4.32.0 (MINOR)
-
-Changes since v4.31.0:
-  Breaking changes: 0
-  New features:     3
-  Bug fixes:        2
-
-Reason: New features detected (backward compatible)
-
-Proceed with version v4.32.0? (Y/n)
-```
-
-### Step 6: Update package.json
-
-```javascript
-const fs = require('fs');
-const path = require('path');
-
-const packageJsonPath = path.join(context.projectRoot, 'package.json');
-const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-
-packageJson.version = newVersion;
-
-fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
-console.log(`✓ Updated package.json to ${newVersion}`);
-```
-
-### Step 7: Create Git Tag
-
-```bash
-git tag -a v<newVersion> -m "Release v<newVersion>"
-```
-
-### Step 8: Generate Changelog
-
-Extract commits since last tag and format:
-
-```markdown
-## [4.32.0] - 2025-10-25
-
-### Added
-- New feature A
-- New feature B
-- New feature C
-
-### Fixed
-- Bug fix 1
-- Bug fix 2
-```
-
-## Example Implementation
-
-```javascript
-const { execSync } = require('child_process');
-const fs = require('fs');
-const path = require('path');
-const inquirer = require('inquirer');
-const semver = require('semver');
-
-async function manageVersion() {
-  // Step 1: Detect context
-  const { detectRepositoryContext } = require('./../scripts/repository-detector');
-  const context = detectRepositoryContext();
-
-  if (!context) {
-    console.error('❌ Unable to detect repository context');
-    process.exit(1);
-  }
-
-  console.log(`\n📦 Version Management for ${context.packageName}`);
-  console.log(`Current version: ${context.packageVersion}\n`);
-
-  // Step 2: Get last tag
-  let lastTag;
-  try {
-    lastTag = execSync('git describe --tags --abbrev=0', {
-      cwd: context.projectRoot
-    }).toString().trim();
-  } catch (error) {
-    lastTag = 'v0.0.0';
-    console.log('⚠️  No tags found, using v0.0.0 as baseline');
-  }
-
-  console.log(`Last tag: ${lastTag}\n`);
-
-  // Step 3: Analyze commits
-  const commits = execSync(`git log ${lastTag}..HEAD --oneline`, {
-    cwd: context.projectRoot
-  }).toString().trim().split('\n').filter(Boolean);
-
-  let breakingChanges = 0;
-  let features = 0;
-  let fixes = 0;
-
-  const breakingPattern = /BREAKING CHANGE:|BREAKING:|^\w+!:/;
-  const featurePattern = /^feat:|^feature:/;
-  const fixPattern = /^fix:|^bugfix:|^hotfix:/;
-
-  commits.forEach(commit => {
-    if (breakingPattern.test(commit)) breakingChanges++;
-    else if (featurePattern.test(commit)) features++;
-    else if (fixPattern.test(commit)) fixes++;
-  });
-
-  // Step 4: Recommend version
-  const currentVersion = context.packageVersion.replace(/^v/, '');
-  let newVersion;
-  let bumpType;
-
-  if (breakingChanges > 0) {
-    newVersion = semver.inc(currentVersion, 'major');
-    bumpType = 'MAJOR';
-  } else if (features > 0) {
-    newVersion = semver.inc(currentVersion, 'minor');
-    bumpType = 'MINOR';
-  } else if (fixes > 0) {
-    newVersion = semver.inc(currentVersion, 'patch');
-    bumpType = 'PATCH';
-  } else {
-    console.log('ℹ️  No version bump needed (no changes detected)');
-    process.exit(0);
-  }
-
-  // Step 5: User confirmation
-  console.log('📊 Version Analysis');
-  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log(`Current version:  v${currentVersion}`);
-  console.log(`Recommended:      v${newVersion} (${bumpType})`);
-  console.log('');
-  console.log(`Changes since ${lastTag}:`);
-  console.log(`  Breaking changes: ${breakingChanges}`);
-  console.log(`  New features:     ${features}`);
-  console.log(`  Bug fixes:        ${fixes}`);
-  console.log('');
-
-  const { confirm } = await inquirer.prompt([
-    {
-      type: 'confirm',
-      name: 'confirm',
-      message: `Proceed with version v${newVersion}?`,
-      default: true
-    }
-  ]);
-
-  if (!confirm) {
-    console.log('❌ Version update cancelled');
-    process.exit(0);
-  }
-
-  // Step 6: Update package.json
-  const packageJsonPath = path.join(context.projectRoot, 'package.json');
-  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
-  packageJson.version = newVersion;
-  fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
-  console.log(`\n✓ Updated package.json to v${newVersion}`);
-
-  // Step 7: Create git tag
-  execSync(`git tag -a v${newVersion} -m "Release v${newVersion}"`, {
-    cwd: context.projectRoot
-  });
-  console.log(`✓ Created git tag v${newVersion}`);
-
-  console.log('\n✅ Version management complete!');
-  console.log(`\nNext steps:`);
-  console.log(`  - Review changes: git show v${newVersion}`);
-  console.log(`  - Push tag: git push origin v${newVersion}`);
-  console.log(`  - Create release with @github-devops *release`);
-}
-
-module.exports = { manageVersion };
-```
-
-## Usage
-
-Called by `@github-devops` agent via `*version-check` command.
-
-## Validation
-
-- Version bump follows semantic versioning rules
-- User confirms version change
-- Git tag created successfully
-- package.json updated correctly
-
-## Notes
-
-- Works with ANY repository (framework or project)
-- Respects conventional commits format
-- User always has final approval
-- Does NOT push to remote (that's done by *push command)
+# version-management.md
+
+**Task**: Semantic Version Management (Repository-Agnostic)
+
+**Purpose**: Analyze changes, recommend version bumps, and manage semantic versioning for ANY repository using AIOS.
+
+**When to use**: Before creating a release, to determine appropriate version number based on changes.
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: githubDevopsVersionManagement()
+responsável: Gage (Automator)
+responsavel_type: Agente
+atomic_layer: Organism
+
+**Entrada:**
+- campo: task
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be registered task
+
+- campo: parameters
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid task parameters
+
+- campo: mode
+  tipo: string
+  origem: User Input
+  obrigatório: false
+  validação: yolo|interactive|pre-flight
+
+**Saída:**
+- campo: execution_result
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: logs
+  tipo: array
+  destino: File (.ai/logs/*)
+  persistido: true
+
+- campo: state
+  tipo: object
+  destino: State management
+  persistido: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Task is registered; required parameters provided; dependencies met
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check task is registered; required parameters provided; dependencies met
+    error_message: "Pre-condition failed: Task is registered; required parameters provided; dependencies met"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Task completed; exit code 0; expected outputs created
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify task completed; exit code 0; expected outputs created
+    error_message: "Post-condition failed: Task completed; exit code 0; expected outputs created"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Task completed as expected; side effects documented
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert task completed as expected; side effects documented
+    error_message: "Acceptance criterion not met: Task completed as expected; side effects documented"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** task-runner
+  - **Purpose:** Task execution and orchestration
+  - **Source:** .aios-core/core/task-runner.js
+
+- **Tool:** logger
+  - **Purpose:** Execution logging and error tracking
+  - **Source:** .aios-core/utils/logger.js
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** execute-task.js
+  - **Purpose:** Generic task execution wrapper
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/execute-task.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Task Not Found
+   - **Cause:** Specified task not registered in system
+   - **Resolution:** Verify task name and registration
+   - **Recovery:** List available tasks, suggest similar
+
+2. **Error:** Invalid Parameters
+   - **Cause:** Task parameters do not match expected schema
+   - **Resolution:** Validate parameters against task definition
+   - **Recovery:** Provide parameter template, reject execution
+
+3. **Error:** Execution Timeout
+   - **Cause:** Task exceeds maximum execution time
+   - **Resolution:** Optimize task or increase timeout
+   - **Recovery:** Kill task, cleanup resources, log state
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-15 min (estimated)
+cost_estimated: $0.003-0.010
+token_usage: ~3,000-10,000 tokens
+```
+
+**Optimization Notes:**
+- Break into smaller workflows; implement checkpointing; use async processing where possible
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Prerequisites
+- Git repository with commit history
+- package.json with current version
+- Understanding of semantic versioning (MAJOR.MINOR.PATCH)
+
+## Semantic Versioning Rules
+
+- **MAJOR** (v4.0.0 → v5.0.0): Breaking changes, API redesign
+- **MINOR** (v4.31.0 → v4.32.0): New features, backward compatible
+- **PATCH** (v4.31.0 → v4.31.1): Bug fixes only
+
+## Keywords for Detection
+
+**Breaking Changes** (MAJOR):
+- `BREAKING CHANGE:`
+- `BREAKING:`
+- `!` in commit type (e.g., `feat!:`)
+- API redesign
+- Removed functionality
+- Incompatible changes
+
+**New Features** (MINOR):
+- `feat:`
+- `feature:`
+- New capability
+- Enhancement
+
+**Bug Fixes** (PATCH):
+- `fix:`
+- `bugfix:`
+- `hotfix:`
+- Patch
+
+## Workflow Steps
+
+### Step 1: Detect Repository Context
+
+```javascript
+const { detectRepositoryContext } = require('./../scripts/repository-detector');
+const context = detectRepositoryContext();
+
+if (!context) {
+  throw new Error('Unable to detect repository context. Run "aios init" first.');
+}
+
+console.log(`📦 Analyzing version for: ${context.packageName}`);
+console.log(`Current version: ${context.packageVersion}`);
+```
+
+### Step 2: Get Last Git Tag
+
+```bash
+git describe --tags --abbrev=0
+```
+
+If no tags exist, use `v0.0.0` as baseline.
+
+### Step 3: Analyze Commits Since Last Tag
+
+```bash
+git log <last-tag>..HEAD --oneline
+```
+
+Parse each commit message:
+- Count breaking changes
+- Count features
+- Count fixes
+
+### Step 4: Recommend Version Bump
+
+**Logic**:
+1. If `breakingChanges > 0` → MAJOR bump
+2. Else if `features > 0` → MINOR bump
+3. Else if `fixes > 0` → PATCH bump
+4. Else → No version bump needed
+
+### Step 5: User Confirmation
+
+Present recommendation:
+
+```
+📊 Version Analysis
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Current version:  v4.31.0
+Recommended:      v4.32.0 (MINOR)
+
+Changes since v4.31.0:
+  Breaking changes: 0
+  New features:     3
+  Bug fixes:        2
+
+Reason: New features detected (backward compatible)
+
+Proceed with version v4.32.0? (Y/n)
+```
+
+### Step 6: Update package.json
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+
+const packageJsonPath = path.join(context.projectRoot, 'package.json');
+const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+packageJson.version = newVersion;
+
+fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+console.log(`✓ Updated package.json to ${newVersion}`);
+```
+
+### Step 7: Create Git Tag
+
+```bash
+git tag -a v<newVersion> -m "Release v<newVersion>"
+```
+
+### Step 8: Generate Changelog
+
+Extract commits since last tag and format:
+
+```markdown
+## [4.32.0] - 2025-10-25
+
+### Added
+- New feature A
+- New feature B
+- New feature C
+
+### Fixed
+- Bug fix 1
+- Bug fix 2
+```
+
+## Example Implementation
+
+```javascript
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const inquirer = require('inquirer');
+const semver = require('semver');
+
+async function manageVersion() {
+  // Step 1: Detect context
+  const { detectRepositoryContext } = require('./../scripts/repository-detector');
+  const context = detectRepositoryContext();
+
+  if (!context) {
+    console.error('❌ Unable to detect repository context');
+    process.exit(1);
+  }
+
+  console.log(`\n📦 Version Management for ${context.packageName}`);
+  console.log(`Current version: ${context.packageVersion}\n`);
+
+  // Step 2: Get last tag
+  let lastTag;
+  try {
+    lastTag = execSync('git describe --tags --abbrev=0', {
+      cwd: context.projectRoot
+    }).toString().trim();
+  } catch (error) {
+    lastTag = 'v0.0.0';
+    console.log('⚠️  No tags found, using v0.0.0 as baseline');
+  }
+
+  console.log(`Last tag: ${lastTag}\n`);
+
+  // Step 3: Analyze commits
+  const commits = execSync(`git log ${lastTag}..HEAD --oneline`, {
+    cwd: context.projectRoot
+  }).toString().trim().split('\n').filter(Boolean);
+
+  let breakingChanges = 0;
+  let features = 0;
+  let fixes = 0;
+
+  const breakingPattern = /BREAKING CHANGE:|BREAKING:|^\w+!:/;
+  const featurePattern = /^feat:|^feature:/;
+  const fixPattern = /^fix:|^bugfix:|^hotfix:/;
+
+  commits.forEach(commit => {
+    if (breakingPattern.test(commit)) breakingChanges++;
+    else if (featurePattern.test(commit)) features++;
+    else if (fixPattern.test(commit)) fixes++;
+  });
+
+  // Step 4: Recommend version
+  const currentVersion = context.packageVersion.replace(/^v/, '');
+  let newVersion;
+  let bumpType;
+
+  if (breakingChanges > 0) {
+    newVersion = semver.inc(currentVersion, 'major');
+    bumpType = 'MAJOR';
+  } else if (features > 0) {
+    newVersion = semver.inc(currentVersion, 'minor');
+    bumpType = 'MINOR';
+  } else if (fixes > 0) {
+    newVersion = semver.inc(currentVersion, 'patch');
+    bumpType = 'PATCH';
+  } else {
+    console.log('ℹ️  No version bump needed (no changes detected)');
+    process.exit(0);
+  }
+
+  // Step 5: User confirmation
+  console.log('📊 Version Analysis');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log(`Current version:  v${currentVersion}`);
+  console.log(`Recommended:      v${newVersion} (${bumpType})`);
+  console.log('');
+  console.log(`Changes since ${lastTag}:`);
+  console.log(`  Breaking changes: ${breakingChanges}`);
+  console.log(`  New features:     ${features}`);
+  console.log(`  Bug fixes:        ${fixes}`);
+  console.log('');
+
+  const { confirm } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirm',
+      message: `Proceed with version v${newVersion}?`,
+      default: true
+    }
+  ]);
+
+  if (!confirm) {
+    console.log('❌ Version update cancelled');
+    process.exit(0);
+  }
+
+  // Step 6: Update package.json
+  const packageJsonPath = path.join(context.projectRoot, 'package.json');
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  packageJson.version = newVersion;
+  fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n');
+  console.log(`\n✓ Updated package.json to v${newVersion}`);
+
+  // Step 7: Create git tag
+  execSync(`git tag -a v${newVersion} -m "Release v${newVersion}"`, {
+    cwd: context.projectRoot
+  });
+  console.log(`✓ Created git tag v${newVersion}`);
+
+  console.log('\n✅ Version management complete!');
+  console.log(`\nNext steps:`);
+  console.log(`  - Review changes: git show v${newVersion}`);
+  console.log(`  - Push tag: git push origin v${newVersion}`);
+  console.log(`  - Create release with @github-devops *release`);
+}
+
+module.exports = { manageVersion };
+```
+
+## Usage
+
+Called by `@github-devops` agent via `*version-check` command.
+
+## Validation
+
+- Version bump follows semantic versioning rules
+- User confirms version change
+- Git tag created successfully
+- package.json updated correctly
+
+## Notes
+
+- Works with ANY repository (framework or project)
+- Respects conventional commits format
+- User always has final approval
+- Does NOT push to remote (that's done by *push command)