Skip to content

foryourhealth111-pixel/Vibe-Skills / bundled/skills/autonomous-builder

autonomous-builder

Flagged

Full-stack software development agent for design, implementation, testing, and deployment. Use when the user explicitly asks for end-to-end project creation, feature development, bug fixing, or code refactoring.

references/github-integration.md

View on GitHub
# GitHub Integration Reference

## Overview

The autonomous-builder skill integrates with GitHub to provide:
- Remote repository management with automatic push
- GitHub Issues tracking for feature implementation
- Release tags at project milestones
- Version rollback support via GitHub history

## Prerequisites

### 1. GitHub CLI Installation

**Windows**:
```bash
winget install GitHub.cli
```

**macOS**:
```bash
brew install gh
```

**Linux**:
```bash
# Debian/Ubuntu
sudo apt install gh

# Fedora/RHEL
sudo dnf install gh
```

### 2. Authentication

```bash
# Authenticate with GitHub
gh auth login

# Verify authentication
gh auth status
```

## Setup Process

### During Initialization (Session 1)

1. **Repository URL Prompt**:
   - You'll be prompted: "GitHub repository URL (leave empty to skip):"
   - Provide URL in format: `https://github.com/owner/repo`
   - Or leave empty to skip GitHub integration

2. **Authentication Check**:
   - Skill verifies `gh auth status`
   - If not authenticated, GitHub integration is disabled
   - You'll see: "GitHub CLI not authenticated. Run: gh auth login"

3. **Remote Setup**:
   - Adds remote: `git remote add origin <url>`
   - Verifies remote: `git remote -v`

4. **Initial Documentation**:
   - Creates `README.md` with project overview
   - Creates `PLANNING.md` with feature breakdown
   - Includes `.builder/` state files

5. **Initial Push**:
   - Commits all files
   - Pushes to GitHub: `git push -u origin main`

6. **GitHub Issues Creation**:
   - Creates one issue per feature
   - Labels: `feature`, `autonomous-builder`
   - Stores issue numbers in `features.json`

## Workflow Integration

### Initializer Agent (Session 1)

```
┌─────────────────────────────────────────┐
│ 1. Create project structure             │
│ 2. Generate features.json               │
│ 3. Initialize Git repository            │
│ 4. ✨ Prompt for GitHub URL             │
│ 5. ✨ Create README.md & PLANNING.md    │
│ 6. ✨ Initial commit and push           │
│ 7. ✨ Create GitHub issues              │
└─────────────────────────────────────────┘
```

### Builder Agent (Sessions 2+)

```
┌─────────────────────────────────────────┐
│ Step 1-7: Implement feature             │
│ Step 8: Git commit + GitHub push        │
│   ├─ Commit with issue reference        │
│   ├─ Push to GitHub (with retry)        │
│   ├─ Update issue status                │
│   └─ Check milestone & create tag       │
│ Step 9-10: Update progress & exit       │
└─────────────────────────────────────────┘
```

## Commit Message Format

### Standard Format

```
<type>: <subject>

<body>

Implementation:
<implementation summary>

Tests: <passed>/<total> passing

Closes #<issue_number>

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
```

### Types

- `feat`: New feature implementation
- `fix`: Bug fix
- `refactor`: Code refactoring
- `test`: Adding or updating tests
- `docs`: Documentation changes
- `chore`: Maintenance tasks

### Example

```
feat: Add user authentication with JWT

Implemented secure authentication system using JWT tokens.
Includes login, logout, and token refresh endpoints.

Implementation:
- Created auth middleware for route protection
- Added JWT token generation and validation
- Implemented password hashing with bcrypt
- Added comprehensive authentication tests

Tests: 12/12 passing

Closes #5

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
```

## Release Tag Strategy

### Milestone Thresholds

| Progress | Version | Milestone Name      |
|----------|---------|---------------------|
| 25%      | v0.1.0  | Foundation          |
| 50%      | v0.2.0  | Core Features       |
| 75%      | v0.3.0  | Advanced Features   |
| 100%     | v1.0.0  | Release             |

### Tag Creation Process

1. **Progress Calculation**:
   ```
   progress = completed_features / total_features
   ```

2. **Milestone Detection**:
   - Checks if progress >= threshold
   - Verifies tag not already created

3. **Tag Creation**:
   ```bash
   git tag -a v0.1.0 -m "Release v0.1.0

   Milestone: 25% completion

   Features completed: 5
   Total features: 20

   Generated by autonomous-builder"
   ```

4. **Push Tag**:
   ```bash
   git push origin v0.1.0
   ```

5. **GitHub Release**:
   ```bash
   gh release create v0.1.0 \
     --title "Release v0.1.0" \
     --notes "<release_notes>"
   ```

### Release Notes Format

```markdown
# Release v0.1.0

## What's New

- **User Authentication**: JWT-based authentication system (#5)
- **Database Setup**: PostgreSQL with migrations (#6)
- **API Foundation**: RESTful API structure with Express (#7)
- **Error Handling**: Centralized error handling middleware (#8)
- **Logging System**: Winston logger with rotation (#9)

## Statistics
- Features in this release: 5
- Total features completed: 5
- Tests passing: 45

---
*Generated by autonomous-builder*
```

## Error Handling

### Network Failures

**Retry Logic**:
```
Attempt 1: Push to GitHub
  ↓ (fails)
Wait 5 seconds
  ↓
Attempt 2: Push to GitHub
  ↓ (fails)
Wait 5 seconds
  ↓
Attempt 3: Push to GitHub
  ↓ (fails)
Add to pending_pushes queue
Continue with next feature
```

**Pending Push Recovery**:
- At start of next session, retry all pending pushes
- If successful, remove from queue
- If still failing, keep in queue for next session

**State Tracking**:
```json
{
  "github": {
    "pending_pushes": [
      {
        "commit": "abc123def456",
        "timestamp": "2026-02-14T10:30:00Z",
        "error": "Failed to connect to github.com"
      }
    ]
  }
}
```

### Authentication Failures

**Detection**:
```bash
gh auth status
# Exit code 1 = not authenticated
```

**Response**:
1. Disable GitHub integration for current session
2. Log warning message
3. Continue with local commits only
4. User can re-enable by running `gh auth login` and restarting

**State Tracking**:
```json
{
  "github": {
    "enabled": false,
    "auth_failure": {
      "timestamp": "2026-02-14T10:30:00Z",
      "message": "gh auth status failed"
    }
  }
}
```

### Push Conflicts

**Scenario**: Remote has commits not in local branch

**Resolution**:
```bash
# 1. Pull with rebase
git pull --rebase origin main

# 2. Retry push
git push origin main
```

**If Still Fails**:
- Log error with details
- Add to pending_pushes queue
- Continue with next feature

## Rollback Procedures

### Rollback to Previous Feature

```bash
# 1. View commit history
git log --oneline

# 2. Identify commit to rollback to
# Example: abc123 feat: Add user authentication

# 3. Reset to commit before feature
git reset --hard abc123^

# 4. Update state.json
# Edit .builder/state.json:
# - Move feature from "completed" to "pending"
# - Update current_feature to null
# - Update git.last_commit

# 5. Force push (if already pushed)
git push --force origin main

# 6. Reopen GitHub issue
gh issue reopen 5
```

### Rollback to Release Tag

```bash
# 1. List available tags
git tag -l

# 2. Checkout tag
git checkout v0.1.0

# 3. Create new branch from tag
git checkout -b rollback-to-v0.1.0

# 4. Restore .builder/ state from that commit
# The state.json at that commit reflects the correct state

# 5. Continue building from this point
# Run builder agent to continue
```

### Automated Rollback Script

Create `.builder/scripts/rollback.sh`:

```bash
#!/bin/bash

FEATURE_ID=$1

if [ -z "$FEATURE_ID" ]; then
    echo "Usage: ./rollback.sh <feature-id>"
    echo "Example: ./rollback.sh feat-005"
    exit 1
fi

# Find commit for feature
COMMIT=$(git log --grep="$FEATURE_ID" --format="%H" -n 1)

if [ -z "$COMMIT" ]; then
    echo "Feature $FEATURE_ID not found in git history"
    exit 1
fi

echo "Rolling back to commit $COMMIT (before $FEATURE_ID)"

# Reset to commit before feature
git reset --hard $COMMIT^

# Update state.json (requires jq)
jq ".features.completed |= map(select(. != \"$FEATURE_ID\"))" .builder/state.json > .builder/state.json.tmp
jq ".features.pending += [\"$FEATURE_ID\"]" .builder/state.json.tmp > .builder/state.json
rm .builder/state.json.tmp

echo "Rollback complete. Run builder to continue from this point."
echo "Note: You may need to force push: git push --force origin main"
```

## Migration Guide

### Adding GitHub to Existing Project

If you have an existing autonomous-builder project without GitHub integration:

1. **Create GitHub Repository**:
   ```bash
   # Option 1: Via gh CLI
   gh repo create my-project --public --source=. --remote=origin

   # Option 2: Via GitHub web UI, then:
   git remote add origin https://github.com/owner/repo.git
   ```

2. **Update state.json**:
   ```bash
   # Edit .builder/state.json
   # Add github object (see state-template.json for structure)
   ```

3. **Push Existing Commits**:
   ```bash
   git push -u origin main
   ```

4. **Create Issues for Pending Features**:
   ```bash
   # For each pending feature in features.json
   gh issue create \
     --title "feat: Feature Name" \
     --body "Description and acceptance criteria" \
     --label "feature,autonomous-builder"

   # Store issue number in features.json
   ```

5. **Resume Building**:
   - Builder will now push after each feature
   - Issues will be closed automatically
   - Release tags will be created at milestones

### Migration Script

Create `.builder/scripts/migrate_to_github.py`:

```python
#!/usr/bin/env python3
import json
import subprocess
import sys
from urllib.parse import urlparse

def run_command(cmd):
    """Run shell command and return output"""
    result = subprocess.run(cmd, shell=True, capture_output=True, text=True)
    if result.returncode != 0:
        raise Exception(f"Command failed: {cmd}\n{result.stderr}")
    return result.stdout.strip()

def extract_repo_info(url):
    """Extract owner and repo name from GitHub URL"""
    # https://github.com/owner/repo or git@github.com:owner/repo.git
    if url.startswith('https://'):
        parts = urlparse(url).path.strip('/').split('/')
        return parts[0], parts[1].replace('.git', '')
    elif url.startswith('git@'):
        parts = url.split(':')[1].strip('/').split('/')
        return parts[0], parts[1].replace('.git', '')
    else:
        raise ValueError(f"Invalid GitHub URL: {url}")

def migrate_to_github(repo_url):
    """Migrate existing project to GitHub"""

    print(f"Migrating to GitHub: {repo_url}")

    # 1. Load current state
    with open('.builder/state.json', 'r') as f:
        state = json.load(f)

    # 2. Extract repo info
    owner, repo_name = extract_repo_info(repo_url)

    # 3. Add GitHub fields
    state['github'] = {
        'enabled': True,
        'repository_url': repo_url,
        'repository_owner': owner,
        'repository_name': repo_name,
        'default_branch': 'main',
        'issue_tracking': True,
        'release_tagging': True,
        'last_push': None,
        'last_push_commit': None,
        'issues': {},
        'releases': [],
        'next_release': None,
        'pending_pushes': [],
        'push_failures': [],
        'auth_failure': None
    }

    # 4. Set up remote
    try:
        run_command(f'git remote add origin {repo_url}')
    except:
        print("Remote 'origin' already exists, updating URL...")
        run_command(f'git remote set-url origin {repo_url}')

    # 5. Push existing commits
    print("Pushing existing commits to GitHub...")
    run_command('git push -u origin main')

    # 6. Load features
    with open('.builder/features.json', 'r') as f:
        features_data = json.load(f)

    # 7. Create GitHub issues for pending features
    print("Creating GitHub issues for pending features...")
    for feature in features_data['features']:
        if feature['status'] in ['pending', 'in_progress']:
            # Create issue
            body = f"{feature['description']}\\n\\n"
            body += "**Acceptance Criteria:**\\n"
            for criterion in feature.get('acceptance_criteria', []):
                body += f"- {criterion}\\n"

            issue_cmd = f'gh issue create --title "feat: {feature["name"]}" --body "{body}" --label "feature,autonomous-builder"'
            issue_number = run_command(issue_cmd).split('/')[-1]

            # Store issue number
            feature['github_issue'] = int(issue_number)
            feature['github_issue_url'] = f"https://github.com/{owner}/{repo_name}/issues/{issue_number}"
            feature['github_issue_state'] = 'open'
            feature['github_commits'] = []

            state['github']['issues'][feature['id']] = int(issue_number)

            print(f"  Created issue #{issue_number} for {feature['id']}")

    # 8. Save updated files
    with open('.builder/state.json', 'w') as f:
        json.dump(state, f, indent=2)

    with open('.builder/features.json', 'w') as f:
        json.dump(features_data, f, indent=2)

    print("✅ Migration complete! GitHub integration enabled.")
    print(f"   Repository: {repo_url}")
    print(f"   Issues created: {len(state['github']['issues'])}")

if __name__ == '__main__':
    if len(sys.argv) != 2:
        print("Usage: python migrate_to_github.py <github-repo-url>")
        print("Example: python migrate_to_github.py https://github.com/owner/repo")
        sys.exit(1)

    migrate_to_github(sys.argv[1])
```

## Disabling GitHub Integration

### During Initialization

Simply leave the repository URL empty when prompted:

```
GitHub repository URL (leave empty to skip): [press Enter]
```

### For Existing Project

Edit `.builder/state.json`:

```json
{
  "github": {
    "enabled": false
  }
}
```

### Temporarily (One Session)

If GitHub operations fail (network, auth), integration is automatically disabled for that session. Local commits continue normally.

## State Schema Reference

### state.json - github Object

```json
{
  "github": {
    "enabled": true,
    "repository_url": "https://github.com/owner/repo",
    "repository_owner": "owner",
    "repository_name": "repo",
    "default_branch": "main",
    "issue_tracking": true,
    "release_tagging": true,
    "last_push": "2026-02-14T10:30:00Z",
    "last_push_commit": "abc123def456",
    "issues": {
      "feat-001": 123,
      "feat-002": 124
    },
    "releases": [
      {
        "version": "v0.1.0",
        "tag": "v0.1.0",
        "created_at": "2026-02-14T12:00:00Z",
        "commit": "abc123",
        "features_completed": 5
      }
    ],
    "next_release": {
      "version": "v0.2.0",
      "threshold": 0.5,
      "progress": 0.52
    },
    "pending_pushes": [],
    "push_failures": [],
    "auth_failure": null
  }
}
```

### features.json - GitHub Fields

```json
{
  "features": [
    {
      "id": "feat-001",
      "name": "Feature Name",
      "github_issue": 123,
      "github_issue_url": "https://github.com/owner/repo/issues/123",
      "github_issue_state": "closed",
      "github_commits": ["abc123", "def456"]
    }
  ]
}
```

## Troubleshooting

### Issue: "gh: command not found"

**Solution**: Install GitHub CLI (see Prerequisites section)

### Issue: "gh auth status" fails

**Solution**:
```bash
gh auth login
# Follow prompts to authenticate
```

### Issue: Push rejected (non-fast-forward)

**Solution**:
```bash
git pull --rebase origin main
git push origin main
```

### Issue: Issues not being created

**Check**:
1. `gh auth status` - Must be authenticated
2. Repository permissions - Must have write access
3. Repository URL - Must be correct in state.json

### Issue: Release tags not being created

**Check**:
1. `state.json → github.release_tagging` - Must be `true`
2. Progress calculation - Verify completed/total features
3. Existing tags - Check `git tag -l` for already created tags

## Best Practices

1. **Always authenticate before starting**:
   ```bash
   gh auth status
   ```

2. **Use descriptive commit messages**:
   - Follow the standard format
   - Include implementation details
   - Reference issue numbers

3. **Monitor pending pushes**:
   - Check `state.json → github.pending_pushes`
   - Retry manually if needed

4. **Regular backups**:
   - GitHub serves as remote backup
   - Tags provide recovery points

5. **Issue tracking**:
   - Use issues for feature planning
   - Link commits to issues
   - Close issues via commit messages

## Additional Resources

- [GitHub CLI Documentation](https://cli.github.com/manual/)
- [Git Tagging](https://git-scm.com/book/en/v2/Git-Basics-Tagging)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [GitHub Issues](https://docs.github.com/en/issues)
- [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github)
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall