shunta-sato/agent-instructions-playbook

branch-completion

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.

bug-investigation-and-rca

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

execution-plans

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

failure-retrospective

Use at a stable checkpoint or closeout after rollback, abandoned/rejected approaches, material rerouting, repeated failure, two+ materially different attempts, a rejected completion claim, or an explicit lessons-learned request; routes learning to task,…

preflight-engineering

Preflight, AGENTS.md, agent context, skill routing, test routing, subagent handoff, prompt caching readiness. Use before long-running, multi-agent, unfamiliar, high-risk, or cross-service coding tasks. Do not use for small one-file edits.

research-synthesis

Use when more than five experiment results have accumulated without synthesis, at a research decision point, or before promoting a research finding into a delivery path. Reads the experiment ledger for knowledge deltas — supported, falsified, still-open — to…

dev-workflow

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

hardening-workflow

Use for delivery-mode tasks whose purpose is quality improvement on shipped code: closing high-risk coverage gaps, structure-budget findings, flaky tests, missing observability, or smell density on a named path. Sequences a measured baseline, risk-tiered…

project-structure

Use when creating a new source file, module, crate, or package, when deciding where code or tests should live, or when a touched file exceeds the structure budget (scripts/check_structure.py). Gives forward-looking physical layout rules: entrypoint vs library…

quality-gate

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

refactor-workflow

Use for delivery-mode tasks whose purpose is structural change with no intended behavior change: extracting, moving, or renaming code, replacing a flawed abstraction, or consolidating duplication. Sequences a behavior lock, the owning structural-change skill,…

agent-workflow-contract-review

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…

uidesign-flow

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

comment-discipline

Use only when explicitly asked to clean up AI-narration/redundant comments in a diff, or to adjudicate comment vs. commit-message vs. test-name content for a specific change. The always-on Why-not comment rule lives in AGENTS.md; this skill is the explicit…

code-smells-and-antipatterns

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…

destructive-refactor

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

embedded-hot-path-review

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…

embedded-nfr-calibration

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.

embedded-nfr-design

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…

embedded-nfr-gate

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.

embedded-nfr-harness-design

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…

embedded-observer-effect-review

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.

embedded-operating-envelope-discovery

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.

embedded-project-constitution

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…

embedded-system-familiarization

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…

embedded-target-characterization

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.

function-boundary-governor

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

playbook-template-authoring

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…

preflight-api-compat

Preflight public API compatibility, OpenAPI, GraphQL, generated clients, public error shapes, versioning. Use before API-facing changes or generated client updates.

preflight-auth-session

Preflight auth, OAuth, refresh token, session, JWT, cookie, CSRF, login redirect, token logging. Use before auth/session/security-sensitive implementation or multi-agent investigation.

preflight-db-migration

Preflight DB migration, schema change, rollback, backfill, data compatibility, transaction boundary. Use before database or persistence-layer changes.

preflight-domain-template

Template for authoring domain preflight skills that extract invariants, first docs/files, AGENTS.md proposals, .agent/ctx maps, test routing, approvals, reviewers, and handoff fragments. Use when creating or reviewing a new preflight-* domain skill, not…

project-initialization

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

requirements-engineering

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…

research-workflow

Use when the task's epistemic mode is research: exploratory optimization, feasibility probes, model/architecture exploration, benchmark investigation, or proof-of-concept work where learning per unit cost matters more than shipping. Routes probes to…

thread-safety-tooling

Thread-safety verification toolkit. Use when C/C++ code introduces threads/locks/atomics or when race conditions/deadlocks are plausible. Provides TSan and compile-time thread-safety analysis guidance.

tonemana-apply

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.

tonemana-catalog

Create or update a comparable Tone & Manner catalog with 7 default patterns, tokens, and preview HTML. Use before choosing a visual/voice pattern for UIUX or UIDesign work.

uidesign-orchestrator

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.

uiux-core

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.