Skip to content

RULES.md

Latest commit

 

History

History
187 lines (145 loc) · 7.96 KB

RULES.md

File metadata and controls

187 lines (145 loc) · 7.96 KB
Raw

GeneralUpdate Skill Execution Rules

These rules apply to the root skill and every sub-skill. They target GeneralUpdate v10.5.0-rc.1 and are the final authority for generated guidance.

1. Rule Priority and Conflict Resolution

Apply rules in this order; a higher item overrides every lower item:

  1. Platform safety, privacy, and system instructions.
  2. The user's explicit scope, constraints, and requested response language.
  3. The v10.5.0-rc.1 API, package, security, and compilability rules in this file.
  4. The selected sub-skill workflow and framework-specific constraints.
  5. Agent-specific detail and presentation defaults.

Additional conflict rules:

  • Security and compilability override brevity and convenience.
  • Do not broaden the requested scenario. Ask only for information required to produce correct code; otherwise state a safe assumption.
  • For an active failure, diagnose with generalupdate-troubleshoot before generating replacement code. For Android, generalupdate-mobile owns the integration. For migrations, generalupdate-migration owns version mapping. If a new desktop integration also needs UI, run generalupdate-init before generalupdate-ui. Strategy and advanced skills supplement those owners.
  • Never combine incompatible desktop/mobile APIs or conflicting strategies.

2. Language Selection

Choose one natural language for the entire response:

  1. Honor an explicit language request.
  2. Otherwise, Chinese text in the request selects Chinese; an English-only request selects English.
  3. For mixed input, use the language carrying most of the user's intent. If tied, use the language of the latest complete sentence, then conversation context. Ask once only if the result remains genuinely ambiguous.
  4. Keep API names, identifiers, commands, paths, and required literals unchanged. They do not count as bilingual mixing.

Do not emit paired English/Chinese headings, explanations, comments, or checklists. The skill source may be bilingual; a generated response must not be.

3. Agent and Detail Adaptation

An explicit user format or detail request always wins. Otherwise:

  • Lightweight or unknown agent: concise answer, minimum runnable code, required commands, warnings, and verification steps.
  • Debugging agent or active failure: numbered diagnosis, evidence, smallest fix, targeted verification, then fallback checks.
  • Professional R&D agent: requirements, decisions, complete artifacts, deployment/security notes, and verification checklist.

All modes must preserve correctness, required configuration, known hazards, and executable verification. Detail adaptation may remove explanation, never required code or safety checks.

4. v10.5.0-rc.1 Technical Contract

Desktop API

  • Pin every GeneralUpdate desktop package to 10.5.0-rc.1.
  • Configure with UpdateRequest plus SetConfig(...), or with SetSource(updateUrl, appSecretKey), and start with LaunchAsync().
  • Use SetOption(...), Hooks<T>(), Strategy<T>(), and UseDiffPipeline(...) only as documented for v10.5.0-rc.1.
  • Never generate Configinfo or other legacy configuration syntax.
  • AppType is an enum: Client = 1, Upgrade = 2, OssClient = 3, OssUpgrade = 4.

Packages

  • Core integration: reference GeneralUpdate.Core.
  • Bowl integration: reference GeneralUpdate.Bowl only; do not reference Core and Bowl together in the same project.
  • Differential support is embedded in Core; never add GeneralUpdate.Differential.
  • Client and Upgrade package versions must match exactly.
  • Android uses the framework-specific package: GeneralUpdate.Avalonia.Android or GeneralUpdate.Maui.Android.

Events and Namespaces

  • GeneralUpdate.Core.Configuration: UpdateRequest, option and app-role types.
  • GeneralUpdate.Core.Download: update and multi-download event arguments.
  • GeneralUpdate.Core.Event: exception and progress event arguments.
  • Use MultiDownloadCompletedEventArgs.IsCompleted, never IsComplated.

Production Boundaries

  • Desktop updates use Client + Upgrade processes and a valid manifest.
  • Use four-part desktop versions such as 1.0.0.0.
  • Require HTTPS and strong non-hardcoded secrets for production examples.
  • Preserve UTF-8, absolute install paths, archive path validation, and platform-specific executable permissions.
  • Never present placeholders, omitted handlers, or pseudo-code as production-ready code. Clearly label any intentionally illustrative fragment.

5. Tool Calling Contract

Use tools only when they improve correctness. Use each agent's native function schema; never invent unsupported arguments. A conceptual call is:

{
  "tool": "allowed-tool-name",
  "input": {},
  "purpose": "one short sentence"
}

Limits and expected results:

  • One operation per call; batch only independent reads/searches.
  • At most 20 paths or 20 returned matches per call. Narrow and repeat instead of dumping large outputs.
  • Search query: non-empty, at most 500 characters.
  • Troubleshooting search: search.py "<query>" --domain issue|strategy -n <1..20> [--json].
  • Code generation: generate.py --framework <listed-value> --strategy <listed-value> plus only supported flags shown by generate.py --help.
  • Never place secrets in tool input. Do not perform writes until requirements and target paths are known.

Success output must identify the operation, relevant result/artifact paths, and verification status. Failure output must identify the failed operation and actionable error without exposing secrets. Do not fabricate a successful tool result.

6. Output Contract

Return only material needed for the selected scenario, in this order:

  1. Assumptions or missing required inputs.
  2. Reusable code and complete configuration.
  3. Exact integration/deployment steps.
  4. Scenario-specific warnings.
  5. Verification checklist.

Code must use official namespaces and APIs, include required event/error handling, and be internally consistent. Do not claim a build or runtime check passed unless it was actually executed; otherwise provide the exact command and mark it as pending.

7. Skill Market and Repository Compliance

  • Every skill has valid YAML frontmatter with a lowercase hyphenated name, a specific description, triggers, and only required allowed-tools.
  • Keep instructions portable across agents; vendor-specific enhancements must have a generic fallback.
  • Edit .claude/skills/, .claude/scripts/, and other documented source-of-truth paths, then synchronize cli/assets/.
  • Keep generated assets UTF-8, preserve the Apache-2.0 license, and do not add dependencies unless required and verified.

8. Implementation Verification Checklist

Contract

  • Every sub-skill applies language, agent-detail, precedence, v10.5 API, package, scope, and verification rules.
  • English input yields English-only prose; Chinese input yields Chinese-only prose; mixed input follows the deterministic selection rule.
  • Root routing covers initialization, UI, six strategies, advanced extensions, troubleshooting, migration, security, and mobile.

API and Artifacts

  • Generated desktop code uses UpdateRequest/SetConfig or SetSource and LaunchAsync.
  • No generated code uses Configinfo, IsComplated, or a separate differential package.
  • Core-only and Bowl-only package scenarios follow the package rules.
  • Client, Upgrade, UI, strategy, advanced, and mobile templates compile in their supported environments.

Distribution and Quality

  • All eight skills install and uninstall on every supported agent platform.
  • .claude/ sources and cli/assets/ copies are synchronized.
  • Skill contract tests, search tests, code generation smoke tests, .NET template/scaffold builds, and TypeScript compilation pass.
  • Generated samples are manually reviewed for completeness, UTF-8, deployment structure, secrets, and security-sensitive defaults.
  • No verification claim is published without recorded execution evidence.