t1k:modules
| Field | Value |
|---|---|
| Module | t1k-base |
| Version | 5.15.36 |
| Effort | medium |
| Tools | — |
Keywords: install, list, manage, modules, preset, remove, update
How to invoke
Section titled “How to invoke”/t1k:modules<subcommand> [args] [--kit <kit>] [--yes|--force|--replace]TheOneKit Modules — Module Management
Section titled “TheOneKit Modules — Module Management”Day-to-day module management for modular kits. Modules are downloaded from
GitHub Releases independently, each versioned via module.json. Dependencies
are resolved automatically using semver ranges.
Subcommands
Section titled “Subcommands”CLI verbs — t1k modules <verb> runs these (the CLI’s whole set is add, remove, update, list, scope, preset, detect, create, migrate; anything else exits Unknown subcommand):
| Command | Purpose |
|---|---|
add <names> | Install modules + auto-resolve deps |
remove <names> | Remove modules (refuses if dependents exist) |
update [<module>] | Deprecated (v4 verb). Do not use. Update modules with t1k init --kit <kit> (project) or t1k init -g --kit <kit> (global); the CLI prints a deprecation notice for modules update |
list | Show every module of each kit in the target scope: ✓ installed or ○ available, deps, [required] and [applies here] / [not applicable here: …] tags, from the locally installed registry. There is no --available flag (exits Unknown option; #4616) |
preset <name> | Install all modules in a preset |
create <name> | Scaffold new module in kit repo |
--dir <install-root> | Selects the scope (a global flag, not a verb). The global install is --dir "$HOME" (→ $HOME/.claude); a project scope is --dir <project>. There is no -g / --global / --scope flag — all three exit Unknown option (the CLI’s own --dir help reads “Target project directory”, but the scope is resolved from exactly that argument, so --dir "$HOME" is the only way to reach the global install; #4396). |
Agent procedures — NOT CLI verbs. t1k modules validate|audit|upgrade|split|merge fail with Unknown subcommand; do not run them. The named procedure in references/subcommand-details.md is carried out by the agent with the doctor checks and file edits it describes:
| Procedure | Purpose |
|---|---|
upgrade --preview <module> | Show upgrade diff before applying |
validate | Check all installed modules have satisfied deps |
audit | Unused modules, missing deps, version conflicts |
split <module> | Split a module into two (kit-repo operation) |
merge <a> <b> | Merge two modules into one (kit-repo operation) |
Scripted installs: t1k init --kit <kit> -y hard-refuses a multi-module kit unless --preset <name>, --modules <a,b,c> or --reuse-modules is also given (single-module kits such as unity/cocos need none). An unattended install without one of the three fails on the first try.
A core-family module at PROJECT scope. core and model-router are global-scope kits by policy (kit-scope-policy.ts), so t1k init --kit core --dir <project> is refused, and t1k modules add writes the project scope only, so it refuses a core module outright. The route is --inherit-from, and the path must be the global .claude/ itself ($HOME/.claude; any other parent is still refused):
t1k init --kit core --modules <name> --dir <project> -y --inherit-from "$HOME/.claude"--modules is an EXACT set — list every module to keep, or the rest are removed. Semantics: docs/global-only-mode.md § “Nested Installs and Inheritance”. Doctor #77 still reports the resulting project-local core files (status=stale → FAIL, exit 1) — it has no inheritsFrom carve-out, unlike #58; that is expected for this route, not a reason to delete the tree.
Delegation (MANDATORY — never run inline from a lead/main session)
Section titled “Delegation (MANDATORY — never run inline from a lead/main session)”Every subcommand above is executed by the t1k-modules-manager sub-agent, not inline by
whichever session invoked /t1k:modules. If you are the main/lead session (or any agent that is
not itself t1k-modules-manager):
- Spawn
t1k-modules-manager(subagent_type: "t1k-modules-manager", task indescription:peragent-name-is-identity.md). - Do not ask for approval first. A module/kit check-or-update request — explicit user ask or a
detected-drift finding — is itself sufficient authorization to spawn and audit; it does not
authorize a mutating verb (
add/remove/update/preset) without the CLI’s own confirmation gates being satisfied first (see “Detect & Apply” and “AI Reasoning Layer” below, which still govern what the agent does once spawned). - Brief with the scope(s) to check (
skills/t1k-team/references/lean-brief-pointer-not-payload.md) — global, project, or both — not with payload; the agent owns discovery, CLI invocation, and the kit-source guard. Name the invocation, not just the concept: the scope selector is--dir <install-root>(global =--dir "$HOME"; there is no-g/--global/--scope— see the--dirrow above). - Relay the agent’s report verbatim.
Exception: if you were spawned specifically to run this skill (you ARE t1k-modules-manager),
execute the workflow below directly — do not recurse-spawn yourself.
Module State Detection
Section titled “Module State Detection”Follow protocol: skills/t1k-modules/references/module-detection-protocol.md
Detect installed kits from MULTIPLE signals:
metadata.json→installedModulesorkitskeyt1k-routing-*.jsonfiles — each fragment = one kit installedt1k-activation-*.jsonfiles — activation fragments confirm kit presence.claude/agents/— kit-specific agents = kit installed
Always read t1k-modules.json to discover ALL available modules. Module discovery scans only the first 30 lines of each module.json (frontmatter region) for performance; full body parsed lazily only when an action requires it.
Live Module State (fetch on demand — do NOT inline in body)
Section titled “Live Module State (fetch on demand — do NOT inline in body)”When a module subcommand runs, fetch live state via tool calls AFTER the body is loaded — NEVER embed inline shell-substitution tokens (the !-prefix-then-backtick syntax) here (cache-busts on every module install/remove). Use:
Read .claude/metadata.json→ v3 schema,installedModules[],kits[]Read .t1k-module-summary.txt→ quick summary (file may not exist)Read .claude/t1k-modules.json→ registry of available modules + presets
If a file doesn’t exist, treat as “no modular kits installed” — do not echo error.
Subcommand Details
Section titled “Subcommand Details”Full implementation details for each subcommand: references/subcommand-details.md
Detect & Apply — CLI Delegation (P4 SSOT)
Section titled “Detect & Apply — CLI Delegation (P4 SSOT)”The skill does NOT reimplement scanning. All evidence collection is CLI-side; the skill is the decision layer.
t1k modules detect --json [--cache-only] [--kit <name>]Returns the 3-section evidence shape: {confident: {install, recover}, ambiguous, unused-suspect, scanned, mode?}. Skill workflow:
confident.install[]— present list with hits + first excerpt; on user confirmation:t1k modules add <name> --yes.confident.recover[]— orphan directories; on user confirmation:t1k modules add <name> --yes(reinstall reconcilesmetadata.installedModules).ambiguous[]— defer to AI reasoning (see next section).unused-suspect[]— NEVER auto-apply; skill explains per-module and asks beforet1k modules remove --yes. Requires--aggressiveon the CLI side.
Fallback when t1k CLI is missing: the skill must detect this (which t1k or spawnSync('t1k', ['--version']) exit != 0), warn with the npm install hint, and fall back to the legacy manual workflow documented in references/subcommand-details.md. Never crash.
AI Reasoning Layer (P7)
Section titled “AI Reasoning Layer (P7)”For ambiguous[] entries, regex hits alone are insufficient. Claude reasons over the full context:
- Read each ambiguous entry’s
excerpts[](file + line + snippet). - Open the first 1–2 source files via the
Readtool to confirm the semantic fit. - Cross-reference the module’s
descriptionandskills[]in.claude/t1k-modules.json. - Form a per-module recommendation with explicit rationale, e.g. “unity-mobile: the project compiles for iOS + reads
Application.platform == IPhonein 3 files; AndroidManifest.xml is absent. Recommend install.” - Present a single conversational summary to the user: per-module
INSTALL / SKIP / NEED MORE INFO, reasons included. Never auto-apply on ambiguous.
For unused-suspect[], Claude reads the module’s description + inspects git history (git log -- .claude/modules/{name}/) to distinguish “never used” from “used transiently, still valuable.” Defaults to recommending KEEP unless clear dead-weight signal.
Design rationale: per CLAUDE.md #8, CLI emits evidence; AI reasons. This is the canonical example of that split. Doctor check #40 (project-module-fitness) remains deterministic: it surfaces confident.* only and never consults the AI layer.
After any update — preserve user settings
Section titled “After any update — preserve user settings”After any t1k init --kit <kit> / t1k init -g --kit <kit> update (either scope), run the settings diff in
skills/t1k-modules/references/preserve-user-settings-across-update.md: compare the live
settings.json against the newest pre-update backup, restore dropped user-owned entries, and
report what you restored in one line (or that the check could not run).
Key Behaviors
Section titled “Key Behaviors”- Modules are downloaded from GitHub Releases (not extracted from a full kit ZIP)
- Each module is independently versioned; deps use semver ranges
- File manifests (
.claude/modules/<name>/manifest.json) enable clean remove/update - All destructive operations (split, merge, remove) require confirmation
- After every operation: auto-run
/t1k:doctormodule checks split,merge,createare kit-repo operations;add,remove,update,presetare project operations
Module management operations only.