Skip to content

Shipped skills are self-contained: one reference convention + regression guard#143

Merged
rdbruhn merged 8 commits into
developfrom
feature/payload-reference-convention
Jun 24, 2026
Merged

Shipped skills are self-contained: one reference convention + regression guard#143
rdbruhn merged 8 commits into
developfrom
feature/payload-reference-convention

Conversation

@rdbruhn

@rdbruhn rdbruhn commented Jun 23, 2026

Copy link
Copy Markdown
Contributor

Summary

Shipped VINE skills cited references/STATE.md (~67×) and bare agents/… paths that don't exist where the code runs — a skill executes with the consuming repo as cwd, and references/ isn't in the plugin payload. vine:init even wrote those dead pointers into other repos' README and CLAUDE.md. This establishes one convention — shipped skills are self-contained — and applies it everywhere, with a guard so it can't drift back.

Closes #142, Closes #141, Closes #138.

Changes

  • Rename references/STATE.md → references/CONTRACTS.md (name now matches the content — artifact templates plus cross-cutting conventions, not just "state"). Live references updated; CHANGELOG and dated knowledge ADRs left period-accurate.
  • Document the three-bucket reference convention in CLAUDE.md and CONTRACTS.md.
  • Apply it across 9 skills: ~60 dead references/ pointers removed (runtime-critical content inlined via the operative-copy pattern), agent citations switched to invocable names, and init/optimize no longer write VINE-internal pointers into consumer repos.
  • Guard it: /trellis Check 13 fails on any shipped-surface VINE-internal reference.

Decisions Made

  • references/ is contributor documentation, not a runtime contract — so it doesn't ship and the runtime is never told to read it. Honors the payload-scope and overlay-distribution decisions; no payload duplication.
  • Historical records (CHANGELOG, dated ADRs) keep naming STATE.md — period-accurate, not drift.

Testing

  • grep -rn "references/" plugins/vine/skills/ → 0 matches; no bare agents|skills|hooks/ paths.
  • sh .vine/scripts/trellis-check.sh → exit 0 (11/11 skills, Check 13 green).
  • sh .vine/scripts/run-tests.sh → 30/30 (includes 3 new Check 13 tests, both directions).

Follow-up

None — the three issues are fully closed. Version bump (patch vs minor) is a release-time call; a [Unreleased] CHANGELOG entry is staged.

🤖 Generated with Claude Code

@rdbruhn rdbruhn changed the base branch from main to develop June 23, 2026 23:52
rdbruhn and others added 8 commits June 23, 2026 18:55
@rdbruhn @claude
vine:verify — payload-relative reference convention (CONTEXT.md)
43b3a17 
Scope the fix for dead/ambiguous payload-internal references across shipped
skills and init's templates. Resolves the shared root cause behind #142
(skill bodies → references/STATE.md ~67×), #141 (init writes dead STATE
pointers into consuming repos), and #138 (agents/ paths ambiguous for
contributors).

Direction (a STATE-as-doc vs b ship-in-payload) left open for inquire.

Refs #142 #141 #138

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rdbruhn @claude
vine:inquire — payload-reference-convention SPEC.md
a3e4685 
Self-contained shipped skills (no VINE-source-internal refs); three-bucket
reference convention; rename references/STATE.md → CONTRACTS.md; init drops
consumer-facing internal pointers; /trellis regression guard. 4 slices,
single PR. Refs #142, #141, #138.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rdbruhn @claude
Rename STATE.md → CONTRACTS.md: rename references/STATE.md to referen…
9861e20 
…ces/CONTRACTS.md and update every live/operative citation, leaving historical records (CHANGELOG, dated knowledge ADRs, archived projects) period-accurate.

Acceptance criteria verified:
- [x] references/STATE.md gone; references/CONTRACTS.md present
- [x] Zero live files reference STATE.md
- [x] CHANGELOG + dated .vine/knowledge ADRs unchanged (period-accurate)
- [x] /trellis passes; cross-reference anchors intact (8 pairs resolve, run-tests 27/27)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rdbruhn @claude
Document the convention: state the three-bucket payload reference con…
b773948 
…vention and the self-contained-skills rule in CLAUDE.md (Skill Authoring Conventions) and CONTRACTS.md (Path resolution by audience, under Reference Legibility).

Acceptance criteria verified:
- [x] Both homes state the three buckets
- [x] Self-contained rule for shipped skills stated
- [x] Name / ${CLAUDE_PLUGIN_ROOT} rule for payload cross-refs stated
- [x] Init writes no VINE-internal pointer stated

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rdbruhn @claude
Make shipped skills self-contained: strip all VINE-source-internal re…
3d57863 
…ferences

Apply the three-bucket reference convention across the 9 affected skills:
drop every `references/STATE.md` provenance pointer (58), inline the two
runtime-critical bits (PROFILE.md format in verify + evolve), and convert the
two `agents/vine-verification.md` citations to invocable-name form. Remove the
dead `references/…` pointers init (and, discovered, optimize) write into a
consumer's README/CLAUDE.md. Drop the now-stale navigate/evolve Check 10 anchor
pairs from trellis-check.sh / trellis.md / run-tests.sh.

Acceptance criteria verified:
- [x] Zero `references/…` in plugins/vine/skills/ (#142)
- [x] No bare agents/|skills/|hooks/ path in a skill body; cross-refs by name (#138)
- [x] init + optimize templates write no `references/…` pointer into consumers (#141)
- [x] Runtime-critical content inlined; trellis 11/11 pass, 6 anchor pairs resolve
- [x] Shipped agents/hooks confirmed clean (bucket-2 only)

Refs #142, #141, #138

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rdbruhn @claude
Add /trellis Check 13: shipped-surface reference guard
3585ead 
Add a repo-level guard that fails /trellis on a convention violation in
plugins/vine/{skills,agents,hooks}/: any `references/…` path, or a bare
`agents|skills|hooks/` plugin-root path. The bare-path regex anchors on a
non-slash boundary, since every legitimate occurrence (`${CLAUDE_PLUGIN_ROOT}/`,
`**/`, `.claude/`, `.vine/`) is `/`-preceded — no prefix allowlist needed.
Bucket-2 consumer paths and name-based agent refs are never flagged. Wired into
trellis-check.sh, documented in trellis.md, covered by 3 run-tests.sh cases.
Also despaces a prose "skills/agents" the guard correctly flagged.

Acceptance criteria verified:
- [x] A `references/…` line in a shipped skill fails /trellis (scripted + manual)
- [x] The corrected tree passes
- [x] The shipped agent's .vine/context/ refs do not trip it
- [x] Bare agents|skills|hooks/ path also caught; run-tests 30/30

Refs #142, #141, #138

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rdbruhn @claude
navigate: close payload-reference-convention (backfill hashes, PROJEC…
3b09b15 
…T-MAP)

Backfill Slice 3 commit hash in NAVIGATION.md and flip the PROJECT-MAP navigate
row to ✅. Closes the navigate phase; evolve picks up next.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rdbruhn @claude
evolve: payload-reference-convention — evolution report and cycle art…
f5e5200 
…ifacts

VINE cycle complete. Captures product verification (all 7 ACs pass,
trellis 11/11, tests 30/30), the three-bucket-convention knowledge ADR,
and a [Unreleased] CHANGELOG entry. Project resolved and archived.

Refs #142, #141, #138 (closed via PR).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@rdbruhn rdbruhn force-pushed the feature/payload-reference-convention branch from 8376ddf to f5e5200 Compare June 23, 2026 23:55
@rdbruhn rdbruhn merged commit 79ddac5 into develop Jun 24, 2026
1 check passed
@rdbruhn rdbruhn deleted the feature/payload-reference-convention branch June 24, 2026 00:00
This was referenced Jun 24, 2026
Merged
Closed
Merged
rdbruhn added a commit that referenced this pull request Jun 24, 2026
@rdbruhn @claude
Release v0.4.1 (#147)
26fe8c7 
* Plugin packaging (1/4): manifest, marketplace + first skill (#134)

* plugin-packaging (#57): verify — CONTEXT.md + PROJECT-MAP.md

Map the distribution surface (create-vine file-copy, package.json, publish
workflow) and the verified Claude Code plugin/marketplace schema for Cycle 5.
Captures the three design forks inquire must resolve: repo layout, commands-vs-
skills, and how team-overlay content travels in a plugin (the seam the team-layer
ADR hands here).

Refs #57

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): inquire — SPEC.md (skills-only, drop npx)

Resolved the commands-vs-skills fork toward skills as the sole product and
retired the npx path (revises #57's backward-compat gate). Overlay distribution
scoped to docs-only (consumer-owned). 9 slices / 4 milestone-tracked phases.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): inquire — add versioning strategy + branch model to SPEC

plugin.json as the single version source (pin, not float, since the repo is
the dev tree); SemVer policy; /plugin update path; main=release / develop=
integration so the marketplace tracks main with no ref management. Remove
package.json entirely. Folds into slices 1, 5, 7, 8, 9 + new ACs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): navigate Slice 1 — plugin scaffold + invocation spike

Stand up .claude-plugin/plugin.json (name vine, version 0.4.0) and
marketplace.json (source "./"), and convert status to skills/status/SKILL.md.
Local-scope install proves /vine:status resolves in colon form — the de-risk
the whole cycle rests on.

Acceptance criteria verified:
- [x] AC1 colon-form /vine:status (engineer-confirmed, not hyphen)
- [x] AC2 no auto-fire (disable-model-invocation: true)
- [x] AC3 argument preserved ($ARGUMENTS)
- [x] AC4 4 agents load via plugin

Refs #57

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): navigate — close Phase 1 group (Slice 1 ✅)

Mark Phase 1 complete and Phase 2 active in PROJECT-MAP milestones; flip the
SPEC Phase 1 header to ✅. Phase-group verification passed (all ACs, no blockers).

Refs #57

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): record PR #134 in Phase 1 milestone

Refs #57

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Plugin packaging (2–3/4): convert to skills + remove npx (#135)

* plugin-packaging (#57): navigate Slice 2 — convert remaining 10 commands to skills

Map init, verify, inquire, navigate, evolve, pair, pause, resume, help, optimize
to skills/<name>/SKILL.md using the Slice 1 recipe (drop name:, add
disable-model-invocation: true, body verbatim). Plugin now ships all 11 skills.

Acceptance criteria verified:
- [x] AC1 colon form /vine:<name> — all 11 skills in plugin snapshot (recipe proven empirically in Slice 1)
- [x] AC2 no auto-fire — disable-model-invocation: true on all 10
- [x] AC3 arguments preserved — argument-hint + $ARGUMENTS carried verbatim

Refs #57

* plugin-packaging (#57): navigate Slice 3 — journal-check plugin hook + payload-slimming restructure

Wire journal-check natively via hooks/hooks.json + ${CLAUDE_PLUGIN_ROOT}; move it out of
.vine/scripts/ and drop its contributor settings.json entry. Restructure the product into
plugins/vine/ (skills/agents/hooks + plugin.json) and point marketplace source there, adopting
the documented plugins/<name>/ convention. This scopes the published payload to product-only:
the installed snapshot now carries only .claude-plugin + skills + agents + hooks.

Acceptance criteria verified:
- [x] AC5 hook native — journal-check fires via ${CLAUDE_PLUGIN_ROOT}; tested stale(block)/current(allow)/non-commit
- [x] AC5 contributor hooks unshipped — trellis-gate.sh / main-guard.sh now absent from the payload entirely

Refs #57

* plugin-packaging (#57): navigate — close Phase 2 group (Slices 2–3 ✅)

Phase-group verification clean (AC1 structural, AC2/AC3/AC5 pass; payload product-only).
Trackers: PROJECT-MAP Phase 2 ✅, Phase 3 active; SPEC Phase 2 header ✅; Slice 3 commit hash.

Refs #57

* plugin-packaging (#57): navigate Slice 3 (cont.) — wire restructure not captured in c679792

A failing pathspec in c679792's git add silently dropped three working-tree changes that
the restructure depends on: marketplace source ./ -> ./plugins/vine (the line that actually
scopes the payload), the journal-check removal from contributor settings.json, and the
.claude/agents symlink repoint. Working tree + installed snapshot were already correct;
this just records them. (Phase PR squash-merges, so history collapses cleanly.)

Refs #57

* plugin-packaging (#57): navigate — record Slice 3 dual commit hashes in journal

Refs #57

* plugin-packaging (#57): navigate Slice 4 — rewire trellis to the skills layout

Point /trellis, the trellis-check engine, and the commit gate at
plugins/vine/skills/<name>/SKILL.md instead of commands/vine/*.md. Stem is now the
skill directory name; Check 1's field set drops `name` and adds disable-model-invocation;
Check 2 ("Name Matches Filename") is repurposed to "No Auto-Fire" (disable-model-invocation:
true), adding AC2 enforcement without renumbering. Check 10 anchors and the gate watch path
move to plugins/vine/.

Acceptance criteria verified:
- [x] AC8 trellis passes on the 11 converted skills (green stamp) and flags a malformed SKILL.md
- [x] AC8 the gate now watches plugins/vine/skills/

Refs #57

* plugin-packaging (#57): navigate — record Slice 4 commit hash in journal

Refs #57

* plugin-packaging (#57): navigate Slice 5 — remove npx + rework release flow

Retire the npx distribution and repoint the release/CI tooling at the
skills/plugin layout. Also fixes red CI (run-tests.sh) that was fallout from
the Slice 3 journal-check move + Slice 4 trellis rewire.

- Delete bin/cli.js, commands/vine/ (11), the .claude/commands/vine +
  .claude/agents symlinks, and package.json entirely.
- Rework publish.yml: node-free version parse from plugin.json, drop npm
  publish + setup-node + node smoke-test (replaced with trellis-check),
  keep tag-check + CHANGELOG-extract + GitHub-release.
- Rewrite run-tests.sh to the plugins/vine/{hooks,skills} layout; now 27/27
  (was 11/27). Clean stale create-vine comments in surviving scripts.

Acceptance criteria verified:
- [x] AC7 npx removed cleanly — no create-vine/npm artifacts remain
- [x] AC11 versioning coherent — plugin.json sole version source (0.4.0); develop/main branch model
- [x] AC6/AC8 (partial) — trellis tooling validates live skills; ci.yml green for PR 3 (full dogfooding re-confirm is the human-only gate)

trellis.yml deliberately not created — ci.yml already gates trellis-check on
every PR (engineer decision).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): navigate — record Slice 5 commit hash in journal

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): navigate Slice 6 — init legacy-install migration

Init now detects a legacy npx install (.claude/commands/vine/) and offers a
one-time cleanup; declining is a no-op (#58 offer-migration pattern). The
obsolete "Native Hook Scaffold" section is replaced — the journal-before-commit
hook now ships with the plugin (default-on), so there's no per-repo settings
scaffold step.

Acceptance criteria verified:
- [x] AC7 (init half) — offers cleanup when .claude/commands/vine/ present; no-op on decline; unchanged when absent
- [x] Obsolete hook-scaffold revised — hook documented as plugin-provided

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): navigate — close Phase 3 group (Slices 4–6 ✅)

Record Slice 6 commit hash; mark Phase 3 complete in PROJECT-MAP + SPEC;
open Phase 4. Phase-group verification ran green (11/11 skills, 27/27 hook
tests, all npx deletions confirmed). Its one cross-slice finding — stale
commands/vine/ references the removal exposed (help/SKILL.md, navigate.md
lint glob, pr.md gate) — is annotated into Slice 8 scope rather than patched
here, since the shipped-skill fix is coupled to the Slice 8 "how skills cite
paths for plugin users" question.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): record PR #135 in Phase 2–3 milestones

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Plugin migration: docs, decision records, and a 2-agent payload (#136)

* plugin-packaging (#57): mark Phases 2–3 shipped (PR #135 merged)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(README+CHANGELOG): lead with plugin install, drop npx (Slice 7)

Acceptance criteria verified:
- [x] AC9 (README half): plugin install + `/plugin update vine` lead; overlay
      distribution documented as consumer-owned (no VINE mechanism); no stale
      npx-as-primary instructions remain (only migration context)

README: plugin-first Installation (marketplace add → install), Updating, and
Migrating-from-npx sections; "Graduating to a team" rewritten for consumer-owned
overlays; Enforced-vs-Advisory hook now reads plugin-default-on; stale agents/
links retargeted to plugins/vine/agents/. CHANGELOG: 0.4.0 plugin-packaging (#57)
Added/Changed/Removed entries.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: rewrite internal docs for the skills/plugin product (Slice 8)

Acceptance criteria verified:
- [x] AC9 (internal-docs half): no internal doc describes the product as
      "11 command files in commands/vine/"; addition checklist targets skills;
      release checklist + branch model documented; no shipped skill or
      contributor doc references the deleted commands/vine/ path
- [x] AC11 (docs half): plugin.json documented as single version source;
      main-release/develop-integration branch model documented

CLAUDE.md (What This Repo Is / Repository Structure / Skill Authoring
Conventions), shared.md (Tooling Notes, Skill Addition Checklist, Branch
Naming, CI/CD branch model + SemVer + no-npm release flow), verify.md,
navigate.md, STATE.md (agent paths, create-vine refs, .vine/scripts + plugin
hook), help skill citation via Glob. Folded in the main->develop retarget of
pr.md + CONTRIBUTING.md so the branch model ships coherently.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* knowledge: record the plugin-packaging cycle decisions (Slice 9)

Acceptance criteria verified:
- [x] AC10: four ADRs capture drop-npx (revised gate), overlay = consumer-owned,
      versioning + main/develop branch model, and plugin-layout/payload-control;
      the team-layer ADR's "seam" expectation is explicitly amended, not dangling

Adds .vine/knowledge/workflow/ records (a) plugin-only/drop-npx,
(b) overlay-distribution-is-documentation, (c) plugin.json single version source
+ main-release/develop-integration, (d) scoped plugins/vine/ payload; amends the
team-layer ADR to point its seam expectation at (b).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: fix stale agents/ paths missed by the Slice 8 sweep (Phase 4 verify)

Phase-group verification surfaced two root-relative agents/ refs the grep
missed (backtick-prefixed form): shared.md Decision Delegation pointer, and
4x in the pr-review.md contributor tool. Both retargeted to
plugins/vine/agents/. No AC impact — completes the npx->plugin path sweep.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* navigate: close Phase 4 — trackers + final handoff (plugin-packaging #57)

Acceptance criteria verified:
- [x] Phase 4 (Slices 7-9) complete: navigate row ✅, Phase 4 milestone ✅,
      SPEC phase header ✅, Remaining Work handoff for evolve written

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin: ship only the phase-support agents; hold autonomous roles in repo

Move vine-coder + vine-reviewer out of the plugin payload into .claude/agents/
(repo-resident). The plugin ships only the two agents the interactive phases
invoke (vine-codebase-explorer, vine-verification). The autonomous-delegation
roles stay available for /pr-review dogfooding and forks but aren't shipped
on-by-default: agents have no auto-delegation gate, so a write-capable coder
shouldn't be a live delegation target in every install.

Docs (README, CLAUDE.md, CHANGELOG, shared.md, STATE.md, pr-review.md) updated
to two-shipped-agents. New ADR records the decision; payload-scoping ADR
updated to agents(2). trellis 11/11.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* journal: record agent re-homing commit hash (73862bb)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* evolve: plugin-packaging — evolution report and cycle close (#57)

VINE cycle complete. Adds EVOLUTION.md (all 11 ACs accounted; full-feature
integration verified), marks the project resolved, and archives it.

Agent evolution: hardens the evolve.md Multi-PR overlay to check for an
already-open handoff PR (--state open), not just merged — the gap that hid #136.

User evolution: platform domain reinforced at confident (PROFILE.md, gitignored
— not staged). Knowledge ADRs were recorded in-cycle (Slice 9 + re-homing).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Release prep: stamp 0.4.0 (CHANGELOG + ROADMAP) (#139)

* release: stamp 0.4.0 — CHANGELOG date + ROADMAP cycle-5 close

Release prep on develop ahead of the develop→main merge:
- CHANGELOG [Unreleased] → [0.4.0] - 2026-06-23. publish.yml extracts the
  section matching plugin.json's version; left unstamped, release notes
  would be empty.
- ROADMAP: Cycle 5 (Plugin, #57) marked done; all table cycles complete;
  #55 (profile rework) carries forward to 0.5.0.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* knowledge: correct ADR-c — main stays default branch, no forge flip owed

Same-cycle factual fix before 0.4.0 cuts. ADR-c's Consequences listed
'set develop as the default PR base' as owed repo-admin, which contradicts
the same record's 'marketplace tracks main (the default branch)': on GitHub
the default PR base IS the default branch, so that line implied the
develop-as-default flip the branch model deliberately avoids. main stays
default for ref-free marketplace tracking; pr.md already targets develop
explicitly. Body-immutability exception: a same-cycle self-contradiction,
not a decision change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* evolve: strike stale 'set develop as default base' in EVOLUTION handoff

Pre-release consistency fix surfaced by a vine-reviewer cold pass on #139.
The archived EVOLUTION 'Repo-admin owed' line still instructed flipping the
default base — superseded by the same-cycle ADR-c correction (b5c059c) and
the main-stays-default alignment. Struck (not rewritten) with a correction
note pointing at the ADR, preserving the historical snapshot.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Shipped skills are self-contained: one reference convention + regression guard (#143)

* vine:verify — payload-relative reference convention (CONTEXT.md)

Scope the fix for dead/ambiguous payload-internal references across shipped
skills and init's templates. Resolves the shared root cause behind #142
(skill bodies → references/STATE.md ~67×), #141 (init writes dead STATE
pointers into consuming repos), and #138 (agents/ paths ambiguous for
contributors).

Direction (a STATE-as-doc vs b ship-in-payload) left open for inquire.

Refs #142 #141 #138

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* vine:inquire — payload-reference-convention SPEC.md

Self-contained shipped skills (no VINE-source-internal refs); three-bucket
reference convention; rename references/STATE.md → CONTRACTS.md; init drops
consumer-facing internal pointers; /trellis regression guard. 4 slices,
single PR. Refs #142, #141, #138.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Rename STATE.md → CONTRACTS.md: rename references/STATE.md to references/CONTRACTS.md and update every live/operative citation, leaving historical records (CHANGELOG, dated knowledge ADRs, archived projects) period-accurate.

Acceptance criteria verified:
- [x] references/STATE.md gone; references/CONTRACTS.md present
- [x] Zero live files reference STATE.md
- [x] CHANGELOG + dated .vine/knowledge ADRs unchanged (period-accurate)
- [x] /trellis passes; cross-reference anchors intact (8 pairs resolve, run-tests 27/27)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Document the convention: state the three-bucket payload reference convention and the self-contained-skills rule in CLAUDE.md (Skill Authoring Conventions) and CONTRACTS.md (Path resolution by audience, under Reference Legibility).

Acceptance criteria verified:
- [x] Both homes state the three buckets
- [x] Self-contained rule for shipped skills stated
- [x] Name / ${CLAUDE_PLUGIN_ROOT} rule for payload cross-refs stated
- [x] Init writes no VINE-internal pointer stated

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Make shipped skills self-contained: strip all VINE-source-internal references

Apply the three-bucket reference convention across the 9 affected skills:
drop every `references/STATE.md` provenance pointer (58), inline the two
runtime-critical bits (PROFILE.md format in verify + evolve), and convert the
two `agents/vine-verification.md` citations to invocable-name form. Remove the
dead `references/…` pointers init (and, discovered, optimize) write into a
consumer's README/CLAUDE.md. Drop the now-stale navigate/evolve Check 10 anchor
pairs from trellis-check.sh / trellis.md / run-tests.sh.

Acceptance criteria verified:
- [x] Zero `references/…` in plugins/vine/skills/ (#142)
- [x] No bare agents/|skills/|hooks/ path in a skill body; cross-refs by name (#138)
- [x] init + optimize templates write no `references/…` pointer into consumers (#141)
- [x] Runtime-critical content inlined; trellis 11/11 pass, 6 anchor pairs resolve
- [x] Shipped agents/hooks confirmed clean (bucket-2 only)

Refs #142, #141, #138

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Add /trellis Check 13: shipped-surface reference guard

Add a repo-level guard that fails /trellis on a convention violation in
plugins/vine/{skills,agents,hooks}/: any `references/…` path, or a bare
`agents|skills|hooks/` plugin-root path. The bare-path regex anchors on a
non-slash boundary, since every legitimate occurrence (`${CLAUDE_PLUGIN_ROOT}/`,
`**/`, `.claude/`, `.vine/`) is `/`-preceded — no prefix allowlist needed.
Bucket-2 consumer paths and name-based agent refs are never flagged. Wired into
trellis-check.sh, documented in trellis.md, covered by 3 run-tests.sh cases.
Also despaces a prose "skills/agents" the guard correctly flagged.

Acceptance criteria verified:
- [x] A `references/…` line in a shipped skill fails /trellis (scripted + manual)
- [x] The corrected tree passes
- [x] The shipped agent's .vine/context/ refs do not trip it
- [x] Bare agents|skills|hooks/ path also caught; run-tests 30/30

Refs #142, #141, #138

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* navigate: close payload-reference-convention (backfill hashes, PROJECT-MAP)

Backfill Slice 3 commit hash in NAVIGATION.md and flip the PROJECT-MAP navigate
row to ✅. Closes the navigate phase; evolve picks up next.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* evolve: payload-reference-convention — evolution report and cycle artifacts

VINE cycle complete. Captures product verification (all 7 ACs pass,
trellis 11/11, tests 30/30), the three-bucket-convention knowledge ADR,
and a [Unreleased] CHANGELOG entry. Project resolved and archived.

Refs #142, #141, #138 (closed via PR).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Add /release-plugin command + pin evolve PR base to develop (#144)

New maintainer command encodes the proven stamp(#139)→cut(#140) release
flow: bump plugin.json, finalize CHANGELOG, drive develop→main up to the
publish.yml dispatch, handing merges + the public publish to the maintainer.

Fix the actual PR-to-main gap surfaced this cycle: the evolve overlay's PR
Workflow now pins the base to develop (the shipped evolve skill defers to
the overlay for the base branch). /pr already targeted develop — it was
never the culprit.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Release prep: stamp 0.4.1 (plugin.json + CHANGELOG) (#145)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This was referenced Jun 24, 2026
Closed
Closed
Closed
rdbruhn added a commit that referenced this pull request Jul 4, 2026
@rdbruhn @claude
Release v0.5.0 (#157)
710f166 
* Plugin packaging (1/4): manifest, marketplace + first skill (#134)

* plugin-packaging (#57): verify — CONTEXT.md + PROJECT-MAP.md

Map the distribution surface (create-vine file-copy, package.json, publish
workflow) and the verified Claude Code plugin/marketplace schema for Cycle 5.
Captures the three design forks inquire must resolve: repo layout, commands-vs-
skills, and how team-overlay content travels in a plugin (the seam the team-layer
ADR hands here).

Refs #57

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): inquire — SPEC.md (skills-only, drop npx)

Resolved the commands-vs-skills fork toward skills as the sole product and
retired the npx path (revises #57's backward-compat gate). Overlay distribution
scoped to docs-only (consumer-owned). 9 slices / 4 milestone-tracked phases.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): inquire — add versioning strategy + branch model to SPEC

plugin.json as the single version source (pin, not float, since the repo is
the dev tree); SemVer policy; /plugin update path; main=release / develop=
integration so the marketplace tracks main with no ref management. Remove
package.json entirely. Folds into slices 1, 5, 7, 8, 9 + new ACs.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): navigate Slice 1 — plugin scaffold + invocation spike

Stand up .claude-plugin/plugin.json (name vine, version 0.4.0) and
marketplace.json (source "./"), and convert status to skills/status/SKILL.md.
Local-scope install proves /vine:status resolves in colon form — the de-risk
the whole cycle rests on.

Acceptance criteria verified:
- [x] AC1 colon-form /vine:status (engineer-confirmed, not hyphen)
- [x] AC2 no auto-fire (disable-model-invocation: true)
- [x] AC3 argument preserved ($ARGUMENTS)
- [x] AC4 4 agents load via plugin

Refs #57

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): navigate — close Phase 1 group (Slice 1 ✅)

Mark Phase 1 complete and Phase 2 active in PROJECT-MAP milestones; flip the
SPEC Phase 1 header to ✅. Phase-group verification passed (all ACs, no blockers).

Refs #57

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): record PR #134 in Phase 1 milestone

Refs #57

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Plugin packaging (2–3/4): convert to skills + remove npx (#135)

* plugin-packaging (#57): navigate Slice 2 — convert remaining 10 commands to skills

Map init, verify, inquire, navigate, evolve, pair, pause, resume, help, optimize
to skills/<name>/SKILL.md using the Slice 1 recipe (drop name:, add
disable-model-invocation: true, body verbatim). Plugin now ships all 11 skills.

Acceptance criteria verified:
- [x] AC1 colon form /vine:<name> — all 11 skills in plugin snapshot (recipe proven empirically in Slice 1)
- [x] AC2 no auto-fire — disable-model-invocation: true on all 10
- [x] AC3 arguments preserved — argument-hint + $ARGUMENTS carried verbatim

Refs #57

* plugin-packaging (#57): navigate Slice 3 — journal-check plugin hook + payload-slimming restructure

Wire journal-check natively via hooks/hooks.json + ${CLAUDE_PLUGIN_ROOT}; move it out of
.vine/scripts/ and drop its contributor settings.json entry. Restructure the product into
plugins/vine/ (skills/agents/hooks + plugin.json) and point marketplace source there, adopting
the documented plugins/<name>/ convention. This scopes the published payload to product-only:
the installed snapshot now carries only .claude-plugin + skills + agents + hooks.

Acceptance criteria verified:
- [x] AC5 hook native — journal-check fires via ${CLAUDE_PLUGIN_ROOT}; tested stale(block)/current(allow)/non-commit
- [x] AC5 contributor hooks unshipped — trellis-gate.sh / main-guard.sh now absent from the payload entirely

Refs #57

* plugin-packaging (#57): navigate — close Phase 2 group (Slices 2–3 ✅)

Phase-group verification clean (AC1 structural, AC2/AC3/AC5 pass; payload product-only).
Trackers: PROJECT-MAP Phase 2 ✅, Phase 3 active; SPEC Phase 2 header ✅; Slice 3 commit hash.

Refs #57

* plugin-packaging (#57): navigate Slice 3 (cont.) — wire restructure not captured in c679792

A failing pathspec in c679792's git add silently dropped three working-tree changes that
the restructure depends on: marketplace source ./ -> ./plugins/vine (the line that actually
scopes the payload), the journal-check removal from contributor settings.json, and the
.claude/agents symlink repoint. Working tree + installed snapshot were already correct;
this just records them. (Phase PR squash-merges, so history collapses cleanly.)

Refs #57

* plugin-packaging (#57): navigate — record Slice 3 dual commit hashes in journal

Refs #57

* plugin-packaging (#57): navigate Slice 4 — rewire trellis to the skills layout

Point /trellis, the trellis-check engine, and the commit gate at
plugins/vine/skills/<name>/SKILL.md instead of commands/vine/*.md. Stem is now the
skill directory name; Check 1's field set drops `name` and adds disable-model-invocation;
Check 2 ("Name Matches Filename") is repurposed to "No Auto-Fire" (disable-model-invocation:
true), adding AC2 enforcement without renumbering. Check 10 anchors and the gate watch path
move to plugins/vine/.

Acceptance criteria verified:
- [x] AC8 trellis passes on the 11 converted skills (green stamp) and flags a malformed SKILL.md
- [x] AC8 the gate now watches plugins/vine/skills/

Refs #57

* plugin-packaging (#57): navigate — record Slice 4 commit hash in journal

Refs #57

* plugin-packaging (#57): navigate Slice 5 — remove npx + rework release flow

Retire the npx distribution and repoint the release/CI tooling at the
skills/plugin layout. Also fixes red CI (run-tests.sh) that was fallout from
the Slice 3 journal-check move + Slice 4 trellis rewire.

- Delete bin/cli.js, commands/vine/ (11), the .claude/commands/vine +
  .claude/agents symlinks, and package.json entirely.
- Rework publish.yml: node-free version parse from plugin.json, drop npm
  publish + setup-node + node smoke-test (replaced with trellis-check),
  keep tag-check + CHANGELOG-extract + GitHub-release.
- Rewrite run-tests.sh to the plugins/vine/{hooks,skills} layout; now 27/27
  (was 11/27). Clean stale create-vine comments in surviving scripts.

Acceptance criteria verified:
- [x] AC7 npx removed cleanly — no create-vine/npm artifacts remain
- [x] AC11 versioning coherent — plugin.json sole version source (0.4.0); develop/main branch model
- [x] AC6/AC8 (partial) — trellis tooling validates live skills; ci.yml green for PR 3 (full dogfooding re-confirm is the human-only gate)

trellis.yml deliberately not created — ci.yml already gates trellis-check on
every PR (engineer decision).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): navigate — record Slice 5 commit hash in journal

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): navigate Slice 6 — init legacy-install migration

Init now detects a legacy npx install (.claude/commands/vine/) and offers a
one-time cleanup; declining is a no-op (#58 offer-migration pattern). The
obsolete "Native Hook Scaffold" section is replaced — the journal-before-commit
hook now ships with the plugin (default-on), so there's no per-repo settings
scaffold step.

Acceptance criteria verified:
- [x] AC7 (init half) — offers cleanup when .claude/commands/vine/ present; no-op on decline; unchanged when absent
- [x] Obsolete hook-scaffold revised — hook documented as plugin-provided

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): navigate — close Phase 3 group (Slices 4–6 ✅)

Record Slice 6 commit hash; mark Phase 3 complete in PROJECT-MAP + SPEC;
open Phase 4. Phase-group verification ran green (11/11 skills, 27/27 hook
tests, all npx deletions confirmed). Its one cross-slice finding — stale
commands/vine/ references the removal exposed (help/SKILL.md, navigate.md
lint glob, pr.md gate) — is annotated into Slice 8 scope rather than patched
here, since the shipped-skill fix is coupled to the Slice 8 "how skills cite
paths for plugin users" question.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin-packaging (#57): record PR #135 in Phase 2–3 milestones

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Plugin migration: docs, decision records, and a 2-agent payload (#136)

* plugin-packaging (#57): mark Phases 2–3 shipped (PR #135 merged)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(README+CHANGELOG): lead with plugin install, drop npx (Slice 7)

Acceptance criteria verified:
- [x] AC9 (README half): plugin install + `/plugin update vine` lead; overlay
      distribution documented as consumer-owned (no VINE mechanism); no stale
      npx-as-primary instructions remain (only migration context)

README: plugin-first Installation (marketplace add → install), Updating, and
Migrating-from-npx sections; "Graduating to a team" rewritten for consumer-owned
overlays; Enforced-vs-Advisory hook now reads plugin-default-on; stale agents/
links retargeted to plugins/vine/agents/. CHANGELOG: 0.4.0 plugin-packaging (#57)
Added/Changed/Removed entries.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: rewrite internal docs for the skills/plugin product (Slice 8)

Acceptance criteria verified:
- [x] AC9 (internal-docs half): no internal doc describes the product as
      "11 command files in commands/vine/"; addition checklist targets skills;
      release checklist + branch model documented; no shipped skill or
      contributor doc references the deleted commands/vine/ path
- [x] AC11 (docs half): plugin.json documented as single version source;
      main-release/develop-integration branch model documented

CLAUDE.md (What This Repo Is / Repository Structure / Skill Authoring
Conventions), shared.md (Tooling Notes, Skill Addition Checklist, Branch
Naming, CI/CD branch model + SemVer + no-npm release flow), verify.md,
navigate.md, STATE.md (agent paths, create-vine refs, .vine/scripts + plugin
hook), help skill citation via Glob. Folded in the main->develop retarget of
pr.md + CONTRIBUTING.md so the branch model ships coherently.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* knowledge: record the plugin-packaging cycle decisions (Slice 9)

Acceptance criteria verified:
- [x] AC10: four ADRs capture drop-npx (revised gate), overlay = consumer-owned,
      versioning + main/develop branch model, and plugin-layout/payload-control;
      the team-layer ADR's "seam" expectation is explicitly amended, not dangling

Adds .vine/knowledge/workflow/ records (a) plugin-only/drop-npx,
(b) overlay-distribution-is-documentation, (c) plugin.json single version source
+ main-release/develop-integration, (d) scoped plugins/vine/ payload; amends the
team-layer ADR to point its seam expectation at (b).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: fix stale agents/ paths missed by the Slice 8 sweep (Phase 4 verify)

Phase-group verification surfaced two root-relative agents/ refs the grep
missed (backtick-prefixed form): shared.md Decision Delegation pointer, and
4x in the pr-review.md contributor tool. Both retargeted to
plugins/vine/agents/. No AC impact — completes the npx->plugin path sweep.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* navigate: close Phase 4 — trackers + final handoff (plugin-packaging #57)

Acceptance criteria verified:
- [x] Phase 4 (Slices 7-9) complete: navigate row ✅, Phase 4 milestone ✅,
      SPEC phase header ✅, Remaining Work handoff for evolve written

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* plugin: ship only the phase-support agents; hold autonomous roles in repo

Move vine-coder + vine-reviewer out of the plugin payload into .claude/agents/
(repo-resident). The plugin ships only the two agents the interactive phases
invoke (vine-codebase-explorer, vine-verification). The autonomous-delegation
roles stay available for /pr-review dogfooding and forks but aren't shipped
on-by-default: agents have no auto-delegation gate, so a write-capable coder
shouldn't be a live delegation target in every install.

Docs (README, CLAUDE.md, CHANGELOG, shared.md, STATE.md, pr-review.md) updated
to two-shipped-agents. New ADR records the decision; payload-scoping ADR
updated to agents(2). trellis 11/11.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* journal: record agent re-homing commit hash (73862bb)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* evolve: plugin-packaging — evolution report and cycle close (#57)

VINE cycle complete. Adds EVOLUTION.md (all 11 ACs accounted; full-feature
integration verified), marks the project resolved, and archives it.

Agent evolution: hardens the evolve.md Multi-PR overlay to check for an
already-open handoff PR (--state open), not just merged — the gap that hid #136.

User evolution: platform domain reinforced at confident (PROFILE.md, gitignored
— not staged). Knowledge ADRs were recorded in-cycle (Slice 9 + re-homing).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Release prep: stamp 0.4.0 (CHANGELOG + ROADMAP) (#139)

* release: stamp 0.4.0 — CHANGELOG date + ROADMAP cycle-5 close

Release prep on develop ahead of the develop→main merge:
- CHANGELOG [Unreleased] → [0.4.0] - 2026-06-23. publish.yml extracts the
  section matching plugin.json's version; left unstamped, release notes
  would be empty.
- ROADMAP: Cycle 5 (Plugin, #57) marked done; all table cycles complete;
  #55 (profile rework) carries forward to 0.5.0.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* knowledge: correct ADR-c — main stays default branch, no forge flip owed

Same-cycle factual fix before 0.4.0 cuts. ADR-c's Consequences listed
'set develop as the default PR base' as owed repo-admin, which contradicts
the same record's 'marketplace tracks main (the default branch)': on GitHub
the default PR base IS the default branch, so that line implied the
develop-as-default flip the branch model deliberately avoids. main stays
default for ref-free marketplace tracking; pr.md already targets develop
explicitly. Body-immutability exception: a same-cycle self-contradiction,
not a decision change.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* evolve: strike stale 'set develop as default base' in EVOLUTION handoff

Pre-release consistency fix surfaced by a vine-reviewer cold pass on #139.
The archived EVOLUTION 'Repo-admin owed' line still instructed flipping the
default base — superseded by the same-cycle ADR-c correction (b5c059c) and
the main-stays-default alignment. Struck (not rewritten) with a correction
note pointing at the ADR, preserving the historical snapshot.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Shipped skills are self-contained: one reference convention + regression guard (#143)

* vine:verify — payload-relative reference convention (CONTEXT.md)

Scope the fix for dead/ambiguous payload-internal references across shipped
skills and init's templates. Resolves the shared root cause behind #142
(skill bodies → references/STATE.md ~67×), #141 (init writes dead STATE
pointers into consuming repos), and #138 (agents/ paths ambiguous for
contributors).

Direction (a STATE-as-doc vs b ship-in-payload) left open for inquire.

Refs #142 #141 #138

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* vine:inquire — payload-reference-convention SPEC.md

Self-contained shipped skills (no VINE-source-internal refs); three-bucket
reference convention; rename references/STATE.md → CONTRACTS.md; init drops
consumer-facing internal pointers; /trellis regression guard. 4 slices,
single PR. Refs #142, #141, #138.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Rename STATE.md → CONTRACTS.md: rename references/STATE.md to references/CONTRACTS.md and update every live/operative citation, leaving historical records (CHANGELOG, dated knowledge ADRs, archived projects) period-accurate.

Acceptance criteria verified:
- [x] references/STATE.md gone; references/CONTRACTS.md present
- [x] Zero live files reference STATE.md
- [x] CHANGELOG + dated .vine/knowledge ADRs unchanged (period-accurate)
- [x] /trellis passes; cross-reference anchors intact (8 pairs resolve, run-tests 27/27)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Document the convention: state the three-bucket payload reference convention and the self-contained-skills rule in CLAUDE.md (Skill Authoring Conventions) and CONTRACTS.md (Path resolution by audience, under Reference Legibility).

Acceptance criteria verified:
- [x] Both homes state the three buckets
- [x] Self-contained rule for shipped skills stated
- [x] Name / ${CLAUDE_PLUGIN_ROOT} rule for payload cross-refs stated
- [x] Init writes no VINE-internal pointer stated

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Make shipped skills self-contained: strip all VINE-source-internal references

Apply the three-bucket reference convention across the 9 affected skills:
drop every `references/STATE.md` provenance pointer (58), inline the two
runtime-critical bits (PROFILE.md format in verify + evolve), and convert the
two `agents/vine-verification.md` citations to invocable-name form. Remove the
dead `references/…` pointers init (and, discovered, optimize) write into a
consumer's README/CLAUDE.md. Drop the now-stale navigate/evolve Check 10 anchor
pairs from trellis-check.sh / trellis.md / run-tests.sh.

Acceptance criteria verified:
- [x] Zero `references/…` in plugins/vine/skills/ (#142)
- [x] No bare agents/|skills/|hooks/ path in a skill body; cross-refs by name (#138)
- [x] init + optimize templates write no `references/…` pointer into consumers (#141)
- [x] Runtime-critical content inlined; trellis 11/11 pass, 6 anchor pairs resolve
- [x] Shipped agents/hooks confirmed clean (bucket-2 only)

Refs #142, #141, #138

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Add /trellis Check 13: shipped-surface reference guard

Add a repo-level guard that fails /trellis on a convention violation in
plugins/vine/{skills,agents,hooks}/: any `references/…` path, or a bare
`agents|skills|hooks/` plugin-root path. The bare-path regex anchors on a
non-slash boundary, since every legitimate occurrence (`${CLAUDE_PLUGIN_ROOT}/`,
`**/`, `.claude/`, `.vine/`) is `/`-preceded — no prefix allowlist needed.
Bucket-2 consumer paths and name-based agent refs are never flagged. Wired into
trellis-check.sh, documented in trellis.md, covered by 3 run-tests.sh cases.
Also despaces a prose "skills/agents" the guard correctly flagged.

Acceptance criteria verified:
- [x] A `references/…` line in a shipped skill fails /trellis (scripted + manual)
- [x] The corrected tree passes
- [x] The shipped agent's .vine/context/ refs do not trip it
- [x] Bare agents|skills|hooks/ path also caught; run-tests 30/30

Refs #142, #141, #138

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* navigate: close payload-reference-convention (backfill hashes, PROJECT-MAP)

Backfill Slice 3 commit hash in NAVIGATION.md and flip the PROJECT-MAP navigate
row to ✅. Closes the navigate phase; evolve picks up next.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* evolve: payload-reference-convention — evolution report and cycle artifacts

VINE cycle complete. Captures product verification (all 7 ACs pass,
trellis 11/11, tests 30/30), the three-bucket-convention knowledge ADR,
and a [Unreleased] CHANGELOG entry. Project resolved and archived.

Refs #142, #141, #138 (closed via PR).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Add /release-plugin command + pin evolve PR base to develop (#144)

New maintainer command encodes the proven stamp(#139)→cut(#140) release
flow: bump plugin.json, finalize CHANGELOG, drive develop→main up to the
publish.yml dispatch, handing merges + the public publish to the maintainer.

Fix the actual PR-to-main gap surfaced this cycle: the evolve overlay's PR
Workflow now pins the base to develop (the shipped evolve skill defers to
the overlay for the base branch). /pr already targeted develop — it was
never the culprit.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Release prep: stamp 0.4.1 (plugin.json + CHANGELOG) (#145)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* release-plugin: merge-commit cut + fast-forward develop sync (#148)

Rewrite Step 5 to merge develop→main as a *merge commit* (not squash) so
develop stays an ancestor of main, with a diverged-history recovery path
(main-based branch carrying develop's tree). Add Step 6: fast-forward
develop up to main after the cut so the branches never diverge — the root
cause of the 0.4.1 release conflicts. Renumber publish/report to 7/8.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* Onboarding hardening; ship framework machinery as plugin PROTOCOL.md (#154)

* Onboarding hardening: cold-run fixes, precedence page, README quick-start

Clean-environment audit of marketplace install → /vine:init → /vine:verify
(three cold simulations on a fresh sample repo, fixes re-validated by a
fourth run). Shipped-skill fixes: first-run init nudge in verify/pair, a
gitignore guard before the first PROFILE.md write, init scaffolding now
reaches history (.gitkeep + commit reminder + verify sweep), batched
domain/slug prompt, borderline scope-check recommendation, announced
commits, and init cold-path polish. Docs: README restructured around
"start with verify" quick start; docs/precedence.md one-pager; verified
update-command syntax. docs/overspec-audit-2026-07.md is proposal-only —
no cuts applied.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* Apply the over-spec audit in full; ship framework machinery as PROTOCOL.md

The framework machinery init used to copy into every consuming repo's
shared.md (~140 lines: overlay loading/precedence, personal-root
resolution, stance, profile protocol, interaction constraints,
out-of-scope routing) now ships as plugins/vine/PROTOCOL.md, loaded by
every phase via ${CLAUDE_PLUGIN_ROOT} before the repo overlays — killing
the version-skew risk and the missing-shared.md dangling references.
init generates a slim repo-specific shared.md from extracted template
files (${CLAUDE_SKILL_DIR}/templates) and gates Step 8 behind a trigger
table with a fresh-run fast path; a Machinery Single-Homing offer
migrates pre-protocol installs. All 11 skills tightened per the audit
(3,900 → ~3,470 lines); trellis Checks 12/13 retargeted; repo's own
shared.md, CLAUDE.md, README, precedence page, CONTRACTS.md synced.

Validated by cold-running init → verify and no-init verify end to end
on fresh sample repos; the runs' findings (check-ignore false-negative
on absent dir, upgrade-mode trigger literalism, a dangling section
name) are fixed in this commit.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* tests: stub PROTOCOL.md in trellis-check fixtures; add missing-file case

Check 12 moved its assertions from the consuming repo's shared.md to the
plugin-shipped plugins/vine/PROTOCOL.md, so the synthetic fixture repos
need the protocol stub (mkanchors now writes it alongside the Check-10
anchors). Also adds the inverse case: a missing PROTOCOL.md flips the
run red.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

* init: add path-resolution fallbacks for the template reads (review finding)

vine-reviewer flagged ${CLAUDE_SKILL_DIR} as an unexercised runtime
dependency — if the variable ever fails to substitute, init silently
can't read its templates. The template references now also cite the
${CLAUDE_PLUGIN_ROOT} equivalent and the harness-injected "Base
directory for this skill" line, which names the same directory.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

* Release prep: stamp 0.5.0 (plugin.json + CHANGELOG) (#155)

* Merge main (gate fixes) into develop — converge before v0.5.0 cut (#156)

* trellis-gate: scope the commit gate to this repo, not the whole session (#152)

The gate string-matched *git*commit* on every Bash call and then checked
VINE's own tree, so a commit in an unrelated repo (git -C, cd, spawned
scratch repos) got blocked whenever plugins/vine/skills/ was dirty here.

Resolve the repo the git command actually targets (explicit -C beats a
cd in the command, beats the payload cwd, beats CLAUDE_PROJECT_DIR) and
exit 0 when it provably resolves to a different repo, compared by
absolute git common dir so linked worktrees of this repo still gate.
Unresolvable targets fall through and gate as before — the skip only
happens on positive proof of a foreign repo. Same-repo checks now run
against the target worktree's own change set and stamp.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

* main-guard: only guard commits that target this repo's worktree (#153)

Port the target-repo resolution from trellis-gate (#152) into main-guard:
resolve the directory the git command runs against (git -C beats an
in-command cd, beats the payload cwd, beats CLAUDE_PROJECT_DIR), compare
repos by absolute git common dir, and pass foreign-repo commits untouched.
Same-repo commits are judged by the target worktree's own HEAD instead of
the root checkout's, so linked worktrees are no longer misread in either
direction.

Extends the main-guard test matrix with foreign-repo (cwd, git -C, cd)
and both worktree-direction cases; all 5 fail against the old guard.

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

---------

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

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

1 participant

@rdbruhn