Skip to content

t1k:kit

FieldValue
Modulet1k-maintainer
Version4.10.58
Effortmedium
Tools—

Keywords: audit, kit, maintainer, migrate, release, scaffold, validate

/t1k:kit
<subcommand> [options]

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

Before starting any subcommand, before briefing a sub-agent, and before opening a PR, run the prior-evidence sweep: references/prior-evidence-sweep.md (theonekit-cli#832, #833).

SubcommandUsagePurpose
validate/t1k:kit validate [--cross-kit]Schema, activation paths, keyword conflicts, preset refs, universal t1k- prefix (skills + agents — see skills/t1k-skill-creator/references/architecture-rules.md § 0 + skills/t1k-agent-creator/references/architecture-rules.md § 0)
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
Terminal window
/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

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)
  • references/global-hook-authoring.md — MANDATORY for any kit shipping hooks at global scope. Required bun -e require(...) wrapper pattern that survives the CLI’s $HOME → $CLAUDE_PROJECT_DIR rewrite bug (model-router#49). CI gate validate-global-hook-home-resilience.cjs enforces it.
  • references/origin-metadata-literal-collision.md — never write the literal string t1k-origin: on a non-header source line; the CI origin-injector strips any line matching that substring, corrupting parsing code that references the marker by name.
  • references/cli-auto-update.md — how t1k CLI self-update works (background SessionStart check-and-notify); see also hooks/telemetry-utils.cjs and hooks/lib/auto-commit-helper.cjs.
  • references/prior-evidence-sweep.md — MANDATORY before starting work, briefing a sub-agent, or opening a PR: search open PRs/issues for related evidence so work isn’t duplicated (theonekit-cli#832, #833).
  • references/shared-asset-convention.md — where a shared asset (template, fixture, shared reference table) two or more modules depend on and neither owns lives (.claude/modules/<name>/_shared/, never a bare kit-root _shared/), and how a collision resolves — read before creating or scaffolding one.

scaffold creates a whole new kit (/t1k:kit scaffold theonekit-{engine}). To add one module inside an existing kit, use the scaffolder instead of hand-creating dirs + registry entries — second occurrence ⇒ automate, never repeat by hand (docs/replicate-and-automate.md):

Terminal window
t1k module new <name> [--required] [--deps a,b] # → .claude/modules/<name>/module.json + skill/agent/rules dirs

It writes module.json, creates the skills/, agents/, and rules/ dirs, adds a registry entry, and regenerates t1k-modules.json (via generate-modules-registry.cjs). Requires CLI ≥ 5.4.0.

  • Global-scope hooks MUST use the bun -e require(...) wrapper, NOT bare $HOME/.claude/hooks/X.cjs. When a kit ships hooks installed into global ~/.claude/settings.json (not project .claude/settings.json), the T1K CLI’s fixSingleCommandPath(cmd, isGlobal=false) defaults isGlobal to false and rewrites $HOME → $CLAUDE_PROJECT_DIR — silently breaking every hook with MODULE_NOT_FOUND (loader:1424). Defense-in-depth wrapper: bun -e "process.env.HOME = require('os').userInfo().homedir; require(require('path').join(process.env.HOME, '.claude', 'hooks', 'your-hook.cjs'))". Reads home from /etc/passwd (POSIX) — unaffected by HOME env corruption. Originating incident: model-router#49 (~363 banner errors per 90-min session before fix). Full pattern + validation: references/global-hook-authoring.md. CI gate validate-global-hook-home-resilience.cjs enforces.
  • Origin metadata: never hand-author it, on new or existing files. CI pre-injects canonical origin / repository / module / protected (and version at release) before validate-origin-injection-coverage.cjs runs on PR branches, and inject-origin-metadata.cjs re-injects post-merge. Format per file type lives in the t1k:skill-creator “Required Frontmatter” section.
  • 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/.
  • 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}; a module named exactly like its kit collapses to t1k-{kit}-{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 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 bun /path/to/release-action/scripts/validate-skill-prefix.cjs and validate-agent-prefix.cjs locally — fail-fast catches missed renames before push.

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.

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