feat: Enhance sync and planning skills with refined documentation

.github/DEPRECATION.md

@@ -1,29 +1,35 @@
 # 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).
 4. Provide a replacement asset when possible.
 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`.

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,9 +1,4 @@
-<!-- markdownlint-disable-file MD041 -->
-<!-- PR title format: <type>(<scope>): <summary> -->
-<!-- Examples: feat(skills): add reusable review workflow -->
-<!--           fix(workflows): tighten customization validation -->
-
-## Description
+# Description
 
 <!-- Describe what changed and why. -->
 

.github/agents/README.md

@@ -3,23 +3,27 @@
 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`.
 - Cross-repository baseline propagation: `internal-sync-global-copilot-configs-into-repo`.
 - 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.

.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
+- Recommended owner when the next step no longer belongs to the challenge lane

.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
+- Boundary note when the task no longer belongs to execution

.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.

.github/copilot-code-review-instructions.md

@@ -1,57 +1,68 @@
 # 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?"
 - If self-questioning changes your assessment, update the finding or downgrade its severity.
 - 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.
 - `Nit`: style, naming, or small convention inconsistencies.
 - `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.
 4. Test coverage for testable logic.
 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.

.github/copilot-commit-message-instructions.md

@@ -1,9 +1,11 @@
 # Commit Message Instructions
 
 ## Format
+
 `<type>(<scope>): <summary>`
 
 ## 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`

.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/<clear-action-or-task-name>/`.
-- 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/<clear-action-or-task-name>/` 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
 

.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 <script>.sh`
 - `shellcheck -s bash <script>.sh` (if available)

.github/instructions/internal-docker.instructions.md

@@ -6,6 +6,7 @@ applyTo: "**/Dockerfile,**/Dockerfile.*,**/*.dockerfile,**/.dockerignore,**/dock
 # Docker Instructions
 
 ## Baseline rules
+
 - Pin base and runtime images by digest and keep a nearby human-readable tag or version reference.
 - Prefer multi-stage builds when build tooling is not needed at runtime.
 - Run containers as a non-root user unless a documented exception is required.
@@ -14,10 +15,12 @@ applyTo: "**/Dockerfile,**/Dockerfile.*,**/*.dockerfile,**/.dockerignore,**/dock
 - Avoid privileged mode, host networking, and broad bind mounts unless explicitly justified.
 
 ## Use the skill for deeper guidance
+
 - Load `.github/skills/internal-docker/SKILL.md` for Dockerfile patterns, Compose topology choices, common mistakes, and container-hardening detail.
 - Keep this instruction as the auto-loaded baseline; keep workflow depth and examples in the skill.
 
 ## Validation
+
 - Validate Dockerfile or Compose syntax when tooling is available.
 - Check that image references remain digest-pinned before merge.
 - Review the final runtime stage for unnecessary tooling, shells, or package managers.

.github/instructions/internal-github-action-composite.instructions.md

@@ -6,10 +6,12 @@ applyTo: "**/actions/**/action.y*ml"
 # Composite Action Instructions
 
 ## Scope
+
 - This instruction augments `.github/instructions/internal-github-actions.instructions.md`.
 - Keep only composite-specific rules here.
 
 ## Composite-specific rules
+
 - Define explicit `inputs` and `outputs`, and keep published names stable for existing callers.
 - Validate required values early and fail before the main logic runs.
 - Pass `${{ inputs.* }}` through `env:` before shell usage.

.github/instructions/internal-github-actions.instructions.md

@@ -6,6 +6,7 @@ applyTo: "**/workflows/**,**/actions/**/action.y*ml"
 # GitHub Actions Instructions
 
 ## Security baseline
+
 - Prefer OIDC over long-lived secrets.
 - Pin actions to full-length commit SHAs with adjacent release comments and upstream release URLs.
 - Pin `docker://` references and workflow container images by digest.
@@ -18,6 +19,7 @@ applyTo: "**/workflows/**,**/actions/**/action.y*ml"
 - Treat self-hosted runners as trusted infrastructure and scope them to the repositories, runner groups, and network access they actually need.
 
 ## Family baseline
+
 - Use clear English step names and deterministic outputs.
 - Set explicit `timeout-minutes` for workflows that could otherwise hang.
 - Set `concurrency` when jobs can conflict on a shared target.
@@ -35,6 +37,7 @@ applyTo: "**/workflows/**,**/actions/**/action.y*ml"
 - Path-specific instructions can use `excludeAgent: "code-review"` or `excludeAgent: "cloud-agent"` when workflow guidance must be scoped to one GitHub Copilot surface, but treat that as a deliberate optimization rather than a default requirement.
 
 ## Use the skill for deeper guidance
+
 - Load `.github/skills/internal-github-actions/SKILL.md` for workflow-vs-reusable-vs-composite decisions, reusable workflow templates, cache and artifact patterns, and workflow hardening checklists.
 - Keep this instruction lean because it is part of the source-managed baseline mirrored into consumer repositories; add new always-on GitHub Actions depth only when downstream reuse justifies that sync cost, and keep advanced patterns, examples, and decision support in the skill references.
 - Keep this instruction as the auto-loaded baseline; keep authoring depth and examples in the skill.