diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 037e1a0..bc34b35 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,89 +1,33 @@ - + + -# GitHub Common Workflows Repository - AI Agent Instructions +# transcoderr — 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 +Rust-based media transcoder CLI using ffmpeg/ffprobe. Wraps ffmpeg/ffprobe to +transcode media files while preserving metadata. Single binary (`transcoderr`), +entry point at `src/main.rs`. -## 🔧 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 | +|------|---------| +| `src/` | Rust source (single `main.rs` binary) | +| `tests/` | Integration tests | +| `benches/` | Criterion benchmarks | +| `testdata/` | Sample media files for tests | +| `scripts/` | Helper scripts | -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. +- Requires `ffmpeg` and `ffprobe` on `PATH` at runtime — do not shell out to any other media tools. +- Optional `json` feature gate enables `serde`/`serde_json` for JSON output mode. +- Minimum Rust edition: 2021. diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..eb6e7b3 --- /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 0000000..664ae68 --- /dev/null +++ b/.standards @@ -0,0 +1 @@ +Subproject commit 664ae68ef7580946eaa5f0fccbd8b60d17373ceb diff --git a/AGENTS.md b/AGENTS.md index 519900b..2c714fe 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,52 +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. -## 🚨 CRITICAL: Documentation Update Protocol - -This repository uses a direct-edit documentation workflow. The legacy doc-update scripts and -workflows are retired. - -- Edit documentation directly in the target files. -- Always keep the required header (file path, version, guid) and bump the version on any change. -- Do not use create-doc-update.sh, doc_update_manager.py, or .github/doc-updates/. -- Prefer VS Code tasks for git operations (Git Add All, Git Commit, Git Push) when available. - - These tasks use the `copilot-agent-util` Rust utility for enhanced logging, error handling, and - safety. - - Download: - -## ⚠️ 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, template changes -- **Major version** (X.y.z): Breaking changes, structural overhauls, format changes - -**Examples:** - -- Fix typo: `1.2.3` → `1.2.4` -- Add new section: `1.2.3` → `1.3.0` -- Change template structure: `1.2.3` → `2.0.0` - -**This applies to ALL files with version headers including documentation, templates, and -configuration files.** - -## Key Copilot/Agent Documents - -- [Copilot Instructions](.github/copilot-instructions.md) -- [Commit Message Standards](.github/commit-messages.md) -- [Pull Request Description Guidelines](.github/pull-request-descriptions.md) -- [Code Review Guidelines](.github/review-selection.md) -- [Test Generation Guidelines](.github/test-generation.md) -- [Security Guidelines](.github/security-guidelines.md) -- [Repository Setup Guide](.github/repository-setup.md) -- [Workflow Usage](.github/workflow-usage.md) -- [All Code Style Guides](.github/) - -> For any agent, Copilot, or workflow task, **always refer to the above files.** +Org-wide coding standards (file headers, language rules, commit format): +**https://github.com/falkcorp/.github** diff --git a/CLAUDE.md b/CLAUDE.md index 099a440..82c1f81 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,11 +1,21 @@ - + + # CLAUDE.md -> **NOTE:** This file is a pointer. All Claude/AI agent and workflow instructions are now -> centralized in the `.github/instructions/` and `.github/prompts/` directories. +transcoderr is a Rust CLI tool that wraps ffmpeg/ffprobe to transcode media files +while preserving metadata. Single binary, entry point at `src/main.rs`. + +## 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` ## 🚨 CRITICAL: Documentation Update Protocol