Skip to content

Commit 20d7351

Browse files
committed
Chore: Update agents.md / skills
1 parent 93a7c93 commit 20d7351

4 files changed

Lines changed: 88 additions & 15 deletions

File tree

‎.claude/skills/feature-review/SKILL.md‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ existing patterns and not introduce new abstractions unless the same problem exi
2323

2424
Find every file that belongs to the feature. Don't stop at the obvious View/ViewModel — most bugs and
2525
inconsistencies hide in the integration points (settings, profiles, group settings, export, command line,
26-
documentation). [references/integration-map.md](references/integration-map.md) lists where a tool lives and
26+
run command, "open in other tool" navigation, documentation). [references/integration-map.md](references/integration-map.md) lists where a tool lives and
2727
how to find all touch points (`git grep -l "<ApplicationName>" -- Source Website` is a good start).
2828

2929
### 2. Understand how it works
@@ -38,6 +38,8 @@ Read the code in this order: model (business logic) → view model (state, comma
3838
view hide/visible, app close
3939
- Integrations: which settings it reads, which profile/group fields it uses, history lists, export formats,
4040
admin rights requirement, external dependencies (PowerShell, WebView2, external processes, APIs)
41+
- Entry points: how the tool is opened with a target or profile (run command `Ctrl+Shift+P`, `NavigationManager.Open`
42+
from other tools, profile panel, command line) and which other tools it sends data to
4143

4244
This section matters on its own: it lets the user verify that the reviewer understood the feature, and
4345
it is the basis for spotting what is missing. If something is unclear after reading the code, say so
@@ -62,10 +64,12 @@ Go through these areas. Skip an area if it doesn't apply, but say so in one line
6264
1. **Bugs and logic errors** — wrong results, unhandled exceptions, race conditions (async commands that can
6365
overlap, refresh vs. modify), cancellation that doesn't stop work, state flags that can get stuck
6466
(set without `try/finally`), stale data after an action, edge cases (empty input, IPv6, very large
65-
ranges, invalid/duplicate entries, no network adapter, no admin rights), wrong disposal / event handlers
66-
that are never unsubscribed (static events!).
67+
ranges, invalid/duplicate/overlapping entries, no network adapter, no admin rights), wrong disposal / event handlers
68+
that are never unsubscribed (static events!), status messages overwritten by a later event (e.g. a completion
69+
event after cancel or after an input error), exceptions in fire-and-forget `async Task` methods (`_ = Start()`)
70+
that leave flags set.
6771
2. **Consistency within the feature** — the same action behaving differently depending on where it is
68-
triggered (button vs. context menu vs. keyboard shortcut vs. profile), single vs. multi selection,
72+
triggered (button vs. context menu vs. keyboard shortcut vs. profile vs. run command / other tool), single vs. multi selection,
6973
texts/terms that differ inside the feature.
7074
3. **Consistency across the application** — compare with the features from step 3 and the conventions:
7175
layout and spacing, icons, button placement, header/status texts, context menu items and order,
@@ -75,12 +79,16 @@ Go through these areas. Skip an area if it doesn't apply, but say so in one line
7579
allocations in hot paths, repeated PowerShell/process calls) *and* in the UI (UI thread blocked, too many
7680
`Dispatcher.Invoke` calls per result, large collections updated item by item, `CanExecute` doing
7781
expensive work, missing virtualization in large grids, timers that keep running when the view is hidden).
78-
The UI has to stay smooth while a scan runs.
82+
The UI has to stay smooth while a scan runs. Estimate the worst-case duration with the default settings for a
83+
typical input (e.g. an empty /24): rounds per item (items ÷ concurrency) × timeout, for every probe — the slowest
84+
probe decides when a result and the progress appear. Also check synchronous work on the UI thread after the action
85+
(export, sorting, large `Clear`/`Add` loops).
7986
5. **Missing essentials** — functions a user would expect for this kind of tool, especially ones that
8087
similar tools in the app already have (export, copy, history, cancel, profile support, search/filter,
8188
multi-select actions, refresh, keyboard shortcuts). Separate small gaps (fix directly) from larger
8289
features (write an issue draft, see below).
83-
6. **Robustness and security** — input passed to PowerShell/command lines/processes without escaping,
90+
6. **Robustness and security** — input passed to PowerShell/command lines/processes without escaping (also values
91+
received from the network, e.g. hostnames in custom commands),
8492
credentials in logs or plain text, unvalidated input, behaviour without admin rights, behaviour when
8593
an external dependency (PuTTY, WebView2, API) is missing or fails.
8694
7. **Localization and texts** — hard-coded user-visible strings, strings used for multiple meanings,
@@ -144,7 +152,15 @@ the motivation, a proposed behaviour (UI + logic), and which existing feature it
144152

145153
### 7. After the report
146154

147-
Don't change code during the review. Ask the user which findings to fix. When fixing:
155+
Don't change code during the review. Ask the user which findings to fix.
156+
157+
When the user wants the work handed over (to another agent or for later), write the result to
158+
`.claude/reviews/<feature>.md` (kebab-case, e.g. `ip-scanner.md`; the folder is not committed). Write it as an
159+
implementation plan, not as a report: verified findings with `path:line`, the concrete fix, the work packages / PR
160+
order, decisions taken and still open, and what must be tested on Windows. Read existing files in `.claude/reviews/`
161+
and `.claude/plans/` for the area first — they record earlier decisions.
162+
163+
When fixing:
148164

149165
- Follow the conventions and keep the change minimal; extract shared helpers only when the same code
150166
already exists in two or more places.

‎.claude/skills/feature-review/references/conventions.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ report that too.
1717
- Layout
1818
- Export and history
1919
- Settings and profiles
20+
- Navigation and run command
2021
- PowerShell and external processes
2122
- Strings, docs and changelog
2223

@@ -98,6 +99,12 @@ Reference: `HostsFileEditorView.xaml`, `FirewallView.xaml`.
9899
`ICollectionView.DeferRefresh()` — the DataGrid accesses the view (selection / current item) while the
99100
items change, which throws "Cannot change or check the contents or Current position of CollectionView
100101
while Refresh is being deferred". Reference: `FirewallViewModel.Refresh`.
102+
Other users: `RunCommandViewModel.Suggestions`. Not yet used (same `Clear()` + `ForEach(Results.Add)` pattern on every
103+
refresh / auto refresh): `ConnectionsViewModel`, `ListenersViewModel`, `NeighborTableViewModel`,
104+
`HostsFileEditorViewModel` — report as a performance finding when reviewing them.
105+
- Don't use a `Reset` for results that are *appended* while a scan runs (IP Scanner, Port Scanner, Traceroute): with a
106+
sorted view every `Reset` re-sorts the whole list and the grid loses its selection / scroll position. Those tools buffer
107+
results and flush them with a `DispatcherTimer` (reference: `IPScannerViewModel.FlushResultsBuffer`).
101108

102109
## Dialogs and confirmations
103110

@@ -147,6 +154,25 @@ Reference: `HostsFileEditorView.xaml`, `FirewallView.xaml`.
147154
profile → group → settings. The same option should have the same label, default and validation in the
148155
settings page, the profile dialog and the group dialog.
149156

157+
## Navigation and run command
158+
159+
Reference: `NavigationManager`, `ApplicationRequest`, `IPScannerHostView.Open`, `RunCommandManager`.
160+
161+
- "Open in <other tool>" (context menus, buttons) calls `NavigationManager.Open(new ApplicationRequest(app) { Target = ... })`
162+
or a derived request with the tool's extra options (`PortScannerRequest.Ports`, `DNSLookupRequest`, `RDAPRequest`,
163+
`WakeOnLANRequest`, ...). Don't reference other view models or views directly.
164+
- The main window switches to the tool and calls `IApplicationRequestHandler.Open(request)` on its view; host views
165+
turn it into `AddTab(target or profile, start: request.Start)`. `Start = false` only fills in the input (the user can
166+
adjust options first). A request for a hidden application shows an error.
167+
- Every tool that accepts a target has a run command (`RunCommandManager.CreateCommands`: lowercase English command +
168+
aliases, translated syntax). The target is validated with the **same validator** as the tool's input field and the
169+
profile dialog (`ValidateTarget`); drift between these is a finding (see `.claude/reviews/run-command.md`).
170+
- A new tool option that is useful from the keyboard can become a run command argument/type (and a property on a derived
171+
request); update the command table in `Website/docs/run-command.md` and `TargetApplications` (suggestions for a target
172+
without a command) when the accepted targets change.
173+
- Values passed to another tool come from the result (e.g. hostname from DNS/NetBIOS). Pass a value the other tool can
174+
actually use (e.g. the IP address when the name is not resolvable by the app's DNS client).
175+
150176
## PowerShell and external processes
151177

152178
Reference: `Source/NETworkManager.Models/Firewall/Firewall.cs`.
@@ -161,6 +187,10 @@ Reference: `Source/NETworkManager.Models/Firewall/Firewall.cs`.
161187
- Cmdlet parameters like `-Name` / `-DisplayName` of the `*-NetFirewallRule` cmdlets accept wildcards. IDs and names
162188
not created by the application (e.g. Windows rules with `[x64]` in the name) must be matched exactly
163189
(e.g. `Get-NetFirewallRule | Where-Object Name -eq ...`), otherwise a different or no item is changed.
190+
- Custom commands (`CustomCommandInfo`, `PlaceholderHelper`, e.g. IP Scanner `{{IPAddress}}` / `{{Hostname}}`) insert
191+
values into a process command line. Values received from the network (DNS PTR, NetBIOS name, SNMP, HTTP) are
192+
untrusted: with `cmd.exe /c ...` characters like `&` or `|` run other commands. Only insert values that match the
193+
expected format (IP address, hostname regex).
164194

165195
## Strings, docs and changelog
166196

‎.claude/skills/feature-review/references/integration-map.md‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,8 @@ sort the hits into the categories below. Some names differ between places (e.g.
1616
| Area | Location | What to check there |
1717
|---|---|---|
1818
| Registration | `Source/NETworkManager.Models/ApplicationName.cs`, `ApplicationManager.cs` (name, icon, default visibility) | Icon matches the one used elsewhere for the tool |
19-
| Main window | `Source/NETworkManager/MainWindow.xaml.cs` — view creation (`case ApplicationName.X`), `OnViewHide`/`OnViewVisible`, `AddTab(...)` for "open in other tool" | View lifecycle: what keeps running when hidden |
19+
| Main window | `Source/NETworkManager/MainWindow.xaml.cs` — view creation (`case ApplicationName.X`), `OnViewHide`/`OnViewVisible`, `NavigationManager_ApplicationRequested` (passes requests to the view) | View lifecycle: what keeps running when hidden |
20+
| Navigation ("open in other tool") | `Source/NETworkManager/NavigationManager.cs` (`Open(request)`, `OpenSettings()`), `ApplicationRequest.cs` (`Target`, `Profile`, `Start` + derived requests like `PortScannerRequest`, `WakeOnLANRequest`), `IApplicationRequestHandler` implemented by `<Tool>HostView.xaml.cs` (`Open(request)` → `AddTab(...)`) | Tool accepts target **and** profile, honours `Start = false` (fill in only), context menu items of other tools use `NavigationManager.Open` |
2021
| Business logic | `Source/NETworkManager.Models/<Tool>/` or `Source/NETworkManager.Models/Network/<Tool>*.cs` (+ `*Options`, `*Info`, `*Args`) | Bugs, performance, cancellation, events |
2122
| View model | `Source/NETworkManager/ViewModels/<Tool>ViewModel.cs`, `<Tool>HostViewModel.cs` (tabs + profiles), `<Tool>SettingsViewModel.cs`, dialog view models | Commands, `CanExecute`, state flags, threading |
2223
| View | `Source/NETworkManager/Views/<Tool>View.xaml(.cs)`, `<Tool>HostView.xaml`, `<Tool>SettingsView.xaml`, `*ChildWindow.xaml` | Layout, context menus, bindings, shortcuts |
@@ -26,8 +27,8 @@ sort the hits into the categories below. Some names differ between places (e.g.
2627
| Profiles | `Source/NETworkManager.Profiles/ProfileInfo.cs` (`<Tool>_*` fields), `ProfileName.cs`, `ProfileViewManager.cs`, `Application/<Tool>.cs` (build session info from profile + group), `GroupInfo.cs` / `GroupViewName.cs` (group-level settings) | Profile field ↔ group inheritance ↔ settings fallback |
2728
| Profile UI | `Source/NETworkManager/ViewModels/ProfileViewModel.cs`, `Views/ProfileChildWindow.xaml` (tool tab), `Views/GroupChildWindow.xaml`, `ProfileDialogManager.cs` | Same fields, labels and validation in profile, group and settings |
2829
| Export | `Source/NETworkManager.Models/Export/ExportManager.<Tool>*.cs`, `ExportChildWindow` | Same columns/formats as similar tools |
29-
| Run command | `Source/NETworkManager/RunCommandManager.cs` | Arguments/placeholder accepted |
30-
| Documentation | `Source/NETworkManager.Documentation/DocumentationManager.cs` (help links), `Website/docs/application/<tool>.md`, `Website/docs/settings/*.md`, `Website/docs/commandline-arguments.md` | Docs match behaviour, defaults and shortcuts |
30+
| Run command | `Source/NETworkManager/RunCommandManager.cs` (command/aliases in `CreateCommands`, suggested apps per target kind in `TargetApplications`, target/argument validators in `ValidateTarget`, request in `CreateRequest`), parser in `Source/NETworkManager.Models/RunCommand/`, dialog `RunCommandViewModel` / `RunCommandChildWindow`, docs `Website/docs/run-command.md` | Same validator as the tool's input field and profile dialog; new options of the tool (e.g. a new input) are reachable via argument/type or deliberately not; command table in the docs matches |
31+
| Documentation | `Source/NETworkManager.Documentation/DocumentationManager.cs` (help links), `Website/docs/application/<tool>.md`, `Website/docs/settings/*.md`, `Website/docs/commandline-arguments.md`, `Website/docs/run-command.md` | Docs match behaviour, defaults and shortcuts |
3132
| Strings | `Source/NETworkManager.Localization/Resources/Strings.resx` (+ `Strings.Designer.cs`) | Only `Strings.resx` (English) is edited; other languages come from Transifex |
3233
| Styles | `Source/NETworkManager/Resources/Styles/*.xaml` (buttons, text blocks, tooltips, rectangles) | Shared styles used instead of local ones |
3334
| Helpers | `Source/NETworkManager.Utilities/`, `Source/NETworkManager.Utilities.WPF/`, `Source/NETworkManager.Converters/`, `Source/NETworkManager.Validators/`, `Source/NETworkManager/DialogHelper.cs` | Existing helper not reused / duplicated logic |
@@ -63,8 +64,10 @@ Cross-cutting areas:
6364

6465
- **Profiles and groups**: `NETworkManager.Profiles`, `ProfilesView`, `ProfileChildWindow`, `GroupChildWindow`,
6566
profile files, encryption (`Credentials*ChildWindow`), import (CSV/AD), filter/tags, profile panel in host views
66-
- **Main window and navigation**: `MainWindow.xaml(.cs)`, application list, run command (`CommandLineWindow`,
67-
`RunCommandManager`), tray, hotkeys, `StatusWindow`, `NotificationWindow`, welcome/upgrade dialogs
67+
- **Main window and navigation**: `MainWindow.xaml(.cs)`, application list, `NavigationManager` / `ApplicationRequest`,
68+
tray, hotkeys, `StatusWindow`, `NotificationWindow`, welcome/upgrade dialogs
69+
- **Run command** (`Ctrl+Shift+P`, global hotkey): `RunCommandManager`, `Models/RunCommand/` (parser), `RunCommandViewModel`,
70+
`RunCommandChildWindow`, docs `run-command.md`; open items and earlier decisions in `.claude/reviews/run-command*.md`
6871
- **Export and dialogs**: `ExportManager`, `ExportChildWindow`, `DialogHelper`, message/confirmation child windows
6972
- **Settings infrastructure**: `SettingsManager` (load/save/upgrade), `LocalSettingsManager`, policies
7073
(`PolicyManager`, `config.json.example`: settings managed by administrator)

‎AGENTS.md‎

Lines changed: 27 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -425,8 +425,12 @@ git diff
425425
3. Add the tool to `ApplicationName` and `ApplicationManager` (`Source/NETworkManager.Models/`), and show/hide it
426426
in `MainWindow.xaml.cs` (`OnApplicationViewVisible` / `OnApplicationViewHide`)
427427
4. Add it to the application list for existing users in `SettingsManager` (upgrade step)
428-
5. Add documentation in `Website/docs/application/` and map it in `DocumentationManager`
429-
6. Add localization strings and a changelog entry
428+
5. If the tool accepts a target or profile: implement `IApplicationRequestHandler` in its (host) view and add a run
429+
command in `RunCommandManager` (command, aliases, validator = the one of the input field; suggestions in
430+
`TargetApplications`), see [Navigation and Run Command](#navigation-and-run-command)
431+
6. Add documentation in `Website/docs/application/` (and the command table in `Website/docs/run-command.md`) and map it
432+
in `DocumentationManager`
433+
7. Add localization strings and a changelog entry
430434

431435
### Adding a New Setting
432436

@@ -486,6 +490,23 @@ git diff
486490
- **Groups**: Hierarchical organization
487491
- **Import/Export**: Profile sharing capabilities
488492

493+
### Navigation and Run Command
494+
495+
- **Open a tool from code**: `NavigationManager.Open(new ApplicationRequest(ApplicationName.X) { Target = ... })` or a
496+
derived request with extra options (`ApplicationRequest.cs`: `PortScannerRequest`, `DNSLookupRequest`, `RDAPRequest`,
497+
`WakeOnLANRequest`, `SubnetCalculatorRequest`, `LookupRequest`). Used for "open in other tool" context menus
498+
(e.g. IP Scanner, Traceroute, Network Interface) and the run command. `Profile` runs a profile, `Start = false` only fills in the input.
499+
- **MainWindow** switches to the tool and calls `IApplicationRequestHandler.Open(request)` on its view (host views call
500+
`AddTab(...)`). Don't reference other tools' views or view models directly.
501+
- **Run command** (`Ctrl+Shift+P`, title bar box, optional global hotkey): parser in
502+
`Source/NETworkManager.Models/RunCommand/`, commands, validation and requests in `Source/NETworkManager/RunCommandManager.cs`,
503+
dialog in `RunCommandViewModel` / `RunCommandChildWindow`, docs in `Website/docs/run-command.md`. The run command must
504+
validate a target with the same validator as the tool's input field and profile dialog.
505+
- **Large lists**: `ObservableRangeCollection<T>.ReplaceAll(items)` (`Source/NETworkManager.Controls/`) replaces all items
506+
with a single `Reset` notification. Use it for lists that are reloaded completely (e.g. Firewall rules, run command
507+
suggestions); not for results that are appended while a scan runs (those are buffered and flushed by a timer, see
508+
`IPScannerViewModel`).
509+
489510
### Embedded Tools Integration
490511

491512
- **Remote Desktop**: Native RDP using `AxMSTSCLib`, `AxMsRdpClient10NotSafeForScripting` and `WindowsFormsHost`
@@ -508,7 +529,10 @@ git diff
508529
11. **Check CI Status**: Both AppVeyor (main build) and GitHub Actions (CodeQL, website) must pass
509530
12. **Dependency Updates**: Dependabot automatically creates PRs for dependency updates
510531
13. **Conventions and reviews**: Read `.claude/skills/feature-review/references/conventions.md` before changing UI or ViewModel code; use the `feature-review` skill to review a whole tool
511-
14. **Windows only**: The solution can't be built on Linux/macOS (WPF, CsWinRT) — say so when changes couldn't be compiled, and list what needs to be tested on Windows
532+
14. **Plans and reviews**: Local (not committed) plans and review results are in `.claude/plans/` and `.claude/reviews/`
533+
(e.g. `.claude/reviews/ip-scanner.md`). Read the file for the area you work on first — it lists verified findings,
534+
decisions and open items
535+
15. **Windows only**: The solution can't be built on Linux/macOS (WPF, CsWinRT) — say so when changes couldn't be compiled, and list what needs to be tested on Windows
512536

513537
## Glossary
514538

0 commit comments

Comments
 (0)