tk-studio-launch
Launch, inspect, or stop the execution substrate (bmad-loop) for one project epic through the studio — distill the epic's SPEC, bootstrap the first story's task manifest at the planner tier, then start the engine detached with a pre-minted run id. Use when the user says "launch epic N", "tk launch", "start the run for this epic", "run status", "stop the run", or a `run-epic` job's invoke-skill directive names this skill.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- tk-studio-launch
- description
- Launch, inspect, or stop the execution substrate (bmad-loop) for one project epic through the studio — distill the epic's SPEC, bootstrap the first story's task manifest at the planner tier, then start the engine detached with a pre-minted run id. Use when the user says "launch epic N", "tk launch", "start the run for this epic", "run status", "stop the run", or a `run-epic` job's invoke-skill directive names this skill.
02 资源文件 1
- 其他customize.toml6.5 KB
03 SKILL.md 正文
tk-studio-launch
The studio's only way to start a run (studio pipeline decision 5: driver →
orchestrator → substrate). A conformant driver — the studio supervisor, Hermes
submitting to it, or direct invocation (driver contract §1) — runs a run-epic
job; the job wrapper invokes this surface; this surface does the planner-tier preparation and then
hands the epic to bmad-loop through lib/launch.py, the one deterministic
core that talks to the substrate (CLI only, never imported — AD-2). Ending
this session never ends the run: the engine is detached and owns the
checkout until it finishes, pauses, or is stopped.
Payload
verb—start(default) |status|stop|sweep(Story 35.7, therun-sweepjob type)directory— the project root (the nested root for a supervisor epic, never an engine worktree);lib/launch.pywalks--directoryup to the nearest folder holding.tk-studio/config.yaml(driver contract 0.1.22), so a nested project launches against its own root and storeepic— epic number (start; required unlessspec_folderis given)spec_folder?— project-relative epic spec folder; default_bmad-output/specs/spec-epic-<N>story?— the first story to bootstrap as<epic>-<story>(default: the epic's first story)bootstrap?—true(default) prepares SPEC.md, the epic's manifest and a plan for every story in it (list order) when absent;falserefuses insteadallow_budget_mismatch?—start:trueacknowledges abudget_mismatchand launches anyway (passed to the core as--allow-budget-mismatch); defaultfalserefuses itmax_bundles?—sweep: an integer ≥ 1 bounding the sweep's bundles (passed as--max-bundles; default: the policy's[sweep] max_bundles)run_id?—status/stop: the run to address (default: the live run)graceful?—stopafter the current unit instead of immediately
Behavior (both modes)
start
-
Resolve the inputs before anything runs (headless: a gap here ends
blocked, never a guess):<root>= theproject_rootprinted byuv run "${CLAUDE_PLUGIN_ROOT}/lib/config.py" root --directory <directory>(the payload'sdirectorywalked up to the nearest folder holding.tk-studio/config.yaml, driver contract 0.1.22). Every later<root>— in every step here and instatus/stop, which resolve it the same way first — is that resolved root, never the rawdirectory.<spec_folder>= the payload'sspec_folder, else_bmad-output/specs/spec-epic-<epic>(the core's--epicflag applies the same default); with neitherepicnorspec_folder, endblocked:spec folder unresolvable: neither epic nor spec_folder given.<story>= the payload'sstory, else the first entry under## Storiesin<root>/_bmad-output/implementation-artifacts/epic-<epic>-context.md(Story N.M: …→N-M), else the first### Story N.Mheading of the epic's section in<root>/_bmad-output/planning-artifacts/epics.md; with none of these, endblocked:first story unresolvable for epic <epic>.
-
Route the epic's first story — the model and effort every leg of the run uses (the session, its implementer / reviewer / consult subagents, the seam check, the review and triage stages, the supervisor pass), resolved runtime > the project's
.bmad-loop/routing.toml> the shipped measured defaults in this skill'scustomize.toml[pipeline](AD-14;kb/execution-pipeline-model-routing.mdcarries the numbers). Run:uv run "${CLAUDE_PLUGIN_ROOT}/lib/pipeline.py" apply --directory <root> --story <epic>-<story>It writes exactly the managed block in
.bmad-loop/policy.toml, the subagent-model line in the tracked Claude profile when the project has one, and.bmad-loop/routing.current.json; nothing else. Readwritesandunignored[]. A non-emptyunignored[]names a file this write would leave dirty in the tree — the engine's preflight refuses a dirty tree — so endblockednaming it (routing write not gitignored: <path>); never add the ignore line yourself in a headless run, and never launch around it. A refusal (ok: false— the policy is missing, the project's routing table is invalid) endsblockedwith itserrorverbatim: the route is never invented. Report the route's session / implementer / reviewers / consult models in the launch report. -
Readiness first, and never guess around a gap. Run:
uv run "${CLAUDE_PLUGIN_ROOT}/lib/launch.py" check --directory <root> --spec <spec_folder>Read
gaps[]. Gaps you may close in this session (only whenbootstrapis true): a missingSPEC.md(step 3) and an empty or missing task manifest (step 4). Story 35.2: the gapopen questionsrefuses the story the launch would start (the first manifest entry with nostories/<id>-*.mdatstatus: done) — one of its CAPs has a- CAP-N:line under SPEC.md## Open Questionsand no design note names that CAP or the story; its detail is<story id>: CAP-N has no design note — <question>(;between CAPs). This session never answers it (the planner's task planning notes it or escalates): endblockedwith the gap verbatim, every CAP named, before any dev session. A later story's un-noted CAP is never a gap. Every other gap — a live engine already on the checkout,bmad-loopnot installed, a failingbmad-loop validate(a dirty tree, a broken policy) — ends the runblockedwith the gap verbatim inreason. Never stop another run to make room; never clean a tree.Read
budgettoo: the core compares the engine's.bmad-loop/policy.tomllimits with.tk-studio/budget-bands.yamland names each limit the bands exceed inbudget.budget_mismatch[]({limit, policy, band, band_field, band_value}). A mismatch is not a gap —checkendspartialnaming it — but step 6'sstartrefuses it unless the payload carriesallow_budget_mismatch: true. Report it with both numbers; never edit its[limits]to clear it (the limit is the operator's machine-local setting; step 1's managed routing block andcheck's[verify] commandsreconciliation are the only launch writes to that file, except a run worktree's per-band cap). Story 38.7:max_followup_reviewsis compared per band (followup_reviews_max), each entry naming itspolicy_key(limits.by_band.<band>.max_followup_reviews, elselimits.max_followup_reviews); the operator's[limits.by_band]closes a band's mismatch. In a linked run worktree whose run takes one story,startitself writes the next story's by-band figure into[limits] max_followup_reviewsof that worktree's policy copy and answersfollowup_cap {band, figure, applied, reason}; a main checkout's policy is never written — reportfollowup_capas it reads.Read
verify_commandstoo (Story 33.5):checkreconciles the policy's[verify] commandsfrom the tracked list (.tk-studio/config.yamlengine.verify_commands, elseplugins/tk-studio/pipeline/verify-commands.toml) and reports it there and in theverify commandsrow:verify_commands.policyiswritten,unchanged,skipped (…)orrefused, and the row's detail readsadded <n> from <source>; kept <m> operator commands,unchanged (…),skipped (…)orrefused: … — fix it by hand; a refusal is a gap the session never closes by hand — endblockedwith it verbatim.Story 36.6: a tracked or unignored
.bmad-loop/policy.tomlwith commands to add is refused (nothing written,verify_commands.policy: "refused", a gap naming the file: add them by hand), and the row's engine-gate clause over a non-emptyengine.verify_commandsnames each running engine sandbox:sandbox <sb>: provisioned WITH_GODOT <ver>, orwarning: sandbox <sb> has no WITH_GODOT record; an engine.verify_commands gate there refuses, advisory. The advisoryrun rhythmrow names therun-epicinstance'sstop.after_stories(the supervisor arms the graceful stop from it and marks each story In Progress; never issue that stop by hand, except the command a refused arming's notifier line gives), or says the run goes to the epic's end when none is declared.The advisory rows never become a gap:
studio-pipeline plugin(present or absent) and, after it,engine sandbox(Story 33.3). That row reads the supervisor config's engine sandboxes (TK_SUPERVISOR_CONFIGjobs.*.sandbox), runssbx daemon statusand thensbx ls. A sandbox listed as running with no live supervisor pin record (<store>/sandboxes/<sandbox>.pin) readswarning: <sandbox> started outside the supervisor; the next pin restarts it— report it; never stop or start the sandbox yourself. A record is live only when it parses (supervisor_pidan integer,sincean ISO-8601 instant), itssupervisor_pidis a running process on this host, and itssinceis not older than the sandbox's start (host-now minussbx exec <sandbox> cat /proc/uptime, run only for a live pid) by more than a 120-second clock-skew tolerance. A record therefore reads as absent when it is unreadable, itssupervisor_pidis not a live process, or itssincepredates the sandbox's start beyond that tolerance — e.g. after a supervisor exit, a reboot or a manual stop/start; a kept pin under a live supervisor is still a legitimate pin (the record is removed only when a release stops the sandbox). An uptime that cannot be read leaves the pid verdict. Otherwise it readspinned by the supervisor,not running,no engine sandbox configured,sbx absentordaemon down. Right after it comesengine sandbox inodes, advisory too: for each running engine sandbox it runssbx exec <sandbox> df -i /and reads<n> free inodes on /,warning: <sandbox> has <n> free inodes on / (below 50000); the engine may fail to write, or<sandbox>: inodes unknownwhen the read fails or does not parse (several sandboxes are each named<sandbox>: …, joined by;); otherwise the samenot running,no engine sandbox configured,sbx absentordaemon down. Report a low reading; never prune or restart the sandbox yourself. After it comesplayable path(Story 34.2), advisory too: for a project whose tracked.tk-studio/config.yamldeclaresverify.engine, it readswarning: no $env:GODOT (unset or not an absolute file); playable runs refuse,warning: no display session; the <path> path needs the logged-in desktop(orwarning: display session unknown (<error>)) orready (<path>), where<path>is the ruled rendering path; any other project readsnot a game project (no verify.engine). Report it; never start the engine. After it comesstory plans(Story 35.2), advisory too:all <n> plannedorwithout a plan: <id>, …(manifest order; a plan is<spec_folder>/plans/<N>-<M>.md), plus; un-noted open questions: CAP-N (<id>), …for the stories after the next one. Report it. After it comesengine mcp(Story 35.4), advisory too, from the tracked.tk-studio/config.yaml:not configured (no engine.mcp), orverify-only filter <flag>; port <per-run|fixed <n> (one flagged run at a time)>; forwarder <…>; a host:port sandbox policy needs the fixed forwarder port (runbook)whenengine.mcp.startcarries the server's verify-only allowlist flag (engine.mcp.filter, default--exclude-domains), elsewarning: engine.mcp.start has no <flag>; the verify-only rule (kb/engine-mcp-godot.md) rests on the engine skill alone; port …; anengine.mcpthe pin'sparseEngineMcprefuses (port: 0with no{port}instart, a missing or non-integer port, an empty or multi-tokenfilter, …) readswarning: <the pin's reason, e.g. engine.mcp.start has no {port} for port: 0>; the pin refuses engine-mcp:no-config(the flagged run would endblocked); a config the lib's YAML subset refuses readswarning: .tk-studio/config.yaml unreadable by the lib's YAML subset (<err>); write engine.mcp in block style. Report it; the run proceeds, and never edit the project's config yourself.Relaunch. When
SPEC.mdand the manifest already exist (the epic launched before: stories alreadydone, the route already applied), steps 3 and 4 write nothing and step 5 makes no commit; go straight to step 6. A relaunch ends exactly as a fresh launch does — on the core's block (see Status block). -
Epic SPEC (when missing). Invoke the project's own
bmad-specskill by name, headless, on the epic: input = the epic's section of_bmad-output/planning-artifacts/epics.mdplus_bmad-output/implementation-artifacts/epic-<N>-context.mdwhen present; slugepic-<N>, so it lands at<spec_folder>/SPEC.md. Express mode: gaps becomeopen_questions[], never invented answers. The stock skill is invoked untouched (AD-4); if it is not installed in the project, endblockednaming it. -
The manifest and every story's plan (when the manifest is empty). The task-planning instructions are a project resource:
<root>/.bmad-loop/plugins/studio-pipeline/task-planning.md(the studio pipeline's gate plugin). Read it and follow it as "bootstrap story<epic>-<story>" — it transcribes the epic into<spec_folder>/stories.yamland writes<spec_folder>/plans/<N>-<M>.mdfor every entry in list order (<epic>-<story>first; a Code Map and the band each), then validates withbmad-loop validate. When the named (next) story has a SPEC open question (CAP-N) it cannot settle into a design note, it endsblockednaming the CAPs, never plans around it (step 6'scheckalso refuses it with the gapopen questions). A later story's unsettled CAP never blocks the launch: it stays un-noted, recorded as a Block If under that story's plan's Risks, named in thestory plansrow, re-checked at that story's boundary and refused bycheckonce that story is next. This is planner-tier work and the reason this surface's model default is the top tier. If the file is absent, endblockednaming it: this surface never invents a task breakdown of its own. -
Commit the bootstrap output — the one rule for the launch's own writes, so the dirty-tree refusal never fires on them. When steps 3–4 wrote files, commit exactly those files (
<spec_folder>/SPEC.md,<spec_folder>/.memlog.md,<spec_folder>/stories.yaml, every<spec_folder>/plans/<N>-<M>.mdstep 4 wrote, and any canonical plan files the transcription wrote) on the checkout's current branch at launch — that branch is the run branch (loop/epic-<N>by convention; a supervisor worktree may name it otherwise, and this surface never checks the name or switches branches) — in one commit with exactly this message:loop(epic-<N>): SPEC, manifest and story plans from the launch bootstrapName those paths, only the ones that exist, in both commands —
git add -- <paths>thengit commit -m '<message>' -- <paths>(a pathspec commit records only those paths, whatever else is staged) — nevergit add -A, never anything else. Ifgit addorgit commitfails, endblockedwith the git error verbatim inreason. When nothing was written (a relaunch), make no commit. Never push. This happens after step 4 and before step 6'scheck. -
Launch. Re-run
check; when it answersok, start the engine (add--allow-budget-mismatchonly when the payload carriesallow_budget_mismatch: true):uv run "${CLAUDE_PLUGIN_ROOT}/lib/launch.py" start --directory <root> --spec <spec_folder> [--allow-budget-mismatch]A
budget_mismatchwithout the acknowledgement is a refusal (exit 2,blocked, both numbers inreason, thebudgetobject carried in the refusal): report it and do not launch. The core mints the run id, spawnsbmad-loop run --spec … --run-id …detached and console-less with its output in~/.tk-studio/projects/<key>/launches/<run-id>.log, and answersokonly once the engine has written.bmad-loop/runs/<run-id>/state.json. A launch it could not confirm answersok: falsewith the pid and log named — report that asblockedwith the reason; do not launch again. -
Report. Attended and headless alike: the run id, the spec folder, the stories planned (none on a relaunch) and the
story plansrow, the route (session / implementer / reviewers / consult models and where each came from), anybudget_mismatchwith both numbers, and how to watch it — the studio supervisor's status page,launch.py status(this surface'sstatusverb), andbmad-loop tui. Then end with the status block (below).
sweep
Story 35.7: one deferred-work sweep through the studio (the run-sweep job type). Resolve <root> as start step 0 does, then run — no route, no bootstrap, no check (the core refuses on its own):
uv run "${CLAUDE_PLUGIN_ROOT}/lib/launch.py" sweep --directory <root> --triage-wait 540 [--max-bundles <max_bundles>]
Run it with the Bash tool timeout set to 600000 ms: the status block must print inside the tool's 600 s cap (the wait counts from the call's start), so the skill waits 540 s; the core's default stays 1500 s. A longer triage ends complete / triage still running and the supervisor's watch records it.
The core refuses before spawning anything (blocked, the gap named): no .bmad-loop/policy.toml, no _bmad-output/implementation-artifacts/deferred-work.md, a live engine owning the checkout (one engine per checkout, as start: the run ids and statuses named — never stopped to make room, never a second engine), a dirty tree (git status --porcelain, the paths named), an existing run dir. Otherwise it starts bmad-loop sweep --project <root> --no-prompt --run-id <rid> [--max-bundles <n>] detached (the triage pass: bmad-loop-sweep partitions the ledger; max_bundles and the attempt caps come from the policy, whose [sweep] auto stays never — an explicit start ignores it), waits for its state.json, then for .bmad-loop/runs/<rid>/triage.json (--triage-wait: the skill waits 540 s; the core's default stays 1500 s). A read triage is emitted once as the sweep-triage ledger event and returned as triage {bundles: [{name, dw_ids}], blocked: [{id, blocker}], decisions: [{id, question}], already_resolved: [id], skip: [id]}. Never clean the tree, never edit the policy or the ledger, never answer a decision: under --no-prompt they are skipped unattended and listed for bmad-loop decisions.
Report the bundles, the blocked entries and the human decisions, then end on the core's block. The bundles run in the engine afterwards; the supervisor closes the run out (one PR per sweep) and flips the ledger after the merge.
status
uv run "${CLAUDE_PLUGIN_ROOT}/lib/launch.py" status --directory <root> [--run-id <id>]
Relay the live runs and the named run's phase/attempt/cycle per task, its pause (stage, reason, story) when paused, and its token totals. Read-only.
stop
uv run "${CLAUDE_PLUGIN_ROOT}/lib/launch.py" stop --directory <root> --run-id <id> [--graceful]
Attended: confirm before an immediate stop (work in the current unit is preserved by the engine's attempt-preserve refs, but the unit is interrupted). Headless: stop as instructed; never ask.
Status block
Every path — start fresh or relaunch, status, stop, attended or headless — ends with the block (§3 of the driver contract) as its final line of output. The core ends every result, refusals included, with the block's keys in order (status, intent, artifacts, reason), so the rule is one: print the last core result's block as the final line, adding to artifacts only the SPEC/plan files this session wrote (never run_dir_abs or the store log path — §3 forbids absolute local paths). A start that launched ends:
{"status": "complete", "intent": "tk-studio-launch", "artifacts": [".bmad-loop/runs/20260903-101500-ab12", "_bmad-output/specs/spec-epic-2"], "reason": null}
A sweep ends on its block: complete with artifacts: [".bmad-loop/runs/<rid>", ".bmad-loop/runs/<rid>/triage.json"] and the one-line reason bundles: <name> (DW-a, DW-b); …; blocked: DW-x, …; decisions: DW-y, … (none for an empty list); complete with artifacts: [".bmad-loop/runs/<rid>"] and reason: "triage still running" when the wait elapsed with the engine live (the supervisor's watch records the triage later); blocked when the engine ended or paused before any triage.json (the triage escalated — or, when the engine's journal holds sweep-nothing-open, reason names sweep: nothing open in the ledger) or leaving a triage.json that does not parse (sweep triage unreadable, no full wait), or a refusal.
blocked names the gap verbatim: the readiness check's gaps[] (an open questions gap naming every CAP of the next story that has no design note), an unacknowledged budget_mismatch, the missing project resource, an unconfirmed launch. A path that ends before any core call (an unresolvable input, an unignored routing write, a missing bmad-spec) prints the same block shape itself, blocked with the gap. partial is the core's check naming a budget_mismatch.
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
- One engine per checkout: the core refuses a launch while any run owns the checkout; this skill never stops one to make room.
- The core never writes into the project tree: run state is the engine's, launch logs live in the per-user store (AD-3).
- SPEC.md comes from
bmad-spec, the task manifest from the project's task-planning instructions — this surface authors neither. - The route comes from
lib/pipeline.py— the shipped legs are measured defaults (AD-14 resource tier); a project overrides them in.bmad-loop/routing.toml, a driver per invocation with--set leg.field=value. Escalation is deliberate: this surface never routes a leg onto a larger model than the resolved value, and never launches a subagent on the planner tier. - Job-level events belong to the job wrapper (
job-run); this surface emits none of its own (AD-12) exceptsweep-triage, which the core'ssweepverb alone emits once per triage read (Story 35.7). - 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.