Hardware FixRecommendedDevice not working? Your driver may be the problemCheck updates for common hardware issues.Fix DriversOctober DealsAmazon USOctober deal check: compare before you payAmazon US: current deals, useful picks and tech finds.Check DealsWindows FixRecommendedWindows errors stealing your time? Find the fix fastScan stability, cleanup and performance issues.Fix Now×
Skip to content
World desk3 min

Can AGENTS.md Depend on a Local Plan? Make the Contract Portable

A project instruction is portable only if its dependencies are available to collaborators in a clean clone. Keep scratch plans local; promote lasting decisions into tracked context.
Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

No: a project-level agent instruction should not depend on a plan that exists only on its author’s machine. A link in AGENTS.md, .apc/, or tracked documentation signals that its target is available, safe to share, and durable enough for other contributors to rely on. If a fresh clone cannot provide it, the link is not a portable project prerequisite.

What makes an agent instruction portable?

A project instruction is a shared contract only when the documents it depends on travel with the project and remain readable in a clean clone. Before linking to a plan or note, ask whether a contributor who clones the repository today on another machine can open it and use it without private setup.

As an Amazon Associate I earn from qualifying purchases.

For example, “Read spec/release-notes.md before changing the deployment flow” is a valid project-wide prerequisite only if that file is tracked and available to the intended readers. If spec/ is ignored because it contains exploratory notes or raw QA evidence, the instruction may work in its author’s checkout and fail elsewhere. Absolute paths, private issue exports, temporary design notes, and runtime logs create the same portability problem.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

Agent Project Context (APC) expresses the principle this way: “If a future contributor cannot read an instruction and every document it depends on, the instruction is not yet a project contract.” The sentence is attributed to Manuel Bruña in a DEV Community search result displayed as posted September 29; the result does not show a year. DEV Community

Where should a plan or note live?

Decide based on who needs the material, how long it will remain useful, whether it is appropriate to share, and whether a fresh checkout will contain it. A task’s working notes and a repository’s durable decisions have different audiences and lifetimes.

Material Best home Reason
Concise, stable project rule AGENTS.md It belongs in the root project contract when contributors need it to guide their work.
Structured or path-scoped project context Appropriate APC locations in the repository It is curated, project-owned context that should be available to collaborators.
Durable, shareable plan useful beyond one runtime session A tracked plan, such as .apc/plans/ Some plans are lasting project artifacts rather than temporary working material.
Scratch plan, raw evidence, or temporary investigation Local working material It may change, become stale, or contain material that should not be distributed as a project prerequisite.
Session transcripts, logs, or runtime history Local runtime state These record an individual runtime’s activity rather than the project’s curated contract.

APC’s documentation describes AGENTS.md as the root project contract and .apc/ as a canonical repository-owned context directory. It includes an optional .apc/plans/ location for durable plans, while distinguishing those from scratch plans and raw runtime state. Its “Add APC to Your Project” guide gives .apc/plans/migration-plan.md as an example to create only when a plan is safe to share and useful beyond one runtime session. Agent Project Context

How to turn local findings into a shared rule

  1. Keep active work local. Use local working material for an in-progress plan, raw evidence, and incomplete alternatives.
  2. Identify the lasting decision. Isolate the part future contributors need, rather than promoting the investigation wholesale?
  3. Rewrite it for the project. Put the decision in a short, self-contained rule or a tracked document. Remove transient evidence and machine-specific paths.
  4. Link only to the shared artifact. Make the contract’s reference resolve in a clean clone, without relying on private setup.

Suppose a local release investigation establishes that generated assets must be checked before publishing. The enduring requirement can move into AGENTS.md or a suitable tracked document. Commands used during the investigation, unresolved alternatives, private paths, and temporary evidence can remain local unless they independently meet the standard for a durable, shareable artifact.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Support on Ko-Fi

How APC and APX divide the work

In APC’s project framing, APC describes repository-owned context, while APX is its reference local runtime. The APX project repository distinguishes project definitions and curated context kept in the repository from local sessions, conversations, messages, and caches stored under ~/.apx/ and not committed. That describes APX’s documented implementation; it is not a universal rule for every agent runtime. APX repository

APC is presented in project materials as a proposal or active draft, not a universally adopted standard. Treat its guidance as the project’s framing rather than an assumption that all tools or repositories organize context identically.

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.

Leave a Reply

Your email address will not be published. Required fields are marked *

Free tools Windows power users keep installed

One-click scans. No signup required.

Special offer. See more information about Outbyte and uninstall instructions. Please review EULA and Privacy policy.

More from the Wire

  1. World desk4 min
    How to Spot an AI Voice Scam Before Sending MoneyDon’t rely on how a caller sounds. Pause, call back through a known number, and verify the emergency with another trusted person before sending money.
  2. Mountain View desk4 min
    Google’s SynthID Detector: How to Check AI-Generated Images, Video and AudioGoogle’s SynthID Detector looks for an embedded watermark in supported images, video and audio. Here is what its results do—and do not—show.
  3. Redmond desk20 min
    How to create a link to File or Folder in Windows 11Windows 11 gives you several ways to point to a file or folder without moving or duplicating it. You can create a desktop shortcut,…
Recommended PC Tool
Recommended PC Tool
PC Slower Than It Used to Be?Free scan - under a minute
Crashes, No Sound, or Screen Glitches?Free driver scan

Two free Windows tools

One Free Minute Could Fix That PC

Before you go - each of these free tools takes about a minute and tackles what quietly slows a Windows PC down.

Special offer. View Outbyte info, uninstall instructions, EULA, and Privacy Policy.