aidevops 2.52.1 → 2.53.2

package/.agent/workflows/version-bump.md

@@ -1,283 +0,0 @@
----
-description: Authoritative guide for version management in aidevops
-mode: subagent
-tools:
-  read: true
-  write: true
-  edit: true
-  bash: true
-  glob: true
-  grep: true
-  webfetch: false
-  task: true
----
-
-# Version Bump Workflow
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **Full release**: `.agent/scripts/version-manager.sh release [major|minor|patch] --skip-preflight`
-- **CRITICAL**: This single command does everything - bump, commit, tag, push, GitHub release
-- **NEVER** run separate commands, manually edit VERSION, or bump versions yourself
-- **Files updated atomically**: VERSION, package.json, README.md badge, setup.sh, sonar-project.properties, .claude-plugin/marketplace.json
-- **Manual step**: Update CHANGELOG.md `[Unreleased]` to `[X.X.X] - YYYY-MM-DD` BEFORE running release
-- **Preflight**: Quality checks run automatically (bypass with `--skip-preflight`)
-
-<!-- AI-CONTEXT-END -->
-
-This is the authoritative guide for AI agents performing version bumps in the aidevops repository.
-
-## Critical: Never Edit VERSION Directly
-
-**DO NOT** manually edit the VERSION file. This causes version inconsistencies and CI failures.
-
-The script updates 6 files atomically:
-1. VERSION
-2. README.md (badge)
-3. sonar-project.properties
-4. setup.sh (header comment)
-5. package.json
-6. .claude-plugin/marketplace.json
-
-If you edit VERSION directly, the other 5 files become stale.
-
-**Always use**:
-
-```bash
-.agent/scripts/version-manager.sh bump [major|minor|patch]
-# or for full release:
-.agent/scripts/version-manager.sh release [major|minor|patch]
-```
-
-## The Primary Tool: version-manager.sh
-
-**Location**: `.agent/scripts/version-manager.sh`
-
-This script handles all version management tasks:
-
-- Bumps semantic versions (major/minor/patch)
-- Updates version references across 6 files
-- Validates version consistency
-- Creates git tags
-- Creates GitHub releases (via `gh` CLI)
-- Runs preflight quality checks
-
-## Complete Command Reference
-
-| Command | Purpose |
-|---------|---------|
-| `get` | Display current version from VERSION file |
-| `bump [type]` | Bump version and update all files |
-| `validate` | Check version consistency across all files |
-| `release [type]` | Full release: bump, validate, tag, GitHub release |
-| `tag` | Create git tag for current version |
-| `github-release` | Create GitHub release for current version |
-| `changelog-check` | Verify CHANGELOG.md has entry for current version |
-| `changelog-preview` | Generate changelog entries from commits |
-
-### Release Options
-
-```bash
-# Standard release (runs preflight checks, requires changelog)
-.agent/scripts/version-manager.sh release patch
-
-# Bypass changelog check
-.agent/scripts/version-manager.sh release minor --force
-
-# Bypass preflight quality checks
-.agent/scripts/version-manager.sh release patch --skip-preflight
-
-# Bypass both
-.agent/scripts/version-manager.sh release patch --force --skip-preflight
-```
-
-## Files Updated Automatically
-
-The script updates these 6 files:
-
-| File | What's Updated |
-|------|----------------|
-| `VERSION` | Plain version number (e.g., `1.6.0`) |
-| `package.json` | `"version": "X.X.X"` field |
-| `README.md` | Version badge: `Version-X.X.X-blue` |
-| `setup.sh` | Header comment: `# Version: X.X.X` |
-| `sonar-project.properties` | `sonar.projectVersion=X.X.X` |
-| `.claude-plugin/marketplace.json` | `"version": "X.X.X"` field |
-
-## The CHANGELOG.md Gap
-
-**CHANGELOG.md requires manual update before running `release`.**
-
-The script checks for content in `[Unreleased]` but does NOT automatically move it to a versioned section.
-
-### Before Running Release
-
-1. Open `CHANGELOG.md`
-2. Change `## [Unreleased]` to `## [X.X.X] - YYYY-MM-DD`
-3. Add a new empty `## [Unreleased]` section above it
-4. Then run the release command
-
-### Example CHANGELOG Update
-
-Before:
-
-```markdown
-## [Unreleased]
-
-### Added
-- New feature X
-```
-
-After (for version 1.6.0):
-
-```markdown
-## [Unreleased]
-
-## [1.6.0] - 2025-06-05
-
-### Added
-- New feature X
-```
-
-### Generating Changelog Content
-
-```bash
-# Preview suggested changelog entries from commits
-.agent/scripts/version-manager.sh changelog-preview
-```
-
-## Recommended Workflow
-
-### Step 1: Validate Current State
-
-```bash
-.agent/scripts/version-manager.sh validate
-```
-
-This catches stale versions before you start. Fix any inconsistencies first.
-
-### Step 2: Update CHANGELOG.md
-
-Manually update the changelog (see gap section above).
-
-### Step 3: Run Release
-
-```bash
-# For bug fixes
-.agent/scripts/version-manager.sh release patch
-
-# For new features
-.agent/scripts/version-manager.sh release minor
-
-# For breaking changes
-.agent/scripts/version-manager.sh release major
-```
-
-### Step 4: Push Changes
-
-```bash
-git push && git push --tags
-```
-
-## Semantic Versioning Rules
-
-Follow [semver.org](https://semver.org/):
-
-| Type | When to Use | Example |
-|------|-------------|---------|
-| **patch** | Bug fixes, docs, minor improvements | 1.5.0 -> 1.5.1 |
-| **minor** | New features, service integrations | 1.5.0 -> 1.6.0 |
-| **major** | Breaking changes, API modifications | 1.5.0 -> 2.0.0 |
-
-## Validation Details
-
-The `validate` command checks:
-
-- VERSION file exists and contains expected version
-- README.md badge contains `Version-X.X.X-blue`
-- sonar-project.properties contains `sonar.projectVersion=X.X.X`
-- setup.sh contains `# Version: X.X.X`
-
-```bash
-# Example output
-[INFO] Validating version consistency across files...
-[SUCCESS] VERSION file: 1.5.0 ✓
-[SUCCESS] README.md badge: 1.5.0 ✓
-[SUCCESS] sonar-project.properties: 1.5.0 ✓
-[SUCCESS] setup.sh: 1.5.0 ✓
-[SUCCESS] All version references are consistent: 1.5.0
-```
-
-## Preflight Quality Checks
-
-The `release` command automatically runs `.agent/scripts/linters-local.sh` before proceeding.
-
-To bypass (not recommended):
-
-```bash
-.agent/scripts/version-manager.sh release patch --skip-preflight
-```
-
-## Troubleshooting
-
-### Version Inconsistency Detected
-
-```bash
-# See which files are out of sync
-.agent/scripts/version-manager.sh validate
-
-# Sync all files to current VERSION
-.agent/scripts/version-manager.sh bump patch  # or use sync if available
-```
-
-### GitHub Release Failed
-
-Ensure GitHub CLI is authenticated:
-
-```bash
-gh auth status
-gh auth login  # if needed
-```
-
-### Changelog Check Failed
-
-Either update CHANGELOG.md or bypass:
-
-```bash
-.agent/scripts/version-manager.sh release patch --force
-```
-
-## Related Workflows
-
-- `workflows/changelog.md` - Changelog management details
-- `workflows/release.md` - Full release process
-- `workflows/preflight.md` - Quality checks before release
-
-## AI Decision-Making for Release Type
-
-When performing releases, **determine the release type autonomously** by analyzing the changes:
-
-1. Review commits since last release: `git log v{LAST_TAG}..HEAD --oneline`
-2. Categorize each change: bug fix, feature, or breaking change
-3. Apply semver rules - highest category wins:
-   - Any breaking change → `major`
-   - Any new feature (no breaking) → `minor`
-   - Only fixes/docs/improvements → `patch`
-4. State your analysis briefly and proceed with the release
-
-**Do not ask the user** to choose patch/minor/major. The semver rules are deterministic - apply them based on the actual changes made.
-
-### Change Type Indicators
-
-| Commit Prefix | Type | Release |
-|---------------|------|---------|
-| `feat:` | New feature | minor |
-| `fix:` | Bug fix | patch |
-| `docs:` | Documentation | patch |
-| `chore:` | Maintenance | patch |
-| `refactor:` | Code restructure | patch |
-| `perf:` | Performance | patch |
-| `BREAKING CHANGE:` | Breaking | major |
-| `!` after type (e.g., `feat!:`) | Breaking | major |

package/.agent/workflows/wiki-update.md

@@ -1,333 +0,0 @@
----
-description: Update GitHub wiki from latest codebase state
-mode: subagent
-tools:
-  read: true
-  write: true
-  edit: true
-  bash: false
-  glob: true
-  grep: true
-  webfetch: false
-  task: true
----
-
-# Wiki Update Workflow
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **Purpose**: Update GitHub wiki from latest codebase state
-- **Wiki Location**: `.wiki/` directory (synced via GitHub Actions)
-- **Sync Workflow**: `.github/workflows/sync-wiki.yml`
-- **Context Tools**: Augment Context Engine, Repomix
-
-**Key Files**:
-
-| File | Purpose |
-|------|---------|
-| `.wiki/Home.md` | Landing page |
-| `.wiki/_Sidebar.md` | Navigation structure |
-| `.wiki/Getting-Started.md` | Installation guide |
-| `.wiki/The-Agent-Directory.md` | Framework structure |
-| `repomix-instruction.md` | Codebase context instructions |
-
-**Workflow**:
-
-1. Build codebase context (Augment/Repomix)
-2. Review current wiki against codebase
-3. Update wiki pages with changes
-4. Commit to `.wiki/` directory
-5. Push triggers auto-sync to GitHub wiki
-
-<!-- AI-CONTEXT-END -->
-
-## Overview
-
-This workflow guides updating the GitHub wiki to reflect the latest state of the aidevops repository. The wiki provides high-level orientation and digestible documentation for users.
-
-## Prerequisites
-
-- Access to Augment Context Engine MCP (for semantic codebase understanding)
-- Repomix available (for structured codebase packing)
-- Write access to the repository
-
-## Step 1: Build Codebase Context
-
-### Using Augment Context Engine
-
-Query the codebase for comprehensive understanding:
-
-```text
-"What is this project? Please use codebase retrieval tool to get the answer."
-```
-
-Key queries for wiki updates:
-
-```text
-# Architecture overview
-"Describe the overall architecture and directory structure of this project"
-
-# New features since last update
-"What are the main features and capabilities of this framework?"
-
-# Service integrations
-"List all service integrations and their purposes"
-
-# Workflow guides
-"What workflows are available in .agent/workflows/?"
-```
-
-### Using Repomix
-
-Generate structured codebase context:
-
-```bash
-# Compress mode for token-efficient overview
-.agent/scripts/context-builder-helper.sh compress .
-
-# Or use Repomix MCP directly
-# pack_codebase with compress=true for ~80% token reduction
-```
-
-Reference `repomix-instruction.md` for codebase understanding guidelines.
-
-## Step 2: Review Current Wiki State
-
-### Wiki Structure
-
-```text
-.wiki/
-├── Home.md                    # Landing page, version, quick start
-├── _Sidebar.md                # Navigation structure
-├── Getting-Started.md         # Installation and setup
-├── For-Humans.md              # Non-technical overview
-├── Understanding-AGENTS-md.md # How AI guidance works
-├── The-Agent-Directory.md     # Framework structure
-├── Workflows-Guide.md         # Development processes
-├── MCP-Integrations.md        # MCP server documentation
-└── Providers.md               # Service provider details
-```
-
-### Review Checklist
-
-- [ ] Version number matches `VERSION` file
-- [ ] Service count matches actual integrations
-- [ ] Script count matches `.agent/scripts/` contents
-- [ ] MCP integrations list is current
-- [ ] Workflow guides reflect actual workflows
-- [ ] Code examples are accurate and working
-
-## Step 3: Identify Updates Needed
-
-### Compare Against Codebase
-
-| Wiki Section | Source of Truth |
-|--------------|-----------------|
-| Version | `VERSION` file |
-| Service count | `.agent/services/` + service `.md` files |
-| Script count | `ls .agent/scripts/*.sh \| wc -l` |
-| MCP integrations | `configs/` directory |
-| Workflows | `.agent/workflows/` directory |
-| Agent structure | `.agent/AGENTS.md` |
-
-### Common Update Triggers
-
-1. **New release** - Update version in `Home.md`
-2. **New service integration** - Update `Providers.md`, `MCP-Integrations.md`
-3. **New workflow** - Update `Workflows-Guide.md`
-4. **Architecture changes** - Update `The-Agent-Directory.md`
-5. **Setup changes** - Update `Getting-Started.md`
-
-## Step 4: Update Wiki Pages
-
-### Page-Specific Guidelines
-
-#### Home.md
-
-- Keep concise - this is the landing page
-- Update version number prominently
-- Maintain quick start simplicity
-- Link to detailed pages, don't duplicate content
-
-#### Getting-Started.md
-
-- Test all installation commands
-- Verify directory paths are correct
-- Ensure example conversations are realistic
-- Keep prerequisites current
-
-#### The-Agent-Directory.md
-
-- Reflect actual directory structure
-- Update script counts
-- Document new subdirectories
-- Keep file conventions accurate
-
-#### MCP-Integrations.md
-
-- List all MCP servers from `configs/`
-- Include configuration snippets
-- Document required environment variables
-- Note any setup prerequisites
-
-#### Workflows-Guide.md
-
-- List all workflows from `.agent/workflows/`
-- Brief description of each
-- Link to detailed workflow files
-
-### Writing Style
-
-- Use tables for structured information
-- Keep paragraphs short (2-3 sentences)
-- Include practical examples
-- Avoid jargon - explain technical terms
-- Use consistent formatting
-
-## Step 5: Validate Changes
-
-### Pre-Commit Checks
-
-```bash
-# Validate markdown formatting
-.agent/scripts/markdown-formatter.sh lint .wiki/
-
-# Check for broken internal links
-# (wiki links use format: [Text](Page-Name))
-
-# Verify version consistency
-.agent/scripts/version-manager.sh validate
-```
-
-### Content Validation
-
-- [ ] All code examples are syntactically correct
-- [ ] All file paths exist in the repository
-- [ ] All links resolve correctly
-- [ ] Version numbers are consistent
-- [ ] No placeholder text remains
-
-## Step 6: Commit and Sync
-
-### Commit Changes
-
-```bash
-git add .wiki/
-git commit -m "docs(wiki): update wiki for v{VERSION}
-
-- Updated version references
-- Added new service integrations
-- Refreshed workflow documentation"
-```
-
-### Automatic Sync
-
-Pushing to `main` with changes in `.wiki/` triggers `.github/workflows/sync-wiki.yml`:
-
-1. Clones the wiki repository
-2. Copies `.wiki/` contents
-3. Commits and pushes to wiki
-
-No manual wiki editing needed - all changes go through `.wiki/` directory.
-
-## Example: Full Wiki Update
-
-```bash
-# 1. Get current version
-cat VERSION
-# Output: 2.0.0
-
-# 2. Count current resources
-echo "Scripts: $(ls .agent/scripts/*.sh 2>/dev/null | wc -l)"
-echo "Services: $(ls .agent/services/**/*.md 2>/dev/null | wc -l)"
-echo "Workflows: $(ls .agent/workflows/*.md 2>/dev/null | wc -l)"
-
-# 3. Build context (using Augment Context Engine)
-# "Summarize all changes since the last wiki update"
-
-# 4. Update wiki pages as needed
-
-# 5. Validate
-.agent/scripts/markdown-formatter.sh lint .wiki/
-
-# 6. Commit
-git add .wiki/
-git commit -m "docs(wiki): sync wiki with v2.0.0 release"
-git push origin main
-```
-
-## Quick Examples for Users
-
-### Example 1: Check Available Services
-
-```text
-User: "What hosting services does aidevops support?"
-
-AI reads .wiki/Providers.md and responds with the list of hosting
-providers: Hostinger, Hetzner, Cloudflare, Vercel, Coolify, etc.
-```
-
-### Example 2: Get Started Quickly
-
-```text
-User: "How do I set up aidevops?"
-
-AI reads .wiki/Getting-Started.md and provides:
-1. Clone command
-2. Setup instructions
-3. First steps with AI assistant
-```
-
-### Example 3: Understand the Structure
-
-```text
-User: "What's in the .agent directory?"
-
-AI reads .wiki/The-Agent-Directory.md and explains:
-- scripts/ - 90+ automation helpers
-- workflows/ - development process guides
-- memory/ - context persistence
-- *.md - service documentation
-```
-
-## Troubleshooting
-
-### Wiki Not Syncing
-
-1. Check GitHub Actions workflow status
-2. Verify `.wiki/` changes are committed
-3. Ensure workflow has write permissions
-4. Check for merge conflicts in wiki repo
-
-### Broken Links
-
-Wiki links use GitHub wiki format:
-
-```markdown
-# Correct
-[Getting Started](Getting-Started)
-
-# Incorrect
-[Getting Started](Getting-Started.md)
-[Getting Started](./Getting-Started.md)
-```
-
-### Version Mismatch
-
-```bash
-# Check all version references
-rg "v[0-9]+\.[0-9]+\.[0-9]+" .wiki/
-
-# Update to match VERSION file
-VERSION=$(cat VERSION)
-# Then update .wiki/Home.md
-```
-
-## Related Documentation
-
-- `repomix-instruction.md` - Codebase context instructions
-- `.agent/tools/context/augment-context-engine.md` - Augment setup
-- `.agent/tools/context/context-builder.md` - Repomix wrapper
-- `.github/workflows/sync-wiki.yml` - Auto-sync workflow