AGENT SKILL

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

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.

  1. 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_id collision 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).

  2. 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 (--role overrides). Every proposed resource carries evidence lines by source: role-default (conservative per-role base), detection (only on a confident outcome — 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): a kind: skill entry with detection: and engine-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's warnings[] and a gds-engine-godot-4: note; a pin that cannot be checked (no readable project.godot, a malformed global.json) is still proposed and carries an engine 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.

  3. 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 resources list). No payload set → do NOT record; end blocked naming 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: mcp entry with detection: and kb: kb/engine-mcp-godot.md evidence, status configured (the project's .mcp.json already has it) or not-configured. It is never part of --resources; only after an explicit yes for that entry (attended), or an explicit mcp name 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.json parseable 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/--resources in one call, both are checked before either is written. Detection and propose never 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).

  4. 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 under planning.jira and planning.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-id or --owner-email from the payload's owner_account_id / owner_email when 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 as blocked, never ask for a token. Relay the setup's status block as this skill's — its status and reason unchanged, its artifacts added to (deduplicated with) the artifacts onboard itself wrote this run (kb/, vault links, the registry entry), with intent set to tk-studio-onboard (the core's block says tk-studio-plan-sync): complete when every step was created or found; partial with its owner_steps[] shown verbatim and in order — the numbered steps the API could not do on the free plan — never reworded and never reported complete; blocked with its reason. A rerun is idempotent: what exists is recognised by key and named in found[].

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[] and created[], then, on partial, its numbered owner steps verbatim.

  • Headless: end with the status block — complete after a successful record (or a clean standup-only run with no confirmation requested), partial when tracking setup ended partial (its reason carries the owner's numbered steps verbatim, artifacts the config it wrote plus what onboard itself wrote), blocked on 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_set and happens only on explicit confirmation — a proposal is never auto-recorded (NFR6).
  • Registry writes go through registry.py with --writer onboard (AD-20 single-writer); this skill never edits projects.yaml directly.
  • Tracked-config writes are classification-checked (AD-3) — a refusal is a blocked status, not a workaround.
  • Tracking setup goes through plansync.py setup only (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

thkennedy
thkennedy/tk-studio

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.

★ 0
thkennedy
thkennedy/tk-studio

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.

★ 0
thkennedy
thkennedy/tk-studio

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.

★ 0
thkennedy
thkennedy/tk-studio

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".

★ 0
thkennedy
thkennedy/tk-studio

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".

★ 0
thkennedy
thkennedy/tk-studio

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.

★ 0