chore(standards): add .standards submodule and centralize AI instructions

.github/copilot-instructions.md

@@ -1,91 +1,29 @@
 <!-- file: .github/copilot-instructions.md -->
-<!-- version: 2.3.3 -->
+<!-- version: 2.4.0 -->
 <!-- guid: 4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a -->
-<!-- last-edited: 2026-01-19 -->
+<!-- last-edited: 2026-06-13 -->
 
-# 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
+**<https://github.com/falkcorp/.github>** 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: `<!-- file: path -->`, `<!-- version: x.y.z -->`, `<!-- guid: uuid -->`
-<!-- last-edited: 2026-01-19 -->
-- 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`

.gitmodules

@@ -0,0 +1,3 @@
+[submodule ".standards"]
+	path = .standards
+	url = https://github.com/falkcorp/.github

AGENTS.md

@@ -1,105 +1,11 @@
 <!-- file: AGENTS.md -->
-<!-- version: 3.0.0 -->
+<!-- version: 4.0.0 -->
 <!-- guid: 2e7c1a4b-5d3f-4b8c-9e1f-7a6b2c3d4e5f -->
-<!-- last-edited: 2026-01-25 -->
+<!-- last-edited: 2026-06-13 -->
 
 # 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):
+**<https://github.com/falkcorp/.github>**

CLAUDE.md

@@ -1,15 +1,26 @@
 <!-- file: CLAUDE.md -->
-<!-- version: 3.0.0 -->
+<!-- version: 3.1.0 -->
 <!-- guid: 3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f -->
-<!-- last-edited: 2026-01-25 -->
+<!-- last-edited: 2026-06-13 -->
 
 # CLAUDE.md
 
 > **NOTE:** This file is a pointer. All Claude/AI agent and workflow
 > 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:**