Plugin migration: docs, decision records, and a 2-agent payload by rdbruhn · Pull Request #136 · moduloMoments/VINE

rdbruhn · 2026-06-23T16:54:28Z

What

Brings every doc and decision record in line with VINE now shipping as a native Claude Code plugin (the code migration landed in earlier PRs). Rewrites the README install path (plugin marketplace + /plugin update vine), updates the internal docs — CLAUDE.md, contributor overlays, the state reference, and the contributor PR tooling — to the skills/plugin layout and the main-release / develop-integration branch model, and adds five decision records. Also scopes the shipped plugin to the two agents the workflow actually invokes; the two autonomous-delegation agents move into the repo (.claude/agents/) and are not shipped by default.

Why

The migration changed how VINE is installed, versioned, and laid out, but the docs still described the old npx install and command-file layout — a new reader would have followed dead instructions. The decision records capture the load-bearing calls (dropping npx, plugin.json as the single version source, the branch model, payload scoping, and why the autonomous agents stay out) so they're recoverable later. And shipping a write-capable autonomous coder to every install — with no guard against accidental auto-delegation — isn't something to turn on by default yet.

Refs #57.

How to test

Read the README "Installation" section — it should describe the plugin marketplace install + /plugin update vine, with no npx-as-primary steps.
ls plugins/vine/agents shows two agents (explorer, verification); ls .claude/agents shows the two autonomous roles.
sh .vine/scripts/trellis-check.sh passes 11/11.

Checklist

I've tested this in an actual VINE cycle (N/A — docs/knowledge; the one skill edit, help, was validated via trellis, not a full /vine:help run)
Changes are focused on a single concern
Any new behavior is documented in the README

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

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>

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>

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>

…rify) 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>

) 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>

…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>

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

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>

* 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> --------- Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

* 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>

* 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>

rdbruhn and others added 9 commits June 23, 2026 02:32

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

1ecfd4c

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

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

b76d3f5

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

rdbruhn merged commit 949e70a into develop Jun 23, 2026
1 check passed

rdbruhn deleted the feature/plugin-packaging branch June 23, 2026 19:07

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

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

Plugin migration: docs, decision records, and a 2-agent payload#136
rdbruhn merged 9 commits into
developfrom
feature/plugin-packaging

rdbruhn commented Jun 23, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

rdbruhn commented Jun 23, 2026

What

Why

How to test

Checklist

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant