soma-core 2.0.1

# 🚀 SOMA-CORE GitHub Project Automation

Automated creation and management of GitHub project cards for your SOMA-CORE multi-agent editing system.

## 🎯 Overview

This automation system creates and manages GitHub issues and project cards based on your SOMA-CORE development roadmap. It automatically generates cards for:

- **Core SOMA Operators** (IntrospectOperator, ConsensusOperator, etc.)
- **Edit Control Enhancement Tasks** (EditModificationInterface, AdvancedPreviewSystem, etc.)
- **Workflow Integration Tasks** (GitIntegration, ConditionalLogicSystem, etc.)

## ⚡ Quick Start

### 1. Setup

```bash
# Navigate to the automation directory
cd scripts/github-automation

# Run the setup script
./setup.sh
```

The setup script will:
- Create a configuration template
- Validate your GitHub token
- Auto-detect your project ID
- Configure the automation environment

### 2. Configure Your Token

1. Go to [GitHub Personal Access Tokens](https://github.com/settings/tokens)
2. Click **"Generate new token (classic)"**
3. Select these scopes:
   - ✅ `repo` (Full control of private repositories)
   - ✅ `project` (Full control of projects)
4. Copy the token and add it to `config.env`:

```bash
# Edit the configuration file
nano config.env

# Update this line with your token:
GITHUB_TOKEN="ghp_your_actual_token_here"
```

### 3. Create Project Cards

```bash
# Create all cards (operators + edit control + workflow)
./create-cards.sh

# Or create specific groups:
./create-cards.sh --operators-only
./create-cards.sh --edit-control-only
./create-cards.sh --workflow-only

# Get help
./create-cards.sh --help
```

## 📋 Configuration

### `config.env` File

```bash
# GitHub Personal Access Token
GITHUB_TOKEN="ghp_your_token_here"

# GitHub username (auto-configured)
GITHUB_USERNAME="diegorhoger"

# Repository name (auto-configured)
GITHUB_REPO="soma-core"

# Project ID (auto-detected or manually set)
GITHUB_PROJECT_ID="PN_kwDOAAJYqM4AF60P"

# Default labels for issues
DEFAULT_LABELS="soma++,operator,enhancement"

# Issue template directory
ISSUE_TEMPLATE_DIR="./issue-templates"
```

## 🤖 Automatic Triggers

### GitHub Actions Integration

The system includes a GitHub Actions workflow (`.github/workflows/project-sync.yml`) that automatically triggers when:

- `plan.md` is updated
- `PROJECT_STATUS.md` is modified  
- New files are added to `src/agents/`
- Manual trigger via GitHub Actions UI

### Manual Workflow Trigger

1. Go to your repository's **Actions** tab
2. Select **"🚀 SOMA-CORE Project Sync"**
3. Click **"Run workflow"**
4. Choose options:
   - **Task Type**: `all`, `operators-only`, `edit-control-only`, or `workflow-only`
   - **Dry Run**: Preview changes without creating issues

## 📊 Task Categories

### 🔧 Core SOMA Operators
- `IntrospectOperator` - Recursive self-diagnosis and phase awareness
- `ConsensusOperator` - Multi-agent edit agreement resolver
- `CognitiveLoadOperator` - Computational complexity estimation
- `AttentionFocusOperator` - High-salience context prioritization
- `VisualReasoningOperator` - Image-to-symbolic conversion
- `MetaReflectiveOperator` - Recursive system introspection

### 📝 Edit Control Enhancement
- `EditModificationInterface` - Inline edit modification capabilities
- `AdvancedPreviewSystem` - Side-by-side editor with live preview
- `GranularApprovalLevels` - Multi-level approval system
- `EditClassificationSystem` - Automated edit categorization
- `StagedApplicationSystem` - Phased edit application
- `FileProtectionConstraints` - File-level protection rules

### 🔄 Workflow Integration
- `GitIntegration` - Branch-per-session automation
- `ConditionalLogicSystem` - Test-based edit application
- `EditHistoryTimeTravel` - Complete edit history management
- `CustomAgentConfiguration` - User-defined agent personalities

## 🛠️ Customization

### Adding New Task Categories

Edit `scripts/github-automation/create-cards.sh` and add new associative arrays:

```bash
declare -A MY_NEW_TASKS=(
    ["TaskName"]="Task description"
    ["AnotherTask"]="Another description"
)

# Add to the main function
process_task_group MY_NEW_TASKS "My Task Group" "$DEFAULT_LABELS,my-label"
```

### Custom Issue Templates

Create templates in the `issue-templates/` directory:

```markdown
<!-- issue-templates/operator.md -->
## 🎯 SOMA Operator: {{ title }}

**Description:** {{ description }}

## 📋 Implementation Checklist
- [ ] Research and design
- [ ] Core implementation  
- [ ] Integration testing
- [ ] Documentation
- [ ] Performance validation

## 🔗 Dependencies
- Core edit control framework
- Multi-agent coordination system

## 📈 Success Criteria
- [ ] Passes all unit tests
- [ ] Integrates with existing operators
- [ ] Performance benchmarks met
- [ ] Documentation complete
```

### Custom Labels

Update the `DEFAULT_LABELS` in `config.env`:

```bash
DEFAULT_LABELS="soma++,operator,enhancement,priority:high"
```

## 🚨 Troubleshooting

### Common Issues

**Token Authentication Failed**
```bash
❌ Invalid GitHub token
```
- Verify token has `repo` and `project` scopes
- Check token hasn't expired
- Ensure token is correctly set in `config.env`

**Project Not Found**
```bash
⚠️ SOMA project not found automatically
```
- Manually set `GITHUB_PROJECT_ID` in `config.env`
- Use the GraphQL query to find your project ID:
```bash
curl -H "Authorization: bearer YOUR_TOKEN" \
  -X POST -d '{"query": "query { viewer { projectsV2(first: 20) { nodes { id title } } } }"}' \
  https://api.github.com/graphql
```

**Rate Limiting**
```bash
API rate limit exceeded
```
- The script includes automatic delays
- For large batches, run smaller groups:
```bash
./create-cards.sh --operators-only
# Wait a few minutes
./create-cards.sh --edit-control-only
```

### Debug Mode

Enable verbose output:

```bash
export DEBUG=1
./create-cards.sh
```

## 📈 Analytics & Monitoring

### GitHub Actions Logs

Monitor automation runs in your repository's **Actions** tab. Each run includes:
- Detailed execution logs
- Success/failure notifications
- Issue creation summary
- Project board updates

### Local Monitoring

The scripts provide colored output with progress indicators:
- 🔍 **Info**: General information
- ✅ **Success**: Completed operations
- ⚠️ **Warning**: Non-critical issues
- ❌ **Error**: Critical failures

## 🔧 Advanced Features

### Conditional Creation

Prevent duplicate issues by checking existing ones:

```bash
# The script automatically checks for existing issues with the same title
# and skips creation if they already exist
```

### Batch Operations

Process multiple task groups efficiently:

```bash
# Process all groups with a single command
./create-cards.sh

# Or chain specific groups
./create-cards.sh --operators-only && \
./create-cards.sh --edit-control-only && \
./create-cards.sh --workflow-only
```

### Integration with Other Tools

The automation system can be extended to work with:
- **Jira**: Convert GitHub issues to Jira tickets
- **Slack**: Send notifications on completion
- **Discord**: Bot integration for team updates
- **Email**: Digest reports for stakeholders

## 🎯 Best Practices

1. **Regular Updates**: Run automation when your `plan.md` changes
2. **Label Consistency**: Use consistent labeling across all issues
3. **Project Organization**: Keep your GitHub project board organized with proper columns
4. **Token Security**: Never commit tokens to version control
5. **Monitoring**: Regularly check GitHub Actions logs for issues

## 🔄 Continuous Integration

The system integrates seamlessly with your development workflow:

1. **Plan Updates** → Automatic issue creation
2. **Code Changes** → Project board updates  
3. **Feature Completion** → Issue closure automation
4. **Release Planning** → Milestone management

## 📞 Support

For issues with the automation system:

1. Check the troubleshooting section above
2. Review GitHub Actions logs in your repository
3. Verify your `config.env` settings
4. Test with a minimal example first

---

**🎉 Happy Automating!**

This automation system is designed to scale with your SOMA-CORE development, providing seamless project management integration for your multi-agent editing platform.