jszmajda/lid/update-lid

update-lid

Configure or reconcile a project for linked-intent development. Dispatches on project state — do not re-run unconditionally.

Invoked as /update-lid. The skill handles both initial bootstrap and ongoing reconciliation; the user's mental model differs ("set me up" vs. "update what we have") but the behavior dispatches on what's detected in the project, not on the user's framing.

Instruction-file anchor

LID's directives, the ## LID block, and the navigation table live in the project's agent-instructions file. Canonically that is `AGENTS.md` (the cross-tool convention Cursor and most agents read), with `CLAUDE.md` a symlink alias so Claude Code sees the same content. Never branch on which host you are running under.

• Read (detect directives, mode, version, drift): use AGENTS.md if it exists, otherwise CLAUDE.md. With the symlink the two are one file.
• Fresh bootstrap (write): create AGENTS.md and a CLAUDE.md symlink pointing at it (ln -s AGENTS.md CLAUDE.md). Where symlinks are unavailable (e.g. Windows without Developer Mode), instead write a CLAUDE.md whose only content is @AGENTS.md.
• Existing project (write): update the file that already exists, in place. A project that already uses CLAUDE.md keeps it — do not migrate it to AGENTS.md.

Below, the instruction file means the file chosen by these rules.

Detection signals

Use these exact detection rules — do not guess or use fuzzy matching.

• LID directives present: grep for the literal strings "linked-intent-dev" or "Linked-Intent Development" in the instruction file. Either match indicates LID directives are already installed.
• LID metadata block present: grep for a ## LID heading in the instruction file. The block carries two bullets:
• - Mode: {Full|Scoped} — the project's LID mode. Case-insensitive on the mode name; whitespace tolerated.
• - Version: {X.Y.Z} — the linked-intent-dev plugin version the project's docs conform to. A project with a ## LID block but no - Version: bullet is treated as predating versioned conventions (no `- Version:` bullet) (walk from the start).
• Project version vs. installed version: read - Version: from the ## LID block and compare its major.minor with the major.minor of the installed linked-intent-dev plugin version (the version field in plugins/linked-intent-dev/.claude-plugin/plugin.json; the three LID plugins share it, and it is the LID conventions version). When the project's major.minor is lower, the project lags and version-walk applies. A difference in the patch number alone is not lag: a patch release asks nothing of a project, so do not walk. When the project's version is newer than the installed one — patch included — a newer LID plugin has already worked on this project; stop and suggest the user update their LID plugins (see the dispatch table). If - Version: does not read as X.Y.Z, read what parses — drop a leading v, take a missing patch as 0 (v1.3 is 1.3.0) — and walk from that version; if nothing parses, treat the project as predating versioned conventions and walk from the start. Never write the installed version over a malformed one without walking: that would silently skip every migration in between.
• Arrow-maintenance overlay present: docs/arrows/ directory exists at the project root.
• Convention drift: any of the required directories missing (docs/intent/, docs/high-level-design.md); the instruction-file directive sections diverge from the current template, including a malformed `## LID` block (heading other than a bare ## LID, mode merged into the heading as ## LID Mode: Full, a missing - Mode: or - Version: bullet, a - Version: not written as X.Y.Z, or stray non-template bullets); a design doc whose prefix: frontmatter is an array (an unresolved multi-prefix marker — see Version-walk); or a node folder holding more than its `<node>-design.md` + optional `<node>-specs.md` pair (an un-promoted sub-LLD left as extra files). The last two are detected independently of version lag — a project already at the installed major.minor still has them re-surfaced by reconcile-conventions, and handled the same way (surfaced with a recommended resolution, never silently left or auto-resolved).

Re-check all detection signals on every invocation. Installing arrow-maintenance after initial setup, for example, should trigger an arrow-navigation-row update on the next /update-lid run.

State dispatch

Inspect the project and take exactly one of these actions:

Version-walk is evaluated before reconcile-conventions: a lagging project is brought to the current conventions version first, then ordinary drift reconciliation runs against those conventions.

Newcomer tour offer. On a project with no LID directives (the full-bootstrap and append-directives rows), check whether the memory your harness already placed in your context shows that this person has met LID before: a record of the LID tour, or other memories of them working with LID. If it doesn't, read the linked-intent-dev skill's references/tour-offer.md (beside this skill, at ../linked-intent-dev/references/tour-offer.md) and follow it. That puts a card at the top of your first message, the one that proposes the setup. Make no offer when a calling skill passed the mode, when the workflow's Phase 1 is applying this bootstrap branch inline (the workflow makes the offer), or on a project that already has LID directives.

Version-walk

A project records the linked-intent-dev version its docs conform to in the ## LID block's - Version: bullet. The canonical LID version is the version field in plugins/linked-intent-dev/.claude-plugin/plugin.json. When the project's major.minor is lower than the installed version's — or - Version: is absent, in which case the project is treated as predating versioned conventions (no `- Version:` bullet) and walked from the start — the skill walks the project forward to the installed version.

Walk the releases between the project's version and the installed version, in ascending order. The migration source is the CHANGELOG at plugins/linked-intent-dev/CHANGELOG.md (the root CHANGELOG.md symlinks to it). Each minor or major release entry has a `### Migration (v1.3 → v1.4)` section describing the doc-level steps to move a project forward by one release; patch entries ask nothing of a project and have none. Read each intervening release's Migration section and reconcile the project against it.

Apply the existing propose → confirm → apply discipline — the skill never silently rewrites:

• Mechanical steps — deterministic edits with one correct outcome (for example, backfill parent:/prefix: frontmatter on design docs, bump docs/arrows/index.yaml schema_version). Batch these and apply them together on a single confirmation.
• Judgment steps — steps that require a human decision (for example, formalizing an ad-hoc sub-HLD, reconciling overlapping segments). Surface each individually as its own proposed decision; do not auto-apply. Present the migration text, name the affected files, and let the user decide per step.

A migration entry that mixes both kinds is split: apply its mechanical part in the batch, surface its judgment part individually.

Never silently leave a transient migration marker. Some migrations deliberately leave a marker that flags a node as unresolved. The load-bearing one is a node folder carrying more than its `<node>-design.md` + `<node>-specs.md` pair — a former separate-spec LLD left as extra files instead of relocated into its own child folder. Relocating the LLDs into the node-as-folder tree is the defining, error-prone part of the move, so an overloaded folder is the marker most worth surfacing; a prefix: array on a design doc is a second, lower-risk marker (agents reconcile these reliably on a later pass). These are the steps most often dropped, because the marker is easy to write and easy to forget — leaving the walk looking done while the structural call it stands in for was never made. Treat each as a judgment step that must be surfaced before the walk reports complete: name the node in the project's own terms, recommend a resolution — promote the extra LLD into its own child folder, collapse a multi-prefix node into <LEAF>-<TYPE> facets, or split into sibling leaves — and apply it on approval. The user may defer any of them — honor that (user-is-always-right) — but the deferral is explicit, the marker stays in place as the record of it, and the completion report names every node left unresolved. The same surfacing-with-recommendation applies when reconcile-conventions detects these markers in a project already at the installed version. Surface, never silently leave; recommend, never silently auto-resolve.

Surface migration and reconciliation choices in the project's own terms — its LLDs, components, segments, and specs — not LID's internal structural vocabulary (HLD tenet: Speak the project's language).