agent-instructions-playbook

Use when finishing a branch or PR after verification and review, including merge, PR publication, keep, discard, cleanup, local sync, and reporting merge or PR URLs with current git state.

Use when handling received code-review feedback on a PR or diff, including requested changes, inline comments, approvals, non-blocking notes, and disputed suggestions. Separates accepted fixes, refutations, deferrals, clarification needs, and merge handoff.

Use when preparing a focused code-review request for a PR or diff after implementation evidence exists, especially to package scope, reviewer focus, PR URL, verification, known risks, and deferred work without deciding final submit readiness.

Use before every submission to decide whether required checks, artifacts, and branch evidence are complete enough to submit.

Use when work is complex, long-running, multi-step, cross-boundary, likely to span multiple PRs/sessions, or needs handoff-ready planning under plans/.

Use when adding or changing Agent-facing workflows, generated prompts, collect plans, executable handoff artifacts, CLI workflows, controller/target-local workflow chains, or validation artifacts consumed by downstream reports. Do not use for ordinary code changes without an Agent-facing workflow or generated instruction surface.

Use when fixing or investigating crashes, regressions, flakes, hangs, incorrect outputs, or incidents.

Use before feature-level implementation that adds two or more classes/modules, introduces a new layer/interface, or adds a second reason-to-change to an existing class/module. Do not use for function-only helper/API decisions or cross-boundary architecture option comparison.

Use for any task that changes code or tests. Routes implementation work by risk and applicable branch skills before editing.

Use when COMMANDS.md is uninitialized, contains <fill>, or the repository lacks verified canonical build, lint, test, and verify commands.

Use when implementing low-level or strict-constraint code (kernels, SIMD/intrinsics, alignment/padding rules, codegen/DSLs, strict ABI or hardware APIs), or when direct implementation repeatedly fails to compile/test.

Use when doing TDD or when dev-workflow routes implementation through a Test List.

Use when an approved tone-and-manner decision must become concrete UI styling tokens and visual previews.

Use only for explicit end-to-end UI evidence orchestration across UIUX, Tone & Manner, and UIDesign packs. Do not trigger for ordinary single-step UIUX, Tone & Manner, or UIDesign work.

Use for platform-agnostic UI/UX design or review work that needs a deterministic UIUX Pack. Also use for web, iOS, or Android UIUX work with the matching platform adapter.

Use when a UIUX Pack needs a transition-map preview from ui_spec.json with pan/zoom, minimap, focus traversal, and Review Mode.

Use when UI changes require repo-defined snapshot or visual-diff verification, baseline review, or a UI Visual Verification Report.

Use when touching code without reliable automated tests or with nondeterminism such as time, randomness, or I/O.

Use after embedded physical budgets exist, or when an embedded daemon/logger/recorder/sampler needs resource, battery, wakeup, flash, thermal, latency, or observer-overhead measurement. Do not use for performance advice without a target-local physical footprint.

Use when embedded, edge, target-local, robot, Android, ROS 2, kernel/driver-adjacent, sensor, logger, recorder, or daemon work requires understanding target behavior, hardware capability, operating envelope, bottlenecks, or NFR provenance before design or optimization. Do not use for small changes with current characterization and no runtime/architecture impact.

Use before and after normal/high-risk implementation when a complexity budget is needed: declare new classes/helpers/wrappers/indirection/estimated lines, justify each new abstraction, and delete or inline abstractions that are not worth their weight. Do not use for low-risk one-file changes with no new abstraction, public API change, or behavior expansion.

Use when reviewing embedded or target-local loops, polling, sampling, collectors, recorders, sub-100ms work, per-iteration I/O, repeated serialization, or hot-path allocation. Do not use for non-embedded application request/render/job paths; use performance-review there.

Use when a runtime behavior change needs diagnosable signals: async/background jobs, external calls, user-visible operations, or incident-prone flows. Do not use for docs-only or refactor-only changes with no behavior shift.

Use when non-embedded application code changes request paths, render paths, input-proportional collection processing, loop I/O, N+1 queries, repeated serialization/allocation, serial awaits, or cache/memoization decisions. Declare hot paths, complexity, I/O counts, scale assumptions, and improve-or-accept decisions. For target-local embedded hot paths, use embedded-hot-path-review instead.

Use only when explicitly authoring or revising reusable, repo-neutral playbook/template skills for deployment, infrastructure operations, data fetching/analysis, or library/API reference guidance. Do not use for normal E2E implementation, executing deployments, running infrastructure changes, one-off data analysis, or applying a library directly.

Use for ambiguous or non-trivial feature planning and requirements documentation: problem framing, spec-before-build checks, requirements briefs/specs, EARS-style requirements, acceptance criteria, traceability, and ISO/IEC 25010 quality scenarios. Do not use for tiny unambiguous implementation tasks, architecture option comparison, or diff-focused design review unless requirements output is requested.

Use before implementation or during explicit design review when a cross-boundary technical decision requires comparing multiple architecture options against measurable quality drivers, risks, tradeoffs, and verification tasks. Do not use for ordinary implementation, requirements drafting, diff-focused smell review, function/helper/API boundary decisions, observability instrumentation details, or final submit gating.

Trigger only for requested readability review/cleanup, touched-code readability work involving comments, names, control flow, function shape, or test clarity, touched C++ headers, or dev-workflow routing to the C++ documentation gate. Do not trigger for ordinary implementation solely because code changed. Enforces mandatory C++ Doxygen and readability documentation gates.

Review the current diff for new or worsened maintainability/design issues: code smells, architecture boundary leaks, weak cohesion, and risky coupling. Use for structural changes, public APIs, adapters/integrations, or design review; avoid generic full-codebase audits.

Autonomous function-boundary design workflow for functions/helpers/APIs/call sites: decide keep/rename/split/merge/replace/inline/no-op, apply coherent changes, verify, and record boundary decisions. Use design-balance instead for module/class responsibility layout.

Use after target characterization or operating-envelope discovery to derive embedded NFR budgets with provenance, confidence, and revisit conditions. Do not use to invent budgets without target evidence unless explicitly marking them provisional.

Use to discover normal, near-boundary, degraded, failure-adjacent, and logging/telemetry blackout behavior for embedded targets before calibrating NFR budgets. Do not use for ordinary performance benchmarking without an embedded target envelope question.

Use when starting an embedded, edge, target-local, daemon/logger/recorder/collector project or introducing that runtime class into an existing repo, to create project-level physical budgets, target profiles, harness skeletons, and no-claim rules. Do not use for ordinary project initialization without embedded physical constraints.

Use before embedded NFR budgeting when the target system, workload, measurement surfaces, resource headroom, or normal operating baseline are not yet characterized. Do not use for generic implementation work with known target budgets.

Use before implementing embedded, edge, target-local, daemon, logger, recorder, collector, sampler, polling-loop, or resource-sensitive always-on behavior to define physical NFR budgets and measurement claims. Do not use for generic backend, web, or schema-only work with no target-local physical footprint.

Use before final submit readiness when embedded NFR design or harness work was triggered, to decide submit/no-submit from physical budgets, measurements, unknowns, and claims. Do not use as a generic quality gate.

Use when target-local logging, recording, collection, tracing, profiling, or measurement could change scheduler, power, thermal, I/O, memory, wakeup, or workload behavior. Do not use for ordinary server observability with no embedded physical-footprint risk.

AI-led replacement protocol for flawed abstractions, allowing temporary red state while migrating call sites and converging back to green or rollback.

Use when a change defines or reviews failure contracts: boundary error translation, nullability/sentinel choices, retries/fallbacks, or API/user-visible failure behavior. Do not use for ordinary validation copy edits or pure logging changes with no failure-contract change.

Apply a selected Tone & Manner pattern to an existing UIUX Pack by producing a versioned Tonemana Pack and wiring references into UIUX artifacts. Use when a human has selected, or asks to choose and apply, a tone/manner pattern for a UI project.