t1k:setup-project
| Field | Value |
|---|---|
| Module | t1k-onboarding |
| Version | 2.7.51 |
| Effort | medium |
| Tools | — |
Keywords: bind discord channel, cấu hình ios, discord channel id, ios setup, jenkins build job, liên kết project, link project to services, link repo to services, onboard project, onboard this repo, service binding, service bindings, set up jenkins job, set up this project, setup ios, setup jenkins job, setup project, setup project ios, setup project unity, setup-project
How to invoke
Section titled “How to invoke”/t1k:setup-project[--service <name>]T1K Setup Project
Section titled “T1K Setup Project”Link an existing repo to the services it needs. v2 covers three: Plane (work-item tracking, via the existing t1k-plane skill), Discord (a build channel, via discord-mcp), and Jenkins (build jobs, via /t1k:jenkins-unity or /t1k:jenkins-cocos). For a Unity project targeting iOS it additionally covers the iOS configuration a build needs and the build job cannot check (Step 5a). This skill is a pure orchestrator — it resolves state, calls the two binding scripts, /t1k:plane bind, the engine’s Jenkins skill, and the read-only iOS checker. It re-implements no binding logic of its own, and no Jenkins config logic either — that lives in t1k-jenkins-job.
When to use
Section titled “When to use”- “Set up this project”, “onboard this repo”, “link this repo to services”, “bind a Discord channel for this repo”, “set up the Jenkins build job for this repo”.
- After a fresh clone, before the first
/t1k:cook, to wire the repo to Plane, Discord, and Jenkins in one pass.
When NOT to use
Section titled “When NOT to use”- The repo has no git remote — there is nothing to bind to; stop with a clear message.
- A one-off for a single service —
/t1k:planefor Plane, thediscord-mcptools for one channel,/t1k:jenkins-unityor/t1k:jenkins-cocosfor one Jenkins job.
Script root — global-only installs are first-class
Section titled “Script root — global-only installs are first-class”theonekit-core is a global-scope kit, so the scripts below normally live in $HOME/.claude/scripts/, not in the repo. Resolve the root once and use it for every command in this skill:
T1K_DIR=$(for d in "$HOME/.claude" ".claude"; do [ -f "$d/scripts/t1k-service-binding.cjs" ] && echo "$d" && break; done)[ -n "$T1K_DIR" ] || { echo "t1k scripts not installed (run t1k modules add t1k-onboarding)"; exit 1; }A state: "skip" from bind / set-thread is NOT a bind. The bindings file is <repo>/.claude/service-bindings.json; with no project .claude/ (global-only install) the script skips by contract. Report not bound: <reason> and mkdir <repo-root>/.claude before retrying — never report a skipped write as bound.
Service table — and the deliberate decision to keep it here
Section titled “Service table — and the deliberate decision to keep it here”| Service | Status command | Bind |
|---|---|---|
| Plane | bun "$T1K_DIR/scripts/t1k-plane-binding.cjs" status | /t1k:plane bind |
| Discord | bun "$T1K_DIR/scripts/t1k-service-binding.cjs" status --service discord | bun "$T1K_DIR/scripts/t1k-service-binding.cjs" bind --service discord … |
| Jenkins | none of its own — engine detection, then the engine’s Jenkins skill | /t1k:jenkins-unity or /t1k:jenkins-cocos |
| iOS config (Unity only) | bun "$T1K_DIR/scripts/t1k-unity-ios-check.cjs" --project <repo-root> | not a binding — references/unity-ios-config.md |
The table stays in the body — the precondition is a loader, not a service count. v1 justified keeping this table here “because there are only two services” and said to split it into a
t1k-services-onboarding.jsonfragment when a third arrived. That premise was wrong. The third service has now arrived, and splitting is still the wrong move:t1k-services-onboarding.jsonhas no loader anywhere in the kit — a grep forservices-onboarding/servicesOnboardingacross every.cjs/.js/.tsreturns zero hits. A fragment nothing reads is a file that changes no behaviour while looking like configuration; seerules/wired-not-just-present.md. The real threshold is “a reader for the fragment ships” — restructure then, and only then. Do not “fix” this ahead of that threshold.
CLI surface — t1k-service-binding.cjs
Section titled “CLI surface — t1k-service-binding.cjs”bun t1k-service-binding.cjs <status|bind|unbind|optout|get|set-thread> [flags] --service <name> required on every command (v1 accepts only: discord) --channel-id <id> bind --channel-name <name> bind (optional) --guild-id <id> bind (optional) --job <name> --thread-id <id> --source <user|created> set-thread- JSON on stdout (one object, always valid); diagnostics on stderr.
- exit 0 on skip (no
.claude/, no git repo, not yet bound). exit 1 only on a usage error. A non-zero exit is never used just because a service is unbound. status→{ok, state, service, repoKey, binding|null};state ∈ unset | bound | opted-out | error.unbinddeletes the entry (→unset);optoutwritestracked:false(durable). Two distinct commands — never conflate them.- The JSON shape is pinned by
.claude/scripts/service-bindings.schema.json(SSOT). Both this skill and the script write only through the script. - This orchestrator calls
status,bind, andset-thread.unbind,optout, andgetare manual tools.
status → action: bound → skip. opted-out → respect (durable tracked:false). error → report, never write.
0 Detect git remote → owner/repo. No remote → stop, state why.1 Preflight MCP presence: plane + discord-mcp. Vault access (required for every user): node hooks/doctor-check-96-vault-access.cjs FAIL → run its printed Fix (`gh auth login`, unset a github_pat_ GITHUB_TOKEN, update the CLI), then continue; see t1k-vault2 Plane t1k-plane-binding.cjs status bound+tracked → skip · unset → /t1k:plane bind · opted-out → respect3 Discord t1k-service-binding.cjs status --service discord unset → AskUserQuestion (channel id) · bind only AFTER verification channel must be CREATED → references/discord-channel.md FIRST (synced permissions + the view gate), then bind · create-then-verify-then-bind4 Threads only if Jenkins will run: one thread per job, per references/discord-thread.md write each via set-thread --source created BEFORE creating its job5a iOS config Unity + iOS target ONLY. BEFORE 5: run the read-only checker, report per step, apply nothing without confirmation. references/unity-ios-config.md.5 Jenkins detect engine → delegate /t1k:jenkins-unity or /t1k:jenkins-cocos passes the bundle id / team id resolved in 5a — never asks for them again thread ids are NOT passed: apply each after create via jenkins-job.cjs update --set6 Report table: service | state | evidence, naming every skip and its reasonStep 2 — Plane
Section titled “Step 2 — Plane”Read status. bound with tracked (or tracked absent) → skip; use status.binding.workspaceSlug on later mcp__plane__* calls. opted-out → respect, do not re-prompt. unset → run /t1k:plane bind (the plane skill resolves workspace + project/module and persists). Plane is touched only via t1k-plane-binding.cjs status and /t1k:plane bind — this skill never reads or writes plane-binding.json.
Step 3 — Discord
Section titled “Step 3 — Discord”Read t1k-service-binding.cjs status --service discord. bound (tracked) → skip. opted-out → respect. unset → AskUserQuestion for the channel id — a 17–20 digit snowflake, from the user or a channel listing, never guessed. Thread ids are not asked for here; Step 4 owns them. Verify the channel through the live discord-mcp BEFORE any bind. An unverified id is never written.
When the channel does not exist yet, references/discord-channel.md runs FIRST. It is the
SSOT for creating a channel: the permission-synced-with-the-category rule, the MANAGE_ROLES
preflight, seeding the parent’s overwrites at creation, and the view gate that must pass before the
bind. Order is create → verify → bind — a channel created bare is invisible to the very people
tagUserId names, and the step is not finished until the gate says they can see it. Asking the user
for an id is the unset path; creating the channel is this one.
| discord-mcp state | The skill does |
|---|---|
| Connected | Verify the channel via the MCP, then bind --service discord --channel-id … [--channel-name …] [--guild-id …]. A human-supplied thread id lands via set-thread --source user; a thread this skill created lands via --source created (Step 4). |
| Needs authentication | Run mcp__discord-mcp__authenticate, hand the user the link; after complete_authentication, re-verify, then bind. |
| Auth failed / user declined mid-way | Discord → pending-auth, write nothing (no file is created). Plane still finishes. The report states the re-run command. |
| MCP absent from session | Discord → pending-auth (nothing written) plus the registration command: ~/.claude/skills/t1k-mcp-management/scripts/install-discord-mcp.sh. |
Step 4 — Threads
Section titled “Step 4 — Threads”Runs only if Jenkins will run, and after Discord is bound — a thread needs a verified channel to live in. references/discord-thread.md is the SSOT for the procedure: channel-type branch, the create sequence, the read-back verification, the idempotency check, and --source created. Follow it; this section says only when to call it.
Create each thread BEFORE the job that consumes it, never after. The delegate creates every job with an empty PARAM_DISCORD_THREAD_ID, and an empty one still verifies green — the parameter is a plain string, so nothing rejects it — so a job whose id is never applied is silently broken. Creating the thread first means a Discord failure stops the run before any job exists (Job/Delete is a separate Jenkins permission you may not hold, so debris cannot be cleaned up), and the id is ready for the Step 5 update.
Runs inline in the main session — never in a fork: a routed fork has no MCP servers, so the create call cannot succeed there (references/discord-thread.md § “The hard constraint”).
Step 5a — Unity iOS config
Section titled “Step 5a — Unity iOS config”Runs only when both hold: the engine is Unity, AND the project’s target set includes iOS. Say
which of the two failed and continue, rather than running it hopefully — every step below is
iOS-specific, and on an Android-only project they would all report missing and mean nothing.
Order matters: 5a runs BEFORE Step 5. It is where the bundle id and the signing team id get settled, and Step 5’s Jenkins delegation consumes them. Ask for them once, here, and pass them through — never re-ask in Step 5.
references/unity-ios-config.md is the SSOT for the procedure: the two halves (checker →
facts, this skill → judgment), the per-step table with the exact fix for each status, and the two
steps that are human handoffs. This section says only when to call it, and what it must not do.
Run the checker read-only:
bun "$T1K_DIR/scripts/t1k-unity-ios-check.cjs" --project <repo-root> [--team-id <id>]Then, per step, in this order — the invariant is references/unity-ios-config.md § “The
invariant that governs every step”: show the fact → state the exact edit and file →
AskUserQuestion → apply only on confirmation → re-run the checker and report the new status.
Never write a Unity asset silently. ProjectSettings.asset, *.asset, and
Packages/manifest.json are re-serialized by the Editor; an unconfirmed edit can be dropped or
persisted wrong. The user may always prefer to make the change in the Editor, or defer it.
Two steps are human handoffs, not edits (steps 1 and 9): the Firebase plist and the Unity
Services Tangle files can only be produced from a console the skill cannot reach. Hand over the
console path, then re-check after — the step is not done until the re-run says ok.
Status semantics: ok → nothing to do · skip → not applicable, reason in the evidence —
never a defect · unknown → an input this run did not get (usually --team-id), so report it and
ask only if the user wants it resolved. A mismatch on one ad unit is never collapsed into a
count — report each non-ok step as its own row.
Step 5 — Jenkins
Section titled “Step 5 — Jenkins”Detect the engine; never guess it, and never infer it from the conversation. Assets/ + ProjectSettings/ProjectVersion.txt → Unity. assets/ + settings/v2/packages/ → Cocos. Neither reading is unambiguous → AskUserQuestion.
| Engine | Delegate |
|---|---|
| Unity | /t1k:jenkins-unity |
| Cocos | /t1k:jenkins-cocos |
The delegate is not handed the thread id: both Jenkins skills always render PARAM_DISCORD_THREAD_ID empty, and their verifier fails a job that carries a value it was not told to expect (t1k-jenkins-unity/references/incident-history.md #28, t1k-jenkins-cocos/SKILL.md). After the delegate has created and verified a job, this skill applies that job’s Step 4 thread id through the config owner, t1k-jenkins-job (jenkins-job.cjs update <folder> <job> --set PARAM_DISCORD_THREAD_ID=<id>), then re-checks it with verify <folder> <job> --expect PARAM_DISCORD_THREAD_ID=<id>. This skill still writes no Jenkins config of its own.
If the user declines Jenkins, the step is skipped and reported, and the skill still finishes Plane + Discord (invariant 2).
Step 6 — Report
Section titled “Step 6 — Report”One table: service | state | evidence, and for every skip the reason (already-bound, opted-out, pending-auth, absent). The report is also what a second run prints unchanged.
For a Unity + iOS project the table carries one row per iOS-config step, not one row for the
step as a whole — references/unity-ios-config.md § “Reporting” has the shape. Each non-ok row
names its own file and key, so a single mismatch cannot hide behind a configured-count.
Invariants
Section titled “Invariants”- Never write an unverified
channelId. Verification fails → no file is created at all; the bind is skipped and reported. - The skill never stops half-way. Worst case it skips exactly one service and finishes all the rest.
- It never reads or writes
plane-binding.json. Plane is touched only viat1k-plane-binding.cjs statusand/t1k:plane bind. - A second run is a complete no-op — every service already
bound/opted-out, and every job’s thread already present in the binding, so it only prints the report. - Threads are created only through
references/discord-thread.md. That file owns the procedure — the channel-type branch, the sequence, the read-back verification, the idempotency check. This skill supplies only the decision to call it. - A thread is never created for a job that already has one in the binding. Read
threads[<job>]first; present → reuse it. A re-run creates nothing. - The skill never writes Jenkins
config.xmlitself. It delegates to/t1k:jenkins-unityor/t1k:jenkins-cocos, and the config itself belongs tot1k-jenkins-job. - No Unity asset is written without a confirmation. Step 5a shows the fact, names the file, and asks — for
ProjectSettings.asset, any*.asset, andPackages/manifest.jsonalike. The Editor re-serializes all of them, so an unconfirmed edit is not just impolite, it is unreliable. - Steps 1 and 9 of 5a are human handoffs re-checked after. The Firebase plist and the Unity Services Tangle files are produced outside the repo; the skill verifies them and re-runs the checker, and never fabricates a substitute file.
- The signing team id is never hardcoded. It comes from
UnityIOS/BaseJob’sPARAM_SIGNING_TEAM_IDdescription (viat1k-jenkins-unity/references/ios-signing.md), passed to the checker with--team-id. Absent → the step reportsunknown, never a guessed id. - A channel this skill creates is never left unsynced. Its permissions end equal to its category’s, and the per-human
view_channelgate inreferences/discord-channel.mdpasses before the bind — the owners named bytagUserIdmust be able to see the channel they were handed. An unrepairable permission gap stops the step with zero writes and asks; it never resolves as a silently invisible channel.
Hard rules
Section titled “Hard rules”service-bindings.jsonis committed in consumer repos — channel ids are not secrets and the team shares one binding. It is shipped by no kit, sot1k modules updatecannot clobber it, exactly likeplane-binding.json.