TK Studio

An AI dev-studio layer over a pinned, unforked BMad Method base — shipped as a Claude Code plugin that the tk-studio installer writes into your skills folder.

tk-studio adds the discipline BMad leaves to the team: version-pinned installs that stay in lockstep across machines, a strict data taxonomy (every write lands in a classified home), a canonical planning layer with backend adapters (Backlog.md, Jira), role-aware orchestration, unattended job execution behind a published driver contract, and a self-measurement loop that turns the studio's own telemetry into reviewed fixes.

How this relates to BMad Method

tk-studio is built on BMad, never a fork of it (AD-1, the zero-fork line):

• The upstream base — BMAD-METHOD (docs, bmad-method on npm) — is installed by running the upstream installer at a committed pin: npx bmad-method@<pin> install …, driven by bmad.lock. BMad code is never vendored, patched, or forked.
• Stock BMad skills (PRD, architecture, stories, dev-story, retros…) run untouched. The studio sequences around them — for example the planning adapter canonicalizes the artifacts they produce, without ever editing BMad itself.
• Base upgrades are a reviewed motion: tk-studio-base-update bumps the pin, reruns the upstream installer, and opens an integration PR so the upstream diff gets human review without owning a fork.

The pinned module set (external modules version independently of core):

For what BMad itself does — agents, workflows, the method — start with the BMad documentation. This README covers only what the studio adds on top.

Prerequisites

• Claude Code ≥ 2.1.223 (verified at 2.1.226) — CLI, desktop, or IDE
• Node.js 20+ — npx runs the upstream BMad installer
• uv — every studio script is stdlib-only Python 3.12+ run via uv run (uv fetches the interpreter if needed)
• git; the gh CLI authenticated (measurement pushes open PRs)
• Optional: Obsidian — the studio can maintain a vault window into each project's knowledge and planning folders

No admin rights are required on Windows; the store uses directory junctions.

Quick start

Bootstrap (one command)

One script installs the pinned uv and the small self-updating tk-studio meta-CLI, puts only the studio's bin folder on your PATH and turns on long paths for git. It never clones anything; re-running it is the update. The meta-CLI then installs and updates the apps the roster ships (tk-studio install, tk-studio update, tk-studio status).

Windows (PowerShell):

irm https://raw.githubusercontent.com/thkennedy/tk-studio/main/tools/installer/install.ps1 | iex

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/thkennedy/tk-studio/main/tools/installer/install.sh | sh

Published SHA-256 of each script:

To verify before running, download, check, then run:

irm https://raw.githubusercontent.com/thkennedy/tk-studio/main/tools/installer/install.ps1 -OutFile install.ps1
(Get-FileHash -Algorithm SHA256 install.ps1).Hash   # must equal the install.ps1 row above
powershell -ExecutionPolicy Bypass -File .\install.ps1   # Windows PowerShell 5.1 (stock); pwsh works too

curl -fsSLO https://raw.githubusercontent.com/thkennedy/tk-studio/main/tools/installer/install.sh
echo "f3bb442100401316e874d9b2c3fddf5f9670a258af575f57bad13ef4c81d672c  install.sh" | sha256sum -c -        # Linux
echo "f3bb442100401316e874d9b2c3fddf5f9670a258af575f57bad13ef4c81d672c  install.sh" | shasum -a 256 -c -    # macOS (no sha256sum)
sh install.sh

Both take a channel (default stable) and a roster override. With the one-liners, pass them through the environment, since iex takes no arguments:

$env:TK_STUDIO_CHANNEL = 'latest'; $env:TK_STUDIO_ROSTER = '<path or https URL>'
irm https://raw.githubusercontent.com/thkennedy/tk-studio/main/tools/installer/install.ps1 | iex

curl -fsSL https://raw.githubusercontent.com/thkennedy/tk-studio/main/tools/installer/install.sh | TK_STUDIO_CHANNEL=latest sh
# or: ... | sh -s -- --channel latest --roster <path or https URL>

A downloaded script also takes -Channel / -Roster (powershell -ExecutionPolicy Bypass -File .\install.ps1 -Channel latest) or --channel / --roster. Through iex a refusal throws <Name>: <detail> and leaves the window open; run as a file it exits 1. Until the first cli--v release is recorded in the roster, the bootstrap stops with CliNotShipped.

1. Install the plugin

With the meta-CLI on your PATH (bootstrap above), one command installs the plugin and the apps the roster ships:

tk-studio install

Until the first cli--v release is recorded in the roster, the bootstrap stops with CliNotShipped; meanwhile run the meta-CLI from a checkout, as shown under "Developers who clone" below (uv run --project tools/installer/cli tk-studio install).

The plugin lands at ~/.claude/skills/tk-studio/ ($CLAUDE_CONFIG_DIR/skills/tk-studio/ when that is set), written from the roster's SHA-256-verified release zip. Claude Code loads it in place as tk-studio@skills-dir, with no marketplace and no claude plugin install. The install also removes any user-scope marketplace copy of tk-studio, because a same-named marketplace copy shadows the skills-dir folder.

Updating later: tk-studio update brings every component to the channel roster's version; tk-studio status shows installed vs roster. Engine sandboxes do not see the host folder live: after tk-studio install or update on the host, run sbx skills import --force so the sandboxes' shared skills store gets the new copy (kb/agent-pc-setup-runbook.md §3.5).

Deprecation watch (skills-dir plugins): this delivery rests on Claude Code loading a plugin folder from the skills directory. Where to look for a change: code.claude.com/docs/en/plugins/create ("Develop without a marketplace"), code.claude.com/docs/en/plugins/loading (the name-conflict order), and the Claude Code CHANGELOG (grep skills-dir). Status: none found as of 2026-10-15.

Moving from the marketplace install: tk-studio install uninstalls only user-scope marketplace copies; a project- or local-scope copy (the old claude plugin install tk-studio@tk-studio --scope project) is only reported, and it shadows the skills-dir folder. From that project's checkout run claude plugin uninstall tk-studio@tk-studio --scope project (--scope local for a local-scope copy), then tk-studio install, then sbx skills import --force for engine sandboxes. claude plugin list should then show tk-studio@skills-dir and no tk-studio@tk-studio; check it there, because "tk activate" sees only user-scope marketplace copies, not project- or local-scope ones. If "tk activate" still reports the plugin plane shadowed, run the fix it prints.

Air-gapped / offline machines: the skills-dir write from a downloaded release zip is in kb/offline-install-runbook.md.

Developers who clone this repo to work on the studio itself:

git clone https://github.com/thkennedy/tk-studio.git
tk-studio install --link <path-to-checkout>

Until the first cli--v release is recorded in the roster the bootstrap stops with CliNotShipped, so from a checkout run the meta-CLI as uv run --project tools/installer/cli tk-studio install --link <path-to-checkout>. --link points ~/.claude/skills/tk-studio at <checkout>/plugins/tk-studio (a junction on Windows, a symlink elsewhere), so your edits load in the next session. Then run sbx skills import --force for engine sandboxes: their store is a copy, also of a linked folder. It links the plugin only; it installs no other app. A later plain tk-studio install or update replaces the link with the release zip's folder; re-run install --link <checkout> (then sbx skills import --force) to get it back. The repo's .claude-plugin/marketplace.json remains as a developer catalog, for browsing it or pinning a tag in a dev checkout:

claude plugin marketplace add thkennedy/tk-studio#tk-studio--v<X.Y.Z>

Every tk-studio install or update runs claude plugin marketplace remove tk-studio, so this catalog is gone after the next install or update; re-add it afterwards if you want it. Never install tk-studio@tk-studio from it alongside the folder: a marketplace copy named tk-studio shadows the skills-dir folder, so use install --link instead.

2. Verify with the drift check

In a Claude Code session:

"activate the studio" (or tk activate, "studio status", "check for drift")

Activation cross-checks four planes — BMad base vs the bmad.lock pin, the skills-dir plugin folder vs the channel's roster, per-user store health, vault window — and reports loudly with exact fix commands. It is read-only: it names fixes, never applies them. On a fresh machine expect the store plane to guide you through standup.

Outside a session, tk-studio doctor reports the plugin folder's mode (written or linked) and runs the installer's smoke checks, one line each with its fix. It is read-only too.

3. Install the BMad base (per project)

In the project you want to work in:

"tk install" (or "install the base")

This runs the upstream installer non-interactively at the committed pin and verifies the result (verify-at-pin). Deterministic, idempotent, zero forks.

4. Onboard your project

"onboard this project" (or tk onboard, "set up the studio here")

Onboarding stands up the taxonomy — per-user store ~/.tk-studio/, tracked project config .tk-studio/config.yaml, the project registry entry, kb/ with its ranked index, the Obsidian vault window if configured — then proposes a role × project working set with evidence (detected project type, role defaults, your own user-authored resources) and records it only on your explicit confirmation. It never guesses.

5. Enter the studio

"enter the studio" (or tk studio; "convene the council" adds the persona shell)

The orchestrator resolves who you are (role, from your store) and what this project needs (your role's confirmed working set) and offers routes by name — stock BMad skills included. developer gets execution framing (dev-story, code review, sprint status); direction-giver gets shaping/delegation/synthesis framing. Thin role agents (tk-studio:developer, tk-studio:direction-giver) enter with the role pre-fixed.

That's the loop: activate → install → onboard → enter, then work through BMad as usual with the studio keeping everything pinned, classified, and measured.

Feature reference

All 18 studio surfaces, grouped by pillar. Every one runs attended and headless with identical behavior (AD-11); headless runs end with a JSON status block and never prompt. Say the trigger phrase in a Claude Code session to use one.

Lockstep — pinned installs and drift

Known upstream behavior: through core 6.10.0 the quick-update ignored --pin and floated stable modules to the latest non-major tag (fixed in 6.11.0's installer, upstream #2680). A verify-at-pin failure right after an upstream release is still drift, not a studio bug — the fix is a pin-bump motion (see issues/ledger.md, ISS-003).

Project setup and recommendation

Orchestration and roles

Roles ship as configuration: v1 has developer and direction-giver (thin agent wrappers included). Working sets are per-role maps in tracked config — one role's confirmation never overwrites another's.

Planning

Planning backends are per-project bindings: bmad-files (fallback), backlog-md (local kanban projection — see kb/backlog-md-verified-behavior.md), jira (via API tokens, not OAuth — headless-safe). Backends are projections; the canonical files in _bmad-output/ are always authoritative.

Knowledge and research

Project knowledge lives in kb/ with an llms.txt-style ranked index as the agent entry point.

Sessions and unattended work

Execution-pipeline routing. Every leg of a bmad-loop run — the monitor session, its implementer / reviewer / consult subagents, the pre-dispatch seam check,