t1k-kit

name	t1k:kit
description	Maintain TheOneKit repos as a kit maintainer. Use for releasing kits, scaffolding new kits, cross-kit validation, schema migration, and E2E test runs.
keywords	["maintainer","release","scaffold","validate","audit","migrate","kit"]
argument-hint	<subcommand> [options]
effort	medium
version	1.115.3
origin	theonekit-core
repository	The1Studio/theonekit-core
module	t1k-maintainer
protected	true

TheOneKit Kit — Maintainer Toolkit

Unified kit maintenance skill. All subcommands are for kit maintainers only, not end-users.

Subcommands

Subcommand	Usage	Purpose
validate	/t1k:kit validate [--cross-kit]	Schema, activation paths, keyword conflicts, preset refs, universal t1k- prefix (skills + agents — see rules/naming-convention.md)
release	/t1k:kit release [--skip-validate]	Guided release: validate → CI gate → GitHub release → Discord
sync	/t1k:kit sync [--pull] [--status-only]	Pull all kits, check version compat, release-action alignment
scaffold	/t1k:kit scaffold <name> [--org]	Create new kit repo from template with full boilerplate
audit	/t1k:kit audit [--all]	Health audit: file counts, modules, keywords, CI, freshness
migrate	/t1k:kit migrate [--dry-run]	Schema migration (e.g., registryVersion 1→2)
test	/t1k:kit test [--all] [--kit <name>]	Comprehensive 15-phase E2E testing: install, modules, CLI, release infra

Quick Reference

/t1k:kit validate              # Validate current kit repo
/t1k:kit validate --cross-kit  # Validate across all installed kits
/t1k:kit release               # Guided release workflow
/t1k:kit sync --pull           # Pull and check all kits
/t1k:kit scaffold theonekit-x  # Scaffold new kit
/t1k:kit audit --all           # Audit all kit repos
/t1k:kit migrate --dry-run     # Preview schema migration
/t1k:kit test --all            # E2E test all kits
/t1k:kit test --kit unity      # E2E test specific kit

Subcommand Details

Read the reference file for full details on each subcommand:

• references/validate.md — per-kit and cross-kit validation checks
• references/release.md — release workflow steps and gates
• references/sync.md — cross-kit synchronization protocol
• references/scaffold.md — new kit scaffolding template
• references/audit.md — health audit checks and scoring
• references/migrate.md — registry schema migration steps (v1→v2)
• references/test.md — 12-phase E2E test plan
• references/cli-commands.md — t1k new, t1k modules create, t1k migrate, t1k migrate metadata, t1k rollback (cli@v4.14.0; flags + gotchas grounded in source)

Gotchas

• Origin metadata: hand-stamp on NEW files, hands-off on existing files. The release-action inject-origin-metadata.cjs runs post-merge — it strips and re-injects canonical origin / repository / module / protected (and version for SKILL.md) from env vars + module-resolution. So files already on main MUST NOT be hand-edited for these fields. BUT new files in PR branches MUST hand-stamp at least origin: (validator validate-origin-injection-coverage.cjs checks marker presence pre-merge — values are best-effort, CI overwrites them). Format per file type lives in memory feedback_origin_marker_handauthor.md and the t1k:skill-creator "Required Frontmatter" section.
• Modular kits use release-modules.cjs (custom release script), NOT semantic-release directly. Flat kits (e.g., theonekit-rn) still use semantic-release. release-modules.cjs produces per-module ZIPs + manifest.json index.
• t1k-modules.json is GENERATED for the modules section — do not hand-author it. Source of truth is each module.json. Only presets in t1k-modules.json are hand-authored.
• .releaserc.json MUST include package.json and .claude/metadata.json in @semantic-release/git assets — without this, package.json stays at 0.0.0 forever. Every kit repo needs: "assets": ["package.json", "CHANGELOG.md", ".claude/metadata.json"]
• Do not hardcode version or buildDate in source metadata.json — CI generates these from package.json. Source should only contain manually-maintained fields (name, repository, deletions).
• Canonical "full" preset — required in EVERY kit — every modular kit MUST declare "full": "*" in t1k-modules.json presets. The interactive selector renders a synthetic "Full — all N modules" choice from any "*"-valued preset (it keys off the value, not the name), so kits with no presets or a differently-named "*" preset look fine in the UI — but scripted invocations like t1k new --preset full fail when the preset is named anything other than literally "full". Apr 2026 audit caught: web (everything: "*"), marketing + nakama (no presets section at all), designer (array-shorthand drift). Always name the "*" preset literally "full" even when the kit has only one required module (future-proofs scripted use). Other named presets (rpg, fullstack, etc.) MUST use v3 object form { "modules": [...], "description"?: "...", "crossKitModules"?: [...] } — array shorthand ["mod-a", "mod-b"] resolves at runtime but breaks cross-kit format consistency.
• module new and kit new are NOT real CLI subcommands. The shipped commands are t1k new (project bootstrap) and t1k modules create (module scaffold). Older audits and design docs use the legacy names — when documenting maintainer flows, reference the real CLI surface (references/cli-commands.md).
• t1k rollback requires a snapshot that nothing currently creates. The H7 rollback read-side shipped in v4.14.0, but no production install/update path calls createSnapshot() yet. Until the write-side lands, t1k rollback --kit X --to-snapshot pre-Y will reliably fail with snapshot '...' does not exist. Direct users to t1k install --reset for now if they're truly stuck — and NEVER recommend rm -rf ~/.claude/.
• t1k rollback --yes is a documented no-op as of v4.14.0 — declared in the CLI registry, never read by the handler. Do not promise confirmation-bypass behavior in maintainer guidance.
• --to-snapshot MUST literally start with pre-. Bare-version arguments (--to-snapshot 2.4.1) are rejected. Always render the pre- prefix in examples.
• Scaffold new modules with a detect: stub — when scaffold or /t1k:modules create writes a new module.json for a non-base module, emit a _disabled: true detect stub so P6d CI and doctor #41 stay green while the author tightens patterns:

  "detect": {
    "_disabled": true,
    "_note": "AUTO-GENERATED STUB. Tighten files+anyOf then remove _disabled to activate.",
    "files": ["**/*.md"],
    "anyOf": [{ "pattern": "TightenThisPattern_<moduleName>", "minHits": 2 }]
  }
  

  The stub is schema-valid (passes P6d), scanner silently skips modules with _disabled: true, and doctor #41 surfaces the stub as "needs activation" so the author can't forget.
• Universal t1k- naming prefix (MANDATORY) — every skill directory + agent file + frontmatter name: MUST start with t1k-. Tiers: core t1k-{slug}, kit-wide t1k-{kit}-{slug}, module-scoped t1k-{kit}-{module}-{slug}. Slug MUST NOT redundantly start with the kit-short or any module-segment-token (algorithm v2 strips them). Three release-action gates are strict-by-default: validate-skill-prefix.cjs, validate-agent-prefix.cjs, validate-new-name-conformance.cjs. SSOT lives at rules/naming-convention.md + skills/t1k-skill-creator/references/architecture-rules.md §0 + skills/t1k-agent-creator/references/architecture-rules.md §0. When scaffold-ing a new kit/module or auditing an existing one, run node /path/to/release-action/scripts/validate-skill-prefix.cjs and validate-agent-prefix.cjs locally — fail-fast catches missed renames before push.
• Activation fragment ref convention — bare-slug refs are the SSOT — entries in t1k-activation-*.json sessionBaseline[] and mappings[].skills[] arrays canonically use the bare slug form (e.g., nakama-rpc for the dir t1k-nakama-rpc). The CI prefixer's auto-prefix-skills.cjs::buildSelfHealMap() self-heals legacy refs to canonical dir names at release time but the SSOT in fragment files stays bare so authors can write naturally. The release-action gate validate-activation-skill-resolution.cjs (per-PR safety net, added 2026-05-11) accepts BOTH bare and full-prefixed forms — anything else fails. When authoring or reviewing activation fragments, use the local bare slug ({slug} after kit + module strip) — NOT {kit}-{slug} shorthand that skips the module segment, which is the legacy form the self-heal does not accept and the gate flags. See t1k-doctor check #47 for the doctor-time mirror.

Future: Self-Improving AI Pipeline

T1K vision: the kit should self-teach and improve using aggregated consumer data. Planned pipeline:

1. User errors collected via telemetry → D1 (already exists)
2. Scheduled AI agent (cron) queries D1 for error clusters (same fingerprint, 3+ occurrences, multiple users)
3. AI aggregates patterns → synthesizes root cause, workaround, prevention
4. Auto-generates gotcha entries for relevant skill SKILL.md files
5. Opens PR to kit repo automatically
6. Maintainer reviews and merges → next release distributes to ALL users

Status: Not yet implemented. See CLAUDE.md "Self-Improving AI Vision" for context.

Auto-Activation Keywords

Triggers on: kit validate, kit release, kit sync, kit scaffold, kit audit, kit migrate, kit test, kit health, kit status, cross-kit, maintainer, test kit, test install, test modules, e2e kit, validate installation, self-improving, auto-gotcha, gotcha generation, ai aggregation, learn from users, t1k new, t1k rollback, t1k migrate, t1k modules create, module new, kit new, module migrate, migrate metadata, rollback snapshot, pre-snapshot