From 2b571161141dffc2a161ea5897f80b3c3385f954 Mon Sep 17 00:00:00 2001 From: Diego Mauricio Lagos Date: Tue, 21 Apr 2026 20:47:44 +0200 Subject: [PATCH 1/6] feat(sync): enhance sync contract and internal audit skills with critical rule mirroring guidance --- .../SKILL.md | 1 + .../references/sync-contract.md | 1 + .github/skills/internal-copilot-audit/SKILL.md | 2 ++ 3 files changed, 4 insertions(+) diff --git a/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/SKILL.md b/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/SKILL.md index a822816..4dcd4c9 100644 --- a/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/SKILL.md +++ b/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/SKILL.md @@ -26,6 +26,7 @@ The paired agent should not restate default mode handling, preserved `local-*` b - Treat this repository as the source of truth. - Keep target assumptions narrow: GitHub Copilot assets live under `.github/` and `AGENTS.md` stays at repository root. - Preserve target `local-*` assets under mirrored categories, preserve the target consumer-local GitHub instructions overrides file after materialization, and delete target-only non-local assets there during `apply`. +- When consumer-local creator bundles depend on shared runtime-critical rules, mirror those rules inside each creator bundle as source-managed files and keep the mirror paths registered in the source inventory and target manifest; do not rely on cross-bundle references or unsynced local-only resources for creator runtime behavior. - When the source baseline includes an approved imported-asset override registry plus replay patches, mirror that governance bundle as source-managed state instead of recreating target-local hidden forks on imported assets. - Exclude source resources named `internal-sync-*` from consumer mirroring and remove any target copies of those resources during `apply`. - Materialize the source template `.github/copilot-instructions.override.md.template` into the consumer target as the consumer-local copilot instructions override file when that target file is missing, then preserve target-authored changes there on later sync runs. diff --git a/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/references/sync-contract.md b/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/references/sync-contract.md index b01c0d2..66dbf2e 100644 --- a/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/references/sync-contract.md +++ b/.github/skills/internal-agent-sync-global-copilot-configs-into-repo/references/sync-contract.md @@ -24,6 +24,7 @@ Mirror or structurally align these source-managed paths into the consumer reposi Do not sync `README.md`, changelogs, other workflows, templates, or bootstrap helpers unless the user explicitly expands scope. Do not sync consumer-facing resources whose file or directory name starts with `internal-sync-`; those remain source-only operational controls for the standards repository. Treat `LESSONS_LEARNED.md` as a structure-managed exception: sync the source template and contract, but preserve target-authored pending lesson rows instead of copying source rows into consumer repositories. +When a consumer-local creator depends on shared runtime-critical rules, keep a self-contained mirror of those rules inside the creator bundle and track the mirror path in the source inventory plus the target `.github/copilot-sync.manifest.json`; do not assume cross-bundle references or target-local extras will be present at runtime. ## Target Rules diff --git a/.github/skills/internal-copilot-audit/SKILL.md b/.github/skills/internal-copilot-audit/SKILL.md index bb5a56f..ccaddea 100644 --- a/.github/skills/internal-copilot-audit/SKILL.md +++ b/.github/skills/internal-copilot-audit/SKILL.md @@ -28,6 +28,7 @@ Treat the declared governance contract in the relevant agent, root `AGENTS.md`, - Detect sync workflows that skip or fail to report governance review for `.github/copilot-instructions.md` and root `AGENTS.md`. - Detect naming violations and stale inventory references. - Detect governance files that still describe removed, renamed, or retired assets. +- Detect catalog retirements or remaps that were not propagated in the same change to the local sync command center, `.github/scripts/validate-copilot-customizations.py`, and `.github/scripts/internal-sync-copilot-configs.py`. ## Audit Order @@ -69,3 +70,4 @@ When a repository-owned internal replacement exists, prefer deleting the weaker - Keeping source-side command-center assets in consumer sync scope - Keeping upstream assets whose only value is historical familiarity - Treating stale inventory references as harmless +- Retiring or remapping managed skills or agents without updating the local sync command center, validator, and sync script in the same change From a7cc23f1f56afa490301f2f31ad0f8adc3b00960 Mon Sep 17 00:00:00 2001 From: Diego Mauricio Lagos Date: Tue, 21 Apr 2026 22:47:00 +0200 Subject: [PATCH 2/6] feat(planning): refine planning policies and execution guidelines for repository-owned tasks --- .../agents/internal-planning-leader.agent.md | 3 +- .github/copilot-instructions.md | 10 ++-- .../skills/internal-executing-plans/SKILL.md | 4 +- .../skills/internal-writing-plans/SKILL.md | 51 ++++++++++++----- .../internal-writing-plans/agents/openai.yaml | 2 +- AGENTS.md | 7 ++- tests/test_plan_policy_contract.py | 56 +++++++++++++++---- 7 files changed, 98 insertions(+), 35 deletions(-) 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-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/skills/internal-executing-plans/SKILL.md b/.github/skills/internal-executing-plans/SKILL.md index 627c3d0..8fd5089 100644 --- a/.github/skills/internal-executing-plans/SKILL.md +++ b/.github/skills/internal-executing-plans/SKILL.md @@ -5,9 +5,9 @@ description: Use when executing a repository-owned plan from tmp/superpowers// and the plan must follow the local multi-file, Italian-default structure. +description: Use when repository-owned work needs a retained numbered plan under tmp/superpowers// and the plan must follow the local Italian-default execution-plan contract. --- # Internal Writing Plans Use this skill as the repository-owned wrapper for plan authoring in this repository. -Treat `obra-writing-plans` as imported depth and keep any repo-local drift fixes narrow. This skill adds the local contract for where plans live, how they are split, what language they use, and what must stay outside the execution loop. +Treat `obra-writing-plans` as imported depth and keep any repo-local drift fixes narrow. This skill adds the local contract for when a plan is retained, where it lives, how numbered files are split, what language they use, and what must stay outside the execution loop. ## When to use -- Writing or rewriting a repository-owned execution plan under `tmp/superpowers/`. -- Converting a monolithic plan into the local multi-file plan structure. +- Writing or rewriting a retained repository-owned execution plan under `tmp/superpowers/` when the work is non-banal. +- Retaining a plan because the work crosses turns, spans multiple macro-categories, needs handoff, tracking, or provenance, or carries tradeoffs or uncertainties that should stay reviewable. +- Converting a monolithic or overgrown plan into the local numbered-plan structure. - Preparing a plan that will later be executed by `internal-executing-plans`. ## When not to use - General design or spec work under `tmp/superpowers/specs/`; use `obra-brainstorming` when that workflow is relevant. +- Clear, local, quick, or banal tasks whose next steps fit in chat. - Local execution with no retained plan artifact. - Imported or sync-managed planning assets; do not edit `obra-*` skills to impose this policy. -## Local plan contract +## Local retained-plan contract -- Create or reuse a task folder named `tmp/superpowers//`. -- Keep active execution plans in multiple numbered Markdown files by macro-category, for example `01-contesto-e-vincoli.md`, `02-implementazione.md`, and `03-validazione.md`. +- Create or reuse a retained plan folder under `tmp/superpowers//` only when the plan needs to survive the current turn. +- Keep planning ephemeral in chat when the task is clear, local, quick, or banal. +- Retain a plan only when at least one of these is true: the work crosses turns, spans multiple macro-categories, needs handoff, tracking, or provenance, or includes tradeoffs or uncertainties that should stay reviewable. +- Use a single numbered file such as `01-implementazione.md` when the work has one macro-category. +- Use multiple numbered Markdown files by macro-category, for example `01-contesto-e-vincoli.md`, `02-implementazione.md`, and `03-validazione.md`, when the work spans more than one macro-category. - Do not keep one monolithic plan file when the work spans multiple macro-categories. - Write those plan files in Italian by default unless the user explicitly asks for another language. - Keep unresolved questions, doubts, and user decisions in `dubbi-e-domande.md`. - `dubbi-e-domande.md` is not an execution-plan file and must stay outside the plan-and-apply loop. +## Numbered-file shape + +- Optimize retained plan files for scanability and decision review rather than exhaustive prose. +- Prefer explicit headings and short bullets; avoid long paragraphs. +- Keep rationales brief and avoid duplicating context already captured in `AGENTS.md`, `.github/copilot-instructions.md`, or neighboring repository-owned assets. +- `Obiettivo` +- `Logica scelta` +- `Assunzioni chiave` +- `Passi eseguibili` +- `Validazione` +- Keep each section to 5-7 bullets when practical. +- Keep bullets to 1-2 lines when practical. +- Make each executable step easy to challenge, verify, or remove without rewriting the whole file. + ## Relationship to OBRA - Use this skill first for repository-owned planning policy. @@ -38,23 +57,29 @@ Treat `obra-writing-plans` as imported depth and keep any repo-local drift fixes ## Workflow -1. Choose a clear task folder name under `tmp/superpowers/`. -2. Define the macro-categories first, then create one numbered plan file per category. -3. Keep each numbered file actionable and scoped to one macro-category. -4. Put open questions and decision requests only in `dubbi-e-domande.md`. -5. Keep executable next steps in the numbered plan files without mixing unresolved questions into them. +1. Decide first whether retained planning is justified or whether in-chat planning is enough. +2. Choose a clear task folder name under `tmp/superpowers/`. +3. Define the macro-categories first and choose the smallest numbered-file shape that fits the work. +4. Use a single `01-...md` file when one macro-category is enough, or create one numbered plan file per category when more than one macro-category exists. +5. Give each numbered file the shape above and keep every section compact. +6. Put open questions and decision requests only in `dubbi-e-domande.md`. +7. Keep executable next steps in the numbered plan files without mixing unresolved questions into them. ## Validation +- The plan exists only when retained planning is justified beyond the current turn. - The plan lives under `tmp/superpowers//`. -- There are `01-...`, `02-...`, `03-...` style plan files when more than one macro-category exists. +- A single `01-...` file is used when one macro-category is enough; `01-...`, `02-...`, `03-...` style plan files exist when more than one macro-category exists. - Plan files are in Italian unless the user asked otherwise. +- The numbered files follow the local shape contract with explicit headings and short bullets. - `dubbi-e-domande.md` exists when needed and remains separate from executable plan files. - The plan does not rely on imported `obra-*` skills as the policy owner; any repo-local drift fix stays narrow and subordinate to this wrapper. ## Common mistakes +- Creating a retained plan artifact for a clear, local, quick task that should stay in chat. - Writing the whole plan in one Markdown file. +- Writing long narrative paragraphs or duplicating canonical context instead of keeping the plan scannable. - Mixing executable checklist items with open questions. - Putting the plan under `docs/` instead of `tmp/superpowers/`. - Switching the whole repository to Italian instead of keeping the exception local to plan files. diff --git a/.github/skills/internal-writing-plans/agents/openai.yaml b/.github/skills/internal-writing-plans/agents/openai.yaml index d4618d5..b320be9 100644 --- a/.github/skills/internal-writing-plans/agents/openai.yaml +++ b/.github/skills/internal-writing-plans/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Internal Writing Plans" short_description: "Repo wrapper for numbered plan authoring" - default_prompt: "Use $internal-writing-plans to author repository-owned multi-file plans under tmp/superpowers with numbered phases and a separate dubbi-e-domande file." + default_prompt: "Use $internal-writing-plans to author retained repository-owned numbered plans under tmp/superpowers, using a single or multi-file shape as needed and a separate dubbi-e-domande file." diff --git a/AGENTS.md b/AGENTS.md index 44e036b..2574f07 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,7 +90,8 @@ This file is the stable entrypoint for the repository instruction architecture. - Transient planning, brainstorming, and other Superpowers-generated working files must not be written under `docs/`. - When such artifacts are needed inside this repository, write them under `tmp/superpowers/`. -- Repository-owned plan work under `tmp/superpowers/` should live in a task-specific folder named `tmp/superpowers//`. -- Keep active execution plans there as multiple numbered macro-category Markdown files, for example `01-contesto-e-vincoli.md`, `02-implementazione.md`, and `03-validazione.md`, instead of one monolithic plan document. +- Keep planning ephemeral in chat for clear, local, quick, or banal tasks. +- Create or reuse `tmp/superpowers//` only for retained repository-owned planning that must survive the current turn because the work is non-banal, crosses turns, spans macro-categories, needs handoff, tracking, or provenance, or preserves tradeoffs worth review. +- Keep retained execution plans as numbered Markdown files: 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 spans multiple macro-categories. - Keep unresolved questions, doubts, or user decisions in `dubbi-e-domande.md`; this file stays separate from executable plan files and remains outside the plan-and-apply loop. -- During execution, create matching `done-*` files, move completed items into them, remove completed items from the active source plan file, delete emptied numbered plan files, and continue through the remaining numbered plan files until the work is finished or a real blocker requires user input. +- During execution, create matching `done-*` files, move completed items into them, remove them from the active numbered source file, and continue through the remaining numbered plan files until the work is finished or a real blocker requires user input. diff --git a/tests/test_plan_policy_contract.py b/tests/test_plan_policy_contract.py index 213bc3d..e5a220c 100644 --- a/tests/test_plan_policy_contract.py +++ b/tests/test_plan_policy_contract.py @@ -14,6 +14,14 @@ def read_text(relative_path: str) -> str: return Path(relative_path).read_text(encoding="utf-8") +def assert_plan_policy_anchors(text: str) -> None: + assert PLAN_TASK_PATH in text + assert "01-...md" in text + assert "01-contesto-e-vincoli.md" in text + assert "dubbi-e-domande.md" in text + assert "done-*" in text + + def test_root_policy_files_define_repository_plan_defaults() -> None: agents_text = read_text("AGENTS.md") copilot_text = read_text(".github/copilot-instructions.md") @@ -22,23 +30,26 @@ def test_root_policy_files_define_repository_plan_defaults() -> None: "The default authoring language for repository artifacts is English" in agents_text ) - assert PLAN_TASK_PATH in agents_text - assert "01-contesto-e-vincoli.md" in agents_text + assert_plan_policy_anchors(agents_text) assert "Italian" in agents_text - assert "dubbi-e-domande.md" in agents_text - assert "done-*" in agents_text + assert "clear, local, quick, or banal tasks" in agents_text + assert "non-banal" in agents_text + assert "macro-categories" in agents_text assert "continue through the remaining numbered plan files" in agents_text + assert "`Obiettivo`" not in agents_text + assert "5-7 bullets when practical" not in agents_text assert ( "The default authoring language for repository artifacts is English" in copilot_text ) - assert PLAN_TASK_PATH in copilot_text - assert "01-contesto-e-vincoli.md" in copilot_text + assert_plan_policy_anchors(copilot_text) assert "Italian" in copilot_text - assert "dubbi-e-domande.md" in copilot_text - assert "done-*" in copilot_text + assert "retained planning is justified" in copilot_text + assert "`internal-writing-plans`" in copilot_text assert "continue through the remaining numbered plan files" in copilot_text + assert "`Obiettivo`" not in copilot_text + assert "5-7 bullets when practical" not in copilot_text def test_internal_planning_leader_prefers_repository_plan_wrappers() -> None: @@ -48,6 +59,8 @@ def test_internal_planning_leader_prefers_repository_plan_wrappers() -> None: assert "- `internal-executing-plans`" in planning_leader_text assert "prefer `internal-writing-plans`" in planning_leader_text assert "prefer `internal-executing-plans`" in planning_leader_text + assert "clear, local, quick, or banal tasks" in planning_leader_text + assert "retained execution plan" in planning_leader_text def test_plan_wrapper_skills_are_listed_in_ownership_map_and_inventory() -> None: @@ -76,14 +89,27 @@ def test_plan_wrapper_skills_define_local_plan_contracts() -> None: assert "## When to use" in writing_skill_text assert PLAN_TASK_PATH in writing_skill_text + assert "crosses turns" in writing_skill_text + assert "handoff, tracking, or provenance" in writing_skill_text assert "01-contesto-e-vincoli.md" in writing_skill_text assert "macro-category" in writing_skill_text assert "monolithic" in writing_skill_text assert "dubbi-e-domande.md" in writing_skill_text assert "Italian" in writing_skill_text + assert "## Local retained-plan contract" in writing_skill_text + assert "## Numbered-file shape" in writing_skill_text + assert "scanability and decision review" in writing_skill_text + assert "`Obiettivo`" in writing_skill_text + assert "`Logica scelta`" in writing_skill_text + assert "`Assunzioni chiave`" in writing_skill_text + assert "`Passi eseguibili`" in writing_skill_text + assert "`Validazione`" in writing_skill_text + assert "5-7 bullets when practical" in writing_skill_text + assert "1-2 lines when practical" in writing_skill_text assert "outside the plan-and-apply loop" in writing_skill_text assert "## When to use" in executing_skill_text + assert "retained numbered plans" in executing_skill_text assert "done-.md" in executing_skill_text assert "dubbi-e-domande.md" in executing_skill_text assert "move it into the matching `done-*` file" in executing_skill_text @@ -94,10 +120,18 @@ def test_plan_wrapper_skills_define_local_plan_contracts() -> None: def test_plan_wrapper_skills_ship_openai_metadata() -> None: - for skill_name in PLAN_SKILL_PATHS: - metadata_text = read_text(f".github/skills/{skill_name}/agents/openai.yaml") + writing_metadata_text = read_text( + ".github/skills/internal-writing-plans/agents/openai.yaml" + ) + executing_metadata_text = read_text( + ".github/skills/internal-executing-plans/agents/openai.yaml" + ) + for metadata_text in (writing_metadata_text, executing_metadata_text): assert "interface:" in metadata_text assert "display_name:" in metadata_text assert "short_description:" in metadata_text - assert f"${skill_name}" in metadata_text + + assert "$internal-writing-plans" in writing_metadata_text + assert "single or multi-file shape as needed" in writing_metadata_text + assert "$internal-executing-plans" in executing_metadata_text From 37a1fbda0fbe481ba048b09f91995cc72054d9de Mon Sep 17 00:00:00 2001 From: Diego Mauricio Lagos Date: Tue, 21 Apr 2026 23:38:03 +0200 Subject: [PATCH 3/6] Refactor skills and documentation for clarity and consistency - Updated internal-agent-sync-external-resources skill documentation to improve clarity in asset management steps. - Enhanced internal-change-impact-analysis skill with additional self-questioning prompts and validation criteria. - Revised internal-cloud-policy skill to clarify usage boundaries and mandatory rules. - Improved internal-code-review skill with clearer escalation rules and validation requirements. - Updated anti-pattern references for various languages (Bash, Java, Node.js, Python, Terraform) to enhance clarity and consistency. - Enhanced internal-copilot-audit skill to specify updated script paths for catalog consistency checks. - Improved internal-docker skill documentation for mandatory rules and validation steps. - Clarified internal-github-action-composite and internal-github-actions skills with better relationship descriptions and mandatory rules. - Updated internal-project skills (Java, Node.js, Python) with clearer project-specific guidance and validation steps. - Enhanced internal-script skills (Bash, Python) with specific guidance for standalone scripts and validation requirements. - Refined internal-terraform skill documentation for mandatory rules and validation steps. - Updated markdownlint configuration to ignore generated tooling state and preserve upstream assets. - Added tests for markdownlint configuration and validation entrypoints to ensure correctness and coverage. --- .github/CHANGELOG.md | 31 ++++++++++++++++++ .github/DEPRECATION.md | 6 ++++ .github/agents/README.md | 5 +++ .../agents/internal-critical-master.agent.md | 2 +- .../internal-delivery-operator.agent.md | 2 +- .github/copilot-code-review-instructions.md | 12 +++++++ .../copilot-commit-message-instructions.md | 4 +++ .../internal-bash.instructions.md | 4 +++ .../internal-docker.instructions.md | 3 ++ ...al-github-action-composite.instructions.md | 2 ++ .../internal-github-actions.instructions.md | 3 ++ .../internal-java.instructions.md | 4 +++ .../internal-json.instructions.md | 4 +++ .../internal-lambda.instructions.md | 6 ++++ .../internal-makefile.instructions.md | 8 +++-- .../internal-markdown.instructions.md | 4 +++ .../internal-nodejs.instructions.md | 4 +++ .../internal-python.instructions.md | 4 +++ .../internal-terraform.instructions.md | 3 ++ .../internal-yaml.instructions.md | 3 ++ .../internal-planning-kickoff.prompt.md | 3 ++ .github/prompts/internal-pre-mortem.prompt.md | 3 ++ .../prompts/internal-review-kickoff.prompt.md | 3 ++ .github/prompts/internal-sync-plan.prompt.md | 3 ++ .github/scripts/github_catalog_validation.py | 10 ++++-- .github/security-baseline.md | 9 ++++++ .../internal-agent-development/SKILL.md | 6 ++-- .../references/example-transformations.md | 24 +++++++------- .../SKILL.md | 8 ++--- .../internal-change-impact-analysis/SKILL.md | 4 +++ .../references/analysis-dimensions.md | 1 + .github/skills/internal-cloud-policy/SKILL.md | 4 +++ .github/skills/internal-code-review/SKILL.md | 5 +++ .../references/anti-patterns-bash.md | 4 +++ .../references/anti-patterns-java.md | 4 +++ .../references/anti-patterns-nodejs.md | 4 +++ .../references/anti-patterns-python.md | 4 +++ .../references/anti-patterns-terraform.md | 4 +++ .../skills/internal-copilot-audit/SKILL.md | 2 +- .github/skills/internal-docker/SKILL.md | 3 ++ .../internal-github-action-composite/SKILL.md | 3 ++ .../skills/internal-github-actions/SKILL.md | 2 ++ .../references/auth-snippets.md | 6 ++++ .../references/language-cues.md | 2 +- .github/skills/internal-pr-editor/SKILL.md | 8 +++++ .github/skills/internal-project-java/SKILL.md | 6 ++++ .../skills/internal-project-nodejs/SKILL.md | 6 ++++ .../skills/internal-project-python/SKILL.md | 7 ++++ .github/skills/internal-script-bash/SKILL.md | 3 ++ .../skills/internal-script-python/SKILL.md | 7 ++++ .github/skills/internal-terraform/SKILL.md | 4 +++ .../references/decision-guide.md | 5 ++- .markdownlint-cli2.jsonc | 5 +++ Makefile | 2 +- tests/github/scripts/test_cli_entrypoints.py | 1 + tests/test_markdownlint_config.py | 32 +++++++++++++++++++ tests/test_validation_entrypoints_contract.py | 23 +++++++++++++ 57 files changed, 315 insertions(+), 29 deletions(-) create mode 100644 tests/test_markdownlint_config.py create mode 100644 tests/test_validation_entrypoints_contract.py 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/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/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/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