agent-handoff

Imported from paigeman/agent-handoff (AGENTS.md). Install upstream with npx skills add paigeman/agent-handoff. Copyright stays with the author.

Agent Rules

These rules apply to agent behavior in this repository.

Commit Message Rules

These rules apply to all commit message generation tasks in this repository.

Language

• Commit messages must be written in English only.
• Both subject and body must be in English.

Required Format

• Use this subject format: <type>(<scope>): <short summary>
• Body must be a bullet list using a - marker followed by a space.
• Match this style:

feat(storage-system): add round counter APIs for RandomEvent

- add per-event round map in StorageSystem (`randomEventId -> current round`)
- implement `IncrementRound(randomEventId)` to initialize at 1 and increment on each call
- add `CleanupRounds()` to clear all round-tracking records
- introduce rating data structs for future suspicion-statistics pipeline:
  `RatingSample` and `(E,m,j)`-scoped `RoundRatings`
- add event-level container skeleton for round rating records

Scope Rules

• Scope selection is module-first, directory-second.
• If changes are mainly in one module, use that module as scope (for example: storage-system, rsu-app).
• If changes span multiple modules but serve one functional pipeline, use a functional scope (for example: rating-pipeline, trust-computation).
• If changes span unrelated modules without one dominant theme, use multi.
• Scope must be lowercase kebab-case.

Type Rules

• Allowed primary types:
  • feat: new user-visible functionality or behavior expansion
  • fix: bug fix or regression fix
  • refactor: internal restructuring without behavior change
  • perf: performance improvement without semantic change
  • test: tests added or updated
  • docs: documentation-only changes
  • build: build system, dependency, or compilation config changes
  • ci: CI/CD workflow changes
  • chore: maintenance work not covered above and without product behavior change
  • revert: revert of a previous commit
• Always prefer the allowed primary types first.
• If no primary type is a clean fit, default to chore instead of inventing a new type.
• A type outside the list is allowed only when:
  • explicitly requested by the user, or
  • already established as a stable convention in this repository history.
• If an outside-list type is used, include one short rationale line in the commit body.

Body Content Rules

• Commit messages must describe only the change scope explicitly requested by the user for that commit.
• If the user does not explicitly declare a commit scope, default to generating the commit message based on current changes.
• The body must summarize only modifications that belong to the selected commit scope (user-requested scope, or current changes by default), regardless of whether they are staged or unstaged.
• Each bullet must describe a distinct change point; do not repeat the same idea across bullets.
• Do not include process/meta bullets about conversation-driven edits, review comments, or feedback rounds.
• Do not describe "changes made because of user comments" as a standalone bullet.
• Summarize the actual code/content changes only, based on the selected commit scope.

Commit Command Quoting

• When executing git commit commands, preserve commit message literals exactly (including backticks).
• Never pass a commit message containing backticks using double-quoted -m "..." arguments.
• For commit messages containing backticks, use single-quoted -m '...' arguments or git commit -F input to avoid shell command substitution.

Pre-Commit Staging

• When a change spans multiple commits, stage files per commit: run git add for the current commit's files immediately before that commit, and never batch-stage the files of all commits with a single git add.
• Before each commit, verify the staged file list matches the commit's intended scope with git diff --cached --name-only, and commit only when the staged set equals that scope.
• If a commit has already absorbed files that belong to a later commit, stop, undo the commit with git reset --soft HEAD~1, unstage the misplaced files, and re-commit per scope before pushing.

Pre-Commit Sensitive Information Review

• Before creating a commit, review the staged file list and staged diff for user-sensitive information, including passwords, private keys, access tokens, API keys, credentials, personal data, a user's public IP address, and environment-variable files or values. Do not commit any such information unless the user has explicitly confirmed that the exact content is intended to be public and version-controlled. If sensitive information is found, stop the commit, keep it out of the staged changes, and inform the user without reproducing the sensitive value in output.

Pre-Commit Formatting

• Before creating a commit, identify the files in the intended commit scope and format each applicable file according to repository-defined rules, commands, scripts, hooks, and formatter configurations. If the repository provides no applicable formatting rule, use the language or file format's official formatter or style; if no official standard exists, follow a widely accepted standard or established industry convention.
• Reading and using an existing repository formatter configuration does not require user approval.
• If the repository has no formatter configuration and the formatter can run with documented defaults or one-time command-line options without writing configuration files, run it without requesting approval.
• If the formatter requires creating or modifying a persistent repository configuration file, first explain the target file, proposed rules, and impact, and obtain explicit user approval. Do not create or modify the configuration before approval.
• Temporary formatter configurations must be created under TEMP_ROOT and included in the session tracking list. They may be used without approval only when they reproduce the formatter's documented defaults or existing repository rules. If rule selection is ambiguous or would materially change the project's formatting standard, obtain explicit user approval first.
• Downloading or installing a formatter, plugin, or dependency requires explicit user approval.
• Limit formatting to files in the intended commit scope, then review and restage the resulting changes before committing. Do not introduce unrelated repository-wide formatting changes.
• If the required formatter is unavailable, its configuration conflicts, or formatting would cause risky or ambiguous changes, stop and inform the user instead of silently skipping the formatting step or weakening rules.

Pre-Commit Linting

• Before creating a commit, identify the files in the intended commit scope and run every applicable repository-defined lint command, script, hook, and configuration for those files. If the repository provides no applicable lint rule, use the language or file format's official linter; if no official linter exists, use a widely accepted linter or established industry convention.
• Reading and using an existing repository lint configuration does not require user approval.
• If the repository has no lint configuration and the linter can run with documented defaults or one-time command-line options without writing files, run it without requesting approval.
• If the linter requires creating or modifying a persistent repository configuration file, first explain the target file, proposed rules, and impact, and obtain explicit user approval. Do not create or modify the configuration before approval.
• Temporary lint configurations must be created under TEMP_ROOT and included in the session tracking list. They may be used without approval only when they reproduce the linter's documented defaults or existing repository rules. If rule selection is ambiguous or would materially change the project's lint standard, obtain explicit user approval first.
• Downloading or installing a linter, plugin, or dependency requires explicit user approval.
• Run formatting before linting unless the repository explicitly defines a different order. Formatting and linting are separate requirements: a successful formatter run does not replace linting, and a successful lint run does not replace formatting. Basic whitespace checks such as git diff --check do not replace either requirement.
• Limit linting and automatic lint fixes to files in the intended commit scope whenever the tooling supports scoped execution. Review and restage any automatic fixes before committing, and do not introduce unrelated repository-wide changes.
• If an applicable linter is unavailable, its configuration conflicts, or its fixes would be risky or ambiguous, stop and inform the user instead of silently skipping the lint step or weakening rules.
• Before committing, report the exact lint command or commands that were run and whether they passed. If no applicable linter exists after checking repository-defined and conventional tooling, explicitly report that no lint command was available and stop for user direction.

Execution Hygiene

Temporary File Hygiene

• TEMP_ROOT means the repository-local temporary directory used for agent-created temporary files.
• TEMP_ROOT is fixed to .agent-tmp/ under the current repository root.
• User-provided overrides for TEMP_ROOT are not allowed.
• TEMP_ROOT must not be a symlink.
• Canonical path of TEMP_ROOT must resolve under the current repository root.
• At creation time, classify each agent-created file as either:
  • temporary (safe to remove after use), or
  • retained (useful output to keep).
• Maintain a session-local tracking list for all agent-created files, including absolute path, classification (temporary or retained), and short purpose note.
• Only files that are both recorded in the session tracking list and classified as temporary are eligible for automatic cleanup.
• If the tracking list is unavailable, stale, or incomplete, disable automatic cleanup and require explicit user approval for deletion.
• Retained/useful files must never be deleted unless explicitly requested by the user.
• Do not delete files produced by normal program execution, build pipelines, tests, or runtime workflows unless explicitly requested.
• If temporary files are needed, create them under TEMP_ROOT.
• Prefer a task-scoped subdirectory under TEMP_ROOT to avoid collisions between tasks.
• After the task completes, remove only agent-created files that are both:
  • located under TEMP_ROOT, and
  • recorded in the session tracking list as temporary.
• Before deletion, verify canonical paths (after symlink resolution) remain under TEMP_ROOT; otherwise treat them as outside TEMP_ROOT.
• Re-validate canonical paths immediately before executing the delete command.
• Never delete files outside TEMP_ROOT without explicit user approval.
• Wildcard or recursive deletion under TEMP_ROOT is allowed only if the resolved target set contains tracked temporary files only.
• If wildcard or recursive expansion includes any untracked or retained file, do not execute and require explicit user approval with exact path list.
• Temporary files must not be included in commits.
• Before creating a commit, verify no temporary files are staged or included in tracked changes.
• If a temporary file is exceptionally created outside TEMP_ROOT, maintain an explicit tracking list with absolute paths and brief purpose notes.
• Deletion of exception temporary files outside TEMP_ROOT requires explicit user approval and must reference the tracked file list.
• For deletion approval of exception temporary files outside TEMP_ROOT, always present these options:
  • include the exact target file list (absolute paths) and the exact delete command,
  • approve all listed files in one batch command,
  • approve files item-by-item, or
  • cancel (no deletion).
• If the user does not explicitly choose an approval option, default to cancel.

Legacy Path Maintenance

These rules govern how an agent treats retired install paths, layout migration, and leftover artifacts on a machine. Until an official release, historical paths are not a product compatibility surface.

Before an official release

• The installer, registry, skill status|install|update|remove, and setup --install|--uninstall recognize only the current DestRel.
• Do not encode historical relative paths in product code: do not add LegacyDestRel, do not scan or delete old paths on install or remove, and do not annotate legacy files in status output.
• Version / outdated / modified on the current destination may stay. That is same-DestRel content upgrade, not old-layout compatibility.
• Do not preserve files at old paths because a user might have edited them. Before release, a file at a retired location is not promised user data.
• Product docs (README, design, phase reports, skills README) must not describe the installer as migrating or cleaning historical layouts. A phase report may record which paths that phase installed; it must not present that history as current product behavior.

Cleaning leftover artifacts (operator / current-session duty)

• Removing leftovers at historical paths is a one-shot operator action, not a standing installer behavior.
• Do it only when the user explicitly asks. First list candidate paths from implementation history (the DestRel of that era, git history, phase reports), then inspect the local machine and any remotes the user authorized probing, and delete only files confirmed to have been written by an earlier build of this product, plus parent directories that become empty.
• Do not compile the path list from that inspection into the binary, the registry, or a script that runs on every install.
• If a delete must exist in the tree during a transition, mark it as pre-release garbage that must be removed before the official release. Do not put it in the Registry or in the public skill contract.

After an official release

• If install destinations move again after release, design a migration for that change and keep it inside that change's scope. Do not pre-write a migration state machine before then.
• A post-release migration may keep user-modified files only when that release explicitly promises it. Do not reuse the pre-release cleanup policy as the default.

Self-check

• When changing install paths or integration management: the registry and installer must not mention a relative path that is no longer current, unless the user is implementing a marked post-release migration.
• When adding or updating tests: do not assert that the installer migrates or refuses files at retired paths. A fake installs.json record may still carry a historical destination string when the test only checks hash / outdated classification.