XRefKit

XRefKit is a framework for making AI-assisted work repeatable, reviewable, and handoff-ready.

It helps teams structure domain procedures and knowledge so that work can record evidence, preserve human judgment, and apply explicit completion checks.

Why XRefKit?

Experimental local tool: Attention Pet helps people assess capability sufficiency and lower inference-cost candidates separately. Its Model Fit / Cost Fit estimates use uncalibrated profiles; it does not measure internal attention or switch models automatically.

Codex-only preview: Attention Pet

Attention Pet is a small local companion for Codex work. It reads the current Codex chat's local session record, estimates whether the selected model meets the visible work requirements, and shows the result through a compact animated pet. It also shows lower inference-cost comparison candidates when the experimental profiles support one. The estimate is observational and does not change the Codex model, reasoning level, or chat.

It does not measure token usage. It estimates the structural complexity of the work context the AI must handle, including retained items, dependencies, constraints, decision depth, conflicts, and dispersed evidence. It does not read model-internal attention or remaining context-window capacity.

Run it from a Codex terminal in this repository so CODEX_THREAD_ID identifies the current chat:

python -m xrefkit.attention_pet serve --port 8769

Open the printed http://127.0.0.1:8769/ address in the Codex browser panel. The display follows the browser's preferred language: Japanese is used for a Japanese preference, with English as the fallback. Stop the process with Ctrl+C.

This Codex preview is bound to the chat that launched it. Selecting another chat does not move the Pet automatically; launch it again from that chat when you want a separate view. The model and reasoning dropdowns only compare estimates and do not change the active Codex settings. See the Attention Pet guide for interpretation, limitations, client integration, and API details.

Using AI for real work creates recurring operating problems:

• the AI can act from incomplete context or unsupported guesses
• procedures, domain facts, and judgment criteria get mixed together in prompts
• execution, checking, and handoff collapse into one opaque step
• work becomes hard to continue across agents, humans, or sessions
• outputs may lack evidence, closure discipline, or auditability

XRefKit provides a repository and runtime model for addressing these problems.

What it provides

• Skills — reusable procedures expressed as SkillDefinitions
• Knowledge — source-backed domain facts and local rules resolved by XID when a Skill run needs them
• Workflow protocol — recorded progress, deterministic workflow-record verification, and closure checks
• Evidence and handoffs — outputs, judgments, concerns, and decisions that remain reviewable after the work is done
• Skill Run Dashboard — inspect recorded Skill execution state, definition identity, runtime binding, referenced XIDs, evidence, judgments, concerns, and handoffs
• XIDs — stable references for connecting procedures, knowledge, and supporting documents

The package includes the resolver, Skill runtime, workflow controls, client tools, and an optional MCP adapter.

Current Skill authoring targets the one-document skill_definition_v1 format. Existing legacy_split_v1 Skills and unversioned historical run logs remain readable during migration. The Workflow Runtime Binding defines how instruction-derived capability, tuning, responsibility, and execution_mode are captured; these are not fixed SkillDefinition properties. Knowledge used by a Skill remains separate and is resolved from the XID catalog when needed.

The Skill Run Dashboard helps people inspect recorded XID retrieval and use together with the run's evidence before a human accepts or hands off the result. The Dashboard reports recorded state and missing observations; it does not accept output quality.

Quick start

XRefKit requires Python 3.11 or later.

python -m pip install xrefkit
xrefkit init
xrefkit --help

For local development:

python -m pip install -e .
xrefkit init

For the optional MCP server:

python -m pip install "xrefkit[mcp]"
xrefkit mcp serve --repo . --transport stdio

This command starts the optional catalog and runtime MCP adapter. This checkout does not implement management upload, staging, sealing, review, or adoption of uploaded SkillDefinition bytes into the active catalog.

To connect VS Code/Copilot, run from your target workspace:

python -m pip install "xrefkit[mcp]"
python -m xrefkit mcp setup --repo . --output .xrefkit/setup-review
python -m xrefkit mcp setup apply --repo . --source .xrefkit/setup-review

Review the generated files before applying them, open the workspace in VS Code, and start the xrefkit MCP server. In Copilot chat, ask: "Call XRefKit's get_startup_context and help me get started." The AI receives any needed legacy migration guidance; you can describe your goal without specifying Skill names. Opening VS Code alone does not guarantee an AI conversation starts.

Where to go next

• Install XRefKit and register Skill Packages
• Understand the workflow protocol
• Use an instruction-backed workflow
• Understand Skills and Knowledge
• Read the SkillDefinition v1 contract
• Author a Skill with xref
• Browse the complete documentation index

Security

XRefKit does not require provider API keys to explore or install the package. Do not commit secrets, API keys, access tokens, .env files, or provider credentials. Authenticate external AI tools through their official provider mechanisms.

Repository Skill adoption and scoped source-analysis knowledge

This repository uses the audited canonical Skill sources listed in skills/repository_adoption.json. Legacy source identities remain aliases; external legacy split Skills and YAML Skill Packages remain supported. See SkillDefinition adoption. The source-analysis common XID remains stable and routes coherent criteria fragments on demand. Narrow tasks avoid unrelated bodies; full reviews retain every required axis. No similarity-based knowledge merge or deletion occurs.

Public website release metadata

The Pages workflow builds from main, verifies the checked-in site against site/sources, then fetches GitHub's latest published stable release and runs tools/site_release_metadata.py on the deployment artifact. It updates the homepage version, UTC publication date and release link, plus the foundation page's release-source link. The checked-in HTML is an offline snapshot; it is not rewritten or committed by deployment. Editorial development notes are maintained separately and are not inferred from release metadata.

Pages runs on main pushes, release publication/changes, manual dispatch, and successful repository push runs of python-package. The last trigger covers releases created using GITHUB_TOKEN, which do not trigger another release workflow. Deployment always checks out main, never a workflow-run/PR artifact. API failure, a draft/prerelease, an unexpected version tag, or missing page markers stops publication and leaves the previous deployed site in place.

To reproduce the rendering after building a site into a separate directory:

gh api repos/synthaicode/XRefKit/releases/latest > release.json
python tools/site_release_metadata.py --site .generated-site --release-json release.json --repository synthaicode/XRefKit

Use the Pages workflow's manual dispatch to retry a failed metadata fetch.