diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..a46aff5 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,40 @@ +name: "CodeQL" + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + schedule: + - cron: "30 18 * * 1" + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + language: [ "python" ] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: ${{ matrix.language }} + + - name: Autobuild + uses: github/codeql-action/autobuild@v3 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 + with: + category: "/language:${{matrix.language}}" diff --git a/.gitignore b/.gitignore index ecb4c6c..41c8e56 100644 --- a/.gitignore +++ b/.gitignore @@ -7,3 +7,7 @@ dist/ build/ *.egg-info/ *.log + +# Unity package artifacts +unity-package/Editor/obj/ +unity-package/Editor/bin/ diff --git a/AGENTS.md b/AGENTS.md index 7aa8f13..431ad49 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,407 +1,371 @@ # Tool Rules (compose-agentsmd) -- Before starting any work, run `compose-agentsmd` from the project root. + +- **Session gate**: before responding to ANY user message, run `compose-agentsmd` from the project root. AGENTS.md contains the rules you operate under; stale rules cause rule violations. If you discover you skipped this step mid-session, stop, run it immediately, re-read the diff, and adjust your behavior before continuing. - `compose-agentsmd` intentionally regenerates `AGENTS.md`; any resulting `AGENTS.md` diff is expected and must not be treated as an unexpected external change. - If `compose-agentsmd` is not available, install it via npm: `npm install -g compose-agentsmd`. -- To update shared rules, run `compose-agentsmd edit-rules`, edit the workspace rules, then run `compose-agentsmd apply-rules`. +- To update shared/global rules, use `compose-agentsmd edit-rules` to locate the writable rules workspace, make changes only in that workspace, then run `compose-agentsmd apply-rules` (do not manually clone or edit the rules source repo outside this workflow). +- If you find an existing clone of the rules source repo elsewhere, do not assume it is the correct rules workspace; always treat `compose-agentsmd edit-rules` output as the source of truth. - `compose-agentsmd apply-rules` pushes the rules workspace when `source` is GitHub (if the workspace is clean), then regenerates `AGENTS.md` with refreshed rules. - Do not edit `AGENTS.md` directly; update the source rules and regenerate. - `tools/tool-rules.md` is the shared rule source for all repositories that use compose-agentsmd. -- Before applying any rule updates, present the planned changes first (prefer a colorized diff-style preview), ask for explicit approval, then make the edits. -- These tool rules live in tools/tool-rules.md in the compose-agentsmd repository; do not duplicate them in global rule modules. -- When updating rules, include a colorized diff-style summary in the final response. Use `git diff --stat` first, then include the raw ANSI-colored output of `git diff --color=always` (no sanitizing or reformatting), and limit the output to the rule files that changed. -- Also provide a short, copy-pasteable command the user can run to view the diff in the same format. Use absolute paths so it works regardless of the current working directory, and scope it to the changed rule files. -- If a diff is provided, a separate detailed summary is not required. If a diff is not possible, include a detailed summary of what changed (added/removed/modified items). +- Before applying any rule updates, present the planned changes first with an ANSI-colored diff-style preview, ask for explicit approval, then make the edits. +- These tool rules live in tools/tool-rules.md in the compose-agentsmd repository; do not duplicate them in other rule modules. -Source: github:metyatech/agent-rules@HEAD/rules/global/00-delivery-hard-gates.md +Source: github:metyatech/agent-rules@HEAD/rules/global/agent-rules-composition.md -# Delivery hard gates +# Rule composition and maintenance -These are non-negotiable completion gates for any state-changing work and for any response that claims "done", "fixed", "working", or "passing". +- AGENTS.md is self-contained; place at project root. Shared rules centrally; project-local only for truly local policies. +- Before work in a repo with `agent-ruleset.json`, run `compose-agentsmd` to refresh AGENTS.md. +- Pre-commit hooks must run the repo's full verification suite, then `compose-agentsmd --compose`, then `git add AGENTS.md`. Do not fail commits on drift or add freshness checks to CI. -## Acceptance criteria (AC) +## Update and editing -- Before state-changing work, list Acceptance Criteria (AC) as binary, testable statements. -- For read-only tasks, AC may be deliverables/questions answered; keep them checkable. -- If AC are ambiguous or not testable, ask blocking questions before proceeding. +- Never edit AGENTS.md directly; update source rules and regenerate. "Update rules" = update module/ruleset, then regenerate. +- Persistent user instructions → encode in appropriate module (global vs local) in the same change set. +- New repos must meet all global rules (AGENTS.md, CI, linting, community health, docs, scanning) before reporting complete. +- Update rulesets for missing domain rules before proceeding. Omit AGENTS.md diffs unless asked. +- Treat AGENTS.md diffs produced by compose-agentsmd as intentional updates: do not discard/revert them unless the requester explicitly asks to drop them. +- When the repository is git-managed, stage those intentional AGENTS.md updates normally (git add) unless the requester explicitly says to exclude them. +- Infer core intent; prefer global over project-local. Keep rules MECE, concise, non-redundant, action-oriented ("do X", "never Z"). No hedging or numeric filename prefixes. +- Placement: based on where needed. Any-workspace → global; domain only for opt-in repos. -## Evidence and verification +## Size budget -- For each AC, define verification evidence (automated test preferred; otherwise a deterministic manual procedure). -- Maintain an explicit mapping: `AC -> evidence (tests/commands/manual steps)`. -- For code or runtime-behavior changes, automated tests are required unless the requester explicitly approves skipping. -- Bugfixes MUST include a regression test that fails before the fix and passes after. -- Run the repo's full verification suite (lint/format/typecheck/test/build) using a single repo-standard `verify` command when available; if missing, add it. -- Enforce verification locally via commit-time hooks (pre-commit or repo-native) and in CI; skipping requires explicit requester approval. -- For non-code changes, run the relevant subset and justify. -- If required checks cannot be run, stop and ask for explicit approval to proceed with partial verification, and provide an exact manual verification plan. +- Total ≤350 lines; per-module ≤30 (soft). Overage → extract procedural content to skills. +- **Rules** = invariants (always loaded, concise). **Skills** = procedures (on-demand, detailed). -## Final response (MUST include) - -- AC list. -- `AC -> evidence` mapping with outcomes (PASS/FAIL/NOT RUN/N/A) and brief notes where needed. -- The exact verification commands executed and their outcomes. - -Source: github:metyatech/agent-rules@HEAD/rules/global/agent-rules-composition.md +Source: github:metyatech/agent-rules@HEAD/rules/global/autonomous-operations.md -# Rule composition and maintenance +# Autonomous operations -## Scope and composition +- Optimize for minimal human effort; default to automation over manual steps. +- Drive work from the desired outcome: choose the highest-quality safe path and execute end-to-end. +- Correctness, safety, robustness, verifiability > speed unless requester explicitly approves the tradeoff. +- Default to long-term maintainability and operational cost over short-term local optimization. +- End-to-end repo autonomy (issues, PRs, pushes, merges, releases, admin) within user-controlled repos; third-party repos require explicit request. +- No backward compatibility unless requested; no legacy aliases or shims. +- Do not introduce temporary compatibility/fallback behavior unless explicitly requested; if unavoidable, require an explicit removal condition and deadline. +- Proactively fix rule gaps, redundancy, or misplacement; regenerate AGENTS.md without waiting. +- Self-evaluate continuously; fix rule/skill gaps immediately on discovery. In delegated mode, include improvement suggestions in the task result. +- On user-reported failures: treat as systemic — fix, update rules, check for same pattern elsewhere, in one action. +- Persistent workflow promises → propose rule update immediately (blocking gate). In delegated mode, follow that module's restricted-operations guidance. +- Session memory resets; use rule files as persistent memory. Always reference current AGENTS.md, never from memory. Never write to platform-specific local memory files (e.g., Claude Code auto-memory); all persistent behavioral knowledge MUST live in agent rules to ensure consistency across all environments, operating systems, and agent platforms. +- Rules are source of truth; update conflicting repos to comply or encode the exception. +- When the `manager` skill is invoked, maintain that role for the session unless user explicitly stops it. +- Investigate unclear items before proceeding; no assumptions without approval. Make scope/risk/cost/irreversibility decisions explicit. +- Prefer async control channels (GitHub Issues/PR comments). Design high-volume workflows with queuing and throttling. -- AGENTS.md is self-contained; do not rely on parent/child AGENTS for inheritance or precedence. -- Maintain shared rules centrally and compose per project; use project-local rules only for truly local policies. -- Place AGENTS.md at the project root; only add another AGENTS.md for nested independent projects. +## PR review response protocol -## Update policy +- After addressing PR review feedback, resolve the corresponding conversation thread. +- After all feedback is addressed, re-request review from the agent or person who raised it. -- Never edit AGENTS.md directly; update source rules and regenerate AGENTS.md. -- A request to "update rules" means: update the appropriate rule module and ruleset, then regenerate AGENTS.md. -- If the user gives a persistent instruction (e.g., "always", "must"), encode it in the appropriate module (global vs local). -- When acknowledging a new persistent instruction, update the rule module in the same change set and regenerate AGENTS.md. -- When creating a new repository, set up rule files (e.g., agent-ruleset.json and any local rules) so compose-agentsmd can run. -- When updating rules, infer the core intent; if it is a global policy, record it in global rules rather than project-local rules. -- If a task requires domain rules not listed in agent-ruleset.json, update the ruleset to include them and regenerate AGENTS.md before proceeding. -- When rule changes produce a diff, include it in the final response unless the user explicitly asks to omit it. +## GitHub notifications -## Editing standards +- After addressing a notification, mark as done via GraphQL `markNotificationsAsDone`. Detailed procedures in the `manager` skill. -- Keep rules MECE, concise, and non-redundant. -- Use short, action-oriented bullets; avoid numbered lists unless order matters. -- Prefer the most general applicable rule to avoid duplication. +Source: github:metyatech/agent-rules@HEAD/rules/global/cli-standards.md -Source: github:metyatech/agent-rules@HEAD/rules/global/autonomous-operations.md +# CLI standards -# Autonomous operations - -- Optimize for minimal human effort; default to automation over manual steps. -- Drive work from the desired outcome: infer acceptance criteria, choose the highest-quality safe path that satisfies the requested quality/ideal bar, and execute end-to-end. -- Treat speed as a secondary optimization; never trade down correctness, safety, robustness, or verifiability unless the requester explicitly approves that tradeoff. -- Assume end-to-end autonomy for repository operations (issue triage, PRs, direct pushes to main/master, merges, releases, repo admin) only within repositories under the user's control (e.g., owned by metyatech or where the user has explicit maintainer/push authority), unless the user restricts scope; for third-party repos, require explicit user request before any of these operations. -- Do not preserve backward compatibility unless explicitly requested; avoid legacy aliases and compatibility shims by default. -- When work reveals rule gaps, redundancy, or misplacement, proactively update rule modules/rulesets (including moves/renames) and regenerate AGENTS.md without waiting for explicit user requests. -- After each task, run a brief retrospective; if you notice avoidable mistakes, missing checks, or recurring back-and-forth, encode the fix as a rule update and regenerate AGENTS.md. -- If you state a persistent workflow change (e.g., "from now on", "I'll always"), immediately propose the corresponding rule update and request approval in the same task; do not leave it as an unrecorded promise. -- Because session memory resets between tasks, treat rule files as persistent memory; when any issue or avoidable mistake occurs, update rules in the same task to prevent recurrence. -- Treat these rules as the source of truth; do not override them with repository conventions. If a repo conflicts, update the repo to comply or update the rules to encode the exception; do not make undocumented exceptions. -- When something is unclear, investigate to resolve it; do not proceed with unresolved material uncertainty. If still unclear, ask and include what you checked. -- Do not proceed based on assumptions or guesses without explicit user approval; hypotheses may be discussed but must not drive action. -- Ask only blocking questions; for non-material ambiguities, pick the lowest-risk option, state the assumption, and proceed. -- Make decisions explicit when they affect scope, risk, cost, or irreversibility. -- Prefer asynchronous, low-friction control channels (GitHub Issues/PR comments) unless a repository mandates another. -- Design autonomous workflows for high volume: queue requests, set concurrency limits, and auto-throttle to prevent overload. +- When building a CLI, follow standard conventions: --help/-h, --version/-V, stdin/stdout piping, --json output, --dry-run for mutations, deterministic exit codes, and JSON Schema config validation. Source: github:metyatech/agent-rules@HEAD/rules/global/command-execution.md # Workflow and command execution +## MCP server setup verification + +- After adding or modifying an MCP server configuration, immediately verify connectivity using the platform's MCP health check and confirm the server is connected. +- If a configured MCP server fails to connect, diagnose and fix before proceeding. Do not silently fall back to alternative tools without reporting the degradation. +- At session start, if expected MCP tools are absent from the available tool set, verify MCP server health and report/fix connection failures before continuing. + - Do not add wrappers or pipes to commands unless the user explicitly asks. - Prefer repository-standard scripts/commands (package.json scripts, README instructions). - Reproduce reported command issues by running the same command (or closest equivalent) before proposing fixes. - Avoid interactive git prompts by using --no-edit or setting GIT_EDITOR=true. -- If elevated privileges are required, use sudo where available; otherwise run as Administrator. +- If elevated privileges are required, use sudo directly; do not launch a separate elevated shell (e.g., Start-Process -Verb RunAs). Fall back to run as Administrator only when sudo is unavailable. - Keep changes scoped to affected repositories; when shared modules change, update consumers and verify at least one. - If no branch is specified, work on the current branch; direct commits to main/master are allowed. -- After addressing PR review feedback, resolve the corresponding review thread(s) before concluding; if you lack permission, state it explicitly. -- After pushing fixes for PR review feedback, re-request review only from reviewer(s) who posted the addressed feedback in the current round. -- Do not re-request review from reviewers (including AI reviewers) who did not post addressed feedback, or who already indicated no actionable issues. -- If no applicable reviewer remains, ask who should review next. -- When Codex and/or Copilot review bots are configured for the repo, trigger re-review only for the bot(s) that posted addressed feedback. -- For Codex re-review (only when applicable): comment `@codex review` on the PR. -- For Copilot re-review (only when applicable): use `gh api` to remove+re-request the bot reviewer `copilot-pull-request-reviewer[bot]` (do not rely on `gh pr edit --add-reviewer Copilot`). - - Remove: `gh api --method DELETE /repos/{owner}/{repo}/pulls/{pr}/requested_reviewers -f "reviewers[]=copilot-pull-request-reviewer[bot]"` - - Add: `gh api --method POST /repos/{owner}/{repo}/pulls/{pr}/requested_reviewers -f "reviewers[]=copilot-pull-request-reviewer[bot]"` -- After completing a PR, merge it, sync the target branch, and delete the PR branch locally and remotely. - -Source: github:metyatech/agent-rules@HEAD/rules/global/implementation-and-coding-standards.md - -# Engineering and implementation standards +- Do not assume agent platform capabilities beyond what is available; fail explicitly when unavailable. -- Prefer official/standard approaches recommended by the framework or tooling. -- Prefer well-maintained external dependencies; build in-house only when no suitable option exists. -- Prefer third-party tools/services over custom implementations when they can meet the requirements; prefer free options (OSS/free-tier) when feasible and call out limitations/tradeoffs. -- PowerShell: `\` is a literal character (not an escape). Do not cargo-cult `\\` escaping patterns from other languages; validate APIs that require names like `Local\...` (e.g., named mutexes). -- PowerShell: avoid assigning to or shadowing automatic/read-only variables (e.g., `$args`, `$PID`); use different names for locals. -- PowerShell: when invoking PowerShell from PowerShell, avoid double-quoted `-Command` strings that allow the outer shell to expand `$...`; prefer `-File`, single quotes, or here-strings to control expansion. -- If functionality appears reusable, assess reuse first and propose a shared module/repo; prefer remote dependencies (never local filesystem paths). -- Maintainability > testability > extensibility > readability. -- Single responsibility; keep modules narrowly scoped and prefer composition over inheritance. -- Keep dependency direction clean and swappable; avoid global mutable state. -- Avoid deep nesting; use guard clauses and small functions. -- Use clear, intention-revealing naming; avoid "Utils" dumping grounds. -- Prefer configuration/constants over hardcoding; consolidate change points. -- For GUI changes, prioritize ergonomics and discoverability so first-time users can complete core flows without external documents. -- Every user-facing GUI component (inputs, actions, status indicators, lists, and dialog controls) must include an in-app explanation (for example tooltip, context help panel, or equivalent). -- Do not rely on README-only guidance for GUI operation; critical usage guidance must be available inside the GUI itself. -- Keep everything DRY across code, specs, docs, tests, configs, and scripts; proactively refactor repeated procedures into shared configs/scripts with small, local overrides. -- Persist durable runtime/domain data in a database with a fully normalized schema (3NF/BCNF target): store each fact once with keys/constraints, and compute derived statuses/views at read time instead of duplicating them. -- Fix root causes; remove obsolete/unused code, branches, comments, and helpers. -- Externalize large embedded strings/templates/rules when possible. -- Do not commit build artifacts (follow the repo's .gitignore). -- Align file/folder names with their contents and keep naming conventions consistent. -- Do not assume machine-specific environments (fixed workspace directories, drive letters, per-PC paths). Prefer repo-relative paths and explicit configuration so workflows work in arbitrary clone locations. +## Codex-only: Commands blocked by policy (PowerShell) -Source: github:metyatech/agent-rules@HEAD/rules/global/linting-formatting-and-static-analysis.md +- Blocked by policy under Codex: `Remove-Item` (aliases: `rm`, `ri`, `del`, `erase`) -> Use: `if ([IO.File]::Exists($p)) { [IO.File]::SetAttributes($p,[IO.FileAttributes]::Normal); [IO.File]::Delete($p) }` +- Blocked by policy under Codex: `Remove-Item -Recurse` (aliases: `rmdir`, `rd`) -> Use: `if ([IO.Directory]::Exists($d)) { [IO.File]::SetAttributes($d,[IO.FileAttributes]::Normal); foreach ($e in [IO.Directory]::EnumerateFileSystemEntries($d,'*',[IO.SearchOption]::AllDirectories)) { [IO.File]::SetAttributes($e,[IO.FileAttributes]::Normal) }; [IO.Directory]::Delete($d,$true) }` -# Linters, formatters, and static analysis +Source: github:metyatech/agent-rules@HEAD/rules/global/delivery-hard-gates.md -## General policy - -- Every code repo must have a formatter and a linter/static analyzer for its primary languages. -- Prefer one formatter and one linter per language; avoid overlapping tools that fight each other. -- Follow the standard toolchains below. If a repo conflicts, migrate it to comply unless the user explicitly restricts scope. -- If you believe an exception is needed, encode it as a rule update and regenerate AGENTS.md before proceeding. -- Enforce in CI: run formatting checks (verify-no-changes) and linting on pull requests and require them for merges. -- Treat warnings as errors in CI; when a tool cannot, use its strictest available setting so warnings fail CI. -- Do not disable rules globally; keep suppressions narrow, justified, and time-bounded. -- Pin tool versions (lockfiles/manifests) for reproducible CI. - -## Design and visual accessibility automation - -- For any design/UI styling change in any project, enforce automated visual accessibility checks as part of the repo-standard `verify` command and CI. -- Do not rely on per-page/manual test maintenance; use route discovery (for example sitemap, generated route lists, or framework route manifests) so newly added pages are automatically included. -- Validate both light and dark themes when theme switching is supported. -- Validate at least default, hover, and focus states for interactive elements. -- Enforce non-text boundary contrast checks across all visible UI elements that present boundaries (including interactive controls and container-like elements), not only predefined component classes. -- Do not hardcode a narrow selector allowlist for boundary checks; use broad DOM discovery with only minimal technical exclusions (for example hidden/zero-size/non-rendered nodes). -- Fail CI on violations; do not silently ignore design regressions. -- If temporary exclusions are unavoidable, keep them narrowly scoped, documented with rationale, and remove them promptly. - -## Security baseline - -- Require dependency vulnerability scanning appropriate to the ecosystem (SCA) for merges. If you cannot enable it, report the limitation and get explicit user approval before proceeding without it. -- Enable GitHub secret scanning and remediate findings; never commit secrets. If it is unavailable, add a repo-local secret scanner and require it for merges. -- Enable CodeQL code scanning for supported languages. If it cannot be enabled, report the limitation and use the best available alternative for that ecosystem. - -## Default toolchain by language - -### JavaScript / TypeScript (incl. React/Next) - -- Format+lint: ESLint + Prettier. -- When configuring Prettier, always add and maintain `.prettierignore` so generated/build outputs and composed files are not formatted/linted as source (e.g., `dist/`, build artifacts, and `AGENTS.md` when generated by compose-agentsmd). -- Typecheck: `tsc` with strict settings for TS projects. -- Dependency scan: `osv-scanner`. If unsupported, use the package manager's audit tooling. - -### Python - -- Format+lint: Ruff. -- Typecheck: Pyright. -- Dependency scan: pip-audit. - -### Go - -- Format: gofmt. -- Lint/static analysis: golangci-lint (includes staticcheck). -- Dependency scan: govulncheck. +# Delivery hard gates -### Rust +These are non-negotiable completion gates for any state-changing work and for any response that claims "done", "fixed", "working", or "passing". -- Format: cargo fmt. -- Lint/static analysis: cargo clippy with warnings as errors. -- Dependency scan: cargo audit. +## Acceptance criteria (AC) -### Java +- Before state-changing work, list Acceptance Criteria (AC) as binary, testable statements. +- For read-only tasks, AC may be deliverables/questions answered; keep them checkable. +- If AC are ambiguous or not testable, ask blocking questions before proceeding. +- Keep AC compact by default (aim: 1-3 items). Expand only when risk/complexity demands it or when the requester asks. -- Format: Spotless + google-java-format. -- Lint/static analysis: Checkstyle + SpotBugs. -- Dependency scan: OWASP Dependency-Check. +## Evidence and verification -### Kotlin +- Do not run `git commit` until the repo's full verification command has passed in the current working tree. This applies to every commit, not only the final delivery. +- For each AC, define verification evidence (automated test preferred; otherwise a deterministic manual procedure). +- Maintain an explicit mapping: `AC -> evidence (tests/commands/manual steps)`. +- The mapping may be presented in a compact per-item form (one line per AC including evidence + outcome) to reduce verbosity. +- For code or runtime-behavior changes, automated tests are required unless the requester explicitly approves skipping. +- Bugfixes MUST include a regression test that fails before the fix and passes after. +- Run the repo's full verification suite (lint/format/typecheck/test/build) using a single repo-standard `verify` command when available; if missing, add it. +- Enforce verification locally via commit-time hooks (pre-commit or repo-native) and in CI; skipping requires explicit requester approval. +- For non-code changes, run the relevant subset and justify. +- If required checks cannot be run, stop and ask for explicit approval to proceed with partial verification, and provide an exact manual verification plan. -- Format: Spotless + ktlint. -- Lint/static analysis: detekt. -- Compiler: enable warnings-as-errors in CI; if impractical, get explicit user approval before relaxing. +## Final response (MUST include) -### C# +- A compact goal+verification report. Labels may be `Goal`/`Verification` instead of `AC` as long as it is equivalent. +- `AC -> evidence` mapping with outcomes (PASS/FAIL/NOT RUN/N/A), possibly in compact per-item form. +- The exact verification commands executed and their outcomes. -- Format: dotnet format (verify-no-changes in CI). -- Lint/static analysis: enable .NET analyzers; treat warnings as errors; enable nullable reference types. -- Dependency scan: `dotnet list package --vulnerable`. +Source: github:metyatech/agent-rules@HEAD/rules/global/implementation-and-coding-standards.md -### C++ +# Engineering and implementation standards -- Format: clang-format. -- Lint/static analysis: clang-tidy. -- Build: enable strong warnings and treat as errors; run sanitizers (ASan/UBSan) in CI where supported. +- Prefer official/standard framework/tooling approaches. +- Prefer well-maintained dependencies; build in-house only when no suitable option exists. +- Prefer third-party tools/services over custom implementations; prefer OSS/free-tier when feasible and call out tradeoffs. +- PowerShell: `\` is literal (not escape); avoid shadowing auto variables (`$args`, `$PID`); avoid double-quoted `-Command` strings (prefer `-File`, single quotes, or here-strings). +- If functionality is reusable, assess reuse first and propose shared module/repo; prefer remote dependencies (never local paths). +- Maintainability > testability > extensibility > readability. +- Single responsibility; composition over inheritance; clean dependency direction; no global mutable state. +- Avoid deep nesting; guard clauses and small functions; clear intention-revealing names; no "Utils" dumping grounds. +- Prefer config/constants over hardcoding; consolidate change points. +- For GUI: prioritize ergonomics/discoverability, include in-app guidance for all components, prefer established design systems (Material, shadcn/ui, Fluent). +- Keep DRY across code/specs/docs/tests/config/scripts; refactor repeated procedures into shared config with local overrides. +- Fix root causes; remove obsolete/unused code/branches/comments; repair user-controlled tools at source, not via workarounds. +- Ensure failure/cancellation paths tear down allocated resources; no partial state. +- Do not block inside async APIs; avoid synchronous I/O where responsiveness is expected. +- Avoid external command execution; prefer native SDKs. If unavoidable: absolute paths, safe argument handling, strict validation. +- Prefer stable public APIs; isolate/document unavoidable internal API usage. +- Externalize large embedded strings/templates/rules. +- Do not commit build artifacts (respect `.gitignore`); keep file/folder naming aligned and consistent. +- Do not assume machine-specific environments; use repo-relative paths and explicit configuration. +- Agent temp files MUST stay under OS temp unless requester approves. +- For agent-facing tools/services, design for cross-agent compatibility via standard interfaces (CLI, HTTP, stdin/stdout, MCP). +- Lifecycle install hooks (`prepare`/`preinstall`/`postinstall`) must succeed on a clean machine with no global tool assumptions; invoke required CLIs through project-local dependencies or package-manager executors (for npm, prefer `npm exec`). +- After manifest changes, regenerate and commit corresponding lock files in the same commit. -### PowerShell +Source: github:metyatech/agent-rules@HEAD/rules/global/linting-formatting-and-static-analysis.md -- Format+lint: PSScriptAnalyzer (Invoke-Formatter + Invoke-ScriptAnalyzer). -- Runtime: Set-StrictMode -Version Latest; fail fast on errors. -- Tests: Pester when tests exist. -- Enforce PSScriptAnalyzer via the repo’s standard `verify` command/script when PowerShell is used; treat findings as errors. +# Linters, formatters, and static analysis -### Shell (sh/bash) +- Every code repo must have a formatter and a linter/static analyzer for its primary languages. +- Prefer one formatter and one linter per language; avoid overlapping tools. +- Enforce in CI: run formatting checks (verify-no-changes) and linting on pull requests and require them for merges. +- Treat warnings as errors in CI. +- Do not disable rules globally; keep suppressions narrow, justified, and time-bounded. +- Pin tool versions (lockfiles/manifests) for reproducible CI. +- For web UI projects, enforce automated visual accessibility checks in CI. +- Require dependency vulnerability scanning, secret scanning, and CodeQL for supported languages. -- Format: shfmt. -- Lint: shellcheck. +Source: github:metyatech/agent-rules@HEAD/rules/global/model-inventory.md -### Dockerfile +# Model inventory and routing -- Lint: hadolint. +- Classify tasks into tiers: Free (trivial, Copilot 0x only), Light, Standard, Heavy, Large Context (>200k tokens, prefer Gemini 1M context). +- Before spawning sub-agents, run `ai-quota` to check availability. +- Always explicitly specify `model` and `effort` from the model inventory when spawning agents; never rely on defaults. +- The full model inventory with agent tables, routing principles, and quota fallback logic is maintained in the `manager` skill. +- **Orchestrator model**: When spawning an orchestrator (manager/autonomous-orchestrator role), default to `claude-sonnet-4-6` with `medium` effort; use `claude-opus-4-6` with `medium` effort when strict rule compliance is required. Research shows higher effort degrades instruction-following on multi-constraint rule sets (arXiv:2505.11423). Use `high`/`max` effort only for complex reasoning tasks, not for rule compliance. +- **Gemini sub-agent reliability**: Do NOT use Gemini (`gemini` agent type) for sub-agent delegation. Even single Gemini agents hit 429 "No capacity available" server errors frequently, making them unreliable for unattended tasks. Use Claude or Copilot instead. Gemini CLI may be used interactively by the user but not as a spawned sub-agent. -### Terraform +Source: github:metyatech/agent-rules@HEAD/rules/global/multi-agent-delegation.md -- Format: terraform fmt -check. -- Validate: terraform validate. -- Lint: tflint. -- Security scan: trivy config. +# Multi-agent delegation -### YAML +- Every agent runs in direct mode (human requester) or delegated mode (spawned by another agent, where the delegator is the requester); default to direct mode. +- In delegated mode, delegation is plan approval: do not re-request human approval, respond in English, emit no notification sounds, and report AC/verification concisely to the delegator. If scope must expand, fail back to the delegator with a clear explanation. +- Delegation prompts MUST state delegated mode and approval state, include AC/verification requirements, and focus on task context (agents read repo AGENTS.md automatically). +- If a delegated agent reports read-only/no-write constraints, it MUST run a minimal reversible OS-temp probe (create/write/read/delete) and report the exact failure verbatim. +- Restricted operations require explicit delegation: modifying rules/rulesets, merging/closing PRs, creating/deleting repos, releasing/deploying, and force-pushing/rewriting published history. +- Delegated agents must not modify rules directly; submit rule-gap suggestions in results for delegator review and human approval. +- Delegated agents inherit delegator repository scope but must not expand it; if required capability is unavailable, fail explicitly. -- Lint: yamllint. +## Cost optimization (model selection) -### Markdown +- Always specify `model` and `effort` when spawning agents; never rely on defaults. +- Minimize total cost (model pricing, reasoning tokens, context, retries). +- Detailed optimization guidance is in the `manager` skill. -- Lint: markdownlint. +## Parallel execution safety -Source: github:metyatech/agent-rules@HEAD/rules/global/observability-and-diagnostics.md +- Do not run concurrent agents that modify the same repository/files; different repositories may run in parallel. +- When conflict risk is unclear, run sequentially. -# Observability and diagnostics +## Execution patience and switching discipline -## General policy +- Do not rapidly switch or respawn sub-agents for the same task while one is actively running without errors. +- Status checks should prioritize non-blocking monitoring and user responsiveness, but must not be used as justification for premature agent replacement. -- Design for debuggability: make failures diagnosable from logs/metrics/traces without reproducing locally. -- Add observability in the same change set as behavior changes that affect runtime behavior, performance, or reliability. +## agents-mcp dispatch -## Performance investigations +- Always set `mode: 'edit'` when spawning implementation agents; default `mode: 'plan'` is read-only and wastes the agent call. +- `agents-mcp wait` and `Status(wait=true)` both poll until agents complete or timeout; either may be used for completion checks. -- For performance/latency issues, measure first: establish a baseline, then use profiling/instrumentation to identify hotspots; do not implement "optimizations" based on guesswork. -- Record before/after numbers and the measurement method in the change set (tests, benchmark output, logs, or deterministic manual steps). -- Prefer automated performance regression tests/benchmarks when feasible; otherwise provide deterministic manual measurement steps. +Source: github:metyatech/agent-rules@HEAD/rules/global/planning-and-approval-gate.md -## Logging +# Planning and approval gate -- Prefer structured logs for services; keep field names stable (e.g., level, message, component, request_id/trace_id, version). -- Include actionable context in errors (what failed, which input/state, what to do next) without logging secrets/PII. -- Log at the right level; avoid noisy logs in hot paths. +- In direct mode, skip approval only for trivial, low-risk, reversible checks: read-only inspection/verification, spawning read-only smoke-check agents, and temp files under OS temp with cleanup. +- Approval required for: file/rule/config edits, dependency/tool changes, git beyond status/diff/log, and external side effects (deploy/publish/API writes/account changes). +- If impact is meaningfully uncertain, request approval. +- Default flow: clarify goal + plan first, then execute after explicit requester approval. +- In delegated mode, delegation itself is plan approval; if scope expansion is needed, fail back to the delegator. +- For potentially state-changing work, clarify details first; do not proceed while ambiguous. +- Allowed before approval: read-only inspection, dependency install, formatters/linters/typecheck/tests/builds (including auto-fix), and deterministic code generation/build steps. +- Before other state-changing execution: restate as AC, produce plan, confirm with requester, and wait for explicit post-plan "yes"; after approval, re-request only if plan/scope changes. +- Do not treat the original task request as plan approval. +- If state-changing work starts without required "yes", stop immediately, report the gate miss, update rules, regenerate AGENTS.md, and restart from the approval gate. +- No bypass exceptions: "skip planning/just do it" means move quickly through the gate, not around it. -## Metrics +## Scope-based blanket approval -- Instrument the golden signals (latency, traffic, errors, saturation) for each service and critical dependency; define concrete SLIs/SLOs for user-facing flows. -- Use OpenTelemetry Metrics for instrumentation and OTLP for export; using vendor-specific metrics SDKs directly is an exception and requires explicit user approval. -- Use the right metric types (counters for monotonic totals, histograms for latencies/sizes, gauges for current values) and include explicit units in names. -- Keep metric names and label keys stable; use a consistent namespace and Prometheus-style `snake_case` naming with base-unit suffixes (e.g., `http_server_request_duration_seconds`). -- Constrain label cardinality: labels must come from small bounded sets; never use user identifiers, raw URLs, request bodies, or other unbounded values as labels. -- Ensure correlation: when supported, record exemplars or identifiers that let you jump from a metric spike to representative traces/logs. -- Treat missing/incorrect metrics as a defect when they block verification, incident response, or SLO evaluation; add/adjust dashboards and alerts with behavior changes that impact reliability/performance. +- Broad directives (e.g., "fix everything") count as approval for all work within scope including implied follow-up (rebuild, restart, update installs); re-request only for out-of-scope expansion. -## Alerting +## Reviewer proxy approval -- Alerting is part of the definition of done for reliability/performance changes: update dashboards, alerts, and runbooks in the same change set. -- Define alert severity and routing explicitly; paging alerts must correspond to user-impacting SLO/error-budget burn, not “interesting” internal signals. -- Use multi-window burn-rate alerting to reduce flapping; page only on sustained burn and use ticket-level alerts for slower burn or early-warning signals. -- Every alert must be actionable and owned: include service/team ownership labels and a runbook link that lists diagnosis steps, mitigation steps, and rollback/feature-flag options. -- Every alert must include a dashboard link and relevant identifiers (service, environment, region/cluster) so responders can triage quickly. -- Reduce noise aggressively: delete or downgrade alerts that page without clear user impact; treat alert fatigue and stale/non-actionable alerts as defects. -- Alert rules must be managed as code and reviewed with code changes; manual, ad-hoc changes in vendor UIs are prohibited. -- Alert rules must be automatically validated and tested in CI; for Prometheus-compatible rules this means `promtool check rules` and `promtool test rules`. -- If constraints make “alerts as code” or CI validation impractical, treat it as an exception and require explicit user approval with documented rationale. +- With `autonomous-orchestrator` active, invocation is blanket approval for user-owned repos; orchestrator approves plans via reviewer proxy without asking the human. +- Reviewer proxy validates against rules, error patterns, and quality standards; proceed if approved, escalate to human if concerns remain. Human may override anytime. +- Reviewer proxy never covers restricted operations (create/delete repos, force-push, rewrite history) — these require human approval. +- Orchestrator may apply safe rule changes when reviewer proxy confirms policy consistency; escalate when ambiguous. -## Tracing +Source: github:metyatech/agent-rules@HEAD/rules/global/post-change-deployment.md -- For multi-service or async flows, use OpenTelemetry and propagate context across boundaries (HTTP/gRPC/queues). -- Correlate logs and traces via trace_id/request_id. +# Post-change deployment -## Health and self-checks +After modifying code in a repository, check whether the changes require +deployment steps beyond commit/push before concluding. -- Services must have readiness and liveness checks; fail fast when dependencies are unavailable. -- CLIs should provide a verbose mode and clear error output; add a self-check command when it reduces support burden. +## Globally linked packages -Source: github:metyatech/agent-rules@HEAD/rules/global/planning-and-approval-gate.md +- If the repository is globally installed via `npm link` (identifiable by + `npm ls -g --depth=0` showing `->` pointing to a local path), run the + repo's build command after code changes so the global binary reflects + the update. +- Verify the rebuilt output is functional (e.g., run the CLI's `--version` + or a smoke command). -# Planning and approval gate +## Locally running services and scheduled tasks -- Default to a two-phase workflow: clarify goal + plan first, execute after explicit requester approval. -- If a request may require any state-changing work, you MUST first dialogue with the requester to clarify details and make the goal explicit. Do not proceed while the goal is ambiguous. -- Allowed before approval: - - Clarifying questions and read-only inspection (reading files, searching, and `git status` / `git diff` / `git log`). - - Any unavoidable automated work triggered as a side-effect of those read-only commands. - - Any command execution that must not adversely affect program behavior or external systems (including changes made by tooling), such as: - - Installing/restoring dependencies using repo-standard tooling (lockfile changes are allowed). - - Running formatters/linters/typecheck/tests/builds (including auto-fix/formatting that modifies files). - - Running code generation/build steps that are deterministic and repo-scoped. - - Running these from clean → dirty → clean is acceptable; publishing/deploying/migrating is not. -- Before any other state-changing execution (e.g., writing or modifying files by hand, changing runtime behavior, or running git commands beyond status/diff/log), do all of the following: - - Restate the request as Acceptance Criteria (AC) and verification methods, following "Delivery hard gates". - - Produce a written plan (use your planning tool when available) focused on the goal, approach, and verification checkpoints (do not enumerate per-file implementation details or exact commands unless the requester asks). - - Confirm the plan with the requester, ask for approval explicitly, and wait for a clear “yes” before executing. - - Once the requester has approved a plan, proceed within that plan without re-requesting approval; re-request approval only when you change or expand the plan. - - Do not treat the original task request as plan approval; approval must be an explicit response to the presented plan. -- If state-changing execution starts without the required post-plan “yes”, stop immediately, report the gate miss, add/update a prevention rule, regenerate AGENTS.md, and then restart from the approval gate. -- No other exceptions: even if the user requests immediate execution (e.g., “skip planning”, “just do it”), treat that as a request to move quickly through this gate, not to bypass it. +- If the repository powers a locally running service, daemon, or scheduled + task, rebuild and restart the affected component after code changes. +- Verify the restart with deterministic evidence (new PID, port check, + service status query, or log entry showing updated behavior). +- Do not claim completion until the running instance reflects the changes. Source: github:metyatech/agent-rules@HEAD/rules/global/quality-testing-and-errors.md # Quality, testing, and error handling -## Quality priority - -- Quality (correctness, safety, robustness, verifiability) takes priority over speed or convenience. +For AC definition, verification evidence, regression tests, and final reporting, see Delivery hard gates. -## Definition of done - -- Do not claim "fixed"/"done" unless it is verified by reproducing the issue and/or running the relevant checks. -- For code changes, treat "relevant checks" as the repo's full lint/typecheck/test/build suite (prefer CI results). -- Prefer a green baseline: if relevant checks fail before you change anything, report it and get explicit user approval before proceeding. -- If you cannot reproduce/verify, do not guess a fix; request missing info or create a failing regression test. -- Follow "Delivery hard gates" for Acceptance Criteria, verification evidence, and final reporting; if anything is unverified, state why and how to verify. +- Quality (correctness, safety, robustness, verifiability) takes priority over speed/convenience. ## Verification -- Follow "Delivery hard gates" for running and reporting verification. -- If you are unsure what constitutes the full suite, run the repo's default verify/CI commands rather than guessing. -- Before committing code changes, run the full suite; if a relevant check is missing and feasible to add, add it in the same change set. -- Enforce via CI: run the full suite on pull requests and on pushes to the default branch, and make it a required status check for merges; if no CI harness exists, add one using repo-standard commands. -- Configure required status checks on the default branch when you have permission; otherwise report the limitation. -- Do not rely on smoke-only gating or scheduled-only full runs for correctness; merges must require the full suite. -- Ensure commit-time automation (pre-commit or repo-native) runs the full suite and blocks commits. -- Never disable checks, weaken assertions, loosen types, or add retries solely to make checks pass. - -## Tests (behavior changes) - -- Follow test-first: add/update tests, observe failure, implement the fix, then observe pass. -- For bugfixes, follow "Delivery hard gates" (regression test: fail-before/pass-after). -- Add/update automated tests for behavior changes and regression coverage. -- Cover success, failure, boundary, invalid input, and key state transitions (including first-run/cold-start vs subsequent-run behavior when relevant); include representative concurrency/retry/recovery when relevant. -- Keep tests deterministic; minimize time/random/external I/O; inject when needed. -- For deterministic output files, use full-content snapshot/golden tests. -- Prefer making nondeterministic failures reproducible over adding sleeps/retries; do not mask flakiness. -- For timing/order/race issues, prefer deterministic synchronization (events, versioned state, acks/handshakes) over fixed sleeps. -- If a heuristic wait is unavoidable, it MUST be condition-based with a hard deadline and diagnostics, and requires explicit requester approval. -- For integration boundaries (network/DB/external services/UI flows), add an integration/E2E/contract test that exercises the boundary; avoid unit-only coverage for integration bugs. -- For non-trivial changes, create a small test matrix (scenarios × inputs × states) and cover the highest-risk combinations; document intentional gaps. - -## Feedback loops and root causes - -- Treat time-to-detect and time-to-fix as quality attributes; shorten the feedback loop with automation and observability rather than relying on manual QA. -- For any defect fix or incident remediation, perform a brief root-cause classification: implementation mistake, design deficit, and/or ambiguous/incorrect requirements. -- Feed the root cause upstream in the same change set: add or tighten tests/checks/alerts, update specs/acceptance criteria, and update design docs/ADRs when applicable. -- If the failure should have been detected earlier, add a gate at the earliest reliable point (lint/typecheck/tests/CI required checks or runtime alerts/health checks); skipping this requires explicit user approval. -- Record the prevention mechanism (what will catch it next time) in the PR description or issue comment; avoid “fixed” without a concrete feedback-loop improvement. - -## Exceptions - -- If required tests are impractical, document the coverage gap, provide a manual verification plan, and get explicit user approval before skipping. - -## Error handling and validation - -- Never swallow errors; fail fast or return early with explicit errors. -- Error messages must reflect actual state and include relevant input context. -- Validate config and external inputs at boundaries; fail with actionable guidance. -- Log minimally but with diagnostic context; never log secrets or personal data. -- Remove temporary debugging/instrumentation before the final patch. - -Source: github:metyatech/agent-rules@HEAD/rules/global/superpowers-integration.md - -# Superpowers integration - -- If Superpowers skills are available in the current agent environment, use them to drive *how* you work (design, planning, debugging, TDD, review) instead of inventing an ad-hoc process. -- Do not duplicate Superpowers installation/usage instructions in this ruleset; follow Superpowers’ own guidance for loading/invoking skills. -- The hard gates in this ruleset still apply when using Superpowers workflows: - - Before any state-changing work: present AC + AC->evidence + a plan, then wait for an explicit “yes”. - - After changes: report AC -> evidence outcomes and the exact verification commands executed. -- When a Superpowers workflow asks for writing docs / commits / pushes, treat those as state-changing steps: include them in the plan and require explicit requester approval before doing them. -- If Superpowers skills are unavailable, proceed with these rules as the fallback. +- If full-suite scope is unclear, run repo-default verify/CI commands rather than guessing. +- CI must run the full suite on PRs and default-branch pushes, require passing status checks for merges; if no CI exists, add one. Do not rely on smoke-only or scheduled-only gates. +- Configure required default-branch checks when permitted; otherwise report the limitation. +- Commit-time automation must run full verify and block commits; before first commit in a session, confirm hooks are installed (install if needed). If impossible, run full verify manually before every commit. +- Never disable checks, weaken assertions/types, or add retries solely to make checks pass. +- If environment limits execution (network/db/sandbox), run the available subset, document skipped coverage, ensure CI covers the remainder. +- For user-facing tools/GUI, run end-to-end manual verification in addition to automated tests; when manual testing finds issues, add failing tests first, then fix. +- Verify scripts must enforce lock-file integrity (manifest/lock drift detection). + +## Tests + +- Test-first: add/update tests, observe failure, implement fix, observe pass. +- Keep tests deterministic; minimize time/random/external I/O via injection. +- Heuristic waits require condition-based logic, hard deadlines, diagnostics, and explicit requester approval. + +## Error handling + +- Never swallow errors; fail fast with explicit errors reflecting actual state and input context. +- Validate config/external inputs at boundaries with actionable failure guidance. +- Log minimally with diagnostic context; never log secrets/personal data; remove debugging instrumentation before final patch. +- If required tests are impractical, document the gap, provide manual verification plan, and get explicit approval. + +Source: github:metyatech/agent-rules@HEAD/rules/global/release-and-publication.md + +# Release and publication + +- Include LICENSE in published artifacts (copyright holder: metyatech). +- Do not ship build/test artifacts or local configs; ensure a clean environment can use the product via README steps. +- Define a SemVer policy and document what counts as a breaking change. +- Keep package version and Git tag consistent. +- Run dependency security checks before release. +- Verify published packages resolve and run correctly before reporting done. + +## Public repository metadata + +- For public repos, set GitHub Description, Topics, and Homepage. +- Assign Topics from the standard set below. Every repo must have at least one standard topic when applicable; repos that do not match any standard topic use descriptive topics relevant to their domain. + - `agent-skill`: repo contains a SKILL.md (an installable agent skill). + - `agent-tool`: CLI tool or MCP server used by agents (e.g., task-tracker, agents-mcp, compose-agentsmd). + - `agent-rule`: rule source or ruleset repository (e.g., agent-rules). + - `unreal-engine`: Unreal Engine plugin or sample project. + - `qti`: QTI assessment ecosystem tool or library. + - `education`: course content, teaching materials, or student-facing platform. + - `docusaurus`: Docusaurus plugin or extension. +- Additional descriptive topics (language, framework, domain keywords) may be added freely alongside standard topics. +- Review and update the standard topic set when the repository landscape changes materially (new domain clusters emerge or existing ones become obsolete). +- Verify topics are set as part of the new-repository compliance gate. + +## Delivery chain gate + +- Before reporting a code change as complete in a publishable package, verify the full delivery chain (commit → push → version bump → release → publish → install verify). Do not stop mid-chain. +- Detailed delivery chain procedures are in the `release-publish` skill. + +Source: github:metyatech/agent-rules@HEAD/rules/global/skill-authoring.md + +# Skill authoring standards + +- Follow the Agent Skills open standard (agentskills.io/specification). +- SKILL.md frontmatter: only `name` (lowercase alphanumeric + hyphens, max 64 chars) and `description` (explain trigger conditions). +- SKILL.md body must be platform-agnostic: no platform-specific tool names. Write in terms of intent. +- Platform-specific examples belong in README.md, not SKILL.md. +- Each skill lives in its own repository with SKILL.md at root. +- Install/manage via `npx skills add / --yes --global`. +- Default to public repositories; include a LICENSE file (prefer MIT). +- Write SKILL.md and README.md in English; keep instructions concise and action-oriented. +- Do not duplicate rules already covered by AGENTS.md global rules; reference them instead. + +Source: github:metyatech/agent-rules@HEAD/rules/global/task-lifecycle-tracking.md + +# Task lifecycle tracking + +- When an actionable task emerges during a session, immediately record it with `task-tracker add` so it persists on disk regardless of session termination. +- `task-tracker` is the persistent cross-session tracker; session-scoped task tools (e.g., TaskCreate) are supplementary. Always use `task-tracker add` first; session-scoped tools may be used in addition but never as a replacement. +- At the start of any session that may involve state-changing work, run `task-tracker check` and report findings before starting new work. +- When reporting a task as complete, state the lifecycle stage explicitly (committed/pushed/released/etc.); never claim "done" when downstream stages remain incomplete. +- If `task-tracker` is not installed, install it via `npm install -g @metyatech/task-tracker` before proceeding. +- CLI: `task-tracker add "desc"` / `check` / `list` / `done ` / `remove ` / `update --stage ` — use `--stage`, NOT `--status`. +- Valid stages: `pending`, `in-progress`, `committed`, `pushed`, `released`, `done`. +- The task-tracker state file (`.tasks.jsonl`) must be committed to version control; do not add it to `.gitignore`. + +Source: github:metyatech/agent-rules@HEAD/rules/global/thread-inbox.md + +# Thread inbox + +- `thread-inbox` is the persistent cross-session conversation context tracker. Use it to preserve discussion topics, decisions, and context that span sessions. +- If `thread-inbox` is not installed, install it via `npm install -g @metyatech/thread-inbox` before proceeding. +- Store `.threads.jsonl` in the workspace root directory (use `--dir `). Do not commit it to version control. +- At session start, run `thread-inbox inbox` and `thread-inbox list --status waiting` to find threads needing attention; report findings before starting new work. +- Do not create threads for tasks already tracked by `task-tracker`; threads are for context and decisions, not work items. +- CLI: `thread-inbox new "title" --dir ` (must create before adding messages) / `add --from user|ai "msg" --dir ` / `inbox --dir ` / `list --status --dir `. +- If a thread captures a persistent behavioral preference, encode it as a rule and resolve the thread. +- Detailed usage procedures (status model, when to create/add messages, lifecycle) are in the `manager` skill. Source: github:metyatech/agent-rules@HEAD/rules/global/user-identity-and-accounts.md @@ -421,7 +385,11 @@ Source: github:metyatech/agent-rules@HEAD/rules/global/writing-and-documentation - Respond in Japanese unless the user requests otherwise. - Always report whether you committed and whether you pushed; include repo(s), branch(es), and commit hash(es) when applicable. -- After completing a response, emit the Windows SystemSounds.Asterisk sound via PowerShell when possible. +- After completing a response, emit the Windows SystemSounds.Asterisk sound via PowerShell only when operating in direct mode (top-level agent). +- If operating in delegated mode (spawned by another agent / sub-agent), do not emit notification sounds. +- If operating as a manager/orchestrator, do not ask delegated sub-agents to emit sounds; emit at most once when the overall task is complete (direct mode only). + +- When delivering a new tool, feature, or artifact to the user, explain what it is, how to use it (with example commands), and what its key capabilities are. Do not report only completion status; always include a usage guide in the same response. ## Developer-facing writing diff --git a/requirements-audit.txt b/requirements-audit.txt deleted file mode 100644 index 86dc3fb..0000000 --- a/requirements-audit.txt +++ /dev/null @@ -1,3 +0,0 @@ -robotframework>=7.0.0 -pywinauto>=0.6.8 -Pillow>=10.0.0 diff --git a/scripts/verify.ps1 b/scripts/verify.ps1 index e9b5100..f51f695 100644 --- a/scripts/verify.ps1 +++ b/scripts/verify.ps1 @@ -23,4 +23,4 @@ Invoke-VerifyCommand @("python", "-m", "ruff", "format", "--check", ".") Invoke-VerifyCommand @("python", "-m", "ruff", "check", ".") Invoke-VerifyCommand @("python", "-m", "pyright") Invoke-VerifyCommand @("python", "-m", "pytest") -Invoke-VerifyCommand @("python", "-m", "pip_audit", "-r", "requirements-audit.txt") +Invoke-VerifyCommand @("python", "-m", "pip_audit", ".")