From f7e9e296373a71465d17a82be13217641eb97711 Mon Sep 17 00:00:00 2001 From: Keysat Date: Mon, 15 Jun 2026 18:09:40 -0500 Subject: [PATCH] Add instruction-file structure + promote-without-trim rules to how-i-work --- how-i-work.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/how-i-work.md b/how-i-work.md index d95e3a9..9edb7f9 100644 --- a/how-i-work.md +++ b/how-i-work.md @@ -51,4 +51,6 @@ Instruction files are the durable, visible record of how I want you to work — - **Add and remove.** If a new rule supersedes an old one, rewrite or delete the old one. Stale rules are worse than no rule. - **Reconcile conflicts.** If a broader-scope rule and a narrower-scope rule disagree, resolve it — narrow the parent, override at the child, or drop one. Don't leave future-me to guess which wins. - **Right scope:** universal → this file; whole-repo → that repo's AGENTS.md; subsystem → a scoped guide. Keep each file to what's true at its scope. +- **How these files are structured (every repo):** `AGENTS.md` is the canonical file, and each vendor's preferred filename is a relative symlink to it — so the repo is already in every tool's native format. Subsystem detail lives in `docs/guides/.md` (with `paths:` frontmatter), surfaced via a relative symlink so a tool auto-loads it when you edit matching files, with a one-line index entry in AGENTS.md so any tool can find it. Knowledge lives in these vendor-neutral files; vendor-named paths are relative symlinks into them. Full protocol: `~/Projects/standards/portability.md`. +- **Promote up, but don't reflexively trim down.** Move a rule here when it's truly universal, so new repos and every session inherit it. Promoting it does *not* mean deleting it from a repo's AGENTS.md: for load-bearing or safety rules, keep the repo copy — it's followed more closely in context, and it travels with the repo to any tool or session, including ones that never load this file. Trim a per-repo copy only when it's pure boilerplate with no project-specific payload *and* the file is genuinely bloated. - **Where project state goes:** a repo's near-term status and next steps live in the `## Current state` section of its AGENTS.md (a snapshot, overwritten each session); longer-term backlog lives in a separate `ROADMAP.md` at the repo root. The split is by time horizon, not scope: would a session starting now act on it? Yes → Current state; not yet → ROADMAP.