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 it to the installed linked-intent-dev plugin version (the version field in plugins/linked-intent-dev/.claude-plugin/plugin.json, the canonical LID conventions version). When the project version is lower, the project lags and version-walk applies.
• 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, 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 version 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.

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 - Version: is lower than the installed version — or 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 release entry has a ### Migration (vX → vY) section describing the doc-level steps to move a project forward by one release; 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).

On a successful walk, refresh the project's - Version: bullet to the installed version. When a walk crosses several releases, refresh once at the end rather than stepping the bullet per release. The defining marker of a conventions version is its structural layout — for the 1.2 conventions, relocation onto the docs/intent/ node-as-folder tree — so a project that has taken those structural moves is on the new conventions and the bullet advances even when the user defers residual cleanup (a prefix array, a not-yet-promoted folder); do not pin it to the prior version. What an honest walk owes the user is not a withheld version bump but a clear account: the completion report names every deferred resolution and every persisting marker (unresolved prefix: arrays, overloaded node folders), and those markers stay in place so the fall-through to reconcile-conventions — and every later /update-lid run — re-surfaces them until resolved.

After version-walk completes, fall through to ordinary reconcile-conventions against the now-current conventions.