@cleocode/skills 2026.5.83 → 2026.5.86

package/skills/ct-contribution/SKILL.md

@@ -11,6 +11,10 @@ tier: 3
 core: false
 category: meta
 protocol: contribution
+loomStage: contribution
+adrRefs:
+  - ADR-015
+  - ADR-053
 dependencies: []
 sharedResources:
   - subagent-protocol-base
@@ -519,3 +523,79 @@ jq -s '[.[] | select(.epicId == "T2204")] | .[0]' .cleo/contributions/CONTRIBUTI
 | [contribution.schema.json](../../schemas/contribution.schema.json) | **Authoritative** for JSON Schema |
 | [CONTRIBUTION-PROTOCOL-GUIDE.md](../../docs/guides/CONTRIBUTION-PROTOCOL-GUIDE.md) | Usage guide with examples |
 | [CONSENSUS-FRAMEWORK-SPEC.md](../../docs/specs/CONSENSUS-FRAMEWORK-SPEC.md) | Consensus voting thresholds |
+
+---
+
+## LOOM Stage Binding (T9670)
+
+`ct-contribution` is bound to LOOM lifecycle stage **`contribution`** — the terminal node of the RCASD-IVTR+C pipeline. Use this skill to formalize an Epic's contribution back to canon after its work has converged.
+
+### Stage-Transition Contract
+
+The contribution stage is entered from one of two upstream stages depending on the Epic's `kind`:
+
+| Upstream stage | Epic kind | Entry condition |
+|---|---|---|
+| **`release`** | most epics (work, bug, experiment) | Release tag pushed; release manifest recorded |
+| **`testing`** | epics whose `kind` is `release` or that gate on IVTR | IVT loop converged; `ivtLoopConverged: true` recorded |
+| **`specification`** | spec-only epics (no code) | Specification accepted; HITL signoff recorded |
+
+```
+research → consensus → architecture_decision → specification → decomposition
+                                                                   ↓
+                                                            implementation
+                                                                   ↓
+                                                              validation
+                                                                   ↓
+                                                                testing  ← (some epics return here)
+                                                                   ↓
+                                                                release
+                                                                   ↓
+                                                            contribution  ← (this skill)
+```
+
+The transition is enforced by the playbook runtime defined in **ADR-053**. The runtime is a deterministic state machine; `contribution` is its terminal accepting state. Once entered, the Epic is closed in canon.
+
+### Acceptance-Gate Evidence
+
+The contribution stage's completion gate is satisfied by emitting **at least one** of the following ADR-051 evidence atoms, recorded via `cleo verify <epicId> --gate contribution --evidence "<atoms>"`:
+
+| Atom kind | Format | Meaning |
+|---|---|---|
+| `decision:` | `decision:D-<slug>` | A BRAIN decision id that records the contribution outcome. |
+| `files:` | `files:path/a.md,path/b.md` | A list of contribution-format JSON / markdown deliverables produced by `/contribution submit`. |
+| `note:` | `note:<freeform>` | Owner-attested closure rationale; preferred when the contribution is non-textual (e.g. a tag push referenced by SHA in the note). |
+
+Example:
+
+```bash
+cleo verify T9568 --gate contribution \
+  --evidence "decision:D-loom-coverage-001;files:.cleo/contributions/T9568-final.json"
+cleo complete T9568
+```
+
+The gate validator (ADR-051 §2.4) rejects an empty evidence string with `E_EVIDENCE_MISSING`. Stale evidence (modified files after `verify` but before `complete`) fails with `E_EVIDENCE_STALE`.
+
+### Open Follow-Up
+
+A future ADR dedicated to the contribution stage's lifecycle gates (covering automated rollup signals from `cleo saga rollup`, multi-Epic contribution aggregation, and the contribution → "saga close" promotion path) is on the roadmap. File via:
+
+```bash
+cleo add --kind work --type task --severity P2 \
+  --title "T-LOOM-GAP-ADR-CONTRIBUTION: dedicated ADR for contribution stage gates" \
+  --relates T9670 \
+  --acceptance "ADR drafted under .cleo/adrs/|Cross-referenced from ct-contribution SKILL.md|Validator gate updated"
+```
+
+Until that ADR lands, contribution gates derive from ADR-015 (multi-contributor architecture) and ADR-053 (playbook runtime) — both already referenced in this skill's `adrRefs`.
+
+---
+
+## See also / References
+
+This skill binds to the **contribution** LOOM lifecycle stage (the final stage of the RCASD-IVTR+C pipeline). Governing ADRs:
+
+- [ADR-015 — multi-contributor architecture](../../../../.cleo/adrs/ADR-015-multi-contributor-architecture.md) — defines the multi-contributor consensus mechanics that this stage formalizes for an Epic's downstream return path.
+- [ADR-053 — playbook runtime](../../../../.cleo/adrs/ADR-053-playbook-runtime.md) — defines the lifecycle state machine; contribution is its terminal node.
+
+LOOM coverage matrix: [docs/skills/loom-coverage-matrix.md](../../../../docs/skills/loom-coverage-matrix.md).

package/skills/ct-docs-lookup/SKILL.md

@@ -63,4 +63,119 @@ Incorporate the fetched documentation into your response:
 
 - **Be specific**: Pass the user's full question as the query for better results
 - **Version awareness**: When users mention versions ("Next.js 15", "React 19"), use version-specific library IDs if available from the resolution step
-- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks
+- **Prefer official sources**: When multiple matches exist, prefer official/primary packages over community forks
+
+## Why Context7 (not training data)
+
+The user's global rule is explicit: prefer Context7 over training data for any
+library, framework, SDK, API, CLI tool, or cloud service — even well-known ones
+like React, Next.js, Prisma, Express, Tailwind, Django, or Spring Boot. This
+includes API syntax, configuration, version migration, library-specific
+debugging, setup instructions, and CLI tool usage. Use even when you think
+you know the answer; training data may not reflect recent changes.
+
+## Three-Command Budget
+
+The user rules cap a docs lookup at three CLI invocations per question. The
+budget fits the standard workflow:
+
+1. `npx ctx7@latest library "<name>" "<question>"` — one call to resolve.
+2. `npx ctx7@latest docs <id> "<question>"` — one call to fetch.
+3. (Optional) `npx ctx7@latest docs <id> "<question>" --research` — one
+   retry with sandboxed agents pulling source + web search.
+
+Going over budget is a signal: the library name is wrong, the question
+is too broad, or Context7 doesn't cover this library. In any of those
+cases, refine before retrying — don't burn more calls.
+
+## When NOT to Use This Skill
+
+The user rules explicitly exclude these from docs-lookup:
+
+- **Refactoring** — re-shaping existing code; no library lookup needed.
+- **Scripts written from scratch** — general programming, not library API.
+- **Debugging business logic** — use codebase tools (Grep, GitNexus), not
+  external docs.
+- **Code review** — quality assessment, not library reference.
+- **General programming concepts** — pure CS questions; training data is fine.
+
+Use docs-lookup ONLY for: API syntax, configuration questions, version
+migration issues, library-specific debugging, setup instructions, and CLI
+tool usage.
+
+## Authentication and Quotas
+
+The `ctx7` CLI runs anonymously with a limited free quota. When quota
+exhausts:
+
+```text
+Error: Quota exceeded.
+  Run `npx ctx7@latest login` for higher limits.
+  Or set CONTEXT7_API_KEY env var with your key.
+```
+
+Surface the error to the user (or include in `needs_followup`). NEVER
+silently fall back to training data — that violates the skill's contract.
+
+## Sensitive Data
+
+Queries to Context7 are logged on the Context7 side. Never include:
+
+- API keys, tokens, passwords
+- Internal hostnames or URLs
+- Customer-identifying data
+- Source code excerpts from private repos
+
+Use generic phrasing. If the actual API call needs a specific value,
+describe it abstractly ("how do I authenticate with an API key" instead
+of "use API key sk_live_abc123 to...").
+
+## Multi-Library Composition
+
+A single question may touch multiple libraries — common in modern stacks
+(SvelteKit + Better-Auth + Drizzle, Next.js + Prisma + Tailwind, etc.).
+Resolve each library independently with the right version pin, then
+synthesize.
+
+The three-command budget applies per-library; a question spanning
+three libraries gets nine commands. Stay focused — fetch the specific
+integration point each time, not the entire library surface.
+
+## Citing Versions in Answers
+
+Every code example produced from a version-pinned fetch MUST cite the
+version. The reader copies the code and runs it; when their version
+differs, the citation is the first thing they check.
+
+```markdown
+Use `defineRelations` (Drizzle ORM v1.0.0-beta and later):
+
+```typescript
+import { defineRelations } from "drizzle-orm";
+// ...
+```
+```
+
+Without the version note, the reader who is on Drizzle 0.x will be
+confused when the import fails.
+
+## Common Failure Modes
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| "Library not found" | Wrong name format | Use official punctuation: "Next.js" not "nextjs" |
+| Stale answer | No version pin | Detect installed version from lockfile, pin |
+| Generic answer when specifics needed | Vague query | Pass full question text, not single words |
+| Quota exceeded | Anonymous over-use | `ctx7 login` or set `CONTEXT7_API_KEY` |
+| Hallucinated API | Skipped Context7 | Always run Step 1+2 before answering library questions |
+| Wrong fork picked | Took top result blindly | Read descriptions; prefer official org |
+
+---
+
+## See references/
+
+Progressive disclosure — load on demand only:
+
+- `references/ctx7-workflow.md` — two-step loop, query formatting, research mode, budget
+- `references/library-id-resolution.md` — signals for picking the right ID; disambiguation procedure
+- `references/version-specific-docs.md` — version pinning, migrations, deprecations, drift detection

package/skills/ct-docs-lookup/references/ctx7-workflow.md

@@ -0,0 +1,198 @@
+# ctx7 Workflow
+
+`ct-docs-lookup` is the CLEO-side wrapper around the `ctx7` CLI. The
+underlying contract is set in the user's global rules
+(`~/.claude/rules/context7.md`) and the project's `MCP_Context7.md`.
+This reference codifies the workflow with concrete examples and
+recovery procedures.
+
+## Why Context7
+
+The skill's purpose statement is direct: when the user asks about a
+library, framework, or needs code examples, fetch current documentation
+instead of relying on training data. Training data is stale — the
+project's user rules say so explicitly.
+
+This applies even when you think you know the answer. API surfaces of
+React, Next.js, Prisma, Tailwind, Drizzle, Svelte, Supabase, and friends
+move faster than any model's cutoff. Verify against current docs.
+
+## The Two-Step Loop
+
+The ctx7 CLI is shipped as `npx ctx7@latest`. The workflow is two calls.
+
+```bash
+# Step 1 — resolve the official library ID
+npx ctx7@latest library "<library-name>" "<user-question>"
+
+# Step 2 — fetch docs for the resolved ID
+npx ctx7@latest docs <libraryId> "<user-question>"
+```
+
+The output of Step 1 is a list of candidate library IDs in the form
+`/org/project`. Pick the best match (see `library-id-resolution.md` for
+the heuristics) and pass it to Step 2.
+
+## Step 1: Library Resolution
+
+Use the official library name with proper punctuation:
+
+| ❌ Wrong | ✅ Correct |
+|----------|------------|
+| `"nextjs"` | `"Next.js"` |
+| `"customerio"` | `"Customer.io"` |
+| `"threejs"` | `"Three.js"` |
+| `"reactdom"` | `"React DOM"` |
+| `"vuejs"` | `"Vue.js"` |
+| `"tailwindcss"` | `"Tailwind CSS"` |
+
+The library name matches what the project documents itself as. When
+unsure, search the project's GitHub README for the official name.
+
+Pass the user's full question as the second arg — specific queries
+return better matches than single words.
+
+```bash
+# GOOD
+npx ctx7@latest library "Drizzle ORM" "how do I define relations in v1"
+
+# BAD — too generic, ranks poorly
+npx ctx7@latest library "drizzle" "relations"
+```
+
+## Step 1 Output Interpretation
+
+The CLI returns candidates with several signals — pick by:
+
+1. **Exact name match.** "Next.js" should resolve to `/vercel/next.js`
+   over `/some-fork/next.js-clone`.
+2. **Source reputation.** Look for High or Medium source labels.
+3. **Code snippet count.** More snippets = better-indexed library.
+4. **Benchmark score.** Higher is better; reflects retrieval quality.
+
+If the top candidate doesn't match exactly what the user asked for —
+e.g., they said "Next.js 15" and the top candidate is generic — try
+again with refined terms or version-specific names.
+
+## Step 2: Docs Fetch
+
+Once you have the library ID:
+
+```bash
+npx ctx7@latest docs /vercel/next.js "how do I configure middleware to inject auth headers"
+```
+
+The output is documentation excerpts with citations. Use these directly
+in your answer — they are current, sourced, and citable.
+
+## Version-Specific Docs
+
+When the user names a version, use the version-specific form:
+
+```bash
+# General
+npx ctx7@latest docs /vercel/next.js "..."
+
+# Pinned to v14.3.0
+npx ctx7@latest docs /vercel/next.js/v14.3.0 "..."
+
+# Pinned to v15 (latest 15.x)
+npx ctx7@latest docs /vercel/next.js/v15 "..."
+```
+
+The Step 1 output enumerates available versions. Pick the version
+matching the project's actual installed version (check
+`package.json` / `Cargo.toml` / `requirements.txt`).
+
+## Research Mode (Fallback)
+
+If the default fetch doesn't satisfy the question, retry with
+`--research`:
+
+```bash
+npx ctx7@latest docs /vercel/next.js "..." --research
+```
+
+This launches sandboxed agents that git-pull the actual source repos
+plus live web search, then synthesizes a fresh answer. More costly
+(longer, more tokens), so use only when:
+
+- Default fetch returned a generic answer when specifics were needed.
+- The question references a recent change that may not be indexed yet.
+- The user explicitly asked for research-grade depth.
+
+## Auth and Quotas
+
+The `ctx7` CLI runs anonymously by default with limited quota. When
+quota is exhausted:
+
+```bash
+# Error message will be something like:
+# Error: Quota exceeded. Run `npx ctx7@latest login` or set CONTEXT7_API_KEY
+```
+
+Instruct the user (or surface in `needs_followup`) to either:
+- Run `npx ctx7@latest login` (one-time browser auth)
+- Set `CONTEXT7_API_KEY` env var with their key
+
+Do NOT silently fall back to training data — that violates the skill's
+contract. The whole point is current docs, not stale recall.
+
+## Budget Discipline
+
+The user rules cap the workflow at "no more than 3 commands per
+question". For most lookups this is plenty:
+- 1 call: library resolution
+- 1 call: docs fetch
+- 1 call (optional): retry with `--research` if needed
+
+Going over budget signals one of:
+- Wrong library name (refine and retry)
+- Question too broad (narrow the question first)
+- Genuine library mismatch (Context7 doesn't cover this library — use
+  web search via WebSearch/WebFetch as alternative)
+
+## Sensitive Data
+
+Never include API keys, passwords, credentials, or internal URLs in
+queries. The query is logged on the Context7 side.
+
+```bash
+# WRONG
+npx ctx7@latest docs /supabase/supabase "use API key sk_live_abc123 to..."
+
+# RIGHT
+npx ctx7@latest docs /supabase/supabase "how do I authenticate the client with an API key"
+```
+
+## End-to-End Example
+
+```bash
+# User asked: "How do I do streaming server actions in Next.js 15?"
+
+# Step 1 — resolve
+$ npx ctx7@latest library "Next.js" "How do I do streaming server actions in Next.js 15?"
+> /vercel/next.js/v15 (benchmark 0.87, snippets 1240, source: High)
+> /vercel/next.js     (benchmark 0.85, snippets 5230, source: High)
+> ...
+
+# Step 2 — fetch (use version-pinned ID)
+$ npx ctx7@latest docs /vercel/next.js/v15 "How do I do streaming server actions in Next.js 15?"
+> [docs excerpt with streaming example, citation]
+
+# Compose answer using the fetched docs, citing version
+```
+
+## When NOT to Use This Skill
+
+See `library-id-resolution.md` for the boundary with debugging tasks,
+and `version-specific-docs.md` for when the answer doesn't depend on
+a specific library. Quick summary:
+
+- ❌ Don't use for refactoring (no library lookup needed)
+- ❌ Don't use for scripts written from scratch
+- ❌ Don't use for debugging business logic (use codebase tools)
+- ❌ Don't use for code review
+- ❌ Don't use for general programming concepts
+- ✅ Use for API syntax, configuration, version migration, library-specific
+  debugging, setup instructions, CLI tool usage

package/skills/ct-docs-lookup/references/library-id-resolution.md

@@ -0,0 +1,217 @@
+# Library ID Resolution
+
+The Context7 library catalog uses `/org/project` IDs. Picking the right
+ID is the difference between fetching authoritative docs and fetching
+a community fork's stale README. This reference codifies the
+disambiguation heuristics with concrete examples.
+
+## ID Anatomy
+
+```
+/vercel/next.js
+└org─┘ └proj─┘
+
+/vercel/next.js/v14.3.0
+└org─┘ └proj─┘ └version┘
+```
+
+- The `org` is typically the GitHub org or the company name.
+- The `project` is the official package name.
+- The optional `version` is a tag or release branch.
+
+## Resolution Output Format
+
+A typical Step 1 (`ctx7 library`) output:
+
+```text
+Top matches for "Next.js" against query "configure middleware":
+
+1. /vercel/next.js
+   - Source: High
+   - Description: The React Framework for the Web.
+   - Code snippets: 5230
+   - Benchmark: 0.85
+
+2. /vercel/next.js/v15
+   - Source: High
+   - Description: Next.js v15 release line.
+   - Code snippets: 1240
+   - Benchmark: 0.87
+
+3. /community/next-with-foo
+   - Source: Medium
+   - Description: Next.js + Foo starter template.
+   - Code snippets: 87
+   - Benchmark: 0.42
+
+4. /old-org/nextjs-legacy
+   - Source: Low
+   - Description: Pre-app-router Next.js patterns.
+   - Code snippets: 412
+   - Benchmark: 0.39
+```
+
+Five signals to weigh.
+
+## Signal 1: Exact Name Match
+
+The user said "Next.js". Candidates 1 and 2 are exact matches; 3 is
+"next-with-foo" (a derivative); 4 is "nextjs-legacy" (suffixed).
+
+Prefer the canonical name. The derivative or suffixed projects are
+appropriate ONLY when the user explicitly named them.
+
+## Signal 2: Source Reputation
+
+`High` > `Medium` > `Low`. Source reputation reflects how authoritative
+Context7 considers the project. Official org-owned repos are High.
+Community forks are typically Medium. Abandoned or low-quality projects
+are Low.
+
+When multiple High candidates exist, look further. When the only
+High candidate is the obvious one, pick it.
+
+## Signal 3: Code Snippet Count
+
+More snippets = better-indexed library = higher chance of finding the
+exact API the user asked about. The unversioned ID usually has higher
+snippet counts than version-pinned IDs because it aggregates across
+versions.
+
+For general questions, prefer unversioned IDs. For version-specific
+questions, accept the lower snippet count of the pinned ID.
+
+## Signal 4: Benchmark Score
+
+The benchmark is a retrieval-quality measure produced by Context7 —
+higher means the candidate library has good documentation that
+indexes well. Use as a tiebreaker only.
+
+In the example above, candidate 2 has a slightly higher benchmark
+(0.87) than candidate 1 (0.85) because v15-specific queries score
+better against the pinned slice. For a v15-specific question, prefer
+candidate 2.
+
+## Signal 5: Query Alignment
+
+The user's query in Step 1 affects ranking. If the query mentioned
+"middleware", candidates whose docs cover middleware will rank higher.
+This is why passing the FULL user question (not a single word) yields
+better resolution.
+
+## Common Pitfalls
+
+### Pitfall: Picking the version-pinned ID for a general question
+
+The user asked "What does Next.js do?" — a general question.
+
+- ❌ Pick `/vercel/next.js/v15` — too narrow; misses cross-version context.
+- ✅ Pick `/vercel/next.js` — covers the whole project.
+
+### Pitfall: Picking the unversioned ID for a version-specific question
+
+The user asked "How do I migrate from Next.js 14 to 15?"
+
+- ❌ Pick `/vercel/next.js` — might return mixed-version docs.
+- ✅ Pick `/vercel/next.js/v15` — gets the migration guide for 15.
+- ✅ Better: pick `/vercel/next.js/v15` for "to" and `/vercel/next.js/v14`
+  for "from", and run two fetches.
+
+### Pitfall: Picking the community fork when the user wants the official
+
+The user asked "How do I use Tailwind utilities?"
+
+- ❌ Pick `/some-community/tailwind-with-extras` — not what they meant.
+- ✅ Pick `/tailwindlabs/tailwindcss` — the official.
+
+Community forks rank LOW on the "what user meant" axis even when they
+rank high on other signals. Default to the official.
+
+### Pitfall: Picking the highest snippet count regardless of relevance
+
+The user asked about Vue 3 composition API.
+
+- ❌ Pick `/vuejs/vue` (high snippet count, but it's the Vue 2 line).
+- ✅ Pick `/vuejs/core` or `/vuejs/vue-next` (Vue 3).
+
+Always read the description, not just the count. Old projects accumulate
+snippets because they've been around longer — they may no longer be
+current.
+
+## Disambiguation Procedure
+
+When two candidates look equally good:
+
+1. **Read the descriptions.** They usually disambiguate.
+2. **Check the org.** Official org = the project's home; community
+   org = derivative.
+3. **Check the project's GitHub URL** if Context7 includes it. The URL
+   matches what the project's README cites.
+4. **Try both.** Compare the outputs of Step 2 for each candidate. The
+   one that better answers the question is the right one.
+
+## When Resolution Fails
+
+Sometimes Step 1 returns no good match. The library may not be in
+Context7's catalog, or the name was wrong. Recovery:
+
+```bash
+# Retry with the formal name from the project's GitHub
+npx ctx7@latest library "TanStack Query" "..."   # not "react-query"
+
+# Retry with the alternative spelling
+npx ctx7@latest library "GitHub Actions" "..."   # not "gh-actions"
+
+# Retry with a more specific query
+npx ctx7@latest library "Next.js" "App Router middleware in v15"
+
+# If all retries fail, fall back to WebSearch / WebFetch
+# (but tell the user the library isn't in Context7's catalog)
+```
+
+## Version Resolution Specifics
+
+When a project has many versions, Step 1's output lists them. Pick by:
+
+1. **Match the project's installed version.** Check `package.json`,
+   `Cargo.toml`, `requirements.txt`, etc.
+2. **If the user named a version, use that.**
+3. **If neither, use the latest stable (highest version number that
+   isn't pre-release).**
+
+```bash
+# Project installed Next.js 14.3.x
+$ jq '.dependencies.next' package.json
+"14.3.0"
+
+# Use the pinned version
+npx ctx7@latest docs /vercel/next.js/v14.3.0 "..."
+```
+
+This catches the case where the user asks about behavior that differs
+between versions; using the wrong version pin gives a confidently
+wrong answer.
+
+## Caching
+
+Library IDs rarely change. If you resolved `/vercel/next.js/v15` for
+one query, you can re-use it for the next query about the same library
+without running Step 1 again. Just remember to refresh the resolution
+when:
+
+- Asking about a different major version.
+- The project's installed version changed.
+- The previous fetch didn't satisfy the question (maybe the wrong ID
+  was picked).
+
+## When NOT to Use Library Lookup
+
+The user rules are explicit: not for refactoring, scripts-from-scratch,
+business-logic debugging, code review, or general programming concepts.
+
+If the question is "how do I structure my repository?" — that is a
+general programming question. Use general knowledge plus codebase
+inspection, not Context7.
+
+If the question is "how does Next.js's app router handle parallel
+routes?" — that is a library API question. Use Context7.