ProxyWarden/.agent/skills/repository-orientation/SKILL.md

Skill: Repository Orientation

Когда использовать

Используй этот skill в начале любой нетривиальной задачи по ProxyWarden: аудит, рефакторинг, bugfix, изменение UI, изменение Windows service flow, изменение subscription/routing.

Цель

Быстро понять, где находится нужная логика, какие инварианты нельзя нарушать и какие проверки нужны перед финальным ответом.

Карта проекта

src/api/tauriCommands.ts        typed frontend API boundary
src/domain/types.ts             TypeScript DTO/domain mirror
src/app/App.tsx                 current UI orchestration, large file
src/app/readiness.ts            apply readiness/gating
src/app/viewModel.ts            view helpers
src/ui/*                        reusable UI components
src/styles/app.css              global/component CSS

src-tauri/src/models.rs         Rust domain models
src-tauri/src/validation.rs     input normalization/validation
src-tauri/src/storage.rs        JSON config/state storage
src-tauri/src/migration.rs      versioned storage adoption/migration
src-tauri/src/activity.rs       activity log
src-tauri/src/subscription.rs   subscription fetch/parse
src-tauri/src/component_catalog.rs pinned offline package catalog
src-tauri/src/component_inventory.rs exact native SCM/process/registry inventory
src-tauri/src/component_detection.rs component status mapping
src-tauri/src/component_packages.rs bundled/cache package plans
src-tauri/src/component_cutover.rs durable legacy cutover/rollback/cleanup
src-tauri/src/privileged_jobs.rs sealed one-shot elevation records
src-tauri/src/privileged_runtime.rs fixed native privileged actions
src-tauri/src/proxifyre_runtime.rs native ProxiFyre lifecycle
src-tauri/src/singbox_runtime.rs native sing-box lifecycle
src-tauri/src/adapters/*        ProxiFyre/sing-box/proxy router adapters
src-tauri/src/commands.rs       Tauri command layer, currently too large
src-tauri/tests/*               Rust tests
scripts/*.ps1                   build/release/QA tooling only

Source of truth

• Persistent app config/state: C:\ProgramData\ProxyWarden\config and state.
• config\components.json is legacy migration input only; live component truth comes from native inventory and verified receipts.
• Current managed roots: C:\Program Files\ProxyWarden\components\ProxiFyre and ...\sing-box.
• Offline baseline: packaged component catalog; verified downloaded cache: C:\ProgramData\ProxyWarden\packages.
• Generated artifacts: C:\ProgramData\ProxyWarden\generated.
• Frontend state is not source of truth. It should represent backend state and pending UI edits.
• Component detection/runtime status should come from backend, not guessed in UI.

First-pass procedure

1. Identify whether the task is backend, UI, security, Windows service, subscription/routing, or testing/release.
2. Read the matching skill file.
3. Inspect the relevant source files listed above.
4. Determine whether the change crosses the Tauri boundary. If yes, update both Rust DTO/command and TypeScript wrapper/types.
5. Determine whether the change touches secrets, service control, generated configs, process execution, filesystem deletion, or network fetch. If yes, apply security checklist.
6. If the change touches install/service/elevation, trace privileged_jobs.rs/privileged_runtime.rs and the native component runtime. Do not introduce PowerShell runtime fallback.
7. If the change touches packaging or release tooling, run scripts/check-runtime-powershell-boundary.ps1 -CheckOnly.
8. Prefer small, isolated changes over broad rewrites.

Do not

• Do not treat App.tsx or commands.rs as the correct permanent architecture just because they currently contain lots of logic.
• Do not introduce a second storage system.
• Do not move service/install logic into frontend.
• Do not treat legacy components.json, fuzzy paths, or service name alone as ownership proof.
• Do not add .ps1, powershell.exe, pwsh, or generated script text to production Rust/Tauri/NSIS paths.
• Do not claim Windows service/elevation behavior is verified unless it was actually tested on Windows.

Output expectations

For code changes, final report should include:

• Changed files.
• User-visible behavior changes.
• Internal behavior changes.
• Tests/checks run.
• Known unverified areas.

Как отчитываться

Перед финальным ответом применить .agent/skills/communication-reporting/SKILL.md и .agent/checklists/communication.md.

Минимум для нетривиальной задачи:

• короткая сводка;
• таблица файлов Файл / Что изменилось / Зачем;
• важные места без пересказа каждой строки;
• что проверено;
• что не проверено;
• конкретные риски.