# External PR Guide

This guide explains how GitHub Actions workflows behave for external contributors (fork PRs).

## For External Contributors (Fork PRs)

When you submit a PR from a fork, workflows run but **cannot auto-commit fixes** due to GitHub security restrictions.

### What Runs Automatically

✅ **Registry Validation**
- Checks if `registry.json` matches actual files
- Validates all paths are correct
- Checks prompts use defaults
- **Cannot auto-commit** (you'll need to fix locally)

✅ **Agent Tests**
- OpenAgent and OpenCoder smoke tests run
- Results are reported in the PR

### What You Need to Do

If the validation workflow reports issues, you'll need to fix them locally:

#### 1. Registry Issues

If new components are detected:

```bash
# Run auto-detect locally
./scripts/auto-detect-components.sh --auto-add

# Commit the updated registry
git add registry.json
git commit -m "chore: update registry with new components"
git push
```

#### 2. Prompt Issues

If prompts don't match defaults:

```bash
# Restore default prompts
./scripts/prompts/use-prompt.sh <agent-name> default

# Commit the changes
git add .opencode/agent/
git commit -m "chore: restore default prompts"
git push
```

#### 3. Path Issues

If registry paths are invalid:

```bash
# Validate and see suggestions
./scripts/validate-registry.sh --fix

# Manually fix paths in registry.json
# Then commit
git add registry.json
git commit -m "fix: correct registry paths"
git push
```

### What Happens Next

1. **Fix Issues Locally**: If validation fails, fix issues and push
2. **Maintainer Review**: A maintainer will review your code
3. **Merge**: Once everything passes, your PR will be merged!

---

## For Maintainers

### Handling External PRs

External PRs run normally but **cannot auto-commit** due to GitHub security (can't push to fork branches).

### Simple Overrides

If you need to override checks:

**Skip Validation:**
1. Go to **Actions** → **Validate Registry on PR**
2. Click **"Run workflow"**
3. Enable **"Skip validation checks"**
4. Run on the PR branch

**Skip Tests:**
1. Go to **Actions** → **Test Agents**
2. Click **"Run workflow"**
3. Enable **"Skip tests"**
4. Run on the PR branch

### Workflow Behavior

| PR Type | Registry Validation | Auto-Commit | Agent Tests |
|---------|-------------------|-------------|-------------|
| **Internal PR** (branch) | ✅ Yes | ✅ Yes | ✅ Yes |
| **External PR** (fork) | ✅ Yes | ❌ No* | ✅ Yes |

*Cannot push to fork branches - contributor must fix locally

### Manual Testing External PRs

If you want to test an external PR locally:

```bash
# Fetch the PR
gh pr checkout <PR_NUMBER>

# Run validation
./scripts/validate-registry.sh -v
./scripts/prompts/validate-pr.sh

# Auto-fix registry if needed
./scripts/auto-detect-components.sh --auto-add

# Run tests
npm run test:ci

# If everything passes, approve and merge
gh pr review <PR_NUMBER> --approve
gh pr merge <PR_NUMBER>
```

---

## Workflow Files

- **`.github/workflows/validate-registry.yml`**: Registry validation with override
- **`.github/workflows/test-agents.yml`**: Agent tests with override

## Questions?

- **Contributors**: See [CONTRIBUTING.md](../docs/contributing/CONTRIBUTING.md)
- **Maintainers**: See [WORKFLOW_GUIDE.md](../WORKFLOW_GUIDE.md)
- **Issues**: Open a [GitHub Issue](https://github.com/darrenhinde/OpenAgents/issues)