diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index b395d213..6e9a2c68 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,91 +1,29 @@ - + - + -# GitHub Common Workflows Repository - AI Agent Instructions +# github-common — Additional Context -This repository serves as the **central infrastructure hub** for reusable GitHub Actions workflows, scripts, and configurations across multiple repositories. It implements a sophisticated modular instruction system and provides automation tools for multi-repository management. +Org-wide coding standards (file headers, language rules, commit format) are at +**** and apply automatically to this repo. -## 🏗️ Repository Architecture +For full project context: **CLAUDE.md** at the repo root. -**This is a workflow infrastructure repository**, not a typical application codebase. Key architectural components: +## Project overview -- **Reusable Workflows**: `.github/workflows/reusable-*.yml` - Called by other repositories -- **Script Library**: `scripts/` - Python automation tools for cross-repo operations -- **Instruction System**: `.github/instructions/` - Modular AI agent rules with language targeting -- **Workflow Debugging**: `scripts/workflow-debugger.py` - Analyzes failures and generates fix tasks -- **Multi-Repo Sync**: `scripts/intelligent_sync_to_repos.py` - Propagates changes to target repos +Reusable GitHub Actions workflows, scripts, and multi-repo automation. Language: Python. -## 🔧 Critical AI Agent Workflows +## Key directories -Use VS Code tasks for non-git operations (build, lint, generate). For git operations, prefer: -1) MCP GitHub tools (preferred), 2) safe-ai-util (fallback), 3) native git (last resort). +| Path | Purpose | +|---|---| +| `.github/workflows/reusable-*.yml` | Reusable workflows called by other repos | +| `scripts/` | Python automation tools for cross-repo operations | +| `.github/instructions/` | Modular AI agent rules with language targeting | -Use specialized subagents when possible: CI Workflow Doctor, Dependency Auditor, Documentation Curator, Git Hygiene Guardian, Lint & Format Conductor, Protobuf Builder, Protobuf Cycle Resolver, and others in `.github/prompts/` for targeted expertise. +## Critical constraints -### Protobuf Operations (Core Focus) -```bash -# Use tasks, not manual buf commands -"Buf Generate with Output" - Generates protobuf code with logging -"Buf Lint with Output" - Lints protobuf files with comprehensive output -``` -- This repo heavily focuses on protobuf tooling and cross-repo protobuf management -- Use `tools/protobuf-cycle-fixer.py` for import cycle resolution -- Protobuf changes trigger the `protobuf-generation.yml` workflow - -### Git Operations (Policy) -- Prefer MCP GitHub tools or safe-ai-util for all git actions (add/commit/push). -- Avoid VS Code git tasks; keep git automation out of editor tasks. -- All commits MUST use conventional commit format: `type(scope): description`. -- See `.github/instructions/commit-messages.instructions.md` for detailed commit message rules. - -## 🎯 Multi-Repository Management Patterns - -**This repository manages configurations for multiple target repositories:** - -### Sync Operations -```bash -# Primary sync script for propagating changes -python scripts/intelligent_sync_to_repos.py --target-repos "repo1,repo2" --dry-run -``` -- Syncs `.github/instructions/`, `.github/prompts/`, and workflows to target repos -- Creates VS Code Copilot symlinks: `.vscode/copilot/` → `.github/instructions/` -- Handles repository-specific file exclusions and maintains file headers - -### Workflow Debugging & Auto-Fix -```bash -python scripts/workflow-debugger.py --org jdfalk --scan-all --fix-tasks -``` -- Analyzes workflow failures across repositories -- Generates JSON fix tasks for Copilot agents at `workflow-debug-output/fix-tasks/` -- Categorizes failures: permissions, dependencies, syntax, infrastructure -- Outputs actionable remediation steps with code examples - -## 📁 File Organization Conventions - -**Modular Instruction System** (referenced by general instructions): -- `general-coding.instructions.md` - Base rules for all languages -- `{language}.instructions.md` - Language-specific extensions with `applyTo: "**/*.{ext}"` frontmatter -- Instructions are synced to target repos and symlinked for VS Code Copilot integration - -**Repository-Specific Patterns**: -- All files require versioned headers: ``, ``, `` - -- Always increment version numbers on file changes (patch/minor/major semantic versioning) -- Use `copilot-util-args` file for storing command arguments between task executions - -## 🔍 Project-Specific Context - -**This is an infrastructure repository** - focus on: -1. **Workflow reliability** - Use workflow debugger to identify and fix cross-repo workflow issues -2. **Protobuf tooling** - Buf integration, cycle detection, and cross-repo protobuf synchronization -3. **Configuration propagation** - Ensure changes sync correctly to target repositories -4. **Agent task generation** - Workflow debugger creates structured tasks for AI agents - -**Common Operations**: -- Analyze workflow failures: `scripts/workflow-debugger.py` -- Sync to repositories: `scripts/intelligent_sync_to_repos.py` -- Fix protobuf cycles: `tools/protobuf-cycle-fixer.py`Always check `logs/` directory after running VS Code tasks for execution details and debugging information. - -For detailed coding rules, see `.github/instructions/general-coding.instructions.md` and language-specific instruction files. +- `scripts/intelligent_sync_to_repos.py` — propagates changes to target repos; use `--dry-run` first +- `scripts/workflow-debugger.py` — analyzes workflow failures; outputs to `workflow-debug-output/fix-tasks/` +- All commits must use conventional commit format: `type(scope): description` diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000..eb6e7b30 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule ".standards"] + path = .standards + url = https://github.com/falkcorp/.github diff --git a/.standards b/.standards new file mode 160000 index 00000000..664ae68e --- /dev/null +++ b/.standards @@ -0,0 +1 @@ +Subproject commit 664ae68ef7580946eaa5f0fccbd8b60d17373ceb diff --git a/AGENTS.md b/AGENTS.md index ee1a7724..ac070c95 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,105 +1,11 @@ - + - + # AGENTS.md -> **NOTE:** This is a pointer file. All detailed Copilot, agent, and workflow -> instructions are in the [.github/](.github/) directory. +See **CLAUDE.md** for all agent instructions and project context. -## 🎯 Quick Reference - -**Main Documentation:** - -- [Copilot Instructions](.github/instructions/copilot-instructions.md) - Primary - AI agent configuration -- [Instructions Directory](.github/instructions/) - All coding standards and - language-specific rules -- [Prompts Directory](.github/prompts/) - Specialized prompts for specific tasks - -## 📋 Instruction Files - -### Core Workflow Instructions - -- [commit-messages.instructions.md](.github/instructions/commit-messages.instructions.md) - - Conventional commit standards -- [pull-request-descriptions.instructions.md](.github/instructions/pull-request-descriptions.instructions.md) - - PR description templates -- [test-generation.instructions.md](.github/instructions/test-generation.instructions.md) - - Test writing guidelines -- [security.instructions.md](.github/instructions/security.instructions.md) - - Security best practices -- [safe-ai-util.instructions.md](.github/instructions/safe-ai-util.instructions.md) - - Git operation safety - -### Language-Specific Instructions - -- [general-coding.instructions.md](.github/instructions/general-coding.instructions.md) - - Universal coding standards -- [go.instructions.md](.github/instructions/go.instructions.md) - Go language - rules -- [python.instructions.md](.github/instructions/python.instructions.md) - Python - language rules -- [typescript.instructions.md](.github/instructions/typescript.instructions.md) - - TypeScript/React rules -- [javascript.instructions.md](.github/instructions/javascript.instructions.md) - - JavaScript rules -- [rust.instructions.md](.github/instructions/rust.instructions.md) - Rust - language rules -- [rust-utility.instructions.md](.github/instructions/rust-utility.instructions.md) - - Rust utilities -- [shell.instructions.md](.github/instructions/shell.instructions.md) - Shell - scripting rules -- [protobuf.instructions.md](.github/instructions/protobuf.instructions.md) - - Protobuf standards -- [markdown.instructions.md](.github/instructions/markdown.instructions.md) - - Markdown formatting -- [json.instructions.md](.github/instructions/json.instructions.md) - JSON - formatting -- [jsonc.instructions.md](.github/instructions/jsonc.instructions.md) - JSON - with comments -- [html-css.instructions.md](.github/instructions/html-css.instructions.md) - - HTML/CSS rules -- [github-actions.instructions.md](.github/instructions/github-actions.instructions.md) - - CI/CD workflow rules - -### Specialized Prompts - -- [code-review.prompt.md](.github/prompts/code-review.prompt.md) - Code review - guidance -- [documentation.prompt.md](.github/prompts/documentation.prompt.md) - - Documentation generation -- [bug-report.prompt.md](.github/prompts/bug-report.prompt.md) - Bug report - templates -- [feature-request.prompt.md](.github/prompts/feature-request.prompt.md) - - Feature request templates -- [merge-conflict-resolution.agent.md](.github/prompts/merge-conflict-resolution.agent.md) - - Merge conflict help -- [test-generation.prompt.md](.github/prompts/test-generation.prompt.md) - Test - generation prompts - -## 🚨 CRITICAL: File Version Updates - -**When modifying any file with a version header, ALWAYS update the version -number:** - -- **Patch version** (x.y.Z): Bug fixes, typos, minor formatting changes -- **Minor version** (x.Y.z): New features, significant content additions -- **Major version** (X.y.z): Breaking changes, structural overhauls - -**This applies to ALL files with version headers including documentation, -templates, and configuration files.** - -## 🔧 Git Operations - -**Preferred order for git operations:** - -1. MCP GitHub tools (preferred) -2. safe-ai-util (fallback) -3. Native git commands (last resort) - -**Use VS Code tasks for non-git operations only (build, lint, test).** - -> For any agent, Copilot, or workflow task, **always refer to the files listed -> above.** +Org-wide coding standards (file headers, language rules, commit format): +**** diff --git a/CLAUDE.md b/CLAUDE.md index 2007673d..6d3ef4fd 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ - + - + # CLAUDE.md @@ -9,7 +9,18 @@ > instructions are centralized in the `.github/instructions/` and > `.github/prompts/` directories. -## 🎯 Quick Reference +## Coding Standards + +Org-wide coding standards are in the `.standards/` git submodule (cloned from +`https://github.com/falkcorp/.github`). Always clone with +`git clone --recurse-submodules` so these are available. + +Key files: + +- **File headers (MANDATORY):** `.standards/instructions/file-headers.md` +- **Commit format:** `.standards/instructions/commit-messages.md` + +## Quick Reference **Main Documentation:**