Skip to content

refactor(instructions): centralize AGENTS.md core and gate session context injection - #76

Open
hapo-nghialuu wants to merge 47 commits into
devfrom
refactor/instructions-2026
Open

refactor(instructions): centralize AGENTS.md core and gate session context injection#76
hapo-nghialuu wants to merge 47 commits into
devfrom
refactor/instructions-2026

Conversation

@hapo-nghialuu

@hapo-nghialuu hapo-nghialuu commented Aug 5, 2026

Copy link
Copy Markdown
Member

Summary

Wave 1 of the instructions refactor: shrink the always-on instruction layer that every user loads each session, and make the machine actually verify what ships.

  • AGENTS.md is now the canonical shared instruction file. CLAUDE.md becomes a thin Claude-specific wrapper importing it via @AGENTS.md. always-on của user Claude: ~130 → ~64 dòng (AGENTS.md 39 + CLAUDE.md ~25).
  • The dynamic rules hook injects once per session instead of on nearly every prompt. The old 5-minute cooldown never held in real sessions. The injected block also drops from ~25 lines of generic advice (YAGNI/KISS/DRY, skill routing, modularization) to paths + docs.maxLoc + Language.
  • Kept the project-specific gotchas across all three runtimes: Completion Criteria / ## Evidence as source of truth, the NO_TESTS rule, skill venv paths for macOS and Windows, edit-skills-in-project, <!-- cafekit:lang --> marker, addressing canary.

Defects found by independent review and fixed in this branch

An independent read-only review of the first implementation found five blocking defects. All five were reproduced by execution and fixed:

  1. Missing runtime.json injected defaults anyway — including a Plans/Docs path resolved from a possibly stale PROJECT_ROOT, which could point at a different project. Now silent. payload.cwd is authoritative; PROJECT_ROOT is a fallback only.
  2. OpenCode never got its language patchedpost-install.js built instruction targets for claude and codex only, so --lang vi left OpenCode in English.
  3. Codex and OpenCode lost the venv and skill-location rules during the template rewrite.
  4. Combined install duplicated the shared core three times in root AGENTS.md. New bin/lib/instruction-blocks.js manages a <!-- CAFEKIT CORE START --> / <!-- CAFEKIT CORE END --> block; later installers detect it and append only their runtime-specific block. Idempotent across re-runs.
  5. The self-test suite proved nothing about shipped output. Mutation testing showed that deleting the shared gotchas, or breaking the managed-block markers, still produced PASS: 211. Assertions now run against real installs into temp directories.

Verification

Each item verified by installing into mktemp -d directories rather than reading source:

Check Result
Missing runtime.json → injection 0 bytes (Claude and Codex)
OpenCode --lang vi Vietnamese present, English absent
venv + skill rule per platform present in claude, codex, opencode output
Combined install core markers 1, still 1 after re-running the installer
Mutation test (venv removed from core) suite now exits 1
Test suite 225 passing, up from 211

Known issue, not fixed here

node bin/install.js --dry-run writes into the repository it runs from — it modified packages/spec/.gitignore and created packages/spec/AGENTS.md and packages/spec/opencode.json. Pre-existing installer bug, out of scope for this wave, worth a separate fix.

Test plan

  • npm test in packages/spec (225 tests)
  • Fresh install per platform: claude, codex, opencode
  • Combined install, then re-run to confirm no duplication
  • Non-English install (--lang vi) on each platform
  • Confirm an existing project's customizations survive an upgrade over this version

hapo-nghialuu and others added 30 commits August 4, 2026 22:13
Install one shared AGENTS.md core and keep runtime adapters thin.

Co-Authored-By: Claude <noreply@anthropic.com>
Remove timestamp cooldowns and trim dynamic reminders to project-specific context.

Co-Authored-By: Claude <noreply@anthropic.com>
Record Wave 1 instruction refactor in the package changelog.

Co-Authored-By: Claude <noreply@anthropic.com>
Document shared AGENTS composition and Claude root instruction installation.

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant