Tooling

Commands and interfaces that make a preferred workflow repeatable.

60 items in this guidance cluster.

Tagged guidance

GuideAgent WorkflowAgent ContextVerificationCoding Agentscoding-agentsCoding-agent guidance covers task setup, repo-owned context, tools, workspaces, verification, handoff proof, feedback loops, and maintainer review flow. It treats agents as workers in a system whose output should be reviewable, durable, and easy to integrate.GuideVCS JJChange ShapeReviewabilityJJ Workflowjj-workflowJJ workflow guidance covers source-control inspection, reviewable changes, descriptions, bookmarks, publication, and recovery in jujutsu repositories. It keeps agents and maintainers thinking in jj changes and operations instead of Git-shaped habits.

RuleAgent WorkflowSecurity PrivacyBoundary CorrectnessGrant Scoped CapabilitiesAGENT-GRANT-SCOPED-CAPABILITIESGive agents only the permissions and external authority the task actually needs. Scoped capability keeps progress possible while reducing accidental mutation, publication, or exposure.RuleAgent WorkflowAutomationVerificationMake Bad Output HardAGENT-MAKE-BAD-OUTPUT-HARDTurn recurring bad agent output into scripts, templates, lint, or checks that fail fast. Mechanical enforcement lowers review cost more reliably than repeated prompt reminders.RuleAgent WorkflowLocal ConventionsPrefer In-Distribution ToolsAGENT-PREFER-IN-DISTRIBUTION-TOOLSUse standard project commands, supported CLIs, and documented workflows before inventing ad hoc tool paths. Familiar tools reduce misuse and make agent output easier to rerun.RuleAgent WorkflowAutomationDocumentationPrefer Tools Over PromptsAGENT-PREFER-TOOLS-OVER-PROMPTSMove repeated instructions into tools, checks, templates, or durable guides. Tooling catches failures even when prompts are short, compacted, or interpreted differently.

RuleBoundary CorrectnessSecurity PrivacySide EffectsGive Tools Identity Policy And LimitsBOUNDARY-GIVE-TOOLS-IDENTITY-POLICY-AND-LIMITSGive effectful callable units typed identity, authorization policy, cancellation, and bounded output. The added ceremony is reserved for real tool boundaries where auditability, recovery, and blast-radius control matter.RuleBoundary CorrectnessValidation PolicyState TransitionsMake Dynamic Conflicts DeterministicBOUNDARY-MAKE-DYNAMIC-CONFLICTS-DETERMINISTICDefine stable ordering, duplicate handling, priority, or override policy for dynamic registrations. Deterministic conflict behavior prevents hash order or load timing from changing which plugin, guest, generated item, or handler wins.RuleBoundary CorrectnessAutomationAgent WorkflowMake Exec Tools NoninteractiveBOUNDARY-MAKE-EXEC-TOOLS-NONINTERACTIVEDefault agent, CI, and background exec paths away from prompts, editors, pagers, and credential UI. Commands then fail or complete predictably, while human interactive modes remain explicit opt-ins.RuleBoundary CorrectnessSource TruthObservabilityTrack Dynamic Registration ProvenanceBOUNDARY-TRACK-DYNAMIC-REGISTRATION-PROVENANCEStore stable source names, versions, paths, owners, or generated identifiers for extension, guest, generated-code, and config registrations. Provenance makes conflicts and failures diagnosable while avoiding sensitive source details.RuleBoundary CorrectnessTestingLocal ConventionsTreat Terminal UI As Product SurfaceBOUNDARY-TREAT-TERMINAL-UI-AS-PRODUCT-SURFACETreat terminal layout, input, scroll behavior, color, viewport size, and platform differences as a user-facing contract when people rely on the interface. This makes regressions reviewable without requiring full visual testing for every tiny internal tool.RuleBoundary CorrectnessLocal ConventionsVerificationUse Conservative Terminal DefaultsBOUNDARY-USE-CONSERVATIVE-TERMINAL-DEFAULTSChoose first-run terminal behavior that works with limited color, small viewports, ordinary keyboard input, and varied fonts or accessibility settings. Advanced styling can remain opt-in or capability-detected after the baseline is readable and usable.

RuleDocumentationLocal ConventionsReviewabilityKeep Markdown LintableDOCS-KEEP-MARKDOWN-LINTABLEUse project Markdown style so formatting stays enforceable and review noise stays low. Treat lint exceptions as intentional local choices, not accumulated drift.RuleDocumentationVerificationVerify Commands, Paths, and LinksDOCS-VERIFY-COMMANDS-PATHS-AND-LINKSCheck commands, file paths, and linked references because readers treat them as executable instructions. Note assumptions when credentials, services, or platforms prevent a full run.

RulePerformanceVerificationSource TruthRecord Benchmark ProvenancePERF-RECORD-BENCHMARK-PROVENANCERecord the commands, inputs, tool versions, build profile, and runner conditions behind benchmark numbers. Provenance makes future comparisons meaningful and helps separate real changes from environment drift.

RuleRustRustdocDocumentationConfigure docs.rsRUST-CONFIGURE-DOCS-RSConfigure docs.rs metadata when features, cfgs, or rustdoc flags affect rendered API docs. Users should see the documentation surface the crate expects to support.RuleRustSecurity PrivacyAutomationDeny Accidental UnsafeRUST-DENY-ACCIDENTAL-UNSAFEUse a crate-level lint when a crate intends to avoid unsafe code entirely. Executable policy catches accidental unsafe before it becomes normal implementation detail.RuleRustAutomationLocal ConventionsEncode Durable Rules in LintsRUST-ENCODE-DURABLE-RULES-IN-LINTSUse lint configuration for project policies stable enough to automate. Durable lints catch repeated mistakes without turning subjective taste into CI noise.RuleRustAutomationFailure OutputKeep Lints ActionableRUST-KEEP-LINTS-ACTIONABLEEnforce lints that improve correctness, API quality, docs, portability, or maintenance in ways reviewers want automated. Scope suppressions tightly so exceptions stay visible.RuleRustAutomationReviewabilityPrefer Expect For Lint SuppressionsRUST-PREFER-EXPECT-FOR-LINT-SUPPRESSIONSUse #[expect] for targeted lint suppressions that should disappear when the warning is fixed. Reserve broad allow attributes for deliberate policy choices that are not expected to expire.

RuleTestingAutomationVerificationCheck Maintainer Commands in CITEST-CHECK-MAINTAINER-COMMANDS-IN-CIPut documented maintainer commands, or intentionally stronger equivalents, in CI. This keeps local instructions honest while leaving slow or credentialed checks to special jobs.RuleTestingVerificationPrefer Deterministic TestsTEST-PREFER-DETERMINISTIC-TESTSPrefer tests controlled by fixed inputs, clocks, ordering, and local state. Deterministic failures are reproducible, while real integration checks should be isolated by cost.RuleTestingVerificationProve Command Construction and DisplayTEST-PROVE-COMMAND-CONSTRUCTION-AND-DISPLAYTest both executable command shape and displayed command text when users rely on them. Quoting, redaction, ordering, and platform formatting can fail even when a local happy path works.RuleTestingAutomationReviewabilityRun Fast Format and Lint Gates EarlyTEST-RUN-FAST-FORMAT-AND-LINT-GATES-EARLYRun cheap format and lint gates early in the feedback loop. They remove mechanical failures quickly, but they do not replace validation of risky behavior.

RuleVCS JJLocal ConventionsReview HandoffAsk Before Repairing JJ AliasesVCS-ASK-BEFORE-REPAIRING-JJ-ALIASESAsk before changing jj aliases when they disagree with the observed repository topology. Aliases encode workflow policy, so silent repairs can alter future user commands.RuleVCS JJAgent WorkflowAutomationAvoid Interactive JJ in Agent WorkVCS-AVOID-INTERACTIVE-JJ-IN-AGENT-WORKUse noninteractive jj commands with explicit messages, targets, and files in agent work. Interactive editors, prompts, merge tools, and pagers can hang unattended sessions.RuleVCS JJAgent WorkflowConfigure JJ PagerVCS-CONFIGURE-JJ-PAGERScope pager control with --no-pager, JJ_PAGER=cat, or session configuration. Direct output keeps source-control evidence visible without changing the users global pager.RuleVCS JJSource TruthDo Not Fall Back to Git for JJ IssuesVCS-DO-NOT-FALL-BACK-TO-GIT-FOR-JJ-ISSUESDiagnose jj locks, pager issues, and state problems through jj before switching tools. Git bypasses jj change-graph semantics, so use it only for transport after jj state is coherent.RuleVCS JJSource TruthInspect Sparse StateVCS-INSPECT-SPARSE-STATECheck sparse checkout state before treating a missing path as absent from history. Sparse patterns can hide files, so inspection prevents recreating or editing the wrong path.RuleVCS JJSource TruthJJ as Source of TruthVCS-JJ-AS-SOURCE-OF-TRUTHUse jj for local workflow in repositories with .jj state. This preserves descriptions, stack shape, operation-log recovery, and bookmark semantics.RuleVCS JJSource TruthReview HandoffMatch JJ Topology to Repo RoleVCS-MATCH-JJ-TOPOLOGY-TO-REPO-ROLEAlign fetch remotes, push remotes, tracked bookmarks, aliases, and PR bases to repo role. Owned, maintainer, and fork-only workflows need different topology assumptions.RuleVCS JJVerificationReviewabilityName Exact JJ Mutation TargetsVCS-NAME-EXACT-JJ-MUTATION-TARGETSSpecify revisions, filesets, bookmarks, and destinations for mutating jj commands. Explicit targets make intent reviewable and prevent defaults from acting on surprising state.RuleVCS JJAutomationQuote Revsets and Shell SyntaxVCS-QUOTE-REVSETS-AND-SHELL-SYNTAXQuote jj revsets, bookmark syntax, and other shell-sensitive command fragments. Shell metacharacters can alter commands, so examples should prefer simple safe quoting.RuleVCS JJSource TruthReview HandoffRepair Remote Topology CoherentlyVCS-REPAIR-REMOTE-TOPOLOGY-COHERENTLYRepair fetch, push, tracking, trunk alias, PR base, and PR head assumptions together. Remote topology is coupled, so partial fixes can leave publication commands half-correct.RuleVCS JJAutomationAgent WorkflowRun JJ Mutations SequentiallyVCS-RUN-JJ-MUTATIONS-SEQUENTIALLYDo not overlap jj commands that write repo, working-copy, bookmark, or config state. Sequential mutations avoid locks, stale reads, and confusing operation order.RuleVCS JJVerificationStop Repeated JJ Retries And Localize StateVCS-STOP-REPEATED-JJ-RETRIES-AND-LOCALIZE-STATEStop repeating a failing jj command after a transient retry and inspect relevant state. Diagnosis beats command spam when locks, sparse paths, bookmarks, or remotes disagree.RuleVCS JJSource TruthTreat Bookmark Remote Syntax as Version SensitiveVCS-TREAT-BOOKMARK-REMOTE-SYNTAX-AS-VERSION-SENSITIVEVerify bookmark@remote and remote-bookmark syntax against the installed jj version. Durable guidance should avoid assuming one spelling works across commands and releases.RuleVCS JJAgent WorkflowReview HandoffUse Git-Formatted Diffs for AgentsVCS-USE-GIT-FORMATTED-DIFFS-FOR-AGENTSPrefer jj diff --git when agents or patch-oriented tools need diff text. Git patch format preserves hunks and paths in a shape those consumers can parse reliably.RuleVCS JJVerificationUse Ignore Working Copy CarefullyVCS-USE-IGNORE-WORKING-COPY-CAREFULLYUse --ignore-working-copy only for understood lock-safe inspection or metadata work. It may read stale file state, so do not use it to bypass normal synchronization before edits.RuleVCS JJAgent WorkflowChange ShapeWorkspace Add for Second CheckoutsVCS-WORKSPACE-ADD-FOR-SECOND-CHECKOUTSUse jj workspace add only when a task needs another filesystem checkout. Ordinary review separation should use jj new; workspaces fit clean validation or parallelism.

PatternLocal ConventionsAgent WorkflowReviewabilityChoose Good Enough Toolschoose-good-enough-toolsTooling choices can become a distraction when the available tool is already adequate for the risk. Prefer the simplest tool that gives trustworthy feedback, upgrading only when accuracy, repeatability, or scale requires it.PatternSource TruthAutomationAgent WorkflowCode Is Memory Of Processcode-is-memory-of-processCode accumulates the history of decisions, shortcuts, and workflows that produced it. When changing it, preserve useful operational memory while removing obsolete process scars that no longer serve readers.PatternAgent WorkflowSecurity PrivacyGrant Scoped Agent Capabilitiesgrant-scoped-agent-capabilitiesBroad tool access increases the blast radius of agent mistakes and makes review harder. Grant the smallest capabilities needed for the current task, then expand deliberately when the work proves it needs more reach.PatternAutomationOwnershipLocal ConventionsKeep Automations Repo Ownedkeep-automations-repo-ownedCritical checks and generation steps become fragile when they live only in personal scripts or local memory. Put repeatable automation in the repository so agents and humans can run the same workflow.PatternAutomationAgent WorkflowVerificationMake Bad Output Mechanically Hardmake-bad-output-mechanically-hardRepeated review failures usually belong in a tool, type, schema, template, lint, or checklist instead of another reminder. Encode stable rejection criteria early, but keep escape hatches when legitimate exceptions are common.PatternChange ShapeReviewabilityMake The Change Easy Firstmake-the-change-easy-firstSome changes are risky because the path to make or verify them is unnecessarily hard. First add the smallest harness, boundary, helper, tool, or runbook that makes the real change cheaper to understand and review.PatternLocal ConventionsAgent WorkflowPrefer In Distribution Toolsprefer-in-distribution-toolsUnusual tools, layouts, and formats consume agent attention before domain work begins. Prefer common, stable conventions when they meet the need, and document specialized choices when the domain honestly requires them.PatternAutomationAgent WorkflowPrefer Tools Over Promptsprefer-tools-over-promptsProse instructions are weak guardrails for repeatable constraints because agents can forget or apply them too late. Use tools, tests, templates, and checks for mechanical preferences, while reserving prompts for judgment and tradeoffs.PatternAgent ContextFailure OutputShape Tool Output For Agentsshape-tool-output-for-agentsHuman-oriented tool output can bury the failure signal an agent needs to act. Prefer quiet summaries, structured output, and saved full logs so agents see the actionable slice first without losing debugging context.PatternAutomationAgent WorkflowTeach Agents Through Toolsteach-agents-through-toolsRepeated agent confusion often means the repo lacks a command, fixture, wrapper, or check rather than another instruction. Convert repeatable setup, inspection, validation, and remediation into tools when they will improve future runs.

PrincipleAgent WorkflowAutomationAgent ContextAgent Instructions Are Operational Controlsagent-instructions-are-operational-controlsAgent instructions should change future behavior, not merely restate a preference. Compact rules need enough trigger, purpose, and boundary context for agents to apply them without blind literalism.PrincipleVCS JJReview HandoffJJ Topology Is Repo Role Dependentjj-topology-is-repo-role-dependentJJ publication behavior depends on whether the checkout is owned, maintained, or fork-based. Align remotes, bookmarks, trunk, and GitHub handoff with that role before mutating public state.PrincipleAutomationAgent WorkflowReviewabilityMechanize Repeated Feedbackmechanize-repeated-feedbackRepeated corrections should become checks, templates, generators, lints, or reusable guidance when the pattern is stable. Mechanizing the feedback moves human attention back to judgment instead of recall.

MechanismAutomationDocumentationSource TruthGuidance Generation And Auditguidance-generation-and-auditGenerators and audits keep rule indexes, compressed agent snippets, downstream templates, and Markdown synchronized. The checks catch recurring drift so review attention stays on judgment instead of mechanical bookkeeping.MechanismVCS JJAgent WorkflowAgent ContextJJ Agent Workflowjj-agent-workflowNoninteractive jj defaults, topology checks, and local override conventions make agent source-control work safer. The mechanism keeps local workflow state explicit without leaking private checkout assumptions into shared artifacts.MechanismRustAutomationDocumentationRust Lints And Formattingrust-lints-and-formattingRust and Markdown formatting plus targeted project lints encode stable mechanical preferences. The mechanism removes repeat style debate from review while leaving design judgment to humans and higher-level guidance.MechanismRustAutomationVerificationRust Tooling Profilerust-tooling-profileThe broad Rust tooling profile gathers lints, docs, release, CI, performance, and agent workflow checks in one place. Use it as a menu of mechanical supports, not as a substitute for project-specific risk judgment.MechanismTestingPerformanceVerificationTesting And Benchmarkingtesting-and-benchmarkingTest, feature-matrix, fuzzing, property, and benchmark tools should be chosen by risk and feedback cost. This mechanism helps match validation depth to the behavior, integration surface, or performance claim under review.

AgentAgent WorkflowAgent ContextReview HandoffCoding Agent Workflow Instructionsagent-coding-workflow-instructionsCompact workflow instructions for repositories that delegate implementation or review work to coding agents. The snippet emphasizes objectives, boundaries, durable handoff, repo-owned context, and feedback that becomes reusable guidance.AgentVCS JJAgent WorkflowReview HandoffJujutsu Agent Instructionsagent-jj-instructionsCompact source-control instructions for coding agents working in repositories that use jujutsu. The snippet covers fresh changes, descriptions, non-interactive commands, recovery, remote handoff, and publication approval.