Skip to content

Commit 130ebcf

Browse files
frjcompvscodeCopilot
authored
Extend Copilot instructions and reusable skills (#644)
* docs: extend copilot instructions and skills --------- Co-authored-by: vscode <vscode@vscode.com> Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
1 parent a03b6f5 commit 130ebcf

9 files changed

Lines changed: 536 additions & 5 deletions

‎.github/AGENTS.md‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
# Pipeleek Copilot Agent Modes
2+
3+
This document defines maintainer-oriented execution modes for Copilot work in this repository.
4+
5+
## command-implementation
6+
7+
### When to use
8+
9+
Use when implementing or modifying an existing command and you need the repository-standard command structure.
10+
11+
### Inputs required
12+
13+
- Touched command file paths.
14+
- Flag-to-config key bindings.
15+
- Required key list and validator expectations.
16+
- Parent command registration path and expected CLI behavior.
17+
18+
### Expected outputs
19+
20+
- Command follows `config.NewCommandSetup` and current repository conventions.
21+
- Required keys validated.
22+
- Values read via unified config getters.
23+
- Parent command registration, tests, and docs are updated when applicable.
24+
25+
### Validation checklist
26+
27+
1. Run focused unit tests for touched command packages.
28+
2. Confirm command is registered in the expected parent tree.
29+
3. Confirm no direct `cmd.Flags().Get*` reads remain in touched execution paths.
30+
31+
## command-coverage
32+
33+
### When to use
34+
35+
Use for requests that affect "all commands" under a platform.
36+
37+
### Inputs required
38+
39+
- Platform root path under `internal/cmd/<platform>/`.
40+
- Requested behavior change to apply.
41+
- Any explicit exclusions from maintainers.
42+
43+
### Expected outputs
44+
45+
- Recursive command tree discovered under `internal/cmd/<platform>/`.
46+
- Scan and non-scan commands updated, including nested children.
47+
- No in-scope command directories skipped.
48+
49+
### Validation checklist
50+
51+
1. Spot-check command directories under the target platform.
52+
2. Verify nested command groups are covered or explicitly marked not applicable.
53+
3. Run targeted tests for multiple affected command groups.
54+
55+
## docs-sync
56+
57+
### When to use
58+
59+
Use when flags, config keys, or command semantics are updated.
60+
61+
### Inputs required
62+
63+
- Changed command files and affected flags.
64+
- Changed config keys and inheritance impact.
65+
- Affected docs sections and examples.
66+
67+
### Expected outputs
68+
69+
- docs/introduction/configuration.md updated if key usage changed.
70+
- User-facing guides updated where behavior or examples changed.
71+
- Generated config output expectations reviewed.
72+
73+
### Validation checklist
74+
75+
1. Verify docs examples match command flags and key names.
76+
2. Verify links and section references resolve.
77+
3. Confirm stale flag references were removed from touched docs.
78+
79+
## new-command
80+
81+
### When to use
82+
83+
Use when adding a new CLI command or subcommand.
84+
Apply the `command-implementation` mode as the baseline, then add the creation-specific work in this mode.
85+
86+
### Inputs required
87+
88+
- Target platform and command path under `internal/cmd/<platform>/`.
89+
- Required flags and config keys.
90+
- Behavior intent and output expectations.
91+
92+
### Expected outputs
93+
94+
- New command added with Cobra wiring and consistent flag naming.
95+
- Command uses `config.NewCommandSetup` with bindings, required keys, and validators.
96+
- Unit tests and e2e tests added or updated for command behavior.
97+
- Each flag defined on the new command is covered by at least one useful e2e test that asserts behavior.
98+
- Documentation updated for flags/config keys and usage examples.
99+
100+
### Validation checklist
101+
102+
1. Confirm command is registered in the correct parent command tree.
103+
2. Confirm config bindings, required keys, and validators are complete.
104+
3. Confirm unit tests and e2e tests for the new command path pass.
105+
4. Confirm each flag defined on the new command has at least one behavior-asserting e2e test.
106+
5. Confirm docs and configuration references are synchronized.
107+
108+
## pr-review-fixes
109+
110+
### When to use
111+
112+
Use when a pull request has review comments that require code changes and thread resolution.
113+
114+
### Inputs required
115+
116+
- Active PR context and changed files.
117+
- Review comments/threads to address.
118+
- Any explicit reviewer constraints or requested behavior.
119+
120+
### Expected outputs
121+
122+
- Review feedback converted into concrete code changes.
123+
- Requested behavior and edge cases addressed in code/tests.
124+
- Response summary maps each fix to the corresponding review thread.
125+
126+
### Validation checklist
127+
128+
1. Fetch and triage open review comments before editing.
129+
2. Apply fixes with minimal behavioral regression risk.
130+
3. Run focused tests for touched areas.
131+
4. Confirm each addressed thread has a clear resolution note.
132+
133+
## pr-actions-failures-debug
134+
135+
### When to use
136+
137+
Use when PR status checks fail and maintainers need local reproduction, diagnosis, and fixes.
138+
139+
### Inputs required
140+
141+
- Failing workflow/check names and failure logs.
142+
- PR branch diff context.
143+
- Local commands needed to reproduce failing jobs.
144+
145+
### Expected outputs
146+
147+
- Root cause identified for each failing check.
148+
- Local reproduction command(s) documented.
149+
- Minimal fix set applied and validated locally.
150+
- Follow-up risk or non-reproducible gaps explicitly noted.
151+
152+
### Validation checklist
153+
154+
1. Extract failing checks and logs before patching.
155+
2. Reproduce failure locally with the closest equivalent command.
156+
3. Apply fix and rerun relevant local validation.
157+
4. Report what passed, what remains unverified, and why.

‎.github/SKILLS/command-coverage.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Skill: Recursive Platform Command Coverage
2+
3+
## When to use
4+
5+
Use this skill when a request targets all commands for a platform or a broad platform-wide behavior.
6+
7+
## Inputs required
8+
9+
- Platform root under `internal/cmd/<platform>/`.
10+
- Change criteria (what must be updated across commands).
11+
- Any exclusions explicitly requested by maintainers.
12+
13+
## Procedure
14+
15+
1. Enumerate command files recursively under the platform directory.
16+
2. Group commands by command tree (for example: scan, renovate/*, runners/*).
17+
3. Identify all run entrypoints impacted by the requested change.
18+
4. Apply updates consistently across scan and non-scan commands.
19+
5. Verify nested command groups were not skipped.
20+
21+
## Expected outputs
22+
23+
1. Full recursive platform scope is covered unless exclusions are explicitly provided.
24+
2. Scan and non-scan command trees receive the requested update consistently.
25+
3. Coverage is reported by command groups in the implementation summary.
26+
27+
## Acceptance checklist
28+
29+
- All in-scope command groups are touched or explicitly marked not applicable.
30+
- No partial rollout to only scan commands when broader scope was requested.
31+
- Follow-up tests cover more than one command group when possible.
32+
33+
## Non-goals
34+
35+
1. Do not assume exclusions without explicit maintainer input.
36+
2. Do not stop at top-level command files if nested groups exist.

‎.github/SKILLS/command-implementation.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Skill: Command Implementation Guidelines
2+
3+
## When to use
4+
5+
Use this skill when implementing or modifying a command in Pipeleek and you need to follow the repository-standard command shape.
6+
7+
Core rule: treat `config.NewCommandSetup` and `WithFlagBindings` as a paired pattern. Do not use one without the other for consumed flags.
8+
9+
## Inputs required
10+
11+
- Target command file path under `internal/cmd/<platform>/`.
12+
- Parent command registration path.
13+
- Required flags and mapped config keys.
14+
- Expected behavior, validation needs, and test scope.
15+
16+
## Procedure
17+
18+
1. Place command logic under the appropriate `internal/cmd/<platform>/` path.
19+
2. Register the command under the correct parent command.
20+
3. Use `config.NewCommandSetup(cmd)` for bindings and validation.
21+
4. Map every consumed flag with `WithFlagBindings`.
22+
5. Use `RequireKeys` for mandatory values.
23+
6. Add validators for URL, token, thread count, or command-specific constraints as needed.
24+
7. Read values with config getters instead of direct flag access.
25+
8. Add or update focused tests for the touched command path.
26+
9. Update docs when flags, keys, or user-visible command behavior changes.
27+
28+
## Expected outputs
29+
30+
1. Command structure matches repository conventions.
31+
2. Config loading and validation follow the current standard.
32+
3. Tests cover the command path that changed.
33+
4. Docs stay aligned with command flags and config keys.
34+
35+
## Acceptance checklist
36+
37+
- Command is registered in the correct parent tree.
38+
- No `cmd.Flags().Get*` reads remain in command execution logic.
39+
- Required keys and validators are defined where needed.
40+
- Focused tests for touched command packages pass.
41+
- `docs/introduction/configuration.md` is updated when key or flag semantics change.
42+
43+
## Non-goals
44+
45+
1. Do not introduce legacy config binding patterns.
46+
2. Do not leave parent command registration incomplete.
47+
3. Do not skip tests or docs for user-visible command changes.

‎.github/SKILLS/docs-sync.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Skill: Docs and Config Synchronization
2+
3+
## When to use
4+
5+
Use this skill when adding/changing flags, config keys, or command behavior that affects user docs.
6+
7+
## Inputs required
8+
9+
- Changed command files.
10+
- Changed flags and key names.
11+
- Affected user-facing docs sections.
12+
13+
## Procedure
14+
15+
1. Update docs/introduction/configuration.md for new or changed config keys.
16+
2. Verify examples use current flags and key names.
17+
3. Check related guides for stale command invocations.
18+
4. Confirm command help output and docs examples are aligned.
19+
20+
## Expected outputs
21+
22+
1. Configuration docs reflect the current key model and inheritance behavior.
23+
2. Guides and examples use current command syntax.
24+
3. Stale flag or key references are removed from touched docs.
25+
26+
## Acceptance checklist
27+
28+
- Configuration docs match current key naming and inheritance behavior.
29+
- Guides reflect current command syntax.
30+
- No stale flags remain in updated sections.
31+
32+
## Non-goals
33+
34+
1. Do not rewrite unrelated documentation sections.
35+
2. Do not leave config or guide examples in a mixed old/new state.

‎.github/SKILLS/new-command.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# Skill: Creating a New Command
2+
3+
## When to use
4+
5+
Use this skill when implementing a new command or subcommand in the Pipeleek CLI.
6+
7+
This skill builds on `.github/SKILLS/command-implementation.md` and adds the extra requirements that are specific to creating a brand new command.
8+
9+
## Inputs required
10+
11+
- Target command path under `internal/cmd/<platform>/`.
12+
- Command name, purpose, and expected output.
13+
- Required flags and mapped config keys.
14+
- Validation requirements and test scope.
15+
16+
## Relationship to command-implementation
17+
18+
Apply `.github/SKILLS/command-implementation.md` as the baseline for command structure, config binding, validators, and docs sync.
19+
Use this skill for the additional creation-specific work below.
20+
21+
## Procedure
22+
23+
1. Add the command file in the appropriate `internal/cmd/<platform>/` directory.
24+
2. Register the new command under the correct parent command.
25+
3. Add unit tests for the command path.
26+
4. Add e2e tests for the command path.
27+
5. Ensure each flag defined on the new command has at least one useful e2e test that asserts behavior.
28+
6. Update docs and config guidance when flags/keys are added.
29+
30+
## Expected outputs
31+
32+
1. New command is accessible via the intended command path.
33+
2. Base command implementation follows repository standards.
34+
3. Unit tests and e2e tests cover the new command behavior.
35+
4. Each command-defined flag is exercised by at least one behavior-asserting e2e test.
36+
5. User-facing docs reflect the new command syntax and config keys.
37+
38+
## Acceptance checklist
39+
40+
- Command is discoverable in help output under the expected parent.
41+
- `command-implementation` requirements are satisfied.
42+
- Unit tests for the touched command path pass.
43+
- E2E tests for the touched command path pass.
44+
- Each flag defined on the new command has at least one useful e2e test that asserts behavior.
45+
- `docs/introduction/configuration.md` is updated when key/flag semantics change.
46+
47+
## Non-goals
48+
49+
1. Do not mix legacy config binding patterns in the new command.
50+
2. Do not skip command registration in parent command trees.
51+
3. Do not leave docs or tests unaddressed for user-visible command additions.

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

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Skill: Debug PR Actions Failures and Apply Fixes Locally
2+
3+
## When to use
4+
5+
Use this skill when GitHub Actions checks fail on a PR and maintainers need local diagnosis and fixes.
6+
7+
## Inputs required
8+
9+
- Failing check names and job/workflow logs.
10+
- PR diff context and touched files.
11+
- Local equivalents of CI commands (test, lint, build, docs).
12+
13+
## Procedure
14+
15+
1. Collect failing checks and extract primary error messages.
16+
2. Identify likely failure class: test failure, lint failure, build failure, docs/generation drift, or environment mismatch.
17+
3. Reproduce each failure locally using closest equivalent command.
18+
4. Apply minimal fixes to remove root cause.
19+
5. Rerun relevant local checks after each fix.
20+
6. Record which failures were reproduced, fixed, and verified.
21+
7. If not reproducible, document likely causes and confidence level.
22+
23+
## Expected outputs
24+
25+
1. Root cause identified for each failing check where possible.
26+
2. Minimal patch set addresses failing checks.
27+
3. Local validation commands and outcomes are documented.
28+
4. Remaining risk is called out for non-reproducible failures.
29+
30+
## Acceptance checklist
31+
32+
- Failing checks/log evidence reviewed before code changes.
33+
- At least one local reproduction command attempted per failing class.
34+
- Post-fix local checks pass for impacted areas.
35+
- Final summary includes fixed items and unresolved risks.
36+
37+
## Non-goals
38+
39+
1. Do not guess fixes without correlating to failure logs.
40+
2. Do not ignore non-reproducible failures; document them explicitly.
41+
3. Do not perform unrelated cleanups while stabilizing failing checks.

0 commit comments

Comments
 (0)