diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..b43b49e --- /dev/null +++ b/.gitignore @@ -0,0 +1,13 @@ +# OS +.DS_Store +Thumbs.db + +# Editor +.vscode/ +.idea/ +*.swp +*.swo + +# Environment +.env +.env.local diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..a836e60 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,51 @@ +# CLAUDE.md — labrats-work/.github + +This file provides context for AI agents (Claude Code and others) working in this repository. + +## Repository Purpose + +This is the `.github` special repository for the `labrats-work` GitHub organization. It controls: + +- **Organization profile** (`profile/README.md`) — shown at github.com/labrats-work +- **Workflow templates** (`workflow-templates/`) — starter workflows surfaced in all org repos +- **Org-level workflows** (`.github/workflows/`) — automation running at org scope + +## Key Files + +| Path | Purpose | +|------|---------| +| `profile/README.md` | Org profile displayed on GitHub — keep accurate and up to date | +| `workflow-templates/*.yml` | Workflow templates — each must have a matching `.properties.json` | +| `workflow-templates/*.properties.json` | Template metadata: `name`, `description`, `iconName`, `categories` | +| `.github/workflows/repo-info.yml` | Example org workflow (repo info dump) | + +## Conventions + +- Workflow template YAMLs use `$default-branch` as a placeholder (replaced by GitHub when applied). +- The corresponding `.properties.json` must match the template filename (without extension). +- Keep `profile/README.md` reflecting the actual org tech stack and projects. + +## AI Agent System + +This org uses multi-agent GitHub automation. Agents are triggered via issue/PR labels and `@mention` in comments: + +| Agent | Trigger | Role | +|-------|---------|------| +| `@ai-developer` | `ai-developer` label | Implements features and fixes | +| `@ai-reviewer` | `ai-reviewer` label | Reviews PRs | +| `@ai-architect` | `ai-architect` label | Designs solutions | +| `@ai-docs` | `ai-docs` label | Writes/maintains documentation | +| `@ai-testing` | `ai-testing` label | Writes tests | +| `@ai-security` | `ai-security` label | Security audits | +| `@ai-ops` | `ai-ops` label | Diagnoses failures | +| `@ai-triage` | `ai-triage` label | Quick issue triage | + +The agent service is hosted in `apps.github-ai-agents`. + +## Branch Naming + +Use `feat/`, `fix/`, `docs/`, `chore/`, `refactor/`, `test/` prefixes. + +## Commit Style + +Follow conventional commits: `type(scope): description` (imperative, under 72 chars). diff --git a/README.md b/README.md new file mode 100644 index 0000000..e77cbc3 --- /dev/null +++ b/README.md @@ -0,0 +1,46 @@ +# labrats-work/.github + +Organization-wide GitHub configuration for [labrats-work](https://github.com/labrats-work), including the org profile, reusable workflow templates, and shared GitHub configuration. + +## Purpose + +This repository serves three roles: + +1. **Organization Profile** — `profile/README.md` is displayed on the labrats-work GitHub organization page. +2. **Workflow Templates** — `workflow-templates/` provides starter workflows available to all repositories in the organization. +3. **Org-Wide GitHub Config** — `.github/` holds workflows and settings that apply at the organization level. + +## Quick Start + +### Using a Workflow Template + +1. In any repository under `labrats-work`, go to **Actions → New workflow**. +2. Workflow templates defined in this repo appear under the organization section. +3. Select a template and follow the setup instructions in the generated workflow file. + +### Contributing a New Workflow Template + +1. Add the workflow YAML to `workflow-templates/.yml`. +2. Add a corresponding `workflow-templates/.properties.json` with `name`, `description`, `iconName`, and `categories`. +3. Open a PR — the template becomes available org-wide once merged to `main`. + +## Structure + +``` +.github/ + workflows/ # Org-level GitHub Actions workflows +profile/ + README.md # Organization profile shown on GitHub +workflow-templates/ + *.yml # Reusable workflow templates for the org + *.properties.json # Metadata for each workflow template +docs/ + workflow-templates.md # Guide for workflow templates + ai-agents.md # Overview of the org AI agent system +``` + +## Related + +- [labrats-work org profile](https://github.com/labrats-work) +- [actions.common](https://github.com/labrats-work/actions.common) — Reusable GitHub Actions +- [apps.github-ai-agents](https://github.com/labrats-work/apps.github-ai-agents) — AI agent service diff --git a/docs/ai-agents.md b/docs/ai-agents.md new file mode 100644 index 0000000..b7b6272 --- /dev/null +++ b/docs/ai-agents.md @@ -0,0 +1,77 @@ +# AI Agents + +The `labrats-work` organization uses a multi-agent AI automation system powered by Claude. Agents handle routine development tasks via GitHub issues and pull requests. + +## How It Works + +1. A human (or bot) opens or comments on an issue/PR. +2. The agent service (`apps.github-ai-agents`) listens for webhook events. +3. When an agent is triggered (via label or `@mention`), it clones the target repo and executes the task. +4. The agent commits changes, creates a PR, and posts status comments. + +## Triggering Agents + +### Via Label + +Apply a label to an issue or PR to trigger the corresponding agent: + +| Label | Agent | +|-------|-------| +| `ai-developer` | `@ai-developer` — implements features/fixes | +| `ai-reviewer` | `@ai-reviewer` — reviews PRs | +| `ai-architect` | `@ai-architect` — designs solutions | +| `ai-docs` | `@ai-docs` — writes documentation | +| `ai-testing` | `@ai-testing` — writes tests | +| `ai-security` | `@ai-security` — security audits | +| `ai-ops` | `@ai-ops` — ops/infra diagnostics | +| `ai-triage` | `@ai-triage` — lightweight issue triage | + +### Via Mention + +Comment `@ai-developer please ...` (or any agent name) in an issue or PR to delegate a task. + +## Agent Roles + +### @ai-developer +Implements features, fixes bugs, addresses PR review feedback. Creates branches, commits, opens PRs. + +### @ai-reviewer +Reviews pull requests for code quality, correctness, and org standards. Posts review comments. + +### @ai-architect +Designs solutions for complex features. Produces implementation plans before dev work begins. + +### @ai-docs +Writes and maintains documentation. Reviews existing docs for accuracy. + +### @ai-testing +Writes unit, integration, and e2e tests. Improves coverage for existing code. + +### @ai-security +Audits code for vulnerabilities. Reviews dependencies, secrets handling, and OWASP concerns. + +### @ai-ops +Diagnoses CI failures, infrastructure issues, and deployment problems. + +### @ai-triage +Quick issue assessment and labeling. Lightweight analysis to route issues to the right agent. + +## Delegation Chain + +A typical flow for a new feature: + +``` +Issue opened + → @ai-triage (assess complexity) + → @ai-architect (design if complex) + → @ai-developer (implement) + → @ai-reviewer (review) + → @ai-docs (document) +``` + +## Infrastructure + +The agent service source is at `labrats-work/apps.github-ai-agents`. It uses: +- GitHub App authentication via `GH_TOKEN` +- Claude Sonnet/Haiku models via Anthropic API +- Per-task repo cloning into isolated workspaces diff --git a/docs/workflow-templates.md b/docs/workflow-templates.md new file mode 100644 index 0000000..5de4d52 --- /dev/null +++ b/docs/workflow-templates.md @@ -0,0 +1,43 @@ +# Workflow Templates + +This directory documents the reusable workflow templates available to all repositories in the `labrats-work` organization. + +## How Templates Work + +GitHub surfaces workflow templates from `workflow-templates/` in any repo's **Actions → New workflow** page under the organization section. Each template requires: + +1. **`.yml`** — The workflow YAML. Use `$default-branch` as a placeholder for the repo's default branch. +2. **`.properties.json`** — Metadata displayed in the GitHub UI. + +### Properties JSON Schema + +```json +{ + "name": "Human-readable template name", + "description": "Short description shown in GitHub UI", + "iconName": "octicon icon name (e.g. check-square)", + "categories": ["Text"], + "filePatterns": ["optional glob patterns that suggest this template"] +} +``` + +## Available Templates + +### `repo-info` + +Dumps repository context information (name, workspace size, GitHub context JSON) on push and pull request events. + +**Use case:** Debugging, onboarding, verifying runner environments. + +**File:** `workflow-templates/repo-info.yml` + +## Adding a New Template + +1. Create `workflow-templates/.yml` with your workflow. +2. Create `workflow-templates/.properties.json` with metadata. +3. Open a PR against `main`. +4. Once merged, the template is immediately available org-wide. + +## References + +- [GitHub Docs — Creating workflow templates](https://docs.github.com/en/actions/using-workflows/creating-starter-workflows-for-your-organization)