@sugar-crash-studios/vibe-forge 0.4.0

package/docs/workflows/README.md

@@ -0,0 +1,32 @@
+# VCS Workflow Guides
+
+Platform-specific workflow guidance for Vibe Forge agents. The appropriate guide is selected based on the project's VCS configuration (see `/configure-vcs`).
+
+## Available Guides
+
+| Platform | File | Use Case |
+|----------|------|----------|
+| [GitHub](./github.md) | `github.md` | GitHub with Actions CI |
+| [GitLab](./gitlab.md) | `gitlab.md` | GitLab with GitLab CI |
+| [Gitea](./gitea.md) | `gitea.md` | Gitea/Codeberg with Gitea Actions |
+| [Azure DevOps](./azure-devops.md) | `azure-devops.md` | Azure DevOps with Pipelines |
+| [Bitbucket](./bitbucket.md) | `bitbucket.md` | Bitbucket with Pipelines |
+| [Git Only](./git-only.md) | `git-only.md` | Git without hosted platform |
+
+## Configuration
+
+VCS type is set during `forge init` or via `/configure-vcs`. Configuration stored in `.forge/config.json`:
+
+```json
+{
+  "vcs": {
+    "type": "github",
+    "name": "GitHub",
+    "autoDetected": true
+  }
+}
+```
+
+## Agent Integration
+
+Agents read the VCS configuration and reference the appropriate workflow guide. The git workflow section in agent personalities is dynamically adjusted based on the configured platform.

package/docs/workflows/azure-devops.md

@@ -0,0 +1,108 @@
+# Azure DevOps Workflow Guide
+
+Git workflow guidance for projects hosted on Azure DevOps.
+
+## Branch Naming
+
+```
+task/TASK-XXX-description     # Task branches
+feature/feature-name          # Feature branches
+bugfix/bug-description        # Bug fix branches
+hotfix/urgent-fix             # Urgent production fixes
+```
+
+## Daily Workflow
+
+### Starting a Task
+
+```bash
+# Ensure you're on latest main
+git checkout main && git pull origin main
+
+# Create feature branch
+git checkout -b task/TASK-XXX-description
+```
+
+### During Development
+
+```bash
+# Stage and commit changes
+git add .
+git commit -m "Add feature X"
+
+# Push to remote (first time)
+git push -u origin task/TASK-XXX-description
+
+# Subsequent pushes
+git push
+```
+
+### Creating a Pull Request
+
+```bash
+# Using Azure CLI
+az repos pr create \
+  --title "TASK-XXX: Add feature X" \
+  --description "Description of changes" \
+  --source-branch task/TASK-XXX-description \
+  --target-branch main
+
+# Set to draft
+az repos pr create --draft \
+  --title "TASK-XXX: WIP - Add feature X" \
+  --source-branch task/TASK-XXX-description
+```
+
+### After PR Approval
+
+```bash
+# Complete PR via Azure CLI
+az repos pr update --id <pr-id> --status completed
+
+# Clean up local branch
+git checkout main
+git pull origin main
+git branch -d task/TASK-XXX-description
+```
+
+## CI/CD
+
+Azure Pipelines configuration goes in `azure-pipelines.yml`:
+
+```yaml
+# azure-pipelines.yml
+trigger:
+  - main
+
+pool:
+  vmImage: 'ubuntu-latest'
+
+steps:
+  - task: NodeTool@0
+    inputs:
+      versionSpec: '20.x'
+
+  - script: npm ci
+    displayName: 'Install dependencies'
+
+  - script: npm test
+    displayName: 'Run tests'
+```
+
+## Useful Commands
+
+```bash
+# Azure CLI for repos
+az repos pr list                    # List open PRs
+az repos pr show --id 123           # Show PR details
+az repos pr checkout --id 123       # Checkout PR locally
+az pipelines run list               # List pipeline runs
+```
+
+## Branch Policies
+
+Configure in Repos > Branches > Branch policies:
+- Require minimum number of reviewers
+- Check for linked work items
+- Build validation
+- Require merge strategy (squash)

package/docs/workflows/bitbucket.md

@@ -0,0 +1,104 @@
+# Bitbucket Workflow Guide
+
+Git workflow guidance for projects hosted on Bitbucket.
+
+## Branch Naming
+
+```
+task/TASK-XXX-description     # Task branches
+feature/feature-name          # Feature branches
+bugfix/bug-description        # Bug fix branches
+hotfix/urgent-fix             # Urgent production fixes
+```
+
+## Daily Workflow
+
+### Starting a Task
+
+```bash
+# Ensure you're on latest main
+git checkout main && git pull origin main
+
+# Create feature branch
+git checkout -b task/TASK-XXX-description
+```
+
+### During Development
+
+```bash
+# Stage and commit changes
+git add .
+git commit -m "Add feature X"
+
+# Push to remote (first time)
+git push -u origin task/TASK-XXX-description
+
+# Subsequent pushes
+git push
+```
+
+### Creating a Pull Request
+
+Bitbucket doesn't have an official CLI. Create PRs via:
+
+1. **Web UI**: After pushing, visit Bitbucket and click "Create pull request"
+2. **API** (if needed):
+   ```bash
+   curl -X POST \
+     -H "Authorization: Bearer $BITBUCKET_TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"title":"TASK-XXX: Add feature X","source":{"branch":{"name":"task/TASK-XXX-description"}},"destination":{"branch":{"name":"main"}}}' \
+     https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/pullrequests
+   ```
+
+### After PR Approval
+
+```bash
+# Merge via Bitbucket UI (squash merge recommended)
+
+# Clean up local branch
+git checkout main
+git pull origin main
+git branch -d task/TASK-XXX-description
+```
+
+## CI/CD
+
+Bitbucket Pipelines configuration goes in `bitbucket-pipelines.yml`:
+
+```yaml
+# bitbucket-pipelines.yml
+image: node:20
+
+pipelines:
+  default:
+    - step:
+        name: Test
+        caches:
+          - node
+        script:
+          - npm ci
+          - npm test
+
+  branches:
+    main:
+      - step:
+          name: Build and Deploy
+          script:
+            - npm ci
+            - npm run build
+```
+
+## Useful Tips
+
+- **Jira Integration**: Link commits with Jira issue keys (e.g., `PROJ-123`)
+- **PR Templates**: Create `PULL_REQUEST_TEMPLATE.md` in repo root
+- **Reviewers**: Set default reviewers in repository settings
+
+## Branch Permissions
+
+Configure in Repository settings > Branch permissions:
+- Require pull request before merging
+- Require approvals
+- Require passing builds
+- Prevent direct pushes to main

package/docs/workflows/git-only.md

@@ -0,0 +1,130 @@
+# Git-Only Workflow Guide
+
+Git workflow guidance for projects using Git without a hosted platform (self-hosted, local-only, or minimal setup).
+
+## Branch Naming
+
+```
+task/TASK-XXX-description     # Task branches
+feature/feature-name          # Feature branches
+bugfix/bug-description        # Bug fix branches
+hotfix/urgent-fix             # Urgent production fixes
+```
+
+## Daily Workflow
+
+### Starting a Task
+
+```bash
+# Ensure you're on latest main
+git checkout main
+git pull origin main  # if remote exists
+
+# Create feature branch
+git checkout -b task/TASK-XXX-description
+```
+
+### During Development
+
+```bash
+# Stage and commit changes
+git add .
+git commit -m "Add feature X"
+
+# Push to remote (if configured)
+git push -u origin task/TASK-XXX-description
+```
+
+### Completing a Task
+
+Without a PR platform, use one of these approaches:
+
+#### Option 1: Direct Merge (Solo Developer)
+
+```bash
+# Switch to main
+git checkout main
+git pull origin main  # if remote
+
+# Merge with squash
+git merge --squash task/TASK-XXX-description
+git commit -m "TASK-XXX: Add feature X"
+
+# Push
+git push origin main
+
+# Clean up
+git branch -d task/TASK-XXX-description
+```
+
+#### Option 2: Code Review via Diff
+
+```bash
+# Generate diff for review
+git diff main...task/TASK-XXX-description > review.patch
+
+# After review approval, merge as above
+```
+
+#### Option 3: Email Workflow
+
+```bash
+# Format patches for email review
+git format-patch main..task/TASK-XXX-description -o patches/
+
+# Apply approved patches
+git am patches/*.patch
+```
+
+## Local CI
+
+Without a hosted CI platform, consider:
+
+### Git Hooks
+
+```bash
+# .git/hooks/pre-commit
+#!/bin/bash
+npm test
+```
+
+### Manual CI Script
+
+```bash
+# scripts/ci.sh
+#!/bin/bash
+set -e
+npm ci
+npm run lint
+npm test
+npm run build
+echo "CI passed!"
+```
+
+## Useful Commands
+
+```bash
+# View branch history
+git log --oneline --graph main..HEAD
+
+# Interactive rebase before merge
+git rebase -i main
+
+# Diff summary
+git diff --stat main...HEAD
+
+# List branches
+git branch -a
+```
+
+## Best Practices
+
+1. **Commit Often**: Small, focused commits are easier to review and revert
+2. **Write Good Messages**: Include context for future reference
+3. **Rebase Before Merge**: Keep history clean with interactive rebase
+4. **Tag Releases**: Use semantic versioning tags
+
+```bash
+git tag -a v1.0.0 -m "Release version 1.0.0"
+git push origin v1.0.0
+```

package/docs/workflows/gitea.md

@@ -0,0 +1,168 @@
+# Gitea Workflow Guide
+
+Git workflow guidance for projects hosted on Gitea (including Codeberg and other Gitea-based instances).
+
+## Branch Naming
+
+```
+task/TASK-XXX-description     # Task branches
+feature/feature-name          # Feature branches
+bugfix/bug-description        # Bug fix branches
+hotfix/urgent-fix             # Urgent production fixes
+```
+
+## Daily Workflow
+
+### Starting a Task
+
+```bash
+# Ensure you're on latest main
+git checkout main && git pull origin main
+
+# Create feature branch
+git checkout -b task/TASK-XXX-description
+```
+
+### During Development
+
+```bash
+# Stage and commit changes
+git add .
+git commit -m "Add feature X"
+
+# Push to remote (first time)
+git push -u origin task/TASK-XXX-description
+
+# Subsequent pushes
+git push
+```
+
+### Creating a Pull Request
+
+```bash
+# Using tea CLI (Gitea's official CLI)
+tea pr create --title "TASK-XXX: Add feature X" --description "Description of changes"
+
+# Or create as draft
+tea pr create --title "TASK-XXX: WIP - Add feature X" --labels "work-in-progress"
+
+# If tea is not installed, use the web UI:
+# Navigate to your Gitea instance -> Repository -> Pull Requests -> New Pull Request
+```
+
+### After PR Approval
+
+```bash
+# Merge via Gitea UI (squash merge recommended)
+# Or via CLI
+tea pr merge --style squash
+
+# Clean up local branch
+git checkout main
+git pull origin main
+git branch -d task/TASK-XXX-description
+```
+
+## CI/CD with Gitea Actions
+
+Gitea Actions (v1.19+) uses GitHub Actions-compatible workflow syntax. Configuration goes in `.gitea/workflows/`:
+
+```yaml
+# .gitea/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - run: npm test
+```
+
+### Alternative: Drone CI
+
+Many Gitea installations use Drone CI. Configuration goes in `.drone.yml`:
+
+```yaml
+# .drone.yml
+kind: pipeline
+type: docker
+name: default
+
+steps:
+  - name: test
+    image: node:20
+    commands:
+      - npm ci
+      - npm test
+```
+
+## Installing tea CLI
+
+```bash
+# macOS
+brew install tea
+
+# Linux (download binary)
+curl -sL https://dl.gitea.io/tea/main/tea-main-linux-amd64 -o tea
+chmod +x tea
+sudo mv tea /usr/local/bin/
+
+# Windows (via scoop)
+scoop install tea
+```
+
+### Configure tea
+
+```bash
+# Add your Gitea instance
+tea login add --name myinstance --url https://gitea.example.com --token YOUR_TOKEN
+
+# Set as default
+tea login default myinstance
+```
+
+## Useful Commands
+
+```bash
+# tea CLI commands
+tea pr list                   # List open PRs
+tea pr view 123               # View PR details
+tea pr checkout 123           # Checkout PR locally
+tea issue list                # List issues
+tea repo list                 # List repositories
+
+# With specific login
+tea pr list --login myinstance
+```
+
+## Branch Protection
+
+Configure in Repository Settings > Branches > Branch Protection:
+- Enable branch protection for `main`
+- Require pull request reviews
+- Require status checks to pass
+- Block force push
+- Block branch deletion
+
+## Gitea vs GitHub Differences
+
+| Feature | GitHub | Gitea |
+|---------|--------|-------|
+| CLI | `gh` | `tea` |
+| CI | GitHub Actions | Gitea Actions / Drone |
+| Workflows | `.github/workflows/` | `.gitea/workflows/` |
+| PR Labels | Built-in | Instance-specific |
+
+## Self-Hosted Considerations
+
+- **Instance URL**: Replace `gitea.example.com` with your actual instance URL
+- **Runner Setup**: Gitea Actions requires act_runner for CI/CD
+- **Token Scopes**: Generate tokens with appropriate scopes in Settings > Applications
+- **Webhooks**: Configure webhooks for external CI if not using Gitea Actions

package/docs/workflows/github.md

@@ -0,0 +1,103 @@
+# GitHub Workflow Guide
+
+Git workflow guidance for projects hosted on GitHub.
+
+## Branch Naming
+
+```
+task/TASK-XXX-description     # Task branches
+feature/feature-name          # Feature branches
+bugfix/bug-description        # Bug fix branches
+hotfix/urgent-fix             # Urgent production fixes
+```
+
+## Daily Workflow
+
+### Starting a Task
+
+```bash
+# Ensure you're on latest main
+git checkout main && git pull origin main
+
+# Create feature branch
+git checkout -b task/TASK-XXX-description
+```
+
+### During Development
+
+```bash
+# Stage and commit changes
+git add .
+git commit -m "Add feature X"
+
+# Push to remote (first time)
+git push -u origin task/TASK-XXX-description
+
+# Subsequent pushes
+git push
+```
+
+### Creating a Pull Request
+
+```bash
+# Using GitHub CLI (recommended)
+gh pr create --title "TASK-XXX: Add feature X" --body "Description of changes"
+
+# Or with draft PR
+gh pr create --draft --title "TASK-XXX: WIP - Add feature X"
+```
+
+### After PR Approval
+
+```bash
+# Squash merge via GitHub UI or CLI
+gh pr merge --squash
+
+# Clean up local branch
+git checkout main
+git pull origin main
+git branch -d task/TASK-XXX-description
+```
+
+## CI/CD
+
+GitHub Actions configuration goes in `.github/workflows/`:
+
+```yaml
+# .github/workflows/ci.yml
+name: CI
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run tests
+        run: npm test
+```
+
+## Useful Commands
+
+```bash
+# Check PR status
+gh pr status
+
+# View PR in browser
+gh pr view --web
+
+# List open PRs
+gh pr list
+
+# Check CI status
+gh run list
+```
+
+## Branch Protection
+
+If on a paid plan, configure branch protection rules:
+- Require PR reviews before merging
+- Require status checks to pass
+- Require branches to be up to date
+
+For free plans, use the pre-push hook in `.githooks/pre-push`.