XRefKit

Less effort reconstructing AI work. More attention for the decisions that matter.

XRefKit is designed to reduce the cognitive load of directing and reviewing AI-assisted work. It keeps reusable procedures, relevant knowledge, progress, and evidence in explicit records, then helps present results in a form people can understand and check.

Why faster AI output can still mean more work for you

Generating a result leaves another task: understanding enough of it to decide whether to use it. You may have to reconstruct the context, identify claims, find supporting sources, and check the revised output again. Faster generation can leave you with more material to review and more connections to reconstruct.

XRefKit addresses five recurring sources of that effort:

• You have to remember what to tell the AI. Rebuilding instructions from memory makes you responsible for recalling every step and criterion. Reusable Skills keep the procedure, required inputs, expected outputs, and criteria available for the next task.
• You have to search for the rules behind a result. Scattered reference material makes you switch between documents and reconnect them yourself. Separate Knowledge records and stable identifiers (XIDs) let a Skill resolve relevant material and record references for review.
• You have to rebuild context after an interruption. A conversation history leaves you to discover where the work stopped. Work items and handoff records preserve progress, open concerns, and next steps that another session or colleague can pick up.
• You have to learn how to read each new report. Changing headings, order, or detail makes you search again for the same information. Optional approved report profiles preserve familiar structure and granularity, giving subsequent reviews an explicit baseline.
• You have to infer what “done” actually covers. A completion statement can leave the checks, evidence, and unresolved decisions unclear. Workflow-record checks and reporting guidance make those boundaries explicit, while tests and reviewers assess the result itself.

The aim is to keep what you need visible and available, so you can check it without remembering or reconstructing it each time. How much these mechanisms reduce the effort in practice still needs evaluation with users.

Make the report easier to understand—and easier to check

A shorter report only helps if it preserves what the reader needs to decide. XRefKit's reporting guidance connects the conclusion, its basis, its limits, and the next action within the task's own format:

• Reduce searching: put the conclusion and requested decision first. Keep material uncertainty beside the claim it qualifies.
• Reduce mental reconstruction: connect a finding to its evidence and explain why that evidence matters. A file list alone leaves that connection for the reader to make.
• Reduce initial overload: present the decision-relevant summary, with clear links to detailed findings, so you can inspect the supporting detail when needed. Keep essential caveats in the summary.
• Reduce relearning: for recurring outputs, use an approved Knowledge quality profile containing examples, headings, table structure, information placement, detail, and criteria. Structural checks detect format differences; independent review still judges meaning and evidential support.

For illustration, a change-review summary could read:

Decision needed: Hold acceptance until the retry case is checked.

Verified: The normal path passed against the agreed criteria; the findings link to the test evidence.

Still unknown: Whether retrying after a timeout creates a duplicate.

Next step: Test the retry case and return the result for review.

This example shows where the reader's attention belongs; it is not a universal template or a real test result. Plain words, short sections, and clear connections between a finding and its evidence help you follow the reasoning.

Reader feedback can identify a missing explanation, confusing placement, or insufficient evidence. The correction can then target the output, inputs, criteria, or procedure. Approved baselines stay intact; procedure changes require explicit authorization.

The purpose is to make informed review less demanding. A familiar layout or a passing record check does not establish correctness. See the reporting contract and fixed-output quality protocol.

How does XRefKit fit with modern agent harnesses?

Modern harnesses already support more than execution. They can preserve sessions, organize repository knowledge and plans, and support evaluation criteria, automated constraints, and structured handoffs. The capabilities available to you depend on the harness and its configuration.

XRefKit's focus is the human effort of directing, understanding, and reviewing that work. It packages reusable procedures, separately maintained knowledge, work records, and reporting criteria as assets the team can inspect and maintain. Repository files and Skill Packages preserve those assets; CLI/MCP interfaces make them available to compatible clients.

Your coding harness can implement and test a change while XRefKit records the applicable review method, references, findings, and open concerns. The report then helps a person decide what the result supports and what to do next. The client runs the model and tools; XRefKit's verify and close check workflow records, while substantive quality needs appropriate tests and review.

If your harness already provides this structure, there may be little to add. Use XRefKit when you want these work assets and review conventions made explicit and reusable. This is a difference in packaged mechanisms and emphasis, not a demonstrated advantage in cognitive load, quality, cost, or performance.

See the Skill and Knowledge operating model and Skill operating contract.

Start with one recurring task

Choose a task you already know how to review: a document check, an investigation, or a development handoff. Start with one procedure and the reference material it needs, then use the resulting work record to decide what to improve.

1. Prepare your workspace

You need Python 3.11 or later. Run these commands in the folder where you want to work:

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

Initialization creates the local XRefKit configuration and missing AI startup files while preserving existing startup files. See the installation and Skill Package guide to add reusable Skills or bring existing material into your workspace.

For older custom Skills that call Python under a shared tools/ directory, connect your AI client and ask it to migrate the old environment. See guided legacy migration for preparation, safe baseline tests, governed registration and client verification.

2. Connect your AI tool

For VS Code/Copilot, install the optional MCP integration and generate a setup proposal:

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

Review the generated files, then apply the setup:

python -m xrefkit mcp setup apply --repo . --source .xrefkit/setup-review

Open the workspace in VS Code, start the xrefkit MCP server, and ask in Copilot chat:

Call XRefKit's get_startup_context and help me get started.

Then describe the task you want to accomplish. You do not need to know a Skill name to ask for guidance. Opening VS Code alone does not start the conversation.

For an MCP client that accepts a local server command, the server entry point is:

xrefkit mcp serve --repo . --transport stdio

3. Review the work and decide what comes next

Use the Skill Run Dashboard to inspect recorded progress, referenced knowledge, outputs, concerns, and handoffs. It shows what was recorded and where observations are missing; you decide whether the result is ready to use.

The workflow walkthrough explains how work moves from a request to verification and handoff.

Choose your next step

• Use existing procedures: Install and register Skill Packages.
• Organize a task from your own instructions: Use an instruction-backed workflow.
• Capture your team's way of working: Understand Skills and Knowledge, then author a Skill.
• Explore the details: Browse the documentation.

Optional: explore model fit with Attention Pet

The experimental Attention Pet companion helps Codex users inspect estimates of model suitability and compare lower-cost candidates using the visible work context. Run it from a Codex terminal in this repository:

python -m xrefkit.attention_pet serve --port 8769

Open the printed address in the Codex browser panel. The preview follows the chat that launched it. Its estimates are uncalibrated; it does not measure internal attention or token usage, and it does not change your model settings.

Contribute or maintain a deployment

For local development, install this checkout with python -m pip install -e .. The pipeline dependency reference describes CI and publication triggers. Internal authoring and runtime details are in the SkillDefinition contract and Workflow Runtime Binding contract.

XRefKit does not require provider API keys to install or explore the package. Authenticate your AI tool through its provider's supported methods, and keep secrets and access tokens out of the repository.