Skip to content

Untie hook scripts from .claude/ and consolidate under .scripts/ #71

@breferrari

Description

@breferrari

Context

Discussion surfaced during the v6 ShardMind conversion (#70). Today the vault has two parallel script roots:

  • .claude/scripts/ — hook implementations referenced by Codex's .codex/hooks.json and Gemini's .gemini/settings.json via ${*_PROJECT_DIR:-.}/.claude/scripts/.... Lives under .claude/ despite being shared infrastructure for all three agents.
  • scripts/ — vault-level utilities (qmd-bootstrap.ts). Floats at vault root with no semantic anchor.

Two related problems:

  1. Naming lies. .claude/scripts/ reads as Claude-specific, but Codex and Gemini both depend on it. A new contributor reasonably assumes deselecting Claude would be safe, when in fact every other agent's hook resolution breaks.
  2. Loose scripts/ at root. Mixed alongside vault content folders (brain/, work/, reference/, …) it reads like vault content, not infrastructure. The v5.1 file explorer surfaces it as a top-level folder; QMD's md-only pattern doesn't index it but it's still odd in the user's vault tree.

Proposal

Consolidate both under a single .scripts/ dotfolder at vault root:

  • .claude/scripts/.scripts/agent-hooks/ (or similar)
  • scripts/qmd-bootstrap.ts.scripts/qmd-bootstrap.ts

Update every reference site:

  • .claude/settings.json (Claude hook commands)
  • .codex/hooks.json (Codex hook commands)
  • .gemini/settings.json (Gemini hook commands)
  • .shardmind/hooks/post-install.ts (QMD_BOOTSTRAP_RELATIVE const)
  • README.md (manual qmd setup invocation)
  • vault-manifest.json::infrastructure[] (path glob updates)
  • .obsidian/app.json::userIgnoreFilters (already covers .claude/ via #70; add .scripts/)

Constraints

This is a path rename, which the v6 contract gates on breferrari/shardmind#88 (rename migrations + shardmind adopt --from-version). The v6 acceptance criteria binding rule:

Verify zero path renames from v5.1. If any surface, rename migrations (shardmind#88) must ship first.

So this issue is blocked on shardmind shipping rename migrations. Once that lands, the obsidian-mind release that introduces this rename uses the migrations to keep existing v6 installs upgrading cleanly without losing user state.

Acceptance

  • All hook command paths under .scripts/ instead of .claude/scripts/
  • .shardmind/hooks/post-install.ts invokes .scripts/qmd-bootstrap.ts
  • README's manual setup section uses the new path
  • vault-manifest.json::infrastructure[] and .obsidian/app.json::userIgnoreFilters updated
  • Migration entry added to .shardmind/shard-schema.yaml::migrations[] mapping the v6→v6.x renames
  • CI green; clone-UX unchanged; shardmind update from older v6 to the rename-bumped version doesn't lose user state

Why not now

Currently blocked on shardmind#88. Tracked here so the rename ships in lockstep with the migration support.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions