aidevops 2.52.1 → 2.53.2

package/.agent/workflows/git-workflow.md

@@ -1,702 +0,0 @@
----
-description: Master git workflow orchestrator - read when coding work begins
-mode: subagent
-tools:
-  read: true
-  write: false
-  edit: false
-  bash: true
-  glob: true
-  grep: true
-  webfetch: false
-  task: true
----
-
-# Git Workflow Orchestrator
-
-<!-- AI-CONTEXT-START -->
-
-## Quick Reference
-
-- **Purpose**: Ensure safe, traceable git workflow for all file changes
-- **Trigger**: Read this when conversation indicates file creation/modification in a git repo
-- **Principle**: Every change on a branch, never directly on main
-- **CRITICAL**: With parallel sessions, ALWAYS verify branch state before ANY file operation
-
-**Pre-Edit Gate** (MANDATORY before ANY file edit/write/create):
-
-```bash
-git branch --show-current  # If result is `main` → STOP
-```
-
-If on `main`: STOP. Present branch options before proceeding with any file changes.
-
-**First Actions** (before any code changes):
-
-```bash
-# 1. Check current branch (PRE-EDIT GATE)
-git branch --show-current
-# If on main → STOP and create branch first
-
-# 2. Check repo ownership
-git remote -v | head -1
-
-# 3. Check for uncommitted work
-git status --short
-
-# 4. Check for remote updates (parallel session safety)
-git fetch origin
-git log --oneline HEAD..origin/$(git branch --show-current) 2>/dev/null
-```
-
-**Parallel Session Safety**:
-
-When running multiple OpenCode sessions on the same repo:
-
-| Situation | Action |
-|-----------|--------|
-| Remote has new commits | Pull/rebase before continuing |
-| Uncommitted local changes | Stash or commit before switching |
-| Different session on same branch | Coordinate or use separate branches |
-| Starting new work | Always create a new branch first |
-| **Multiple parallel sessions** | **Use git worktrees** (see below) |
-
-**Git Worktrees for Parallel Work** (DEFAULT):
-
-**Core principle**: The main repo directory (`~/Git/{repo}/`) should ALWAYS stay on `main`. All feature work happens in worktree directories.
-
-```bash
-# Create separate working directory for a branch
-~/.aidevops/agents/scripts/worktree-helper.sh add feature/my-feature
-# Creates: ~/Git/{repo}-feature-my-feature/
-
-# List all worktrees
-~/.aidevops/agents/scripts/worktree-helper.sh list
-
-# Each terminal/session works in its own directory
-# No branch switching affects other sessions
-```
-
-**Why this matters**: If the main repo is left on a feature branch, the next session inherits that state. This causes "local changes would be overwritten" errors and breaks parallel workflows.
-
-See `workflows/worktree.md` for full worktree workflow.
-
-**Session-Branch Tracking**:
-
-OpenCode auto-generates session titles from the first prompt. To sync session names with branches:
-
-| Tool/Command | Purpose |
-|--------------|---------|
-| `session-rename_sync_branch` | **AI tool**: Auto-sync session name with current git branch |
-| `session-rename` | **AI tool**: Set custom session title |
-| `/sync-branch` | **Slash command**: Rename session to match current git branch |
-| `/rename feature/xyz` | **Slash command**: Rename session to any title |
-| `/sessions` (Ctrl+x l) | List all sessions by name |
-
-| Workflow | How to Track |
-|----------|--------------|
-| **New session, known work** | Start with: `opencode --title "feature/my-feature"` |
-| **Existing session, new branch** | Call `session-rename_sync_branch` tool after creating branch |
-| **Multiple sessions** | Each session named after its branch |
-| **Resume work** | `opencode -c` continues last session, or `-s <id>` for specific |
-
-**Best Practice**: After creating a branch, call `session-rename_sync_branch` tool to sync session name.
-
-**Scope Monitoring** (during session):
-
-When work evolves significantly from the branch name/purpose:
-
-| Signal | Example | Action |
-|--------|---------|--------|
-| Different feature area | Branch is `chore/update-deps`, now adding new API endpoint | Suggest new branch |
-| Unrelated bug fix | Branch is `feature/user-auth`, found unrelated CSS bug | Suggest separate branch |
-| Scope expansion | Branch is `bugfix/login-timeout`, now refactoring entire auth system | Suggest `refactor/` branch |
-| Command/API rename | Branch is `chore/optimize-X`, now renaming unrelated commands | Suggest new branch |
-
-**When detected**, proactively offer:
-
-> This work (`{description}`) seems outside the scope of `{current-branch}` ({original-purpose}).
->
-> 1. Create new branch `{suggested-type}/{suggested-name}` (recommended)
-> 2. Continue on current branch (if intentionally expanding scope)
-> 3. Stash changes and switch to existing branch
-
-**Stash workflow** (if user chooses option 1 or 3):
-
-```bash
-git stash --include-untracked -m "WIP: {description}"
-git checkout main && git pull origin main
-git checkout -b {type}/{description}
-git stash pop
-```
-
-**Self-check trigger**: Before each file edit, briefly consider: "Does this change align with `{branch-name}`?"
-
-**Decision Tree**:
-
-| Situation | Action |
-|-----------|--------|
-| On `main` branch | Suggest branch creation (see below) |
-| On feature/bugfix branch | Continue, follow `branch.md` lifecycle |
-| Issue URL pasted | Parse and create appropriate branch |
-| Non-owner repo | Fork workflow (see `pr.md`) |
-| New empty repo | Initialize with `main`, suggest `release/0.1.0` |
-
-<!-- AI-CONTEXT-END -->
-
-## Time Tracking Integration
-
-When creating branches, record the `started:` timestamp in TODO.md or PLANS.md:
-
-### Recording Start Time
-
-After creating a branch, update the corresponding task in TODO.md:
-
-```bash
-# Find the task and add started: timestamp
-# Before: - [ ] Add Ahrefs MCP server #seo ~4h
-# After:  - [ ] Add Ahrefs MCP server #seo ~4h started:2025-01-15T10:30Z
-```
-
-For PLANS.md entries, update the plan's status section:
-
-```markdown
-### [2025-01-15] User Authentication Overhaul
-**Status:** In Progress
-**Started:** 2025-01-15T10:30Z
-**Branch:** feature/user-auth-overhaul
-```
-
-### Time Tracking Workflow
-
-| Event | Action | Field Updated |
-|-------|--------|---------------|
-| Branch created | Record start time | `started:` |
-| Work session ends | Log time spent | `logged:` (cumulative) |
-| PR merged | Record completion | `completed:` |
-| Release published | Calculate actual | `actual:` |
-
-See `workflows/plans.md` for full time tracking format.
-
-## Branch Naming from TODO.md and PLANS.md
-
-When creating branches, derive names from planning files when available:
-
-### Check Planning Files First
-
-```bash
-# Check TODO.md for matching task
-grep -i "{keyword}" TODO.md
-
-# Check PLANS.md for matching plan
-grep -i "{keyword}" todo/PLANS.md
-
-# Check for PRD/tasks files
-ls todo/tasks/*{keyword}* 2>/dev/null
-```
-
-### Branch Name Derivation
-
-| Source | Branch Name Pattern | Example |
-|--------|---------------------|---------|
-| TODO.md task | `{type}/{slugified-description}` | `feature/add-ahrefs-mcp-server` |
-| PLANS.md entry | `{type}/{plan-slug}` | `feature/user-authentication-overhaul` |
-| PRD file | `{type}/{prd-feature-name}` | `feature/export-csv` |
-| Multiple tasks | `{type}/{summary-slug}` | `feature/seo-improvements` |
-
-### Slugification Rules
-
-- Lowercase all text
-- Replace spaces with hyphens
-- Remove special characters except hyphens
-- Truncate to ~50 chars if needed
-- Remove common words (the, a, an) if too long
-
-**Examples:**
-
-| Task/Plan | Generated Branch |
-|-----------|------------------|
-| `- [ ] Add Ahrefs MCP server integration #seo` | `feature/add-ahrefs-mcp-server` |
-| `- [ ] Fix login timeout bug #auth` | `bugfix/fix-login-timeout` |
-| `### [2025-01-15] User Authentication Overhaul` | `feature/user-authentication-overhaul` |
-| `prd-export-csv.md` | `feature/export-csv` |
-
-## Core Principle: Branch-First Development
-
-Every code change should happen on a branch, enabling:
-
-- **Safe parallel work** - Multiple developers without conflicts
-- **Full traceability** - Every change linked to branch → PR → merge
-- **Easy rollback** - Revert branches without affecting main
-- **Code review** - PRs enable review before merge
-- **Blame history** - Track who did what, when, and why
-
-## Conversation Start: Git Context Check
-
-When a conversation indicates file work will happen (code, docs, config, assets, etc.):
-
-### Step 1: Detect Git Context
-
-```bash
-# Check if in a git repo
-git rev-parse --is-inside-work-tree 2>/dev/null || echo "NOT_GIT_REPO"
-
-# Get current branch
-git branch --show-current
-
-# Get repo root
-git rev-parse --show-toplevel
-```
-
-### Step 2: Check for Existing Branches
-
-Before suggesting a new branch, check for existing work that might match:
-
-```bash
-# List work-in-progress branches
-git branch -a | grep -E "(feature|bugfix|hotfix|refactor|chore|experiment|release)/"
-
-# Check for uncommitted changes
-git status --short
-```
-
-### Step 3: Check Planning Files
-
-Before suggesting branch names, check for matching tasks/plans:
-
-```bash
-# Check TODO.md In Progress section
-grep -A 20 "## In Progress" TODO.md | grep "^\- \[ \]"
-
-# Check TODO.md Backlog for matching work
-grep -i "{user_request_keywords}" TODO.md
-
-# Check PLANS.md for active plans
-grep -A 5 "^### \[" todo/PLANS.md | grep -i "{user_request_keywords}"
-```
-
-### Step 4: Auto-Select with Override Options
-
-**If on `main` branch**, auto-select best match and offer override:
-
-> On `main`. Creating worktree for `feature/{best-match-name}` (from {source}).
->
-> [Enter] to confirm, or:
-> 1. Use different name
-> 2. Continue on `main` (docs-only, not recommended for code)
-
-Where `{source}` is one of:
-- "TODO.md" - matched a task
-- "PLANS.md" - matched an active plan
-- "your request" - derived from conversation
-
-**Note**: Always use worktrees, not `git checkout -b`. The main repo directory must stay on `main`.
-
-**If existing branch matches**, auto-select it:
-
-> Found existing branch: `feature/user-auth` (3 days old, 5 commits ahead)
->
-> [Enter] to continue on this branch, or:
-> 1. Create new branch instead
-> 2. Use different existing branch
-
-**If already on a work branch**, just continue:
-
-> Continuing on `feature/user-auth`.
-
-### User Response Handling
-
-- **Number**: Execute that option
-- **"yes"/"y"**: Execute option 1 (default/recommended)
-- **Custom text**: Interpret as branch name or clarification
-
-## Issue URL Handling
-
-When user pastes a GitHub/GitLab/Gitea issue URL:
-
-### Supported URL Patterns
-
-| Platform | Pattern | Example |
-|----------|---------|---------|
-| GitHub | `github.com/{owner}/{repo}/issues/{num}` | `https://github.com/user/repo/issues/123` |
-| GitLab | `gitlab.com/{owner}/{repo}/-/issues/{num}` | `https://gitlab.com/user/repo/-/issues/45` |
-| Gitea | `{domain}/{owner}/{repo}/issues/{num}` | `https://git.example.com/user/repo/issues/67` |
-| Self-hosted | `git.{domain}/*` or `git*.{domain}/*` | `https://git.company.com/team/project/issues/89` |
-
-### Issue Workflow
-
-```bash
-# 1. Parse URL to extract: platform, owner, repo, issue_number
-# Example: https://github.com/acme/widget/issues/42
-
-# 2. Check if repo exists locally
-REPO_PATH=~/Git/{repo}
-if [[ -d "$REPO_PATH" ]]; then
-    cd "$REPO_PATH"
-    git fetch origin
-else
-    # Clone to ~/Git/{repo}
-    gh repo clone {owner}/{repo} "$REPO_PATH"  # GitHub
-    # glab repo clone {owner}/{repo} "$REPO_PATH"  # GitLab
-    cd "$REPO_PATH"
-fi
-
-# 3. Determine branch type from issue
-# - "bug" label → bugfix/
-# - "feature"/"enhancement" label → feature/
-# - Default → feature/
-
-# 4. Create branch
-git checkout main && git pull origin main
-git checkout -b {type}/{issue_number}-{slug-from-title}
-# Example: feature/42-add-user-dashboard
-
-# 5. Inform user
-echo "Created branch {type}/{issue_number}-{slug} linked to issue #{issue_number}"
-```
-
-### Platform Detection
-
-```bash
-# Detect platform from URL
-detect_git_platform() {
-    local url="$1"
-    if [[ "$url" == *"github.com"* ]]; then
-        echo "github"
-    elif [[ "$url" == *"gitlab.com"* ]]; then
-        echo "gitlab"
-    elif [[ "$url" == *"gitea"* ]] || [[ "$url" == *"/issues/"* ]]; then
-        # Check if it's a Gitea instance
-        echo "gitea"
-    else
-        # Self-hosted - try to detect
-        echo "unknown"
-    fi
-}
-```
-
-## Repository Ownership Check
-
-Before pushing or creating PRs, check ownership:
-
-```bash
-# Get remote URL
-REMOTE_URL=$(git remote get-url origin)
-
-# Extract owner from URL
-# GitHub: git@github.com:owner/repo.git or https://github.com/owner/repo.git
-REPO_OWNER=$(echo "$REMOTE_URL" | sed -E 's/.*[:/]([^/]+)\/[^/]+\.git$/\1/')
-
-# Get current user
-CURRENT_USER=$(gh api user --jq '.login')  # GitHub
-# CURRENT_USER=$(glab api user --jq '.username')  # GitLab
-
-# Check if owner
-if [[ "$REPO_OWNER" != "$CURRENT_USER" ]]; then
-    echo "NON_OWNER: Fork workflow required"
-fi
-```
-
-**If non-owner**: See `workflows/pr.md` for fork workflow.
-
-## New Repository Initialization
-
-For new empty repositories:
-
-```bash
-# 1. Initialize with main branch
-git init
-git checkout -b main
-
-# 2. Create initial commit
-echo "# Project Name" > README.md
-git add README.md
-git commit -m "chore: initial commit"
-
-# 3. Suggest first release branch
-echo "Repository initialized. For your first version, create:"
-echo "  git checkout -b release/0.1.0"
-```
-
-### First Version Guidance
-
-| Project State | Suggested Version | Branch |
-|---------------|-------------------|--------|
-| New project, no features | 0.1.0 | `release/0.1.0` |
-| MVP ready | 1.0.0 | `release/1.0.0` |
-| Existing project, first aidevops use | Current + patch | `release/X.Y.Z` |
-
-## Branch Type Selection
-
-When creating a branch, determine type from conversation context:
-
-| If user mentions... | Branch Type | Example |
-|---------------------|-------------|---------|
-| "add", "new", "feature", "implement" | `feature/` | `feature/user-auth` |
-| "fix", "bug", "broken", "error" | `bugfix/` | `bugfix/login-timeout` |
-| "urgent", "critical", "production down" | `hotfix/` | `hotfix/security-patch` |
-| "refactor", "cleanup", "restructure" | `refactor/` | `refactor/api-cleanup` |
-| "docs", "readme", "documentation" | `chore/` | `chore/update-docs` |
-| "update deps", "config", "maintenance" | `chore/` | `chore/update-deps` |
-| "try", "experiment", "POC", "spike" | `experiment/` | `experiment/new-ui` |
-| "release", "version" | `release/` | `release/1.2.0` |
-
-See `workflows/branch.md` for naming conventions.
-
-## Workflow Lifecycle
-
-```text
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                         COMPLETE GIT WORKFLOW                                │
-├─────────────────────────────────────────────────────────────────────────────┤
-│                                                                              │
-│  1. CONVERSATION START                                                       │
-│     ├── Detect git repo context                                              │
-│     ├── Check current branch (warn if on main)                               │
-│     ├── Check for existing WIP branches                                      │
-│     └── Suggest/create appropriate branch                                    │
-│         └── See: workflows/branch.md                                         │
-│                                                                              │
-│  2. DEVELOPMENT                                                              │
-│     ├── Work on feature/bugfix/etc branch                                    │
-│     ├── Regular commits with conventional format                             │
-│     └── Keep branch updated with main                                        │
-│         └── See: workflows/branch.md                                         │
-│                                                                              │
-│  3. PREFLIGHT (before push)                                                  │
-│     ├── Run linters-local.sh                                                 │
-│     ├── Validate code quality                                                │
-│     └── Check for secrets                                                    │
-│         └── See: workflows/preflight.md                                      │
-│                                                                              │
-│  4. PUSH & PR                                                                │
-│     ├── Push branch to origin (or fork if non-owner)                         │
-│     ├── Create PR/MR                                                         │
-│     └── Run code-audit-remote                                                │
-│         └── See: workflows/pr.md                                             │
-│                                                                              │
-│  5. REVIEW & MERGE                                                           │
-│     ├── Address review feedback                                              │
-│     ├── Squash merge to main                                                 │
-│     └── Delete feature branch                                                │
-│         └── See: workflows/pr.md                                             │
-│                                                                              │
-│  6. RELEASE PREPARATION (when ready)                                         │
-│     ├── Create release/X.Y.Z branch                                          │
-│     ├── Select branches to include                                           │
-│     ├── Update version files                                                 │
-│     └── Generate changelog                                                   │
-│         └── See: workflows/version-bump.md                                   │
-│                                                                              │
-│  7. RELEASE                                                                  │
-│     ├── Merge release branch to main                                         │
-│     ├── Tag main with vX.Y.Z                                                 │
-│     ├── Create GitHub/GitLab release                                         │
-│     └── Delete release branch                                                │
-│         └── See: workflows/release.md                                        │
-│                                                                              │
-│  8. POSTFLIGHT                                                               │
-│     ├── Verify CI/CD passes                                                  │
-│     ├── Check quality gates                                                  │
-│     └── Offer cleanup of merged branches                                     │
-│         └── See: workflows/postflight.md                                     │
-│                                                                              │
-│  9. CLEANUP                                                                  │
-│     ├── Delete merged branches (local + remote)                              │
-│     ├── Prune stale remote refs                                              │
-│     └── Update local main                                                    │
-│                                                                              │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-## Post-Change Workflow
-
-After completing file changes, run preflight automatically:
-
-> Running preflight checks...
-
-**If preflight passes**, auto-commit with suggested message:
-
-> Preflight passed. Committing: "{suggested message}"
->
-> [Enter] to confirm, or:
-> 1. Use different message
-> 2. Make more changes first
-
-**If preflight fails**, show issues and offer fixes:
-
-> Preflight found {N} issues:
-> - {issue 1}
-> - {issue 2}
->
-> 1. Fix automatically (if possible)
-> 2. View detailed report
-> 3. Skip and commit anyway (not recommended)
-
-**After successful commit**, auto-push if on a branch:
-
-> Committed and pushed to `{branch}`.
->
-> 1. Create PR
-> 2. Continue working
-> 3. Done for now
-
-**If changes include `.agent/` files** (in aidevops repo or repos with local agents):
-
-> Agent files modified. Run `./setup.sh` to deploy to `~/.aidevops/agents/`?
->
-> 1. Run setup.sh now (recommended)
-> 2. Remind me after merge
-> 3. Skip (I'll do it manually)
-
-This ensures the deployed agents at `~/.aidevops/agents/` stay in sync with source.
-
-## Branch Cleanup
-
-After merge and successful postflight:
-
-```bash
-# 1. Switch to main and update
-git checkout main
-git pull origin main
-
-# 2. List merged branches
-git branch --merged main | grep -vE "^\*|main|develop"
-
-# 3. Delete merged branches (with confirmation)
-# For each branch:
-git branch -d {branch-name}           # Local
-git push origin --delete {branch-name} # Remote (if not auto-deleted)
-
-# 4. Prune stale remote refs
-git remote prune origin
-```
-
-### Cleanup Decision Tree
-
-| Branch State | Action |
-|--------------|--------|
-| Merged + postflight passed | Safe to delete |
-| Merged + postflight failed | Keep, may need hotfix |
-| Unmerged + stale (>30 days) | Ask user about status |
-| Unmerged + active | Keep |
-
-## User Experience Levels
-
-These workflows support all skill levels:
-
-### New Developers (Vibe-Coders)
-
-- AI handles branch creation automatically
-- Clear explanations of why branching matters
-- Guided through PR process
-- Protected from common mistakes
-
-### Experienced Developers
-
-- Can override suggestions when needed
-- Familiar patterns (GitFlow-inspired)
-- Efficient commands without excessive prompts
-- Full control when requested
-
-### Team Collaboration
-
-- Consistent branch naming across team
-- Clear PR descriptions for reviewers
-- Traceable history for debugging
-- Easy handoff between developers
-
-## Override Handling
-
-When user wants to work directly on main:
-
-```text
-User: "Just make the change on main, I know what I'm doing"
-
-AI: "Understood. I'll proceed on main. Note that without a branch:
-- Changes are harder to rollback
-- No PR review before merge
-- Harder to collaborate or get help
-
-Proceeding with changes on main..."
-```
-
-**Never block** the user - these are guidelines, not restrictions.
-
-## Database Schema Changes
-
-When changes include database schema modifications:
-
-### Detection
-
-Look for:
-- Files in `schemas/` (declarative schema files)
-- Files in `migrations/`, `database/migrations/`, or similar
-- SQL files with schema changes (`CREATE TABLE`, `ALTER TABLE`, etc.)
-- ORM schema files (Drizzle `.ts`, Prisma `.prisma`, etc.)
-
-### Declarative Schema Workflow (Recommended)
-
-When `schemas/` directory exists (created by `aidevops init database`):
-
-1. **Edit schema files** in `schemas/`
-2. **Generate migration** via diff command:
-   - Supabase: `supabase db diff -f description`
-   - Drizzle: `npx drizzle-kit generate`
-   - Atlas: `atlas migrate diff description`
-   - Prisma: `npx prisma migrate dev --name description`
-3. **Review generated migration** in `migrations/`
-4. **Apply migration** locally
-5. **Commit both** schema and migration files together
-
-### Branch Naming for Migrations
-
-| Change Type | Branch | Example |
-|-------------|--------|---------|
-| New table | `feature/` | `feature/add-user-preferences-table` |
-| Schema fix | `bugfix/` | `bugfix/fix-orders-foreign-key` |
-| Data backfill | `chore/` | `chore/backfill-user-status` |
-
-### Pre-Push Checklist for Migrations
-
-Before pushing migration files:
-
-1. ✅ Schema file updated (if using declarative approach)
-2. ✅ Migration generated via diff (not written manually)
-3. ✅ Migration reviewed for unexpected changes
-4. ✅ Tested locally (apply, rollback, apply again)
-5. ✅ No modifications to already-pushed migrations
-6. ✅ Timestamp is current (regenerate if rebasing)
-
-### Critical Rules
-
-- **NEVER modify migrations that have been pushed/deployed.** Create a new migration to fix issues.
-- **ALWAYS commit schema and migration files together** to keep them in sync.
-- **ALWAYS review generated migrations** before committing.
-
-See `workflows/sql-migrations.md` for full migration workflow.
-
-## Related Workflows
-
-| Workflow | When to Read |
-|----------|--------------|
-| `branch.md` | Branch naming, creation, lifecycle |
-| `branch/release.md` | Release branch specifics |
-| `pr.md` | PR creation, review, merge, fork workflow |
-| `preflight.md` | Quality checks before push |
-| `postflight.md` | Verification after release |
-| `version-bump.md` | Version management, release branches |
-| `release.md` | Full release process |
-| `feature-development.md` | Feature implementation patterns |
-| `bug-fixing.md` | Bug fix patterns |
-| `sql-migrations.md` | Database schema version control |
-
-## Platform CLI Reference
-
-| Platform | CLI | Branch | PR | Release |
-|----------|-----|--------|-----|---------|
-| GitHub | `gh` | `git checkout -b` | `gh pr create` | `gh release create` |
-| GitLab | `glab` | `git checkout -b` | `glab mr create` | `glab release create` |
-| Gitea | `tea` | `git checkout -b` | `tea pulls create` | `tea releases create` |
-
-See `tools/git.md` for detailed CLI usage.