diff --git a/.github/CHANGELOG.md b/.github/CHANGELOG.md index 52fa102..d6fdacc 100644 --- a/.github/CHANGELOG.md +++ b/.github/CHANGELOG.md @@ -1,18 +1,30 @@ # Changelog ## Entry template + Use this format for new updates: + - `## YYYY-MM-DD` - One bullet per meaningful change. - Include file/path scope when useful. +## 2026-04-21 + +- Realigned `.github/skills/internal-copilot-audit/SKILL.md` to the current catalog-consistency and sync entrypoints, removing stale references to retired source-side script names that were blocking `make skill-lint`. +- Tightened `.markdownlint-cli2.jsonc` to exclude the local `.github/scripts/.venv/` tree and preserved imported `awesome-copilot-*` instruction files from repo-owned Markdown lint enforcement, keeping the lint target aligned with the repository rule that upstream assets stay verbatim unless explicitly refreshed. +- Normalized repo-owned Markdown and prompt surfaces across `.github/agents/`, `.github/prompts/`, and multiple `.github/skills/internal-*/` files so `make docs-lint` now passes alongside the existing catalog validators. +- Promoted `docs-lint` into the standard validation path through `Makefile` and `.github/scripts/github_catalog_validation.py`, and added regression coverage for the markdownlint config plus the aggregate `all` target. +- Hardened `Makefile` again so the aggregate `lint` target now absorbs `docs-lint` without double-running it through `all`, and added a workflow-level contract test that keeps `_github-catalog-validation` pinned to the canonical Bash wrapper entrypoints. + ## 2026-04-19 + - Renamed the root `Makefile` target from `catalog-validation` to `github-catalog-validation` for nomenclature consistency with the `_github-catalog-validation` workflow and refreshed `.github/README.md` plus `.github/agents/README.md` to remove remaining live `internal-router` wording in favor of the direct-entry operational model. - Renamed the canonical execution and challenge agents from `.github/agents/internal-fast-executor.agent.md` and `.github/agents/internal-critical-challenger.agent.md` to `.github/agents/internal-delivery-operator.agent.md` and `.github/agents/internal-critical-master.agent.md`, then realigned the live operational contracts, prompt references, shared boundary skills, and tests to the new canonical names. - Renamed `.github/workflows/catalog-validation.yml` to `.github/workflows/_github-catalog-validation.yml`, replaced the old Bash-only `catalog_validation` entrypoint with the new `.github/scripts/github_catalog_validation.py` plus matching Bash wrappers, and realigned `Makefile`, script coverage tests, and security-baseline references to the new workflow and script names. - Codified the pending retained-learning lessons into `.github/skills/internal-agent-sync-global-copilot-configs-into-repo/references/sync-contract.md`, `.github/skills/internal-agent-development/SKILL.md`, and `.github/skills/internal-agent-development/references/subagent-patterns.md`, added contract tests for the new guidance, and cleared the now-codified rows from `LESSONS_LEARNED.md`. ## 2026-04-18 + - Centralized lane-mismatch handling into the new repository-owned skill `.github/skills/internal-agent-boundary-recommendation-engine/`, realigned the four canonical operational agents plus the two sync command centers to stop and recommend the right owner through one shared protocol, removed the unused `agent` tool from the sync agents, and retired the orphaned `internal-agent-routing-engine` bundle from the live catalog. - Removed `internal-router` and the paired `internal-agent-routing-engine` from the live canonical operational model, left the four direct owners as the only canonical lanes, defaulted ambiguous entry to `internal-planning-leader`, platform-enforced no hidden peer dispatch by setting the canonical owners to `disable-model-invocation: true`, and realigned the active contracts, references, and tests away from router-centric dispatch. - Narrowed `.github/workflows/catalog-validation.yml` so it no longer repeats `_pre-commit` coverage: the workflow now runs the new `make catalog-lint` target for Bash syntax plus Python bytecode compilation, skips the duplicate YAML lint step, and leaves Markdown lint available as a manual target instead of failing the catalog-specific gate on long-standing repo-wide style debt. @@ -21,11 +33,13 @@ Use this format for new updates: - Simplified `.github/workflows/_pre-commit.yml` so it no longer depends on the `inputs` context during `push` or `pull_request` runs, keeping the surviving workflow aligned with GitHub Actions context-availability rules. ## 2026-04-17 + - Added reusable prompt files under `.github/prompts/` for planning kickoff, pre-mortem challenge, review kickoff, and sync planning so the repository now ships concrete prompt-file surfaces instead of an empty placeholder directory. - Refreshed plan tracking under `tmp/done/superpowers/plans/` so completed plan work is mirrored outside the active plan files and the remaining plan sources can stay current-state only. - Rebuilt `.github/INVENTORY.md` after the catalog refresh so support-only imported office skills are labeled explicitly in the generated inventory output. ## 2026-04-12 + - Renamed the repository-root retained-learning ledger to `LESSONS_LEARNED.md`, then realigned the retained-learning contract, sync automation, and tests to use the new canonical path. - Aligned `.pre-commit-config.yaml` and expanded `.editorconfig` with file-type defaults for Python, shell, Terraform/HCL, YAML, JSON/TOML, Markdown, Make, and local config files so the repo and synced consumers get a practical editor baseline without the formatter ping-pong that left `pre-commit` failing with no visible git diff. - Expanded the cross-repository sync baseline to include `.editorconfig`, `.pre-commit-config.yaml`, and `.github/workflows/terraform-pre-commit.yml`, then updated the sync agent/skill contract and sync planner tests to keep that scope explicit and narrow. @@ -37,6 +51,7 @@ Use this format for new updates: - Simplified `LESSONS_LEARNED.md` again so it now keeps only pending lessons; once a lesson is codified into a canonical owner, it is removed from the ledger instead of being duplicated there. ## 2026-04-11 + - Tightened the Python skill split instead of collapsing it: clarified the shared baseline in `.github/instructions/internal-python.instructions.md`, sharpened `internal-project-python` around structured package and application boundaries, and expanded `internal-script-python` plus its layout reference to cover the repository-aligned toolkit pattern used under `.github/scripts/` with shared `lib/`, hash-locked `requirements.txt`, shared `run.sh`, root-level tests, and thin wrapper entrypoints. - Renamed the sync engine skill from `.github/skills/internal-sync-global-copilot-configs-into-repo/` to `.github/skills/internal-agent-sync-global-copilot-configs-into-repo/`, then realigned the paired agent contract and skill invocation metadata to the new canonical skill name. - Updated `.github/scripts/lib/internal_skills.py` so documented workflow outputs under `tmp/` are treated as virtual paths during internal-skill validation, then refreshed `.github/README.md` to match the live tracked agent catalog and current source-side script entrypoints. @@ -50,13 +65,16 @@ Use this format for new updates: - Removed `.github/instructions/awesome-copilot-copilot-sdk-python.instructions.md` from the live catalog and realigned `.github/INVENTORY.md`, `.github/README.md`, `.github/agents/internal-sync-external-resources.agent.md`, and `tmp/superpowers/2026-04-10-audit-catalogo-copilot.md` so the imported Python SDK instruction is no longer treated as active. ## 2026-04-10 + - Added the provider skill rollout beyond AWS by creating repository-owned Azure, GCP, and GitHub skill families under `.github/skills/internal-{azure,gcp,github}-*`, keeping the AWS boundary model as the baseline with short adaptive strategic skills, separate organization/governance/operations lanes where justified, minimal `references/`, and `agents/openai.yaml` metadata for every new skill. - Refreshed `.github/README.md` and `.github/INVENTORY.md` so the maintainer-facing catalog now matches the live provider-skill inventory and the current prompt, skill, and script counts on disk. ## 2026-04-07 + - Updated the completion-report policy in `.github/copilot-instructions.md`, `.github/README.md`, and the sync agent and skill contract so synced target repositories now inherit a summary format that lists only the actually used agents, instructions, prompts, skills, and other resources, each with a short reason. ## 2026-04-06 + - Externalized the exact path inventory into `.github/INVENTORY.md`, reduced root `AGENTS.md` to a bridge pointer, removed the current repository validator/test layer, and updated maintainer docs, templates, and governance text to stop depending on deleted validation assets and the removed `internal-agents-md-bridge` skill. - Refactored the instruction architecture around rule ownership: root `AGENTS.md` is now the strategic entrypoint and precedence anchor, `.github/copilot-instructions.md` is the compact repo-wide Copilot projection, `INTERNAL_CONTRACT.md` now captures rebuild-safe invariants instead of deleted automation behavior, scoped Markdown guidance now projects the central English-by-default rule, and sync governance assets were updated to stop treating root `AGENTS.md` as a subordinate thin bridge. - Slimmed `.github/copilot-instructions.md` by removing stack-owned Python template, script, Java, and Node guidance, and reduced `.github/instructions/internal-bash.instructions.md` to repo-local Bash additions so runtime-specific rules now stay with their matching instruction owners instead of the primary policy layer. @@ -66,6 +84,7 @@ Use this format for new updates: - Tightened the active non-README governance layer after the refactor: reduced root `AGENTS.md` to a thinner bridge, refreshed `.github/INVENTORY.md` to match the live prompt catalog, removed stale prompt/script/source-of-truth references from active governance assets, and aligned the cross-repository sync agent/skill with the files that actually exist on disk. ## 2026-04-05 + - Added `scripts/internal_yaml.py` and reused it from both `internal-sync-copilot-configs.py` and `validate-copilot-customizations.py` so repository-owned Python automation now shares one YAML/frontmatter parser instead of duplicating parsing logic. - Restored hash-locked Python dependency policy for repository-owned scripts: `scripts/requirements.txt` now carries the pinned `PyYAML` wheel hash and `internal-python-runner.sh` installs with `--require-hashes` without any fallback path. - Removed the hash-detection fallback from `scripts/internal-python-runner.sh`, switched repository-owned Python launcher guidance to install directly from `requirements.txt`, and deleted the internal Python-policy clause that allowed a non-locked fallback path. @@ -79,6 +98,7 @@ Use this format for new updates: - Refreshed `.github/README.md` so the maintainer-facing catalog now matches the live `internal-*`, `obra-*`, and imported support families, the canonical internal agent model, and the actual scripts and workflow present on disk after recent repository restructuring. ## 2026-04-04 + - Added a mandatory end-of-operation completion report contract to `.github/copilot-instructions.md`, documented the same emoji-based `Outcome` / `Agents` / `Instructions` / `Skills` structure in `.github/README.md`, and kept root `AGENTS.md` on a thin bridge pointer to the detailed policy. - Extended `INTERNAL_CONTRACT.md`, `tests/test_contract_runner.py`, `tests/test_validate_copilot_customizations.py`, and `.github/scripts/validate-copilot-customizations.py` so the completion-report contract is now source-governed and strict-validator enforced. - Updated `internal-sync-external-resources`, `internal-sync-global-copilot-configs-into-repo`, and the sync skill workflow so completed sync runs must also end with the same completion-report categories and explicit unused-category explanations. @@ -86,10 +106,12 @@ Use this format for new updates: - Updated `.github/copilot-instructions.md`, `.github/instructions/internal-python.instructions.md`, and `.github/skills/internal-script-python/SKILL.md` so new Python scripts must make an explicit stdlib-vs-library decision, prefer mature third-party packages when they clearly simplify the final code, and record that choice in a short dependency decision note before implementation. ## 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`. - Annotated `.github/workflows/terraform-pre-commit.yml` image digest references with the corresponding `pre-commit-terraform` release version to make the SHA-based pin self-describing. @@ -98,14 +120,17 @@ Use this format for new updates: - Updated `.github/scripts/internal-sync-copilot-configs.py` so the default VS Code PR description mode expected during consumer alignment is now `template` instead of `Copilot`. ## 2026-03-12 + - Renamed the canonical PR prompt from `tech-ai-pr-description.prompt.md` / `TechAIPRDescription` to `tech-ai-pr-editor.prompt.md` / `TechAIPREditor`, and updated `AGENTS.md`, the validator, and review notes to use the new canonical name consistently. - Updated `scripts/internal-sync-copilot-configs.py` and its tests so sync plans now delete manifest-managed files that were removed from the desired baseline, allowing canonical renames to cleanly remove deprecated managed assets in consumer repositories. ## 2026-03-11 + - Updated `scripts/internal-sync-copilot-configs.py` so consumer sync now discovers new instructions from `applyTo`, automatically includes all portable consumer-facing agents, and merges consumer-facing prompt/skill capabilities declared in the source `AGENTS.md` preferred sections. This prevents newly added shared assets such as the PAIR analysis flow from being silently skipped in downstream repos. - Updated `scripts/internal-sync-copilot-configs.py` and `tests/test_tech_ai_sync_copilot_configs.py` so consumer alignment now reports a target-side gap when `.vscode/settings.json` is missing or does not set `githubPullRequests.pullRequestDescription` to `Copilot`, making the VS Code PR-form Copilot dependency visible in sync reports. ## 2026-03-09 + - 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/internal-sync-copilot-configs.py`, updated lifecycle docs, and made quickstart plus `.github/README.md` prefer sync-first alignment. @@ -115,6 +140,7 @@ Use this format for new updates: - Expanded validator and sync tests to cover new recommendation, rendering, provenance, and validation paths. ## 2026-03-08 + - Updated the PR-writing prompt, skill, and agent guidance to derive required sections from the resolved repository PR template instead of hardcoding older headings such as `Security and Compliance` or `Related Links`. - Updated `scripts/internal-sync-copilot-configs.py` and `scripts/validate-copilot-customizations.sh` so repository-owned prompt, skill, and agent assets outside the synced global baseline must use `internal-*` in both filenames and `name:` values, making internal customizations visibly distinct from synced `tech-ai-*` assets. - Updated `scripts/internal-sync-copilot-configs.py` so target-only skill detection compares full relative paths instead of the shared `SKILL.md` filename, fixing missed unmanaged skill assets in consumer repositories. @@ -130,6 +156,7 @@ Use this format for new updates: - 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 `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. @@ -143,6 +170,7 @@ Use this format for new updates: - 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-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/internal-sync-copilot-configs.py` plus `tests/test_tech_ai_sync_copilot_configs.py` for deterministic analysis, manifest-based sync planning, and reporting. @@ -152,6 +180,7 @@ Use this format for new updates: - Added `.github/tech-ai-requirements-dev.txt`, CI pytest execution, `shellcheck` pre-commit coverage, and validator integration tests for stronger local and CI validation. ## 2026-03-04 + - Added `skills/tech-ai-code-review/SKILL.md`: per-language anti-pattern catalogs with severity mappings and good-vs-bad examples. - Added `prompts/cs-code-review.prompt.md`: on-demand strict code review prompt with configurable strictness. - Added `agents/tech-ai-script-reviewer.agent.md`: exhaustive, nit-level code reviewer (`TechAIScriptReviewer`) for Python, Bash, and Terraform with review persona inspired by Martin Fowler, Raymond Hettinger, and Kelsey Hightower. @@ -159,9 +188,11 @@ Use this format for new updates: - Updated `AGENTS.md` with `TechAIScriptReviewer` routing, `code-review` skill, and `cs-code-review` prompt. ## 2026-02-28 + - Renamed GitHub-related files to `github-*` prefix for consistency across agents, prompts, instructions, and workflows. ## 2026-02-07 + - Added missing global Copilot instruction files for commit messages and code review. - Added new instruction files: YAML, Markdown, Makefile, Scripts, Lambda. - Added new skills: `terraform-module`, `cloud-policy`. diff --git a/.github/DEPRECATION.md b/.github/DEPRECATION.md index fe90b65..8ea5ec9 100644 --- a/.github/DEPRECATION.md +++ b/.github/DEPRECATION.md @@ -1,14 +1,17 @@ # Deprecation Policy ## Purpose + Define a predictable process for deprecating Copilot customization assets (`instructions`, `skills`, `agents`, and templates). ## Lifecycle states + - Active: recommended for current use. - Deprecated: still available but scheduled for removal. - Removed: no longer maintained or supported. ## Required process + 1. Mark the asset as deprecated in its file header or first section. 2. Record the change in `.github/CHANGELOG.md` with migration guidance. 3. Keep a minimum deprecation window of one release cycle (or 30 days if no release cycle exists). @@ -16,14 +19,17 @@ Define a predictable process for deprecating Copilot customization assets (`inst 5. Remove only after the window ends and no blocking consumers remain. ## Backward compatibility rules + - Instructions: avoid changing mandatory behavior without documenting impact. - Skills: keep old skill path available during transition. - Agents: keep objective and restriction semantics stable where possible. ## Emergency exception + Immediate removal is allowed only for security or compliance issues. The removal reason must be documented in `.github/CHANGELOG.md`. ## Current deprecations + - `.github/workflows/_terraform-pre-commit.yml`: **Removed**. Replaced by `.github/workflows/_pre-commit.yml` after consolidating duplicate pre-commit workflows into one canonical entrypoint. - `.github/workflows/terraform-pre-commit.yml`: **Removed**. Replaced by `.github/workflows/_pre-commit.yml` so the source baseline ships a single pre-commit workflow. - `.github/skills/antigravity-domain-driven-design/SKILL.md`: **Removed**. Consolidated into `.github/skills/internal-ddd/SKILL.md`. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 5f20381..cc861aa 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,9 +1,4 @@ - - - - - -## Description +# Description diff --git a/.github/agents/README.md b/.github/agents/README.md index 4158889..14c8339 100644 --- a/.github/agents/README.md +++ b/.github/agents/README.md @@ -3,12 +3,14 @@ This folder contains deliberate custom agents for repository-owned direct-owner operations plus repo-only sync workflows. ## Resolution order + 1. Apply repository non-negotiables from `copilot-instructions.md`. 2. Apply explicit user request and selected agent behavior (agent-first). 3. Apply matching `instructions/*.instructions.md` (`applyTo` by path). 4. Apply referenced skill details. ## Recommended owner selection + - Safe fallback when the right operational lane is still ambiguous: `internal-planning-leader`. - Direct canonical owners: `internal-delivery-operator`, `internal-planning-leader`, `internal-review-guard`, `internal-critical-master`. - Source-side catalog sync, rationalization, overlap cleanup, and governance drift correction in this repository: `internal-sync-external-resources`. @@ -16,10 +18,12 @@ This folder contains deliberate custom agents for repository-owned direct-owner - PR-focused work should use the `internal-pr-editor` skill because this repository does not currently ship a dedicated PR editor agent. ## Repo-only agents (not synced to consumers) + - `internal-sync-external-resources` - `internal-sync-global-copilot-configs-into-repo` ## Why this catalog stays deliberate + - This repository keeps a deliberate set of source-side command-center agents under `.github/agents/`. - Prefer one cohesive agent per recurring operational or governance workflow. - Keep the four canonical owners explicit and non-overlapping, and keep reusable logic in skills instead of bloating agent bodies. @@ -28,6 +32,7 @@ This folder contains deliberate custom agents for repository-owned direct-owner - Prefer skills for detailed task procedures unless a dedicated agent file is present. ## Selection guide + 1. Use `internal-planning-leader` when the user has not yet chosen the right owner or the request could plausibly be execution, planning, review, or challenge. 2. Use `internal-delivery-operator` for clear, local execution work with concrete verification and no non-trivial strategic tradeoffs. 3. Use `internal-review-guard` for defect-first review, merge readiness, regression analysis, and evidence-based validation. diff --git a/.github/agents/internal-critical-master.agent.md b/.github/agents/internal-critical-master.agent.md index 9e7a1f5..42fd0ef 100644 --- a/.github/agents/internal-critical-master.agent.md +++ b/.github/agents/internal-critical-master.agent.md @@ -82,4 +82,4 @@ You are the repository-owned pressure-test and reframing lane for reasoning, ass - Why it matters now - One probing question or reframing move - Closing synthesis when the pressure test is complete -- Recommended owner when the next step no longer belongs to the challenge lane \ No newline at end of file +- Recommended owner when the next step no longer belongs to the challenge lane diff --git a/.github/agents/internal-delivery-operator.agent.md b/.github/agents/internal-delivery-operator.agent.md index 5d5759b..a694481 100644 --- a/.github/agents/internal-delivery-operator.agent.md +++ b/.github/agents/internal-delivery-operator.agent.md @@ -52,4 +52,4 @@ You are the execution owner for clear, local, low-risk work selected directly by - Execution scope - Relevant tactical skill or runtime lane - Validation path -- Boundary note when the task no longer belongs to execution \ No newline at end of file +- Boundary note when the task no longer belongs to execution diff --git a/.github/agents/internal-planning-leader.agent.md b/.github/agents/internal-planning-leader.agent.md index 7eaac83..1615350 100644 --- a/.github/agents/internal-planning-leader.agent.md +++ b/.github/agents/internal-planning-leader.agent.md @@ -31,6 +31,7 @@ You are the planning, authoring, and decision owner for non-trivial operational - Make assumptions, tradeoffs, and the selected direction explicit. - Own non-trivial repository-owned authoring for agents, skills, instructions, routing, and governance updates. +- Do not create retained plan artifacts for clear, local, quick, or banal tasks; keep that planning ephemeral in chat. - Do not default into implementation once the design is settled; recommend the right next owner instead. - When the user is unsure which operational lane fits, treat that ambiguity as planning-owned until a clearer direct owner emerges. - Treat `obra-using-superpowers` as upstream workflow guidance, not as proof that every referenced tool contract or runtime term maps 1:1 to this repository's GitHub Copilot environment. @@ -60,5 +61,5 @@ You are the planning, authoring, and decision owner for non-trivial operational ## Mode Guidance - Brainstorming mode: prefer `obra-brainstorming` when requirements, solution shape, or user intent are still fluid. -- Plan-authoring mode: prefer `internal-writing-plans` when repository-owned work needs an execution plan under `tmp/superpowers/` and the local multi-file plan policy applies. +- Plan-authoring mode: prefer `internal-writing-plans` only when repository-owned work needs a retained execution plan under `tmp/superpowers/` because the work crosses turns, macro-categories, handoff or tracking needs, or explicit tradeoffs. Keep planning in chat for clear, local, quick, or banal tasks. - Plan-execution oversight: prefer `internal-executing-plans` when an approved repository-owned plan is being applied and the `done-*` loop or blocker handling must stay explicit. diff --git a/.github/copilot-code-review-instructions.md b/.github/copilot-code-review-instructions.md index 2e8ac35..27ab0d9 100644 --- a/.github/copilot-code-review-instructions.md +++ b/.github/copilot-code-review-instructions.md @@ -1,13 +1,16 @@ # Code Review Instructions ## Objective + - Protect the business: find defects, security flaws, and maintainability risks before they reach production. - Keep findings concise, severity-ordered, and tied to concrete evidence. - Preserve requested behavior first, then improve security, maintainability, and simplicity. - Never write review output to files unless the user explicitly asks. All output goes in chat. ## Self-questioning protocol + Every review must include self-questioning: + - Assign a confidence level to every finding: **High**, **Medium**, or **Low**. - For **Low** confidence findings, explain what context might be missing that could invalidate the finding. - After producing all findings, re-examine the top 3 most severe ones and ask: "Could this be intentional? Am I sure? Is my suggested fix actually simpler?" @@ -15,13 +18,16 @@ Every review must include self-questioning: - Include a brief "Self-questioning notes" section at the end with any revised assessments. ## Priority order + Apply this priority to all reviews: + 1. **Correctness** — Does it do what it claims? 2. **Security** — Secrets, injection, privilege, unsafe operations. 3. **Simplicity** — Is this the simplest thing that could work? 4. **Maintainability** — Will this be easy to change in 6 months? ## Review output format + - `Critical`: must-fix issues such as security flaws, correctness bugs, or data-loss risk. - `Major`: high-risk improvements such as mandatory rule violations, unsafe defaults, or missing validation. - `Minor`: worthwhile improvements that reduce technical debt or clarify intent. @@ -29,12 +35,14 @@ Apply this priority to all reviews: - `Notes`: assumptions, follow-ups, or scope clarifications. Every finding must include: + - Severity and confidence level. - File path and line reference. - What is wrong and why it matters (impact on business or operations). - Concrete fix suggestion. ## Baseline checks + 1. Security and least privilege. 2. No hardcoded secrets or credentials. 3. Consistency with repository naming and structure conventions. @@ -42,16 +50,19 @@ Every finding must include: 5. Documentation updates when behavior changes (excluding `README.md` unless explicitly requested). ## Escalation rules + - Any repeated anti-pattern (3+ times in the same diff) escalates one severity level. - Any deviation from the matching `instructions/*.instructions.md` file is at minimum a `Nit`. - Any violation of `security-baseline.md` is at minimum a `Major`. ## Token-aware review protocol + - Load only the diff, directly related files, and the matching instruction files. - Use `.github/skills/internal-code-review/SKILL.md` as the detailed anti-pattern catalog for Python, Bash, and Terraform. - Do not inline long language-specific catalogs when the `code-review` skill is available. ## Focus by area + - Terraform: drift risk, lifecycle safety, variable typing, plan readability, provider pinning, and cloud-specific IAM patterns. - Workflows: SHA pinning, minimal permissions, environment protection, OIDC, and deterministic checks. - Scripts: input validation, early returns, readable control flow, and English logs. @@ -62,6 +73,7 @@ Every finding must include: - Copilot customization assets: reusable wording, naming consistency, and low-noise token usage. ## Minimum language guardrails + - Python: flag hardcoded secrets, `eval()`/`exec()`, unsafe `pickle`, bare `except`, `shell=True`, and missing tests for new logic. - Bash: flag hardcoded secrets, `eval`, unsafe temp files, missing `set -euo pipefail`, unquoted variables, and missing dependency checks. - Terraform: flag hardcoded secrets, wildcard IAM, missing state-locking expectations, unpinned providers, and hardcoded environment-specific identifiers. diff --git a/.github/copilot-commit-message-instructions.md b/.github/copilot-commit-message-instructions.md index dc25e09..e6de36b 100644 --- a/.github/copilot-commit-message-instructions.md +++ b/.github/copilot-commit-message-instructions.md @@ -1,9 +1,11 @@ # Commit Message Instructions ## Format + `(): ` ## Types + - `feat`: New behavior - `fix`: Bug fix - `docs`: Documentation updates @@ -12,12 +14,14 @@ - `chore`: Tooling/maintenance ## Rules + - Use imperative mood. - Keep summary concise (<= 72 chars preferred). - Scope should match changed area (for example `terraform`, `scripts`, `workflows`, `docs`). - Use an English body when context is needed. ## Examples + - `feat(terraform): add policy assignment module` - `fix(workflows): pin checkout action by full SHA` - `docs(copilot): align skill and agent references` diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 7168b99..68feb05 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -8,7 +8,7 @@ You are an expert software and platform engineer. Protect correctness, security, - Inspect nearby files before editing and follow the existing naming, frontmatter, and directory patterns. - Use only repository evidence that exists on disk. Do not invent runtimes, validators, sync flows, or test suites. - Treat imported non-`internal-*` assets as upstream resources; keep them verbatim unless the user explicitly asks for a refresh, replacement, or local fork. -- Do not edit imported upstream assets in place unless the need is strong, the user explicitly counter-validates the exception, and the replay patch is registered in the `internal-agent-sync-control-center` bundle in the same change. +- Do not edit imported upstream assets in place unless the need is strong, the user explicitly counter-validates the exception, and the replay patch is registered in the `internal-agent-sync-external-resources` bundle in the same change. ## Precedence And Projections @@ -77,12 +77,14 @@ You are an expert software and platform engineer. Protect correctness, security, ## Superpowers Plan Policy -- For repository-owned planning work, create or reuse a task folder at `tmp/superpowers//`. -- Keep execution plans as multiple numbered Markdown files by macro-category, such as `01-contesto-e-vincoli.md`, `02-implementazione.md`, and `03-validazione.md`; do not collapse them into one monolithic plan file. +- Keep planning ephemeral in chat for clear, local, quick, or banal tasks. +- Create or reuse `tmp/superpowers//` only when retained planning is justified by non-banal work such as multi-turn coordination, multiple macro-categories, explicit handoff, tracking, or provenance, or tradeoffs and uncertainties that merit a saved plan. +- Keep retained execution plans as numbered Markdown files: use a single `01-...md` file when one macro-category is enough, or multiple numbered files such as `01-contesto-e-vincoli.md`, `02-implementazione.md`, and `03-validazione.md` when the work genuinely spans multiple macro-categories. +- Keep detailed plan-shape and authoring heuristics in `internal-writing-plans` instead of restating them in this repo-wide projection. - Keep doubts, open questions, and user decisions in `dubbi-e-domande.md`. This file stays outside the plan-and-apply loop and must not be treated as an executable plan file. - During execution, maintain matching `done-*` files. Move completed items into the corresponding `done-*` file, remove them from the active source file, delete an emptied source plan file, and continue through the remaining numbered plan files until the work is finished or a real blocker requires user input. - Preserve imported `obra-*`, `awesome-*`, `openai-*`, and other upstream assets; express this repository's planning policy through repository-owned internal wrappers instead of editing upstream planning skills. -- If an imported asset still requires a direct repo-local exception, register the replay patch in `.github/skills/internal-agent-sync-control-center/references/imported-asset-overrides.yaml` instead of leaving an undocumented fork. +- If an imported asset still requires a direct repo-local exception, register the replay patch in `.github/skills/internal-agent-sync-external-resources/references/imported-asset-overrides.yaml` instead of leaving an undocumented fork. ## Repository Workflow Reminders diff --git a/.github/instructions/internal-bash.instructions.md b/.github/instructions/internal-bash.instructions.md index 49d20e8..1e22a0e 100644 --- a/.github/instructions/internal-bash.instructions.md +++ b/.github/instructions/internal-bash.instructions.md @@ -14,6 +14,7 @@ Assume `.github/instructions/awesome-copilot-shell.instructions.md` covers the b The two instruction files intentionally co-load for `**/*.sh`: the imported file remains the generic shell baseline, while this file owns the repository-specific Bash defaults, operator-facing emoji logs, wrapper conventions, and Python-launcher rules. ## Repository-specific rules + - Use Bash only: `#!/usr/bin/env bash`. - Add a short header comment with purpose and usage examples. - Use emoji logs (`ℹ️ ✅ ⚠️ ❌`) for operator-facing runtime messages. @@ -23,6 +24,7 @@ The two instruction files intentionally co-load for `**/*.sh`: the imported file - Apply these rules for both create and modify operations. ## Minimal delta example + ```bash #!/usr/bin/env bash # @@ -45,10 +47,12 @@ main "$@" ``` ## Python launcher additions + - When the Bash script is a launcher for a standalone Python tool, use it only when that tool needs external packages or an isolated local bootstrap path. - Python launchers must keep the common invocation path zero-argument friendly by embedding sensible default Python-script parameters and exposing only optional overrides. - For those Python launchers, resolve the script directory, create or reuse a sibling `.venv`, install from the local hash-locked `requirements.txt`, and execute the sibling Python entry point. ## Validation + - `bash -n