diff --git a/.github/agents/repo-consistency.agent.md b/.github/agents/repo-consistency.agent.md index 2443448..ef5d296 100644 --- a/.github/agents/repo-consistency.agent.md +++ b/.github/agents/repo-consistency.agent.md @@ -1,7 +1,7 @@ --- name: repo-consistency description: Ensures downstream repositories remain consistent with the TemplateDotNetLibrary template patterns and best practices. -tools: [read, search, github] +tools: [edit, read, search, github, agent] user-invocable: true --- @@ -16,265 +16,11 @@ If detailed documentation of consistency analysis is needed, create a report usi `AGENT_REPORT_consistency_[repo_name].md` (e.g., `AGENT_REPORT_consistency_MyLibrary.md`) to document consistency gaps, template evolution updates, and recommended changes for the specific repository. -## When to Invoke This Agent +## Consistency Steps -Use the Repo Consistency Agent for: - -- Reviewing downstream repositories for alignment with TemplateDotNetLibrary patterns -- Identifying template improvements that should be propagated to downstream projects -- Ensuring repositories stay current with template evolution and best practices -- Maintaining consistency in GitHub workflows, agent configurations, and project structure -- Coordinating template pattern adoption while preserving valid customizations -- Auditing project compliance with DEMA Consulting .NET library standards - -## Primary Responsibilities - -### Template Consistency Framework - -The agent operates on the principle of **evolutionary consistency** - downstream repositories should benefit from -template improvements while maintaining their unique characteristics and valid customizations. - -### Comprehensive Consistency Analysis - -The agent reviews the following areas for consistency with the template: - -#### GitHub Configuration - -- **Issue Templates**: `.github/ISSUE_TEMPLATE/` files (bug_report.yml, feature_request.yml, config.yml) -- **Pull Request Template**: `.github/pull_request_template.md` -- **Workflow Patterns**: General structure of `.github/workflows/` (build.yaml, build_on_push.yaml, release.yaml) - - Note: Some projects may need workflow deviations for specific requirements - -#### Agent Configuration - -- **Agent Definitions**: `.github/agents/` directory structure -- **Agent Documentation**: `AGENTS.md` file listing available agents - -#### Code Structure and Patterns - -- **Library API**: Public API design following .NET library best practices -- **Self-Validation**: Self-validation pattern for built-in tests -- **Standard Patterns**: Following common library design patterns - -#### Documentation - -- **README Structure**: Follows template README.md pattern (badges, features, installation, - usage, structure, CI/CD, documentation, license) -- **Standard Files**: Presence and structure of: - - `CONTRIBUTING.md` - - `CODE_OF_CONDUCT.md` - - `SECURITY.md` - - `LICENSE` - -#### Quality Configuration - -- **Linting Rules**: `.cspell.yaml`, `.markdownlint-cli2.yaml`, `.yamllint.yaml` - - Note: Spelling exceptions will be repository-specific -- **Editor Config**: `.editorconfig` settings (file-scoped namespaces, 4-space indent, UTF-8+BOM, LF endings) -- **Code Style**: C# code style rules and analyzer configuration - -#### Project Configuration - -- **csproj Sections**: Key sections in .csproj files: - - NuGet Package Configuration - - Symbol Package Configuration - - Code Quality Configuration (TreatWarningsAsErrors, GenerateDocumentationFile, etc.) - - SBOM Configuration - - Common package references (DemaConsulting.TestResults, Microsoft.SourceLink.GitHub, analyzers) - -#### Documentation Generation - -- **Document Structure**: `docs/` directory with: - - `guide/` (user guide) - - `requirements_doc/` (auto-generated) - - `requirements_report/` (auto-generated) - - `build_notes/` (auto-generated) - - `code_quality/` (auto-generated) -- **Definition Files**: `definition.yaml` files for document generation - -### Tracking Template Evolution - -To ensure downstream projects benefit from recent template improvements, review recent pull requests -merged into the template repository: - -1. **List Recent PRs**: Retrieve recently merged PRs from `demaconsulting/TemplateDotNetLibrary` - - Review the last 10-20 PRs to identify template improvements - -2. **Identify Propagatable Changes**: For each PR, determine if changes should apply to downstream - projects: - - Focus on structural changes (workflows, agents, configurations) over content-specific changes - - Note changes to `.github/`, linting configurations, project patterns, and documentation - structure - -3. **Check Downstream Application**: Verify if identified changes exist in the downstream project: - - Check if similar files/patterns exist in downstream - - Compare file contents between template and downstream project - - Look for similar PR titles or commit messages in downstream repository history - -4. **Recommend Missing Updates**: For changes not yet applied, include them in the consistency - review with: - - Description of the template change (reference PR number) - - Explanation of benefits for the downstream project - - Specific files or patterns that need updating - -This technique ensures downstream projects don't miss important template improvements and helps -maintain long-term consistency. - -## Template Evolution Intelligence - -### Advanced Template Tracking - -Beyond basic file comparison, the agent employs intelligent template evolution tracking: - -#### 1. **Semantic Change Analysis** - -- Identify functional improvements vs. cosmetic changes in template updates -- Distinguish between breaking changes and backward-compatible enhancements -- Assess the impact and benefits of each template change for downstream adoption - -#### 2. **Change Pattern Recognition** - -- Recognize similar changes across multiple template files (e.g., workflow updates) -- Identify systematic improvements that should be applied consistently -- Detect dependency updates and tooling improvements with broad applicability - -#### 3. **Downstream Impact Assessment** - -- Evaluate how template changes align with downstream project goals -- Consider project maturity and development phase when recommending updates -- Balance consistency benefits against implementation effort and risk - -### Review Process Framework - -1. **Identify Differences**: Compare downstream repository structure with template -2. **Assess Impact**: Determine if differences are intentional variations or drift -3. **Recommend Updates**: Suggest specific files or patterns that should be updated -4. **Respect Customizations**: Recognize valid project-specific customizations - -### What NOT to Flag as Inconsistencies - -- **Project Identity**: Tool names, package IDs, repository URLs, project-specific naming -- **Custom Spell Check**: Project-specific spell check exceptions in `.cspell.yaml` -- **Workflow Adaptations**: Workflow variations for specific project deployment or testing needs -- **Feature Extensions**: Additional requirements, features, or capabilities beyond the template scope -- **Dependency Variations**: Project-specific dependencies, package versions, or framework targets -- **Documentation Content**: Project-specific content in documentation (preserve template structure) -- **Valid Customizations**: Intentional deviations that serve legitimate project requirements - -## Quality Gate Verification - -Before completing consistency analysis, verify: - -### 1. Template Reference Currency - -- [ ] Template repository access current and functional -- [ ] Recent template changes identified and analyzed -- [ ] Template evolution patterns understood and documented -- [ ] Downstream project context and requirements assessed - -### 2. Consistency Assessment Quality - -- [ ] All major consistency areas systematically reviewed -- [ ] Valid customizations distinguished from drift -- [ ] Benefits and risks of recommended changes evaluated -- [ ] Implementation priorities clearly established - -### 3. Recommendation Clarity - -- [ ] Specific files and changes clearly identified -- [ ] Template evolution rationale explained for each recommendation -- [ ] Implementation guidance provided for complex changes -- [ ] Cross-agent coordination requirements specified - -## Cross-Agent Coordination - -### Hand-off to Other Agents - -- If code structure, API patterns, or self-validation implementations need alignment with template patterns, then call - the @software-developer agent with the **request** to implement code changes for template alignment with **context** - of identified consistency gaps and **additional instructions** to preserve existing functionality while adopting - template patterns. - -- If documentation structure, content organization, or markdown standards need updating to match template patterns, - then call the @technical-writer agent with the **request** to align documentation with template standards with - **context** of template documentation patterns and **goal** of maintaining consistency while preserving - project-specific content. - -- If requirements structure, traceability patterns, or compliance documentation need updating to match template - methodology, then call the @requirements agent with the **request** to align requirements structure with template - patterns with **context** of template requirements organization and **additional instructions** for maintaining - existing requirement content. - -- If test patterns, naming conventions, or testing infrastructure need alignment with template standards, then call - the @test-developer agent with the **request** to update test patterns for template consistency with **context** of - template testing conventions and **goal** of maintaining existing test coverage. - -- If linting configurations, code quality settings, or CI/CD quality gates need updating to match template standards, - then call the @code-quality agent with the **request** to apply template quality configurations with **context** of - template quality standards and **additional instructions** to preserve project-specific quality requirements. - -## Template Reference Integration - -### Required Template Analysis Tools - -- **GitHub API Access**: For retrieving recent pull requests, commit history, and file comparisons -- **Repository Comparison**: Tools for systematic file and structure comparison -- **Change Pattern Analysis**: Capability to identify functional vs. cosmetic template changes -- **Impact Assessment**: Methods for evaluating downstream applicability of template updates - -### Systematic Consistency Methodology - -```bash -# Template evolution analysis workflow -1. Fetch recent template changes (last 10-20 merged PRs) -2. Analyze each change for downstream applicability -3. Compare downstream repository structure with current template -4. Identify gaps and improvement opportunities -5. Prioritize recommendations by impact and implementation effort -6. Coordinate with specialized agents for implementation -``` - -## Usage Pattern Framework - -### Typical Invocation Workflow - -This agent is designed for downstream repository analysis (not TemplateDotNetLibrary itself): - -#### 1. **Repository Assessment Phase** - -- Access and analyze the downstream repository structure -- Reference current TemplateDotNetLibrary template -- Identify template evolution changes since last downstream update - -#### 2. **Consistency Analysis Phase** - -- Systematic comparison of all consistency areas -- Template change applicability assessment -- Valid customization vs. drift classification - -#### 3. **Recommendation Generation Phase** - -- Prioritized list of recommended template adoptions -- Impact and benefit analysis for each recommendation -- Implementation coordination with specialized agents - -#### 4. **Implementation Coordination Phase** - -- Hand-off to appropriate specialized agents for specific changes -- Quality verification of implemented changes -- Validation of preserved customizations and functionality - -## Compliance Verification Checklist - -### Before Completing Consistency Analysis - -1. **Template Currency**: Current template state analyzed and recent changes identified -2. **Comprehensive Coverage**: All major consistency areas systematically reviewed -3. **Change Classification**: Template changes properly categorized and assessed -4. **Valid Customizations**: Project-specific customizations preserved and documented -5. **Implementation Guidance**: Clear, actionable recommendations with priority levels -6. **Agent Coordination**: Appropriate specialized agents identified for implementation -7. **Risk Assessment**: Implementation risks and mitigation strategies identified +1. Fetch the last 20 merged PRs (`is:pr is:merged`) from +2. Determine the intent of the template pull requests (what changes were performed to which files) +3. Apply missing changes to this repository's files (if appropriate and with translation) ## Don't Do These Things @@ -283,7 +29,6 @@ This agent is designed for downstream repository analysis (not TemplateDotNetLib - **Never apply template changes blindly** without assessing downstream project impact - **Never ignore template evolution benefits** when they clearly improve downstream projects - **Never recommend breaking changes** without migration guidance and impact assessment -- **Never modify downstream code directly** (coordinate through appropriate specialized agents) - **Never skip validation** of preserved functionality after template alignment - **Never assume all template patterns apply universally** (assess project-specific needs) @@ -292,5 +37,3 @@ This agent is designed for downstream repository analysis (not TemplateDotNetLib - **Evolutionary Consistency**: Template improvements should enhance downstream projects systematically - **Intelligent Customization Respect**: Distinguished valid customizations from unintentional drift - **Incremental Template Adoption**: Support phased adoption of template improvements based on project capacity -- **Evidence-Based Recommendations**: All consistency recommendations backed by clear benefits and rationale -- **Cross-Agent Coordination**: Leverage specialized agents for implementation while maintaining oversight