UKit

UKit installs a project-local AI workspace (.claude/, adapters, docs, and index helpers) so your team can work with Claude Code, Antigravity, OpenAI Codex, and OpenCode from the same repo setup.

Highest-Priority Team Rule

For normal team usage, the only UKit command anyone should need to remember is ukit install.

After ukit install finishes:

• open your AI tool
• describe the task in natural language
• let the workspace instructions route the flow

How the CLI binary itself gets installed or refreshed is a maintainer/platform concern. Inside projects, the command teammates should remember remains ukit install.

Do not onboard the whole team around ukit doctor, ukit diff, ukit uninstall, or ukit index .... Those commands can still exist for maintainers/debugging, but they are intentionally not the default human workflow.

Team Workflow

1. Install the UKit CLI globally.

   npm install -g @ngockhoale/ukit

2. Open any project root in the terminal.
3. Run:

ukit install

4. Fill in the generated docs baseline:
   • docs/PROJECT.md
   • docs/MEMORY.md
   • docs/AI_HANDOFF/
   • docs/WORKLOG.md
5. Open your AI tool and work in natural language.

Update Policy

The same command handles both first-time setup and refreshes:

ukit install

If UKit changes, your templates change, or a teammate needs to re-apply the workspace, rerun ukit install. If maintainers roll out a newer CLI build, the in-project workflow still stays the same: rerun ukit install.

What ukit install Creates

Core workspace

• .claude/skills/ — canonical skills
• .claude/agents/ — specialist agents
• .claude/hooks/ — tool hooks
• CLAUDE.md — Claude Code instructions
• AGENTS.md — shared instructions for AGENTS-compatible tools

Adapters

• .antigravity/skills/ → symlink to .claude/skills/
• .antigravity/rules/ — Antigravity rules
• .codex/settings.json + .codex/settings.local.json — Codex config
• opencode.json — OpenCode project config with UKit-safe guardrails

Project support files

• .claude/ukit/.ukit/ — installer manifests, metadata, backups
• .ukit/ — hidden shared runtime storage for config, cache, and cross-agent memory
• docs/ — PROJECT / MEMORY / AI_HANDOFF / WORKLOG baseline

UKit v1.3.1 Runtime

UKit now installs a hidden shared local runtime at .ukit/ for production-oriented state that should survive across agent sessions:

• .ukit/storage/config.json — runtime defaults for compact/router/memory/validation/subagent hints
• .ukit/storage/cache/ — reusable prompt-cache, compact history, compact-pressure state, and output summaries
• .ukit/storage/memory/ — cross-agent local memory
• .ukit/storage/backups/ — rollback bytes for risky Safe Patch Protocol edits

If an older repo still has a visible legacy ukit/ runtime folder, rerunning ukit install now migrates the shared runtime into hidden .ukit/ when the target paths are free.

When long sessions approach the compact threshold, UKit now uses a conservative pressure lane:

• soft threshold = configured compact token threshold
• hard threshold = roughly 20% above soft
• compact only safe-zone history/noise
• preserve active task, rules, decisions, and current code focus

UKit v1.3.1 keeps the same shared runtime contract while adding Safe Patch Protocol guardrails and the local AI task queue alongside living project status routing:

• install globally with npm install -g @ngockhoale/ukit
• keep using the exact same human workflow inside projects: ukit install
• preserve the same ukit binary, hooks, and install-first orchestration while standardizing the runtime root as hidden .ukit/
• install docs/AI_HANDOFF/ as the cross-AI handoff folder with per-task isolation: ACTIVE.md (snapshot), INDEX.md (task index), tasks/ (one file per task) so each AI reads only the task it needs, with token budget rules in RULES.md
• auto-route open-ended “what next?” / “continue” prompts to the next-step skill with a visible freshness cue when status may be stale
• auto-route explicit handoff/wrap-up requests to the update-status skill while skipping trivial/no-state-change tasks
• keep concrete debug/implementation/review prompts primary, so project status never replaces source/index-first task work
• quietly guard risky AI edits with Safe Patch Protocol: stale/ambiguous specs are blocked, shared-risk whole-file writes are discouraged, and internal helpers preserve UTF-8 BOM/no-BOM plus LF/CRLF for multilingual text

UKit v1.3.1 also keeps the fast path improvements from the recent runtime releases:

• Vietnamese prompts now normalize more effectively for English-heavy code symbols and paths
• localized simple direct-target lanes skip extra previous-context / recent-output work when it would not change the next action
• routed verification lanes reuse declared packageManager metadata so helpers/hooks stop probing every lockfile candidate unnecessarily

For maintainers, the runtime is inspectable with:

• ukit status
• ukit memory list
• ukit memory recall "<current task>"
• ukit memory export

Normal teammates should still only need ukit install.

Installer Behavior

• idempotent install (safe to rerun)
• timestamped backups before overwrite
• template rendering with project-aware variables
• dependency-ordered manifest execution
• path safety checks for template and target traversal
• shared-skill adapter linking across supported tools
• post-install docs baseline reminders
• automatic code-index build + refresh hook install

Working Style After Install

UKit is built so the team can stop memorizing UKit subcommands and focus on product work:

• ask for fixes, reviews, implementations, tests, or docs in natural language
• let the installed instructions choose the right workflow
• let the AI use the indexed source code first so it can find the right files/tests fast
• let Claude Code / Codex / OpenCode auto-detect and use the right project-local skill from the prompt and the files/tools involved
• let the AI prefer targeted verification first, then widen only when shared/risky scope justifies it
• let the AI selectively auto-delegate internal subagents only when that actually reduces context/noise or unlocks parallel progress; small localized work should stay direct
• keep long sessions compact across agents: Claude keeps PreCompact/reinject, OpenCode keeps native auto/prune compaction, and Codex Desktop uses internal compact.codexContext.compactTarget soft handoffs (default 150 lines; 120-150 preferred, hard max 170), without asking end users to manage context manually
• let UKit internally use the ukit-small-task-maintainer subagent with subagents.smallTaskModel=unic-lite for safe task cleanup, fast-vs-slow/safe-vs-risky lane hints, skill-routing/step-budget hints, agent context-budget decisions, compact decisions, doc summarization, classification, and queue maintenance while risky/security/release/quality-risk work stays on the main model
• rerun ukit install when you need to refresh the workspace

End users should not need to know or memorize skill names.

Upstream Skill Alignment

To keep UKit strong over time, maintainer work should track the current upstream skill ecosystem:

• official Anthropic skills: anthropics/skills
• official OpenAI skills: openai/skills
• Agent Skills open standard: agentskills.io
• curated discovery lists such as awesome-claude-code and awesome-agent-skills

But this is a maintainer concern, not a team-onboarding burden.

The rule remains:

ship curated improvements through UKit, then ask teammates to rerun ukit install

Do not require normal contributors to learn marketplace/plugin commands just to use the workspace.

Maintainer / Debug Commands

These commands are still available, but they are advanced workflows, not default team onboarding:

• ukit diff — preview file changes before install
• ukit doctor — validate UKit state and docs baseline
• ukit uninstall — remove UKit-managed assets
• ukit status — inspect shared UKit runtime state
• ukit memory ... — inspect/export/forget shared memory items
• ukit index ... — run repo indexing/query/triage tools directly
• ukit build index — alias for ukit index build

Use them when maintaining UKit, debugging workspace setup, or developing the CLI itself — not as the day-to-day path every teammate must learn.

Repo Development

For maintainers evolving UKit itself, the key repo references live in:

• docs/UKIT_CODEV_PRINCIPLES.md
• docs/RELEASE_1_1_3_SIGNOFF.md

Run the test suite from the UKit repo root:

yarn test

For deeper index development, repo-level scripts are available:

• yarn index:build
• yarn index:refresh
• yarn index:query -- "<error|symbol|path>"
• yarn bug:triage -- "<error signature>"

Tool Support

| Tool | Instructions | Skills | Config | |------|-------------|--------|--------| | Claude Code | CLAUDE.md | .claude/skills/ (canonical) | .claude/settings.json | | Antigravity | AGENTS.md | .antigravity/skills/ (symlink) | .antigravity/rules/, .antigravity/README.md | | OpenAI Codex | AGENTS.md | .claude/skills/ (referenced) | .codex/settings.json, .codex/settings.local.json, .codex/README.md | | OpenCode | AGENTS.md | .claude/skills/ (native Claude-compatible support) | opencode.json |

All supported tools share the same SKILL.md ecosystem so the workspace is authored once and reused everywhere.