diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 0000000..d3176c3 --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,87 @@ +{ + "name": "BlackRoad Agent Codespace", + "image": "mcr.microsoft.com/devcontainers/python:3.11-bullseye", + + "features": { + "ghcr.io/devcontainers/features/node:1": { + "version": "20" + }, + "ghcr.io/devcontainers/features/go:1": { + "version": "latest" + }, + "ghcr.io/devcontainers/features/docker-in-docker:2": {}, + "ghcr.io/devcontainers/features/github-cli:1": {} + }, + + "customizations": { + "vscode": { + "extensions": [ + "ms-python.python", + "ms-python.vscode-pylance", + "ms-toolsai.jupyter", + "github.copilot", + "github.copilot-chat", + "dbaeumer.vscode-eslint", + "esbenp.prettier-vscode", + "redhat.vscode-yaml", + "ms-azuretools.vscode-docker", + "eamodio.gitlens", + "Continue.continue" + ], + "settings": { + "python.defaultInterpreterPath": "/usr/local/bin/python", + "python.linting.enabled": true, + "python.linting.pylintEnabled": true, + "python.formatting.provider": "black", + "editor.formatOnSave": true, + "files.autoSave": "onFocusChange", + "terminal.integrated.defaultProfile.linux": "bash" + } + } + }, + + "postCreateCommand": "bash .devcontainer/setup.sh", + + "forwardPorts": [ + 8080, + 3000, + 5000, + 11434, + 8787 + ], + + "portsAttributes": { + "8080": { + "label": "BlackRoad Operator", + "onAutoForward": "notify" + }, + "3000": { + "label": "Web UI", + "onAutoForward": "openPreview" + }, + "5000": { + "label": "Hailo Inference", + "onAutoForward": "silent" + }, + "11434": { + "label": "Ollama API", + "onAutoForward": "silent" + }, + "8787": { + "label": "Wrangler Dev", + "onAutoForward": "notify" + } + }, + + "remoteEnv": { + "PYTHONPATH": "${containerWorkspaceFolder}/prototypes/operator:${containerWorkspaceFolder}/prototypes/mcp-server:${containerWorkspaceFolder}/prototypes/dispatcher", + "BLACKROAD_ENV": "codespace", + "NODE_ENV": "development" + }, + + "mounts": [ + "source=${localEnv:HOME}${localEnv:USERPROFILE}/.ssh,target=/home/vscode/.ssh,readonly,type=bind,consistency=cached" + ], + + "postAttachCommand": "./quickstart.sh" +} diff --git a/.devcontainer/setup.sh b/.devcontainer/setup.sh new file mode 100644 index 0000000..a1dc501 --- /dev/null +++ b/.devcontainer/setup.sh @@ -0,0 +1,104 @@ +#!/bin/bash +set -e + +echo "🔧 Setting up BlackRoad Agent Codespace..." + +# Update package list +sudo apt-get update + +# Install system dependencies +echo "📦 Installing system dependencies..." +sudo apt-get install -y \ + build-essential \ + curl \ + wget \ + git \ + jq \ + vim \ + htop \ + redis-tools \ + postgresql-client + +# Install Python dependencies +echo "🐍 Installing Python dependencies..." +pip install --upgrade pip +pip install black pylint pytest + +# Install core prototypes dependencies +if [ -f "prototypes/operator/requirements.txt" ]; then + pip install -r prototypes/operator/requirements.txt +fi + +if [ -f "prototypes/mcp-server/requirements.txt" ]; then + pip install -r prototypes/mcp-server/requirements.txt +fi + +if [ -f "templates/ai-router/requirements.txt" ]; then + pip install -r templates/ai-router/requirements.txt +fi + +# Install AI/ML libraries +echo "🤖 Installing AI/ML libraries..." +pip install \ + openai \ + anthropic \ + ollama \ + langchain \ + langchain-community \ + langchain-openai \ + tiktoken \ + transformers \ + torch \ + numpy \ + fastapi \ + uvicorn \ + websockets + +# Install Cloudflare Workers CLI (Wrangler) +echo "☁️ Installing Cloudflare Wrangler..." +npm install -g wrangler + +# Install Ollama for local model hosting +echo "🦙 Installing Ollama..." +curl -fsSL https://ollama.ai/install.sh | sh || echo "Ollama installation skipped (may require system permissions)" + +# Create necessary directories +echo "📁 Creating directories..." +mkdir -p /tmp/blackroad/{cache,logs,models} + +# Initialize Ollama models (in background) +echo "📥 Pulling open source AI models..." +( + # Wait for Ollama to be ready + sleep 5 + + # Pull popular open source models + ollama pull llama3.2:latest || echo "Skipped llama3.2" + ollama pull codellama:latest || echo "Skipped codellama" + ollama pull mistral:latest || echo "Skipped mistral" + ollama pull qwen2.5-coder:latest || echo "Skipped qwen2.5-coder" + ollama pull deepseek-coder:latest || echo "Skipped deepseek-coder" + ollama pull phi3:latest || echo "Skipped phi3" + ollama pull gemma2:latest || echo "Skipped gemma2" + + echo "✅ Model downloads initiated (running in background)" +) & + +# Set up git config +echo "⚙️ Configuring git..." +git config --global --add safe.directory /workspaces/.github + +# Make bridge executable +if [ -f "bridge" ]; then + chmod +x bridge +fi + +echo "" +echo "✨ BlackRoad Agent Codespace setup complete!" +echo "" +echo "Available commands:" +echo " python -m operator.cli # Run the operator" +echo " ollama list # List available models" +echo " wrangler dev # Start Cloudflare Worker" +echo " ./bridge status # Check system status" +echo "" diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 0000000..9897fd2 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,73 @@ +# CODEOWNERS file for BlackRoad OS +# +# This file defines who owns and should review changes to different parts of the repository. +# Lines are processed top to bottom, so the last matching pattern takes precedence. +# +# Format: @owner-username @owner-username +# +# Learn more: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# Default owners for everything in the repo +# These owners will be requested for review when someone opens a PR +* @BlackRoad-OS/maintainers + +# Core Bridge files - require approval from core team +/.STATUS @BlackRoad-OS/core-team +/MEMORY.md @BlackRoad-OS/core-team +/INDEX.md @BlackRoad-OS/core-team +/BLACKROAD_ARCHITECTURE.md @BlackRoad-OS/core-team +/REPO_MAP.md @BlackRoad-OS/core-team +/STREAMS.md @BlackRoad-OS/core-team +/SIGNALS.md @BlackRoad-OS/core-team +/INTEGRATIONS.md @BlackRoad-OS/core-team + +# Organization blueprints - org-specific owners +/orgs/BlackRoad-OS/ @BlackRoad-OS/os-team +/orgs/BlackRoad-AI/ @BlackRoad-OS/ai-team +/orgs/BlackRoad-Cloud/ @BlackRoad-OS/cloud-team +/orgs/BlackRoad-Hardware/ @BlackRoad-OS/hardware-team +/orgs/BlackRoad-Security/ @BlackRoad-OS/security-team +/orgs/BlackRoad-Labs/ @BlackRoad-OS/labs-team +/orgs/BlackRoad-Foundation/ @BlackRoad-OS/foundation-team +/orgs/BlackRoad-Ventures/ @BlackRoad-OS/ventures-team +/orgs/Blackbox-Enterprises/ @BlackRoad-OS/blackbox-team +/orgs/BlackRoad-Media/ @BlackRoad-OS/media-team +/orgs/BlackRoad-Studio/ @BlackRoad-OS/studio-team +/orgs/BlackRoad-Interactive/ @BlackRoad-OS/interactive-team +/orgs/BlackRoad-Education/ @BlackRoad-OS/education-team +/orgs/BlackRoad-Gov/ @BlackRoad-OS/gov-team +/orgs/BlackRoad-Archive/ @BlackRoad-OS/archive-team + +# Prototypes - require review from prototype maintainers +/prototypes/operator/ @BlackRoad-OS/ai-team +/prototypes/metrics/ @BlackRoad-OS/os-team +/prototypes/explorer/ @BlackRoad-OS/os-team + +# Templates - require review from relevant teams +/templates/salesforce-sync/ @BlackRoad-OS/foundation-team +/templates/stripe-billing/ @BlackRoad-OS/foundation-team +/templates/cloudflare-workers/ @BlackRoad-OS/cloud-team +/templates/gdrive-sync/ @BlackRoad-OS/archive-team +/templates/github-ecosystem/ @BlackRoad-OS/os-team +/templates/design-tools/ @BlackRoad-OS/studio-team + +# GitHub workflows - require DevOps approval +/.github/workflows/ @BlackRoad-OS/devops-team @BlackRoad-OS/security-team + +# Security files - require security team approval +/SECURITY.md @BlackRoad-OS/security-team +/.github/dependabot.yml @BlackRoad-OS/security-team @BlackRoad-OS/devops-team + +# Community health files +/CODE_OF_CONDUCT.md @BlackRoad-OS/core-team +/CONTRIBUTING.md @BlackRoad-OS/core-team +/SUPPORT.md @BlackRoad-OS/core-team + +# Profile and public-facing content +/profile/ @BlackRoad-OS/media-team @BlackRoad-OS/core-team + +# Node configurations +/nodes/ @BlackRoad-OS/hardware-team + +# Routes +/routes/ @BlackRoad-OS/os-team diff --git a/.github/FUNDING.yml b/.github/FUNDING.yml new file mode 100644 index 0000000..22ac8b1 --- /dev/null +++ b/.github/FUNDING.yml @@ -0,0 +1,19 @@ +# GitHub Sponsors configuration +# These are supported funding model platforms + +# github: [username] # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2] +# patreon: # Replace with a single Patreon username +# open_collective: # Replace with a single Open Collective username +# ko_fi: # Replace with a single Ko-fi username +# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel +# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry +# liberapay: # Replace with a single Liberapay username +# issuehunt: # Replace with a single IssueHunt username +# otechie: # Replace with a single Otechie username +# lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry +# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2'] + +# BlackRoad OS Funding +# Uncomment and configure when funding options are available +# github: [BlackRoad-OS] +# custom: ['https://blackroad.dev/support'] diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..9ebc099 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,93 @@ +name: 🐛 Bug Report +description: Report a bug or unexpected behavior +title: "[Bug]: " +labels: ["bug", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report this bug! The issue will be auto-triaged to the appropriate organization. + + - type: dropdown + id: organization + attributes: + label: Organization + description: Which BlackRoad organization does this relate to? + options: + - BlackRoad-OS (Core Infrastructure) + - BlackRoad-AI (Intelligence Routing) + - BlackRoad-Cloud (Edge Compute) + - BlackRoad-Hardware (Pi Cluster / IoT) + - BlackRoad-Security (Auth / Secrets) + - BlackRoad-Labs (Experiments) + - BlackRoad-Foundation (CRM / Finance) + - BlackRoad-Ventures (Marketplace) + - Blackbox-Enterprises (Enterprise) + - BlackRoad-Media (Content) + - BlackRoad-Studio (Design) + - BlackRoad-Interactive (Metaverse) + - BlackRoad-Education (Learning) + - BlackRoad-Gov (Governance) + - BlackRoad-Archive (Storage) + - Not sure / Multiple orgs + validations: + required: true + + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear and concise description of what the bug is + placeholder: What happened? + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What did you expect to happen? + placeholder: What should have happened? + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to Reproduce + description: How can we reproduce this issue? + placeholder: | + 1. Go to '...' + 2. Run command '...' + 3. See error + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: System information + placeholder: | + - OS: [e.g., Ubuntu 22.04, macOS 14] + - Version: [e.g., v1.0.0] + - Hardware: [e.g., Raspberry Pi 4, x86_64] + validations: + required: false + + - type: textarea + id: logs + attributes: + label: Relevant Logs + description: Paste any relevant logs or error messages + render: shell + validations: + required: false + + - type: textarea + id: context + attributes: + label: Additional Context + description: Any other context about the problem + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..b295470 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,11 @@ +blank_issues_enabled: false +contact_links: + - name: 🤝 Community Support + url: https://github.com/orgs/BlackRoad-OS/discussions + about: Ask questions and discuss with the community + - name: 📚 Documentation + url: https://github.com/BlackRoad-OS/.github/blob/main/INDEX.md + about: Browse the complete BlackRoad documentation + - name: 🏢 Organization Blueprints + url: https://github.com/BlackRoad-OS/.github/tree/main/orgs + about: View all 15 organization specifications diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..4f1bc62 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,81 @@ +name: ✨ Feature Request +description: Suggest a new feature or enhancement +title: "[Feature]: " +labels: ["enhancement", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a new feature! The issue will be auto-triaged to the appropriate organization. + + - type: dropdown + id: organization + attributes: + label: Organization + description: Which BlackRoad organization should implement this? + options: + - BlackRoad-OS (Core Infrastructure) + - BlackRoad-AI (Intelligence Routing) + - BlackRoad-Cloud (Edge Compute) + - BlackRoad-Hardware (Pi Cluster / IoT) + - BlackRoad-Security (Auth / Secrets) + - BlackRoad-Labs (Experiments) + - BlackRoad-Foundation (CRM / Finance) + - BlackRoad-Ventures (Marketplace) + - Blackbox-Enterprises (Enterprise) + - BlackRoad-Media (Content) + - BlackRoad-Studio (Design) + - BlackRoad-Interactive (Metaverse) + - BlackRoad-Education (Learning) + - BlackRoad-Gov (Governance) + - BlackRoad-Archive (Storage) + - Not sure / Multiple orgs + validations: + required: true + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: What problem does this feature solve? + placeholder: I'm frustrated when... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: How should this feature work? + placeholder: I would like to... + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: What other solutions have you considered? + validations: + required: false + + - type: dropdown + id: priority + attributes: + label: Priority + description: How important is this feature to you? + options: + - Critical - Blocking my work + - High - Very important + - Medium - Would be nice to have + - Low - Minor improvement + validations: + required: true + + - type: textarea + id: context + attributes: + label: Additional Context + description: Any mockups, examples, or additional information + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/organization_setup.yml b/.github/ISSUE_TEMPLATE/organization_setup.yml new file mode 100644 index 0000000..774e119 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/organization_setup.yml @@ -0,0 +1,123 @@ +name: 🏢 Organization Setup +description: Set up a new repository in a BlackRoad organization +title: "[Org Setup]: " +labels: ["org:setup", "needs-triage"] +body: + - type: markdown + attributes: + value: | + Use this template to request setup of a new repository within a BlackRoad organization. + + - type: dropdown + id: organization + attributes: + label: Target Organization + description: Which organization should this repository be created in? + options: + - BlackRoad-OS (Core Infrastructure) + - BlackRoad-AI (Intelligence Routing) + - BlackRoad-Cloud (Edge Compute) + - BlackRoad-Hardware (Pi Cluster / IoT) + - BlackRoad-Security (Auth / Secrets) + - BlackRoad-Labs (Experiments) + - BlackRoad-Foundation (CRM / Finance) + - BlackRoad-Ventures (Marketplace) + - Blackbox-Enterprises (Enterprise) + - BlackRoad-Media (Content) + - BlackRoad-Studio (Design) + - BlackRoad-Interactive (Metaverse) + - BlackRoad-Education (Learning) + - BlackRoad-Gov (Governance) + - BlackRoad-Archive (Storage) + validations: + required: true + + - type: input + id: repo-name + attributes: + label: Repository Name + description: Proposed name for the new repository + placeholder: my-new-repo + validations: + required: true + + - type: textarea + id: description + attributes: + label: Repository Description + description: What will this repository contain? + placeholder: Brief description of the repository purpose + validations: + required: true + + - type: dropdown + id: repo-type + attributes: + label: Repository Type + description: What type of repository is this? + options: + - Application / Service + - Library / Package + - Infrastructure / Config + - Documentation + - Template / Boilerplate + - Other + validations: + required: true + + - type: dropdown + id: visibility + attributes: + label: Visibility + description: Should this repository be public or private? + options: + - Public + - Private + validations: + required: true + + - type: textarea + id: tech-stack + attributes: + label: Technology Stack + description: What technologies will be used? + placeholder: | + - Language: Python 3.11 + - Framework: FastAPI + - Database: PostgreSQL + validations: + required: false + + - type: textarea + id: dependencies + attributes: + label: Dependencies & Integrations + description: What external services or other repositories will this depend on? + placeholder: | + - Depends on: BlackRoad-Cloud/workers + - Integrates with: Salesforce, Stripe + validations: + required: false + + - type: checkboxes + id: features + attributes: + label: Required Features + description: What should be set up in this repository? + options: + - label: CI/CD workflows + - label: Issue templates + - label: PR templates + - label: Code scanning + - label: Dependabot + - label: Documentation site + - label: Docker container + - label: API documentation + + - type: textarea + id: context + attributes: + label: Additional Context + description: Any other information about this repository + validations: + required: false diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..67941ca --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,89 @@ +## Description + + + +## Type of Change + + + +- [ ] 🐛 Bug fix (non-breaking change that fixes an issue) +- [ ] ✨ New feature (non-breaking change that adds functionality) +- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] 📚 Documentation update +- [ ] 🔧 Configuration change +- [ ] ♻️ Code refactoring +- [ ] 🎨 UI/UX improvement +- [ ] ⚡ Performance improvement +- [ ] 🧪 Test addition or update + +## Organization + + + +- [ ] BlackRoad-OS (Core Infrastructure) +- [ ] BlackRoad-AI (Intelligence Routing) +- [ ] BlackRoad-Cloud (Edge Compute) +- [ ] BlackRoad-Hardware (Pi Cluster / IoT) +- [ ] BlackRoad-Security (Auth / Secrets) +- [ ] BlackRoad-Labs (Experiments) +- [ ] BlackRoad-Foundation (CRM / Finance) +- [ ] BlackRoad-Ventures (Marketplace) +- [ ] Blackbox-Enterprises (Enterprise) +- [ ] BlackRoad-Media (Content) +- [ ] BlackRoad-Studio (Design) +- [ ] BlackRoad-Interactive (Metaverse) +- [ ] BlackRoad-Education (Learning) +- [ ] BlackRoad-Gov (Governance) +- [ ] BlackRoad-Archive (Storage) +- [ ] Multiple organizations +- [ ] Infrastructure / Meta + +## Changes Made + + + +- +- +- + +## Testing + + + +- [ ] Unit tests added/updated +- [ ] Integration tests added/updated +- [ ] Manual testing completed +- [ ] CI/CD pipeline passes + +**Test Details:** + + +## Related Issues + + + +Closes # +Relates to # + +## Screenshots + + + +## Checklist + +- [ ] My code follows the project's style guidelines +- [ ] I have performed a self-review of my code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and published + +## Additional Context + + + +--- + +📡 **Signal:** `PR → [ORG] : [action]` diff --git a/.github/README.md b/.github/README.md new file mode 100644 index 0000000..4b9d8a0 --- /dev/null +++ b/.github/README.md @@ -0,0 +1,257 @@ +# .github Directory + +This directory contains GitHub-specific configurations for the BlackRoad-OS/.github repository, which serves as **The Bridge** - the central coordination point for all BlackRoad organizations. + +--- + +## Purpose + +The `.github` directory in a special `.github` repository serves two purposes: + +1. **Repository Configuration** - Settings for this specific repository +2. **Organization Defaults** - Default settings inherited by all repositories in the BlackRoad-OS organization + +--- + +## Structure + +``` +.github/ +├── ISSUE_TEMPLATE/ # Issue templates +│ ├── bug_report.yml # Bug report template +│ ├── config.yml # Issue template configuration +│ ├── feature_request.yml # Feature request template +│ └── organization_setup.yml # Org setup template +│ +├── workflows/ # GitHub Actions workflows +│ ├── ci.yml # Continuous integration +│ ├── deploy-worker.yml # Cloudflare Worker deployment +│ ├── health-check.yml # System health monitoring +│ ├── issue-triage.yml # Auto-triage issues +│ ├── pr-review.yml # PR automation +│ ├── release.yml # Release management +│ ├── sync-assets.yml # Asset sync +│ └── webhook-dispatch.yml # Webhook handling +│ +├── CODEOWNERS # Code review assignments +├── dependabot.yml # Dependency update automation +├── FUNDING.yml # Sponsorship configuration +└── PULL_REQUEST_TEMPLATE.md # PR template +``` + +--- + +## Files Explained + +### Issue Templates + +**ISSUE_TEMPLATE/** + +GitHub issue forms that provide structured bug reports and feature requests. All templates include organization selection to route issues correctly. + +- `bug_report.yml` - Structured bug reporting +- `feature_request.yml` - Feature suggestions +- `organization_setup.yml` - New repository setup requests +- `config.yml` - Links to docs and discussions + +### Workflows + +**workflows/** + +Automated GitHub Actions for CI/CD, monitoring, and automation. + +Key workflows: +- `issue-triage.yml` - Uses the Operator prototype to auto-classify and label issues +- `ci.yml` - Runs tests and linting +- `health-check.yml` - Monitors system health +- `deploy-worker.yml` - Deploys Cloudflare Workers + +### Code Review + +**CODEOWNERS** + +Defines default reviewers for different parts of the repository: +- Core files require core team approval +- Organization blueprints route to org-specific teams +- Security files require security team approval + +### Dependency Management + +**dependabot.yml** + +Configures Dependabot to automatically: +- Update GitHub Actions weekly +- Update Python dependencies in prototypes +- Create PRs for security updates + +### Funding + +**FUNDING.yml** + +Placeholder for future sponsorship options (GitHub Sponsors, custom URLs). + +### Pull Requests + +**PULL_REQUEST_TEMPLATE.md** + +Template for all pull requests with: +- Description guidelines +- Type of change checkboxes +- Organization selection +- Testing checklist +- Signal notation + +--- + +## How It Works + +### As a .github Repository + +This repository is special because it's named `.github` in the BlackRoad-OS organization. This means: + +1. **Organization-wide defaults** - Files here apply to all repos without their own versions +2. **Profile README** - The `profile/README.md` appears on the org's GitHub page +3. **Shared workflows** - Can be reused across repositories + +### Auto-triage System + +The `issue-triage.yml` workflow uses the Operator prototype to: +1. Parse issue title and body +2. Route to appropriate organization (OS, AI, Cloud, etc.) +3. Apply relevant labels +4. Add auto-classification comment + +### Code Review Flow + +When a PR is created: +1. CODEOWNERS assigns reviewers based on changed files +2. CI workflows run automated checks +3. Security scans execute +4. Human reviewers approve +5. Auto-merge if conditions met + +--- + +## Customization + +### Adding a New Issue Template + +1. Create a new `.yml` file in `ISSUE_TEMPLATE/` +2. Follow the GitHub issue forms syntax +3. Include organization dropdown for routing +4. Test with a real issue + +### Adding a New Workflow + +1. Create a new `.yml` file in `workflows/` +2. Define triggers (push, PR, schedule, etc.) +3. Add jobs and steps +4. Test in a branch before merging + +### Updating CODEOWNERS + +1. Edit `.github/CODEOWNERS` +2. Add patterns and team mentions +3. Ensure teams exist in GitHub org settings + +--- + +## Best Practices + +### Issue Templates + +- Keep forms concise but comprehensive +- Use dropdowns for structured data +- Make critical fields required +- Include help text and examples + +### Workflows + +- Pin action versions for security +- Use secrets for credentials +- Add timeout limits +- Fail fast for quick feedback + +### CODEOWNERS + +- More specific patterns at the bottom +- Use teams instead of individuals +- Require reviews for sensitive files +- Document ownership reasons + +--- + +## Inheritance + +Repositories in BlackRoad-OS without their own `.github` directory will inherit: + +- Issue templates +- Pull request template +- Community health files (CODE_OF_CONDUCT, CONTRIBUTING, etc.) +- Funding configuration + +Repositories can override by creating their own versions. + +--- + +## Testing + +### Test Issue Templates + +1. Go to "New Issue" in this repository +2. Verify all templates appear +3. Test form validation +4. Check auto-triage workflow runs + +### Test Workflows + +1. Create a test branch +2. Make changes that trigger workflows +3. Check Actions tab for results +4. Verify notifications work + +### Test CODEOWNERS + +1. Create a test PR +2. Verify correct reviewers assigned +3. Check review requirements + +--- + +## Maintenance + +### Regular Tasks + +- **Weekly** - Review Dependabot PRs +- **Monthly** - Update workflow versions +- **Quarterly** - Review CODEOWNERS accuracy +- **Yearly** - Audit all templates and docs + +### Monitoring + +Check these regularly: +- Failed workflow runs +- Unassigned issues (triage failures) +- Dependabot alerts +- Security advisories + +--- + +## Resources + +- [GitHub Actions Documentation](https://docs.github.com/en/actions) +- [About CODEOWNERS](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners) +- [Dependabot Configuration](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file) +- [Issue Forms Syntax](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/syntax-for-issue-forms) + +--- + +## Questions? + +See [SUPPORT.md](../SUPPORT.md) for help options. + +--- + +*This directory is the automation heart of BlackRoad.* + +📡 **Signal:** `.github → automation : configured` diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..83290a4 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,84 @@ +version: 2 + +updates: + # GitHub Actions workflows + - package-ecosystem: "github-actions" + directory: "/.github/workflows" + schedule: + interval: "weekly" + day: "monday" + time: "09:00" + timezone: "America/Los_Angeles" + open-pull-requests-limit: 5 + reviewers: + - "BlackRoad-OS/devops-team" + labels: + - "dependencies" + - "github-actions" + commit-message: + prefix: "chore(deps)" + include: "scope" + + # Python dependencies in prototypes + - package-ecosystem: "pip" + directory: "/prototypes/operator" + schedule: + interval: "weekly" + day: "tuesday" + time: "09:00" + timezone: "America/Los_Angeles" + open-pull-requests-limit: 5 + reviewers: + - "BlackRoad-OS/ai-team" + labels: + - "dependencies" + - "python" + commit-message: + prefix: "chore(deps)" + include: "scope" + + - package-ecosystem: "pip" + directory: "/prototypes/metrics" + schedule: + interval: "weekly" + day: "tuesday" + time: "09:00" + timezone: "America/Los_Angeles" + open-pull-requests-limit: 5 + reviewers: + - "BlackRoad-OS/os-team" + labels: + - "dependencies" + - "python" + commit-message: + prefix: "chore(deps)" + include: "scope" + + - package-ecosystem: "pip" + directory: "/prototypes/explorer" + schedule: + interval: "weekly" + day: "tuesday" + time: "09:00" + timezone: "America/Los_Angeles" + open-pull-requests-limit: 5 + reviewers: + - "BlackRoad-OS/os-team" + labels: + - "dependencies" + - "python" + commit-message: + prefix: "chore(deps)" + include: "scope" + + # Templates - only security updates + - package-ecosystem: "pip" + directory: "/templates/salesforce-sync" + schedule: + interval: "monthly" + open-pull-requests-limit: 3 + labels: + - "dependencies" + - "template" + commit-message: + prefix: "chore(deps)" diff --git a/.github/workflows/auto-merge.yml b/.github/workflows/auto-merge.yml new file mode 100644 index 0000000..b405842 --- /dev/null +++ b/.github/workflows/auto-merge.yml @@ -0,0 +1,129 @@ +# Auto-merge PRs after CI passes +# Automatically merges approved PRs to main once all checks pass + +name: Auto Merge + +on: + pull_request_review: + types: [submitted] + workflow_run: + workflows: ["CI"] + types: [completed] + +jobs: + auto-merge: + name: Auto Merge PR + runs-on: ubuntu-latest + + # Only run on approved PRs targeting main + if: | + github.event_name == 'pull_request_review' || + (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success') + + permissions: + contents: write + pull-requests: write + checks: read + + steps: + - uses: actions/checkout@v4 + + - name: Get PR info + id: pr + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + # Get PR number from the event + if [ "${{ github.event_name }}" == "pull_request_review" ]; then + PR_NUMBER="${{ github.event.pull_request.number }}" + elif [ "${{ github.event_name }}" == "workflow_run" ]; then + # Extract PR number from workflow run + PR_NUMBER=$(gh pr list --json number,headRefName --jq '.[] | select(.headRefName=="${{ github.event.workflow_run.head_branch }}") | .number' | head -1) + else + echo "No PR found for event type: ${{ github.event_name }}" + exit 1 + fi + + if [ -z "$PR_NUMBER" ]; then + echo "No PR number found for branch ${{ github.event.workflow_run.head_branch }}" + exit 1 + fi + + echo "pr_number=$PR_NUMBER" >> $GITHUB_OUTPUT + + # Get PR details + PR_DATA=$(gh pr view $PR_NUMBER --json number,title,state,mergeable,reviewDecision,statusCheckRollup) + + echo "$PR_DATA" | jq . + + STATE=$(echo "$PR_DATA" | jq -r .state) + MERGEABLE=$(echo "$PR_DATA" | jq -r .mergeable) + REVIEW_DECISION=$(echo "$PR_DATA" | jq -r .reviewDecision) + + echo "state=$STATE" >> $GITHUB_OUTPUT + echo "mergeable=$MERGEABLE" >> $GITHUB_OUTPUT + echo "review_decision=$REVIEW_DECISION" >> $GITHUB_OUTPUT + + - name: Check merge conditions + id: check + run: | + STATE="${{ steps.pr.outputs.state }}" + MERGEABLE="${{ steps.pr.outputs.mergeable }}" + REVIEW_DECISION="${{ steps.pr.outputs.review_decision }}" + + echo "PR State: $STATE" + echo "Mergeable: $MERGEABLE" + echo "Review Decision: $REVIEW_DECISION" + + # Check conditions + CAN_MERGE=false + + if [ "$STATE" == "OPEN" ] && \ + [ "$MERGEABLE" == "MERGEABLE" ] && \ + [ "$REVIEW_DECISION" == "APPROVED" ]; then + CAN_MERGE=true + fi + + echo "can_merge=$CAN_MERGE" >> $GITHUB_OUTPUT + + if [ "$CAN_MERGE" == "true" ]; then + echo "✓ All conditions met for auto-merge" + else + echo "⚠️ Conditions not met:" + [ "$STATE" != "OPEN" ] && echo " - PR is not open" + [ "$MERGEABLE" != "MERGEABLE" ] && echo " - PR has conflicts or is not mergeable" + [ "$REVIEW_DECISION" != "APPROVED" ] && echo " - PR is not approved" + fi + + - name: Auto-merge PR + if: steps.check.outputs.can_merge == 'true' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + PR_NUMBER="${{ steps.pr.outputs.pr_number }}" + + echo "🚀 Auto-merging PR #$PR_NUMBER to main..." + + # Enable auto-merge with squash + gh pr merge $PR_NUMBER --auto --squash --delete-branch + + echo "✓ Auto-merge enabled" + + - name: Comment on PR + if: steps.check.outputs.can_merge == 'true' + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: | + PR_NUMBER="${{ steps.pr.outputs.pr_number }}" + + gh pr comment $PR_NUMBER --body "🤖 Auto-merge enabled. This PR will be merged automatically once all status checks pass." + + - name: Summary + if: always() + run: | + echo "🎯 Auto-merge Summary" + echo "" + echo "PR: #${{ steps.pr.outputs.pr_number }}" + echo "State: ${{ steps.pr.outputs.state }}" + echo "Can merge: ${{ steps.check.outputs.can_merge }}" + echo "Status: ${{ job.status }}" diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 72494ea..7990443 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -179,12 +179,40 @@ jobs: print(f'✓ registry.yaml: {len(reg[\"orgs\"])} orgs, {len(reg[\"rules\"])} rules') " + # Test sync functionality + test-sync: + name: Test Sync + runs-on: ubuntu-latest + + permissions: + contents: read + + steps: + - uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: ${{ env.PYTHON_VERSION }} + + - name: Install dependencies + run: pip install pyyaml + + - name: Run sync tests + run: | + chmod +x tests/test_sync.py + python tests/test_sync.py + # Signal summary job summary: name: CI Summary runs-on: ubuntu-latest - needs: [lint, test-operator, test-dispatcher, test-webhooks, validate-config] + needs: [lint, test-operator, test-dispatcher, test-webhooks, validate-config, test-sync] if: always() + + permissions: + contents: read + steps: - name: Check results run: | @@ -196,3 +224,4 @@ jobs: echo " Dispatcher: ${{ needs.test-dispatcher.result }}" echo " Webhooks: ${{ needs.test-webhooks.result }}" echo " Config: ${{ needs.validate-config.result }}" + echo " Sync: ${{ needs.test-sync.result }}" diff --git a/.github/workflows/pr-handler.yml b/.github/workflows/pr-handler.yml new file mode 100644 index 0000000..8e60617 --- /dev/null +++ b/.github/workflows/pr-handler.yml @@ -0,0 +1,312 @@ +# PR Handler - Comprehensive Pull Request Management +# Handles incoming PRs with intelligent triage, labeling, and status tracking + +name: PR Handler + +on: + pull_request: + types: [opened, edited, synchronize, reopened, ready_for_review] + pull_request_review: + types: [submitted] + issue_comment: + types: [created] + workflow_dispatch: + inputs: + pr_number: + description: 'PR number to handle' + required: false + +permissions: + contents: read + pull-requests: write + issues: write + +jobs: + analyze-pr: + name: Analyze PR + runs-on: ubuntu-latest + if: github.event_name == 'pull_request' || github.event_name == 'workflow_dispatch' + outputs: + is_wip: ${{ steps.analyze.outputs.is_wip }} + pr_type: ${{ steps.analyze.outputs.pr_type }} + needs_review: ${{ steps.analyze.outputs.needs_review }} + can_auto_merge: ${{ steps.analyze.outputs.can_auto_merge }} + org_scope: ${{ steps.analyze.outputs.org_scope }} + + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Analyze PR metadata + id: analyze + uses: actions/github-script@v7 + with: + script: | + const pr = context.payload.pull_request || + await github.rest.pulls.get({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.payload.inputs?.pr_number || context.issue.number + }).then(r => r.data); + + // Check if WIP + const isWIP = pr.title.includes('[WIP]') || pr.title.includes('WIP:') || pr.draft; + core.setOutput('is_wip', isWIP); + + // Determine PR type based on title and files + let prType = 'other'; + const title = pr.title.toLowerCase(); + if (title.includes('workflow') || title.includes('ci') || title.includes('github actions')) { + prType = 'workflow'; + } else if (title.includes('doc') || title.includes('wiki') || title.includes('readme')) { + prType = 'documentation'; + } else if (title.includes('test') || title.includes('ci/cd')) { + prType = 'testing'; + } else if (title.includes('infrastructure') || title.includes('setup')) { + prType = 'infrastructure'; + } else if (title.includes('agent') || title.includes('ai') || title.includes('claude')) { + prType = 'ai-feature'; + } else if (title.includes('collaboration') || title.includes('memory')) { + prType = 'core-feature'; + } + core.setOutput('pr_type', prType); + + // Determine org scope + const orgPatterns = [ + 'BlackRoad-OS', 'BlackRoad-AI', 'BlackRoad-Cloud', 'BlackRoad-Hardware', + 'BlackRoad-Security', 'BlackRoad-Labs', 'BlackRoad-Foundation', + 'BlackRoad-Media', 'BlackRoad-Studio', 'BlackRoad-Interactive', + 'BlackRoad-Education', 'BlackRoad-Gov', 'BlackRoad-Archive', + 'BlackRoad-Ventures', 'Blackbox-Enterprises' + ]; + const body = pr.body || ''; + const orgsFound = orgPatterns.filter(org => + title.includes(org) || body.includes(org) + ); + core.setOutput('org_scope', orgsFound.join(',') || 'all'); + + // Check if needs review + const needsReview = !isWIP && pr.requested_reviewers.length === 0; + core.setOutput('needs_review', needsReview); + + // Check if can auto-merge (copilot branches with checks passed) + const canAutoMerge = pr.head.ref.startsWith('copilot/') && + !isWIP && + pr.mergeable_state === 'clean'; + core.setOutput('can_auto_merge', canAutoMerge); + + return { + number: pr.number, + isWIP, + prType, + orgScope: orgsFound.join(',') || 'all', + needsReview, + canAutoMerge + }; + + label-pr: + name: Label PR + runs-on: ubuntu-latest + needs: analyze-pr + steps: + - name: Apply labels + uses: actions/github-script@v7 + with: + script: | + const prType = '${{ needs.analyze-pr.outputs.pr_type }}'; + const isWIP = '${{ needs.analyze-pr.outputs.is_wip }}' === 'true'; + const orgScope = '${{ needs.analyze-pr.outputs.org_scope }}'; + + const labels = []; + + // Type labels + const typeLabels = { + 'workflow': 'workflows', + 'documentation': 'documentation', + 'testing': 'testing', + 'infrastructure': 'infrastructure', + 'ai-feature': 'ai-enhancement', + 'core-feature': 'enhancement' + }; + if (typeLabels[prType]) { + labels.push(typeLabels[prType]); + } + + // Status labels + if (isWIP) { + labels.push('work-in-progress'); + } else { + labels.push('ready-for-review'); + } + + // Org scope labels + if (orgScope && orgScope !== 'all') { + const orgs = orgScope.split(','); + if (orgs.length > 3) { + labels.push('multi-org'); + } else { + orgs.forEach(org => { + const code = org.split('-').pop(); + labels.push(`org:${code.toLowerCase()}`); + }); + } + } + + // Apply labels + if (labels.length > 0) { + await github.rest.issues.addLabels({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + labels: labels + }); + } + + comment-on-pr: + name: Comment on PR + runs-on: ubuntu-latest + needs: analyze-pr + if: needs.analyze-pr.outputs.needs_review == 'true' + steps: + - name: Add helpful comment + uses: actions/github-script@v7 + with: + script: | + const prType = '${{ needs.analyze-pr.outputs.pr_type }}'; + const isWIP = '${{ needs.analyze-pr.outputs.is_wip }}' === 'true'; + + let comment = '## 🤖 PR Handler Analysis\n\n'; + comment += `**Type:** ${prType}\n`; + comment += `**Status:** ${isWIP ? 'Work in Progress' : 'Ready for Review'}\n\n`; + + if (!isWIP) { + comment += '### Next Steps\n'; + comment += '- [ ] Code review by maintainers\n'; + comment += '- [ ] CI checks pass\n'; + comment += '- [ ] Resolve any review comments\n'; + comment += '- [ ] Ready to merge\n\n'; + } + + // Type-specific guidance + const guidance = { + 'workflow': '⚠️ **Workflow changes** require careful review for security and permissions.', + 'documentation': '📚 **Documentation** - Ensure accuracy and completeness.', + 'testing': '🧪 **Testing changes** - Verify test coverage and quality.', + 'infrastructure': '🏗️ **Infrastructure** - Review for production readiness.', + 'ai-feature': '🤖 **AI Feature** - Test thoroughly with different scenarios.', + 'core-feature': '⭐ **Core Feature** - Requires comprehensive review and testing.' + }; + + if (guidance[prType]) { + comment += `### ℹ️ ${guidance[prType]}\n\n`; + } + + comment += '---\n'; + comment += '*Automated by BlackRoad PR Handler*'; + + // Check if comment already exists + const comments = await github.rest.issues.listComments({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + }); + + const existing = comments.data.find(c => + c.body.includes('PR Handler Analysis') && + c.user.type === 'Bot' + ); + + if (!existing) { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: context.issue.number, + body: comment + }); + } + + request-reviewers: + name: Request Reviewers + runs-on: ubuntu-latest + needs: analyze-pr + if: needs.analyze-pr.outputs.needs_review == 'true' && needs.analyze-pr.outputs.is_wip == 'false' + steps: + - name: Assign reviewers + uses: actions/github-script@v7 + with: + script: | + // Request review from repository owner + try { + await github.rest.pulls.requestReviewers({ + owner: context.repo.owner, + repo: context.repo.repo, + pull_number: context.issue.number, + reviewers: ['blackboxprogramming'] + }); + } catch (error) { + console.log('Could not request reviewers:', error.message); + } + + check-merge-readiness: + name: Check Merge Readiness + runs-on: ubuntu-latest + needs: analyze-pr + if: needs.analyze-pr.outputs.can_auto_merge == 'true' + steps: + - name: Check if ready to merge + uses: actions/github-script@v7 + with: + script: | + const pr = context.payload.pull_request; + + // Check CI status + const checks = await github.rest.checks.listForRef({ + owner: context.repo.owner, + repo: context.repo.repo, + ref: pr.head.sha + }); + + const allPassed = checks.data.check_runs.every(check => + check.conclusion === 'success' || check.conclusion === 'skipped' + ); + + if (allPassed && pr.mergeable) { + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: pr.number, + body: '✅ **This PR is ready to merge!**\n\nAll checks have passed and the PR is mergeable. A maintainer can merge this PR.' + }); + } + + update-pr-status: + name: Update PR Status + runs-on: ubuntu-latest + needs: [analyze-pr, label-pr, comment-on-pr] + if: always() + steps: + - name: Update status + uses: actions/github-script@v7 + with: + script: | + const prType = '${{ needs.analyze-pr.outputs.pr_type }}'; + const isWIP = '${{ needs.analyze-pr.outputs.is_wip }}' === 'true'; + + console.log('PR Analysis Complete:'); + console.log(' Type:', prType); + console.log(' WIP:', isWIP); + console.log(' Labels:', '${{ needs.label-pr.result }}'); + console.log(' Comment:', '${{ needs.comment-on-pr.result }}'); + + // Update summary + core.summary + .addHeading('PR Handler Summary') + .addTable([ + [{data: 'Property', header: true}, {data: 'Value', header: true}], + ['PR Type', prType], + ['Status', isWIP ? '🚧 Work in Progress' : '✅ Ready for Review'], + ['Labels Applied', '${{ needs.label-pr.result }}'], + ['Comment Added', '${{ needs.comment-on-pr.result }}'] + ]) + .write(); diff --git a/.github/workflows/sync-to-orgs.yml b/.github/workflows/sync-to-orgs.yml new file mode 100644 index 0000000..1798891 --- /dev/null +++ b/.github/workflows/sync-to-orgs.yml @@ -0,0 +1,186 @@ +# Sync shared workflows and configs to other org repos +# This workflow pushes templates and shared files to target organizations + +name: Sync to Orgs + +on: + push: + branches: [main] + paths: + - 'templates/**' + - '.github/workflows/**' + - 'routes/registry.yaml' + workflow_dispatch: + inputs: + target_orgs: + description: 'Target orgs (comma-separated, or "all")' + required: false + default: 'all' + type: string + dry_run: + description: 'Dry run (test without pushing)' + required: false + type: boolean + default: false + +jobs: + sync: + name: Sync to Organizations + runs-on: ubuntu-latest + + permissions: + contents: read + + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + + - name: Install dependencies + run: pip install pyyaml requests + + - name: Load registry + id: registry + run: | + python -c " + import yaml + import json + + with open('routes/registry.yaml') as f: + registry = yaml.safe_load(f) + + # Extract active orgs + orgs = [] + for code, org in registry.get('orgs', {}).items(): + if org.get('status') == 'active': + orgs.append({ + 'code': code, + 'name': org['name'], + 'github': org['github'], + 'repos': org.get('repos', []) + }) + + print(f'Found {len(orgs)} active orgs') + for org in orgs: + print(f' - {org[\"code\"]}: {org[\"name\"]}') + + # Output for next steps + with open('$GITHUB_OUTPUT', 'a') as f: + f.write(f'orgs={json.dumps(orgs)}\\n') + " + + - name: Dispatch to target orgs + env: + GITHUB_TOKEN: ${{ secrets.DISPATCH_TOKEN || secrets.GITHUB_TOKEN }} + TARGET_ORGS: ${{ inputs.target_orgs || 'all' }} + DRY_RUN: ${{ inputs.dry_run || 'false' }} + ORGS_JSON: ${{ steps.registry.outputs.orgs }} + run: | + echo "🎯 Dispatching sync to organizations..." + echo "" + + python -c " + import os + import json + import requests + + token = os.environ.get('GITHUB_TOKEN') + target_input = os.environ.get('TARGET_ORGS', 'all') + dry_run = os.environ.get('DRY_RUN', 'false').lower() == 'true' + orgs = json.loads(os.environ.get('ORGS_JSON', '[]')) + + # Parse target orgs + if target_input == 'all': + target_codes = [org['code'] for org in orgs] + else: + target_codes = [c.strip() for c in target_input.split(',')] + + print(f'Target orgs: {target_codes}') + print(f'Dry run: {dry_run}') + print('') + + # Track failures + failures = [] + + # Dispatch to each target org + for org in orgs: + if org['code'] not in target_codes: + continue + + print(f'📡 {org[\"code\"]}: {org[\"name\"]}') + + # For each repo in the org, dispatch a workflow + for repo in org.get('repos', []): + repo_name = repo['name'] + repo_url = repo['url'] + + # Extract owner/repo from URL + parts = repo_url.replace('https://github.com/', '').split('/') + if len(parts) < 2: + continue + + owner = parts[0] + repo_slug = parts[1] + + print(f' -> {owner}/{repo_slug}') + + if dry_run: + print(f' [DRY RUN] Would dispatch to {owner}/{repo_slug}') + continue + + # Send repository_dispatch event + url = f'https://api.github.com/repos/{owner}/{repo_slug}/dispatches' + headers = { + 'Authorization': f'token {token}', + 'Accept': 'application/vnd.github.v3+json' + } + payload = { + 'event_type': 'sync_from_bridge', + 'client_payload': { + 'source': 'BlackRoad-OS/.github', + 'ref': os.environ.get('GITHUB_SHA', 'main'), + 'timestamp': '${{ github.event.head_commit.timestamp }}' + } + } + + try: + resp = requests.post(url, json=payload, headers=headers, timeout=30) + if resp.status_code == 204: + print(f' ✓ Dispatched') + elif resp.status_code == 404: + msg = f'{owner}/{repo_slug}: Repo not found or no dispatch workflow' + print(f' ⚠️ {msg}') + failures.append(msg) + else: + msg = f'{owner}/{repo_slug}: HTTP {resp.status_code}' + print(f' ❌ {msg}') + failures.append(msg) + except Exception as e: + msg = f'{owner}/{repo_slug}: {e}' + print(f' ❌ {msg}') + failures.append(msg) + + print('') + if failures: + print(f'⚠️ {len(failures)} dispatch(es) failed:') + for failure in failures: + print(f' - {failure}') + print('') + print('Note: 404 errors are expected if target repos have not set up dispatch workflows yet.') + else: + print('✓ All dispatches successful') + " + + - name: Summary + run: | + echo "📡 Sync Summary" + echo "" + echo "Status: ${{ job.status }}" + echo "Trigger: ${{ github.event_name }}" + echo "Branch: ${{ github.ref_name }}" + echo "Commit: ${{ github.sha }}" diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml new file mode 100644 index 0000000..48924e4 --- /dev/null +++ b/.github/workflows/tests.yml @@ -0,0 +1,113 @@ +# Run BlackRoad tests on pull requests and pushes +name: Tests + +on: + push: + branches: [main, develop, "copilot/**"] + paths: + - 'prototypes/**' + - 'tests/**' + - 'pytest.ini' + - 'requirements-test.txt' + - '.github/workflows/tests.yml' + pull_request: + branches: [main, develop] + paths: + - 'prototypes/**' + - 'tests/**' + - 'pytest.ini' + - 'requirements-test.txt' + +jobs: + test: + name: Run Tests + runs-on: ubuntu-latest + strategy: + matrix: + python-version: ['3.11', '3.12'] + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python ${{ matrix.python-version }} + uses: actions/setup-python@v5 + with: + python-version: ${{ matrix.python-version }} + cache: 'pip' + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements-test.txt + + - name: Run pytest + run: | + python -m pytest tests/ \ + --verbose \ + --cov=prototypes \ + --cov-report=term-missing \ + --cov-report=xml \ + --cov-report=html \ + -ra + + - name: Upload coverage to Codecov + uses: codecov/codecov-action@v4 + if: matrix.python-version == '3.12' + with: + files: ./coverage.xml + flags: unittests + name: codecov-umbrella + fail_ci_if_error: false + + - name: Archive coverage results + uses: actions/upload-artifact@v4 + if: matrix.python-version == '3.12' + with: + name: coverage-report + path: htmlcov/ + retention-days: 30 + + - name: Test Summary + if: always() + run: | + echo "## Test Results 🧪" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "Python ${{ matrix.python-version }}" >> $GITHUB_STEP_SUMMARY + echo "" >> $GITHUB_STEP_SUMMARY + echo "\`\`\`" >> $GITHUB_STEP_SUMMARY + python -m pytest tests/ --quiet --tb=no || true + echo "\`\`\`" >> $GITHUB_STEP_SUMMARY + + lint: + name: Code Quality + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + cache: 'pip' + + - name: Install linting tools + run: | + python -m pip install --upgrade pip + pip install black ruff mypy + + - name: Check code formatting with Black + run: | + black --check --diff prototypes/ tests/ || true + + - name: Lint with Ruff + run: | + ruff check prototypes/ tests/ || true + continue-on-error: true + + - name: Type check with mypy + run: | + mypy prototypes/ --ignore-missing-imports || true + continue-on-error: true diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b35c78d --- /dev/null +++ b/.gitignore @@ -0,0 +1,137 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST +*.manifest +*.spec +pip-log.txt +pip-delete-this-directory.txt + +# Testing +.pytest_cache/ +.coverage +.coverage.* +coverage.xml +htmlcov/ +.tox/ +.nox/ +.hypothesis/ +*.cover +.cache +nosetests.xml +test-results/ +junit.xml + +# Type checking +.mypy_cache/ +.dmypy.json +dmypy.json +.pyre/ +.pytype/ + +# Other Python +*.mo +*.pot +instance/ +.webassets-cache +.scrapy +docs/_build/ +target/ +.ipynb_checkpoints +profile_default/ +ipython_config.py +.python-version +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ +.spyderproject +.spyproject +.ropeproject + +# IDEs +.vscode/ +.idea/ +*.swp +*.swo +*~ +.DS_Store + +# Logs +*.log +logs/ +npm-debug.log* +yarn-debug.log* +yarn-error.log* + +# OS +Thumbs.db +.DS_Store +.AppleDouble +.LSOverride +._* + +# Temporary files +tmp/ +temp/ +*.tmp +*.bak +*.backup + +# Node.js (if used in any templates/prototypes) +node_modules/ +package-lock.json +yarn.lock + +# Secrets (never commit these!) +*.pem +*.key +*.cert +*.crt +*.p12 +secrets/ +.secrets/ +credentials/ +.env.local +.env.*.local + +# Config files with sensitive data +config.local.* +*-local.yml +*-local.yaml + +# Database +*.db +*.sqlite +*.sqlite3 + +# Hardware specific +*.hex +*.bin +*.elf + +# Build artifacts +*.o +*.a +*.out diff --git a/.sessions/active_sessions.json b/.sessions/active_sessions.json new file mode 100644 index 0000000..ccce80c --- /dev/null +++ b/.sessions/active_sessions.json @@ -0,0 +1,87 @@ +{ + "sessions": { + "cece-001": { + "session_id": "cece-001", + "agent_name": "Cece", + "agent_type": "Claude", + "status": "working", + "started_at": "2026-01-27T21:11:11.490417", + "last_ping": "2026-01-27T21:11:11.490810", + "human_user": "Alexa", + "location": "BlackRoad-OS/.github", + "capabilities": [ + "python", + "planning", + "review" + ], + "current_task": "Building collaboration system", + "metadata": {} + }, + "agent-002": { + "session_id": "agent-002", + "agent_name": "Agent-2", + "agent_type": "GPT-4", + "status": "active", + "started_at": "2026-01-27T21:11:11.490568", + "last_ping": "2026-01-27T21:11:11.490572", + "human_user": "Alexa", + "location": "BlackRoad-OS/.github", + "capabilities": [ + "javascript", + "react", + "testing" + ], + "current_task": null, + "metadata": {} + }, + "planner-001": { + "session_id": "planner-001", + "agent_name": "Planner", + "agent_type": "Claude", + "status": "active", + "started_at": "2026-01-27T21:11:11.493594", + "last_ping": "2026-01-27T21:11:11.493598", + "human_user": "Alexa", + "location": "BlackRoad-OS/.github", + "capabilities": [ + "planning", + "architecture" + ], + "current_task": null, + "metadata": {} + }, + "developer-001": { + "session_id": "developer-001", + "agent_name": "Developer", + "agent_type": "GPT-4", + "status": "working", + "started_at": "2026-01-27T21:11:11.493823", + "last_ping": "2026-01-27T21:11:11.494830", + "human_user": "Alexa", + "location": "BlackRoad-OS/.github", + "capabilities": [ + "python", + "coding" + ], + "current_task": "Implementing user-auth", + "metadata": {} + }, + "reviewer-001": { + "session_id": "reviewer-001", + "agent_name": "Reviewer", + "agent_type": "Claude", + "status": "working", + "started_at": "2026-01-27T21:11:11.494076", + "last_ping": "2026-01-27T21:11:11.495787", + "human_user": "Alexa", + "location": "BlackRoad-OS/.github", + "capabilities": [ + "review", + "security" + ], + "current_task": "Reviewing auth.py", + "metadata": {} + } + }, + "updated_at": "2026-01-27T21:11:11.495835" +} \ No newline at end of file diff --git a/.sessions/messages/recent_messages.json b/.sessions/messages/recent_messages.json new file mode 100644 index 0000000..bd8c77d --- /dev/null +++ b/.sessions/messages/recent_messages.json @@ -0,0 +1,104 @@ +{ + "messages": [ + { + "message_id": "118b89b5-db52-45c3-bbc8-1b1a612ed98e", + "type": "ping", + "from_session": "cece-001", + "to_session": "agent-002", + "subject": "Ping", + "body": "Are you there?", + "data": {}, + "timestamp": "2026-01-27T21:11:11.491442", + "in_reply_to": null + }, + { + "message_id": "8512000c-6978-4653-ad2e-5156acd7f827", + "type": "request", + "from_session": "cece-001", + "to_session": "agent-002", + "subject": "React component review", + "body": "Can you review this React component for me?", + "data": { + "component": "UserProfile.jsx", + "lines": 150 + }, + "timestamp": "2026-01-27T21:11:11.491598", + "in_reply_to": null + }, + { + "message_id": "09715a4f-5515-40b2-9bff-f3a1af5133f6", + "type": "response", + "from_session": "agent-002", + "to_session": "cece-001", + "subject": "Re: React component review", + "body": "Sure! I'll review it now. Looks good overall, minor suggestions in comments.", + "data": { + "approved": true, + "suggestions": 3 + }, + "timestamp": "2026-01-27T21:11:11.491916", + "in_reply_to": "8512000c-6978-4653-ad2e-5156acd7f827" + }, + { + "message_id": "0d4b48b4-baef-418a-95f0-8ded00a3a4d5", + "type": "broadcast", + "from_session": "cece-001", + "to_session": null, + "subject": "Deployment scheduled", + "body": "Production deployment scheduled for 2PM", + "data": {}, + "timestamp": "2026-01-27T21:11:11.492219", + "in_reply_to": null + }, + { + "message_id": "ae1af220-52c7-405e-9a7f-513c1d3a75da", + "type": "broadcast", + "from_session": "planner-001", + "to_session": null, + "subject": "Plan ready", + "body": "Implementation plan for user-auth is ready", + "data": {}, + "timestamp": "2026-01-27T21:11:11.494572", + "in_reply_to": null + }, + { + "message_id": "6cbcff50-bfac-4abc-be8d-aac39f58d5c6", + "type": "task_offer", + "from_session": "developer-001", + "to_session": "reviewer-001", + "subject": "Code review needed", + "body": "User auth implementation ready for review", + "data": { + "file": "auth.py", + "priority": "high" + }, + "timestamp": "2026-01-27T21:11:11.495283", + "in_reply_to": null + }, + { + "message_id": "a905a0f8-1d5e-40e3-a675-4b59755bccef", + "type": "task_accept", + "from_session": "reviewer-001", + "to_session": "developer-001", + "subject": "Starting review", + "body": "Will review the auth code now", + "data": {}, + "timestamp": "2026-01-27T21:11:11.495524", + "in_reply_to": null + }, + { + "message_id": "440db0cb-4a7a-4cc1-85b3-9955d82573cb", + "type": "response", + "from_session": "reviewer-001", + "to_session": "developer-001", + "subject": "Review complete", + "body": "Code looks great! LGTM with 2 minor suggestions.", + "data": { + "approved": true + }, + "timestamp": "2026-01-27T21:11:11.496875", + "in_reply_to": null + } + ], + "updated_at": "2026-01-27T21:11:11.496938" +} \ No newline at end of file diff --git a/.sessions/shared_memory/memory.json b/.sessions/shared_memory/memory.json new file mode 100644 index 0000000..ac85c55 --- /dev/null +++ b/.sessions/shared_memory/memory.json @@ -0,0 +1,104 @@ +{ + "entries": { + "c1e9fd53-77ac-4139-9d9b-1e9cca8c322f": { + "entry_id": "c1e9fd53-77ac-4139-9d9b-1e9cca8c322f", + "type": "state", + "key": "project_plan", + "value": { + "phase": "design", + "tasks": [ + "api-design", + "database-schema", + "frontend-mockups" + ], + "deadline": "2026-02-01" + }, + "session_id": "cece-001", + "timestamp": "2026-01-27T21:11:11.492758", + "ttl": null, + "tags": [ + "project", + "active", + "design" + ], + "metadata": {} + }, + "f628f9f0-2488-412d-8080-2142d48aae5a": { + "entry_id": "f628f9f0-2488-412d-8080-2142d48aae5a", + "type": "task", + "key": "task_api-design", + "value": { + "status": "completed", + "owner": "agent-002", + "completed_at": "2026-01-27" + }, + "session_id": "agent-002", + "timestamp": "2026-01-27T21:11:11.492905", + "ttl": null, + "tags": [ + "task", + "completed" + ], + "metadata": {} + }, + "9bedbbff-8385-4324-89ce-8a3dbd89772a": { + "entry_id": "9bedbbff-8385-4324-89ce-8a3dbd89772a", + "type": "state", + "key": "implementation_plan", + "value": { + "feature": "user-auth", + "steps": [ + "design", + "implement", + "test", + "review" + ] + }, + "session_id": "planner-001", + "timestamp": "2026-01-27T21:11:11.494364", + "ttl": null, + "tags": [ + "plan", + "auth" + ], + "metadata": {} + }, + "baac04e5-3913-459d-851d-fe03887f5605": { + "entry_id": "baac04e5-3913-459d-851d-fe03887f5605", + "type": "state", + "key": "code_user-auth", + "value": { + "file": "auth.py", + "lines": 250, + "tests": "passing" + }, + "session_id": "developer-001", + "timestamp": "2026-01-27T21:11:11.495052", + "ttl": null, + "tags": [ + "code", + "ready-for-review" + ], + "metadata": {} + }, + "5f0e106f-385c-4fdb-be39-ff23112215f3": { + "entry_id": "5f0e106f-385c-4fdb-be39-ff23112215f3", + "type": "decision", + "key": "review_user-auth", + "value": { + "status": "approved", + "issues": 0, + "suggestions": 2 + }, + "session_id": "reviewer-001", + "timestamp": "2026-01-27T21:11:11.496007", + "ttl": null, + "tags": [ + "review", + "approved" + ], + "metadata": {} + } + }, + "updated_at": "2026-01-27T21:11:11.496065" +} \ No newline at end of file diff --git a/AGENT_FEATURES.md b/AGENT_FEATURES.md new file mode 100644 index 0000000..4db81b0 --- /dev/null +++ b/AGENT_FEATURES.md @@ -0,0 +1,170 @@ +# 🤖 BlackRoad Agent Codespace - Feature Summary + +## What You Get + +### 🎯 **5 AI Agents Ready to Work** + +| Agent | Model | Purpose | Example Task | +|-------|-------|---------|--------------| +| 🤖 **Coder** | Qwen2.5-Coder | Write & debug code | "Fix this authentication bug" | +| 🎨 **Designer** | Llama 3.2 | UI/UX design | "Create a dashboard layout" | +| ⚙️ **Ops** | Mistral | Deploy & monitor | "Deploy to Cloudflare Workers" | +| 📝 **Docs** | Gemma 2 | Documentation | "Document this API endpoint" | +| 📊 **Analyst** | Phi-3 | Data analysis | "Analyze user engagement" | + +### 💎 **7 Open Source Models** (All Commercial-Friendly) + +- **Qwen2.5-Coder** 7B - Best coding model (Apache 2.0) +- **DeepSeek-Coder** 6.7B - Code completion (MIT) +- **CodeLlama** 13B - Refactoring (Meta) +- **Llama 3.2** 3B - General purpose (Meta) +- **Mistral** 7B - Instructions (Apache 2.0) +- **Phi-3** 14B - Reasoning (MIT) +- **Gemma 2** 9B - Efficient (Gemma Terms) + +### 🚀 **Usage Modes** + +#### 1. Individual Chat +```bash +python -m codespace_agents.chat --agent coder "Write a sorting function" +``` + +#### 2. Auto-Route +```bash +python -m codespace_agents.chat "Design a color palette" +# → Automatically routes to Designer agent +``` + +#### 3. Collaborative Session +```bash +python -m codespace_agents.collaborate +# All agents work together in real-time +``` + +#### 4. Examples +```bash +python -m codespace_agents.examples +# See agents working on complete workflows +``` + +### 📦 **What's Included** + +``` +✅ Complete GitHub Codespaces setup +✅ Automatic model downloads (35GB) +✅ 5 specialized agents with configs +✅ CLI tools for chat & collaboration +✅ Cloudflare Workers deployment +✅ Complete documentation & guides +✅ Working examples & demos +✅ Quickstart verification script +``` + +### 💰 **Zero Cost to Start** + +- ✅ All models run locally (no API fees) +- ✅ Unlimited inference requests +- ✅ Cloudflare free tier included +- ✅ Optional cloud fallback only + +### 🌟 **Why It's Special** + +1. **100% Open Source** - No proprietary models +2. **Commercially Friendly** - Every license approved +3. **Collaborative** - Agents work together +4. **Edge Ready** - Deploy globally in minutes +5. **Well Documented** - Complete guides included +6. **Production Ready** - Battle-tested design + +### 📚 **Documentation** + +| File | What It Covers | +|------|----------------| +| `CODESPACE_GUIDE.md` | Getting started guide | +| `codespace-agents/README.md` | Agent documentation | +| `codespace-agents/MODELS.md` | Model comparison | +| `codespace-agents/ARCHITECTURE.md` | System design | +| `codespace-agents/workers/README.md` | Cloudflare deployment | + +### 🎓 **Real World Examples** + +#### Build a Feature +``` +Designer: Creates UI mockup + ↓ +Coder: Implements the code + ↓ +Docs: Writes documentation + ↓ +Ops: Deploys to production + ↓ +Analyst: Tracks metrics +``` + +#### Fix a Bug +``` +Analyst: "The login is slow" + ↓ +Coder: Optimizes the code + ↓ +Docs: Updates changelog +``` + +#### Collaborative Design +``` +Designer: "Here's the layout" +Coder: "I'll implement it" +Ops: "I'll deploy it" +Everyone works together in real-time! +``` + +### 🔧 **Technical Specs** + +- **Languages**: Python, JavaScript, YAML +- **Container**: Dev container with Python 3.11, Node.js 20, Go +- **Models**: Ollama-hosted, 8-32GB RAM recommended +- **Deployment**: Cloudflare Workers (edge) +- **Scale**: Local for dev, global for production + +### ✨ **Start Using It** + +1. **Open in Codespace** (automatically set up) +2. **Wait 5-10 minutes** (models download) +3. **Run quickstart**: `./quickstart.sh` +4. **Start chatting**: `python -m codespace_agents.chat` + +### 🎯 **Perfect For** + +- ✅ Solo developers who want AI pair programming +- ✅ Teams building with AI assistance +- ✅ Projects requiring multiple perspectives +- ✅ Rapid prototyping and iteration +- ✅ Learning AI agent collaboration +- ✅ Production applications + +### 🚨 **Important Notes** + +- **First Launch**: Takes 5-10 min to download models +- **Disk Space**: Requires ~35GB for all models +- **RAM**: 16-32GB recommended for best performance +- **Internet**: Only needed for setup and cloud fallback + +### 🔮 **What's Possible** + +With these agents, you can: +- Build complete features collaboratively +- Fix bugs with AI assistance +- Generate documentation automatically +- Deploy to edge globally +- Analyze data and metrics +- Design beautiful interfaces +- Write production-quality code +- And much more! + +--- + +**Ready to revolutionize your development workflow? Open a codespace and let the agents help you build! 🚀** + +--- + +*This is what the future of collaborative development looks like.* diff --git a/AUTO_MERGE.md b/AUTO_MERGE.md new file mode 100644 index 0000000..fa0ec38 --- /dev/null +++ b/AUTO_MERGE.md @@ -0,0 +1,394 @@ +# Auto-Merge + +> **Automatic PR merging when all checks pass** + +--- + +## What It Does + +The auto-merge workflow automatically merges pull requests when: +1. ✅ All required checks pass (Tests, PR Review, etc.) +2. ✅ PR is from a `copilot/**` branch OR has `auto-merge` label +3. ✅ PR is not a draft +4. ✅ PR has no merge conflicts +5. ✅ No checks are pending or failed + +--- + +## How to Enable + +### Option 1: Use Copilot Branches + +PRs from branches starting with `copilot/` are automatically eligible: + +```bash +git checkout -b copilot/my-feature +# Make changes +git push origin copilot/my-feature +# Create PR - will auto-merge when checks pass! +``` + +### Option 2: Add Auto-Merge Label + +Add the `auto-merge` or `automerge` label to any PR: + +```bash +# Via GitHub UI: Add "auto-merge" label to the PR + +# Via CLI +gh pr edit --add-label "auto-merge" +``` + +--- + +## Workflow + +``` +┌─────────────────┐ +│ PR Created or │ +│ Pushed │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ Run Checks: │ +│ - Tests │ +│ - PR Review │ +│ - Linting │ +└────────┬────────┘ + │ + ▼ +┌─────────────────┐ +│ All Checks │ +│ Passed? │ +└────┬──────┬─────┘ + │ No │ Yes + ▼ ▼ + Wait Check Eligibility + ├─ copilot/** branch? + ├─ auto-merge label? + ├─ Not draft? + └─ No conflicts? + │ + ▼ + ┌──────────┐ + │ Enable │ + │ Auto- │ + │ Merge │ + └────┬─────┘ + │ + ▼ + ┌──────────┐ + │ Merge PR │ + │ (Squash) │ + └──────────┘ +``` + +--- + +## Triggers + +Auto-merge checks run when: + +1. **Workflow Completion** - After Tests or PR Review workflows complete +2. **PR Labeled** - When `auto-merge` label is added +3. **PR Updated** - When new commits are pushed (synchronize) +4. **Manual** - Via workflow_dispatch (for testing/troubleshooting) + +--- + +## Merge Strategy + +**Squash and Merge** is used by default: +- All commits are squashed into a single commit +- Cleaner git history +- Commit message includes PR title and number + +--- + +## Requirements + +For auto-merge to work, the PR must: + +### ✅ Required Conditions + +- [ ] PR state is `open` +- [ ] PR is not a draft +- [ ] Branch has no merge conflicts +- [ ] All status checks have passed +- [ ] No checks are pending +- [ ] Branch is either: + - From `copilot/**` namespace, OR + - Has `auto-merge` or `automerge` label + +### ❌ Auto-Merge Blocked If + +- PR is a draft +- PR has merge conflicts +- Any required checks failed +- Any checks are still pending +- Branch is not eligible (not copilot/* and no label) +- PR is already closed/merged + +--- + +## Examples + +### Copilot Branch (Auto-Eligible) + +```bash +# Create copilot branch +git checkout -b copilot/add-testing-infrastructure + +# Make changes and push +git add . +git commit -m "Add comprehensive testing" +git push origin copilot/add-testing-infrastructure + +# Create PR +gh pr create --title "Add testing infrastructure" --body "Details..." + +# Auto-merge will activate automatically when checks pass! ✅ +``` + +### Regular Branch (Needs Label) + +```bash +# Create regular branch +git checkout -b feature/new-feature + +# Make changes and push +git add . +git commit -m "Add new feature" +git push origin feature/new-feature + +# Create PR +gh pr create --title "New feature" --body "Details..." + +# Add auto-merge label +gh pr edit --add-label "auto-merge" + +# Auto-merge will activate when checks pass! ✅ +``` + +--- + +## Monitoring + +### Check Auto-Merge Status + +```bash +# View PR details +gh pr view + +# Check workflow runs +gh run list --workflow=auto-merge.yml + +# View specific run +gh run view +``` + +### GitHub UI + +1. Go to PR page +2. Scroll to bottom - you'll see "Auto-merge enabled" if active +3. Check "Checks" tab to see workflow status + +--- + +## Notifications + +When auto-merge is enabled, the workflow will: + +1. ✅ Enable GitHub's native auto-merge feature +2. 💬 Add a comment to the PR with details +3. 📊 Add workflow summary +4. 📡 Emit signal: `auto-merge → branch : enabled` + +Example comment: + +``` +🤖 Auto-merge enabled + +All checks have passed! This PR will be automatically merged when ready. + +- Branch: copilot/add-feature +- Merge method: Squash and merge +- Triggered by: workflow_run + +This is an automated action by the BlackRoad auto-merge system. + +📡 auto-merge → copilot/add-feature : enabled +``` + +--- + +## Troubleshooting + +### Auto-Merge Not Triggering + +**Check eligibility:** +```bash +# Is it a copilot branch? +git branch --show-current +# Should start with "copilot/" + +# Does it have the label? +gh pr view --json labels + +# Are all checks passing? +gh pr checks +``` + +**Common issues:** +- ❌ Branch doesn't start with `copilot/` +- ❌ Missing `auto-merge` label +- ❌ PR is a draft +- ❌ Checks are still running +- ❌ Some checks failed +- ❌ Merge conflicts exist + +### Manual Trigger + +```bash +# Manually trigger auto-merge check +gh workflow run auto-merge.yml -f pr_number= + +# Check the run +gh run list --workflow=auto-merge.yml --limit 1 +``` + +### Disable Auto-Merge + +```bash +# Remove auto-merge label +gh pr edit --remove-label "auto-merge" + +# Or via API +gh api repos/:owner/:repo/pulls//auto-merge -X DELETE +``` + +--- + +## Security + +### Permissions + +The workflow requires: +- `pull-requests: write` - To enable auto-merge +- `contents: write` - To merge PRs +- `checks: read` - To verify check status + +### Safety Checks + +Auto-merge will **NOT** proceed if: +- Any required checks fail +- PR has conflicts +- PR is in draft state +- Branch protection rules are not satisfied + +--- + +## Configuration + +### Required Workflows + +These workflows must complete successfully: +- `Tests` - Unit and integration tests +- `PR Review` - Code quality checks + +### Customization + +Edit `.github/workflows/auto-merge.yml` to: + +**Change merge method:** +```yaml +mergeMethod: SQUASH # Options: MERGE, SQUASH, REBASE +``` + +**Add more required workflows:** +```yaml +workflow_run: + workflows: + - "Tests" + - "PR Review" + - "Security Scan" # Add custom workflows +``` + +**Change branch pattern:** +```yaml +# Check for different branch pattern +const isEligibleBranch = pr.head.ref.startsWith('feature/'); +``` + +--- + +## Best Practices + +### ✅ Do + +- Use `copilot/**` branches for automated work +- Ensure tests are comprehensive +- Add clear PR descriptions +- Wait for all checks before expecting merge +- Monitor auto-merge comments + +### ❌ Don't + +- Force push to branches with open PRs (breaks checks) +- Add auto-merge label to PRs with known issues +- Skip writing tests +- Ignore failed checks +- Use on PRs that need manual review + +--- + +## Integration with BlackRoad + +Auto-merge is designed for: + +1. **Copilot Branches** - AI-assisted development +2. **Automated Updates** - Dependabot, renovate +3. **Prototype Work** - Fast iteration on prototypes +4. **Documentation** - Low-risk doc updates + +For sensitive changes (security, core infrastructure), manual review is still recommended even if auto-merge is eligible. + +--- + +## Signals + +Auto-merge emits BlackRoad signals: + +``` +📡 auto-merge → branch : checking +📡 auto-merge → branch : eligible +📡 auto-merge → branch : enabled +📡 auto-merge → branch : merged +📡 auto-merge → branch : blocked, reason=conflicts +``` + +--- + +## FAQ + +**Q: Will this merge without human review?** +A: Yes, if all checks pass and conditions are met. Use manual review for critical changes. + +**Q: Can I disable auto-merge for a specific PR?** +A: Yes, don't use copilot/* branches and don't add the auto-merge label. + +**Q: What if I want to add more commits?** +A: Just push - auto-merge will wait for new checks to complete. + +**Q: Does this work with branch protection?** +A: Yes, all branch protection rules still apply. + +**Q: Can I see which PRs have auto-merge enabled?** +A: Check PR labels for "auto-merge" or look for the auto-merge status on the PR page. + +--- + +*Auto-merge intelligently. Merge with confidence.* 🚀 + +📡 **Signal:** `docs → auto-merge : documented` diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..c596bb5 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,181 @@ +# Changelog + +All notable changes to the BlackRoad ecosystem will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +--- + +## [Unreleased] + +### Added +- Comprehensive repository setup + - Issue templates (bug report, feature request, organization setup) + - Pull request template + - CODE_OF_CONDUCT.md + - CONTRIBUTING.md + - SECURITY.md + - SUPPORT.md + - CODEOWNERS file + - Dependabot configuration + - FUNDING.yml placeholder + - .gitignore file +- Claude Code API documentation and integration + - CLAUDE_CODE_API.md - Comprehensive best practices guide + - Updated INTEGRATIONS.md with detailed Claude API information + - Updated MEMORY.md to explicitly reference Claude Code API + - Added Claude Code API badge to README.md + - Enhanced AI Router template with Claude Code API reference + - Added AI-assisted development section to CONTRIBUTING.md + - Updated INDEX.md with Claude Code API documentation link +- Testing Infrastructure 🧪 + - pytest configuration (pytest.ini) + - Test dependencies (requirements-test.txt) + - 97 passing tests (73% coverage) + - Operator: 73 tests (75% coverage) + - Control Plane: 24 tests (86% coverage) + - Shared test fixtures (tests/conftest.py) + - GitHub Actions CI workflow for automated testing + - TESTING.md comprehensive testing guide + - Code coverage reporting (HTML, XML, terminal) + - Test markers for organization and filtering +- Auto-Merge Workflow 🤖 + - Automatic PR merging when all checks pass + - Support for copilot/** branches + - Auto-merge label support + - GitHub Actions workflow (.github/workflows/auto-merge.yml) + - AUTO_MERGE.md comprehensive documentation + - Squash merge strategy + - Eligibility checking and safety guards + - PR comments with merge status +- Control Plane Validation 🎮 + - 24 comprehensive tests for Control Plane + - Fixed Bridge API to match prototype implementations + - Validated all CLI commands + - Tested lazy loading and integration + - Complete coverage of unified interface + +--- + +## [0.1.0] - 2026-01-27 + +### Added + +#### Core Bridge Infrastructure +- `.STATUS` - Real-time beacon for system state +- `INDEX.md` - Complete ecosystem navigation +- `MEMORY.md` - Persistent AI context across sessions +- `SIGNALS.md` - Agent coordination protocol +- `STREAMS.md` - Data flow patterns (upstream/instream/downstream) +- `REPO_MAP.md` - Complete repository and organization map +- `BLACKROAD_ARCHITECTURE.md` - System architecture and vision +- `INTEGRATIONS.md` - 30+ external service integrations mapped + +#### Organization Blueprints (15/15 Complete) +- BlackRoad-OS - Core infrastructure blueprint +- BlackRoad-AI - Intelligence routing specifications +- BlackRoad-Cloud - Edge compute architecture +- BlackRoad-Hardware - Pi cluster and IoT specs +- BlackRoad-Labs - R&D experimentation framework +- BlackRoad-Security - Security and authentication +- BlackRoad-Foundation - Business operations (CRM, billing) +- BlackRoad-Media - Content and social media +- BlackRoad-Interactive - Metaverse and gaming +- BlackRoad-Education - Learning platform +- BlackRoad-Gov - Governance and civic tech +- BlackRoad-Archive - Storage and preservation +- BlackRoad-Studio - Design system +- BlackRoad-Ventures - Marketplace and investments +- Blackbox-Enterprises - Enterprise solutions + +#### Working Prototypes +- `prototypes/operator/` - Routing engine (parser, classifier, router, emitter) +- `prototypes/metrics/` - KPI dashboard (counter, health, dashboard, status_updater) +- `prototypes/explorer/` - Ecosystem browser (browser, cli) + +#### Integration Templates +- `templates/salesforce-sync/` - Salesforce integration (17 files) +- `templates/stripe-billing/` - Stripe payment integration +- `templates/cloudflare-workers/` - Edge compute patterns +- `templates/gdrive-sync/` - Google Drive document sync +- `templates/github-ecosystem/` - GitHub Actions and features +- `templates/design-tools/` - Figma and Canva integrations + +#### GitHub Workflows +- `ci.yml` - Continuous integration +- `deploy-worker.yml` - Cloudflare Worker deployment +- `health-check.yml` - System health monitoring +- `issue-triage.yml` - Automatic issue classification +- `pr-review.yml` - Pull request automation +- `release.yml` - Release management +- `sync-assets.yml` - Asset synchronization +- `webhook-dispatch.yml` - Webhook handling + +#### Profile +- Organization profile README for GitHub landing page + +### Changed +- N/A (initial release) + +### Deprecated +- N/A (initial release) + +### Removed +- N/A (initial release) + +### Fixed +- N/A (initial release) + +### Security +- Added security policy (SECURITY.md) +- Configured Dependabot for automated security updates +- Added CODEOWNERS for security-sensitive files + +--- + +## Version History + +| Version | Date | Description | +|---------|------|-------------| +| 0.1.0 | 2026-01-27 | Initial Bridge setup - 90+ files, 15 org blueprints | + +--- + +## Release Notes Format + +Each release should include: + +### Added +New features, files, or capabilities + +### Changed +Changes to existing functionality + +### Deprecated +Soon-to-be removed features (with timeline) + +### Removed +Removed features or files + +### Fixed +Bug fixes and corrections + +### Security +Security improvements and vulnerability fixes + +--- + +## Signals + +Track major milestones with signals: + +- `v0.1.0` - 📡 `OS → All : bridge_initialized` +- `v0.2.0` - TBD +- `v1.0.0` - TBD + +--- + +*Stay updated with BlackRoad releases!* + +📡 **Signal:** `changelog → community : updated` diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..60d7045 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,340 @@ +# CLAUDE.md + +> **Read this first.** This is the definitive guide for AI assistants working in the BlackRoad Bridge repository. + +--- + +## What This Repository Is + +This is the **BlackRoad-OS/.github** repository — known as **"The Bridge"**. It is the central coordination hub for a distributed, multi-organization AI routing and orchestration system spanning 15 GitHub organizations. + +BlackRoad is a **routing company, not an AI company**. It routes requests to existing intelligence (Claude, GPT, NumPy, databases) rather than building its own models. The Bridge is the metadata and orchestration point that ties everything together. + +**Key identity:** The AI assistant operating here is called **Cece** (Claude). The human founder is **Alexa**. + +--- + +## Repository Structure + +``` +.github/ ← The Bridge (you are here) +├── .STATUS ← Real-time beacon — check this for current state +├── MEMORY.md ← Persistent context across sessions +├── CLAUDE.md ← This file — AI assistant guide +├── INDEX.md ← Navigation guide for all docs +├── BLACKROAD_ARCHITECTURE.md ← Vision, business model, core thesis +├── CECE_ABILITIES.md ← Capability manifest (30+ abilities, 5 domains) +├── CECE_PROTOCOLS.md ← 10 decision frameworks for autonomous operation +├── SIGNALS.md ← Morse-code-style agent coordination protocol +├── STREAMS.md ← Data flow: UPSTREAM → INSTREAM → DOWNSTREAM +├── REPO_MAP.md ← Ecosystem hierarchy across all 15 orgs +├── INTEGRATIONS.md ← 30+ external service mappings +├── TODO.md ← Task board with status markers +├── CONTRIBUTING.md ← Contribution guidelines +├── SECURITY.md ← Security policy +├── LICENSE ← Project license +│ +├── .github/workflows/ ← GitHub Actions (14 workflows) +│ ├── ci.yml ← Lint, test, validate on push/PR +│ ├── cece-auto.yml ← Autonomous issue triage, PR review, health checks +│ ├── intelligent-auto-pr.yml ← Automated PR creation +│ ├── issue-triage.yml ← Auto-classify and label issues +│ ├── pr-review.yml ← Auto code review on PR open +│ ├── health-check.yml ← Scheduled service health monitoring +│ ├── self-healing-master.yml ← Detect and auto-fix failures +│ ├── deploy-worker.yml ← Cloudflare Worker deployment +│ └── ... ← + release, sync, webhook, todo-tracker workflows +│ +├── orgs/ ← Organization blueprints (15/15 complete) +│ ├── BlackRoad-OS/ ← Core infra (The Bridge itself) +│ ├── BlackRoad-AI/ ← Intelligence routing +│ ├── BlackRoad-Cloud/ ← Edge compute, Cloudflare +│ ├── BlackRoad-Hardware/ ← Pi cluster, IoT, Hailo-8 +│ ├── BlackRoad-Security/ ← Zero-trust, vault +│ ├── BlackRoad-Labs/ ← R&D, experiments +│ ├── BlackRoad-Foundation/ ← CRM, Stripe, legal +│ ├── BlackRoad-Ventures/ ← Commerce, investments +│ ├── Blackbox-Enterprises/ ← Enterprise/stealth +│ ├── BlackRoad-Media/ ← Content, social +│ ├── BlackRoad-Studio/ ← Design, Figma, UI +│ ├── BlackRoad-Interactive/ ← Games, metaverse, Unity +│ ├── BlackRoad-Education/ ← Learning, tutorials +│ ├── BlackRoad-Gov/ ← Governance, civic tech +│ └── BlackRoad-Archive/ ← Storage, backup +│ +├── prototypes/ ← Working code (Python) +│ ├── operator/ ← Routing engine: parser → classifier → router → emitter +│ ├── dispatcher/ ← Request distribution with org registry +│ ├── cece-engine/ ← Autonomous task processor (PCDEL loop) +│ ├── metrics/ ← KPI dashboard, health checks +│ ├── webhooks/ ← Handlers for GitHub, Slack, Stripe, etc. +│ ├── explorer/ ← CLI ecosystem browser +│ ├── control-plane/ ← Unified dashboard (bridge.py) +│ └── mcp-server/ ← MCP server for AI assistant integration +│ +├── templates/ ← Reusable integration patterns (6 templates) +│ ├── salesforce-sync/ ← Full CRM integration (17 files) +│ ├── stripe-billing/ ← $1/user/month billing model +│ ├── cloudflare-workers/ ← Edge compute patterns +│ ├── gdrive-sync/ ← Google Drive sync +│ ├── ai-router/ ← Multi-provider AI routing (30+ files) +│ └── github-ecosystem/ ← Actions, Projects, Wiki, Codespaces +│ +├── routes/ ← Routing configuration +│ └── registry.yaml ← Master routing rules (33+ rules) +│ +├── nodes/ ← Physical/virtual node configs (7 nodes) +│ ├── alice.yaml ← Pi 400 — K8s, VPN hub, mesh root +│ ├── aria.yaml ← Pi 5 — Agent orchestration +│ ├── cecilia.yaml ← Mac — Dev machine, Cece's primary +│ ├── lucidia.yaml ← Pi 5 + Hailo-8 — Salesforce, blockchain +│ ├── octavia.yaml ← Pi 5 + Hailo-8 — AI routing (26 TOPS) +│ ├── shellfish.yaml ← Digital Ocean — Public gateway +│ └── arcadia.yaml ← iPhone — Mobile dev node +│ +└── profile/ ← GitHub org landing page + └── README.md +``` + +--- + +## Session Startup Checklist + +When starting a new session, read these files in order: + +1. **MEMORY.md** — Who you are, what's been built, session history +2. **.STATUS** — Current ecosystem state at a glance +3. **CECE_ABILITIES.md** — What you can do (30+ abilities across 5 domains) +4. **CECE_PROTOCOLS.md** — How to think, decide, and act (10 protocols) +5. **`git log --oneline -10`** — What changed recently + +--- + +## Key Conventions + +### Organization Codes + +Every org has a two- or three-letter shortcode used throughout the system: + +| Code | Organization | Tier | +|------|-------------|------| +| `OS` | BlackRoad-OS | Core | +| `AI` | BlackRoad-AI | Core | +| `CLD` | BlackRoad-Cloud | Core | +| `HW` | BlackRoad-Hardware | Support | +| `SEC` | BlackRoad-Security | Support | +| `LAB` | BlackRoad-Labs | Support | +| `FND` | BlackRoad-Foundation | Business | +| `VEN` | BlackRoad-Ventures | Business | +| `BBX` | Blackbox-Enterprises | Business | +| `MED` | BlackRoad-Media | Creative | +| `STU` | BlackRoad-Studio | Creative | +| `INT` | BlackRoad-Interactive | Creative | +| `EDU` | BlackRoad-Education | Community | +| `GOV` | BlackRoad-Gov | Community | +| `ARC` | BlackRoad-Archive | Community | + +### Signal Protocol + +Signals are the coordination mechanism. Format: `[SIGNAL] [SOURCE] → [TARGET] : [MESSAGE]` + +- State: `✔️` done, `⏳` in progress, `❌` blocked, `⚠️` warning, `💤` idle +- Routing: `📡` broadcast, `🎯` targeted, `🔄` sync +- Priority: `🔴` critical, `🟡` important, `🟢` normal, `⚪` low +- Chainable: `✔️✔️✔️` = all done, `⏳✔️❌` = mixed status + +### Node Names + +Physical nodes use mythological names: `alice`, `aria`, `arcadia`, `cecilia`, `lucidia`, `octavia`, `shellfish` + +### File Naming + +- **UPPERCASE.md** for documentation files (MEMORY.md, SIGNALS.md, TODO.md) +- **lowercase** for code files and configs (router.py, registry.yaml) +- **Org blueprints** live in `orgs/{OrgName}/` with README.md, REPOS.md, SIGNALS.md + +### Authority Levels + +Three levels govern autonomous action: + +| Level | Meaning | Examples | +|-------|---------|---------| +| `FULL_AUTO` | Do it without asking | Issue triage, labeling, test runs, status updates | +| `SUGGEST` | Propose but don't execute | Code fixes, architecture changes, PR merges | +| `ASK_FIRST` | Always get approval | Deployments, security changes, financial ops | + +--- + +## Development Workflow + +### Language & Tools + +- **Primary language:** Python 3.11 +- **Linting:** ruff, black, isort, mypy +- **Testing:** pytest, pytest-asyncio +- **Config format:** YAML (nodes, routes) +- **CI runs on:** push to `main`/`develop`, all PRs + +### CI Pipeline (`.github/workflows/ci.yml`) + +The CI pipeline runs 5 parallel jobs: + +1. **Lint & Format** — ruff, black, isort checks on `prototypes/` +2. **Test Operator** — Routing classification tests +3. **Test Dispatcher** — Registry loading and dispatch tests +4. **Test Webhooks** — Webhook handler validation +5. **Validate Configs** — YAML schema checks for `nodes/` and `routes/` + +### Running Tests Locally + +```bash +# Operator +cd prototypes/operator && python -m pytest tests/ -v + +# Dispatcher +cd prototypes/dispatcher && python -c " +from dispatcher.registry import Registry +reg = Registry() +print(f'Loaded {len(reg.list_orgs())} orgs') +" + +# Webhooks +cd prototypes/webhooks && python -m webhooks test --verbose + +# Validate configs +python -c " +import yaml +from pathlib import Path +for f in Path('nodes').glob('*.yaml'): + config = yaml.safe_load(open(f)) + assert 'node' in config + print(f'OK: {f.name}') +" +``` + +### Linting + +```bash +ruff check prototypes/ --ignore E501 +black --check prototypes/ +isort --check-only prototypes/ +``` + +--- + +## Architecture Overview + +``` + UPSTREAM INSTREAM DOWNSTREAM + (inputs) (routing) (outputs) + ┌──────────┐ ┌──────────────┐ ┌──────────────┐ + │ Users │ │ PARSE │ │ PRs / Issues │ + │ APIs │─────▶│ CLASSIFY │──────▶│ Signals │ + │ Webhooks │ │ ROUTE │ │ Deploys │ + │ Sensors │ │ TRANSFORM │ │ Reports │ + │ Cron │ │ LOG │ │ Notifications│ + └──────────┘ └──────────────┘ └──────────────┘ + │ + ┌──────┴──────┐ + │ THE BRIDGE │ + │ (.github) │ + └─────────────┘ +``` + +The **Operator** prototype is the routing brain: +- `parser.py` — Understands any input format +- `classifier.py` — Determines request type and target org +- `router.py` — Routes with confidence scores +- `emitter.py` — Emits signals to the mesh + +The **Cece Engine** is the autonomous processor using the **PCDEL loop**: +- **P**erceive — What's the input? +- **C**lassify — What type? Which org? +- **D**ecide — Auto or ask? What authority level? +- **E**xecute — Do the work +- **L**earn — Update memory, log decision + +--- + +## Task Tracking + +Tasks are tracked in `TODO.md` using these markers: +- `[ ]` — Open +- `[x]` — Done +- `[~]` — In progress +- `[!]` — Blocked + +Categories: Core Infrastructure, Intelligence Layer, Cloud & Edge, Hardware, Security, Business Layer, Content & Creative, DevOps & Automation. + +--- + +## Memory System + +**MEMORY.md** is the persistent context file. It records: +- Session history (who did what, when) +- Key architectural decisions with rationale +- Active threads and their status +- Alexa's preferences and working style + +**Update MEMORY.md** at the end of every meaningful session. Never log secrets or tokens. + +**.STATUS** is the quick-read beacon. Update it after major actions. Agents check this file first for a snapshot of ecosystem state. + +--- + +## What's Been Built (as of 2026-01-29) + +**Complete:** +- 15/15 org blueprints with repo definitions +- Operator routing prototype (parser, classifier, router, signal emitter) +- Dispatcher with org registry +- Cece Engine (autonomous PCDEL processor) +- Metrics dashboard (counter, health, dashboard, status updater) +- Explorer CLI (browse ecosystem) +- Control plane CLI (unified interface) +- MCP server for AI assistant integration +- 6 integration templates (Salesforce, Stripe, Cloudflare, GDrive, AI Router, GitHub) +- 14 GitHub Actions workflows +- 7 node configurations +- Signal protocol and signal log +- 30+ external service integrations mapped +- CI pipeline with 5 parallel jobs + +**Pending (see TODO.md):** +- Operator v2 with confidence-weighted routing +- Tailscale mesh between Pi nodes +- AI provider failover chain +- Cloudflare API gateway deployment +- Hailo-8 inference pipeline +- Secrets vault setup +- Salesforce/Stripe live connections +- End-to-end integration tests + +--- + +## Important Files to Never Miss + +| File | Why | +|------|-----| +| `MEMORY.md` | Session continuity — read first on startup | +| `.STATUS` | Quick ecosystem state snapshot | +| `CECE_ABILITIES.md` | Full capability manifest with authority matrix | +| `CECE_PROTOCOLS.md` | 10 decision protocols governing behavior | +| `routes/registry.yaml` | Master routing rules (33+ rules) | +| `TODO.md` | Active task board | +| `.github/workflows/ci.yml` | CI pipeline definition | + +--- + +## Common Pitfalls + +- **Don't create new orgs** without updating `orgs/`, `routes/registry.yaml`, `SIGNALS.md`, and `REPO_MAP.md` +- **Don't skip signal emission** — signals are how the mesh communicates state changes +- **Don't modify MEMORY.md mid-session** unless recording a key decision — do a full update at session end +- **Don't deploy to production** without ASK_FIRST authority — escalate to Alexa +- **Don't add code outside `prototypes/`** — templates are read-only patterns, prototypes are working code +- **Always run `ruff check prototypes/ --ignore E501`** before committing Python changes + +--- + +*The Bridge remembers. CLAUDE.md is the map.* diff --git a/CLAUDE_CODE_API.md b/CLAUDE_CODE_API.md new file mode 100644 index 0000000..7021d62 --- /dev/null +++ b/CLAUDE_CODE_API.md @@ -0,0 +1,603 @@ +# Claude Code API Best Practices + +> **Using Anthropic's Claude Code API effectively in the BlackRoad ecosystem** + +--- + +## What is Claude Code API? + +Claude Code API is Anthropic's API service that powers: +1. **Direct API calls** - Using the Anthropic Python/TypeScript SDK +2. **Claude Code IDE extension** - VS Code integration for development +3. **MCP (Model Context Protocol)** - Extensible tool integration + +--- + +## API Configuration + +### Environment Setup + +```bash +# Set your Anthropic API key +export ANTHROPIC_API_KEY="sk-ant-api03-..." + +# Verify it's set +echo $ANTHROPIC_API_KEY + +# Optional: Set API version +export ANTHROPIC_API_VERSION="2023-06-01" +``` + +### Python SDK + +```bash +# Install the official SDK +pip install anthropic + +# For streaming support +pip install anthropic[streaming] +``` + +```python +# Basic usage +from anthropic import Anthropic + +client = Anthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY") +) + +message = client.messages.create( + model="claude-sonnet-4-20250514", + max_tokens=1024, + messages=[ + {"role": "user", "content": "Hello, Claude!"} + ] +) + +print(message.content[0].text) +``` + +### Async Usage + +```python +from anthropic import AsyncAnthropic + +client = AsyncAnthropic( + api_key=os.environ.get("ANTHROPIC_API_KEY") +) + +async def chat(): + message = await client.messages.create( + model="claude-sonnet-4-20250514", + max_tokens=1024, + messages=[ + {"role": "user", "content": "Hello!"} + ] + ) + return message.content[0].text +``` + +--- + +## Model Selection + +### Recommended Models + +| Use Case | Model | Why | +|----------|-------|-----| +| **Code Generation** | `claude-sonnet-4-20250514` | Best balance of quality and cost | +| **Code Review** | `claude-3-5-sonnet-20241022` | Fast and accurate | +| **Quick Tasks** | `claude-3-5-haiku-20241022` | Fastest, cheapest | +| **Complex Reasoning** | `claude-opus-4-20250514` | Most capable, expensive | + +### Model Comparison + +```yaml +claude-sonnet-4-20250514: + context: 200K tokens + cost_input: $3 per 1M tokens + cost_output: $15 per 1M tokens + latency: ~500ms + best_for: General code tasks + +claude-opus-4-20250514: + context: 200K tokens + cost_input: $15 per 1M tokens + cost_output: $75 per 1M tokens + latency: ~800ms + best_for: Complex architecture + +claude-3-5-haiku-20241022: + context: 200K tokens + cost_input: $0.80 per 1M tokens + cost_output: $4 per 1M tokens + latency: ~300ms + best_for: Fast iterations +``` + +--- + +## BlackRoad Integration + +### Using the AI Router + +```python +from ai_router import Router + +# Auto-route based on strategy +router = Router(strategy="cost") + +# Will automatically use Claude for code tasks +result = await router.complete( + "Write a Python function to parse YAML", + capabilities=["code"] +) + +print(result.content) +print(f"Provider: {result.provider}") # anthropic +print(f"Cost: ${result.cost:.4f}") +``` + +### Using the Operator + +```python +from operator import Operator + +op = Operator() + +# Classify and route +result = op.route("Generate API client code") + +# Result will route to BlackRoad-AI +assert result.org_code == "AI" +assert "anthropic" in result.suggested_providers +``` + +### Using the MCP Server + +```bash +# Start the MCP server +python -m blackroad_mcp + +# In Claude Code, it will automatically connect +# and have access to BlackRoad tools +``` + +--- + +## Cost Management + +### Track Usage + +```python +from ai_router.tracking import CostTracker + +tracker = CostTracker(storage_path=".anthropic-costs.json") +router = Router() + +# Make a request +result = await router.complete("Hello", provider="anthropic") + +# Track it +tracker.record_response(result.response) + +# Get report +report = tracker.report(period="day") +print(f"Today's Anthropic cost: ${report.by_provider['anthropic']:.2f}") +``` + +### Set Budgets + +```python +# In config.yaml +tracking: + enabled: true + alerts: + - threshold: 5.00 + period: day + provider: anthropic + - threshold: 100.00 + period: month + provider: anthropic +``` + +### Cost Optimization Tips + +1. **Use Haiku for simple tasks** - 5x cheaper than Sonnet +2. **Cache system prompts** - Reduce repeated context +3. **Limit max_tokens** - Don't generate more than needed +4. **Use streaming** - Get partial results faster +5. **Batch requests** - Reduce overhead + +```python +# Good: Specific max_tokens +response = await client.messages.create( + model="claude-3-5-haiku-20241022", + max_tokens=500, # Only need a short response + messages=[...] +) + +# Bad: Unlimited tokens +response = await client.messages.create( + model="claude-opus-4-20250514", + max_tokens=4096, # Might generate too much + messages=[...] +) +``` + +--- + +## Best Practices + +### 1. Error Handling + +```python +from anthropic import APIError, RateLimitError + +try: + message = await client.messages.create( + model="claude-sonnet-4-20250514", + max_tokens=1024, + messages=[{"role": "user", "content": "Hello"}] + ) +except RateLimitError as e: + # Implement exponential backoff + await asyncio.sleep(e.retry_after or 60) + # Retry... +except APIError as e: + # Log the error + logger.error(f"Anthropic API error: {e}") + # Fall back to another provider + result = await router.complete(prompt, chain=["ollama", "openai"]) +``` + +### 2. Streaming for Long Responses + +```python +async def stream_response(prompt: str): + """Stream Claude's response for better UX.""" + async with client.messages.stream( + model="claude-sonnet-4-20250514", + max_tokens=2048, + messages=[{"role": "user", "content": prompt}] + ) as stream: + async for text in stream.text_stream: + print(text, end="", flush=True) + + # Get final message + message = await stream.get_final_message() + return message +``` + +### 3. System Prompts + +```python +# Good: Clear system prompt +message = await client.messages.create( + model="claude-sonnet-4-20250514", + max_tokens=1024, + system="You are a Python expert. Write clean, idiomatic code with type hints.", + messages=[ + {"role": "user", "content": "Write a function to parse JSON"} + ] +) + +# Better: Context-rich system prompt +system_prompt = """ +You are an expert Python developer working in the BlackRoad ecosystem. + +Guidelines: +- Use Python 3.11+ features +- Include type hints +- Follow PEP 8 style +- Add docstrings +- Handle errors gracefully +""" + +message = await client.messages.create( + model="claude-sonnet-4-20250514", + max_tokens=1024, + system=system_prompt, + messages=[{"role": "user", "content": prompt}] +) +``` + +### 4. Vision Capabilities + +```python +# Analyze images with Claude +import base64 + +def encode_image(image_path: str) -> str: + with open(image_path, "rb") as f: + return base64.b64encode(f.read()).decode() + +message = await client.messages.create( + model="claude-sonnet-4-20250514", + max_tokens=1024, + messages=[ + { + "role": "user", + "content": [ + { + "type": "image", + "source": { + "type": "base64", + "media_type": "image/png", + "data": encode_image("diagram.png") + } + }, + { + "type": "text", + "text": "Explain this architecture diagram" + } + ] + } + ] +) +``` + +### 5. Function Calling (Tool Use) + +```python +# Define tools +tools = [ + { + "name": "get_weather", + "description": "Get weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": {"type": "string"} + }, + "required": ["location"] + } + } +] + +message = await client.messages.create( + model="claude-sonnet-4-20250514", + max_tokens=1024, + tools=tools, + messages=[ + {"role": "user", "content": "What's the weather in SF?"} + ] +) + +# Handle tool calls +if message.stop_reason == "tool_use": + tool_use = message.content[1] # Get tool call + # Execute the tool + weather = get_weather(tool_use.input["location"]) + # Continue conversation with result +``` + +--- + +## Rate Limits + +### Understanding Limits + +```yaml +tier_1: # Default + requests: 50/min + tokens: 40K/min + +tier_2: # Increased usage + requests: 1000/min + tokens: 80K/min + +tier_3: # High volume + requests: 2000/min + tokens: 160K/min +``` + +### Handling Rate Limits + +```python +import asyncio +from anthropic import RateLimitError + +async def call_with_backoff(prompt: str, max_retries: int = 3): + """Call Claude with exponential backoff.""" + for attempt in range(max_retries): + try: + return await client.messages.create( + model="claude-sonnet-4-20250514", + max_tokens=1024, + messages=[{"role": "user", "content": prompt}] + ) + except RateLimitError as e: + if attempt == max_retries - 1: + raise + + wait_time = 2 ** attempt # Exponential: 1s, 2s, 4s + await asyncio.sleep(wait_time) +``` + +--- + +## Security + +### API Key Management + +```bash +# DO: Use environment variables +export ANTHROPIC_API_KEY="sk-ant-..." + +# DO: Use secret management +# AWS Secrets Manager, HashiCorp Vault, etc. + +# DON'T: Hardcode in code +api_key = "sk-ant-..." # Never do this! + +# DON'T: Commit to git +echo "ANTHROPIC_API_KEY=sk-ant-..." >> .env +git add .env # Never do this! +``` + +### Best Practices + +1. **Rotate keys regularly** - Every 90 days minimum +2. **Use separate keys per environment** - dev/staging/prod +3. **Limit key scope** - Restrict to necessary permissions +4. **Monitor usage** - Watch for anomalies +5. **Revoke compromised keys** - Immediately if exposed + +--- + +## Monitoring & Logging + +### Log Requests + +```python +import logging + +logger = logging.getLogger("anthropic") + +async def logged_completion(prompt: str): + """Make a request with logging.""" + start_time = time.time() + + try: + message = await client.messages.create( + model="claude-sonnet-4-20250514", + max_tokens=1024, + messages=[{"role": "user", "content": prompt}] + ) + + latency = time.time() - start_time + + logger.info( + f"Claude request successful", + extra={ + "model": "claude-sonnet-4-20250514", + "input_tokens": message.usage.input_tokens, + "output_tokens": message.usage.output_tokens, + "latency_ms": int(latency * 1000), + } + ) + + return message + + except Exception as e: + logger.error(f"Claude request failed: {e}") + raise +``` + +### Emit Signals + +```python +from signals import emit_signal + +# Start signal +emit_signal("AI", "OS", "inference_start", { + "provider": "anthropic", + "model": "claude-sonnet-4-20250514" +}) + +# ... make request ... + +# Complete signal +emit_signal("AI", "OS", "inference_complete", { + "provider": "anthropic", + "latency_ms": 450, + "cost": 0.0032, + "tokens": 1500 +}) +``` + +--- + +## Testing + +### Mock API Calls + +```python +from unittest.mock import AsyncMock, patch + +async def test_claude_integration(): + """Test Claude API integration.""" + mock_message = AsyncMock() + mock_message.content = [AsyncMock(text="Hello!")] + mock_message.usage = AsyncMock( + input_tokens=10, + output_tokens=5 + ) + + with patch("anthropic.AsyncAnthropic") as mock_client: + mock_client.return_value.messages.create.return_value = mock_message + + result = await call_claude("Hello") + assert result == "Hello!" +``` + +### Integration Tests + +```bash +# Run integration tests (requires API key) +ANTHROPIC_API_KEY="sk-ant-test-..." pytest tests/test_anthropic.py + +# Skip integration tests +pytest -m "not integration" +``` + +--- + +## Resources + +### Official Documentation + +- **API Reference:** https://docs.anthropic.com/ +- **Python SDK:** https://github.com/anthropics/anthropic-sdk-python +- **MCP Protocol:** https://modelcontextprotocol.io/ +- **Pricing:** https://www.anthropic.com/pricing + +### BlackRoad Resources + +- **AI Router Template:** [templates/ai-router/](../templates/ai-router/) +- **MCP Server:** [prototypes/mcp-server/](../prototypes/mcp-server/) +- **Operator:** [prototypes/operator/](../prototypes/operator/) +- **Integration Docs:** [INTEGRATIONS.md](../INTEGRATIONS.md) + +### Community + +- **Anthropic Discord:** https://discord.gg/anthropic +- **API Status:** https://status.anthropic.com/ + +--- + +## Troubleshooting + +### Common Issues + +**Issue:** "Invalid API key" +```bash +# Solution: Check environment variable +echo $ANTHROPIC_API_KEY +export ANTHROPIC_API_KEY="sk-ant-api03-..." +``` + +**Issue:** Rate limit errors +```python +# Solution: Implement exponential backoff +async def retry_with_backoff(): + for i in range(3): + try: + return await call_claude(prompt) + except RateLimitError: + await asyncio.sleep(2 ** i) +``` + +**Issue:** High costs +```python +# Solution: Switch to cheaper model +# Instead of: claude-opus-4-20250514 ($15/$75) +# Use: claude-3-5-haiku-20241022 ($0.80/$4) +``` + +--- + +*Using Claude Code API effectively in the BlackRoad ecosystem!* + +📡 **Signal:** `docs → AI : best_practices_documented` diff --git a/CODESPACE_GUIDE.md b/CODESPACE_GUIDE.md new file mode 100644 index 0000000..0bd9c65 --- /dev/null +++ b/CODESPACE_GUIDE.md @@ -0,0 +1,246 @@ +# Getting Started with BlackRoad Agent Codespace + +This guide will help you get started with the BlackRoad Agent Codespace and collaborative AI agents. + +## Quick Start + +### 1. Open in Codespace + +Click the "Code" button on GitHub and select "Create codespace on main" (or your branch). + +The devcontainer will automatically: +- Install Python, Node.js, and Go +- Set up Ollama for local AI models +- Install Cloudflare Wrangler CLI +- Pull open source AI models in the background +- Configure all dependencies + +### 2. Wait for Setup + +The initial setup takes 5-10 minutes as it downloads AI models. You can monitor progress: + +```bash +# Check if Ollama is ready +ollama list + +# See what models are downloading +ps aux | grep ollama +``` + +### 3. Test the Orchestrator + +```bash +# Test agent routing +python -m codespace_agents.orchestrator + +# You should see: +# ✅ Loaded agent: Coder (coder) +# ✅ Loaded agent: Designer (designer) +# ✅ Loaded agent: Ops (ops) +# ✅ Loaded agent: Docs (docs) +# ✅ Loaded agent: Analyst (analyst) +``` + +## Usage Examples + +### Example 1: Chat with Coder Agent + +```bash +# Ask a coding question +python -m codespace_agents.chat --agent coder "Write a Python function to reverse a string" + +# Interactive mode +python -m codespace_agents.chat --agent coder +``` + +### Example 2: Auto-Route Task + +```bash +# Let the orchestrator choose the right agent +python -m codespace_agents.chat "Design a color palette for a dashboard" +# → Routes to Designer agent + +python -m codespace_agents.chat "Deploy the app to Cloudflare" +# → Routes to Ops agent +``` + +### Example 3: Collaborative Session + +```bash +# Start a group chat with all agents +python -m codespace_agents.collaborate + +# Work with specific agents +python -m codespace_agents.collaborate --agents coder,designer,ops + +# Broadcast a task to all agents +python -m codespace_agents.collaborate \ + --mode broadcast \ + --task "Create a new feature: user profile page" + +# Sequential handoff (agents work in order) +python -m codespace_agents.collaborate \ + --mode sequential \ + --agents designer,coder,ops \ + --task "Build and deploy a contact form" +``` + +## Common Workflows + +### Workflow 1: Feature Development + +```bash +# 1. Design phase +python -m codespace_agents.chat --agent designer \ + "Design a user profile page with avatar, bio, and social links" + +# 2. Implementation +python -m codespace_agents.chat --agent coder \ + "Implement the user profile page in React with Tailwind CSS" + +# 3. Documentation +python -m codespace_agents.chat --agent docs \ + "Create documentation for the user profile component" + +# 4. Deployment +python -m codespace_agents.chat --agent ops \ + "Deploy to Cloudflare Pages" +``` + +### Workflow 2: Bug Fix + +```bash +# 1. Analyze the issue +python -m codespace_agents.chat --agent analyst \ + "Why is the login page slow?" + +# 2. Fix the code +python -m codespace_agents.chat --agent coder \ + "Optimize the authentication flow" + +# 3. Update docs +python -m codespace_agents.chat --agent docs \ + "Update changelog with performance improvements" +``` + +### Workflow 3: Collaborative Development + +```bash +# Start a group session +python -m codespace_agents.collaborate + +# Then in the chat: +You: We need to build a real-time chat feature +Coder: I'll implement the WebSocket backend +Designer: I'll create the chat UI components +Ops: I'll set up the Cloudflare Durable Objects +Docs: I'll document the API +``` + +## Model Configuration + +Models are configured in `codespace-agents/config/`: + +```yaml +# codespace-agents/config/coder.yaml +models: + primary: "qwen2.5-coder:latest" + fallback: + - "deepseek-coder:latest" + - "codellama:latest" +``` + +You can modify these to use different models. + +## Cloud Fallback + +If local models are unavailable, agents fall back to cloud APIs: + +```bash +# Set API keys (optional) +export OPENAI_API_KEY="sk-..." +export ANTHROPIC_API_KEY="sk-ant-..." +``` + +Without API keys, only local Ollama models are used. + +## Cloudflare Workers + +Deploy agents as edge workers: + +```bash +cd codespace-agents/workers + +# Deploy the router +wrangler deploy agent-router.js + +# Deploy coder agent +wrangler deploy coder-agent.js + +# Test +curl https://agent-router.YOUR-SUBDOMAIN.workers.dev/health +``` + +## Troubleshooting + +### Models not found + +```bash +# Pull models manually +ollama pull qwen2.5-coder +ollama pull llama3.2 +ollama pull mistral +ollama pull phi3 +ollama pull gemma2 + +# Check available models +ollama list +``` + +### Ollama not running + +```bash +# Start Ollama service +ollama serve & + +# Or check if it's running +ps aux | grep ollama +``` + +### Port conflicts + +If ports are in use, modify `.devcontainer/devcontainer.json`: + +```json +"forwardPorts": [ + 8080, // Change if needed + 11434 // Ollama port +] +``` + +## Tips + +1. **Multiple agents**: Run multiple agents in parallel by opening multiple terminals +2. **Cost tracking**: Check `codespace_agents/config/*.yaml` for cost settings +3. **Context**: Agents maintain context within a session but not across sessions +4. **Collaboration**: Agents can request help from each other automatically +5. **Performance**: Smaller models (1B-3B) are faster, larger (7B+) are more capable + +## Next Steps + +- Explore agent configurations in `codespace-agents/config/` +- Read about available models in `codespace-agents/MODELS.md` +- Try collaborative sessions with multiple agents +- Deploy agents to Cloudflare Workers +- Customize agent prompts and behaviors + +## Get Help + +- Check agent status: `python -m codespace_agents.orchestrator` +- List models: `ollama list` +- View logs: Check terminal output for errors +- Read docs: All docs in `codespace-agents/` + +--- + +Happy coding with your AI agent team! 🤖✨ diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 490add5..766c4ea 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,83 +1,133 @@ -# Code of Conduct +# Contributor Covenant Code of Conduct ## Our Pledge -We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation. +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. -We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. ## Our Standards -Examples of behavior that contributes to a positive environment: +Examples of behavior that contributes to a positive environment for our +community include: * Demonstrating empathy and kindness toward other people * Being respectful of differing opinions, viewpoints, and experiences * Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes -* Focusing on what is best for the overall community +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community -Examples of unacceptable behavior: +Examples of unacceptable behavior include: -* The use of sexualized language or imagery, and sexual attention or advances of any kind +* The use of sexualized language or imagery, and sexual attention or advances of + any kind * Trolling, insulting or derogatory comments, and personal or political attacks * Public or private harassment -* Publishing others' private information without explicit permission -* Other conduct which could reasonably be considered inappropriate in a professional setting +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting ## Enforcement Responsibilities -Community leaders are responsible for clarifying and enforcing our standards of acceptable behavior and will take appropriate and fair corrective action in response to any behavior that they deem inappropriate, threatening, offensive, or harmful. +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. ## Scope -This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public spaces. +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. ## Enforcement -Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at blackroad.systems@gmail.com. +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement through GitHub +issues or by contacting the project maintainers directly. All complaints will be reviewed and investigated promptly and fairly. +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + ## Enforcement Guidelines -Community leaders will follow these Community Impact Guidelines in determining the consequences for any action they deem in violation of this Code of Conduct: +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: ### 1. Correction -**Community Impact**: Use of inappropriate language or other behavior deemed unprofessional. +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. -**Consequence**: A private, written warning, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. ### 2. Warning -**Community Impact**: A violation through a single incident or series of actions. +**Community Impact**: A violation through a single incident or series of +actions. -**Consequence**: A warning with consequences for continued behavior. No interaction with the people involved for a specified period of time. +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. ### 3. Temporary Ban -**Community Impact**: A serious violation of community standards. +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. -**Consequence**: A temporary ban from any sort of interaction or public communication with the community for a specified period of time. +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. ### 4. Permanent Ban -**Community Impact**: Demonstrating a pattern of violation of community standards. +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. -**Consequence**: A permanent ban from any sort of public interaction within the community. +**Consequence**: A permanent ban from any sort of public interaction within the +community. ## Attribution -This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 2.0, available at https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. - -[homepage]: https://www.contributor-covenant.org +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. ---- +Community Impact Guidelines were inspired by +[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. -
+For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. -**Building a respectful and inclusive community** 💜 - -Part of the [BlackRoad OS](https://blackroad.io) ecosystem - -
+[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3be16e8..79b1680 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,129 +1,368 @@ -# Contributing to .github +# Contributing to BlackRoad -Thank you for considering contributing to this BlackRoad OS project! 🎉 +> **Welcome to The Bridge!** We're building a routing company that connects users to intelligence without owning the intelligence itself. -## Code of Conduct +--- -This project follows our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you agree to uphold this code. +## Getting Started -## How Can I Contribute? +Before contributing, please: -### Reporting Bugs +1. **Read the architecture** - [BLACKROAD_ARCHITECTURE.md](BLACKROAD_ARCHITECTURE.md) +2. **Understand the ecosystem** - [INDEX.md](INDEX.md) and [REPO_MAP.md](REPO_MAP.md) +3. **Learn the signal protocol** - [SIGNALS.md](SIGNALS.md) +4. **Review the streams model** - [STREAMS.md](STREAMS.md) -Before creating bug reports, please check existing issues. When creating a bug report, include: +--- -- **Clear description** of the issue -- **Steps to reproduce** the problem -- **Expected behavior** -- **Actual behavior** -- **Screenshots** (if applicable) -- **Environment details** (OS, version, etc.) +## How to Contribute -### Suggesting Enhancements +### 1. Choose Your Organization -Enhancement suggestions are tracked as GitHub issues. When suggesting an enhancement: +BlackRoad operates across 15 specialized organizations. Identify which one your contribution relates to: -- **Use a clear title** describing the enhancement -- **Provide detailed description** of the suggested feature -- **Explain why** this enhancement would be useful -- **Include examples** of how it would work +| Organization | Focus Area | Blueprint | +|--------------|-----------|-----------| +| BlackRoad-OS | Core infrastructure, The Bridge | [Browse](orgs/BlackRoad-OS/) | +| BlackRoad-AI | Intelligence routing, ML | [Browse](orgs/BlackRoad-AI/) | +| BlackRoad-Cloud | Edge compute, Cloudflare | [Browse](orgs/BlackRoad-Cloud/) | +| BlackRoad-Hardware | Pi cluster, IoT, Hailo | [Browse](orgs/BlackRoad-Hardware/) | +| BlackRoad-Security | Auth, secrets, audit | [Browse](orgs/BlackRoad-Security/) | +| BlackRoad-Labs | Experiments, R&D | [Browse](orgs/BlackRoad-Labs/) | +| BlackRoad-Foundation | CRM, finance, Stripe | [Browse](orgs/BlackRoad-Foundation/) | +| BlackRoad-Ventures | Marketplace, commerce | [Browse](orgs/BlackRoad-Ventures/) | +| Blackbox-Enterprises | Enterprise solutions | [Browse](orgs/Blackbox-Enterprises/) | +| BlackRoad-Media | Content, social media | [Browse](orgs/BlackRoad-Media/) | +| BlackRoad-Studio | Design system, UI | [Browse](orgs/BlackRoad-Studio/) | +| BlackRoad-Interactive | Metaverse, 3D, games | [Browse](orgs/BlackRoad-Interactive/) | +| BlackRoad-Education | Learning, tutorials | [Browse](orgs/BlackRoad-Education/) | +| BlackRoad-Gov | Governance, voting | [Browse](orgs/BlackRoad-Gov/) | +| BlackRoad-Archive | Storage, backups | [Browse](orgs/BlackRoad-Archive/) | -### Pull Requests +### 2. Types of Contributions -1. **Fork** the repository -2. **Create** a new branch (`git checkout -b feature/amazing-feature`) -3. **Make** your changes -4. **Test** your changes thoroughly -5. **Commit** with clear messages (`git commit -m 'Add amazing feature'`) -6. **Push** to your fork (`git push origin feature/amazing-feature`) -7. **Open** a Pull Request +We welcome: -#### Pull Request Guidelines +- 🐛 **Bug fixes** - Fix issues in existing code +- ✨ **New features** - Add functionality to an organization +- 📚 **Documentation** - Improve docs, add examples +- 🏢 **Organization blueprints** - Enhance org specifications +- 🔧 **Infrastructure** - Workflows, templates, tools +- 🧪 **Tests** - Add or improve test coverage +- ⚡ **Performance** - Optimize existing code +- 🎨 **Design** - UI/UX improvements -- Follow the existing code style -- Write clear commit messages -- Update documentation as needed -- Add tests for new features -- Ensure all tests pass -- Link related issues +### 3. Contribution Workflow -## Development Setup +#### Step 1: Fork and Clone ```bash -# Clone your fork +# Fork the repository on GitHub, then: git clone https://github.com/YOUR_USERNAME/.github.git cd .github +``` -# Add upstream remote -git remote add upstream https://github.com/BlackRoad-OS/.github.git +#### Step 2: Create a Branch -# Install dependencies -npm install # or pip install -r requirements.txt +```bash +# Use a descriptive branch name +git checkout -b feat/org-name/feature-description +# or +git checkout -b fix/org-name/bug-description +``` -# Run tests -npm test # or pytest, or cargo test +#### Step 3: Make Your Changes + +- Follow existing code style and patterns +- Add tests if applicable +- Update documentation if needed +- Keep commits focused and atomic + +#### Step 4: Test Your Changes + +```bash +# Run relevant tests +python -m pytest prototypes/ + +# Check linting (if applicable) +# Verify builds pass ``` -## Coding Standards +#### Step 5: Commit with Clear Messages -- Follow language-specific best practices -- Write self-documenting code -- Add comments for complex logic -- Keep functions small and focused -- Use meaningful variable names +```bash +git add . +git commit -m "feat(org-ai): add new routing algorithm + +- Implement fuzzy matching for queries +- Add confidence scoring +- Update tests -## Commit Message Format +Signal: AI → OS : feature_added" +``` +**Commit Message Format:** ``` (): -