foryourhealth111-pixel/Vibe-Skills / bundled/skills/autonomous-builder
autonomous-builder
FlaggedFull-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)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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: 198k | Updated | Claude CodeCodex | Verified | Install |