From arrow-maintenance
Maintains navigation and audit overlays for linked-intent development in docs/arrows/: orients via index.yaml, audits spec-to-code coherence, detects orphans/drift, supports renaming/splitting/merging segments. Activates ambiently or via /arrow-maintenance.
npx claudepluginhub jszmajda/lid --plugin arrow-maintenanceThis skill uses the workspace's default tool permissions.
The arrow-maintenance overlay scales linked-intent-dev for projects too large to hold in one context window. It provides a navigation index, systematic audit, and brownfield bootstrap.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Checks Next.js compilation errors using a running Turbopack dev server after code edits. Fixes actionable issues before reporting complete. Replaces `next build`.
Share bugs, ideas, or general feedback.
The arrow-maintenance overlay scales linked-intent-dev for projects too large to hold in one context window. It provides a navigation index, systematic audit, and brownfield bootstrap.
This skill operates in two modes. Detect which mode applies before acting.
Ambient mode. Auto-triggered on arrow-adjacent prompts when docs/arrows/ exists. Posture is catch and recommend — notice relevant work, surface findings, edit only as the surrounding conversation authorizes. File writes happen opportunistically (e.g., updating an arrow doc's coverage table alongside a linked-intent-dev edit on the same segment). Do not initiate a systematic audit-and-update pass in ambient mode.
Command mode. Invoked explicitly as /arrow-maintenance. Posture is directed action — the user has asked for the pass. Run an audit-and-update pass, apply unambiguous fixes in place, and surface the rest for user decision. Does not pause at synthetic phase boundaries — it is a single directed pass.
/arrow-maintenance is invokedInspect the project and dispatch on state:
docs/arrows/ exists) → run the audit-and-update pass (below).docs/arrows/ → generate the overlay from existing LID docs: populate index.yaml with one arrows: entry per existing LLD, status MAPPED, sampled: {today}, audited_sha: null; create one per-segment arrow doc per LLD referencing the existing LLD and any known tests/code. Do not generate new HLD, LLD, or EARS skeletons (those exist)./arrow-maintenance on a project that isn't ready for it. Don't just print a redirect — describe what you found and offer to dispatch: "I see no LID installation here. You probably want /lid-setup if this is a greenfield project, or /map-codebase if you're bringing LID to an existing codebase. Shall I run one of those instead, or did you mean something else?" Then proceed based on the user's answer.Every /arrow-maintenance run, in order:
Repair broken overlay state. Malformed index.yaml, missing per-segment docs referenced by the index, stale schema versions — these are this skill's domain, so fix them first.
Run the five audit checks (see references/audit-checklist.md):
audited and audited_sha against current state to find segments whose files changed since last audit.audited_sha, specs changed without test updates, tests passing but missing @spec annotations, @spec annotations pointing to missing spec IDs (reverse orphans).When a project-local coherence script is declared under ## LID Tooling in CLAUDE.md (as Coherence check: {path}), invoke that script and treat its output as authoritative for the deterministic checks it performs. Languages and paths vary by project — trust the declaration. If the declaration is missing or the declared path does not exist, perform the checks in-prompt. A reference Node implementation is bundled at references/coherence-check.mjs that users may copy to their project and declare in CLAUDE.md.
Apply unambiguous fixes in place:
## Spec Coverage tables in affected arrow docs from source scans.## References sections from source scans (grep for @spec, check file paths exist).status / next / drift fields in index.yaml where the new state is clear.unmapped.docs: assign entries to segments where the assignment is unambiguous; flag the rest for user assignment.audited: {today} and audited_sha: {current git HEAD} on each audited segment.Surface everything else for user decision:
unmapped.docs entries.Produce a structured report at the end: list findings, distinguishing those that were automatically resolved from those requiring user decision. Include location (segment, file, line) for each.
When audited_sha is populated and git history is available, run the audit in incremental mode — inspect only segments whose files changed since audited_sha. This is a large performance win on big projects. When audited_sha is null (never audited) or git history is unavailable, audit every segment.
When the skill is consulted ambiently (not via /arrow-maintenance), bias the agent's work on arrow-adjacent tasks:
index.yaml. Load it first, before any per-segment doc. Query for unblocked segments (where blockedBy is empty and status is not OK or OBSOLETE).## References into LLDs, spec files, tests, or code as needed.linked-intent-dev drive the fix.linked-intent-dev is editing a segment, update that segment's arrow doc and index.yaml entry in the same cascade — this is opportunistic, not initiated by you.When information appears in multiple places, this is the authority rule:
status, sampled, audited, audited_sha, next, drift, blocks, blockedBy, merged_into) live authoritatively in index.yaml.index.yaml schema is defined in references/index-schema.md (and in docs/llds/arrow-maintenance.md).docs/llds/linked-intent-dev.md — this skill reads from that schema.@spec placement rule (entry point of behavior's implementation graph) is defined in the linked-intent-dev skill.Each segment has one markdown file in docs/arrows/{segment-name}.md. See references/arrow-doc-template.md for the template. The arrow doc is an orientation page, not a design doc — pointers + coverage table, no duplicated design content.
| Status | Meaning |
|---|---|
| UNMAPPED | Not yet explored |
| MAPPED | Structure known, specs not verified against code |
| AUDITED | Specs verified — implementation status understood |
| OK | Fully coherent — all specs implemented |
| PARTIAL | Some specs missing or partial |
| BROKEN | Code and docs have diverged significantly |
| STALE | Docs exist but outdated |
| OBSOLETE | Superseded, kept for historical reference |
| MERGED | Combined into another arrow (use merged_into field) |
Normal progression: UNMAPPED → MAPPED → AUDITED → OK.
Segments evolve. Four first-class events:
index.yaml. If detected mid-change, ask whether to split now or defer — deferring is preferred. Split at clean breaks, not mid-edit.MERGED with merged_into: {primary-name}. Tombstone or delete the secondary's arrow doc.auth → identity). Walk all cross-references atomically in the same session: arrow-doc filename, index.yaml entry key, blocks, blockedBy, merged_into, taxonomy membership, and every other arrow doc's References section. Rename is not rename-and-hope; update every reference in one pass.UNMAPPED → MAPPED → AUDITED → OK with detours as needed. Timestamps (sampled, audited, audited_sha) record when each transition happened.| Concern | Owner |
|---|---|
| Per-change HLD/LLD/EARS/test/code work | linked-intent-dev |
| Cascade at change time | linked-intent-dev |
Arrow doc + index.yaml updates during a change | linked-intent-dev (has segment in context) |
unmapped.docs cleanup | arrow-maintenance during audit; linked-intent-dev when it notices an unmapped doc it can assign in passing |
| Systematic audit across segments | arrow-maintenance |
| Drift detection between sessions | arrow-maintenance |
| Brownfield mapping | arrow-maintenance (/map-codebase) |
| Overlay bootstrap on existing LID projects | arrow-maintenance (/arrow-maintenance command mode) |
| Lifecycle events (split, merge, rename, status) | Either skill; arrow-maintenance has richer guidance for multi-segment events and renames |
The skill does not prescribe "run audit every N commits" or "run weekly." Surface staleness signals when consulted; let the user choose the rhythm.
references/index-schema.md — full index.yaml schema.references/arrow-doc-template.md — per-segment arrow doc template.references/audit-checklist.md — the five audit checks in actionable form.references/coherence-check.mjs — reference Node implementation of deterministic checks. Optional; any equivalent in any language works.references/README-template.md — template for the docs/arrows/README.md that projects install alongside their overlay.