Agent Workflow

How coding-agent work is scoped, executed, checked, and handed back.

74 items in this guidance cluster.

Tagged guidance

GuideAgent ContextToolingVerificationCoding 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.

RuleVerificationReview HandoffFeedback LoopsBudget for Feedback LoopsAGENT-BUDGET-FOR-FEEDBACK-LOOPSReserve enough time and tokens for checks, failure inspection, and handoff proof. Planning for the feedback loop keeps validation from being squeezed out after the first edit.RuleReviewabilityPublic APIDocumentationDefine Good Before Judgment-Heavy WorkAGENT-DEFINE-GOOD-BEFORE-JUDGMENT-HEAVY-WORKState the quality bar before work where taste, naming, API shape, or review expectations matter. Clear criteria give the agent goalposts before it creates a large speculative diff.RuleLocal ConventionsSource TruthDocumentationDistill From Blessed ArtifactsAGENT-DISTILL-FROM-BLESSED-ARTIFACTSStudy accepted code, docs, tests, and reviews first. Adapt local convention to this task.RuleSecurity PrivacyPerformanceVerificationEncode Nonfunctional RequirementsAGENT-ENCODE-NONFUNCTIONAL-REQUIREMENTSPut invisible constraints such as security, accessibility, latency, and compatibility near the task. Encoding them upfront makes those requirements part of the implementation target.RuleAgent ContextBoundary CorrectnessReview HandoffGive Objectives With BoundariesAGENT-GIVE-OBJECTIVES-WITH-BOUNDARIESDescribe the outcome, scope, non-goals, forbidden moves, and proof instead of handing over brittle steps. Boundaries preserve intent while leaving room for local implementation choices.RuleSecurity PrivacyToolingBoundary 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.RuleVCS JJChange ShapeReviewabilityIsolate Workspaces by TaskAGENT-ISOLATE-WORKSPACES-BY-TASKPut separable or parallel agent work in its own workspace or source-control lane. Isolation keeps diffs, validation, and ownership clear when multiple changes are in flight.RuleAgent ContextSource TruthDocumentationKeep Durable Context on DiskAGENT-KEEP-DURABLE-CONTEXT-ON-DISKStore project facts, accepted decisions, and long-lived operating notes in files instead of relying on chat context. Durable context makes future sessions and reviews resumable.RuleSecurity PrivacyAgent ContextKeep Secrets Out of ContextAGENT-KEEP-SECRETS-OUT-OF-CONTEXTAvoid putting real credentials or sensitive values into prompts, docs, logs, and tests. Keeping secrets out of context reduces leakage through retained, repeated, or committed text.RuleToolingAutomationVerificationMake 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.RuleChange ShapeVerificationTestingPrefer Build-Preserving EditsAGENT-PREFER-BUILD-PRESERVING-EDITSMake multi-step edits in slices that keep compilation or tests close to green when the route allows it. Build-preserving work keeps failures close to the edit that caused them.RuleToolingLocal 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.RuleToolingAutomationDocumentationPrefer 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.RuleReview HandoffReviewabilityChange ShapePresent Concrete Next OptionsAGENT-PRESENT-CONCRETE-NEXT-OPTIONSAfter a validated chunk, offer specific follow-up chunks with their tradeoffs. Concrete options let the maintainer steer scope without decoding vague requests to continue.RuleChange ShapeOwnershipVCS JJPreserve Human WorkAGENT-PRESERVE-HUMAN-WORKInspect and protect unrelated local edits before changing files. Preserving human work keeps the task diff focused and avoids destroying unfinished or intentional changes.RuleAgent ContextReviewabilityPreserve IntentAGENT-PRESERVE-INTENTOptimize for the users underlying objective when literal wording would miss the point. Intent-preserving work keeps changes aligned with the real readability, review, or behavior goal.RuleReview HandoffVerificationDocumentationProduce Review PacketsAGENT-PRODUCE-REVIEW-PACKETSHand off agent work with purpose, changed files, evidence, skipped checks, risks, and follow-ups. A review packet lets maintainers inspect the output without replaying the session.RuleSecurity PrivacyVerificationReview HandoffProve Security ImpactAGENT-PROVE-SECURITY-IMPACTSeparate security hypotheses from proof of reachability, exploitability, assets, and user impact. This keeps prioritization and mitigation tied to demonstrated risk.RuleReview HandoffVerificationTestingReport Proof in HandoffsAGENT-REPORT-PROOF-IN-HANDOFFSReplace confidence language with the exact checks, inspection, screenshots, and skipped validation behind a handoff. Proof lets reviewers decide what to trust and what remains risky.RuleReviewabilityReader LocalityReview HandoffReview Output as Future MaintainerAGENT-REVIEW-OUTPUT-AS-FUTURE-MAINTAINERReview agent output as someone who will not have the chat transcript. This keeps attention on durable code, docs, tests, validation proof, and residual risk.RuleAgent ContextReviewabilityChange ShapeSeparate Notes From CorrectionsAGENT-SEPARATE-NOTES-FROM-CORRECTIONSCapture fast-review notes before fixing them when there are multiple comments or unclear patterns. Separating capture from correction preserves signal and supports coherent follow-up.RuleAgent ContextReviewabilityPublic APISpend Human Attention on AmbiguityAGENT-SPEND-HUMAN-ATTENTION-ON-AMBIGUITYAsk for human judgment where product behavior, API compatibility, naming, or security posture is still ambiguous. Resolving direction early prevents large speculative diffs.RuleLocal ConventionsAgent ContextSource TruthSuggest Local Override FilesAGENT-SUGGEST-LOCAL-OVERRIDE-FILESPut checkout-only facts in ignored override files instead of shared guidance. Local overrides keep machine-specific steering useful without leaking it to every contributor.RuleDocumentationAutomationReviewabilityTurn Feedback Into GuidanceAGENT-TURN-FEEDBACK-INTO-GUIDANCEConvert repeated review corrections into rules, templates, snippets, or checks. Durable guidance fixes the workflow problem instead of requiring the same steering again.RuleAgent ContextDocumentationSource TruthUse AGENTS.md as MapAGENT-USE-AGENTS-MD-AS-MAPKeep AGENTS.md compact by using it to route agents to deeper guides and mechanisms. Treating it as a map preserves startup context without losing durable project guidance.RuleVerificationReleaseAutomationVerify Risky Changes With CanariesAGENT-VERIFY-RISKY-CHANGES-WITH-CANARIESUse staged rollout, shadowing, dry runs, or partial publication for changes that can fail only under real conditions. Canaries reduce blast radius while evidence accumulates.

RuleBoundary CorrectnessToolingAutomationMake 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.

RuleDocumentationReviewabilityExamplesExpose Move, Risk, and Example in PatternsDOCS-EXPOSE-MOVE-RISK-AND-EXAMPLE-IN-PATTERNSGive pattern guidance a recognizable trigger, preferred move, risk, example, and agent instruction. The extra structure makes repeatable advice easier to cite and apply.

RuleReviewabilityChange ShapeSeparate Discovery, Selection, and ImplementationREVIEW-SEPARATE-DISCOVERY-SELECTION-IMPLEMENTATIONSplit problem discovery, solution selection, and implementation review when they require different decisions. This keeps design debate out of patch correctness review once scope or direction is still unsettled.

RuleSource TruthLocal ConventionsDocumentationGeneralize Project-Specific RulesSOURCE-GENERALIZE-PROJECT-SPECIFIC-RULESExtract the portable failure mode before promoting local lessons into shared guidance. Provider, repo, or tool details should stay local unless they clarify the durable rule.

RuleVCS JJToolingAutomationAvoid 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 JJToolingConfigure 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 JJToolingAutomationRun 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 JJReview HandoffToolingUse 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 JJChange ShapeToolingWorkspace 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.

PatternReviewabilityAgent ContextDocumentationAsk What Were You Trying To Achieveask-what-were-you-trying-to-achieveRecover the original intent before judging a surprising design. Separating purpose from mechanism makes it easier to preserve useful constraints while replacing stale structure.PatternAgent ContextVerificationFeedback LoopsBudget Tokens For Feedback Loopsbudget-tokens-for-feedback-loopsLong-running agent work can exhaust context before validation, review, or handoff happens. Reserve space for feedback loops by summarizing durable state and avoiding unnecessary transcript growth.PatternToolingLocal ConventionsReviewabilityChoose 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.PatternVerificationReview HandoffFeedback LoopsClose The Agent Loopclose-the-agent-loopAgent work is incomplete when it stops at edits without checking the result or explaining residual risk. Finish the loop by validating, reporting evidence, and making the next human decision clear.PatternSource TruthToolingAutomationCode 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.PatternVerificationReviewabilityDefine Good Before Judgment-Heavy Workdefine-good-before-judgment-heavy-workWork that depends on taste or judgment drifts when success is not defined up front. Establish acceptance criteria, examples, and review dimensions before spending effort on subjective iteration.PatternAgent ContextDocumentationDeliver Context Just In Timedeliver-context-just-in-timeToo much context up front overloads the reader, while too little context forces rediscovery. Provide the next useful fact at the point of decision, linking outward when deeper background is optional.PatternVerificationSecurity PrivacyPerformanceEncode Nonfunctional Requirementsencode-nonfunctional-requirementsPerformance, security, accessibility, privacy, and reliability expectations are easy to lose when they live only in prose. Encode important requirements in tests, budgets, schemas, automation, or review gates where the system can keep enforcing them.PatternAgent ContextSource TruthAutomationGarbage Collect Agent Driftgarbage-collect-agent-driftAgent-generated notes, plans, and assumptions can outlive their usefulness and mislead later work. Periodically remove, update, or promote them so durable guidance stays current and temporary scaffolding does not become false context.PatternAgent ContextBoundary CorrectnessGive Agents Objectives With Boundariesgive-agents-objectives-with-boundariesAgents perform better when they know both the desired outcome and the limits around scope, authority, and risk. State objectives with concrete boundaries so the agent can act autonomously without expanding the task accidentally.PatternSecurity PrivacyToolingGrant 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.PatternAgent ContextVCS JJOwnershipIsolate Agent Workspacesisolate-agent-workspacesShared worktrees make it easy for agent edits, generated files, or validation steps to collide with unrelated work. Use isolated workspaces when concurrent tasks or uncertain changes need clear ownership and cleanup.PatternAutomationToolingVerificationMake 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.PatternSource TruthReview HandoffMake Plans Versioned Artifactsmake-plans-versioned-artifactsChat-only plans are difficult to review, resume, cite, or keep current once work spans sessions. Put substantial plans in the repository with goals, constraints, progress, decisions, and open questions, while keeping obvious one-step edits lightweight.PatternAgent ContextSource TruthManage Agent Work Not Sessionsmanage-agent-work-not-sessionsInteractive sessions do not scale when the maintainer must remember every thread, terminal, and handoff. Represent agent work as durable tasks with states, owners, validation, and review criteria so humans spend attention on priorities and judgment.PatternAgent ContextReader LocalityOptimize For Agent Legibilityoptimize-for-agent-legibilityRepositories that are hard for agents to inspect, search, run, and validate make delegated work slower and less reliable. Prefer structures, commands, names, examples, and runtime signals that help both agents and human maintainers reason locally.PatternVerificationAutomationFeedback LoopsPractice Agent Workoutspractice-agent-workoutsHigh-risk or repeated agent workflows are unreliable when first exercised during real work. Build safe practice tasks with explicit win conditions so the workflow, skill, or runbook can improve before pressure arrives.PatternToolingLocal ConventionsPrefer 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.PatternToolingAutomationPrefer 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 ContextReview HandoffPreserve Agent Context Coherencepreserve-agent-context-coherenceMixing unrelated work pollutes the sessions attention, working-copy state, and handoff narrative. Keep each session and jj change focused on one purpose, splitting work when ownership, validation, or review decisions diverge.PatternReview HandoffAgent ContextPreserve Intent Over Literalismpreserve-intent-over-literalismLiteral compliance can violate the users actual goal when a request touches risky, privileged, or externally visible actions. Infer the safe operating intent and stop when policy, review expectations, or irreversible consequences conflict with the words alone.PatternReview HandoffVerificationProduce Review Packetsproduce-review-packetsReviewers lose time when a handoff contains only a diff and no acceptance evidence. Package the goal, validation, risks, and proof artifact in proportion to the review burden.PatternSource TruthDocumentationFeedback LoopsRecord Agent Operating Lessonsrecord-agent-operating-lessonsAgent work produces useful operational knowledge that is easy to lose after the task succeeds or fails. Record reusable lessons in the right durable place so future runs inherit the improved workflow instead of rediscovering it.PatternChange ShapeReviewabilitySeparate Discovery From Editingseparate-discovery-from-editingEditing while still discovering the system can bake early misunderstandings into the diff. Read enough to find the ownership, constraints, and likely change shape before making scoped edits.PatternReviewabilityReview HandoffSpend Human Attention On Ambiguityspend-human-attention-on-ambiguityAgent throughput can exceed the maintainers ability to review and steer. Delegate execution and inspection, but reserve human attention for ambiguous goals, taste, architecture, risk, and the systems that make future delegation safer.PatternToolingAutomationTeach 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.PatternAutomationSource TruthFeedback LoopsTurn Feedback Into Guidanceturn-feedback-into-guidanceRepeated steering signals that a preference is missing from durable repo guidance or tooling. Fix the current artifact and encode the reusable lesson at the right level when the feedback applies beyond one line.PatternReviewabilityReview HandoffUse Narrow Agent Reviewersuse-narrow-agent-reviewersBroad review prompts often miss specific risks or return vague feedback. Add focused agent reviewers for important, repeatable concerns when narrow context will produce more useful findings than another general pass.

PrincipleToolingAutomationAgent 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.PrincipleAutomationToolingReviewabilityMechanize 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.

MechanismDocumentationSource TruthReviewabilityGuidance Content Model Stewardshipguidance-content-model-stewardshipContent-model stewardship keeps guides, rules, patterns, principles, mechanisms, references, snippets, and downstream templates in distinct roles. The mechanism combines mechanical inventory checks with maintainer review queues for overlap, thin guidance, noisy tags, and subjective content-quality decisions.MechanismVCS JJToolingAgent 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.

AgentAgent ContextReviewabilitySource TruthApply Practice Guidanceagent-apply-practice-guidanceCompact instructions for Codex sessions that need to use the shared practice catalog from another repository. The snippet turns broad standards into a task-local application loop without loading the whole catalog or treating preferences as automatic churn.AgentAgent ContextToolingReview 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.AgentAgent ContextReview HandoffVerificationCore Agent Instructionsagent-core-instructionsBroad baseline instructions for coding agents working in repositories that adopt these development preferences. The snippet keeps AGENTS.md short while routing agents to canonical guides, principles, mechanisms, and the reviewed rule pack.AgentAgent ContextSource TruthReviewabilityFull Software Doctrine Prompt Packagent-full-software-doctrine-prompt-packLarge single-file prompt pack that combines the repos software rules and the reasons behind them into one coherent artifact. This version is tuned for Rust-heavy maintenance and refactoring work, especially when existing code needs to be reshaped toward better locality, coherence, ownership, and documentation.AgentVCS JJToolingReview 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.AgentGenerated ArtifactsAutomationSource TruthReviewed Rule Agent Packagent-reviewed-rule-packGenerated compact execution surface for every reviewed rule. The pack gives agents stable rule IDs and instructions while leaving rationale, examples, and deeper context in the canonical rule files.