grant/standards
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add instruction-file structure + promote-without-trim rules to how-i-work

Browse Source
This commit is contained in:
Keysat
2026-06-15 18:09:40 -05:00
parent 7ed43fcb59
commit f7e9e29637
1 changed files with 2 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
how-i-work.md
+2
View File
@@ -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/<topic>.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.