Skip to content

t1k:modules

FieldValue
Modulet1k-base
Version5.15.36
Effortmedium
Tools—

Keywords: install, list, manage, modules, preset, remove, update

/t1k:modules
<subcommand> [args] [--kit <kit>] [--yes|--force|--replace]

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.

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):

CommandPurpose
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
listShow 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:

ProcedurePurpose
upgrade --preview <module>Show upgrade diff before applying
validateCheck all installed modules have satisfied deps
auditUnused 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):

Terminal window
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):

  1. Spawn t1k-modules-manager (subagent_type: "t1k-modules-manager", task in description: per agent-name-is-identity.md).
  2. 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).
  3. 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 --dir row above).
  4. 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.

Follow protocol: skills/t1k-modules/references/module-detection-protocol.md

Detect installed kits from MULTIPLE signals:

  1. metadata.json → installedModules or kits key
  2. t1k-routing-*.json files — each fragment = one kit installed
  3. t1k-activation-*.json files — activation fragments confirm kit presence
  4. .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.

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:

  1. confident.install[] — present list with hits + first excerpt; on user confirmation: t1k modules add <name> --yes.
  2. confident.recover[] — orphan directories; on user confirmation: t1k modules add <name> --yes (reinstall reconciles metadata.installedModules).
  3. ambiguous[] — defer to AI reasoning (see next section).
  4. unused-suspect[] — NEVER auto-apply; skill explains per-module and asks before t1k modules remove --yes. Requires --aggressive on 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.

For ambiguous[] entries, regex hits alone are insufficient. Claude reasons over the full context:

  1. Read each ambiguous entry’s excerpts[] (file + line + snippet).
  2. Open the first 1–2 source files via the Read tool to confirm the semantic fit.
  3. Cross-reference the module’s description and skills[] in .claude/t1k-modules.json.
  4. Form a per-module recommendation with explicit rationale, e.g. “unity-mobile: the project compiles for iOS + reads Application.platform == IPhone in 3 files; AndroidManifest.xml is absent. Recommend install.”
  5. 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).

  • 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:doctor module checks
  • split, merge, create are kit-repo operations; add, remove, update, preset are project operations

Module management operations only.