@lab43/q 0.4.0 → 0.6.0

package/skills/install/SKILL.md

@@ -1,150 +0,0 @@
----
-name: install
-description: Install q into a project, or add an extension to one. Invoke bare to set q up; name an extension to install it. Idempotent, safe to re-run on a partially set-up project. The changes ship as a PR.
----
-
-# Install
-
-The scaffold is deliberately near-empty — this skill creates the structure the other skills expect, not content.
-
-Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`. The invocation picks the path: a bare run bootstraps q (Steps 3–4); an extension run adds the extension install (Step 5) after them. A run naming `q` or `@lab43/q` is a bare run, because q is the framework rather than an extension (source: q conventions/extensions.md, Identity). Scaffolding brings q's surfaces to the forms in Step 3: create what is absent, correct what has drifted. Any run therefore completes a partially set-up project. Never rewrite what the user owns — each item below marks its own boundary.
-
-## Step 1: Survey current state
-
-Hold the project against each of Step 3's scaffold items, noting what is absent and what has drifted from its form. Alongside, check:
-
-- Convention-like docs living elsewhere (a `docs/` scan for rule-carrying files, a briefing bloated with per-task rules) — candidates for migration
-- Whether an earlier run's scaffold sits uncommitted in the working tree
-- On an extension run: whether the named extension is already pinned, installed, indexed, and watermarked
-- The GitHub CLI: `gh auth status`, and that the repo's `origin` is GitHub-hosted (`gh repo view` succeeds). q's workflow skills require both. If either fails, tell the user the fix (install via https://cli.github.com and authenticate with `gh auth login`; `gh repo view` failing with an authenticated CLI means `origin` is not GitHub-hosted) and continue — the scaffold still lands.
-
-## Step 2: Settle delivery
-
-Skip this step in any of these cases:
-
-- A bare run where Step 1 found nothing missing or drifted beyond an unpopulated `node_modules/`, no migration candidates, and no scaffold sitting uncommitted from an earlier run — there is nothing to change or deliver. Enforce the pins per `${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.md` (machine state, not a repo change), then stop with the closing report (Step 8).
-- An extension run where the named extension is already pinned, installed, indexed, and watermarked, Step 1 found nothing missing from the q scaffold, and no install sits uncommitted from an earlier run — report that and stop.
-- Step 1's GitHub CLI check failed — there is no delivery to settle.
-- Another skill's run invoked this one — the changes join that run's change.
-
-Otherwise, ask which review mode — local or ship — the run delivers under (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes). Then pick the delivery branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch); on an extension run the connected-work case is the extension arriving with the dependency that ships it.
-
-## Step 3: Scaffold
-
-The invocation is the agreement — scaffold autonomously; on a fully set-up, undrifted project the whole step is a no-op:
-
-1. **The two mirror docs** — create each if missing, with exactly this content; if present, leave it untouched. A seeded doc is the user's from creation, intro and entries alike — never corrected on a re-run. `docs/conventions/principles.md`:
-
-   ```markdown
-   # Principles
-
-   This project's cross-cutting rules, including any deviations from q's (see: q conventions/principles.md).
-   ```
-
-   `docs/conventions/documentation.md`:
-
-   ```markdown
-   # Documentation
-
-   This project's documentation rulings and deviations (see: q conventions/documentation.md, Three tiers of conventions).
-   ```
-
-   No other conventions doc is scaffolded — `/q:update-docs` creates each topical doc when its first entry is recorded.
-2. **The q dependency** — q installs as one pinned npm package, carrying its conventions and its plugin together:
-   - Ensure a root `package.json` — create `{"private": true}` if the project has none.
-   - If `@lab43/q` is not yet in `devDependencies`: `npm install --save-dev --save-exact --ignore-scripts @lab43/q` (via the project's package manager when it isn't npm). If it is, leave the recorded pin alone.
-
-   That pin is the only place a q version appears. Moving it and installing is the whole of an update.
-3. **Agent briefing** — ensure the project's briefing carries the section the briefing template defines, adding what is missing and correcting drift, per that file's rules (see: `${CLAUDE_PLUGIN_ROOT}/references/agent-briefing.md`).
-4. **Plugin declaration** — the project publishes its own marketplace, sourcing the q it already has in `node_modules`. Two files hold it, created if missing.
-
-   `.claude-plugin/marketplace.json` at the project root is the conventional path for a project publishing a marketplace, so the file is shared territory rather than q's. Merge the `q` entry into an existing manifest: leave every other `plugins` entry and the recorded name untouched. Write the whole file only when creating it.
-
-   The marketplace needs a name no other project on the machine will use. The registry the CLI resolves against holds one entry per marketplace name, machine-wide (source: ${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.md). Two projects sharing a name means the second one loads a q version it never pinned.
-
-   Name it `q-pin-<owner>-<repo>-<suffix>` — for example, `q-pin-acme-storefront-4f2ab9`. Owner and repo keep the name legible in that registry. The suffix is six random hex characters. It is what keeps the name unique. Read owner and repo from the repo's GitHub origin with `gh repo view --json nameWithOwner`. Use the project directory's name in their place when that command yields nothing. Lowercase the whole name and replace every character outside `a-z0-9-` with a hyphen.
-
-   Generate that name only when creating the file. A project that already records one keeps it, whatever it is. Other clones have already registered that name locally. Regenerating it strands them. Keeping a name the project chose gives up guaranteed uniqueness, which is the better trade against renaming a marketplace the project owns.
-
-   ```json
-   {
-     "name": "<marketplace>",
-     "owner": { "name": "this project" },
-     "metadata": { "description": "Pins this project's q version. The name must stay unique to this project. Sharing another project's name makes this one resolve to that project's pinned q." },
-     "plugins": [
-       {
-         "name": "q",
-         "source": "./node_modules/@lab43/q",
-         "description": "The q workflow plugin, pinned for this project."
-       }
-     ]
-   }
-   ```
-
-   Then merge into `.claude/settings.json`, leaving other keys untouched. Key both entries to whatever name the manifest records, and correct either if it has drifted from it:
-
-   ```json
-   {
-     "extraKnownMarketplaces": {
-       "<marketplace>": { "source": { "source": "directory", "path": "./" } }
-     },
-     "enabledPlugins": { "q@<marketplace>": true, "q@q": false }
-   }
-   ```
-
-   Write the path by hand, relative to the project root — `claude plugin marketplace add` records an absolute path, which breaks every other checkout of the repo.
-
-   `"q@q": false` retires the bootstrap marketplace the package ships. Its name is the same in every copy of q, so leaving it enabled means loading whichever copy registered that name last. Disabling it is what makes the project's own pin authoritative.
-5. **Enforce the declarations** — make this machine match the pins just declared, per `${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.md`.
-6. **State file** — write `.claude/q-state.json` per `${CLAUDE_PLUGIN_ROOT}/references/q-state.md`: a `reconciledAgainst` entry for `@lab43/q`, from the version in `node_modules/@lab43/q/package.json`. Write only absent watermarks — a present entry, stale or not, is reconciliation's to move (source: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md).
-7. **Ignore rules** — ensure `.gitignore` covers `node_modules/`, `.claude/settings.local.json`, and `.claude/worktrees/`, and that the committed scaffold files are not ignored: run `git check-ignore` on `.claude/settings.json`, `.claude-plugin/`, and `.claude/q-state.json`, fixing the rules until it reports nothing. A bare negation under an ignored `.claude/` does nothing — the directory rule itself must become `.claude/*` plus the negations. Leave every unrelated ignore rule alone.
-8. **README setup instructions** — ensure the README tells a collaborator using Claude Code how to bring up a fresh clone: install the project's dependencies, which is what delivers q. Fold that into the project's existing setup instructions or setup script — a dependency install the project already documents (`npm install`, a pnpm or yarn equivalent, a bootstrap script) covers it, and a README already carrying the information needs nothing. Present the q steps as applying to collaborators who use Claude Code, never as requirements for working in the repo. Create a minimal README with just these instructions when the project has none.
-9. Scaffold nothing else. An empty taxonomy directory arrives when its first document does.
-
-## Step 4: Migration proposals (existing projects only)
-
-On an extension run, skip this step unless Step 3 just bootstrapped a previously q-less project. If Step 1 found convention-like content outside `docs/conventions/` — rules in the briefing that apply only to particular kinds of work, rule-carrying docs elsewhere in `docs/` — read `node_modules/@lab43/q/conventions/documentation.md` and propose moving the content per its taxonomy, via AskUserQuestion — a conversational stretch. Apply approved moves, leaving a one-line pointer behind where the policy calls for one.
-
-## Step 5: Install the extension (extension runs only)
-
-The named extension is the agreement — install it autonomously. If it is not yet in `devDependencies` (via the project's package manager when it isn't npm):
-
-```
-npm install --save-dev --save-exact --ignore-scripts <extension>
-```
-
-If it is, leave the recorded pin alone and make this machine match through `${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.md`.
-
-Verify what arrived is an extension: `node_modules/<extension>/package.json` carries the `q-extension` keyword, and the package root holds a `conventions/` directory, a `.claude-plugin/` directory, or both (source: q conventions/extensions.md). If not, `npm uninstall` it and report — never index it. When the run changed nothing else, switch back to the prior branch and delete any branch this run created; when Step 3 bootstrapped the project, keep that scaffold, carry on to Step 6, and report the extension failure in the close.
-
-An extension shipping `conventions/` gets one briefing index line per doc the index doesn't already carry, under its extensions group and contiguous with any lines it already has: package name plus path from the package root (see: q conventions/documentation.md, Package doc paths), blurb restating the doc's intro (source: q conventions/documentation.md, Taxonomy). One shipping no `conventions/` is watermarked without being indexed, having no docs to index (source: q conventions/extensions.md, Layout).
-
-When the extension has no `reconciledAgainst` entry, write one from the version in `node_modules/<extension>/package.json` (see: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md) — an extension Step 1 found pinned and installed by hand included. Never overwrite a present entry, stale or not — it is reconciliation's to move (source: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md).
-
-Installing an extension's plugin is not yet part of this step: q scaffolds only its own marketplace entry.
-
-## Step 6: Adversarial review
-
-Invoked from another skill's run, stop here — the changes are that run's to validate and deliver. When the run changed nothing tracked — every proposal declined on an otherwise complete project — and no earlier run's scaffold awaits delivery: switch back to the prior branch, delete any branch this run created, and report that and stop. When Step 1's GitHub CLI check failed, stop here with the closing report (Step 8), adding:
-
-- That the changes stay uncommitted — restate the `gh` fix.
-- That a re-run delivers them once `gh` is in place.
-
-Otherwise: in ship mode, commit first. In both modes, validate the changes (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses.
-
-## Step 7: Open the PR
-
-1. **Local review's gate**: run the gate over the uncommitted changes (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The local gate).
-2. **Open the PR**: push the branch and open the PR per the PR-authoring rules (see: q conventions/pull-requests.md).
-
-## Step 8: Report
-
-Close the session by reporting:
-
-- What was created.
-- What already existed and was left untouched.
-- What was proposed, and the user's decisions.
-- On an extension run:
-  - The extension and version installed, and the index lines added.
-  - Any overrides markers its docs carry against q's rules. These are deviations the project now lives under. The project's own rulings still win on conflict.
-  - Its q declaration — its `@lab43/q` devDependency (source: q conventions/extensions.md) — held against the project's own pin. An extension written against a newer q than the project runs is the signal to suggest `/q:update`. One written against an older q, or carrying no declaration, is noted as-is — no update closes it.

package/skills/sync/SKILL.md

@@ -1,45 +0,0 @@
----
-name: sync
-description: Set up or repair this machine for a q-using project, handing off to /q:install, /q:update, or /q:uninstall-extension when the project's records don't match its pins. Use on a fresh clone or a new machine, or whenever the session-start check says the project's q setup did not validate. Never moves pins and never reconciles docs; the only tracked file it may touch is a lockfile a dependency install rewrites.
----
-
-# Sync
-
-Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`. The invocation is the agreement — proceed autonomously throughout. Sync delivers no repo change, so there is no branch, review mode, or PR.
-
-## Step 1: Enforce the pins
-
-Two states have nothing to sync yet. Propose `/q:install` and stop for either:
-
-- The project declares no `@lab43/q` devDependency. It has no pins to enforce.
-- It declares one but has no `.claude/q-state.json`. q's bytes arrived. The scaffold that records them has not run. This is the window between the bootstrap install and the first `/q:install`. It is the state the session-start check reports.
-
-Otherwise enforce the pins per `${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.md`.
-
-## Step 2: Check the GitHub CLI
-
-Run `gh auth status`, and `gh repo view` to confirm the repo's `origin` is GitHub-hosted — q's workflow skills require both. When either fails, report the fix: install via https://cli.github.com and authenticate with `gh auth login` for a missing or unauthenticated CLI; a failing `gh repo view` with an authenticated CLI means `origin` is not GitHub-hosted.
-
-## Step 3: Compare pins against watermarks
-
-Read `.claude/q-state.json` (see: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md) and compare:
-
-- the pin of `@lab43/q` and of each extension in `package.json` against its `reconciledAgainst` entry, in both directions — the extensions are the direct `devDependencies` whose own `package.json` carries the `q-extension` keyword (source: q conventions/extensions.md)
-
-Each finding routes to its remedy:
-
-- A pin differing from its watermark (moved out of band, unreconciled) → `/q:update`, invoked bare once — a bare run covers every such finding.
-- An entry for an extension no longer in `package.json` (removed out of band, the removal never reconciled) → `/q:uninstall-extension`, with the extension name, one run per extension.
-- No record where one belongs → `/q:install` — bare for a missing state file or a missing `@lab43/q` entry; with the extension name for any other pinned extension that has no entry, one run per extension. These were installed or scaffolded by hand, never recorded.
-
-Never write the state file — watermarks certify reconciliation, and sync never reconciles (source: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md).
-
-## Step 4: Report, then hand off
-
-Report:
-
-- What Step 1 enforced, and any tracked file it rewrote (a lockfile) left in the tree as the user's.
-- The GitHub CLI result, with the fix when it failed.
-- Each finding from Step 3 and the remedy it routes to.
-
-Then make Step 3's hand-offs — each invocation a full run of its own that asks and delivers for itself. Make the `/q:install` and `/q:uninstall-extension` runs before any `/q:update` run, so update starts from repaired records.

package/skills/uninstall-extension/SKILL.md

@@ -1,52 +0,0 @@
----
-name: uninstall-extension
-description: Remove a q extension from a project, or reconcile a removal already made out of band — a hand-run npm uninstall, a teammate's merge. Invoke with the extension name. Uninstalls the package, removes its briefing index lines, drops its watermark, and surfaces the project docs that reference it for the user's ruling. Refuses @lab43/q. The changes ship as a PR.
----
-
-# Uninstall Extension
-
-Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`. Given no extension, ask which one.
-
-## Step 1: Take stock
-
-Refuse `q` and `@lab43/q`. q is the framework rather than an extension (source: q conventions/extensions.md, Identity), and no q project can remove it (source: q conventions/documentation.md, Three tiers of conventions).
-
-Confirm the named target is an extension — any of the following identifies it:
-
-- the `q-extension` keyword in `node_modules/<extension>/package.json` (source: q conventions/extensions.md)
-- the same keyword read from the registry (`npm view <extension> keywords`), for one pinned but not installed
-- a `reconciledAgainst` entry (see: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md)
-
-A target none of these identify has nothing here to remove — report that and stop.
-
-## Step 2: Settle delivery
-
-Ask which review mode — local or ship — the run delivers under (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes). Then pick the delivery branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch).
-
-## Step 3: Remove the extension's records
-
-Remove without asking — each item a no-op when already absent:
-
-1. When the extension is pinned: `npm uninstall --ignore-scripts <extension>` (via the project's package manager when it isn't npm).
-2. When the pin is already gone: run the package manager's dependency install, catching up any lockfile and `node_modules` remnants the removal left.
-3. Remove the extension's lines from the agent briefing's docs index. An extension that shipped no `conventions/` has none to remove.
-4. Drop the extension's `reconciledAgainst` entry, per `${CLAUDE_PLUGIN_ROOT}/references/q-state.md`.
-
-## Step 4: Rule on references
-
-Grep the docs the documentation policy owns (see: q conventions/documentation.md, Taxonomy) for the extension's name. Every hit lost its backing with the extension: an overrides marker's target, a restatement's home, a cross-reference's destination. On a clean grep, skip the step.
-
-Recommend a resolution for each hit, grounded in the documentation policy, in one AskUserQuestion batch — a conversational stretch. The user rules. Apply the rulings.
-
-## Step 5: Adversarial review
-
-In ship mode, commit first. In both modes, validate the changes (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses.
-
-## Step 6: Open the PR
-
-1. **Local review's gate**: run the gate over the uncommitted changes (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The local gate).
-2. **Open the PR**: push the branch and open the PR per the PR-authoring rules (see: q conventions/pull-requests.md).
-3. Close the session by reporting:
-   - The extension removed, or the out-of-band removal reconciled.
-   - The index lines and watermark entry dropped, and any lockfile catch-up applied.
-   - Each reference surfaced and the user's ruling on it.

package/skills/update/SKILL.md

@@ -1,75 +0,0 @@
----
-name: update
-description: Update q and the project's installed extensions — move pins to the latest releases with the user's go-ahead, reconcile the project's docs with what each release changed, and catch up any pin that moved out of band. Invoked bare it covers q and every installed extension; a named target — q, or an extension — scopes the run. Use after a release ships, or whenever pins may be behind. To audit docs without updating, use groom-docs; to repair this machine without touching docs, use sync. A pin move or catch-up ships as a PR.
----
-
-# Update
-
-Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
-
-## Step 1: Take stock
-
-Bare invocation covers `@lab43/q` and every installed extension — the direct `devDependencies` whose own `package.json` carries the `q-extension` keyword (source: q conventions/extensions.md). A named target scopes the run: `q` means `@lab43/q`; any other name means that extension. Confirm any target you can't identify as an extension before treating it as one. Below, *package* covers both q and an extension.
-
-Read four versions for each package in scope — the watermarks per `${CLAUDE_PLUGIN_ROOT}/references/q-state.md`:
-
-| Pinned | Installed | Latest | Watermark |
-| --- | --- | --- | --- |
-| its pin in the project's `package.json`; in a repo authoring an extension, the q pin lives in that extension's own manifest (source: q conventions/extensions.md) | `version` in `node_modules/<package>/package.json` | `npm view <package> version` | its `reconciledAgainst` entry |
-
-Alongside the versions, hold each third-party extension's q declaration — its `@lab43/q` devDependency (source: q conventions/extensions.md) — against the project's own q pin, and flag a mismatch either way. A declaration ahead of the pin closes by updating q here; one behind closes only by that extension's release.
-
-A package with no pin and no watermark entry has nothing to update — propose `/q:install` for it and stop.
-
-Validate the records before sorting. Check that every pinned package in scope carries its watermark. Check that no watermark outlives its pin: every watermark on a bare run, the target's on a named run. On any failure, propose `/q:sync` and stop.
-
-Report the versions, then sort each package by its state:
-
-- **Pinned behind latest** → a pin move to offer. Diff the two published versions: `npm pack <package>@<version>` for each into a scratch directory, extract both, and diff the trees. Diff the whole tarball rather than `conventions/` alone, because a release can change skills, hooks, agents and references too. Step 4's reconciliation and the closing report both read from this diff. Summarize what changed and what reconciliation it demands. Pins are recorded decisions — only the user moves them.
-- **Pinned ≠ watermark** → a catch-up: the pin moved out of band. Reconciled in Step 4, without moving any pin.
-- **Installed ≠ pinned** → machine drift: enforce without asking, per `${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.md`. When a pin move is on offer, enforce only after the ask below, so enforcement lands on the pins the run keeps; otherwise enforce now.
-- **Everything agreeing, nothing newer** → in force and reconciled; report and stop.
-
-Then ask once, one batch: each offered pin move (take it or stay), and the review mode — local or ship — the delivery runs under (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes). A run with only catch-ups asks the review mode alone. A run finding only machine drift asks nothing — enforce, report, stop. The go-ahead makes the rest of the run autonomous: declined moves drop out, catch-ups stay in. When the answers leave nothing due, report and stop.
-
-## Step 2: Branch
-
-Pick the delivery branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch).
-
-## Step 3: Move the pins
-
-For each pin the user agreed to move:
-
-Run `npm install --save-dev --save-exact --ignore-scripts <package>@<latest>`, via the project's package manager when it isn't npm. Moving any pin is the same act, q's included.
-
-## Step 4: Reconcile what the diff touched
-
-Work only from the diffs. Each package's diff runs from its watermark to its pin as Step 3 left it. What the diff touched decides which of these applies. A diff may touch both:
-
-- **Changed `conventions/`** — hold the project's docs against each changed rule:
-  - remove an override whose target updated to agree or disappeared — it is spent (source: q conventions/documentation.md, Three tiers of conventions)
-  - re-check each "(source: …)" restatement against its changed home
-  - prune a project rule the new text now owns — it is duplication now
-  - ask about a project rule the new text contradicts, the one call the go-ahead didn't settle: keep it as a recorded deviation (add the overrides marker) or adopt the incoming rule. Adopting can leave code non-conforming — suggest `/q:review` on the affected area; code fixes are out of scope here
-
-  An extension authored in this repo is part of that surface: re-check its docs the same way. The q pin this run moved is also that extension's shipped written-against declaration, and the re-check is what makes the moved declaration true (source: q conventions/extensions.md).
-
-  Then sync the briefing's index lines for the package — a doc added or removed changes the list, a changed intro re-draws its blurb (see: q conventions/documentation.md, Taxonomy).
-- **A changed plugin** — re-run `/q:install`, scoped to join this run's change: it is idempotent, creating what the new version's scaffold expects and correcting what has drifted from it.
-
-After each package's reconciliation, write its watermark per `${CLAUDE_PLUGIN_ROOT}/references/q-state.md`: its `reconciledAgainst` entry to its pinned version.
-
-The go-ahead in Step 1 covered this reconciliation — apply it without re-asking.
-
-## Step 5: Adversarial review
-
-In ship mode, commit first. In both modes, validate the changes (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses.
-
-## Step 6: Open the PR
-
-1. **Local review's gate**: run the gate over the uncommitted changes (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The local gate).
-2. **Open the PR**: push the branch and open the PR per the PR-authoring rules (see: q conventions/pull-requests.md).
-3. Close the session by reporting:
-   - Old and new pins, and each catch-up applied without a pin move.
-   - What each release changed.
-   - Each reconciliation applied and any follow-up suggested — a third-party extension the moved q pin leaves behind included; a newer release of that extension is what closes the gap.