From 321e0fe1fe691de2c4f50df4368b91170d553587 Mon Sep 17 00:00:00 2001 From: Diego Mauricio Lagos Date: Tue, 10 Mar 2026 14:47:12 +0100 Subject: [PATCH 1/4] feat(agents): add TechAIPairArchitectAnalysisExecutor for validated execution planning --- .github/agents/README.md | 2 + ...-pair-architect-analysis-executor.agent.md | 66 ++++++++++++++ .../agents/tech-ai-pair-architect.agent.md | 3 +- .../SKILL.md | 90 +++++++++++++++++++ 4 files changed, 160 insertions(+), 1 deletion(-) create mode 100644 .github/agents/tech-ai-pair-architect-analysis-executor.agent.md create mode 100644 .github/skills/tech-ai-pair-architect-analysis-executor/SKILL.md diff --git a/.github/agents/README.md b/.github/agents/README.md index 0b74689..38554c9 100644 --- a/.github/agents/README.md +++ b/.github/agents/README.md @@ -10,6 +10,7 @@ This folder contains optional custom agents for focused tasks. ## Recommended routing - Read-only: `TechAIPlanner`, `TechAIReviewer`, `TechAISecurityReviewer`, `TechAIWorkflowSupplyChain`, `TechAITerraformGuardrails`, `TechAIIAMLeastPrivilege`. +- Analysis-to-plan: `TechAIPairArchitectAnalysisExecutor` (takes `TechAIPairArchitect` output, re-evaluates, produces execution plan). - PR-focused: `TechAIPRWriter`. - Write-capable: `TechAIImplementer`. - Repo-only standards specialists: `TechAIGlobalCustomizationBuilder`, `TechAIGlobalCustomizationAuditor`. @@ -40,3 +41,4 @@ This folder contains optional custom agents for focused tasks. 9. Use `TechAIGlobalCustomizationAuditor` as the final gate for those customization changes. 10. Use `TechAISyncCopilotConfigs` to align a consumer baseline before creating repo-owned internal assets. 11. Use `TechAIInternalCopilotCustomizationBuilder` for repo-owned `internal-*` prompts, skills, agents, and `AGENTS.md` updates that should stay consumer-repository. +12. Use `TechAIPairArchitectAnalysisExecutor` after `TechAIPairArchitect` to re-evaluate findings, produce a validated execution plan with per-finding decision tables, extract lessons learned, and prepare work packages for `TechAIImplementer`. diff --git a/.github/agents/tech-ai-pair-architect-analysis-executor.agent.md b/.github/agents/tech-ai-pair-architect-analysis-executor.agent.md new file mode 100644 index 0000000..e8e43d8 --- /dev/null +++ b/.github/agents/tech-ai-pair-architect-analysis-executor.agent.md @@ -0,0 +1,66 @@ +--- +description: Re-evaluate the TechAIPairArchitect analysis report, challenge each finding, produce a validated execution plan with per-finding decision tables, and extract lessons learned. +name: TechAIPairArchitectAnalysisExecutor +tools: ["search", "usages", "problems", "editFiles", "runTerminal", "fetch"] +--- + +# TechAI Pair Architect Analysis Executor Agent + +You are a senior staff engineer who turns architectural analysis into validated, actionable execution plans. You are methodical, skeptical, and pragmatic — you never accept an analysis at face value. + +## Persona + +- **Staff Engineer** — "Is this actionable? What is the smallest correct change? What is the blast radius?" +- **Devil's Advocate** — "Is the analysis right? Could the current state be intentional? Is the cure worse than the disease?" +- **Pragmatic Architect** — "Does fixing this deliver value proportional to its cost?" + +Tone: analytical, direct, constructive. Justify every decision. Be transparent about uncertainty. + +## Objective + +Consume `ANALYSIS_REPORT.md` from `TechAIPairArchitect`, re-evaluate every finding against the actual repo state, and produce `EXECUTION_PLAN.md` containing: per-finding decision tables, lessons learned, sequenced work packages, and a validation checklist for the user. + +## Restrictions + +- Do not modify source code until the user validates the plan. +- Do not run destructive commands. +- Base every assessment on concrete repository evidence. +- If `ANALYSIS_REPORT.md` does not exist, stop and report. +- Keep output in English, Markdown format. + +## Workflow + +Use `.github/skills/tech-ai-pair-architect-analysis-executor/SKILL.md` as the single source of truth for decision-table format, report template, disagreement protocol, and quality checklist. + +### Phase 1 — Parse +Read `ANALYSIS_REPORT.md`. Extract every finding with ID, severity, title, description, recommendation. + +### Phase 2 — Verify +For each finding: locate referenced files, verify current state, assess recommendation, determine agreement, define concrete action (or "No action" with justification). + +### Phase 3 — Learn +Identify recurring patterns, systemic insights, prevention opportunities, and knowledge gaps across the full finding set. + +### Phase 4 — Plan +Sequence approved actions by dependency and priority. Group into work packages. Estimate effort, risks, rollback, and validation criteria. + +### Phase 5 — Present +Generate `EXECUTION_PLAN.md` per the skill template. Highlight disagreements. Wait for user approval before any execution. + +## Specialist delegation + +This agent produces the plan only — it does not execute. +- Execution → `TechAIImplementer` +- Terraform → `TechAITerraformGuardrails` +- IAM → `TechAIIAMLeastPrivilege` +- Workflows → `TechAIWorkflowSupplyChain` +- Security → `TechAISecurityReviewer` +- Line-level review → `TechAIScriptReviewer` +- Copilot assets → `TechAIGlobalCustomizationBuilder` + +## Handoff + +- Primary deliverable: `EXECUTION_PLAN.md`. +- Report: total findings, agreements, disagreements, work package count. +- Designed for `TechAIImplementer` to consume as step-by-step guide. +- If no actionable items remain: "All findings addressed or not applicable." diff --git a/.github/agents/tech-ai-pair-architect.agent.md b/.github/agents/tech-ai-pair-architect.agent.md index a15e747..5040149 100644 --- a/.github/agents/tech-ai-pair-architect.agent.md +++ b/.github/agents/tech-ai-pair-architect.agent.md @@ -74,6 +74,7 @@ Do not duplicate those definitions here — defer to the skill file at runtime. - The generated `ANALYSIS_REPORT.md` is the primary deliverable. - Always report the health score and verdict in the handoff message. -- If `Critical` errors are found, explicitly recommend routing to `TechAIImplementer` for remediation before merge. +- For validated execution planning, route to `TechAIPairArchitectAnalysisExecutor` — it will re-evaluate each finding, produce per-finding decision tables, extract lessons learned, and generate a sequenced execution plan for user validation. +- If `Critical` errors are found, explicitly recommend routing to `TechAIPairArchitectAnalysisExecutor` for plan generation, then to `TechAIImplementer` for remediation before merge. - If the analysis is clean, state it explicitly: "No blocking issues found. Change set is ready for peer review." diff --git a/.github/skills/tech-ai-pair-architect-analysis-executor/SKILL.md b/.github/skills/tech-ai-pair-architect-analysis-executor/SKILL.md new file mode 100644 index 0000000..ba307ef --- /dev/null +++ b/.github/skills/tech-ai-pair-architect-analysis-executor/SKILL.md @@ -0,0 +1,90 @@ +--- +name: TechAIPairArchitectAnalysisExecutor +description: Templates, decision-table format, and validation rules for re-evaluating an ANALYSIS_REPORT and producing an EXECUTION_PLAN. +--- + +# Pair Architect Analysis Executor Skill + +## When to use +- After `TechAIPairArchitect` has produced an `ANALYSIS_REPORT.md`. +- To critically verify each finding against the actual codebase. +- To generate a validated, sequenced `EXECUTION_PLAN.md` ready for `TechAIImplementer`. + +## Decision table format + +For **each** finding produce exactly this table (no empty cells): + +```markdown +#### [] + +| Aspect | Detail | +|---|---| +| **What the analysis says** | | +| **Why it says it** | | +| **Agreement** | ✅ Agree / ⚠️ Partially Agree / ❌ Disagree | +| **Motivation** | | +| **Concrete action** | | +| **Effort** | Low / Medium / High | +| **Priority** | P0 (blocker) / P1 (before merge) / P2 (next sprint) / P3 (backlog) | +``` + +Group tables by original report section (Errors, Improvements, Doubts, Blind Spots, Architecture, Devil's Advocate). + +## Report template — EXECUTION_PLAN.md + +All five sections are mandatory. + +### Section 1 — Executive Summary +3-5 sentences: what the analysis found, how many findings validated vs challenged, analysis quality assessment, proposed approach. + +### Section 2 — Finding-by-Finding Evaluation +One decision table per finding (format above). + +### Section 3 — Lessons Learned + +| Subsection | Content | +|---|---| +| 3.1 Recurring Patterns | Table: Pattern / Affected Findings / Root Cause / Systemic Fix | +| 3.2 Repository Maturity Insights | Prose: strengths, weaknesses, direction | +| 3.3 Prevention Mechanisms | Table: Gap / Proposed Prevention / Type (Tooling/Process/Convention) | +| 3.4 Knowledge Gaps | Prose: areas needing better docs or understanding | + +### Section 4 — Execution Plan + +| Subsection | Content | +|---|---| +| 4.1 Work Packages | Table: # / Name / Findings Addressed / Actions / Effort / Priority / Dependencies | +| 4.2 Execution Sequence | Ordered list with rationale | +| 4.3 Risk Assessment | Table: Risk / Impact / Mitigation / Rollback | +| 4.4 Validation Criteria | Table: Work Package / Validation Method / Expected Result | + +### Section 5 — Summary for Validation + +Checklist for user approval: + +```markdown +- [ ] **WP-1**: (P0, effort: Low) +- ... + +### Key Decisions Requiring Attention +1. **[]**: Disagreement — . Alternative: . +``` + +## Disagreement protocol + +When disagreeing with a finding: +1. Mark ❌ in the decision table. +2. Cite concrete evidence (file, line, git history). +3. Explain what the analysis missed. +4. Propose alternative or "No action". +5. Surface in Section 5 "Key Decisions". + +## Quality checklist + +- [ ] Every decision table is complete — no empty cells. +- [ ] Every "Concrete action" is specific enough for `TechAIImplementer` without re-analysis. +- [ ] Every disagreement includes evidence, not opinion. +- [ ] Execution plan is dependency-ordered. +- [ ] Effort estimates are realistic. +- [ ] Lessons Learned contains systemic insights, not finding repetitions. +- [ ] Work packages are grouped by logical affinity, not listed 1:1 per finding. From 4fa730a2972f64067d4affb6839f7d0fc4185fd3 Mon Sep 17 00:00:00 2001 From: Diego Mauricio Lagos Date: Tue, 10 Mar 2026 14:48:39 +0100 Subject: [PATCH 2/4] feat(agents): add TechAIPairArchitectAnalysisExecutor for validated execution planning and update usage guidelines --- .../prompts/tech-ai-pair-architect-analysis.prompt.md | 11 +++++++++++ AGENTS.md | 10 ++++++++-- 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/.github/prompts/tech-ai-pair-architect-analysis.prompt.md b/.github/prompts/tech-ai-pair-architect-analysis.prompt.md index fc9e148..177d038 100644 --- a/.github/prompts/tech-ai-pair-architect-analysis.prompt.md +++ b/.github/prompts/tech-ai-pair-architect-analysis.prompt.md @@ -32,3 +32,14 @@ After generating the report: - If Critical errors exist, recommend routing to `TechAIImplementer` for remediation. - If the change set is clean, state it explicitly. +## Minimal example +- Input: `target=HEAD~3..HEAD output=ANALYSIS_REPORT.md depth=full mode=devil` +- Expected output: + - `ANALYSIS_REPORT.md` written at repository root. + - Health score, verdict, and severity-ordered findings backed by concrete file references. + - A clear next-step recommendation for remediation or peer review. + +## Validation +- Keep `.github/skills/tech-ai-pair-architect/SKILL.md` as the referenced analysis framework. +- Generate a valid Markdown report with all mandatory sections required by that skill. +- Cite concrete file paths and line numbers for every finding. diff --git a/AGENTS.md b/AGENTS.md index 66ac9f9..c37b6df 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,6 +34,7 @@ This file is for GitHub Copilot and AI assistants working in this repository. - Use `TechAIReviewer` for quality gates and defect or regression findings. - Use `TechAIScriptReviewer` for exhaustive, nit-level reviews on Python, Bash, and Terraform. - Use `TechAIPairArchitect` for deep change-impact analysis with DDD focus, blind-spot detection, and structured Markdown report generation. +- Use `TechAIPairArchitectAnalysisExecutor` after `TechAIPairArchitect` when the user wants a validated execution plan from `ANALYSIS_REPORT.md` before implementation. - Use `TechAIGlobalCustomizationBuilder` as the default specialist for creating or updating GitHub Copilot customization assets in this repository. - Use `TechAIGlobalCustomizationAuditor` as the final quality gate for GitHub Copilot customization changes in this repository. - Use `TechAICustomizationAuditor` only as a deprecated compatibility alias while older references are migrated. @@ -56,6 +57,7 @@ This file is for GitHub Copilot and AI assistants working in this repository. - Do not use `TechAIPairArchitect` for quick line-level nit reviews; use `TechAIScriptReviewer` or `TechAICodeReview` instead. - Do not use `TechAIReviewer` when you need holistic change-set impact analysis with DDD, architecture, and blind spots; use `TechAIPairArchitect`. - Do not use `TechAIPairArchitect` for exhaustive per-language anti-pattern scanning; use `TechAIScriptReviewer` and then `TechAIPairArchitect` for the bigger picture. +- Do not send a complex `ANALYSIS_REPORT.md` straight to `TechAIImplementer` when the user first needs a validated remediation plan; use `TechAIPairArchitectAnalysisExecutor`. ### Composition and Handoffs @@ -68,8 +70,9 @@ This file is for GitHub Copilot and AI assistants working in this repository. - `TechAIReviewer` findings flagged as `Critical` or `Major` route back to `TechAIImplementer` for remediation. - `TechAIGlobalCustomizationBuilder` output is input context for `TechAIGlobalCustomizationAuditor`. - `TechAIGlobalCustomizationAuditor` findings flagged as `Critical` or `Major` route back to `TechAIGlobalCustomizationBuilder` for remediation. -- `TechAIPairArchitect` output (`ANALYSIS_REPORT.md`) is input context for `TechAIImplementer` when remediation is needed. -- For thorough pre-merge validation, the recommended chain is `TechAIImplementer` -> `TechAIPairArchitect` -> `TechAIImplementer` (remediation). +- `TechAIPairArchitect` output (`ANALYSIS_REPORT.md`) is input context for `TechAIPairArchitectAnalysisExecutor` when a validated execution plan is needed. +- `TechAIPairArchitectAnalysisExecutor` output (`EXECUTION_PLAN.md`) is input context for `TechAIImplementer` after the user approves execution. +- For thorough pre-merge validation, the recommended chain is `TechAIImplementer` -> `TechAIPairArchitect` -> `TechAIPairArchitectAnalysisExecutor` -> `TechAIImplementer`. ## Governance References @@ -154,6 +157,7 @@ This file is for GitHub Copilot and AI assistants working in this repository. - `TechAICloudPolicy`: reusable cloud policy authoring patterns. - `TechAITerraformModule`: reusable Terraform module design. - `TechAIPairArchitect`: change-set-level impact, DDD smell catalog, health scoring, risk matrix, and blind-spot detection. +- `TechAIPairArchitectAnalysisExecutor`: per-finding re-evaluation, decision tables, lessons learned, and validated execution planning. ### Required validations before PR @@ -205,6 +209,7 @@ This file is for GitHub Copilot and AI assistants working in this repository. ### Skills +- `.github/skills/tech-ai-pair-architect-analysis-executor/SKILL.md` - `.github/skills/tech-ai-pair-architect/SKILL.md` - `.github/skills/tech-ai-cicd-workflow/SKILL.md` - `.github/skills/tech-ai-cloud-policy/SKILL.md` @@ -224,6 +229,7 @@ This file is for GitHub Copilot and AI assistants working in this repository. ### Agents +- `.github/agents/tech-ai-pair-architect-analysis-executor.agent.md` - `.github/agents/tech-ai-pair-architect.agent.md` - `.github/agents/tech-ai-customization-auditor.agent.md` - `.github/agents/tech-ai-github-pr-writer.agent.md` From d5507e009df9c6cd9acd9f895388e690df44c9fe Mon Sep 17 00:00:00 2001 From: Diego Mauricio Lagos Date: Tue, 10 Mar 2026 14:50:44 +0100 Subject: [PATCH 3/4] feat(analysis): enhance TechAIPairArchitectAnalysisExecutor with validation rules and execution plan requirements --- .github/prompts/tech-ai-pair-architect-analysis.prompt.md | 1 + .../skills/tech-ai-pair-architect-analysis-executor/SKILL.md | 5 +++++ 2 files changed, 6 insertions(+) diff --git a/.github/prompts/tech-ai-pair-architect-analysis.prompt.md b/.github/prompts/tech-ai-pair-architect-analysis.prompt.md index 177d038..fb4812a 100644 --- a/.github/prompts/tech-ai-pair-architect-analysis.prompt.md +++ b/.github/prompts/tech-ai-pair-architect-analysis.prompt.md @@ -31,6 +31,7 @@ After generating the report: - Print the summary statistics and health score to the conversation. - If Critical errors exist, recommend routing to `TechAIImplementer` for remediation. - If the change set is clean, state it explicitly. +- If the user wants a validated execution plan from the report, hand off to `.github/skills/tech-ai-pair-architect-analysis-executor/SKILL.md` via `TechAIPairArchitectAnalysisExecutor`. ## Minimal example - Input: `target=HEAD~3..HEAD output=ANALYSIS_REPORT.md depth=full mode=devil` diff --git a/.github/skills/tech-ai-pair-architect-analysis-executor/SKILL.md b/.github/skills/tech-ai-pair-architect-analysis-executor/SKILL.md index ba307ef..11b4288 100644 --- a/.github/skills/tech-ai-pair-architect-analysis-executor/SKILL.md +++ b/.github/skills/tech-ai-pair-architect-analysis-executor/SKILL.md @@ -88,3 +88,8 @@ When disagreeing with a finding: - [ ] Effort estimates are realistic. - [ ] Lessons Learned contains systemic insights, not finding repetitions. - [ ] Work packages are grouped by logical affinity, not listed 1:1 per finding. + +## Validation +- Every finding from `ANALYSIS_REPORT.md` must appear exactly once in `EXECUTION_PLAN.md`. +- Every disagreement must cite repository evidence. +- `EXECUTION_PLAN.md` must include all five mandatory sections and complete decision tables. From 5265d8f0502e9970878afed78410969eeb8a3f6e Mon Sep 17 00:00:00 2001 From: Diego Mauricio Lagos Date: Tue, 10 Mar 2026 15:48:42 +0100 Subject: [PATCH 4/4] Refactor Copilot customization agents and skills for improved clarity and functionality - Renamed `TechAISyncCopilotConfigs` to `TechAISyncGlobalCopilotConfigsIntoRepo` for better alignment with its purpose. - Updated agent and skill paths to reflect the new naming convention. - Introduced new skills: `TechAIPREditor` and `TechAIRepoCopilotExtender` to enhance PR editing and internal customization workflows. - Replaced references to deprecated global customization agents with their new counterparts in `AGENTS.md`. - Adjusted validation scripts and tests to accommodate the new agent and skill names. - Enhanced documentation to clarify usage and validation processes for the new agents and skills. --- .github/CHANGELOG.md | 22 +- ...t_template.md => PULL_REQUEST_TEMPLATE.md} | 0 .github/README.md | 277 +++++++++++++++--- .github/agents/README.md | 24 +- .../tech-ai-customization-auditor.agent.md | 2 +- ...-pair-architect-analysis-executor.agent.md | 2 +- ...er.agent.md => tech-ai-pr-editor.agent.md} | 8 +- ...=> tech-ai-repo-copilot-extender.agent.md} | 8 +- ...ai-standards-repo-config-auditor.agent.md} | 6 +- ...ai-standards-repo-config-builder.agent.md} | 6 +- ...global-copilot-configs-into-repo.agent.md} | 6 +- ...pt.md => tech-ai-pr-description.prompt.md} | 12 +- ...> tech-ai-repo-copilot-extender.prompt.md} | 8 +- ...lobal-copilot-configs-into-repo.prompt.md} | 6 +- .../scripts/tech-ai-sync-copilot-configs.py | 30 +- .../validate-copilot-customizations.sh | 31 +- .../SKILL.md | 10 +- .../SKILL.md | 12 +- .../SKILL.md | 10 +- AGENTS.md | 62 ++-- ANALYSIS_REPORT.md | 2 +- CONTRIBUTING.md | 4 +- COPILOT_REVIEW.md | 14 +- tests/test_tech_ai_sync_copilot_configs.py | 24 +- ...tech_ai_validate_copilot_customizations.py | 18 +- 25 files changed, 410 insertions(+), 194 deletions(-) rename .github/{pull_request_template.md => PULL_REQUEST_TEMPLATE.md} (100%) rename .github/agents/{tech-ai-github-pr-writer.agent.md => tech-ai-pr-editor.agent.md} (91%) rename .github/agents/{tech-ai-internal-copilot-customization-builder.agent.md => tech-ai-repo-copilot-extender.agent.md} (84%) rename .github/agents/{tech-ai-global-customization-auditor.agent.md => tech-ai-standards-repo-config-auditor.agent.md} (88%) rename .github/agents/{tech-ai-global-customization-builder.agent.md => tech-ai-standards-repo-config-builder.agent.md} (93%) rename .github/agents/{tech-ai-sync-copilot-configs.agent.md => tech-ai-sync-global-copilot-configs-into-repo.agent.md} (84%) rename .github/prompts/{tech-ai-github-pr-description.prompt.md => tech-ai-pr-description.prompt.md} (93%) rename .github/prompts/{tech-ai-internal-copilot-customization-builder.prompt.md => tech-ai-repo-copilot-extender.prompt.md} (85%) rename .github/prompts/{tech-ai-sync-copilot-configs.prompt.md => tech-ai-sync-global-copilot-configs-into-repo.prompt.md} (88%) rename .github/skills/{tech-ai-pr-writing => tech-ai-pr-editor}/SKILL.md (92%) rename .github/skills/{tech-ai-internal-copilot-customization-builder => tech-ai-repo-copilot-extender}/SKILL.md (87%) rename .github/skills/{tech-ai-sync-copilot-configs => tech-ai-sync-global-copilot-configs-into-repo}/SKILL.md (88%) diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md index 1432a98..220c126 100644 --- a/.github/CHANGELOG.md +++ b/.github/CHANGELOG.md @@ -7,8 +7,8 @@ Use this format for new updates: - Include file/path scope when useful. ## 2026-03-09 -- Added the repo-only `TechAIInternalCopilotCustomizationBuilder` agent, prompt, and skill for creating consumer-repository `internal-*` Copilot assets without duplicating the shared baseline, and excluded the trio from consumer sync. -- Tightened `TechAIInternalCopilotCustomizationBuilder` so it must ground repo-local prompts, examples, schema snippets, and naming rules on concrete target files instead of generic remembered patterns. +- Added the repo-only `TechAIRepoCopilotExtender` agent, prompt, and skill for creating consumer-repository `internal-*` Copilot assets without duplicating the shared baseline, and excluded the trio from consumer sync. +- Tightened `TechAIRepoCopilotExtender` so it must ground repo-local prompts, examples, schema snippets, and naming rules on concrete target files instead of generic remembered patterns. - Deprecated `.github/scripts/bootstrap-copilot-config.sh` in favor of `.github/scripts/tech-ai-sync-copilot-configs.py`, updated lifecycle docs, and made quickstart plus `.github/README.md` prefer sync-first alignment. - Added source release metadata with root `VERSION`, contributor workflow documentation, and manifest provenance fields for source version and commit. - Tightened consumer alignment: improved composite-action detection, enabled data-registry selection for JSON-heavy repositories, slimmed generated `AGENTS.md`, removed spurious `pytest` recommendations for repos without pytest tests, and added sync recommendations for missing Copilot validation workflows plus legacy source-only residues. @@ -23,31 +23,31 @@ Use this format for new updates: - Updated sync planning so legacy aliases such as `cs-*`, unprefixed prompt names, and legacy skill directories are reported even when the canonical family is outside the selected minimum baseline. - Updated generated `AGENTS.md` inventory rendering and `.github/templates/AGENTS.template.md` so inventory reflects the desired managed baseline plus target-local Copilot assets already present in the consumer repository. - Added source-side redundancy auditing to `scripts/tech-ai-sync-copilot-configs.py`, including canonical asset inventory, legacy alias detection, triad role-overlap checks, and `AGENTS.md` inventory-repeat detection in both markdown and JSON reports. -- Refactored `agents/tech-ai-sync-copilot-configs.agent.md`, `skills/tech-ai-sync-copilot-configs/SKILL.md`, and `prompts/tech-ai-sync-copilot-configs.prompt.md` so workflow detail lives in the skill while the agent and prompt stay thin. +- Refactored `agents/tech-ai-sync-global-copilot-configs-into-repo.agent.md`, `skills/tech-ai-sync-global-copilot-configs-into-repo/SKILL.md`, and `prompts/tech-ai-sync-global-copilot-configs-into-repo.prompt.md` so workflow detail lives in the skill while the agent and prompt stay thin. - Simplified root `AGENTS.md` and `.github/templates/AGENTS.template.md` to keep asset paths in the inventory section only and remove descriptive prompt or skill catalogs. - Expanded sync and validator tests to cover source audit behavior, slimmer AGENTS structure, and JSON report sections. -- Updated `agents/tech-ai-sync-copilot-configs.agent.md`, `skills/tech-ai-sync-copilot-configs/SKILL.md`, and `prompts/tech-ai-sync-copilot-configs.prompt.md` so the sync workflow explicitly detects redundant legacy aliases before apply. +- Updated `agents/tech-ai-sync-global-copilot-configs-into-repo.agent.md`, `skills/tech-ai-sync-global-copilot-configs-into-repo/SKILL.md`, and `prompts/tech-ai-sync-global-copilot-configs-into-repo.prompt.md` so the sync workflow explicitly detects redundant legacy aliases before apply. - Updated `scripts/tech-ai-sync-copilot-configs.py` to recognize legacy `cs-*`, unprefixed prompt names, and legacy agent or skill aliases, report them as redundant target assets, and raise sync conflicts instead of creating duplicate canonical `tech-ai-*` assets. - Updated `tests/test_tech_ai_sync_copilot_configs.py` to cover duplicate-alias detection and conflict behavior during sync planning. ## 2026-03-07 -- Added repo-only global customization agents `TechAIGlobalCustomizationBuilder` and `TechAIGlobalCustomizationAuditor` for standards-authoring and final quality gates in this repository. -- Marked `TechAICustomizationAuditor` as a deprecated compatibility alias that now points to `TechAIGlobalCustomizationAuditor`. +- Added repo-only global customization agents `TechAIStandardsRepoConfigBuilder` and `TechAIStandardsRepoConfigAuditor` for standards-authoring and final quality gates in this repository. +- Marked `TechAICustomizationAuditor` as a deprecated compatibility alias that now points to `TechAIStandardsRepoConfigAuditor`. - Updated root `AGENTS.md`, agent catalog docs, sync exclusions, validator semantics, and tests to treat the `TechAIGlobal*` pair as repo-only standards agents. - Added `.gitignore` coverage for Python caches/virtualenvs and macOS Finder artifacts so local validation runs stop creating noisy untracked files. - Added canonical low-duplication script prompts: `prompts/tech-ai-bash-script.prompt.md` (`TechAIBashScript`) and `prompts/tech-ai-python-script.prompt.md` (`TechAIPythonScript`). - Reduced the legacy `cs-*` and `script-*` Bash/Python prompts to thin compatibility aliases that now point to the canonical TechAI prompts. - Updated `scripts/tech-ai-sync-copilot-configs.py`, `AGENTS.md`, and tests to prefer the new `tech-ai-*` canonical script prompts. - Reduced token overlap by trimming repository-specific catalog content out of `copilot-instructions.md` and keeping `AGENTS.md` as the single repository-specific source of truth. -- Normalized the `name:` frontmatter for the TechAI sync prompt and skill to `TechAISyncCopilotConfigs`. +- Normalized the `name:` frontmatter for the TechAI sync prompt and skill to `TechAISyncGlobalCopilotConfigsIntoRepo`. - Renamed the remaining canonical `cs-*` prompt files to `tech-ai-*` and updated profile, AGENTS, sync, and test references accordingly. - Removed the redundant `script-bash.prompt.md` and `script-python.prompt.md` alias prompts to keep one canonical script prompt per stack. ## 2026-03-06 -- Added `agents/tech-ai-sync-copilot-configs.agent.md`: `TechAISyncCopilotConfigs` for local repository analysis and conservative Copilot-core alignment. -- Added `prompts/tech-ai-sync-copilot-configs.prompt.md` and `skills/tech-ai-sync-copilot-configs/SKILL.md` for repeatable alignment workflows. +- Added `agents/tech-ai-sync-global-copilot-configs-into-repo.agent.md`: `TechAISyncGlobalCopilotConfigsIntoRepo` for local repository analysis and conservative Copilot-core alignment. +- Added `prompts/tech-ai-sync-global-copilot-configs-into-repo.prompt.md` and `skills/tech-ai-sync-global-copilot-configs-into-repo/SKILL.md` for repeatable alignment workflows. - Added `scripts/tech-ai-sync-copilot-configs.py` plus `tests/test_tech_ai_sync_copilot_configs.py` for deterministic analysis, manifest-based sync planning, and reporting. -- Updated `AGENTS.md` with `TechAISyncCopilotConfigs` routing, inventory, and preferred asset references. +- Updated `AGENTS.md` with `TechAISyncGlobalCopilotConfigsIntoRepo` routing, inventory, and preferred asset references. - Reduced `copilot-code-review-instructions.md` to a lighter-weight review protocol that delegates the detailed anti-pattern catalog to `skills/tech-ai-code-review/SKILL.md`. - Updated `scripts/tech-ai-sync-copilot-configs.py` to prefer canonical `cs-*` script prompts during consumer alignment, reducing prompt duplication and token footprint without removing legacy source assets. - Added `.github/tech-ai-requirements-dev.txt`, CI pytest execution, `shellcheck` pre-commit coverage, and validator integration tests for stronger local and CI validation. @@ -77,7 +77,7 @@ Use this format for new updates: - Added `instructions/composite-action.instructions.md` for reusable composite actions. - Added `scripts/bootstrap-copilot-config.sh` for safe `.github` bootstrap and sync. - Added `templates/copilot-quickstart.md` for portable onboarding. -- Added PR authoring assets: `prompts/tech-ai-github-pr-description.prompt.md` and `skills/tech-ai-pr-writing/SKILL.md`. +- Added PR authoring assets: `prompts/tech-ai-pr-description.prompt.md` and `skills/tech-ai-pr-editor/SKILL.md`. - Updated docs to be repository-agnostic and reusable across different tech stacks. - Standardized script prompt wording to remove organization-specific terminology and keep language portable. - Hardened validator frontmatter key detection for multiline YAML keys. diff --git a/.github/pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE.md similarity index 100% rename from .github/pull_request_template.md rename to .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/README.md b/.github/README.md index 26a5012..16ed967 100644 --- a/.github/README.md +++ b/.github/README.md @@ -1,42 +1,251 @@ # .github Configuration -This folder contains global GitHub Copilot customization that can be reused across repositories. +This folder is the **single source of truth** for GitHub Copilot customization assets propagated to all consumer repositories. It defines rules, prompts, skills, agents, and tooling that ensure consistent AI-assisted development across the organization. + +--- ## Structure -- `copilot-instructions.md`: global baseline rules -- `copilot-commit-message-instructions.md`: commit message policy -- `copilot-code-review-instructions.md`: review policy -- `repo-profiles.yml`: reusable high-level profile catalog for different repo types -- `security-baseline.md`: portable security baseline checklist -- `DEPRECATION.md`: lifecycle policy for prompts/skills/instructions/agents -- `instructions/`: path-specific auto-applied rules -- `prompts/`: reusable slash prompts -- `skills/`: reusable implementation capabilities -- `agents/`: optional custom chat agents -- `scripts/`: validation scripts -- `workflows/`: CI validation workflows -- `templates/`: reusable templates (for example root-level `AGENTS.md`) - -## Agent routing -- Read-only agents: `TechAIPlanner`, `TechAIReviewer`, `TechAISecurityReviewer`, `TechAIWorkflowSupplyChain`, `TechAITerraformGuardrails`, `TechAIIAMLeastPrivilege` -- Write-capable agent: `TechAIImplementer` -- Repo-only global customization agents: `TechAIGlobalCustomizationBuilder`, `TechAIGlobalCustomizationAuditor` - -See `.github/agents/README.md` for details. + +### Baseline files (always applied) + +| File | Purpose | Use when | Do NOT use when | +| --- | --- | --- | --- | +| `copilot-instructions.md` | Global non-negotiable rules: language policy, least privilege, DDD preference, test execution order, script standards, validation baseline. | Every Copilot interaction — this is the root of the instruction chain. | Never skip — it's always loaded first. | +| `copilot-commit-message-instructions.md` | Commit message format: `(): `, imperative mood, 72-char limit. | Writing commits via Copilot or reviewing commit messages. | Manual commits that follow the same convention already. | +| `copilot-code-review-instructions.md` | Review severity levels, baseline checks, escalation rules. References `tech-ai-code-review/SKILL.md` for anti-pattern catalogs. | Running Copilot code review or configuring review agents. | Deep per-line review (use `TechAIScriptReviewer` instead). | +| `security-baseline.md` | Portable security checklist: SHA-pinned actions, minimal permissions, OIDC, branch protection, prompt/agent safety. | Every infrastructure or workflow change. Referenced by all agents as a minimum bar. | Application-only code changes with no infra impact. | + +### Configuration and governance + +| File | Purpose | Use when | Do NOT use when | +| --- | --- | --- | --- | +| `repo-profiles.yml` | Advisory catalog of 6 profiles (`minimal`, `backend-java`, `backend-nodejs`, `backend-python`, `infrastructure-heavy`, `mixed-platform`). Maps each to recommended instructions, prompts, and skills. | Onboarding a new consumer repo — pick a profile to bootstrap the right asset set. | Enforcement — profiles are advisory today, not enforced by validators. | +| `DEPRECATION.md` | Lifecycle policy (Active → Deprecated → Removed) with 30-day window, migration guidance, emergency exception for security. | Sunsetting a prompt, skill, instruction, or agent. Check before removing anything. | Creating new assets (no lifecycle concerns for new additions). | +| `CHANGELOG.md` | Change log for notable modifications to customization assets. | After every meaningful change to `.github/` — update as last maintenance step. | Minor formatting or comment-only changes. | +| `dependabot.yml` | Dependabot configuration for automated dependency updates. | Configuring update schedules for consumer repos using this as a template. | This repo itself only uses Python stdlib + pytest — the npm/maven/gradle ecosystems are templates for consumers. | +| `PULL_REQUEST_TEMPLATE.md` | PR template with sections: Description, Change Type, Consumer Impact, Testing, Validation Evidence, Breaking Changes, Checklist. | Every PR to this repository. Auto-loaded by GitHub. | Consumer repos — they should define their own PR template. | +| `tech-ai-requirements-dev.txt` | Dev dependencies for the test suite (currently: `pytest==8.3.3`). | Running `make test` or `pytest` locally. | Production — there are no runtime dependencies. | +| `.bootstrap-ignore` | Rsync exclude patterns for the deprecated `bootstrap-copilot-config.sh`. | Only if still using the legacy bootstrap path. | The preferred sync script — it uses its own manifest logic. | + +### Instructions (`instructions/`) + +Path-specific rules auto-applied by Copilot when editing matching files. Each instruction targets a language or file type via `applyTo` glob patterns. + +| Category | Files | Example use case | +| --- | --- | --- | +| **Languages** | `bash`, `java`, `nodejs`, `python` | Editing a `.py` file → `python.instructions.md` auto-applies with naming, testing, and style rules. | +| **Infrastructure** | `terraform`, `makefile` | Running `terraform plan` or editing a `Makefile` → relevant conventions auto-apply. | +| **CI/CD** | `github-actions`, `github-action-composite` | Editing a workflow YAML → SHA-pinning, permission, and caching rules auto-apply. | +| **Data formats** | `json`, `yaml`, `markdown` | Editing a `README.md` → Markdown linting and structural rules auto-apply. | +| **Scripts** | `scripts`, `lambda` | Editing a script or Lambda handler → orchestration and logging conventions auto-apply. | + +**When to use**: Instructions are automatic — they apply based on file path. No manual invocation needed. +**When NOT to use**: Don't reference instructions directly in prompts — Copilot resolves them from `applyTo` rules. + +### Prompts (`prompts/`) + +Slash-command prompts invoked via `/` in Copilot chat for structured, repeatable tasks. + +**When to use**: You need a consistent, reproducible output for a known task type. +**When NOT to use**: Ad-hoc questions, exploratory conversations, or one-off edits — just chat normally. + +#### Language and project scaffolding + +| Prompt | Purpose | Example trigger | +| --- | --- | --- | +| `tech-ai-java` | Create or modify Java project components (services, controllers, handlers) with JUnit 5 tests. | `/tech-ai-java action=create component_type=service component_name=PaymentService purpose="process payments"` | +| `tech-ai-nodejs` | Create or modify Node.js modules (services, handlers, adapters) with `node:test` tests. | `/tech-ai-nodejs action=create component_type=handler component_name=webhook purpose="receive Stripe events"` | +| `tech-ai-python` | Create or modify Python application components (DDD entities, services, adapters) with pytest. | `/tech-ai-python action=create component_type=domain_service component_name=InvoiceService purpose="invoice generation"` | +| `tech-ai-python-script` | Create or modify standalone Python scripts with explicit interfaces, emoji logs, pinned deps. | `/tech-ai-python-script action=create script_name=migrate-data purpose="migrate legacy DB records"` | +| `tech-ai-bash-script` | Create or modify Bash scripts with strict mode, guard clauses, emoji logs. | `/tech-ai-bash-script action=create script_name=cleanup-ecr purpose="prune untagged ECR images"` | + +#### Infrastructure + +| Prompt | Purpose | Example trigger | +| --- | --- | --- | +| `tech-ai-terraform` | Create or modify Terraform resources and features in an existing stack. | `/tech-ai-terraform action=create type=resource description="S3 bucket for logs" target_dir=src/infra/prod` | +| `tech-ai-terraform-module` | Create or modify reusable Terraform modules with standard file layout. | `/tech-ai-terraform-module action=create module_name=vpc purpose="shared VPC with public/private subnets"` | +| `tech-ai-cloud-policy` | Create or modify cloud governance policies (AWS SCP, Azure Policy, GCP Org Policy). | `/tech-ai-cloud-policy action=create cloud=aws policy_name=deny-public-s3 purpose="block public S3 buckets"` | + +#### CI/CD + +| Prompt | Purpose | Example trigger | +| --- | --- | --- | +| `tech-ai-cicd-workflow` | Create or modify reusable GitHub Actions workflows for CI/CD and governance. | `/tech-ai-cicd-workflow action=create workflow_name=deploy-staging purpose="deploy to staging on push to main" trigger=push` | +| `tech-ai-github-action` | Create or modify a single GitHub Actions workflow file. | `/tech-ai-github-action action=create workflow_name=lint purpose="run linters on PR" triggers=pull_request` | +| `tech-ai-github-composite-action` | Create or modify a reusable GitHub composite action. | `/tech-ai-github-composite-action action=create action_name=setup-node purpose="install Node.js with caching"` | + +#### Review, analysis, and PR + +| Prompt | Purpose | Example trigger | +| --- | --- | --- | +| `tech-ai-code-review` | Exhaustive, nit-level code review on Python, Bash, or Terraform files. | `/tech-ai-code-review target=src/infra/modules/vpc language=terraform strictness=strict` | +| `tech-ai-pair-architect-analysis` | Deep change-impact analysis: errors, improvements, blind spots, DDD, and architecture. Generates `ANALYSIS_REPORT.md`. | `/tech-ai-pair-architect-analysis target=main depth=full mode=devil` | +| `tech-ai-pr-description` | Generate a PR description from the repo template and the current diff. | `/tech-ai-pr-description title="Add VPC module" intent="shared networking" changed_files=src/infra/modules/vpc` | + +#### Testing and reporting + +| Prompt | Purpose | Example trigger | +| --- | --- | --- | +| `tech-ai-add-unit-tests` | Add or improve unit tests for Python code following org conventions. | `/tech-ai-add-unit-tests target_file=src/services/payment.py` | +| `tech-ai-add-report-script` | Add or update a reporting/governance script with configurable output format. | `/tech-ai-add-report-script action=create script_name=orphan-finder purpose="find unused IAM roles" output_format=json` | + +#### Operations and governance + +| Prompt | Purpose | Example trigger | +| --- | --- | --- | +| `tech-ai-data-registry` | Add, modify, or remove entries in structured JSON/YAML registry files. | `/tech-ai-data-registry action=create file=config/users.json key=new-user change="add service account"` | +| `tech-ai-add-platform` | Add or update a reusable platform/profile definition for repo standards. | `/tech-ai-add-platform action=add platform_id=ml-training primary_stack=python goal="ML training pipelines"` | +| `tech-ai-sync-global-copilot-configs-into-repo` | Analyze and align a consumer repo with the minimum Copilot customization assets from this standards repo. | `/tech-ai-sync-global-copilot-configs-into-repo target_repo=../oneidentity mode=plan` | + +#### Copilot customization (consumer repos) + +| Prompt | Purpose | Example trigger | +| --- | --- | --- | +| `tech-ai-repo-copilot-extender` | Create or update repo-owned `internal-*` Copilot assets in a consumer repo without duplicating the shared baseline. | `/tech-ai-repo-copilot-extender target_repo=../onemail change="add internal prompt for email templates" internal_asset_type=prompt` | + +### Skills (`skills/`) + +Implementation knowledge bases loaded on demand by agents and prompts. They contain templates, anti-pattern catalogs, and generation patterns. You rarely invoke skills directly — they are consumed automatically when you use the matching prompt or agent. + +**When to use**: Referenced automatically by agents/prompts. Read a SKILL.md directly only when debugging agent behavior or understanding what patterns are applied. +**When NOT to use**: Don't load skills manually in normal workflows. + +| Skill | Purpose | Consumed by | +| --- | --- | --- | +| `tech-ai-pair-architect` | DDD analysis dimensions, severity mappings, health score, risk matrix format, report template for change-impact analysis. | Agent `TechAIPairArchitect`, prompt `tech-ai-pair-architect-analysis` | +| `tech-ai-pair-architect-analysis-executor` | Decision-table format, execution plan template, disagreement protocol, quality checklist for re-evaluating analysis reports. | Agent `TechAIPairArchitectAnalysisExecutor` | +| `tech-ai-code-review` | Per-language anti-pattern catalogs (Python, Bash, Terraform), severity mappings, escalation rules for exhaustive code review. | Agents `TechAIScriptReviewer`, `TechAIPairArchitect`; prompt `tech-ai-code-review` | +| `tech-ai-pr-editor` | PR description templates, section structure, and diff-to-description mapping for generating review-ready PR bodies. | Agent `TechAIPREditor`, prompt `tech-ai-pr-description` | +| `tech-ai-project-java` | Java component scaffolding: purpose JavaDoc, BDD-like JUnit 5 tests, module conventions. | Prompt `tech-ai-java` | +| `tech-ai-project-nodejs` | Node.js module scaffolding: purpose comments, `node:test` tests, adapter patterns. | Prompt `tech-ai-nodejs` | +| `tech-ai-project-python` | Python application scaffolding: DDD boundaries, early returns, pytest coverage. | Prompt `tech-ai-python` | +| `tech-ai-script-bash` | Bash script patterns: purpose header, emoji logs, guard-clause flow, shellcheck compliance. | Prompt `tech-ai-bash-script` | +| `tech-ai-script-python` | Python script patterns: purpose docstring, emoji logs, pinned deps, unit tests. | Prompt `tech-ai-python-script` | +| `tech-ai-terraform-feature` | Terraform resource/variable/output/data source implementation patterns. | Prompt `tech-ai-terraform` | +| `tech-ai-terraform-module` | Terraform module scaffolding: standard file layout (`main.tf`, `variables.tf`, `outputs.tf`), validation. | Prompt `tech-ai-terraform-module` | +| `tech-ai-cloud-policy` | Cloud governance policy patterns for AWS SCP, Azure Policy, GCP Org Policy. | Prompt `tech-ai-cloud-policy` | +| `tech-ai-cicd-workflow` | Secure GitHub Actions workflow patterns: SHA-pinning, permissions, caching, matrix strategies. | Prompt `tech-ai-cicd-workflow` | +| `tech-ai-composite-action` | Composite action patterns: secure Bash steps, input/output contracts, deterministic behavior. | Prompt `tech-ai-github-composite-action` | +| `tech-ai-data-registry` | JSON/YAML registry update patterns: safe mutations, key validation, schema consistency. | Prompt `tech-ai-data-registry` | +| `tech-ai-sync-global-copilot-configs-into-repo` | Manifest-based sync logic for propagating the shared baseline into consumer repos — asset selection, SHA256 checksums, conflict detection, and reporting. | Agent `TechAISyncGlobalCopilotConfigsIntoRepo`, prompt `tech-ai-sync-global-copilot-configs-into-repo` | +| `tech-ai-repo-copilot-extender` | Generation patterns for repo-specific `internal-*` Copilot assets in consumer repos — naming rules, baseline preservation, `AGENTS.md` integration. | Agent `TechAIRepoCopilotExtender`, prompt `tech-ai-repo-copilot-extender` | + +### Agents (`agents/`) + +Custom chat agents for focused tasks. Each agent has a single responsibility. See [`agents/README.md`](agents/README.md) for the full selection guide. + +**When to use**: Route to agents based on your workflow step. +**When NOT to use**: Simple questions or one-off edits — Copilot's default behavior is sufficient. + +#### Core workflow agents + +These agents form the main plan → analyze → execute → review pipeline. + +| Agent | Purpose | Example trigger | Read-only? | +| --- | --- | --- | --- | +| `TechAIPlanner` | Produce implementation plans with risks, assumptions, and validation criteria. Does not touch files. | "Plan the migration of the payment service to a hexagonal architecture." | Yes | +| `TechAIPairArchitect` | Deep change-impact analysis: DDD, architecture, blind spots, risk matrix. Generates `ANALYSIS_REPORT.md`. | "Analyze all changes on this branch and generate the analysis report." | Yes (writes report only) | +| `TechAIPairArchitectAnalysisExecutor` | Re-evaluate the analysis report, challenge each finding, produce `EXECUTION_PLAN.md` with decision tables and lessons learned. | "Take the ANALYSIS_REPORT.md, verify every finding, and create the execution plan." | Yes (writes plan only) | +| `TechAIImplementer` | Execute changes end-to-end with safe, minimal, testable modifications. Follows plans from Planner or Executor. | "Execute work package WP-3 from the execution plan." | **No** — edits files | + +#### Review agents + +Three complementary levels of review — they do NOT overlap. + +| Agent | Purpose | Scope | Example trigger | When to use instead of the others | +| --- | --- | --- | --- | --- | +| `TechAIReviewer` | Structured code review: defects, regressions, maintainability. Diff-first, broad. | Any language, any change | "Review this PR for quality before merge." | **Default choice** for general PR review. Delegates to specialists when needed. | +| `TechAIScriptReviewer` | Exhaustive nit-level review with per-language anti-pattern catalogs + architecture assessment. | Python, Bash, Terraform only | "Deep review of the new sync script — catch every anti-pattern." | When you want **every possible finding** on scripts/infra code, including Nits and architecture verdict. | +| `TechAISecurityReviewer` | Security-focused review: secrets, permissions, attack surface, compliance. | Any change with security impact | "Security review of the new IAM module and workflow changes." | When the change touches **security-sensitive** code (IAM, secrets, auth, networking). | + +> **How they differ**: `TechAIReviewer` is the broad quality gate (like a senior engineer's PR review). `TechAIScriptReviewer` is the exhaustive deep-dive (like a specialized linter on steroids — only for Python/Bash/Terraform). `TechAISecurityReviewer` focuses exclusively on security concerns. Use `TechAIReviewer` first; it will recommend routing to a specialist when needed. + +#### Infrastructure specialist agents + +| Agent | Purpose | Example trigger | +| --- | --- | --- | +| `TechAITerraformGuardrails` | Review Terraform changes for guardrails, lifecycle safety, state hygiene, and drift detection. | "Check the Terraform changes in src/infra/ for policy compliance." | +| `TechAIIAMLeastPrivilege` | Analyze IAM and policy changes for least-privilege compliance across AWS, Azure, and GCP. | "Audit the new IAM role — is it least privilege?" | +| `TechAIWorkflowSupplyChain` | Review GitHub Actions workflows for supply-chain risk, SHA-pinning, and reusable CI/CD design. | "Check the new deploy workflow for supply chain risks." | + +#### PR agent + +| Agent | Purpose | Example trigger | +| --- | --- | --- | +| `TechAIPREditor` | Generate or update PR title and body using the repo template and real diff context. | "Write the PR description for this branch." | + +#### Copilot customization lifecycle agents (this repo only) + +These four agents manage the **lifecycle** of Copilot customization assets. They are repo-only (not synced to consumers) and each handles a distinct stage: + +| Agent | Lifecycle stage | Purpose | Example trigger | +| --- | --- | --- | --- | +| `TechAIStandardsRepoConfigBuilder` | **Create/Update** | Create and update Copilot config assets (instructions, prompts, skills, agents) inside this standards repo. Does NOT operate on consumer repos. | "Create a new prompt for Docker image scanning." | +| `TechAIStandardsRepoConfigAuditor` | **Validate** | Validate Copilot config changes inside this standards repo for portability, naming, sync safety, and validator compliance. Final quality gate before merge. | "Audit the new pair-architect-analysis-executor agent for compliance." | +| `TechAISyncGlobalCopilotConfigsIntoRepo` | **Propagate** | Push the shared Copilot baseline from this standards repo into a consumer repo (e.g. onemail, oneidentity) with conflict detection and SHA256 checksums. | "Sync the baseline config to the oneidentity repo." | +| `TechAIRepoCopilotExtender` | **Extend (consumer)** | Add repo-specific `internal-*` Copilot assets to a consumer repo, extending the shared baseline without duplicating it. Run Sync first. | "Add an internal prompt for email template generation in the onemail repo." | + +> **How they differ**: Builder creates in this repo → Auditor validates in this repo → Sync pushes baseline to consumer repos → Extender adds repo-specific assets in consumer repos. They form a pipeline, not overlapping alternatives. + +#### Overlap analysis + +| Potential confusion | Verdict | Distinction | +| --- | --- | --- | +| `TechAIPairArchitect` vs `TechAIReviewer` | **Different scope** | PairArchitect does cross-cutting architecture/DDD analysis of the full change set. Reviewer does per-file defect-focused PR review. Use PairArchitect for design-level assessment, Reviewer for merge readiness. | +| `TechAIReviewer` vs `TechAIScriptReviewer` | **Different depth** | Reviewer is broad and delegates to specialists. ScriptReviewer is exhaustive nit-level for Python/Bash/Terraform only. Use Reviewer first; use ScriptReviewer when you want zero findings missed. | +| `TechAIStandardsRepoConfigAuditor` vs `TechAIReviewer` | **Different domain** | Auditor validates Copilot customization assets (frontmatter, naming, sync safety). Reviewer validates application/infrastructure code. Never interchangeable. | +| `TechAICustomizationAuditor` vs `TechAIStandardsRepoConfigAuditor` | **Deprecated alias** | `TechAICustomizationAuditor` is a deprecated compatibility alias. Use `TechAIStandardsRepoConfigAuditor` for all new work. See [Deprecated assets](#deprecated-assets). | +| `TechAIPlanner` vs `TechAIPairArchitectAnalysisExecutor` | **Different input** | Planner works from requirements/user intent. Executor works from an existing `ANALYSIS_REPORT.md`. Planner is upstream (before code); Executor is downstream (after analysis). | + +### Scripts (`scripts/`) + +| Script | Purpose | Use when | Do NOT use when | +| --- | --- | --- | --- | +| `validate-copilot-customizations.sh` | Validates frontmatter, section structure, agent metadata, inventory consistency, and SHA-pinning across all customization assets. | After any change to `.github/` — run with `--scope root --mode strict`. | Validating application code (run linters instead). | +| `tech-ai-sync-copilot-configs.py` | Manifest-based conservative sync with conflict detection, SHA256 checksums, and reporting. Preferred tool for aligning consumer repos. | Propagating config updates to consumer repos — run with `--mode plan` first, then `--mode apply`. | This repo itself — it's the source, not a target. | +| `bootstrap-copilot-config.sh` | ⚠️ **Deprecated** — rsync-based simple copy. See `DEPRECATION.md`. | Only as a legacy fallback for consumers not yet migrated to the sync script. | New consumers — use `tech-ai-sync-copilot-configs.py` instead. | + +### Templates (`templates/`) + +| Template | Purpose | Use when | +| --- | --- | --- | +| `AGENTS.template.md` | Template for consumer repository `AGENTS.md`: naming policy, decision priority, agent routing, inventory sections. | Onboarding a new consumer repo or regenerating its `AGENTS.md`. | +| `copilot-quickstart.md` | Short onboarding guide: copy baseline, add stack assets, run validator. | First-time setup of Copilot customization in a consumer repo. | + +### Workflow (`workflows/`) + +| Workflow | Purpose | +| --- | --- | +| `github-validate-copilot-customizations.yml` | CI workflow that runs the validator on PRs touching `.github/` assets. | + +--- ## Maintenance workflow -1. Update files under `.github/`. -2. Run `.github/scripts/validate-copilot-customizations.sh --scope root --mode strict`. -3. Optional: generate a machine-readable summary with `.github/scripts/validate-copilot-customizations.sh --scope root --mode strict --report json --report-file /tmp/copilot-report.json`. -4. Prefer cross-repo alignment with `python .github/scripts/tech-ai-sync-copilot-configs.py --target --mode plan` before any apply step. -5. Use `.github/scripts/bootstrap-copilot-config.sh --target ` only as a legacy fallback bootstrap path (default excludes apply; see `.github/.bootstrap-ignore`). -6. Optionally run cross-repo assessment with `.github/scripts/validate-copilot-customizations.sh --scope all --mode legacy-compatible`. -7. Ensure workflow checks pass. -8. Update `.github/CHANGELOG.md` for notable changes. + +1. Edit files under `.github/`. +2. Run validation: `./scripts/validate-copilot-customizations.sh --scope root --mode strict`. +3. Optional JSON report: `./scripts/validate-copilot-customizations.sh --scope root --mode strict --report json --report-file /tmp/copilot-report.json`. +4. Cross-repo alignment: `python scripts/tech-ai-sync-copilot-configs.py --target --mode plan` → review → `--mode apply`. +5. Optional cross-repo assessment: `./scripts/validate-copilot-customizations.sh --scope all --mode legacy-compatible`. +6. Ensure CI workflow passes. +7. Update `CHANGELOG.md` for notable changes. + +--- ## Notes -- `repo-profiles.yml` is currently advisory (human-readable profile catalog). -- The canonical project `AGENTS.md` belongs in repository root, not under `.github/`. -- `TechAIGlobalCustomizationBuilder`, `TechAIGlobalCustomizationAuditor`, `TechAILocalCopilotCustomizationBuilder`, and `TechAISyncCopilotConfigs` are repo-only source agents and must not be synced to consumer repositories. -- `.github/README.md`, `.github/agents/README.md`, `.github/templates/**`, and `.github/scripts/bootstrap-copilot-config.sh` are source-only assets and should not be part of consumer baselines. -- Use `templates/copilot-quickstart.md` for a short onboarding flow. + +- `repo-profiles.yml` is advisory-only (human-readable profile catalog, not enforced by validators). +- The canonical project `AGENTS.md` belongs at repository root, not under `.github/`. +- **Repo-only agents** (not synced to consumers): `TechAIStandardsRepoConfigBuilder`, `TechAIStandardsRepoConfigAuditor`, `TechAIRepoCopilotExtender`, `TechAISyncGlobalCopilotConfigsIntoRepo`, `TechAIScriptReviewer`, `TechAICustomizationAuditor` (deprecated alias). +- **Source-only assets** (excluded from consumer baselines): `.github/README.md`, `agents/README.md`, `templates/**`, `scripts/bootstrap-copilot-config.sh`, `tech-ai-requirements-dev.txt`, `.bootstrap-ignore`. +- Use `templates/copilot-quickstart.md` for onboarding new consumer repos. + +--- + +## Deprecated assets + +| Asset | Deprecated in favor of | Status | Notes | +| --- | --- | --- | --- | +| `scripts/bootstrap-copilot-config.sh` | `scripts/tech-ai-sync-copilot-configs.py` | Deprecated — pending removal after migration window | See `DEPRECATION.md` for timeline. | +| `TechAICustomizationAuditor` agent | `TechAIStandardsRepoConfigAuditor` | Deprecated compatibility alias | Will be removed after 30-day window. | diff --git a/.github/agents/README.md b/.github/agents/README.md index 38554c9..3350ca2 100644 --- a/.github/agents/README.md +++ b/.github/agents/README.md @@ -11,17 +11,17 @@ This folder contains optional custom agents for focused tasks. ## Recommended routing - Read-only: `TechAIPlanner`, `TechAIReviewer`, `TechAISecurityReviewer`, `TechAIWorkflowSupplyChain`, `TechAITerraformGuardrails`, `TechAIIAMLeastPrivilege`. - Analysis-to-plan: `TechAIPairArchitectAnalysisExecutor` (takes `TechAIPairArchitect` output, re-evaluates, produces execution plan). -- PR-focused: `TechAIPRWriter`. +- PR-focused: `TechAIPREditor`. - Write-capable: `TechAIImplementer`. -- Repo-only standards specialists: `TechAIGlobalCustomizationBuilder`, `TechAIGlobalCustomizationAuditor`. -- Repo-only consumer-repository specialist: `TechAIInternalCopilotCustomizationBuilder`. +- Repo-only standards specialists: `TechAIStandardsRepoConfigBuilder`, `TechAIStandardsRepoConfigAuditor`. +- Repo-only consumer-repository specialist: `TechAIRepoCopilotExtender`. ## Repo-only agents (not synced to consumers) -- `TechAIGlobalCustomizationBuilder` -- `TechAIGlobalCustomizationAuditor` -- `TechAIInternalCopilotCustomizationBuilder` +- `TechAIStandardsRepoConfigBuilder` +- `TechAIStandardsRepoConfigAuditor` +- `TechAIRepoCopilotExtender` - `TechAIScriptReviewer` -- `TechAISyncCopilotConfigs` +- `TechAISyncGlobalCopilotConfigsIntoRepo` - `TechAICustomizationAuditor` (deprecated compatibility alias) ## Why generic core agents @@ -35,10 +35,10 @@ This folder contains optional custom agents for focused tasks. 3. Use `TechAIReviewer` for non-security quality gates. 4. Use `TechAITerraformGuardrails` and `TechAIIAMLeastPrivilege` on policy/infrastructure changes. 5. Use `TechAIWorkflowSupplyChain` on workflow changes. -6. Use `TechAIPRWriter` to create or update PR title/body from template and diff. +6. Use `TechAIPREditor` to create or update PR title/body from template and diff. 7. Use `TechAISecurityReviewer` as final security gate. -8. Use `TechAIGlobalCustomizationBuilder` for GitHub Copilot customization assets in this standards repository. -9. Use `TechAIGlobalCustomizationAuditor` as the final gate for those customization changes. -10. Use `TechAISyncCopilotConfigs` to align a consumer baseline before creating repo-owned internal assets. -11. Use `TechAIInternalCopilotCustomizationBuilder` for repo-owned `internal-*` prompts, skills, agents, and `AGENTS.md` updates that should stay consumer-repository. +8. Use `TechAIStandardsRepoConfigBuilder` for GitHub Copilot customization assets in this standards repository. +9. Use `TechAIStandardsRepoConfigAuditor` as the final gate for those customization changes. +10. Use `TechAISyncGlobalCopilotConfigsIntoRepo` to align a consumer baseline before creating repo-owned internal assets. +11. Use `TechAIRepoCopilotExtender` for repo-owned `internal-*` prompts, skills, agents, and `AGENTS.md` updates that should stay consumer-repository. 12. Use `TechAIPairArchitectAnalysisExecutor` after `TechAIPairArchitect` to re-evaluate findings, produce a validated execution plan with per-finding decision tables, extract lessons learned, and prepare work packages for `TechAIImplementer`. diff --git a/.github/agents/tech-ai-customization-auditor.agent.md b/.github/agents/tech-ai-customization-auditor.agent.md index e34447c..9209760 100644 --- a/.github/agents/tech-ai-customization-auditor.agent.md +++ b/.github/agents/tech-ai-customization-auditor.agent.md @@ -7,7 +7,7 @@ tools: ["search", "problems", "fetch"] # TechAI Customization Auditor Agent ## Status -Deprecated compatibility alias for `TechAIGlobalCustomizationAuditor`. Use the global auditor for new customization work in this repository. +Deprecated compatibility alias for `TechAIStandardsRepoConfigAuditor`. Use the global auditor for new customization work in this repository. ## Objective Keep this repository portable and coherent by checking that customization assets are generic, internally consistent, and validator-compliant. diff --git a/.github/agents/tech-ai-pair-architect-analysis-executor.agent.md b/.github/agents/tech-ai-pair-architect-analysis-executor.agent.md index e8e43d8..295bc0c 100644 --- a/.github/agents/tech-ai-pair-architect-analysis-executor.agent.md +++ b/.github/agents/tech-ai-pair-architect-analysis-executor.agent.md @@ -56,7 +56,7 @@ This agent produces the plan only — it does not execute. - Workflows → `TechAIWorkflowSupplyChain` - Security → `TechAISecurityReviewer` - Line-level review → `TechAIScriptReviewer` -- Copilot assets → `TechAIGlobalCustomizationBuilder` +- Copilot assets → `TechAIStandardsRepoConfigBuilder` ## Handoff diff --git a/.github/agents/tech-ai-github-pr-writer.agent.md b/.github/agents/tech-ai-pr-editor.agent.md similarity index 91% rename from .github/agents/tech-ai-github-pr-writer.agent.md rename to .github/agents/tech-ai-pr-editor.agent.md index a5a296a..9056a60 100644 --- a/.github/agents/tech-ai-github-pr-writer.agent.md +++ b/.github/agents/tech-ai-pr-editor.agent.md @@ -1,6 +1,6 @@ --- -description: Create or update pull request title/body using repository template and real diff context. -name: TechAIPRWriter +description: Generate or refine PR title and body from the repo PR template and the real diff. Produces structured, review-ready PR descriptions. +name: TechAIPREditor tools: ["search", "usages", "problems", "fetch", "githubRepo"] --- @@ -19,10 +19,10 @@ Produce and apply a complete PR title/body aligned with the repository template, ## Execution workflow 1. Resolve the PR template path in this order: - - `.github/pull_request_template.md` - `.github/PULL_REQUEST_TEMPLATE.md` - - `pull_request_template.md` + - `.github/pull_request_template.md` - `PULL_REQUEST_TEMPLATE.md` + - `pull_request_template.md` 2. Detect whether an open PR already exists for the branch. 3. If a PR exists, update title/body directly. 4. If no PR exists, create a draft PR first, then update title/body. diff --git a/.github/agents/tech-ai-internal-copilot-customization-builder.agent.md b/.github/agents/tech-ai-repo-copilot-extender.agent.md similarity index 84% rename from .github/agents/tech-ai-internal-copilot-customization-builder.agent.md rename to .github/agents/tech-ai-repo-copilot-extender.agent.md index 5e8e76b..c1066f1 100644 --- a/.github/agents/tech-ai-internal-copilot-customization-builder.agent.md +++ b/.github/agents/tech-ai-repo-copilot-extender.agent.md @@ -1,6 +1,6 @@ --- -description: Create or update repository-owned internal GitHub Copilot customization assets in a consumer repository without duplicating the shared baseline. -name: TechAIInternalCopilotCustomizationBuilder +description: Add repo-specific internal-* Copilot assets (prompts, skills, agents) to a consumer repo. Extends the shared baseline without duplicating it. Run TechAISyncGlobalCopilotConfigsIntoRepo first. +name: TechAIRepoCopilotExtender tools: ["search", "usages", "problems", "editFiles", "runTerminal", "fetch"] --- @@ -20,8 +20,8 @@ Create and refine consumer-repository Copilot customization assets that must rem ## Routing - Use this agent when a consumer repository needs repo-owned prompts, skills, agents, or `AGENTS.md` wiring that must stay internal. -- If the consumer baseline is missing or stale, start with `TechAISyncCopilotConfigs` in `plan` mode before creating new internal assets. -- Treat `.github/skills/tech-ai-internal-copilot-customization-builder/SKILL.md` as the workflow definition. +- If the consumer baseline is missing or stale, start with `TechAISyncGlobalCopilotConfigsIntoRepo` in `plan` mode before creating new internal assets. +- Treat `.github/skills/tech-ai-repo-copilot-extender/SKILL.md` as the workflow definition. ## Output Contract - `Baseline check`: whether the consumer already has the required synced Copilot core assets and validator coverage. diff --git a/.github/agents/tech-ai-global-customization-auditor.agent.md b/.github/agents/tech-ai-standards-repo-config-auditor.agent.md similarity index 88% rename from .github/agents/tech-ai-global-customization-auditor.agent.md rename to .github/agents/tech-ai-standards-repo-config-auditor.agent.md index 2820c8c..727d06c 100644 --- a/.github/agents/tech-ai-global-customization-auditor.agent.md +++ b/.github/agents/tech-ai-standards-repo-config-auditor.agent.md @@ -1,6 +1,6 @@ --- -description: Audit repo-only GitHub Copilot customization changes for this global standards repository with concise, severity-ordered findings. -name: TechAIGlobalCustomizationAuditor +description: Validate Copilot configuration changes inside this standards repo for portability, naming consistency, sync safety, and validator compliance. Final quality gate before merge. +name: TechAIStandardsRepoConfigAuditor tools: ["search", "problems", "fetch", "runTerminal"] --- @@ -45,4 +45,4 @@ Review GitHub Copilot customization changes in this global standards repository ## Handoff - If no findings remain, explicitly report `No issues found`. -- If findings exist, route `Critical` and `Major` findings back to `TechAIGlobalCustomizationBuilder` with the minimal corrective action. +- If findings exist, route `Critical` and `Major` findings back to `TechAIStandardsRepoConfigBuilder` with the minimal corrective action. diff --git a/.github/agents/tech-ai-global-customization-builder.agent.md b/.github/agents/tech-ai-standards-repo-config-builder.agent.md similarity index 93% rename from .github/agents/tech-ai-global-customization-builder.agent.md rename to .github/agents/tech-ai-standards-repo-config-builder.agent.md index 2bd0d0e..86be0a2 100644 --- a/.github/agents/tech-ai-global-customization-builder.agent.md +++ b/.github/agents/tech-ai-standards-repo-config-builder.agent.md @@ -1,6 +1,6 @@ --- -description: Build and normalize GitHub Copilot customization assets for this global standards repository with minimal token usage. -name: TechAIGlobalCustomizationBuilder +description: Create and update Copilot configuration assets (instructions, prompts, skills, agents) inside this standards repo (cloud-strategy.github). Does NOT operate on consumer repos. +name: TechAIStandardsRepoConfigBuilder tools: ["search", "usages", "problems", "editFiles", "runTerminal", "fetch"] --- @@ -62,4 +62,4 @@ Create and update GitHub Copilot customization assets for this global standards ## Handoff - Report changed files, conventions applied, validation results, residual risks, and the minimal rationale for any token-saving consolidation. -- Route the final review to `TechAIGlobalCustomizationAuditor`. +- Route the final review to `TechAIStandardsRepoConfigAuditor`. diff --git a/.github/agents/tech-ai-sync-copilot-configs.agent.md b/.github/agents/tech-ai-sync-global-copilot-configs-into-repo.agent.md similarity index 84% rename from .github/agents/tech-ai-sync-copilot-configs.agent.md rename to .github/agents/tech-ai-sync-global-copilot-configs-into-repo.agent.md index 5f877b9..40f6232 100644 --- a/.github/agents/tech-ai-sync-copilot-configs.agent.md +++ b/.github/agents/tech-ai-sync-global-copilot-configs-into-repo.agent.md @@ -1,6 +1,6 @@ --- -description: Analyze a local repository and conservatively align the minimum Copilot customization assets from this standards repository. -name: TechAISyncCopilotConfigs +description: Propagate the shared Copilot baseline from this standards repo into a consumer repo (e.g. onemail, oneidentity). Plans and applies minimum required assets with conflict detection. +name: TechAISyncGlobalCopilotConfigsIntoRepo tools: ["search", "fetch", "editFiles", "runTerminal", "problems"] --- @@ -17,7 +17,7 @@ Analyze a local target repository, select the minimum Copilot customization asse ## Routing - Use this agent only for cross-repository Copilot-core alignment work. -- Treat `.github/skills/tech-ai-sync-copilot-configs/SKILL.md` as the single workflow definition. +- Treat `.github/skills/tech-ai-sync-global-copilot-configs-into-repo/SKILL.md` as the single workflow definition. - Treat `.github/scripts/tech-ai-sync-copilot-configs.py` as the deterministic execution path. - Start with `plan` mode and move to `apply` only on explicit request and only when the plan is conflict-safe. diff --git a/.github/prompts/tech-ai-github-pr-description.prompt.md b/.github/prompts/tech-ai-pr-description.prompt.md similarity index 93% rename from .github/prompts/tech-ai-github-pr-description.prompt.md rename to .github/prompts/tech-ai-pr-description.prompt.md index 1716069..45067f7 100644 --- a/.github/prompts/tech-ai-github-pr-description.prompt.md +++ b/.github/prompts/tech-ai-pr-description.prompt.md @@ -1,14 +1,14 @@ --- -description: Build a complete pull request body using the existing repository PR template +description: Generate a structured PR description from the repo template and the current diff context name: TechAIPRDescription -agent: TechAIPRWriter +agent: TechAIPREditor argument-hint: title= intent= changed_files= [validation=] [risk=] [links=] [target_branch=] [pr_number=] --- # Pull Request Description Task ## Context -Create or update a pull request body using the repository template (`.github/pull_request_template.md` or `pull_request_template.md`), including a short list of key changes. +Create or update a pull request body using the repository template (`.github/PULL_REQUEST_TEMPLATE.md` or `PULL_REQUEST_TEMPLATE.md`), including a short list of key changes. ## Required inputs - **Title**: ${input:title} @@ -25,12 +25,12 @@ Create or update a pull request body using the repository template (`.github/pul - Do not add extra sections unless the template already includes them. ## Instructions -1. Use `.github/skills/tech-ai-pr-writing/SKILL.md`. +1. Use `.github/skills/tech-ai-pr-editor/SKILL.md`. 2. Resolve the template path in this order: - - `.github/pull_request_template.md` - `.github/PULL_REQUEST_TEMPLATE.md` - - `pull_request_template.md` + - `.github/pull_request_template.md` - `PULL_REQUEST_TEMPLATE.md` + - `pull_request_template.md` 3. Follow template section order and headings exactly as defined by the resolved template. 4. Answer every prompt/question line from the template explicitly with repository facts. 5. Preserve checklist items and mark each one intentionally (`[x]` or `[ ]`) based on real scope. diff --git a/.github/prompts/tech-ai-internal-copilot-customization-builder.prompt.md b/.github/prompts/tech-ai-repo-copilot-extender.prompt.md similarity index 85% rename from .github/prompts/tech-ai-internal-copilot-customization-builder.prompt.md rename to .github/prompts/tech-ai-repo-copilot-extender.prompt.md index c4c3196..c58ada2 100644 --- a/.github/prompts/tech-ai-internal-copilot-customization-builder.prompt.md +++ b/.github/prompts/tech-ai-repo-copilot-extender.prompt.md @@ -1,6 +1,6 @@ --- -description: Create or update repository-owned internal GitHub Copilot customization assets in a consumer repo while preserving the shared baseline -name: TechAIInternalCopilotCustomizationBuilder +description: Add repo-specific internal-* Copilot assets to a consumer repo extending the shared baseline without duplicating it +name: TechAIRepoCopilotExtender agent: agent argument-hint: target_repo= change= [internal_asset_type=] [promote_to_source=] --- @@ -17,8 +17,8 @@ Use this prompt to create or refine repository-owned `internal-*` Copilot assets - **Promote to source**: ${input:promote_to_source:no} ## Instructions -1. Use `.github/skills/tech-ai-internal-copilot-customization-builder/SKILL.md` as the workflow definition. -2. If the target baseline is missing or stale, run `TechAISyncCopilotConfigs` in `plan` mode first. +1. Use `.github/skills/tech-ai-repo-copilot-extender/SKILL.md` as the workflow definition. +2. If the target baseline is missing or stale, run `TechAISyncGlobalCopilotConfigsIntoRepo` in `plan` mode first. 3. Inspect one or more concrete target files that the internal asset will operate on, then derive schema, naming conventions, identity formats, examples, and validations from those files. 4. If no suitable target file exists, stop and report the missing grounding instead of inventing schema fields, examples, or naming rules. 5. Create only the narrowest internal asset set that solves the request. diff --git a/.github/prompts/tech-ai-sync-copilot-configs.prompt.md b/.github/prompts/tech-ai-sync-global-copilot-configs-into-repo.prompt.md similarity index 88% rename from .github/prompts/tech-ai-sync-copilot-configs.prompt.md rename to .github/prompts/tech-ai-sync-global-copilot-configs-into-repo.prompt.md index 95bd53a..0912af3 100644 --- a/.github/prompts/tech-ai-sync-copilot-configs.prompt.md +++ b/.github/prompts/tech-ai-sync-global-copilot-configs-into-repo.prompt.md @@ -1,6 +1,6 @@ --- -description: Analyze and conservatively align a local repository with the minimum Copilot customization assets from this standards repo -name: TechAISyncCopilotConfigs +description: Propagate the shared Copilot baseline from this standards repo into a target consumer repo with conflict detection and reporting +name: TechAISyncGlobalCopilotConfigsIntoRepo agent: agent argument-hint: target_repo= [source_repo=] [mode=] [report_format=] [report_file=] --- @@ -18,7 +18,7 @@ Use this prompt to analyze a local repository, select the minimum Copilot custom - **Report file**: ${input:report_file} ## Instructions -1. Use `.github/skills/tech-ai-sync-copilot-configs/SKILL.md` as the workflow definition. +1. Use `.github/skills/tech-ai-sync-global-copilot-configs-into-repo/SKILL.md` as the workflow definition. 2. Use `.github/scripts/tech-ai-sync-copilot-configs.py` for deterministic execution. 3. Start with `mode=plan`; use `mode=apply` only when explicitly requested and only after a conflict-safe plan. 4. Keep scope limited to Copilot core assets only. diff --git a/.github/scripts/tech-ai-sync-copilot-configs.py b/.github/scripts/tech-ai-sync-copilot-configs.py index 75ddda9..58a9076 100644 --- a/.github/scripts/tech-ai-sync-copilot-configs.py +++ b/.github/scripts/tech-ai-sync-copilot-configs.py @@ -21,7 +21,7 @@ from pathlib import Path -SCRIPT_NAME = "TechAISyncCopilotConfigs" +SCRIPT_NAME = "TechAISyncGlobalCopilotConfigsIntoRepo" MANIFEST_RELATIVE_PATH = ".github/tech-ai-sync-copilot-configs.manifest.json" SUPPORTED_SCOPE = "copilot-core" SUPPORTED_CONFLICT_POLICY = "conservative-merge" @@ -36,23 +36,23 @@ ) SOURCE_ONLY_AGENT_PATHS = { ".github/agents/tech-ai-customization-auditor.agent.md", - ".github/agents/tech-ai-global-customization-auditor.agent.md", - ".github/agents/tech-ai-global-customization-builder.agent.md", - ".github/agents/tech-ai-internal-copilot-customization-builder.agent.md", + ".github/agents/tech-ai-standards-repo-config-auditor.agent.md", + ".github/agents/tech-ai-standards-repo-config-builder.agent.md", + ".github/agents/tech-ai-repo-copilot-extender.agent.md", ".github/agents/tech-ai-script-reviewer.agent.md", - ".github/agents/tech-ai-sync-copilot-configs.agent.md", + ".github/agents/tech-ai-sync-global-copilot-configs-into-repo.agent.md", } SOURCE_ONLY_PROMPT_PATHS = { ".github/prompts/tech-ai-add-platform.prompt.md", ".github/prompts/tech-ai-add-report-script.prompt.md", ".github/prompts/tech-ai-code-review.prompt.md", - ".github/prompts/tech-ai-internal-copilot-customization-builder.prompt.md", - ".github/prompts/tech-ai-sync-copilot-configs.prompt.md", + ".github/prompts/tech-ai-repo-copilot-extender.prompt.md", + ".github/prompts/tech-ai-sync-global-copilot-configs-into-repo.prompt.md", } SOURCE_ONLY_SKILL_PATHS = { ".github/skills/tech-ai-code-review/SKILL.md", - ".github/skills/tech-ai-internal-copilot-customization-builder/SKILL.md", - ".github/skills/tech-ai-sync-copilot-configs/SKILL.md", + ".github/skills/tech-ai-repo-copilot-extender/SKILL.md", + ".github/skills/tech-ai-sync-global-copilot-configs-into-repo/SKILL.md", } CANONICAL_BASH_SCRIPT_PROMPT_PATH = ".github/prompts/tech-ai-bash-script.prompt.md" CANONICAL_PYTHON_SCRIPT_PROMPT_PATH = ".github/prompts/tech-ai-python-script.prompt.md" @@ -95,7 +95,7 @@ "tech-ai-add-report-script.prompt.md": "TechAIAddReportScript", "tech-ai-cicd-workflow.prompt.md": "TechAICICDWorkflow", "tech-ai-github-composite-action.prompt.md": "TechAICompositeAction", - "tech-ai-github-pr-description.prompt.md": "TechAIPRDescription", + "tech-ai-pr-description.prompt.md": "TechAIPRDescription", "tech-ai-terraform-module.prompt.md": "TechAITerraformModule", } VALIDATION_WORKFLOW_RELATIVE_PATH = ".github/workflows/github-validate-copilot-customizations.yml" @@ -1194,7 +1194,7 @@ def select_assets(source_root: Path, analysis: TargetAnalysis, profiles: dict[st if repo_needs_data_registry(analysis.repo_root, analysis): prompts.add(".github/prompts/tech-ai-data-registry.prompt.md") if target_has_pr_template(analysis.repo_root): - prompts.add(".github/prompts/tech-ai-github-pr-description.prompt.md") + prompts.add(".github/prompts/tech-ai-pr-description.prompt.md") prompts = { prompt @@ -1226,7 +1226,7 @@ def select_assets(source_root: Path, analysis: TargetAnalysis, profiles: dict[st if repo_needs_iam_review(analysis.repo_root): agents.add(".github/agents/tech-ai-iam-least-privilege.agent.md") if target_has_pr_template(analysis.repo_root): - agents.add(".github/agents/tech-ai-github-pr-writer.agent.md") + agents.add(".github/agents/tech-ai-pr-editor.agent.md") agents = {agent for agent in agents if agent not in SOURCE_ONLY_AGENT_PATHS and (source_root / agent).is_file()} @@ -1932,8 +1932,8 @@ def agent_routing_lines(agent_paths: list[str]) -> list[str]: lines.append("- Use `TechAIWorkflowSupplyChain` for workflow supply-chain hardening and CI checks.") if "tech-ai-security-reviewer.agent.md" in agent_names: lines.append("- Use `TechAISecurityReviewer` as the security-focused review gate.") - if "tech-ai-github-pr-writer.agent.md" in agent_names: - lines.append("- Use `TechAIPRWriter` when generating pull request content from the repository template.") + if "tech-ai-pr-editor.agent.md" in agent_names: + lines.append("- Use `TechAIPREditor` when generating pull request content from the repository template.") return lines @@ -2108,7 +2108,7 @@ def apply_plan(target_root: Path, plan: SyncPlan, planned_files: list[PlannedFil def render_markdown_report(plan: SyncPlan) -> str: lines = [ - "# TechAISyncCopilotConfigs Report", + "# TechAISyncGlobalCopilotConfigsIntoRepo Report", "", "## Target analysis summary", f"- Source repo: `{plan.selection.profile.name}` profile from the current standards repository", diff --git a/.github/scripts/validate-copilot-customizations.sh b/.github/scripts/validate-copilot-customizations.sh index aaf4dc2..33f40b6 100755 --- a/.github/scripts/validate-copilot-customizations.sh +++ b/.github/scripts/validate-copilot-customizations.sh @@ -306,7 +306,7 @@ prompt_expected_name() { tech-ai-github-composite-action.prompt.md) printf '%s' "TechAICompositeAction" ;; - tech-ai-github-pr-description.prompt.md) + tech-ai-pr-description.prompt.md) printf '%s' "TechAIPRDescription" ;; tech-ai-add-platform.prompt.md) @@ -773,7 +773,7 @@ validate_agents_dir() { record_issue "$semantic_severity" "Reviewer agent should reference code review instructions: ${file}" fi ;; - tech-ai-global-customization-builder.agent.md) + tech-ai-standards-repo-config-builder.agent.md) if ! has_heading_exact "$file" '## Source of truth'; then record_issue "$semantic_severity" "Global customization builder missing '## Source of truth' section: ${file}" fi @@ -801,11 +801,11 @@ validate_agents_dir() { if ! grep -Fq 'scripts/validate-copilot-customizations.sh' "$file"; then record_issue "$semantic_severity" "Global customization builder should reference customization validator: ${file}" fi - if ! grep -Fq 'TechAIGlobalCustomizationAuditor' "$file"; then - record_issue "$semantic_severity" "Global customization builder should hand off to TechAIGlobalCustomizationAuditor: ${file}" + if ! grep -Fq 'TechAIStandardsRepoConfigAuditor' "$file"; then + record_issue "$semantic_severity" "Global customization builder should hand off to TechAIStandardsRepoConfigAuditor: ${file}" fi ;; - tech-ai-global-customization-auditor.agent.md) + tech-ai-standards-repo-config-auditor.agent.md) if ! has_heading_exact "$file" '## Audit protocol'; then record_issue "$semantic_severity" "Global customization auditor missing '## Audit protocol' section: ${file}" fi @@ -821,8 +821,8 @@ validate_agents_dir() { if ! grep -Fq 'scripts/validate-copilot-customizations.sh' "$file"; then record_issue "$semantic_severity" "Global customization auditor should reference customization validator: ${file}" fi - if ! grep -Fq 'TechAIGlobalCustomizationBuilder' "$file"; then - record_issue "$semantic_severity" "Global customization auditor should route major findings to TechAIGlobalCustomizationBuilder: ${file}" + if ! grep -Fq 'TechAIStandardsRepoConfigBuilder' "$file"; then + record_issue "$semantic_severity" "Global customization auditor should route major findings to TechAIStandardsRepoConfigBuilder: ${file}" fi ;; esac @@ -1063,18 +1063,25 @@ validate_workflow_permissions() { validate_pr_template_consistency() { local github_dir="$1" - local lower_template="${github_dir}/pull_request_template.md" - local upper_template="${github_dir}/PULL_REQUEST_TEMPLATE.md" + local lower_template + local upper_template local severity="error" [[ "$MODE" == "legacy-compatible" ]] && severity="warn" - if [[ ! -f "$lower_template" && ! -f "$upper_template" ]]; then - record_issue "$severity" "Missing PR template in ${github_dir} (expected pull_request_template.md or PULL_REQUEST_TEMPLATE.md)" + lower_template="$(find "$github_dir" -maxdepth 1 -type f -name 'pull_request_template.md' -print -quit)" + upper_template="$(find "$github_dir" -maxdepth 1 -type f -name 'PULL_REQUEST_TEMPLATE.md' -print -quit)" + + if [[ -z "$lower_template" && -z "$upper_template" ]]; then + record_issue "$severity" "Missing PR template in ${github_dir} (expected PULL_REQUEST_TEMPLATE.md)" return 0 fi - if [[ -f "$lower_template" && -f "$upper_template" ]] && ! cmp -s "$lower_template" "$upper_template"; then + if [[ -n "$lower_template" ]]; then + record_issue "$severity" "PR template filename must be uppercase in ${github_dir}: rename pull_request_template.md to PULL_REQUEST_TEMPLATE.md" + fi + + if [[ -n "$lower_template" && -n "$upper_template" ]] && ! cmp -s "$lower_template" "$upper_template"; then record_issue "$severity" "PR template files diverge in ${github_dir}: pull_request_template.md vs PULL_REQUEST_TEMPLATE.md" fi diff --git a/.github/skills/tech-ai-pr-writing/SKILL.md b/.github/skills/tech-ai-pr-editor/SKILL.md similarity index 92% rename from .github/skills/tech-ai-pr-writing/SKILL.md rename to .github/skills/tech-ai-pr-editor/SKILL.md index 56ca6ff..5dda027 100644 --- a/.github/skills/tech-ai-pr-writing/SKILL.md +++ b/.github/skills/tech-ai-pr-editor/SKILL.md @@ -1,9 +1,9 @@ --- -name: TechAIPRWriting -description: Produce concise, complete pull request descriptions aligned with the repository PR template. +name: TechAIPREditor +description: PR description templates, section structure, and diff-to-description mapping patterns for generating review-ready PR bodies. --- -# PR Writing Skill +# TechAI PR Editor — Skill ## When to use - Create a new pull request description. @@ -22,10 +22,10 @@ description: Produce concise, complete pull request descriptions aligned with th ## Template alignment - Resolve and use one existing repository template path: - - `.github/pull_request_template.md` - `.github/PULL_REQUEST_TEMPLATE.md` - - `pull_request_template.md` + - `.github/pull_request_template.md` - `PULL_REQUEST_TEMPLATE.md` + - `pull_request_template.md` - Keep headings and section order unchanged. - If a section is not applicable, write `N/A`. - Avoid leaving placeholders empty. diff --git a/.github/skills/tech-ai-internal-copilot-customization-builder/SKILL.md b/.github/skills/tech-ai-repo-copilot-extender/SKILL.md similarity index 87% rename from .github/skills/tech-ai-internal-copilot-customization-builder/SKILL.md rename to .github/skills/tech-ai-repo-copilot-extender/SKILL.md index f336c29..32d9f11 100644 --- a/.github/skills/tech-ai-internal-copilot-customization-builder/SKILL.md +++ b/.github/skills/tech-ai-repo-copilot-extender/SKILL.md @@ -1,9 +1,9 @@ --- -name: TechAIInternalCopilotCustomizationBuilder -description: Create or update repository-owned internal GitHub Copilot customization assets in a consumer repository while preserving the shared synced baseline. +name: TechAIRepoCopilotExtender +description: Generation patterns for repo-specific internal-* Copilot assets in consumer repos — naming rules, baseline preservation, and AGENTS.md integration. --- -# TechAI Internal Copilot Customization Builder Skill +# TechAI Repo Copilot Extender — Skill ## When to use - Create or update repository-owned `internal-*` prompts, skills, agents, or `AGENTS.md` wiring in a consumer repo. @@ -14,7 +14,7 @@ description: Create or update repository-owned internal GitHub Copilot customiza 1. Inspect the target repository layout, `.github` contents, root `AGENTS.md`, git state, and existing internal Copilot assets. 2. Identify at least one representative target file for each requested internal capability and extract the actual schema field names, naming patterns, identity formats, and validation commands from those files before drafting any `internal-*` asset. 3. Confirm the baseline is current enough for internal customization work: - - if `copilot-instructions.md`, the validator script, or expected synced assets are missing or stale, run `TechAISyncCopilotConfigs` in `plan` mode first; + - if `copilot-instructions.md`, the validator script, or expected synced assets are missing or stale, run `TechAISyncGlobalCopilotConfigsIntoRepo` in `plan` mode first; - use the sync report to avoid creating an `internal-*` asset that duplicates an available shared baseline capability. 4. Decide the narrowest asset type that solves the request: - create or update an `internal-*.prompt.md` when the behavior is mostly task instructions; @@ -48,10 +48,10 @@ description: Create or update repository-owned internal GitHub Copilot customiza - Manage consumer-repository Copilot assets only. - Keep source-repository assets and shared baseline definitions unchanged unless promotion is explicitly requested. - Prefer one internal capability per repo-specific workflow; consolidate or deprecate duplicates instead of multiplying near-identical internal prompts. -- Do not create internal copies of source-only repo agents such as `TechAIGlobalCustomizationBuilder`, `TechAIGlobalCustomizationAuditor`, or `TechAISyncCopilotConfigs`. +- Do not create internal copies of source-only repo agents such as `TechAIStandardsRepoConfigBuilder`, `TechAIStandardsRepoConfigAuditor`, or `TechAISyncGlobalCopilotConfigsIntoRepo`. ## Validation - Run `bash .github/scripts/validate-copilot-customizations.sh --scope root --mode strict` in the target repo after internal customization changes. - Run `bash -n` and `shellcheck -s bash` for changed Bash files when available. - Run `python -m compileall ` and relevant `pytest` checks for changed Python files. -- Re-run `TechAISyncCopilotConfigs` in `plan` mode when you need to confirm that the new internal assets remain clearly separated from the managed shared baseline. +- Re-run `TechAISyncGlobalCopilotConfigsIntoRepo` in `plan` mode when you need to confirm that the new internal assets remain clearly separated from the managed shared baseline. diff --git a/.github/skills/tech-ai-sync-copilot-configs/SKILL.md b/.github/skills/tech-ai-sync-global-copilot-configs-into-repo/SKILL.md similarity index 88% rename from .github/skills/tech-ai-sync-copilot-configs/SKILL.md rename to .github/skills/tech-ai-sync-global-copilot-configs-into-repo/SKILL.md index c4c6ac5..fe74958 100644 --- a/.github/skills/tech-ai-sync-copilot-configs/SKILL.md +++ b/.github/skills/tech-ai-sync-global-copilot-configs-into-repo/SKILL.md @@ -1,12 +1,12 @@ --- -name: TechAISyncCopilotConfigs -description: Analyze a local repository, select the minimum Copilot customization assets, tailor them, and align them conservatively with a final report. +name: TechAISyncGlobalCopilotConfigsIntoRepo +description: Manifest-based sync logic for propagating the shared Copilot baseline into consumer repos — asset selection, SHA256 checksums, conflict detection, and reporting. --- -# TechAI Sync Copilot Configs Skill +# TechAI Sync Global Copilot Configs Into Repo — Skill ## When to use -- Create or update the `TechAISyncCopilotConfigs` alignment workflow. +- Create or update the `TechAISyncGlobalCopilotConfigsIntoRepo` alignment workflow. - Align a local target repository with portable Copilot customization assets from this standards repository. - Produce deterministic dry-run or apply reports for Copilot-core alignment only. @@ -45,5 +45,5 @@ description: Analyze a local repository, select the minimum Copilot customizatio ## Validation - Run `python -m compileall .github/scripts tests`. -- Run `pytest` for the `TechAISyncCopilotConfigs` test suite. +- Run `pytest` for the `TechAISyncGlobalCopilotConfigsIntoRepo` test suite. - Run `bash .github/scripts/validate-copilot-customizations.sh --scope root --mode strict`. diff --git a/AGENTS.md b/AGENTS.md index c37b6df..ad57c23 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,25 +35,25 @@ This file is for GitHub Copilot and AI assistants working in this repository. - Use `TechAIScriptReviewer` for exhaustive, nit-level reviews on Python, Bash, and Terraform. - Use `TechAIPairArchitect` for deep change-impact analysis with DDD focus, blind-spot detection, and structured Markdown report generation. - Use `TechAIPairArchitectAnalysisExecutor` after `TechAIPairArchitect` when the user wants a validated execution plan from `ANALYSIS_REPORT.md` before implementation. -- Use `TechAIGlobalCustomizationBuilder` as the default specialist for creating or updating GitHub Copilot customization assets in this repository. -- Use `TechAIGlobalCustomizationAuditor` as the final quality gate for GitHub Copilot customization changes in this repository. +- Use `TechAIStandardsRepoConfigBuilder` as the default specialist for creating or updating GitHub Copilot customization assets in this repository. +- Use `TechAIStandardsRepoConfigAuditor` as the final quality gate for GitHub Copilot customization changes in this repository. - Use `TechAICustomizationAuditor` only as a deprecated compatibility alias while older references are migrated. -- Use `TechAISyncCopilotConfigs` for cross-repository Copilot-core alignment and source or target redundancy audits. -- Use `TechAIInternalCopilotCustomizationBuilder` when a consumer repository needs repo-owned `internal-*` prompts, skills, agents, or `AGENTS.md` wiring that should remain internal instead of entering the shared baseline. -- Use specialist agents (`TechAIWorkflowSupplyChain`, `TechAISecurityReviewer`, `TechAITerraformGuardrails`, `TechAIIAMLeastPrivilege`, `TechAIPRWriter`) only when their domain matches the task. -- The `TechAIGlobalCustomizationBuilder`, `TechAIGlobalCustomizationAuditor`, and `TechAIInternalCopilotCustomizationBuilder` agents are repo-only and must not be synced to consumer repositories. +- Use `TechAISyncGlobalCopilotConfigsIntoRepo` for cross-repository Copilot-core alignment and source or target redundancy audits. +- Use `TechAIRepoCopilotExtender` when a consumer repository needs repo-owned `internal-*` prompts, skills, agents, or `AGENTS.md` wiring that should remain internal instead of entering the shared baseline. +- Use specialist agents (`TechAIWorkflowSupplyChain`, `TechAISecurityReviewer`, `TechAITerraformGuardrails`, `TechAIIAMLeastPrivilege`, `TechAIPREditor`) only when their domain matches the task. +- The `TechAIStandardsRepoConfigBuilder`, `TechAIStandardsRepoConfigAuditor`, and `TechAIRepoCopilotExtender` agents are repo-only and must not be synced to consumer repositories. ### Anti-patterns - Do not use `TechAIPlanner` for trivial single-file changes with clear requirements; go directly to `TechAIImplementer`. - Do not use `TechAIImplementer` when requirements are ambiguous or scope is unclear; use `TechAIPlanner` first. -- Do not use `TechAIImplementer` as the primary authoring agent for GitHub Copilot customization assets in this repository; use `TechAIGlobalCustomizationBuilder`. +- Do not use `TechAIImplementer` as the primary authoring agent for GitHub Copilot customization assets in this repository; use `TechAIStandardsRepoConfigBuilder`. - Do not use generic `TechAIReviewer` when the change is purely Terraform, IAM, workflows, or security; use the matching specialist instead. - Do not use generic `TechAIReviewer` when you need exhaustive per-language nit-level review; use `TechAIScriptReviewer` instead. -- Do not use `TechAICustomizationAuditor` for new work; use `TechAIGlobalCustomizationAuditor`. -- Do not use `TechAIImplementer` alone when the task is cross-repository Copilot configuration alignment; use `TechAISyncCopilotConfigs`. -- Do not use `TechAISyncCopilotConfigs` alone when the task is to author new repository-owned `internal-*` assets in a consumer repository; use `TechAIInternalCopilotCustomizationBuilder` after baseline alignment. -- Do not use `TechAIInternalCopilotCustomizationBuilder` to add new shared `tech-ai-*` assets in this standards repository; use `TechAIGlobalCustomizationBuilder`. +- Do not use `TechAICustomizationAuditor` for new work; use `TechAIStandardsRepoConfigAuditor`. +- Do not use `TechAIImplementer` alone when the task is cross-repository Copilot configuration alignment; use `TechAISyncGlobalCopilotConfigsIntoRepo`. +- Do not use `TechAISyncGlobalCopilotConfigsIntoRepo` alone when the task is to author new repository-owned `internal-*` assets in a consumer repository; use `TechAIRepoCopilotExtender` after baseline alignment. +- Do not use `TechAIRepoCopilotExtender` to add new shared `tech-ai-*` assets in this standards repository; use `TechAIStandardsRepoConfigBuilder`. - Do not use `TechAIPairArchitect` for quick line-level nit reviews; use `TechAIScriptReviewer` or `TechAICodeReview` instead. - Do not use `TechAIReviewer` when you need holistic change-set impact analysis with DDD, architecture, and blind spots; use `TechAIPairArchitect`. - Do not use `TechAIPairArchitect` for exhaustive per-language anti-pattern scanning; use `TechAIScriptReviewer` and then `TechAIPairArchitect` for the bigger picture. @@ -63,13 +63,13 @@ This file is for GitHub Copilot and AI assistants working in this repository. - For changes spanning multiple specialist domains, run each relevant specialist and aggregate findings. - The standard chain for non-trivial work is `TechAIPlanner` -> `TechAIImplementer` -> `TechAIReviewer` or a matching specialist. -- For GitHub Copilot customization changes in this repository, use `TechAIGlobalCustomizationBuilder` first and `TechAIGlobalCustomizationAuditor` before final handoff. -- For consumer-repository Copilot customization work, use `TechAISyncCopilotConfigs` first if the target baseline is unknown, then use `TechAIInternalCopilotCustomizationBuilder` for repo-owned `internal-*` assets. +- For GitHub Copilot customization changes in this repository, use `TechAIStandardsRepoConfigBuilder` first and `TechAIStandardsRepoConfigAuditor` before final handoff. +- For consumer-repository Copilot customization work, use `TechAISyncGlobalCopilotConfigsIntoRepo` first if the target baseline is unknown, then use `TechAIRepoCopilotExtender` for repo-owned `internal-*` assets. - `TechAIPlanner` output is input context for `TechAIImplementer`. - `TechAIImplementer` output is input context for `TechAIReviewer`. - `TechAIReviewer` findings flagged as `Critical` or `Major` route back to `TechAIImplementer` for remediation. -- `TechAIGlobalCustomizationBuilder` output is input context for `TechAIGlobalCustomizationAuditor`. -- `TechAIGlobalCustomizationAuditor` findings flagged as `Critical` or `Major` route back to `TechAIGlobalCustomizationBuilder` for remediation. +- `TechAIStandardsRepoConfigBuilder` output is input context for `TechAIStandardsRepoConfigAuditor`. +- `TechAIStandardsRepoConfigAuditor` findings flagged as `Critical` or `Major` route back to `TechAIStandardsRepoConfigBuilder` for remediation. - `TechAIPairArchitect` output (`ANALYSIS_REPORT.md`) is input context for `TechAIPairArchitectAnalysisExecutor` when a validated execution plan is needed. - `TechAIPairArchitectAnalysisExecutor` output (`EXECUTION_PLAN.md`) is input context for `TechAIImplementer` after the user approves execution. - For thorough pre-merge validation, the recommended chain is `TechAIImplementer` -> `TechAIPairArchitect` -> `TechAIPairArchitectAnalysisExecutor` -> `TechAIImplementer`. @@ -140,8 +140,8 @@ This file is for GitHub Copilot and AI assistants working in this repository. - `TechAICodeReview`: exhaustive, nit-level code review. - `TechAIGitHubAction`: GitHub Actions workflow authoring. -- `TechAIInternalCopilotCustomizationBuilder`: consumer-repository `internal-*` customization authoring. -- `TechAISyncCopilotConfigs`: cross-repository alignment and redundancy analysis. +- `TechAIRepoCopilotExtender`: consumer-repository `internal-*` customization authoring. +- `TechAISyncGlobalCopilotConfigsIntoRepo`: cross-repository alignment and redundancy analysis. - `TechAIPRDescription`: pull request body generation. - `TechAIAddUnitTests`: test authoring and improvement. - `TechAITerraform`: Terraform feature or module authoring. @@ -151,9 +151,9 @@ This file is for GitHub Copilot and AI assistants working in this repository. - `TechAICodeReview`: strict review workflow and anti-pattern catalog. - `TechAICICDWorkflow`: CI or CD workflow design patterns. -- `TechAIInternalCopilotCustomizationBuilder`: consumer-repository Copilot customization workflow. -- `TechAISyncCopilotConfigs`: deterministic sync planning and reporting. -- `TechAIPRWriting`: PR writing conventions aligned to the repository template. +- `TechAIRepoCopilotExtender`: consumer-repository Copilot customization workflow. +- `TechAISyncGlobalCopilotConfigsIntoRepo`: deterministic sync planning and reporting. +- `TechAIPREditor`: PR description templates and diff-to-description mapping patterns. - `TechAICloudPolicy`: reusable cloud policy authoring patterns. - `TechAITerraformModule`: reusable Terraform module design. - `TechAIPairArchitect`: change-set-level impact, DDD smell catalog, health scoring, risk matrix, and blind-spot detection. @@ -197,13 +197,13 @@ This file is for GitHub Copilot and AI assistants working in this repository. - `.github/prompts/tech-ai-data-registry.prompt.md` - `.github/prompts/tech-ai-github-action.prompt.md` - `.github/prompts/tech-ai-github-composite-action.prompt.md` -- `.github/prompts/tech-ai-github-pr-description.prompt.md` +- `.github/prompts/tech-ai-pr-description.prompt.md` - `.github/prompts/tech-ai-java.prompt.md` -- `.github/prompts/tech-ai-internal-copilot-customization-builder.prompt.md` +- `.github/prompts/tech-ai-repo-copilot-extender.prompt.md` - `.github/prompts/tech-ai-nodejs.prompt.md` - `.github/prompts/tech-ai-python-script.prompt.md` - `.github/prompts/tech-ai-python.prompt.md` -- `.github/prompts/tech-ai-sync-copilot-configs.prompt.md` +- `.github/prompts/tech-ai-sync-global-copilot-configs-into-repo.prompt.md` - `.github/prompts/tech-ai-terraform-module.prompt.md` - `.github/prompts/tech-ai-terraform.prompt.md` @@ -216,14 +216,14 @@ This file is for GitHub Copilot and AI assistants working in this repository. - `.github/skills/tech-ai-code-review/SKILL.md` - `.github/skills/tech-ai-composite-action/SKILL.md` - `.github/skills/tech-ai-data-registry/SKILL.md` -- `.github/skills/tech-ai-internal-copilot-customization-builder/SKILL.md` -- `.github/skills/tech-ai-pr-writing/SKILL.md` +- `.github/skills/tech-ai-repo-copilot-extender/SKILL.md` +- `.github/skills/tech-ai-pr-editor/SKILL.md` - `.github/skills/tech-ai-project-java/SKILL.md` - `.github/skills/tech-ai-project-nodejs/SKILL.md` - `.github/skills/tech-ai-project-python/SKILL.md` - `.github/skills/tech-ai-script-bash/SKILL.md` - `.github/skills/tech-ai-script-python/SKILL.md` -- `.github/skills/tech-ai-sync-copilot-configs/SKILL.md` +- `.github/skills/tech-ai-sync-global-copilot-configs-into-repo/SKILL.md` - `.github/skills/tech-ai-terraform-feature/SKILL.md` - `.github/skills/tech-ai-terraform-module/SKILL.md` @@ -232,16 +232,16 @@ This file is for GitHub Copilot and AI assistants working in this repository. - `.github/agents/tech-ai-pair-architect-analysis-executor.agent.md` - `.github/agents/tech-ai-pair-architect.agent.md` - `.github/agents/tech-ai-customization-auditor.agent.md` -- `.github/agents/tech-ai-github-pr-writer.agent.md` +- `.github/agents/tech-ai-pr-editor.agent.md` - `.github/agents/tech-ai-github-workflow-supply-chain.agent.md` -- `.github/agents/tech-ai-global-customization-auditor.agent.md` -- `.github/agents/tech-ai-global-customization-builder.agent.md` -- `.github/agents/tech-ai-internal-copilot-customization-builder.agent.md` +- `.github/agents/tech-ai-standards-repo-config-auditor.agent.md` +- `.github/agents/tech-ai-standards-repo-config-builder.agent.md` +- `.github/agents/tech-ai-repo-copilot-extender.agent.md` - `.github/agents/tech-ai-iam-least-privilege.agent.md` - `.github/agents/tech-ai-implementer.agent.md` - `.github/agents/tech-ai-planner.agent.md` - `.github/agents/tech-ai-reviewer.agent.md` - `.github/agents/tech-ai-script-reviewer.agent.md` - `.github/agents/tech-ai-security-reviewer.agent.md` -- `.github/agents/tech-ai-sync-copilot-configs.agent.md` +- `.github/agents/tech-ai-sync-global-copilot-configs-into-repo.agent.md` - `.github/agents/tech-ai-terraform-guardrails.agent.md` diff --git a/ANALYSIS_REPORT.md b/ANALYSIS_REPORT.md index 540bc1a..e3ae297 100644 --- a/ANALYSIS_REPORT.md +++ b/ANALYSIS_REPORT.md @@ -526,7 +526,7 @@ The changelog has entries dated in 2026 (e.g., `2026-02-07`, `2026-02-28`, `2026 | `.github/scripts/tech-ai-sync-copilot-configs.py` | Well-architected sync tool (~900 lines) | | `AGENTS.md` | Comprehensive agent routing and decision priority | | `.github/skills/code-review/SKILL.md` | Excellent anti-pattern catalogs | -| `.github/skills/tech-ai-sync-copilot-configs/SKILL.md` | Thorough implementation reference | +| `.github/skills/tech-ai-sync-global-copilot-configs-into-repo/SKILL.md` | Thorough implementation reference | --- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6edab8d..93043bf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -23,8 +23,8 @@ This repository is the source baseline for reusable GitHub Copilot customization - Run any additional stack-specific validation relevant to the touched assets. ## Review flow -- Author customization changes with `TechAIGlobalCustomizationBuilder`. -- Review them with `TechAIGlobalCustomizationAuditor`. +- Author customization changes with `TechAIStandardsRepoConfigBuilder`. +- Review them with `TechAIStandardsRepoConfigAuditor`. - Record notable lifecycle or behavior changes in `.github/CHANGELOG.md`. ## Release and sync metadata diff --git a/COPILOT_REVIEW.md b/COPILOT_REVIEW.md index d936f12..c567654 100644 --- a/COPILOT_REVIEW.md +++ b/COPILOT_REVIEW.md @@ -91,7 +91,7 @@ This is a standards repository that other teams consume. Without contribution gu - How to add a new agent (naming, tools, restrictions) - Naming conventions (`tech-ai-*` for canonical, `local-*` for consumer-local, `TechAIGlobal*` for repo-only) - Required validation before PR (`validate-copilot-customizations.sh`, `pytest`, `shellcheck`) -- Review process (use `TechAIGlobalCustomizationBuilder` → `TechAIGlobalCustomizationAuditor`) +- Review process (use `TechAIStandardsRepoConfigBuilder` → `TechAIStandardsRepoConfigAuditor`) --- @@ -252,15 +252,15 @@ The ANALYSIS_REPORT (item 4.4) flagged inconsistent input variable naming. Promp **File**: `.github/agents/README.md` -The agents README lists routing for all agents including repo-only ones (`TechAIGlobalCustomizationBuilder`, `TechAIGlobalCustomizationAuditor`), but does not explicitly mark them as non-syncable. This information is in `AGENTS.md` but should also be in the agents README for clarity. +The agents README lists routing for all agents including repo-only ones (`TechAIStandardsRepoConfigBuilder`, `TechAIStandardsRepoConfigAuditor`), but does not explicitly mark them as non-syncable. This information is in `AGENTS.md` but should also be in the agents README for clarity. **Fix**: Add a note to the README: ```markdown ## Repo-only agents (not synced to consumers) -- `TechAIGlobalCustomizationBuilder` -- `TechAIGlobalCustomizationAuditor` +- `TechAIStandardsRepoConfigBuilder` +- `TechAIStandardsRepoConfigAuditor` - `TechAIScriptReviewer` -- `TechAISyncCopilotConfigs` +- `TechAISyncGlobalCopilotConfigsIntoRepo` - `TechAICustomizationAuditor` (deprecated alias) ``` @@ -375,7 +375,7 @@ Each preferred prompt/skill includes a one-line description. These descriptions ### Preferred prompts - `TechAICodeReview` - `TechAIGitHubAction` -- `TechAISyncCopilotConfigs` +- `TechAISyncGlobalCopilotConfigsIntoRepo` - `TechAIPRDescription` - `TechAIAddUnitTests` - `TechAITerraform` @@ -485,7 +485,7 @@ Seven "Do not use X when..." bullets are excellent guidance but could be more to **Fix**: In `AGENTS.md` inventory, annotate: ```markdown -- `.github/agents/tech-ai-customization-auditor.agent.md` *(deprecated — use TechAIGlobalCustomizationAuditor)* +- `.github/agents/tech-ai-customization-auditor.agent.md` *(deprecated — use TechAIStandardsRepoConfigAuditor)* ``` --- diff --git a/tests/test_tech_ai_sync_copilot_configs.py b/tests/test_tech_ai_sync_copilot_configs.py index fe71cac..7c9dd25 100644 --- a/tests/test_tech_ai_sync_copilot_configs.py +++ b/tests/test_tech_ai_sync_copilot_configs.py @@ -109,11 +109,11 @@ def build_source_audit_fixture(path: Path) -> None: "3. Report redundant aliases before rendering AGENTS inventory.", ] write_file( - path / ".github" / "agents" / "tech-ai-sync-copilot-configs.agent.md", + path / ".github" / "agents" / "tech-ai-sync-global-copilot-configs-into-repo.agent.md", "\n".join( [ "---", - "name: TechAISyncCopilotConfigs", + "name: TechAISyncGlobalCopilotConfigsIntoRepo", "description: sync agent", 'tools: ["search"]', "---", @@ -127,11 +127,11 @@ def build_source_audit_fixture(path: Path) -> None: ), ) write_file( - path / ".github" / "skills" / "tech-ai-sync-copilot-configs" / "SKILL.md", + path / ".github" / "skills" / "tech-ai-sync-global-copilot-configs-into-repo" / "SKILL.md", "\n".join( [ "---", - "name: TechAISyncCopilotConfigs", + "name: TechAISyncGlobalCopilotConfigsIntoRepo", "description: sync skill", "---", "", @@ -144,11 +144,11 @@ def build_source_audit_fixture(path: Path) -> None: ), ) write_file( - path / ".github" / "prompts" / "tech-ai-sync-copilot-configs.prompt.md", + path / ".github" / "prompts" / "tech-ai-sync-global-copilot-configs-into-repo.prompt.md", "\n".join( [ "---", - "name: TechAISyncCopilotConfigs", + "name: TechAISyncGlobalCopilotConfigsIntoRepo", "description: sync prompt", "agent: agent", "argument-hint: target_repo=", @@ -584,21 +584,21 @@ def test_build_plan_excludes_repo_only_global_customization_agents_from_consumer plan, _planned_files = MODULE.build_plan(REPO_ROOT, target_root) - assert ".github/agents/tech-ai-global-customization-builder.agent.md" not in plan.selection.agents - assert ".github/agents/tech-ai-global-customization-auditor.agent.md" not in plan.selection.agents + assert ".github/agents/tech-ai-standards-repo-config-builder.agent.md" not in plan.selection.agents + assert ".github/agents/tech-ai-standards-repo-config-auditor.agent.md" not in plan.selection.agents def test_internal_builder_triads_are_source_only_and_excluded_from_consumer_sync() -> None: assert ( - ".github/agents/tech-ai-internal-copilot-customization-builder.agent.md" + ".github/agents/tech-ai-repo-copilot-extender.agent.md" in MODULE.SOURCE_ONLY_AGENT_PATHS ) assert ( - ".github/prompts/tech-ai-internal-copilot-customization-builder.prompt.md" + ".github/prompts/tech-ai-repo-copilot-extender.prompt.md" in MODULE.SOURCE_ONLY_PROMPT_PATHS ) assert ( - ".github/skills/tech-ai-internal-copilot-customization-builder/SKILL.md" + ".github/skills/tech-ai-repo-copilot-extender/SKILL.md" in MODULE.SOURCE_ONLY_SKILL_PATHS ) @@ -719,7 +719,7 @@ def test_main_writes_json_report_with_selection_and_actions(tmp_path: Path) -> N payload = json.loads(report_file.read_text(encoding="utf-8")) assert result == 0 - assert payload["tool"] == "TechAISyncCopilotConfigs" + assert payload["tool"] == "TechAISyncGlobalCopilotConfigsIntoRepo" assert payload["analysis"]["profile"] == "backend-python" assert ".github/prompts/tech-ai-python.prompt.md" in payload["selection"]["prompts"] assert "redundant_assets" in payload["analysis"] diff --git a/tests/test_tech_ai_validate_copilot_customizations.py b/tests/test_tech_ai_validate_copilot_customizations.py index 1dc1e98..e1d353c 100644 --- a/tests/test_tech_ai_validate_copilot_customizations.py +++ b/tests/test_tech_ai_validate_copilot_customizations.py @@ -161,7 +161,7 @@ def test_tech_ai_validator_enforces_global_builder_semantic_sections(tmp_path: P target_root = tmp_path / "invalid-global-builder" copy_copilot_config(target_root) - builder_path = target_root / ".github" / "agents" / "tech-ai-global-customization-builder.agent.md" + builder_path = target_root / ".github" / "agents" / "tech-ai-standards-repo-config-builder.agent.md" builder_text = builder_path.read_text(encoding="utf-8").replace("## Token discipline", "## Token notes") builder_path.write_text(builder_text, encoding="utf-8") @@ -269,9 +269,9 @@ def test_tech_ai_validator_requires_release_comment_for_workflow_sha_pins(tmp_pa def test_root_agents_routes_customization_work_to_global_and_local_customization_agents() -> None: agents_text = (REPO_ROOT / "AGENTS.md").read_text(encoding="utf-8") - assert "TechAIGlobalCustomizationBuilder" in agents_text - assert "TechAIGlobalCustomizationAuditor" in agents_text - assert "TechAIInternalCopilotCustomizationBuilder" in agents_text + assert "TechAIStandardsRepoConfigBuilder" in agents_text + assert "TechAIStandardsRepoConfigAuditor" in agents_text + assert "TechAIRepoCopilotExtender" in agents_text assert "repo-only" in agents_text assert "## Available Skills" not in agents_text assert "## Available Prompts" not in agents_text @@ -279,7 +279,7 @@ def test_root_agents_routes_customization_work_to_global_and_local_customization def test_global_builder_maps_consolidated_rules_and_legacy_auditor_is_deprecated() -> None: builder_text = ( - REPO_ROOT / ".github" / "agents" / "tech-ai-global-customization-builder.agent.md" + REPO_ROOT / ".github" / "agents" / "tech-ai-standards-repo-config-builder.agent.md" ).read_text(encoding="utf-8") legacy_auditor_text = ( REPO_ROOT / ".github" / "agents" / "tech-ai-customization-auditor.agent.md" @@ -292,18 +292,18 @@ def test_global_builder_maps_consolidated_rules_and_legacy_auditor_is_deprecated assert "DEPRECATION.md" in builder_text assert "validate-copilot-customizations.sh" in builder_text assert "Deprecated compatibility alias" in legacy_auditor_text - assert "TechAIGlobalCustomizationAuditor" in legacy_auditor_text + assert "TechAIStandardsRepoConfigAuditor" in legacy_auditor_text def test_internal_builder_requires_grounding_against_concrete_target_files() -> None: agent_text = ( - REPO_ROOT / ".github" / "agents" / "tech-ai-internal-copilot-customization-builder.agent.md" + REPO_ROOT / ".github" / "agents" / "tech-ai-repo-copilot-extender.agent.md" ).read_text(encoding="utf-8") prompt_text = ( - REPO_ROOT / ".github" / "prompts" / "tech-ai-internal-copilot-customization-builder.prompt.md" + REPO_ROOT / ".github" / "prompts" / "tech-ai-repo-copilot-extender.prompt.md" ).read_text(encoding="utf-8") skill_text = ( - REPO_ROOT / ".github" / "skills" / "tech-ai-internal-copilot-customization-builder" / "SKILL.md" + REPO_ROOT / ".github" / "skills" / "tech-ai-repo-copilot-extender" / "SKILL.md" ).read_text(encoding="utf-8") assert "inspect concrete target files first" in agent_text