Extend Copilot instructions and reusable skills

.github/AGENTS.md

@@ -0,0 +1,157 @@
+# Pipeleek Copilot Agent Modes
+
+This document defines maintainer-oriented execution modes for Copilot work in this repository.
+
+## command-implementation
+
+### When to use
+
+Use when implementing or modifying an existing command and you need the repository-standard command structure.
+
+### Inputs required
+
+- Touched command file paths.
+- Flag-to-config key bindings.
+- Required key list and validator expectations.
+- Parent command registration path and expected CLI behavior.
+
+### Expected outputs
+
+- Command follows `config.NewCommandSetup` and current repository conventions.
+- Required keys validated.
+- Values read via unified config getters.
+- Parent command registration, tests, and docs are updated when applicable.
+
+### Validation checklist
+
+1. Run focused unit tests for touched command packages.
+2. Confirm command is registered in the expected parent tree.
+3. Confirm no direct `cmd.Flags().Get*` reads remain in touched execution paths.
+
+## command-coverage
+
+### When to use
+
+Use for requests that affect "all commands" under a platform.
+
+### Inputs required
+
+- Platform root path under `internal/cmd/<platform>/`.
+- Requested behavior change to apply.
+- Any explicit exclusions from maintainers.
+
+### Expected outputs
+
+- Recursive command tree discovered under `internal/cmd/<platform>/`.
+- Scan and non-scan commands updated, including nested children.
+- No in-scope command directories skipped.
+
+### Validation checklist
+
+1. Spot-check command directories under the target platform.
+2. Verify nested command groups are covered or explicitly marked not applicable.
+3. Run targeted tests for multiple affected command groups.
+
+## docs-sync
+
+### When to use
+
+Use when flags, config keys, or command semantics are updated.
+
+### Inputs required
+
+- Changed command files and affected flags.
+- Changed config keys and inheritance impact.
+- Affected docs sections and examples.
+
+### Expected outputs
+
+- docs/introduction/configuration.md updated if key usage changed.
+- User-facing guides updated where behavior or examples changed.
+- Generated config output expectations reviewed.
+
+### Validation checklist
+
+1. Verify docs examples match command flags and key names.
+2. Verify links and section references resolve.
+3. Confirm stale flag references were removed from touched docs.
+
+## new-command
+
+### When to use
+
+Use when adding a new CLI command or subcommand.
+Apply the `command-implementation` mode as the baseline, then add the creation-specific work in this mode.
+
+### Inputs required
+
+- Target platform and command path under `internal/cmd/<platform>/`.
+- Required flags and config keys.
+- Behavior intent and output expectations.
+
+### Expected outputs
+
+- New command added with Cobra wiring and consistent flag naming.
+- Command uses `config.NewCommandSetup` with bindings, required keys, and validators.
+- Unit tests and e2e tests added or updated for command behavior.
+- Each flag defined on the new command is covered by at least one useful e2e test that asserts behavior.
+- Documentation updated for flags/config keys and usage examples.
+
+### Validation checklist
+
+1. Confirm command is registered in the correct parent command tree.
+2. Confirm config bindings, required keys, and validators are complete.
+3. Confirm unit tests and e2e tests for the new command path pass.
+4. Confirm each flag defined on the new command has at least one behavior-asserting e2e test.
+5. Confirm docs and configuration references are synchronized.
+
+## pr-review-fixes
+
+### When to use
+
+Use when a pull request has review comments that require code changes and thread resolution.
+
+### Inputs required
+
+- Active PR context and changed files.
+- Review comments/threads to address.
+- Any explicit reviewer constraints or requested behavior.
+
+### Expected outputs
+
+- Review feedback converted into concrete code changes.
+- Requested behavior and edge cases addressed in code/tests.
+- Response summary maps each fix to the corresponding review thread.
+
+### Validation checklist
+
+1. Fetch and triage open review comments before editing.
+2. Apply fixes with minimal behavioral regression risk.
+3. Run focused tests for touched areas.
+4. Confirm each addressed thread has a clear resolution note.
+
+## pr-actions-failures-debug
+
+### When to use
+
+Use when PR status checks fail and maintainers need local reproduction, diagnosis, and fixes.
+
+### Inputs required
+
+- Failing workflow/check names and failure logs.
+- PR branch diff context.
+- Local commands needed to reproduce failing jobs.
+
+### Expected outputs
+
+- Root cause identified for each failing check.
+- Local reproduction command(s) documented.
+- Minimal fix set applied and validated locally.
+- Follow-up risk or non-reproducible gaps explicitly noted.
+
+### Validation checklist
+
+1. Extract failing checks and logs before patching.
+2. Reproduce failure locally with the closest equivalent command.
+3. Apply fix and rerun relevant local validation.
+4. Report what passed, what remains unverified, and why.

.github/SKILLS/command-coverage.md

@@ -0,0 +1,36 @@
+# Skill: Recursive Platform Command Coverage
+
+## When to use
+
+Use this skill when a request targets all commands for a platform or a broad platform-wide behavior.
+
+## Inputs required
+
+- Platform root under `internal/cmd/<platform>/`.
+- Change criteria (what must be updated across commands).
+- Any exclusions explicitly requested by maintainers.
+
+## Procedure
+
+1. Enumerate command files recursively under the platform directory.
+2. Group commands by command tree (for example: scan, renovate/*, runners/*).
+3. Identify all run entrypoints impacted by the requested change.
+4. Apply updates consistently across scan and non-scan commands.
+5. Verify nested command groups were not skipped.
+
+## Expected outputs
+
+1. Full recursive platform scope is covered unless exclusions are explicitly provided.
+2. Scan and non-scan command trees receive the requested update consistently.
+3. Coverage is reported by command groups in the implementation summary.
+
+## Acceptance checklist
+
+- All in-scope command groups are touched or explicitly marked not applicable.
+- No partial rollout to only scan commands when broader scope was requested.
+- Follow-up tests cover more than one command group when possible.
+
+## Non-goals
+
+1. Do not assume exclusions without explicit maintainer input.
+2. Do not stop at top-level command files if nested groups exist.

.github/SKILLS/command-implementation.md

@@ -0,0 +1,47 @@
+# Skill: Command Implementation Guidelines
+
+## When to use
+
+Use this skill when implementing or modifying a command in Pipeleek and you need to follow the repository-standard command shape.
+
+Core rule: treat `config.NewCommandSetup` and `WithFlagBindings` as a paired pattern. Do not use one without the other for consumed flags.
+
+## Inputs required
+
+- Target command file path under `internal/cmd/<platform>/`.
+- Parent command registration path.
+- Required flags and mapped config keys.
+- Expected behavior, validation needs, and test scope.
+
+## Procedure
+
+1. Place command logic under the appropriate `internal/cmd/<platform>/` path.
+2. Register the command under the correct parent command.
+3. Use `config.NewCommandSetup(cmd)` for bindings and validation.
+4. Map every consumed flag with `WithFlagBindings`.
+5. Use `RequireKeys` for mandatory values.
+6. Add validators for URL, token, thread count, or command-specific constraints as needed.
+7. Read values with config getters instead of direct flag access.
+8. Add or update focused tests for the touched command path.
+9. Update docs when flags, keys, or user-visible command behavior changes.
+
+## Expected outputs
+
+1. Command structure matches repository conventions.
+2. Config loading and validation follow the current standard.
+3. Tests cover the command path that changed.
+4. Docs stay aligned with command flags and config keys.
+
+## Acceptance checklist
+
+- Command is registered in the correct parent tree.
+- No `cmd.Flags().Get*` reads remain in command execution logic.
+- Required keys and validators are defined where needed.
+- Focused tests for touched command packages pass.
+- `docs/introduction/configuration.md` is updated when key or flag semantics change.
+
+## Non-goals
+
+1. Do not introduce legacy config binding patterns.
+2. Do not leave parent command registration incomplete.
+3. Do not skip tests or docs for user-visible command changes.

.github/SKILLS/docs-sync.md

@@ -0,0 +1,35 @@
+# Skill: Docs and Config Synchronization
+
+## When to use
+
+Use this skill when adding/changing flags, config keys, or command behavior that affects user docs.
+
+## Inputs required
+
+- Changed command files.
+- Changed flags and key names.
+- Affected user-facing docs sections.
+
+## Procedure
+
+1. Update docs/introduction/configuration.md for new or changed config keys.
+2. Verify examples use current flags and key names.
+3. Check related guides for stale command invocations.
+4. Confirm command help output and docs examples are aligned.
+
+## Expected outputs
+
+1. Configuration docs reflect the current key model and inheritance behavior.
+2. Guides and examples use current command syntax.
+3. Stale flag or key references are removed from touched docs.
+
+## Acceptance checklist
+
+- Configuration docs match current key naming and inheritance behavior.
+- Guides reflect current command syntax.
+- No stale flags remain in updated sections.
+
+## Non-goals
+
+1. Do not rewrite unrelated documentation sections.
+2. Do not leave config or guide examples in a mixed old/new state.

.github/SKILLS/new-command.md

@@ -0,0 +1,51 @@
+# Skill: Creating a New Command
+
+## When to use
+
+Use this skill when implementing a new command or subcommand in the Pipeleek CLI.
+
+This skill builds on `.github/SKILLS/command-implementation.md` and adds the extra requirements that are specific to creating a brand new command.
+
+## Inputs required
+
+- Target command path under `internal/cmd/<platform>/`.
+- Command name, purpose, and expected output.
+- Required flags and mapped config keys.
+- Validation requirements and test scope.
+
+## Relationship to command-implementation
+
+Apply `.github/SKILLS/command-implementation.md` as the baseline for command structure, config binding, validators, and docs sync.
+Use this skill for the additional creation-specific work below.
+
+## Procedure
+
+1. Add the command file in the appropriate `internal/cmd/<platform>/` directory.
+2. Register the new command under the correct parent command.
+3. Add unit tests for the command path.
+4. Add e2e tests for the command path.
+5. Ensure each flag defined on the new command has at least one useful e2e test that asserts behavior.
+6. Update docs and config guidance when flags/keys are added.
+
+## Expected outputs
+
+1. New command is accessible via the intended command path.
+2. Base command implementation follows repository standards.
+3. Unit tests and e2e tests cover the new command behavior.
+4. Each command-defined flag is exercised by at least one behavior-asserting e2e test.
+5. User-facing docs reflect the new command syntax and config keys.
+
+## Acceptance checklist
+
+- Command is discoverable in help output under the expected parent.
+- `command-implementation` requirements are satisfied.
+- Unit tests for the touched command path pass.
+- E2E tests for the touched command path pass.
+- Each flag defined on the new command has at least one useful e2e test that asserts behavior.
+- `docs/introduction/configuration.md` is updated when key/flag semantics change.
+
+## Non-goals
+
+1. Do not mix legacy config binding patterns in the new command.
+2. Do not skip command registration in parent command trees.
+3. Do not leave docs or tests unaddressed for user-visible command additions.

.github/SKILLS/pr-actions-failures-debug.md

@@ -0,0 +1,41 @@
+# Skill: Debug PR Actions Failures and Apply Fixes Locally
+
+## When to use
+
+Use this skill when GitHub Actions checks fail on a PR and maintainers need local diagnosis and fixes.
+
+## Inputs required
+
+- Failing check names and job/workflow logs.
+- PR diff context and touched files.
+- Local equivalents of CI commands (test, lint, build, docs).
+
+## Procedure
+
+1. Collect failing checks and extract primary error messages.
+2. Identify likely failure class: test failure, lint failure, build failure, docs/generation drift, or environment mismatch.
+3. Reproduce each failure locally using closest equivalent command.
+4. Apply minimal fixes to remove root cause.
+5. Rerun relevant local checks after each fix.
+6. Record which failures were reproduced, fixed, and verified.
+7. If not reproducible, document likely causes and confidence level.
+
+## Expected outputs
+
+1. Root cause identified for each failing check where possible.
+2. Minimal patch set addresses failing checks.
+3. Local validation commands and outcomes are documented.
+4. Remaining risk is called out for non-reproducible failures.
+
+## Acceptance checklist
+
+- Failing checks/log evidence reviewed before code changes.
+- At least one local reproduction command attempted per failing class.
+- Post-fix local checks pass for impacted areas.
+- Final summary includes fixed items and unresolved risks.
+
+## Non-goals
+
+1. Do not guess fixes without correlating to failure logs.
+2. Do not ignore non-reproducible failures; document them explicitly.
+3. Do not perform unrelated cleanups while stabilizing failing checks.