docs(vault): single-source agent spec in AGENTS.md; document template dev workflow - #49
Merged
Merged
Conversation
… dev workflow Context-engineering pass. CLAUDE.md/AGENTS.md/CODEX.md carried three divergent copies of the spec and drifted repeatedly (78e1e67, 081e274: CLAUDE.md's soft-rule digest misnumbered canonical SR IDs and listed a rule that does not exist in soft-rules.md). - AGENTS.md: now the canonical spec. Absorbs the only content CLAUDE.md had that it lacked (rate-limit override paragraph, SR-005 log entry format, source-page naming, index-update vs index-rebuild guidance, confidence calibration). Digest numbering now matches canonical HR/SR IDs exactly. - CLAUDE.md: thin Claude Code adapter (298 -> 21 lines) that imports @AGENTS.md. Version string and identity now live only in AGENTS.md (init.sh's version-reset sed no-ops harmlessly on CLAUDE.md). Initialization checklist relocated to README/getting-started, which already covered it. - CODEX.md: drops the boundaries block that was "reproduced for convenience" (85 -> 28 lines); pure pointer + commit-trailer override. - CONTRIBUTING.md: new Template Development Workflow section (placed inside the span init.sh deletes for instances, so it self-removes): protected-path pre-commit behavior and the human --no-verify convention, test-suite invocation, runnable definition-of-done, maintainer release checklist. Linter commands updated to the CI-verified forms. - docs/skills.md: names the exact skill-hardening substring traps instead of alluding to them. - README.md: link docs/getting-started.md (was orphaned). - init.sh: fix stale template_version="0.4.0" stamp and v0.4.0 CHANGELOG seed line -> 0.6.0 (both flagged by the new release checklist as per-release touch points). - lib-manage.sh: doctor's unresolved-placeholder check now targets AGENTS.md (which carries the Identity placeholders) instead of the now-placeholder-free thin CLAUDE.md, where it would always pass. - CHANGELOG.md: [Unreleased] entry for all of the above. Verified: markdownlint 0 errors, doctor exit 0, 11/11 script tests, shellcheck clean, typos clean. init.sh sed anchors in CONTRIBUTING.md ("## Two Types of Contributions" / "## How to Report Bugs") preserved; AGENTS.md retains the exact "**Vault Version**:" pattern init.sh resets. Touches HR-012/HR-013-protected files: human commit with --no-verify required (agents must not use it). Co-Authored-By: Claude <noreply@anthropic.com>
galimba
added a commit
that referenced
this pull request
Jul 10, 2026
Resolves the expected CHANGELOG [Unreleased] conflict with the context-engineering pass (#49) by keeping both entries. Committed with --no-verify because the merge brings #49's protected-path files (CLAUDE.md, AGENTS.md, CODEX.md, .vault/scripts/) into the staged diff and the pre-commit hook is not merge-aware; no protected file was edited in this resolution — only CHANGELOG.md. Co-Authored-By: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Context-engineering pass: one canonical agent spec, zero duplication, and the template-development workflow finally written down.
AGENTS.mdis now the single canonical specification (~220 lines). Its rules digest numbering matches the canonical HR-/SR- IDs exactly (the old CLAUDE.md digest misnumbered SR-005/007/008 and listed a rule that exists in no rule file — the drift class behind 78e1e67 and 081e274). Absorbs the operational details agents actually need per-session: SR-005 log entry format,source-*naming,index-updatevs destructiveindex-rebuild, confidence calibration, rate-limit override protocol.CLAUDE.md→ 21-line adapter that imports@AGENTS.md. The vault version string now lives only inAGENTS.md, so releases have one less file to bump (init.sh's version-reset sed no-ops harmlessly on the adapter).CODEX.md→ 28-line adapter; drops the boundaries block that was duplicated "for convenience."CONTRIBUTING.mdgains a Template Development Workflow section: protected-path pre-commit behavior and the human--no-verifyconvention, test-suite invocation, a runnable definition-of-done, and the maintainer release checklist. Placed inside the spaninit.shdeletes when scaffolding an instance, so instances never see it (verified by simulating the sed).init.sh: staletemplate_version="0.4.0"stamp and v0.4.0 CHANGELOG seed line → 0.6.0.lib-manage.sh: doctor's unresolved-placeholder check now targetsAGENTS.md(which carries the Identity placeholders) instead of the now-placeholder-free thinCLAUDE.md, where it would always pass.docs/skills.md: names the exact literal-substring hardening traps that block skill commits;README.md: links the previously orphaned getting-started guide, platform table marksAGENTS.mdcanonical.Verification
shellcheckon all.vaultscripts: cleanmarkdownlint-cli2on all tracked markdown: 0 errorsvault-tools.sh doctor: exit 0 (placeholder warning now correctly fires against AGENTS.md on the pristine template, warning-level as before)init.shsed anchors in CONTRIBUTING.md preserved;AGENTS.mdretains the exact**Vault Version**:pattern init.sh resetsNotes for review
--no-verifyper the (now documented) convention.[Unreleased]— keep both entries.🤖 Generated with Claude Code