diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md index 8aab468..d2e4945 100644 --- a/.github/CHANGELOG.md +++ b/.github/CHANGELOG.md @@ -6,6 +6,10 @@ Use this format for new updates: - One bullet per meaningful change. - Include file/path scope when useful. +## 2026-03-19 +- Updated `.github/copilot-instructions.md`, `.github/instructions/python.instructions.md`, and `.github/prompts/tech-ai-python.prompt.md` so Python tasks now standardize on human-readable hash-locked `requirements.txt` files for external dependencies, clarify that the lock file should capture the full dependency closure, and treat third-party libraries as a recommendation only when they materially simplify the code. +- Updated `.github/prompts/tech-ai-python-script.prompt.md`, `.github/skills/tech-ai-script-python/SKILL.md`, and `.github/instructions/bash.instructions.md` so new standalone Python tools default to a self-contained folder with a `run.sh` launcher, add a local `requirements.txt` only when external packages are used, and bootstrap `.venv` plus locked dependency installation only when that file exists. + ## 2026-03-13 - Updated `.pre-commit-config.yaml` to pin `pre-commit-hooks` `v6.0.0`, keep `pre-commit-terraform` explicitly annotated at `v1.105.0`, and move `shellcheck-py` to `v0.11.0.1`, adding inline release comments for each pinned revision. - Updated `.github/workflows/github-validate-copilot-customizations.yml` to pin the runner to `ubuntu-24.04`, add `actions/setup-python` pinned by SHA for Python `3.14.3`, pin `pip` to `26.0.1`, and replace the unpinned `apt` shellcheck install with the pinned Python dependency set from `.github/tech-ai-requirements-dev.txt`. diff --git a/.github/README.md b/.github/README.md index 01c3cf6..768126b 100644 --- a/.github/README.md +++ b/.github/README.md @@ -12,7 +12,7 @@ This folder is the **single source of truth** for GitHub Copilot customization a | --- | --- | --- | --- | | `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). | +| `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. | General implementation guidance (see reviewer agents for specialized reviews). | | `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 @@ -109,7 +109,7 @@ Implementation knowledge bases loaded on demand by agents and prompts. They cont | --- | --- | --- | | `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-code-review` | Per-language anti-pattern catalogs (Python, Bash, Terraform), severity mappings, escalation rules for exhaustive code review. | Agents `TechAIBashReviewer`, `TechAIPythonReviewer`, `TechAITerraformReviewer`, `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` | @@ -149,10 +149,9 @@ 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. +> **How they differ**: `TechAIReviewer` is the broad quality gate (like a senior engineer's PR review). `TechAISecurityReviewer` focuses exclusively on security concerns. Use `TechAIReviewer` first; it will recommend routing to a specialist when needed. #### Infrastructure specialist agents @@ -183,7 +182,6 @@ These agents manage the **lifecycle** of Copilot customization assets. They are | 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. | | `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/`) @@ -225,7 +223,7 @@ These agents manage the **lifecycle** of Copilot customization assets. They are - `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): `TechAISyncGlobalCopilotConfigsIntoRepo`, `TechAIScriptReviewer`. +- **Repo-only agents** (not synced to consumers): `TechAISyncGlobalCopilotConfigsIntoRepo`. - **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. diff --git a/.github/agents/README.md b/.github/agents/README.md index 556c521..e5a89e3 100644 --- a/.github/agents/README.md +++ b/.github/agents/README.md @@ -15,7 +15,6 @@ This folder contains optional custom agents for focused tasks. - Write-capable: `TechAIImplementer`. ## Repo-only agents (not synced to consumers) -- `TechAIScriptReviewer` - `TechAISyncGlobalCopilotConfigsIntoRepo` ## Why generic core agents diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3e08e03..34f44d9 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -64,6 +64,9 @@ These apply to every code change, regardless of language or technology: - Use simple control flow and early returns. - Bash: always `#!/usr/bin/env bash` (never POSIX `sh`). - Python: add unit tests for testable logic. +- Python dependencies: when external packages are introduced, standardize on a compiled `requirements.txt` with exact pins, full transitive dependency closure, and `--hash` entries, plus short comment lines that make the pinned versions readable to humans. +- Python dependencies: third-party libraries are recommended when they materially simplify parsing, validation, HTTP, CLI, serialization, or retry logic; keep the standard library when it is simpler and safer. +- New standalone Python scripts should default to a self-contained folder that includes the Python entry point, a Bash launcher, and a local `requirements.txt` only when external packages are required. The launcher should bootstrap `.venv` and install from `requirements.txt` only when that file exists. - Prefer immutable dependency and image pins; keep stack-specific locking details in the matching instruction file. ## Java and Node.js standards diff --git a/.github/instructions/bash.instructions.md b/.github/instructions/bash.instructions.md index f2d2344..882048e 100644 --- a/.github/instructions/bash.instructions.md +++ b/.github/instructions/bash.instructions.md @@ -35,6 +35,7 @@ set -euo pipefail - Use `getopts` for argument parsing. - Keep logic simple and avoid unnecessary complexity. - Validate inputs and handle errors gracefully. +- When the Bash script is a launcher for a standalone Python tool, resolve its own directory, create or reuse a sibling `.venv`, install from the local hash-locked `requirements.txt` if it exists, and execute the sibling Python entry point. ## Validation - `bash -n