tk-studio-onboard
Onboard a project into the studio — stand up the taxonomy (store, config, registry, kb, vault window), then propose a role × project working set with evidence and record it only on explicit confirmation. Use when the user says "onboard this project", "tk onboard", "set up the studio here", or "recommend a working set".
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- tk-studio-onboard
- description
- Onboard a project into the studio — stand up the taxonomy (store, config, registry, kb, vault window), then propose a role × project working set with evidence and record it only on explicit confirmation. Use when the user says "onboard this project", "tk onboard", "set up the studio here", or "recommend a working set".
02 资源文件 1
- 其他customize.toml516 B
03 SKILL.md 正文
tk-studio-onboard
Onboarding lands the Taxonomy (Epic 2) and turns the Recommendation inputs
(tk-studio-detect) into a confirmed, recorded working set (AD-17). Detection
never guesses; recording happens only on the operator's explicit confirmation.
Flow (both modes)
Run each step through the plugin root; all are idempotent.
-
Taxonomy standup (skips cleanly whatever already exists):
uv run "${CLAUDE_PLUGIN_ROOT}/lib/store.py" standup uv run "${CLAUDE_PLUGIN_ROOT}/lib/config.py" standup --directory <project-root> [--vcs git|perforce] [--project-id ID] uv run "${CLAUDE_PLUGIN_ROOT}/lib/registry.py" register --directory <project-root> --writer onboard [--project-id ID] uv run "${CLAUDE_PLUGIN_ROOT}/lib/kb.py" standup --directory <project-root> uv run "${CLAUDE_PLUGIN_ROOT}/lib/vault.py" link --project-id <id>A
project_idcollision fails registration and demands an explicit id (AD-20) — surface it, never invent one. No vault configured → linking skips cleanly (the vault is a view, never a dependency).Attended, after standup: if the store config has no
display_name, ask how the operator wants the studio to address them and record the answer:uv run "${CLAUDE_PLUGIN_ROOT}/lib/store.py" set-name "<name>""Use my assistant preference" records the literal
assistant-preference— the fallback, chosen, so no surface asks again. Headless never prompts and skips this (address is presentation-only). -
Propose (read-only — this IS the dry run; it shows the full plan and writes nothing):
uv run "${CLAUDE_PLUGIN_ROOT}/lib/recommend.py" propose --directory <project-root>Role resolves from the per-user store (
--roleoverrides). Every proposed resource carries evidence lines by source:role-default(conservative per-role base),detection(only on aconfidentoutcome — type, score, fired markers),user-authored(the project's own resources, first-class). On an ask outcome (ambiguous — ask/unknown — ask) the proposal carries no detection-derived entries and a note saying so.A confident game profile can also propose a plugin-shipped engine skill (
game-godot→gds-engine-godot-4, Story 34.4): akind: skillentry withdetection:andengine-pin:evidence (the project's pinned engine version against the skill's supported range). A pin outside the range, a features/SDK disagreement or an unreadable pin adds the entry'swarnings[]and agds-engine-godot-4:note; a pin that cannot be checked (no readableproject.godot, a malformedglobal.json) is still proposed and carries anengine pin not checked: <reason>warning; attended, show that warning to the operator before they confirm. Headless onboarding records nothing new: it records only what the payload confirms. -
Confirm, then record:
-
Attended: present the proposal with its evidence; the operator edits/accepts the set. On an ask outcome, ask what the project is first and re-propose. Only after an explicit yes:
uv run "${CLAUDE_PLUGIN_ROOT}/lib/recommend.py" record --directory <project-root> --role <role> --resources <a,b,c> -
Headless: confirmation must arrive in the payload (an explicit
resourceslist). No payload set → do NOT record; endblockednaming the missing confirmation (AD-11 — never prompt, never guess). -
The engine MCP (Story 34.5): a confident game profile can also propose its engine MCP — a
kind: mcpentry withdetection:andkb: kb/engine-mcp-godot.mdevidence, statusconfigured(the project's.mcp.jsonalready has it) ornot-configured. It is never part of--resources; only after an explicit yes for that entry (attended), or an explicitmcpname in the payload (headless), record it — the one write of the project's.mcp.json:uv run "${CLAUDE_PLUGIN_ROOT}/lib/recommend.py" record --directory <project-root> --mcp <name>It merges
mcpServers.<name>with the URL and bearer as${TK_ENGINE_MCP_URL:-}/${TK_ENGINE_MCP_BEARER:-}(never a value; the empty default keeps.mcp.jsonparseable in every session where the supervisor set neither), rewrites an entry in the earlier${VAR}form, leaves every other server untouched, and refuses a name no profile suggests or a malformed.mcp.json(exit 2). Given with--role/--resourcesin one call, both are checked before either is written. Detection andproposenever write it.
Recording lands in tracked config
working_set.<role>— a role-keyed map: this role's entry replaced, every other role's entry and every comment preserved byte-for-byte. Re-recording an identical set is a no-op (idempotent re-onboarding). -
-
Set up tracking (optional — only when asked: attended, the operator asks for it; headless, the payload carries
tracking: true). The planning adapter creates the project's Jira project, its statuses and the "Needs you" filter, and the linked Confluence space with its design-page folders, from the studio template, and records the keys and ids underplanning.jiraandplanning.confluence(AD-4: this skill never calls Atlassian itself):uv run "${CLAUDE_PLUGIN_ROOT}/lib/plansync.py" setup --directory <project-root> [--dry-run] [--owner-account-id <id> | --owner-email <owner email>]Pass
--owner-account-idor--owner-emailfrom the payload'sowner_account_id/owner_emailwhen given. It uses the agent seat's variables only —TK_ATLASSIAN_SITE(first setup),TK_ATLASSIAN_AGENT_EMAIL,TK_ATLASSIAN_AGENT_TOKEN,TK_ATLASSIAN_AGENT_CONFLUENCE_TOKEN,TK_ATLASSIAN_CLOUD_ID— and refuses with each absent one named (and on an unregistered project) before any call: relay that refusal asblocked, never ask for a token. Relay the setup's status block as this skill's — itsstatusandreasonunchanged, itsartifactsadded to (deduplicated with) the artifacts onboard itself wrote this run (kb/, vault links, the registry entry), withintentset totk-studio-onboard(the core's block saystk-studio-plan-sync):completewhen every step was created or found;partialwith itsowner_steps[]shown verbatim and in order — the numbered steps the API could not do on the free plan — never reworded and never reportedcomplete;blockedwith itsreason. A rerun is idempotent: what exists is recognised by key and named infound[].
Report
-
Attended: one line per standup step (created vs already-present), the proposal table with evidence, then the recorded outcome.
-
Attended, tracking: the setup's
found[]andcreated[], then, onpartial, its numbered owner steps verbatim. -
Headless: end with the status block —
completeafter a successful record (or a clean standup-only run with no confirmation requested),partialwhen tracking setup endedpartial(itsreasoncarries the owner's numbered steps verbatim,artifactsthe config it wrote plus what onboard itself wrote),blockedon collision, classification refusal, missing confirmation, or a tracking-setup refusal:{"status": "complete", "intent": "tk-studio-onboard", "artifacts": [".tk-studio/config.yaml"], "reason": null}
If the deterministic core is unrunnable — a tool call denied by permissions, uv/python unavailable — end blocked with the status block naming the unrunnable core as reason: never a question, never a headless run that ends without the block (AD-11).
Rules
- Recording is the only write to
working_setand happens only on explicit confirmation — a proposal is never auto-recorded (NFR6). - Registry writes go through
registry.pywith--writer onboard(AD-20 single-writer); this skill never editsprojects.yamldirectly. - Tracked-config writes are classification-checked (AD-3) — a refusal is a
blockedstatus, not a workaround. - Tracking setup goes through
plansync.py setuponly (AD-4); the owner's token is never read and no token lands in any file (AD-3). - All paths resolve through
${CLAUDE_PLUGIN_ROOT}.
04 同仓库更多 Skills
tk-studio-track
Tracking verbs on the bound Jira project — `block` moves a story the loop cannot progress, and each dependent story, to "Blocked - Awaiting User" with a comment that @mentions the owner (or, with `--engagement`, one engagement's questions issue, which `close` later moves to "Done"); `reply` posts the owner's answer (or "Done.") with the owner's host-only token and moves the issue to "Block Resolved"; `validate` checks that resolution and passes the issue back to work or re-blocks it with a follow-up. Use when the user says "block this story", "tk track block", "put it in the owner's inbox", "reply to the blocked issue", "validate the resolution", or a supervisor or engagement payload names this skill.
tk-studio-session
Session discipline as a surface — land a boundary handoff (optionally carrying knowledge deltas) and end the session, or resume a fresh session from a run workspace alone. Use when the user says "hand off this run", "tk session", "resume the run", or a boundary/budget trigger says the session must split.
tk-studio-research
Run a chartered research pass — survey the topics a charter scopes, grade every finding by evidence, land the findings in the run workspace, and emit observation events for recommendation-worthy ones. Use when the user says "run the ecosystem watch", "tk research", or a research job's invoke-skill directive names this skill.
tk-studio-report
One-verb human defect report — "the skill did the wrong thing" — recorded as a report event in the local measurement ledger. Use when the user says "tk report", "report a defect", "that skill misbehaved", or "log a studio issue".
tk-studio-playable-judge
The playable-verify leg's screenshot judge (Story 34.3) — reads only a playable run's report.json and its frames, answers the fixed rubric (scene loaded, player visible and framed, no magenta or error overlay, HUD reads, the named moments shown) with pass or fail and findings each naming a frame and a rubric line. Driven headless by the supervisor's host leg on the project's sandbox tier; use when the payload names a playable `media` folder, or the user says "judge the playable frames".
tk-studio-plan-sync
Planning adapter — canonicalize BMad-native planning artifacts (normalize pass, sole id authority) and sync them with the bound planning backend. Use when the user says "sync the plan", "normalize planning artifacts", "tk plan sync", or after stock BMad planning flows produce or change epics/stories.