t1k:kit
| Field | Value |
|---|---|
| Module | t1k-maintainer |
| Version | 4.10.58 |
| Effort | medium |
| Tools | — |
Keywords: audit, kit, maintainer, migrate, release, scaffold, validate
How to invoke
Section titled “How to invoke”/t1k:kit<subcommand> [options]TheOneKit Kit — Maintainer Toolkit
Section titled “TheOneKit Kit — Maintainer Toolkit”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).
Subcommands
Section titled “Subcommands”| Subcommand | Usage | Purpose |
|---|---|---|
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 |
Quick Reference
Section titled “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 kitSubcommand Details
Section titled “Subcommand Details”Read the reference file for full details on each subcommand:
references/validate.md— per-kit and cross-kit validation checksreferences/release.md— release workflow steps and gatesreferences/sync.md— cross-kit synchronization protocolreferences/scaffold.md— new kit scaffolding templatereferences/audit.md— health audit checks and scoringreferences/migrate.md— registry schema migration steps (v1→v2)references/test.md— 12-phase E2E test planreferences/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. Requiredbun -e require(...)wrapper pattern that survives the CLI’s$HOME→$CLAUDE_PROJECT_DIRrewrite bug (model-router#49). CI gatevalidate-global-hook-home-resilience.cjsenforces it.references/origin-metadata-literal-collision.md— never write the literal stringt1k-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— howt1kCLI self-update works (backgroundSessionStartcheck-and-notify); see alsohooks/telemetry-utils.cjsandhooks/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.
Per-module scaffold
Section titled “Per-module scaffold”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):
t1k module new <name> [--required] [--deps a,b] # → .claude/modules/<name>/module.json + skill/agent/rules dirsIt 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.
Hard rules
Section titled “Hard rules”- 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’sfixSingleCommandPath(cmd, isGlobal=false)defaultsisGlobalto false and rewrites$HOME→$CLAUDE_PROJECT_DIR— silently breaking every hook withMODULE_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 gatevalidate-global-hook-home-resilience.cjsenforces. - Origin metadata: never hand-author it, on new or existing files. CI pre-injects canonical
origin / repository / module / protected(andversionat release) beforevalidate-origin-injection-coverage.cjsruns on PR branches, andinject-origin-metadata.cjsre-injects post-merge. Format per file type lives in thet1k:skill-creator“Required Frontmatter” section. t1k rollbackrequires a snapshot that nothing currently creates. The H7 rollback read-side shipped in v4.14.0, but no production install/update path callscreateSnapshot()yet. Until the write-side lands,t1k rollback --kit X --to-snapshot pre-Ywill reliably fail withsnapshot '...' does not exist. Direct users tot1k install --resetfor now if they’re truly stuck — and NEVER recommendrm -rf ~/.claude/.- Universal
t1k-naming prefix (MANDATORY) — every skill directory + agent file + frontmattername:MUST start witht1k-. Tiers: coret1k-{slug}, kit-widet1k-{kit}-{slug}, module-scopedt1k-{kit}-{module}-{slug}; a module named exactly like its kit collapses tot1k-{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 atskills/t1k-skill-creator/references/architecture-rules.md§0 +skills/t1k-agent-creator/references/architecture-rules.md§0. Whenscaffold-ing a new kit/module or auditing an existing one, runbun /path/to/release-action/scripts/validate-skill-prefix.cjsandvalidate-agent-prefix.cjslocally — fail-fast catches missed renames before push.
Future: Self-Improving AI Pipeline
Section titled “Future: Self-Improving AI Pipeline”T1K vision: the kit should self-teach and improve using aggregated consumer data. Planned pipeline:
- User errors collected via telemetry → D1 (already exists)
- Scheduled AI agent (cron) queries D1 for error clusters (same fingerprint, 3+ occurrences, multiple users)
- AI aggregates patterns → synthesizes root cause, workaround, prevention
- Auto-generates gotcha entries for relevant skill SKILL.md files
- Opens PR to kit repo automatically
- 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
Section titled “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