Consider extracting vault-agent into standalone repository

[laurigates]

Summary

Extract vault-agent into its own repository (laurigates/vault-agent), the same way git-repo-agent was extracted in #1017. vault-agent is a standalone Claude Agent SDK / Typer CLI that lives in this monorepo but is not a Claude Code plugin (absent from marketplace.json and release-please). Extracting it enables clean uvx vault-agent / uv tool install vault-agent, independent versioning, and PyPI publishing.

This is the direct sibling of #1017 — reuse the proven template there (laurigates/git-repo-agent, PR #1, and this repo's sync workflow PR #1972).

Motivation

Same rationale as #1017:

• uvx vault-agent / uv tool install vault-agent without a claude-plugins checkout.
• Clearer separation of concerns and independent release cadence for a self-contained CLI.
• Consistency with git-repo-agent, now extracted.

Current coupling

vault-agent/src/vault_agent/prompts/compiler.py reads Obsidian-plugin skills from the monorepo at runtime:

_REPO_ROOT = _MODULE_DIR.parent.parent.parent  # vault-agent/
_PLUGINS_ROOT = _REPO_ROOT.parent              # claude-plugins/
# sources: obsidian-plugin/skills/vault-{frontmatter,tags,templates,wikilinks,orphans,stubs,mocs}/SKILL.md

This is ADR-0005 ("skill-source-obsidian-plugin") — analogous to git-repo-agent's compiler reading its sibling plugins.

Key difference from #1017: git-repo-agent had already solved the standalone-install problem (ADR-009: a compiler fallback that ships pre-compiled generated/ artifacts). vault-agent has not — its compiler.py has no standalone mode and no committed src/vault_agent/prompts/generated/. So the extraction has an extra Phase 0 prerequisite that git-repo-agent did not.

Proposed approach

Mirror #1017's phased, verify-before-remove cutover (per this repo's tool-migration-cutover rule), with the added Phase 0:

Phase 0 — standalone-install prompt fallback (prerequisite; the ADR-009 analog)

• Add a fallback to compiler.py: monorepo (dev) mode live-compiles from sibling obsidian-plugin/skills/*/SKILL.md; standalone (installed) mode reads pre-compiled artifacts from src/vault_agent/prompts/generated/ when siblings are absent (per-skill selection).
• Commit the generated/ artifacts; add a scripts/compile_prompts.py --check drift check.
• tests/test_compiler_standalone.py simulating standalone mode (empty _PLUGINS_ROOT).
• Record the decision as a vault-agent ADR (mirror git-repo-agent's ADR-009).

Phase 1 — stand up the standalone repo

• Create the public repo; seed with history via git subtree split --prefix=vault-agent.
• pyproject.toml: MIT license, project URLs, PyPI classifiers/keywords (keep requires-python >= 3.13), widen the uv_build constraint.
• CI (ci.yml): ruff + pytest + a build & standalone-CLI smoke. Configure a git identity + init.defaultBranch main if any test shells out to real git (git-repo-agent's tests did; check vault-agent's test_worktree.py).
• publish.yml: PyPI Trusted Publishing (OIDC) on a GitHub Release.
• README: standalone install/dev/release sections; fix the monorepo-relative uv tool install -e ./vault-agent.
• Verify uv build + uv run --isolated --no-project --with dist/*.whl vault-agent --help works with no claude-plugins parent.

Phase 2 — cross-repo sync

• Add a sync-vault-agent-prompts.yml workflow in this repo (mirror ci: cross-repo prompt-sync workflow for git-repo-agent #1972): regenerate generated/ on obsidian-plugin/skills/*/SKILL.md changes → open a PR on vault-agent. Needs a VAULT_AGENT_SYNC_TOKEN secret.

Phase 3 — remove from the monorepo (after Phases 1–2 verified)

• Replace vault-agent/ with a pointer README.
• Update the path-scoped rules that reference it: .claude/rules/agent-cli-worktree-safety.md (vault-agent/** glob + the test_worktree.py mirror reference), .claude/rules/typer-cli-completion.md (vault-agent/** glob), and the version-pinning.md sibling-repo follow-up note.

Owner actions (manual, mirror #1017)

• PyPI pending publisher for project vault-agent (workflow publish.yml, environment pypi).
• VAULT_AGENT_SYNC_TOKEN secret (contents + PR write on vault-agent).

References

• Consider extracting git-repo-agent into standalone repository #1017 — the git-repo-agent extraction this mirrors.
• laurigates/git-repo-agent — the proven layout (ADR-009 fallback, publish.yml, CI git-identity + init.defaultBranch fix, standalone-verify).
• claude-plugins ci: cross-repo prompt-sync workflow for git-repo-agent #1972 — the cross-repo sync workflow template.
• vault-agent ADR-0005 (skill-source-obsidian-plugin), ADR-0001 (precompute-vault-graph).

[laurigates]

Status analysis (2026-07-10)

Where things stand

Phase 0 (standalone-install prompt fallback) — implemented, awaiting merge in PR #2035 (opened 2026-07-10, mergeable_state: clean). It delivers every Phase 0 checklist item:

• Two-mode compiler.py: monorepo (dev) mode live-compiles from sibling obsidian-plugin/skills/*/SKILL.md; standalone mode falls back to shipped src/vault_agent/prompts/generated/ artifacts, with per-skill selection
• Committed generated/ artifacts (4 subagent bundles + 7 per-skill fragments) + scripts/compile_prompts.py --check drift check
• tests/test_compiler_standalone.py regression test (repoints _PLUGINS_ROOT at an empty dir)
• ADR-0006 standalone-install-prompt-fallback mirroring git-repo-agent's ADR-009

Verification per the PR: 167 tests passing, ruff clean, --check exits 0. Note it is not yet on main — current main (fd72462) still has no vault-agent/scripts/ or prompts/generated/.

Phases 1–3 — entirely outstanding:

• Phase 1 (create laurigates/vault-agent via git subtree split, pyproject/CI/publish.yml/README, standalone-verify): the standalone repo does not exist yet; this plus the owner actions (PyPI pending publisher, VAULT_AGENT_SYNC_TOKEN) are external to this repo.
• Phase 2 (sync-vault-agent-prompts.yml mirroring ci: cross-repo prompt-sync workflow for git-repo-agent #1972): no such workflow in .github/workflows/ yet.
• Phase 3 (pointer README + updating the path-scoped rules agent-cli-worktree-safety.md, typer-cli-completion.md, version-pinning.md): gated behind Phases 1–2 per the verify-before-remove cutover.

Recommendation

Keep open. The issue remains valid and the sibling precedent (#1017 / git-repo-agent, sync workflow #1972) still applies. Suggested sequence:

1. Merge PR feat(vault-agent): add standalone-install prompt fallback (Phase 0 of extraction) #2035 to land Phase 0.
2. Owner performs Phase 1 (repo creation + PyPI pending publisher + sync token) — manual, external steps.
3. Once the standalone repo exists, Phase 2 (sync workflow) and Phase 3 (monorepo removal + rule updates) become ordinary in-repo PRs.

🤖 Status analysis by Claude Code

---

Generated by Claude Code