Synergy Tracker
Manage the SYNERGY-*.md files that track shared patterns, divergences,
extraction candidates, and capabilities observed in sibling projects while
building this one. This skill tracks patterns and capabilities across
peer/sibling projects under the same maintainer — not upstream dependency
friction (use /upstream-tracker for that).
Tracking Files
Sibling projects (permanent files)
Sibling projects are declared in .claude/synergy-registry.json (if it exists)
as an array of {name, file, remote, bm-entity, relationship} objects. See
references/synergy-entry-format.md for the full registry schema.
To discover which projects are registered, read .claude/synergy-registry.json
if it exists. If it does not exist, glob for SYNERGY-*.md to infer sibling
names from existing files. If neither is present, ask the user which sibling
project is involved before proceeding.
File naming
Files are named SYNERGY-<project-name>.md. The project name is taken from
the name field in the registry (tier 3 of the canonical derivation
algorithm — synergy-tracker's subject is always sibling). For projects
outside the registry, fall back to tier 4 (directory basename), then
normalize. Full algorithm:
references/project-name-derivation.md. Examples: vp-knowledge →
SYNERGY-vp-knowledge.md, @scope/shared-utils →
SYNERGY-scope--shared-utils.md.
See references/synergy-entry-format.md for the full naming convention
(normalization rules) and references/project-name-derivation.md for the
tiered derivation algorithm shared with /sibling-sync.
Lifecycle
SYNERGY files are permanent — they always exist for registered sibling
projects, even when all sections are empty. When an entry is resolved or
dismissed, remove it and restore the _No entries yet._ placeholder for that
section. Do not delete the file.
Private overlay (PRIVATE-SYNERGY-*.md)
For entries that must stay out of a public repo (a proprietary sibling's
internal paths, client names, unreleased plans), use a gitignored
PRIVATE-SYNERGY-<project-name>.md companion to the committed
SYNERGY-<project-name>.md. It holds additional private entries under the same
four section headings.
The PRIVATE- prefix is the privacy mechanism. It keeps the overlay
OUTSIDE the SYNERGY-*.md glob namespace, so every public consumer (this
skill's boundary-crossing workflows, /sibling-sync, /retrospective, the
sprint-review agent, session-start.sh) structurally cannot read it — no
per-consumer exclusion is needed or used. Only the deliberate local-only read
in workflow 2 (Review) additionally globs PRIVATE-SYNERGY-*.md to assemble the
combined private view.
Invariant: private-overlay entries are NEVER promoted to Basic Memory
(workflow 5 (Promote to Basic Memory)) and NEVER reciprocated/written to a
sibling. With the prefix scheme this is enforced structurally — the promote
and reciprocate paths glob SYNERGY-*.md, which cannot match
PRIVATE-SYNERGY-*.md. This keeps the public view a sibling sees stable (so
bilateral convergence still works) and prevents a proprietary↔public leak.
When a PRIVATE-SYNERGY-*.md overlay exists, the committed
SYNERGY-<project-name>.md carries a one-line pointer noting it (gitignored
files are invisible to collaborators and git grep). Gitignored via the
explicit PRIVATE-SYNERGY-*.md line; session-start.sh warns if any is
tracked. Full convention: CLAUDE.md ### Synergy tracking convention.
Same-title shadowing (workflow 2 (Review) only). When a private entry shares
a title with a committed entry, surface both in the review view — the
committed row (still promotable/reciprocable) labelled [committed, shadowed]
and the private row labelled [local] — so the reviewer never loses sight that
a public twin exists. This local-view assembly never participates in
/sibling-sync's title-keyed bilateral matching, which reads committed entries
only.
Structure
All SYNERGY files use the same four-section structure:
## Shared Patterns
_No entries yet._
## Divergences
_No entries yet._
## Extraction Candidates
_No entries yet._
## They Have / We Don't
_No entries yet._
Section semantics:
Shared Patterns — practices, conventions, or implementations that exist
in both projects and should stay aligned
Divergences — places where the two projects intentionally or accidentally
differ in approach to the same problem
Extraction Candidates — code, patterns, or logic in this project that is
a strong candidate for extraction into a shared package or library
They Have / We Don't — capabilities in the sibling project that this
project lacks and may want to adopt. Apply the domain-fit test before
logging:
Pass test: "this project has the underlying need but lacks the implementation."
Fail test: "the sibling has a capability in a different domain than this project's."
Without this test, every comparison run produces noise the user must
dismiss. Worked failures from Sprint 19: vp-beads's swarm-wave (sprint
orchestration is a different domain from vp-claude's research fan-outs)
and vp-beads's vendor-sync (vp-beads vendors content; vp-claude has no
vendored surface to sync) both passed the surface filter but failed the
domain-fit test.
Workflows
Determine which workflow the user needs based on their request. If ambiguous,
default to workflow 1 (log) for "synergy" or "log this" requests, workflow 2
(review) for "review synergies" or "what's open" requests, and workflow 3
(compare) for "compare with" requests.
1. Log a synergy entry
When the user observes a shared pattern, a divergence, an extraction candidate,
or a capability gap between this project and a sibling — add it to the correct
file. Infer the details from the current conversation context: what code was
being discussed, what pattern was noticed, what contrast was made.
Steps:
- Identify which sibling project is involved from the conversation context.
If the user named a sibling project in their request (e.g., "compare with
vp-knowledge", "log this for vp-knowledge"), use that name directly — do
not ask again. Otherwise, check
.claude/synergy-registry.json first. If
the registry does not identify the sibling, glob for SYNERGY-*.md as a
fallback. If neither resolves it, ask the user.
Step 1b — Guided registry creation (only when
.claude/synergy-registry.json is absent AND a sibling has been named in
step 1). If the registry file already exists (returning user adding a
second sibling, or any case where a registry was hand-written), skip this
step silently and proceed to step 2 — do not modify hand-written
registries. Append-to-existing is not supported; that case falls back
to manual editing of .claude/synergy-registry.json (add a new
{name, file, remote, bm-entity, relationship} entry per the schema in
references/synergy-entry-format.md). Tracked separately as a future
enhancement (vp-beads-bma). Otherwise, run the following bootstrap so
the project can route future syncs and comparisons through the registry
rather than re-asking each time.
Confirm the sibling name resolved from step 1. If step 1 deferred to
asking the user, defer this step too — only proceed once a name is in
hand.
Derive both project names before proceeding.
<sibling> — the name confirmed in step 1. In practice this is already
the tier-3 registry name field (or, for unregistered siblings, the
directory basename: tier 4). No additional derivation is needed; just
carry the value forward.
<this-project> — this project's own canonical name, derived using
the four-tier algorithm in
skills/synergy-tracker/references/project-name-derivation.md (self
subject: tiers 1-4, starting with the sibling's back-pointer). In the
common case — vp-beads with a registered sibling — tier 1 or tier 2
resolves immediately. Use the normalized result as <this-project>
everywhere below: in the bm-entity value and in any reciprocal file
references.
Auto-derive the four registry fields that have unambiguous defaults:
name — already known from step 1.
file — mechanical: SYNERGY-<sibling>.md.
remote — probe the sibling's git origin if the sibling repo is
accessible on disk at ../<sibling>/:
git -C ../<sibling> remote get-url origin 2>/dev/null | sed 's/\.git$//'
If the command fails or the path is not accessible, leave remote as
an empty string in the preview.
bm-entity — apply the canonical convention
engineering/agents/vp-plugins-<this-project>-and-<sibling> (see
references/synergy-entry-format.md).
Prompt only the residuals. At most three AskUserQuestion calls
(Anthropic SDK caps the header field at 12 characters):
- First, a
header: "Visibility" (10 chars) call — "Public (committed
registry) or Private (gitignored — the sibling's name is never committed)?"
Default Public. Choose Private for a proprietary partner whose very
existence must stay out of a public repo. When the user picks Private,
switch to the private-sibling path:
- Write the entry to
.claude/synergy-registry.local.json only (never the
committed base), with file set to PRIVATE-SYNERGY-<sibling>.md.
- Omit
bm-entity entirely — a private name in a Basic Memory path would
leak it (the validator warns if present).
- Create the gitignored content file
PRIVATE-SYNERGY-<sibling>.md from the
four-section template (it is the sibling's sole synergy file — there is no
committed SYNERGY-<sibling>.md).
- Verify both
.claude/synergy-registry.local.json and the
PRIVATE-SYNERGY-*.md wildcard are gitignored (git check-ignore -q).
Never add a per-name PRIVATE-SYNERGY-<sibling>.md line to .gitignore
— that line would itself commit the name; the PRIVATE-SYNERGY-*.md
wildcard already covers it. If the wildcard is missing, warn the user to
add the wildcard line (not a per-name one).
- The preview shows ONLY the
.local.json block (no committed-registry
block, no bm-entity). Skip the Relationship-into-base step; relationship
still goes into the .local.json entry.
- One call with
header: "Relationship" (12 chars). The validator's
KNOWN_RELATIONSHIPS set caps options at six; AskUserQuestion caps at
4 visible options + auto "Other". Surface the four most common —
sibling-plugin (default), shared-tooling, fork, consumer — and
let the auto "Other" route to a free-text fallback that the workflow
then validates against the remaining two (coordinated-release,
dependency). If the user types anything else, warn that the value will
trigger a validate-plugin.mjs warning and confirm before writing. See
references/synergy-entry-format.md "Relationship vocabulary" for the
canonical set.
- Only when
../<sibling>/ does not resolve to an accessible directory, a
second call with header: "Local path" (10 chars) — free-text or
skip. If the user provides a path, it goes into
.claude/synergy-registry.local.json, never into the base registry.
Preview both files in a single message before writing anything. Use
this shape (omit the .local.json block when no local-path was
supplied). Show BOTH the placeholder schema and a worked substitution so
the user can see how <this-project> and <sibling> resolve. Annotate
auto-derived fields with their source as inline comments after rendering
(e.g. "remote": "https://github.com/voxpelli/vp-claude" # from <sibling> git origin, "bm-entity": "engineering/agents/..." # canonical convention) so the user can spot derivation errors before approving:
Proposed .claude/synergy-registry.json (schema):
[
{
"name": "<sibling>",
"file": "SYNERGY-<sibling>.md",
"remote": "<derived-or-blank>",
"bm-entity": "engineering/agents/vp-plugins-<this-project>-and-<sibling>",
"relationship": "<chosen>"
}
]
Worked example (this-project = vp-beads, sibling = vp-knowledge):
[
{
"name": "vp-knowledge",
"file": "SYNERGY-vp-knowledge.md",
"remote": "https://github.com/voxpelli/vp-claude",
"bm-entity": "engineering/agents/vp-plugins-vp-beads-and-vp-knowledge",
"relationship": "sibling-plugin"
}
]
Proposed .claude/synergy-registry.local.json (only if local-path given):
[
{ "name": "<sibling>", "local-path": "<path>" }
]
Confirm? [yes / edit / skip]
Handle the user's response. On yes, proceed to write. On edit,
re-prompt each derived field individually so the user can correct
name, remote, bm-entity, relationship, or the optional
local-path, then re-render the preview. On skip, continue the
workflow without writing the registry — resume to step 2.
Write the files using the Write tool. Always write
.claude/synergy-registry.json, and additionally write
.claude/synergy-registry.local.json only when a local-path was
provided. The .local.json is always a separate file — never embed
local-path in the committed base registry.
Verify round-trip. Use the Read tool to re-read each written file,
then validate the JSON via
node -e 'JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"))' <path>
(any non-zero exit signals invalid JSON). Confirm: base registry contains
entries with name and file set; if .local.json was written, it
contains name and local-path. On base-registry parse failure or
missing required fields, abort step 1b — report the problem and offer to
re-run; do not proceed to step 2 with a broken base registry. On
.local.json parse failure only, warn and continue without the local
override (the base registry is still usable).
Check that .local.json is gitignored when one was written:
git check-ignore -q .claude/synergy-registry.local.json
Exit status semantics: 0 = file is gitignored (no action); 1 = file
is not gitignored — warn the user with the exact line to add: "Add
.claude/*.local.json to your .gitignore (covers both
synergy-registry.local.json and vendor-registry.local.json, and is
forward-compatible with future .local.json registries)." Do not
auto-edit .gitignore — it is user-owned. 128 = the check itself
failed (not a git repo, or another git error) — report the underlying
error and skip the gitignore warning rather than emitting a
false-positive.
Resume to step 2 (Basic Memory pre-check).
- Basic Memory pre-check. If Basic Memory MCP tools are available, make
two
mcp__basic-memory__search_notes calls: one with the sibling project
name, one with 2-4 keywords describing the topic being logged (e.g.,
"PreCompact prompt command hook" or "edit_note append gotcha"). If either
search returns a matching note with synergy-related or engineering-pattern
content, surface it to the user: "This pattern is already tracked in Basic
Memory: [summary]. Logging it locally as well so this project tracks it."
If Basic Memory tools are not available, skip this step silently.
- If no
SYNERGY-<project>.md file exists yet, create it from the template
in references/synergy-entry-format.md (four sections with placeholders).
- Classify the entry into one of the four sections:
- Shared Pattern — the same approach exists in both projects
- Divergence — the projects handle this differently
- Extraction Candidate — this project has something worth extracting
- They Have / We Don't — the sibling has something we lack
- Read the target file. If the entry is proprietary (names a private
sibling's internal paths, client names, or unreleased plans that must not
reach a public repo), target the gitignored
PRIVATE-SYNERGY-<project>.md
overlay instead of the committed SYNERGY-<project>.md (see
### Private overlay). Before the first write to a new overlay, verify it is
ignored: git check-ignore -q PRIVATE-SYNERGY-<project>.md (exit 0 = ignored,
safe; exit 1 = NOT ignored — stop and have the user add PRIVATE-SYNERGY-*.md
to .gitignore first). Then, only for a public sibling that has a committed
SYNERGY-<project>.md, add a one-line pointer to that committed file
(e.g. "A private PRIVATE-SYNERGY-<project>.md overlay exists for this
sibling.") so collaborators know it may exist. For a fully-private sibling
(registered only in .local.json with file: PRIVATE-SYNERGY-<name>.md),
there is no committed SYNERGY-<name>.md and you write no pointer — a
pointer would commit the private name. Otherwise (a public sibling, ordinary
entry) target the committed SYNERGY-<project>.md.
- Compose the entry from this project's perspective using the entry format from
references/synergy-entry-format.md. Focus on impact and adoption cost, not
implementation internals.
- Add the entry under the correct section heading, using today's date. When
adding the first entry to a section, replace the
_No entries yet._
placeholder. Keep entries concise — 1-3 sentences. The title should be
scannable. Entries written to a PRIVATE-SYNERGY-*.md overlay are never
promoted to Basic Memory or reciprocated to a sibling (privacy invariant —
structurally enforced by the prefix).
Structured fields (all optional — omit fields that add no signal):
| Field |
Values |
Section |
Status: |
aligned · drifting |
Shared Patterns |
Last verified: |
YYYY-MM-DD (use today's date for new entries) |
Shared Patterns |
Convergence path: |
accept-difference · adopt-theirs · propose-shared |
Divergences |
Readiness: |
ready · needs-cleanup · proof-of-concept |
Extraction Candidates |
Priority: |
adopt-soon · consider · deferred |
They Have / We Don't |
Effort: |
trivial · moderate · significant |
Extraction Candidates, They Have / We Don't |
See references/synergy-entry-format.md for full entry format templates and
field value definitions.
Bilateral reciprocation mandate. When the sibling has already written
entries from their side (resolve the sibling path via the registry-with-override
pattern from workflow 3 (Compare with sibling) — local-path from the merged
registry, falling back to ../<sibling>/; check
<resolved-path>/SYNERGY-<this-project>.md if the sibling repo is accessible
on disk), reciprocate by re-verifying each
entry from this project's angle, recording your verification dates, and
noting any drift you observe. Do not skip duplicates — the reciprocation IS
the verification step. As captured in BM
engineering/agents/vp-plugins-vp-beads-and-vp-knowledge:
SYNERGY entries describe two parallel implementations that happen to be
aligned, not one shared thing — both sides need their own record so each
can verify from their POV at their own cadence. "Reciprocation IS the
verification step."
Sprint 19 evidence: vp-claude reciprocated 9 shared-pattern entries from
vp-beads's SYNERGY-vp-knowledge.md to a new SYNERGY-vp-beads.md, and the
re-verification surfaced 3 actively drifting artifacts
(validate-plugin.mjs 358 vs 333 lines; scripts/check-hooks.mjs 366 vs
284 lines; npm-run-all2 since-converged) plus 1 stale aligned row
(PreCompact retired post-v0.28.0 on the vp-claude side). When logging an
entry with no reciprocal yet on the sibling, prompt the user to file the
reciprocal entry on the sibling project (typically a follow-up task in the
sibling repo's bd backlog).
Eager promotion check. If Basic Memory MCP tools are available, assess
the project's tempo:
git rev-list --count --since="90 days ago" HEAD 2>/dev/null
Guard: skip if the repo has zero commits total
(git log --oneline -1 2>/dev/null returns empty). Also skip if this is
the first entry in any SYNERGY file for this project (the user is still
learning the workflow — promotion is premature).
| Tempo |
Commits in 90 days |
Promotion behavior |
| Dormant |
0–4 |
Offer inline promotion for any promotable entry |
| Moderate |
5–14 |
Offer only for Extraction Candidates with Readiness: ready |
| Active |
15+ |
Skip — the normal sprint cadence handles promotion |
When offering inline promotion, say: "This project has low commit
frequency — SYNERGY entries can sit unread for months. This entry looks
promotable to Basic Memory. Want to promote it now?"
If the user agrees, defer to workflow 5 (Promote to Basic Memory) for the
actual write — invoke its single-entry path scoped to this entry (steps 3-4
of workflow 5 (Promote to Basic Memory)). Step 8 only offers promotion;
workflow 5 (Promote to Basic Memory) performs it. This split keeps
## Cross-Project Synergy writes within workflow 5 (Promote to Basic Memory)'s
sole-owner boundary.
If the user declines, or if Basic Memory tools are not available, or if the
project is active, skip silently.
2. Review open synergies
Summarize the current state of all synergy tracking files.
Steps:
Glob for all SYNERGY-*.md files and read them. This is the one local-only
review, so ALSO glob PRIVATE-SYNERGY-*.md private overlays and assemble
the combined view per ### Private overlay: merge public + private entries
per section and label every private (PRIVATE-SYNERGY-sourced) row
[local]. When a [local] entry shares a title with a committed entry,
show both (committed row [committed, shadowed], private row [local])
so the promotable public twin stays visible. A [local] row is review-only:
never offer it as a reciprocation or Basic Memory promotion candidate (those
paths glob SYNERGY-*.md, which structurally cannot reach
PRIVATE-SYNERGY-*.md).
Present a summary grouped by file, showing counts per section and listing
each open entry with title and date.
Flag stale entries (older than 3 months with no activity). A Trend Review
entry resets the staleness clock for the entire file.
Highlight actionable items:
- Extraction Candidates with
Readiness: ready — extractable now
- Divergences with
Convergence path: of adopt-theirs or propose-shared
- They Have / We Don't with
Priority: adopt-soon
Inverse-file glob staleness detection (optional). For each sibling
represented by a SYNERGY-<sibling>.md file on this side, attempt to
read the inverse file — the sibling's SYNERGY-<this-project>.md —
to surface cross-side drift that single-side review cannot detect.
Reuse the registry-with-override path-resolution pattern from workflow 3
(Compare with sibling): prefer the local-path field on the merged
.claude/synergy-registry.json + .claude/synergy-registry.local.json
entry (relative paths resolve from the current project root); if absent,
fall back to ../<sibling>/SYNERGY-<this-project>.md. <this-project>
is this project's canonical name derived per
references/project-name-derivation.md (tiers 1–4, sibling
back-pointer first; in the common case the registered sibling's own
registry resolves it immediately).
Bilateral first. When the sibling repo is accessible AND the user wants
more than a single-side enrichment — full reciprocation gaps, status drift
in both directions, auto-reciprocation — defer to /sibling-sync
workflow 2 (Sync sibling SYNERGY) instead. Step 5 here only surfaces
inverse-file findings as a side-channel of the single-side review;
/sibling-sync is the authoritative bilateral tool.
Degradation. If the registry is missing, the sibling path does not
resolve, the inverse file is not present, or any read fails for any
reason, skip this step silently and continue with the regular
single-side review. Never hard-fail. The inverse-file step is a
best-effort enrichment, not a gate.
When the inverse file IS accessible, surface two classes of drift:
- Stale
aligned rows (staleness threshold: workflow 4
(Trend review (quarterly)) canonical — Last verified: more than two
trend-review cycles, ≈8 sprints). Entries marked Status: aligned on
this side whose corresponding entry on the sibling side shows measurable
drift — either the sibling lists the entry under ## Divergences
(contradicting our aligned), or the sibling's entry carries
Status: drifting, or the sibling has annotated the entry as
resolved/retired. The motivating example: vp-knowledge retired
PreCompact in v0.28.0 while this project's
SYNERGY-vp-knowledge.md still tagged PreCompact aligned 2026-04-05
— no automated detection caught the staleness until manual
reciprocation. Flag each such row with the sibling's contradicting
state so the user can reconcile.
- Missing-this-side rows. Features the sibling tracks under
## Shared Patterns (or any section) that no longer exist in this
project — typically because this project retired the feature without
updating the sibling-tracked entry. Surface them so the user can
either re-add the feature, mark the entry as resolved on both sides,
or escalate to /sibling-sync for bilateral reconciliation.
For deeper bilateral reconciliation (reciprocation gaps, status drift
in both directions, auto-reciprocation), defer to /sibling-sync
workflow 2 (Sync sibling SYNERGY) — workflow 2 (Review) here only
surfaces inverse-file findings as part of the single-side review
summary.
Output format:
## Synergy Status
### <project-name>
- Shared Patterns: N (N drifting)
- Divergences: N (N with active convergence path)
- Extraction Candidates: N (N ready)
- They Have / We Don't: N (N adopt-soon)
- [list each entry with title and date]
### Notes
- [stale entries]
- [actionable items]
- [inverse-file findings, if any: stale aligned rows, missing-this-side rows]
If all files are empty or no SYNERGY files exist, say so and suggest whether a
comparison run (workflow 3 (Compare with sibling)) would be useful — note that it
works best when the sibling repo is accessible on disk at the registry-resolved
path (local-path from the merged .claude/synergy-registry.json +
.claude/synergy-registry.local.json, falling back to ../<project-name>).
Source. The inverse-file glob step is sourced from
../vp-claude/UPSTREAM-vp-beads.md entry 3 (2026-05-04).
3. Compare with sibling
Perform a direct comparison between this project and a named sibling to surface
unlogged synergy observations.
Steps:
Identify the sibling from the user's request or the argument-hint — if
the user named a project, use that name directly without re-asking. Load
the registry with override merge:
- Read
.claude/synergy-registry.json for the sibling's remote and any
metadata.
- If
.claude/synergy-registry.local.json exists, read it and merge it on
top of the base registry. Match entries by the name key (the
human-stable identifier across machines and BM entity paths); for each
matched entry, fields present in .local.json win. A .local.json-only
entry (no matching base name) is added as a private sibling when its
file is PRIVATE-SYNERGY-<name>.md, and otherwise ignored (the base
registry is the authoritative source of which public siblings exist).
See references/synergy-entry-format.md "Private sibling entries".
If no project is identified from the argument, merged registry, or existing
SYNERGY files, ask the user which sibling project to compare with.
If no registry exists at all, also offer to create one via workflow 1 (Log a synergy entry) step 1b before proceeding with the comparison.
Gather sibling context. Resolve the sibling's local path: prefer the
local-path field on the merged registry entry (relative paths are resolved
from the current project root); if absent, fall back to ../<project-name>
relative to the current project root. If the resolved path is not
accessible, ask the user for the path (and suggest they record it in
.claude/synergy-registry.local.json to avoid re-prompting). Read the
sibling's key files if accessible:
package.json — dependencies, scripts, entry points
CLAUDE.md — conventions, architecture, workflow documentation
- Skill files (
Glob for skills/**/SKILL.md) — what skills exist, their
workflows, trigger phrases
- Hook definitions (
hooks/hooks.json) — event handling patterns
- Agent files (
Glob for agents/*.md) — what agents exist
If neither local files, conversation context, nor Basic Memory provides
substantive information about the sibling, stop and tell the user that a
meaningful comparison requires access to the sibling repo or prior
knowledge. Do not generate speculative entries.
Diff patterns. Compare against this project's equivalent files.
Identify observations in each of the four categories:
- Shared Patterns: conventions both projects use (same frontmatter fields,
same BM integration approach, same commit style)
- Divergences: structural or stylistic differences (different hook handling,
different reference doc organization, different BM section ownership)
- Extraction Candidates: logic in this project that would apply to the
sibling (validation scripts, shared reference formats, utility functions)
- They Have / We Don't: features or patterns in the sibling absent here
(agents, skills, hooks, conventions this project lacks)
Propose new entries. Present each observation as a candidate entry with
draft text matching the format in references/synergy-entry-format.md. For
each, ask: "Log this as a [category] entry for [sibling]?" The user
approves, edits, or skips each candidate. No mutations without approval.
Log confirmed entries by classifying, reading the file, composing, and
adding per workflow 1 (Log) steps 4–7. Skip step 8 (eager promotion) for batch
entries to avoid prompt fatigue. Offer a single summary at the end:
"N entries logged. Run workflow 2 (Review) to review the full picture."
If the user skips all candidates, report that no entries were logged and
suggest whether a follow-up comparison with different focus areas would be
useful.
5. Promote to Basic Memory
Promote generalizable cross-project synergy entries from project-local
SYNERGY-*.md files into sibling project entity notes in Basic Memory. This
creates or extends a ## Cross-Project Synergy section in the target sibling
note (typically at engineering/agents/vp-plugins-<this-project>-and-<sibling>).
Use only MCP tools from this skill's allowed-tools —
mcp__basic-memory__search_notes, mcp__basic-memory__read_note,
mcp__basic-memory__edit_note. If Basic Memory MCP tools are not available,
report that promotion is unavailable and suggest checking Basic Memory manually.
Steps:
- Scan for candidates. Glob all
SYNERGY-*.md files and read them. (This
glob structurally excludes every PRIVATE-SYNERGY-*.md — both private
overlays of public siblings and the sole content file of a private
sibling registered via .local.json. Neither is ever promoted; their names
must never reach Basic Memory. See ### Private overlay and
references/synergy-entry-format.md "Private sibling entries".) Filter
eligible entries by section + structured fields:
- Extraction Candidates with
Readiness: ready (always)
- Shared Patterns with
Status: aligned (always)
- Shared Patterns with
Status: drifting (flag the drift in the draft)
- Extraction Candidates with
Readiness: needs-cleanup or
proof-of-concept (lower priority — surface but mark as such)
- Divergences with
Convergence path: adopt-theirs or propose-shared
(skip accept-difference — by definition not promotion-worthy)
- They Have / We Don't with
Priority: adopt-soon (skip deferred)
- Skip any entry already annotated with
_(Promoted YYYY-MM-DD)_ —
that annotation is the dedup signal written in step 4 below.
- Present candidates to the user. Per-entry, never auto-promote. For
each candidate, show:
- Sibling project name and target BM note path
- Section (Shared Pattern / Divergence / Extraction Candidate / They
Have / We Don't) and entry title
- A draft generalized version. Apply the transforms documented in
references/synergy-bm-format.md: strip dates from titles,
project-specific file paths, sprint numbers, and bd issue IDs;
rewrite the prose from a neutral symmetric POV (so any sibling can
read the entry as authoritative); keep Status:, Convergence path:,
Readiness:, Priority:, and Effort: fields verbatim because they
carry cross-project meaning.
- Whether a Basic Memory note already exists for this sibling.
Let the user approve, edit, or skip each candidate.
- Route by target. For each approved candidate, look up the sibling's
bm-entity value from .claude/synergy-registry.json (with
.claude/synergy-registry.local.json merged on top by the name key).
If bm-entity is present, use it as the BM note path. If absent, call
mcp__basic-memory__search_notes with the sibling project name and
surface the candidate matches to the user. Legacy bm-entity form
warning: if the registered bm-entity does NOT start with
engineering/agents/vp-plugins- (the canonical convention from v0.12.1
onward), warn the user before proceeding: "Registered bm-entity
<value> does not match the canonical
engineering/agents/vp-plugins-<this-project>-and-<sibling> form. This
may be a pre-v0.12.1 registry pointing at a single-project entity note
(e.g. npm/<sibling>) — workflow 5 (Promote to Basic Memory) will
write to that legacy location, which may scatter cross-project content.
Recommended: update the registry to the canonical form and migrate any
existing ## Cross-Project Synergy content to
engineering/agents/vp-plugins-<this-project>-and-<sibling> first." Ask
the user whether to proceed anyway, abort, or migrate. Stale
bm-entity fallback:
if bm-entity is present but step 4's read_note returns not-found
(the registry path has been renamed or deleted), warn the user
("BM note not found at <bm-entity> — registry may be stale") and
fall through to mcp__basic-memory__search_notes exactly as the
absent-bm-entity row does. The full routing table — including the
fallback search order (engineering/agents/ for relationship notes,
then projects/ and npm/ as last-resort fallbacks for unregistered
siblings) — lives in references/synergy-bm-format.md.
- Write or flag. Three branches per approved candidate:
- Note exists, has
## Cross-Project Synergy with target subsection —
call mcp__basic-memory__read_note first to fetch exact content, then
mcp__basic-memory__edit_note with find_replace anchored to the next
### heading for uniqueness, expected_replacements=1. Deduplicate by
entry title (case-insensitive, whitespace-trimmed) before appending — if
the title already appears in the subsection, skip. If find_replace
returns zero replacements despite expected_replacements=1, the note was
edited between read_note and edit_note — do NOT annotate the local
entry; defer this candidate (increment a deferred-count) and continue
with the next candidate. The step 6 report includes deferred entries
under "deferred (BM note changed mid-write): N entries — re-run
workflow 5 (Promote to Basic Memory) once BM writes settle." Do NOT
re-invoke workflow 5 (Promote to Basic Memory) automatically inside
the same run; persistent contention would otherwise loop.
- Note exists, no
## Cross-Project Synergy section — call
mcp__basic-memory__edit_note with insert_before_section on
Relations to add the full section block (all five subsections per the
template in references/synergy-bm-format.md).
- No note exists — do NOT create a thin note. Flag for enrichment:
"No Basic Memory note for
<sibling>. Enrich it first (manual creation
under engineering/agents/), then re-run workflow 5 (Promote to Basic
Memory)."
- After successful write, annotate the local SYNERGY entry with
_(Promoted YYYY-MM-DD)_ via the Edit tool. This is the dedup signal
that step 1 consults on subsequent runs.
- See
references/synergy-bm-format.md for edit_note gotchas (never
use append with section, always read_note first, anchor
find_replace matches to the next ### heading).
- Prune pass. For entries already annotated
_(Resolved ...)_ in the
local SYNERGY file, offer to move the corresponding BM entry to the
### Resolved subsection of ## Cross-Project Synergy in the sibling
note. The user confirms each. Mirrors upstream-tracker workflow 6
(Promote to Basic Memory) prune-pass behavior.
- Report. Summarize: promoted count, pruned count, skipped count
(already-promoted), and flagged-for-enrichment count. Suggest verifying
the result with
build_context("memory://engineering/agents/vp-plugins-<this-project>-and-<sibling>").
See references/synergy-bm-format.md for the target section structure,
generalization transform rules, and edit_note gotchas.
Division of labor: This workflow owns the ## Cross-Project Synergy
section of sibling project entity notes in Basic Memory. The
upstream-tracker skill's workflow 6 (Promote to Basic Memory) owns
## Upstream Friction in package/tool entity notes. The retrospective
skill's step 7 owns engineering/* notes (patterns, conventions, lessons).
These three sections never overlap — synergy entries are cross-project,
upstream friction is package-specific, learnings are domain-specific.
4. Trend review (quarterly)
Every 4th sprint, perform a cross-cutting analysis of all SYNERGY tracking
files. This cadence aligns with the every-4th-sprint trend review used by
/retrospective and /upstream-tracker (see CLAUDE.md and MEMORY.md). It
replaces the interim workaround of running workflow 2 (Review) manually at
trend-review boundaries.
Input signals:
- Glob for all
SYNERGY-*.md files and read them. (Trend review is a
boundary-crossing path — step 5 cross-references Basic Memory and step 8
recommends workflow 5 (Promote to Basic Memory) — so private overlays must be
excluded; the SYNERGY-*.md glob does this structurally, since it cannot
match PRIVATE-SYNERGY-*.md. Private entries are reviewed via workflow 2
(Review)'s local-only view, never trend-prom
…(truncated)
1---2name: synergy-tracker3description: "Manage cross-project synergy tracking between sibling projects. Use when the user wants to log a shared pattern, a divergence, an extraction candidate, or something a sibling project has that this one doesn't. Also use when the user wants to promote synergy entries to Basic Memory (workflow 5). NOT for upstream dependency bugs or vendor friction (use /upstream-tracker for those). Trigger phrases: 'synergy', 'sibling project', 'cross-project', 'extraction candidate', 'compare with [project]', 'both projects do', 'they have X we don't', 'shared pattern', 'divergence', 'cross-project alignment', 'review synergies', 'log this pattern', 'we should extract this', 'they handle this differently', 'promote synergy', 'promote to basic memory', 'promote synergy entries', 'sync synergy to memory', or any mention of patterns, divergences, shared practices, or BM promotion across related projects."4user-invocable: true5argument-hint: "[workflow] [project-name]"6paths:7 - "SYNERGY-*.md"8 - "PRIVATE-SYNERGY-*.md"9 - ".claude/synergy-registry.json"10allowed-tools:11 - Read12 - Write13 - Edit14 - Glob15 - Grep16 - Bash17 - AskUserQuestion18 - mcp__basic-memory__search_notes19 - mcp__basic-memory__read_note20 - mcp__basic-memory__edit_note21metadata:22 source: https://skillmd.com/skills/voxpelli/synergy-tracker23---2425# Synergy Tracker2627Manage the `SYNERGY-*.md` files that track shared patterns, divergences,28extraction candidates, and capabilities observed in sibling projects while29building this one. This skill tracks patterns and capabilities across30peer/sibling projects under the same maintainer — not upstream dependency31friction (use `/upstream-tracker` for that).3233## Tracking Files3435### Sibling projects (permanent files)3637Sibling projects are declared in `.claude/synergy-registry.json` (if it exists)38as an array of `{name, file, remote, bm-entity, relationship}` objects. See39`references/synergy-entry-format.md` for the full registry schema.4041To discover which projects are registered, read `.claude/synergy-registry.json`42if it exists. If it does not exist, glob for `SYNERGY-*.md` to infer sibling43names from existing files. If neither is present, ask the user which sibling44project is involved before proceeding.4546### File naming4748Files are named `SYNERGY-<project-name>.md`. The project name is taken from49the `name` field in the registry (tier 3 of the canonical derivation50algorithm — synergy-tracker's subject is always sibling). For projects51outside the registry, fall back to tier 4 (directory basename), then52normalize. Full algorithm:53`references/project-name-derivation.md`. Examples: `vp-knowledge` →54`SYNERGY-vp-knowledge.md`, `@scope/shared-utils` →55`SYNERGY-scope--shared-utils.md`.5657See `references/synergy-entry-format.md` for the full naming convention58(normalization rules) and `references/project-name-derivation.md` for the59tiered derivation algorithm shared with `/sibling-sync`.6061### Lifecycle6263SYNERGY files are **permanent** — they always exist for registered sibling64projects, even when all sections are empty. When an entry is resolved or65dismissed, remove it and restore the `_No entries yet._` placeholder for that66section. Do not delete the file.6768### Private overlay (`PRIVATE-SYNERGY-*.md`)6970For entries that must stay out of a public repo (a proprietary sibling's71internal paths, client names, unreleased plans), use a **gitignored**72`PRIVATE-SYNERGY-<project-name>.md` companion to the committed73`SYNERGY-<project-name>.md`. It holds additional private entries under the same74four section headings.7576**The `PRIVATE-` prefix is the privacy mechanism.** It keeps the overlay77OUTSIDE the `SYNERGY-*.md` glob namespace, so every public consumer (this78skill's boundary-crossing workflows, `/sibling-sync`, `/retrospective`, the79`sprint-review` agent, `session-start.sh`) **structurally cannot read it** — no80per-consumer exclusion is needed or used. Only the deliberate *local-only* read81in workflow 2 (Review) additionally globs `PRIVATE-SYNERGY-*.md` to assemble the82combined private view.8384**Invariant: private-overlay entries are NEVER promoted to Basic Memory85(workflow 5 (Promote to Basic Memory)) and NEVER reciprocated/written to a86sibling.** With the prefix scheme this is enforced structurally — the promote87and reciprocate paths glob `SYNERGY-*.md`, which cannot match88`PRIVATE-SYNERGY-*.md`. This keeps the public view a sibling sees stable (so89bilateral convergence still works) and prevents a proprietary↔public leak.9091When a `PRIVATE-SYNERGY-*.md` overlay exists, the committed92`SYNERGY-<project-name>.md` carries a one-line pointer noting it (gitignored93files are invisible to collaborators and `git grep`). Gitignored via the94explicit `PRIVATE-SYNERGY-*.md` line; `session-start.sh` warns if any is95tracked. Full convention: CLAUDE.md `### Synergy tracking convention`.9697**Same-title shadowing (workflow 2 (Review) only).** When a private entry shares98a title with a committed entry, surface **both** in the review view — the99committed row (still promotable/reciprocable) labelled `[committed, shadowed]`100and the private row labelled `[local]` — so the reviewer never loses sight that101a public twin exists. This local-view assembly never participates in102`/sibling-sync`'s title-keyed bilateral matching, which reads committed entries103only.104105### Structure106107All SYNERGY files use the same four-section structure:108109```110## Shared Patterns111112_No entries yet._113114## Divergences115116_No entries yet._117118## Extraction Candidates119120_No entries yet._121122## They Have / We Don't123124_No entries yet._125```126127Section semantics:128129- **Shared Patterns** — practices, conventions, or implementations that exist130 in both projects and should stay aligned131- **Divergences** — places where the two projects intentionally or accidentally132 differ in approach to the same problem133- **Extraction Candidates** — code, patterns, or logic in this project that is134 a strong candidate for extraction into a shared package or library135- **They Have / We Don't** — capabilities in the sibling project that this136 project lacks and may want to adopt. Apply the **domain-fit test** before137 logging:138139 > Pass test: "this project has the underlying need but lacks the implementation."140 > Fail test: "the sibling has a capability in a different domain than this project's."141142 Without this test, every comparison run produces noise the user must143 dismiss. Worked failures from Sprint 19: vp-beads's `swarm-wave` (sprint144 orchestration is a different domain from vp-claude's research fan-outs)145 and vp-beads's `vendor-sync` (vp-beads vendors content; vp-claude has no146 vendored surface to sync) both passed the surface filter but failed the147 domain-fit test.148149## Workflows150151Determine which workflow the user needs based on their request. If ambiguous,152default to workflow 1 (log) for "synergy" or "log this" requests, workflow 2153(review) for "review synergies" or "what's open" requests, and workflow 3154(compare) for "compare with" requests.155156### 1. Log a synergy entry157158When the user observes a shared pattern, a divergence, an extraction candidate,159or a capability gap between this project and a sibling — add it to the correct160file. Infer the details from the current conversation context: what code was161being discussed, what pattern was noticed, what contrast was made.162163**Steps:**1641651. Identify which sibling project is involved from the conversation context.166 If the user named a sibling project in their request (e.g., "compare with167 vp-knowledge", "log this for vp-knowledge"), use that name directly — do168 not ask again. Otherwise, check `.claude/synergy-registry.json` first. If169 the registry does not identify the sibling, glob for `SYNERGY-*.md` as a170 fallback. If neither resolves it, ask the user.171172**Step 1b — Guided registry creation (only when173`.claude/synergy-registry.json` is absent AND a sibling has been named in174step 1).** If the registry file already exists (returning user adding a175second sibling, or any case where a registry was hand-written), skip this176step silently and proceed to step 2 — do not modify hand-written177registries. **Append-to-existing is not supported**; that case falls back178to manual editing of `.claude/synergy-registry.json` (add a new179`{name, file, remote, bm-entity, relationship}` entry per the schema in180`references/synergy-entry-format.md`). Tracked separately as a future181enhancement (`vp-beads-bma`). Otherwise, run the following bootstrap so182the project can route future syncs and comparisons through the registry183rather than re-asking each time.184185- **Confirm the sibling name** resolved from step 1. If step 1 deferred to186 asking the user, defer this step too — only proceed once a name is in187 hand.188189- **Derive both project names before proceeding.**190 - `<sibling>` — the name confirmed in step 1. In practice this is already191 the tier-3 registry `name` field (or, for unregistered siblings, the192 directory basename: tier 4). No additional derivation is needed; just193 carry the value forward.194 - `<this-project>` — this project's own canonical name, derived using195 the four-tier algorithm in196 `skills/synergy-tracker/references/project-name-derivation.md` (self197 subject: tiers 1-4, starting with the sibling's back-pointer). In the198 common case — `vp-beads` with a registered sibling — tier 1 or tier 2199 resolves immediately. Use the normalized result as `<this-project>`200 everywhere below: in the `bm-entity` value and in any reciprocal file201 references.202203- **Auto-derive the four registry fields** that have unambiguous defaults:204 - `name` — already known from step 1.205 - `file` — mechanical: `SYNERGY-<sibling>.md`.206 - `remote` — probe the sibling's git origin if the sibling repo is207 accessible on disk at `../<sibling>/`:208209 ```bash210 git -C ../<sibling> remote get-url origin 2>/dev/null | sed 's/\.git$//'211 ```212213 If the command fails or the path is not accessible, leave `remote` as214 an empty string in the preview.215 - `bm-entity` — apply the canonical convention216 `engineering/agents/vp-plugins-<this-project>-and-<sibling>` (see217 `references/synergy-entry-format.md`).218219- **Prompt only the residuals.** At most three `AskUserQuestion` calls220 (Anthropic SDK caps the `header` field at 12 characters):221 - **First, a `header: "Visibility"` (10 chars) call** — "Public (committed222 registry) or Private (gitignored — the sibling's name is never committed)?"223 Default **Public**. Choose **Private** for a proprietary partner whose very224 existence must stay out of a public repo. When the user picks **Private**,225 switch to the private-sibling path:226 - Write the entry to `.claude/synergy-registry.local.json` only (never the227 committed base), with `file` set to `PRIVATE-SYNERGY-<sibling>.md`.228 - **Omit `bm-entity` entirely** — a private name in a Basic Memory path would229 leak it (the validator warns if present).230 - Create the gitignored content file `PRIVATE-SYNERGY-<sibling>.md` from the231 four-section template (it is the sibling's sole synergy file — there is no232 committed `SYNERGY-<sibling>.md`).233 - Verify both `.claude/synergy-registry.local.json` and the234 `PRIVATE-SYNERGY-*.md` wildcard are gitignored (`git check-ignore -q`).235 **Never add a per-name `PRIVATE-SYNERGY-<sibling>.md` line to `.gitignore`**236 — that line would itself commit the name; the `PRIVATE-SYNERGY-*.md`237 wildcard already covers it. If the wildcard is missing, warn the user to238 add the wildcard line (not a per-name one).239 - The preview shows ONLY the `.local.json` block (no committed-registry240 block, no `bm-entity`). Skip the Relationship-into-base step; relationship241 still goes into the `.local.json` entry.242 - One call with `header: "Relationship"` (12 chars). The validator's243 `KNOWN_RELATIONSHIPS` set caps options at six; `AskUserQuestion` caps at244 4 visible options + auto "Other". Surface the four most common —245 `sibling-plugin` (default), `shared-tooling`, `fork`, `consumer` — and246 let the auto "Other" route to a free-text fallback that the workflow247 then validates against the remaining two (`coordinated-release`,248 `dependency`). If the user types anything else, warn that the value will249 trigger a `validate-plugin.mjs` warning and confirm before writing. See250 `references/synergy-entry-format.md` "Relationship vocabulary" for the251 canonical set.252 - Only when `../<sibling>/` does not resolve to an accessible directory, a253 second call with `header: "Local path"` (10 chars) — free-text or254 skip. If the user provides a path, it goes into255 `.claude/synergy-registry.local.json`, never into the base registry.256257- **Preview both files in a single message** before writing anything. Use258 this shape (omit the `.local.json` block when no local-path was259 supplied). Show BOTH the placeholder schema and a worked substitution so260 the user can see how `<this-project>` and `<sibling>` resolve. **Annotate261 auto-derived fields with their source** as inline comments after rendering262 (e.g. `"remote": "https://github.com/voxpelli/vp-claude" # from <sibling>263 git origin`, `"bm-entity": "engineering/agents/..." # canonical264 convention`) so the user can spot derivation errors before approving:265266 ```267 Proposed .claude/synergy-registry.json (schema):268 [269 {270 "name": "<sibling>",271 "file": "SYNERGY-<sibling>.md",272 "remote": "<derived-or-blank>",273 "bm-entity": "engineering/agents/vp-plugins-<this-project>-and-<sibling>",274 "relationship": "<chosen>"275 }276 ]277278 Worked example (this-project = vp-beads, sibling = vp-knowledge):279 [280 {281 "name": "vp-knowledge",282 "file": "SYNERGY-vp-knowledge.md",283 "remote": "https://github.com/voxpelli/vp-claude",284 "bm-entity": "engineering/agents/vp-plugins-vp-beads-and-vp-knowledge",285 "relationship": "sibling-plugin"286 }287 ]288289 Proposed .claude/synergy-registry.local.json (only if local-path given):290 [291 { "name": "<sibling>", "local-path": "<path>" }292 ]293294 Confirm? [yes / edit / skip]295 ```296297- **Handle the user's response.** On `yes`, proceed to write. On `edit`,298 re-prompt each derived field individually so the user can correct299 `name`, `remote`, `bm-entity`, `relationship`, or the optional300 `local-path`, then re-render the preview. On `skip`, continue the301 workflow without writing the registry — resume to step 2.302303- **Write the files using the `Write` tool.** Always write304 `.claude/synergy-registry.json`, and additionally write305 `.claude/synergy-registry.local.json` only when a `local-path` was306 provided. The `.local.json` is always a separate file — never embed307 `local-path` in the committed base registry.308309- **Verify round-trip.** Use the `Read` tool to re-read each written file,310 then validate the JSON via311 `node -e 'JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"))' <path>`312 (any non-zero exit signals invalid JSON). Confirm: base registry contains313 entries with `name` and `file` set; if `.local.json` was written, it314 contains `name` and `local-path`. On base-registry parse failure or315 missing required fields, abort step 1b — report the problem and offer to316 re-run; do not proceed to step 2 with a broken base registry. On317 `.local.json` parse failure only, warn and continue without the local318 override (the base registry is still usable).319320- **Check that `.local.json` is gitignored** when one was written:321322 ```bash323 git check-ignore -q .claude/synergy-registry.local.json324 ```325326 Exit status semantics: `0` = file is gitignored (no action); `1` = file327 is **not** gitignored — warn the user with the exact line to add: "Add328 `.claude/*.local.json` to your `.gitignore` (covers both329 synergy-registry.local.json and vendor-registry.local.json, and is330 forward-compatible with future `.local.json` registries)." Do not331 auto-edit `.gitignore` — it is user-owned. `128` = the check itself332 failed (not a git repo, or another git error) — report the underlying333 error and skip the gitignore warning rather than emitting a334 false-positive.335336- **Resume to step 2** (Basic Memory pre-check).3373382. **Basic Memory pre-check.** If Basic Memory MCP tools are available, make339 two `mcp__basic-memory__search_notes` calls: one with the sibling project340 name, one with 2-4 keywords describing the topic being logged (e.g.,341 "PreCompact prompt command hook" or "edit\_note append gotcha"). If either342 search returns a matching note with synergy-related or engineering-pattern343 content, surface it to the user: "This pattern is already tracked in Basic344 Memory: \[summary]. Logging it locally as well so this project tracks it."345 If Basic Memory tools are not available, skip this step silently.3463. If no `SYNERGY-<project>.md` file exists yet, create it from the template347 in `references/synergy-entry-format.md` (four sections with placeholders).3484. Classify the entry into one of the four sections:349 - **Shared Pattern** — the same approach exists in both projects350 - **Divergence** — the projects handle this differently351 - **Extraction Candidate** — this project has something worth extracting352 - **They Have / We Don't** — the sibling has something we lack3535. Read the target file. **If the entry is proprietary** (names a private354 sibling's internal paths, client names, or unreleased plans that must not355 reach a public repo), target the gitignored `PRIVATE-SYNERGY-<project>.md`356 overlay instead of the committed `SYNERGY-<project>.md` (see357 `### Private overlay`). Before the first write to a new overlay, verify it is358 ignored: `git check-ignore -q PRIVATE-SYNERGY-<project>.md` (exit 0 = ignored,359 safe; exit 1 = NOT ignored — stop and have the user add `PRIVATE-SYNERGY-*.md`360 to `.gitignore` first). Then, **only for a public sibling that has a committed361 `SYNERGY-<project>.md`**, add a one-line pointer to that committed file362 (e.g. "*A private `PRIVATE-SYNERGY-<project>.md` overlay exists for this363 sibling.*") so collaborators know it may exist. **For a fully-private sibling**364 (registered only in `.local.json` with `file: PRIVATE-SYNERGY-<name>.md`),365 there is **no** committed `SYNERGY-<name>.md` and you write **no** pointer — a366 pointer would commit the private name. Otherwise (a public sibling, ordinary367 entry) target the committed `SYNERGY-<project>.md`.3686. Compose the entry from this project's perspective using the entry format from369 `references/synergy-entry-format.md`. Focus on impact and adoption cost, not370 implementation internals.3717. Add the entry under the correct section heading, using today's date. When372 adding the first entry to a section, replace the `_No entries yet._`373 placeholder. Keep entries concise — 1-3 sentences. The title should be374 scannable. **Entries written to a `PRIVATE-SYNERGY-*.md` overlay are never375 promoted to Basic Memory or reciprocated to a sibling** (privacy invariant —376 structurally enforced by the prefix).377378**Structured fields** (all optional — omit fields that add no signal):379380| Field | Values | Section |381| ------------------- | ------------------------------------------------------- | ------------------------------------------- |382| `Status:` | `aligned` · `drifting` | Shared Patterns |383| `Last verified:` | `YYYY-MM-DD` (use today's date for new entries) | Shared Patterns |384| `Convergence path:` | `accept-difference` · `adopt-theirs` · `propose-shared` | Divergences |385| `Readiness:` | `ready` · `needs-cleanup` · `proof-of-concept` | Extraction Candidates |386| `Priority:` | `adopt-soon` · `consider` · `deferred` | They Have / We Don't |387| `Effort:` | `trivial` · `moderate` · `significant` | Extraction Candidates, They Have / We Don't |388389See `references/synergy-entry-format.md` for full entry format templates and390field value definitions.391392**Bilateral reciprocation mandate.** When the sibling has already written393entries from their side (resolve the sibling path via the registry-with-override394pattern from workflow 3 (Compare with sibling) — `local-path` from the merged395registry, falling back to `../<sibling>/`; check396`<resolved-path>/SYNERGY-<this-project>.md` if the sibling repo is accessible397on disk), reciprocate by re-verifying each398entry from this project's angle, recording your verification dates, and399noting any drift you observe. Do not skip duplicates — the reciprocation IS400the verification step. As captured in BM401`engineering/agents/vp-plugins-vp-beads-and-vp-knowledge`:402403> SYNERGY entries describe two parallel implementations that *happen* to be404> aligned, not one shared thing — both sides need their own record so each405> can verify from their POV at their own cadence. "Reciprocation IS the406> verification step."407408Sprint 19 evidence: vp-claude reciprocated 9 shared-pattern entries from409vp-beads's `SYNERGY-vp-knowledge.md` to a new `SYNERGY-vp-beads.md`, and the410re-verification surfaced 3 actively drifting artifacts411(`validate-plugin.mjs` 358 vs 333 lines; `scripts/check-hooks.mjs` 366 vs412284 lines; `npm-run-all2` since-converged) plus 1 stale `aligned` row413(PreCompact retired post-v0.28.0 on the vp-claude side). When logging an414entry with no reciprocal yet on the sibling, prompt the user to file the415reciprocal entry on the sibling project (typically a follow-up task in the416sibling repo's bd backlog).4174188. **Eager promotion check.** If Basic Memory MCP tools are available, assess419 the project's tempo:420421 ```bash422 git rev-list --count --since="90 days ago" HEAD 2>/dev/null423 ```424425 Guard: skip if the repo has zero commits total426 (`git log --oneline -1 2>/dev/null` returns empty). Also skip if this is427 the first entry in any SYNERGY file for this project (the user is still428 learning the workflow — promotion is premature).429430 | Tempo | Commits in 90 days | Promotion behavior |431 | ------------ | ------------------ | ------------------------------------------------------------ |432 | **Dormant** | 0–4 | Offer inline promotion for any promotable entry |433 | **Moderate** | 5–14 | Offer only for Extraction Candidates with `Readiness: ready` |434 | **Active** | 15+ | Skip — the normal sprint cadence handles promotion |435436 When offering inline promotion, say: "This project has low commit437 frequency — SYNERGY entries can sit unread for months. This entry looks438 promotable to Basic Memory. Want to promote it now?"439440 If the user agrees, defer to workflow 5 (Promote to Basic Memory) for the441 actual write — invoke its single-entry path scoped to this entry (steps 3-4442 of workflow 5 (Promote to Basic Memory)). Step 8 only **offers** promotion;443 workflow 5 (Promote to Basic Memory) **performs** it. This split keeps444 `## Cross-Project Synergy` writes within workflow 5 (Promote to Basic Memory)'s445 sole-owner boundary.446447 If the user declines, or if Basic Memory tools are not available, or if the448 project is active, skip silently.449450### 2. Review open synergies451452Summarize the current state of all synergy tracking files.453454**Steps:**4554561. Glob for all `SYNERGY-*.md` files and read them. **This is the one local-only457 review, so ALSO glob `PRIVATE-SYNERGY-*.md` private overlays** and assemble458 the combined view per `### Private overlay`: merge public + private entries459 per section and **label every private (`PRIVATE-SYNERGY`-sourced) row460 `[local]`**. When a `[local]` entry shares a title with a committed entry,461 show **both** (committed row `[committed, shadowed]`, private row `[local]`)462 so the promotable public twin stays visible. A `[local]` row is review-only:463 never offer it as a reciprocation or Basic Memory promotion candidate (those464 paths glob `SYNERGY-*.md`, which structurally cannot reach465 `PRIVATE-SYNERGY-*.md`).4662. Present a summary grouped by file, showing counts per section and listing467 each open entry with title and date.4683. Flag stale entries (older than 3 months with no activity). A Trend Review469 entry resets the staleness clock for the entire file.4704. Highlight actionable items:471 - Extraction Candidates with `Readiness: ready` — extractable now472 - Divergences with `Convergence path:` of `adopt-theirs` or `propose-shared`473 - They Have / We Don't with `Priority: adopt-soon`4745. **Inverse-file glob staleness detection (optional).** For each sibling475 represented by a `SYNERGY-<sibling>.md` file on this side, attempt to476 read the inverse file — the sibling's `SYNERGY-<this-project>.md` —477 to surface cross-side drift that single-side review cannot detect.478 Reuse the registry-with-override path-resolution pattern from workflow 3479 (Compare with sibling): prefer the `local-path` field on the merged480 `.claude/synergy-registry.json` + `.claude/synergy-registry.local.json`481 entry (relative paths resolve from the current project root); if absent,482 fall back to `../<sibling>/SYNERGY-<this-project>.md`. `<this-project>`483 is this project's canonical name derived per484 `references/project-name-derivation.md` (tiers 1–4, sibling485 back-pointer first; in the common case the registered sibling's own486 registry resolves it immediately).487488 **Bilateral first.** When the sibling repo is accessible AND the user wants489 more than a single-side enrichment — full reciprocation gaps, status drift490 in both directions, auto-reciprocation — defer to `/sibling-sync`491 workflow 2 (Sync sibling SYNERGY) instead. Step 5 here only surfaces492 inverse-file findings as a side-channel of the single-side review;493 `/sibling-sync` is the authoritative bilateral tool.494495 **Degradation.** If the registry is missing, the sibling path does not496 resolve, the inverse file is not present, or any read fails for any497 reason, **skip this step silently and continue with the regular498 single-side review.** Never hard-fail. The inverse-file step is a499 best-effort enrichment, not a gate.500501 When the inverse file IS accessible, surface two classes of drift:502503 - **Stale `aligned` rows** (staleness threshold: workflow 4504 (Trend review (quarterly)) canonical — `Last verified:` more than two505 trend-review cycles, ≈8 sprints). Entries marked `Status: aligned` on506 this side whose corresponding entry on the sibling side shows measurable507 drift — either the sibling lists the entry under `## Divergences`508 (contradicting our `aligned`), or the sibling's entry carries509 `Status: drifting`, or the sibling has annotated the entry as510 resolved/retired. The motivating example: vp-knowledge retired511 `PreCompact` in v0.28.0 while this project's512 `SYNERGY-vp-knowledge.md` still tagged `PreCompact aligned 2026-04-05`513 — no automated detection caught the staleness until manual514 reciprocation. Flag each such row with the sibling's contradicting515 state so the user can reconcile.516 - **Missing-this-side rows.** Features the sibling tracks under517 `## Shared Patterns` (or any section) that no longer exist in this518 project — typically because this project retired the feature without519 updating the sibling-tracked entry. Surface them so the user can520 either re-add the feature, mark the entry as resolved on both sides,521 or escalate to `/sibling-sync` for bilateral reconciliation.522523 For deeper bilateral reconciliation (reciprocation gaps, status drift524 in both directions, auto-reciprocation), defer to `/sibling-sync`525 workflow 2 (Sync sibling SYNERGY) — workflow 2 (Review) here only526 surfaces inverse-file findings as part of the single-side review527 summary.528529**Output format:**530531```532## Synergy Status533534### <project-name>535536- Shared Patterns: N (N drifting)537- Divergences: N (N with active convergence path)538- Extraction Candidates: N (N ready)539- They Have / We Don't: N (N adopt-soon)540- [list each entry with title and date]541542### Notes543544- [stale entries]545- [actionable items]546- [inverse-file findings, if any: stale aligned rows, missing-this-side rows]547```548549If all files are empty or no SYNERGY files exist, say so and suggest whether a550comparison run (workflow 3 (Compare with sibling)) would be useful — note that it551works best when the sibling repo is accessible on disk at the registry-resolved552path (`local-path` from the merged `.claude/synergy-registry.json` +553`.claude/synergy-registry.local.json`, falling back to `../<project-name>`).554555**Source.** The inverse-file glob step is sourced from556`../vp-claude/UPSTREAM-vp-beads.md` entry 3 (2026-05-04).557558### 3. Compare with sibling559560Perform a direct comparison between this project and a named sibling to surface561unlogged synergy observations.562563**Steps:**5645651. Identify the sibling from the user's request or the `argument-hint` — if566 the user named a project, use that name directly without re-asking. Load567 the registry with override merge:568569 1. Read `.claude/synergy-registry.json` for the sibling's `remote` and any570 metadata.571 2. If `.claude/synergy-registry.local.json` exists, read it and merge it on572 top of the base registry. Match entries by the `name` key (the573 human-stable identifier across machines and BM entity paths); for each574 matched entry, fields present in `.local.json` win. A `.local.json`-only575 entry (no matching base `name`) is **added** as a private sibling when its576 `file` is `PRIVATE-SYNERGY-<name>.md`, and otherwise **ignored** (the base577 registry is the authoritative source of which *public* siblings exist).578 See `references/synergy-entry-format.md` "Private sibling entries".579580 If no project is identified from the argument, merged registry, or existing581 SYNERGY files, ask the user which sibling project to compare with.582 If no registry exists at all, also offer to create one via workflow 1 (Log a synergy entry) step 1b before proceeding with the comparison.5832. **Gather sibling context.** Resolve the sibling's local path: prefer the584 `local-path` field on the merged registry entry (relative paths are resolved585 from the current project root); if absent, fall back to `../<project-name>`586 relative to the current project root. If the resolved path is not587 accessible, ask the user for the path (and suggest they record it in588 `.claude/synergy-registry.local.json` to avoid re-prompting). Read the589 sibling's key files if accessible:590591 - `package.json` — dependencies, scripts, entry points592 - `CLAUDE.md` — conventions, architecture, workflow documentation593 - Skill files (`Glob` for `skills/**/SKILL.md`) — what skills exist, their594 workflows, trigger phrases595 - Hook definitions (`hooks/hooks.json`) — event handling patterns596 - Agent files (`Glob` for `agents/*.md`) — what agents exist597598 If neither local files, conversation context, nor Basic Memory provides599 substantive information about the sibling, stop and tell the user that a600 meaningful comparison requires access to the sibling repo or prior601 knowledge. Do not generate speculative entries.6023. **Diff patterns.** Compare against this project's equivalent files.603 Identify observations in each of the four categories:604 - Shared Patterns: conventions both projects use (same frontmatter fields,605 same BM integration approach, same commit style)606 - Divergences: structural or stylistic differences (different hook handling,607 different reference doc organization, different BM section ownership)608 - Extraction Candidates: logic in this project that would apply to the609 sibling (validation scripts, shared reference formats, utility functions)610 - They Have / We Don't: features or patterns in the sibling absent here611 (agents, skills, hooks, conventions this project lacks)6124. **Propose new entries.** Present each observation as a candidate entry with613 draft text matching the format in `references/synergy-entry-format.md`. For614 each, ask: "Log this as a \[category] entry for \[sibling]?" The user615 approves, edits, or skips each candidate. **No mutations without approval.**6165. Log confirmed entries by classifying, reading the file, composing, and617 adding per workflow 1 (Log) steps 4–7. Skip step 8 (eager promotion) for batch618 entries to avoid prompt fatigue. Offer a single summary at the end:619 "N entries logged. Run workflow 2 (Review) to review the full picture."620621 If the user skips all candidates, report that no entries were logged and622 suggest whether a follow-up comparison with different focus areas would be623 useful.624625### 5. Promote to Basic Memory626627Promote generalizable cross-project synergy entries from project-local628`SYNERGY-*.md` files into sibling project entity notes in Basic Memory. This629creates or extends a `## Cross-Project Synergy` section in the target sibling630note (typically at `engineering/agents/vp-plugins-<this-project>-and-<sibling>`).631Use only MCP tools from this skill's `allowed-tools` —632`mcp__basic-memory__search_notes`, `mcp__basic-memory__read_note`,633`mcp__basic-memory__edit_note`. If Basic Memory MCP tools are not available,634report that promotion is unavailable and suggest checking Basic Memory manually.635636**Steps:**6376381. **Scan for candidates.** Glob all `SYNERGY-*.md` files and read them. (This639 glob structurally excludes every `PRIVATE-SYNERGY-*.md` — both private640 *overlays* of public siblings and the sole content file of a *private641 sibling* registered via `.local.json`. Neither is ever promoted; their names642 must never reach Basic Memory. See `### Private overlay` and643 `references/synergy-entry-format.md` "Private sibling entries".) Filter644 eligible entries by section + structured fields:645 - Extraction Candidates with `Readiness: ready` (always)646 - Shared Patterns with `Status: aligned` (always)647 - Shared Patterns with `Status: drifting` (flag the drift in the draft)648 - Extraction Candidates with `Readiness: needs-cleanup` or649 `proof-of-concept` (lower priority — surface but mark as such)650 - Divergences with `Convergence path: adopt-theirs` or `propose-shared`651 (skip `accept-difference` — by definition not promotion-worthy)652 - They Have / We Don't with `Priority: adopt-soon` (skip `deferred`)653 - **Skip any entry already annotated with `_(Promoted YYYY-MM-DD)_`** —654 that annotation is the dedup signal written in step 4 below.6552. **Present candidates to the user.** Per-entry, never auto-promote. For656 each candidate, show:657 - Sibling project name and target BM note path658 - Section (Shared Pattern / Divergence / Extraction Candidate / They659 Have / We Don't) and entry title660 - A draft generalized version. Apply the transforms documented in661 `references/synergy-bm-format.md`: strip dates from titles,662 project-specific file paths, sprint numbers, and bd issue IDs;663 rewrite the prose from a neutral symmetric POV (so any sibling can664 read the entry as authoritative); keep `Status:`, `Convergence path:`,665 `Readiness:`, `Priority:`, and `Effort:` fields verbatim because they666 carry cross-project meaning.667 - Whether a Basic Memory note already exists for this sibling.668 Let the user approve, edit, or skip each candidate.6693. **Route by target.** For each approved candidate, look up the sibling's670 `bm-entity` value from `.claude/synergy-registry.json` (with671 `.claude/synergy-registry.local.json` merged on top by the `name` key).672 If `bm-entity` is present, use it as the BM note path. If absent, call673 `mcp__basic-memory__search_notes` with the sibling project name and674 surface the candidate matches to the user. **Legacy `bm-entity` form675 warning:** if the registered `bm-entity` does NOT start with676 `engineering/agents/vp-plugins-` (the canonical convention from v0.12.1677 onward), warn the user before proceeding: "Registered bm-entity678 `<value>` does not match the canonical679 `engineering/agents/vp-plugins-<this-project>-and-<sibling>` form. This680 may be a pre-v0.12.1 registry pointing at a single-project entity note681 (e.g. `npm/<sibling>`) — workflow 5 (Promote to Basic Memory) will682 write to that legacy location, which may scatter cross-project content.683 Recommended: update the registry to the canonical form and migrate any684 existing `## Cross-Project Synergy` content to685 `engineering/agents/vp-plugins-<this-project>-and-<sibling>` first." Ask686 the user whether to proceed anyway, abort, or migrate. **Stale687 `bm-entity` fallback:**688 if `bm-entity` is present but step 4's `read_note` returns not-found689 (the registry path has been renamed or deleted), warn the user690 ("BM note not found at `<bm-entity>` — registry may be stale") and691 fall through to `mcp__basic-memory__search_notes` exactly as the692 absent-`bm-entity` row does. The full routing table — including the693 fallback search order (`engineering/agents/` for relationship notes,694 then `projects/` and `npm/` as last-resort fallbacks for unregistered695 siblings) — lives in `references/synergy-bm-format.md`.6964. **Write or flag.** Three branches per approved candidate:697 - **Note exists, has `## Cross-Project Synergy` with target subsection** —698 call `mcp__basic-memory__read_note` first to fetch exact content, then699 `mcp__basic-memory__edit_note` with `find_replace` anchored to the next700 `###` heading for uniqueness, `expected_replacements=1`. Deduplicate by701 entry title (case-insensitive, whitespace-trimmed) before appending — if702 the title already appears in the subsection, skip. If `find_replace`703 returns zero replacements despite `expected_replacements=1`, the note was704 edited between `read_note` and `edit_note` — do NOT annotate the local705 entry; defer this candidate (increment a deferred-count) and continue706 with the next candidate. The step 6 report includes deferred entries707 under "deferred (BM note changed mid-write): N entries — re-run708 workflow 5 (Promote to Basic Memory) once BM writes settle." Do NOT709 re-invoke workflow 5 (Promote to Basic Memory) automatically inside710 the same run; persistent contention would otherwise loop.711 - **Note exists, no `## Cross-Project Synergy` section** — call712 `mcp__basic-memory__edit_note` with `insert_before_section` on713 `Relations` to add the full section block (all five subsections per the714 template in `references/synergy-bm-format.md`).715 - **No note exists** — do NOT create a thin note. Flag for enrichment:716 "No Basic Memory note for `<sibling>`. Enrich it first (manual creation717 under `engineering/agents/`), then re-run workflow 5 (Promote to Basic718 Memory)."719 - **After successful write,** annotate the local SYNERGY entry with720 `_(Promoted YYYY-MM-DD)_` via the `Edit` tool. This is the dedup signal721 that step 1 consults on subsequent runs.722 - See `references/synergy-bm-format.md` for `edit_note` gotchas (never723 use `append` with `section`, always `read_note` first, anchor724 `find_replace` matches to the next `###` heading).7255. **Prune pass.** For entries already annotated `_(Resolved ...)_` in the726 local SYNERGY file, offer to move the corresponding BM entry to the727 `### Resolved` subsection of `## Cross-Project Synergy` in the sibling728 note. The user confirms each. Mirrors upstream-tracker workflow 6729 (Promote to Basic Memory) prune-pass behavior.7306. **Report.** Summarize: promoted count, pruned count, skipped count731 (already-promoted), and flagged-for-enrichment count. Suggest verifying732 the result with733 `build_context("memory://engineering/agents/vp-plugins-<this-project>-and-<sibling>")`.734735See `references/synergy-bm-format.md` for the target section structure,736generalization transform rules, and `edit_note` gotchas.737738**Division of labor:** This workflow owns the `## Cross-Project Synergy`739section of sibling project entity notes in Basic Memory. The740upstream-tracker skill's workflow 6 (Promote to Basic Memory) owns741`## Upstream Friction` in package/tool entity notes. The retrospective742skill's step 7 owns `engineering/*` notes (patterns, conventions, lessons).743These three sections never overlap — synergy entries are cross-project,744upstream friction is package-specific, learnings are domain-specific.745746### 4. Trend review (quarterly)747748Every 4th sprint, perform a cross-cutting analysis of all SYNERGY tracking749files. This cadence aligns with the every-4th-sprint trend review used by750`/retrospective` and `/upstream-tracker` (see CLAUDE.md and MEMORY.md). It751replaces the interim workaround of running workflow 2 (Review) manually at752trend-review boundaries.753754**Input signals:**7557561. Glob for all `SYNERGY-*.md` files and read them. (Trend review is a757 boundary-crossing path — step 5 cross-references Basic Memory and step 8758 recommends workflow 5 (Promote to Basic Memory) — so private overlays must be759 excluded; the `SYNERGY-*.md` glob does this structurally, since it cannot760 match `PRIVATE-SYNERGY-*.md`. Private entries are reviewed via workflow 2761 (Review)'s local-only view, never trend-prom762763…(truncated)