Agent Workflow

Agent workflow rules cover objectives, scoped capabilities, durable context, review packets, security proof, feedback loops, and concrete next choices.

Objectives, scoped tools, durable context, and handoff evidence.

26 rules

VerificationReview 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.ReviewabilityPublic 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.Local ConventionsSource TruthDocumentationDistill From Blessed ArtifactsAGENT-DISTILL-FROM-BLESSED-ARTIFACTSStudy accepted code, docs, tests, and reviews first. Adapt local convention to this task.Security 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.Agent 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.Security 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.VCS 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.Agent 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.Security 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.ToolingAutomationVerificationMake 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.Change 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.ToolingLocal 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.ToolingAutomationDocumentationPrefer 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.Review 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.Change 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.Agent 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.Review 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.Security 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.Review 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.ReviewabilityReader 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.Agent 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.Agent 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.Local 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.DocumentationAutomationReviewabilityTurn 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.Agent 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.VerificationReleaseAutomationVerify 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.