Skip to content

P3: ship canonical docs inside the skills plugin so citations stop being URLs #8

Description

@RonenMars

Follow-on to #6, and the eventual replacement for the URL-plus-link-check arrangement adopted today.

Component repos cite canonical documents in this repo as absolute GitHub URLs.
That works, and a link-check job now catches a rename instead of letting it rot silently — RonenMars/threadbase-streamer#663 and RonenMars/threadbase-mobile#799.

It still has two costs a URL cannot avoid.
An agent working without network cannot read the document it is being told to read.
And nothing pins a version, so a skill can cite a document that changed underneath it and neither side notices.

What would remove both

If the shared skills move into a threadbase-skills plugin hosted here — the work in #6 — then the skill file and the document it cites end up in the same repository.
The citation becomes a relative path inside the plugin, resolvable offline, versioned with the plugin, and the cross-repo mechanism disappears rather than being made more reliable.

integration-branch/SKILL.md and integration-branch-lifecycle.md are the concrete pair: they are already one piece of knowledge split across two repos by nothing more than where the files happen to live.

Why this is not urgent

The link-check closes the failure mode that actually loses information — a citation that 404s and nobody notices.
What remains is inconvenience for an offline agent and the absence of version pinning, neither of which silently corrupts anything.

Submodules were considered and rejected for this: git pull does not move a submodule checkout, machines without SSH keys fail submodule update, and threadbase-streamer deliberately runs CI with submodules: false, so the documents would be absent in CI or every job would get slower.

Depends on

#6 — there is nothing to ship docs inside until the plugin exists.

Done looks like

integration-branch/SKILL.md cites integration-branch-lifecycle.md by relative path, both resolve with no network, and the link-check job in each component repo is deleted along with the last URL it was guarding.

Verified state

Checked 2026-08-20.

  • docs/issue-tracker.md, docs/triage-labels.md and docs/integration-branch-lifecycle.md are canonical here as of docs: make the umbrella canonical for triage labels and integration-branch lifecycle #7.
  • Both component copies of the integration-branch skill cite the lifecycle document by absolute URL.
  • A link-check workflow resolving every https://github.com/RonenMars/threadbase/blob/main/ link is open in both component repos, verified against a real link, a fabricated 404 and an empty match set.

Component halves: RonenMars/threadbase-mobile#800 and RonenMars/threadbase-streamer#664.

Metadata

Metadata

Assignees

No one assigned

    Labels

    P3Deferred. Real, but nobody is waiting.ciCI, workflows, release automation, build harness.enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions