core: establish core/ as home for host-agnostic content (closes #14)#57
Merged
Conversation
Adds core/AGENTS.md as the boundary spec for what belongs under core/ (host-agnostic prose: skill bodies, agent personas, templates, vault spec) versus what stays in a host-specific layer like plugins/athena- notes/ (runtime tool calls, agent frontmatter, plugin manifest, ~/. claude/ config paths). Cross-references added: - CONTRIBUTING.md filter extended four → five points (host-agnostic check) - plugins/athena-notes/AGENTS.md Cross-Tool Compatibility section forward-points at core/AGENTS.md - README.md Cross-tool portability section forward-points at core/AGENTS.md - CHANGELOG [Unreleased] / Added bullet Scope kept deliberately narrow: this PR establishes the destination so subsequent epic subissues (skill migration, opencode adapter at #21) can argue from a fixed boundary. No content migrated, no symlinks, no adapters/ directory, no CI/lint changes, no version bump.
- CONTRIBUTING.md: workflow checklist updated to "five filter points" (was stale "four" after the filter was extended in the prior commit). CONTRIBUTING.md: link text in point 5 changed from `[core/]` to `[core/AGENTS.md]` so the displayed text doesn't read like a directory link. - plugins/athena-notes/AGENTS.md: "portability epic" link target corrected #21 → #22 (the parent epic; #21 is the opencode adapter subissue). - core/AGENTS.md: dropped PR-tense from a permanent spec file — removed "Explicit deferrals" section and its "picking up the next subissue" prescriptive paragraph; folded operational deferrals (version-check, lint coverage) into Current state as durable facts; dropped the calendar date from the Current state heading; named sibling subissues (#15, #16, #17) directly so readers find the follow-on scope without wading through PR scaffolding. - CHANGELOG.md: trimmed the [Unreleased] / Added bullet to a single observable-change sentence (motivation moved to commit + PR body per the project convention).
- README.md: Contributing summary section updated four-point → five-point filter (matches CONTRIBUTING.md), added the host-agnostic bullet with a pointer at core/AGENTS.md. Pass-1 update missed this duplicate filter list. - CONTRIBUTING.md: point-5 link prose corrected — content belongs in the directory `core/`, not in the spec file. Link target unchanged (core/AGENTS.md) but now framed as the boundary spec rather than the destination. - core/AGENTS.md: scoped the "nothing in core/ references plugins/ or adapters/" rule to *content* (skills, agents, templates), with an explicit exception for this boundary spec's transitional cross- references — the prior wording read as universal and was self- violated by the Cross-references section. - core/AGENTS.md: removed redundant "(this file)" parenthetical from the Current state bullet about plugins/athena-notes/AGENTS.md.
- README.md: bare `AGENTS.md` reference qualified to `[plugins/athena-notes/AGENTS.md]` so the line below it (which introduces core/AGENTS.md) doesn't make the bare reference ambiguous. - core/AGENTS.md: trimmed the redundant "; once migration completes, those pointers go away" sunset clause from the boundary section — Current state already makes the transient nature of the cross- references clear. - core/AGENTS.md: dropped trailing "not now" hedge from the per-skill extraction note — "at migration time" already conveys deferral.
SnowboardTechie
added
enhancement
- core/AGENTS.md: drop https://agents.md hyperlink (squatted third-party); remove Future-shape section (out of scope for this PR); remove transient CI-coverage line (belongs in #17). - CONTRIBUTING.md: trim filter point 5 to match the other points; move migration-state note to italicized prose above the list. - README.md: tighten Cross-tool portability paragraph (link #15-#17 directly instead of the 'Subsequent migration issues' phrasing).
This was referenced Apr 25, 2026
4 tasks
SnowboardTechie
added a commit
that referenced
this pull request
May 1, 2026
) ## Summary The `archivist` agent's prompt body searched `.notes/` with bare relative paths, so every Glob/Grep failed when the agent ran inside a git worktree (the `.notes` symlink lives only in the trunk). Six parallel archivist calls during [#57](#57 `/pr-self-review` Phase 1.2 all returned "vault not accessible" — the regression [#59](#59) documented. This PR grants archivist `Bash` and adds a Startup section that runs `git rev-parse --path-format=absolute --git-common-dir` once per invocation, drops the trailing `/.git`, and uses the result as `\$TRUNK_ROOT` for every search-strategy path. The single command is equivalent to the canonical two-step `resolve_trunk_root` from `agent-workspace` (`--git-common-dir` always points at the trunk's `.git` from either side), expressed inline because archivist's bash-hygiene rule forbids shell functions and pipes. The five archivist callers (`pr-self-review`, `session-review`, `meeting-sync`, `workday-planning`, `athena.md`) stay untouched — their existing "archivist owns path resolution" contract is now actually true. The plan considered Option B (each caller passes \`trunk_root:\` in the prompt) and Option C (hybrid) but went with Option A (agent self-resolves) for blast-radius reasons: five caller-site edits avoided, existing \`workday-planning\` contract preserved, and the new Bash surface is bounded to \`git rev-parse\` by archivist's existing hygiene rule. ## Test plan No agent test harness exists in the repo, so verification is manual. - [x] Direct archivist invocation from this worktree (executed during \`/pr-self-review\` Phase 1.2 of this PR's own self-review): pre-fix returned "vault not accessible" string responses; post-fix archivist resolved the trunk, located the project vault, and scanned end-to-end. Result was "0 matches" only because the project vault is genuinely empty of related-topic content — the resolution itself succeeded. - [x] \`git rev-parse --path-format=absolute --git-common-dir\` returns the trunk's \`.git\` from both the trunk and a worktree on this machine — verified live during planning. - [x] Three-lens self-review (correctness / security / simplicity) ran clean after one fix-up commit. Pass 1 surfaced 1 Major + 5 Minor + 2 Nit; all 7 actionable findings accepted in the second commit. Pass 2 surfaced two non-blocker wording nits, both intentionally skipped. Acceptance criteria from [#59](#59): - ✅ \`@archivist\` invoked from a worktree successfully reads \`.notes/\` content from the trunk. - ✅ At least one existing skill-invocation path returns archivist results from the resolved vault — \`/pr-self-review\` Phase 1.2 of this PR demonstrates it. - ✅ \`archivist.md\` references the \`agent-workspace\` trunk-resolution pattern explicitly in the new Startup section. ## Changelog - [x] **Non-release PR** — added a bullet under \`## [Unreleased]\` in \`CHANGELOG.md\`.
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
Establish
core/as the documented home for host-agnostic content (skill prose, agent personas, templates, vault spec) versus host-specific glue (runtime tool calls, agent frontmatter, plugin manifests,~/.claude/config paths). The directory ships with one substantive document —core/AGENTS.md— that is both the directory's reason for existing and the rule a contributor applies to decide where new content belongs. No content is migrated in this PR; that's what subsequent epic subissues (#15 skills, #16 embedded content, #17 regression safeguards) are for. Closes #14.core/AGENTS.md(~95 lines) — boundary spec, decision rule for new content, current state, future shape (adapters/{host}/).CONTRIBUTING.md— four-point filter extended to a five-point filter (host-agnostic check); link tocore/AGENTS.mdnear the top.README.md— Cross-tool portability section + Contributing summary list updated to point atcore/AGENTS.mdand to include the host-agnostic filter point.plugins/athena-notes/AGENTS.md— Cross-Tool Compatibility section gains a forward-pointer tocore/AGENTS.md; "portability epic" link target corrected [Placeholder] Stand up adapters/opencode/ #21 → Epic: Make Athena Notes portable to a second AI coding host (opencode) #22.CHANGELOG.md— single observable-change bullet under## [Unreleased] / ### Added.Test plan
python3 scripts/lint-frontmatter.py— passes (14 agents, 18 skills validated).rg --pcre2 --type md '\]\((?!https?://|mailto:|#)[^)]*/\)' .— no relative trailing-slash links.frontmatter-lint,docs-lint,version-check(touchesplugins/athena-notes/AGENTS.mdso CHANGELOG entry is required — present).Changelog
## [Unreleased]inCHANGELOG.md.