tk-studio-job
Run declared jobs on the harness's own scheduling primitives — submit, status, cancel, and wake per the driver contract, with budget guards and stop conditions enforced. Use when the user says "submit a job", "tk job", "job status", "cancel that job", or wants recurring/unattended work scheduled.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- tk-studio-job
- description
- Run declared jobs on the harness's own scheduling primitives — submit, status, cancel, and wake per the driver contract, with budget guards and stop conditions enforced. Use when the user says "submit a job", "tk job", "job status", "cancel that job", or wants recurring/unattended work scheduled.
02 资源文件 1
- 其他customize.toml557 B
03 SKILL.md 正文
tk-studio-job
Jobs are data (contracts/job.schema.json, ST-6.1); this skill is the
execution wrapper (AD-10, O8 hybrid): it drives the §4 scheduler verbs and
binds recurring work to whatever the harness natively offers — scheduled
tasks/cron for cron triggers, loop primitives for fixed loop cadence,
self-paced wakeups for self-paced — never a bespoke runner. Run state
lives in resumable run workspaces under the per-user store.
Behavior (both modes)
-
Every verb goes through the deterministic core (the one §4 surface):
uv run "${CLAUDE_PLUGIN_ROOT}/lib/jobrun.py" submit --directory <root> --id <job-id> uv run "${CLAUDE_PLUGIN_ROOT}/lib/jobrun.py" status --directory <root> --job-id <id> [--run-id <rid>] uv run "${CLAUDE_PLUGIN_ROOT}/lib/jobrun.py" resolve --directory <root> [--job-id <id>] uv run "${CLAUDE_PLUGIN_ROOT}/lib/jobrun.py" cancel --directory <root> --job-id <id> [--run-id <rid>] uv run "${CLAUDE_PLUGIN_ROOT}/lib/jobrun.py" wake --directory <root> --job-id <id>submitvalidates (a job missing guards or stop conditions is rejected,accepted: false), gates on stop conditions, and answers with a directive. Core-target one-shots execute immediately, wall-clock guarded. Anaccepted/wokenfalseis an answer — relay the reason.resolveis read-only: it serves every declared job (or one, by id) fully resolved — type extension applied by the one resolver — so a substrate-side driver classifies recurring work from the trigger/cadence served here and never raw-reads.tk-studio/jobs/<id>.json(PROP-008); an entry's problems ride it named in place, an unknown id is a named refusal. -
Bind the directive to the harness.
{"kind": "cron", "schedule": ...}→ the harness's scheduled-task primitive;{"kind": "loop", ...}/{"kind": "self-paced", ...}→ its loop/wakeup primitives;{"kind": "invoke-skill", ...}→ invoke the named skill with the payload, then report the outcome withfinish. Each firing of a recurring job is onewake. Aninvoke-skilldirective also names the run's provisional-knowledge artifacts (knowledge: spine/seed paths withpresentflags — the §4 KB-injection directive, contract 0.1.7): inject each present artifact's contents into the segment you invoke. Aid, not gate — an absent artifact never skips or fails the run. -
Skill-target runs stay honest. While executing an
invoke-skilldirective, callaccount --run-id <rid> --turns 1 [--tokens N]every iteration; the moment it answerswithin_budget: false, end the runpartialwith the guard named:uv run "${CLAUDE_PLUGIN_ROOT}/lib/jobrun.py" finish --directory <root> --run-id <rid> --state partial --reason "guard: max_turns"Pass
--total-cost-usd <usd>tofinishwhen the worker reports one (its--output-format jsonresult); omit it otherwise, never guess.finishrecords the terminal state and emits the run'sjob-runevent — this wrapper alone emits job-level events; the target skill emits its own surface events, never both for one failure (AD-12). Every terminal transition also captures the run's handoff deltas into the per-project reconciliation queue (ST-9.4,lib/reconcile.py— deduped, idempotent, per-user store only); the capture evidence ridessummary.jsonand thefinishresponse, and a capture problem is recorded there, never a failed verb.uv run "${CLAUDE_PLUGIN_ROOT}/lib/reconcile.py" route --directory <root>renders the routing doc beside the queue — a pure render that applies nothing (promotion is ST-9.5's PR membrane). -
Durability is surfaced, never silently lost. A
durable: truerecurring job on this session-scoped substrate gets adurability_constraintin the submit response: relay it verbatim (attended) or include it in the status blockreasoncontext (headless). Bind durable jobs to a cloud routine or an external harness via the driver contract; otherwise they must be re-submitted each session. -
Attended: confirm before binding schedules; summarize directive, guards, and stop conditions. Headless: everything arrives in the payload; an unknown job id or invalid definition ends
blocked, a guard or stop condition hit endspartialwith the reason named — never a prompt (AD-11). End headless runs with the status block:{"status": "complete", "intent": "tk-studio-job", "artifacts": ["~/.tk-studio/projects/<key>/runs/<run-id>/"], "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
- The job model is data; never invent, widen, or hot-patch a definition —
instances live in
.tk-studio/jobs/<id>.json, listed in configjobs[]. - Guards and stop conditions are contracts, not suggestions: obey
accountverdicts immediately; a job never runs away (AD-10). - Run workspaces are the resumable truth: a fresh session continues a
queued|runningrun fromrun.jsonalone (snapshot + checkpoint). - Every terminal run leaves
summary.jsonin its workspace (core runs also land the full parsed result asoutput.json); point the operator there, never paste whole reports into chat. - Long work splits at declared boundaries (ST-6.6; surface:
tk-studio-session, ST-9.2): at an epic/story/phase boundary or a budget trigger, land the handoff and END the session —uv run "${CLAUDE_PLUGIN_ROOT}/lib/session.py" handoff --directory <root> --run-id <rid> --boundary <kind> --name <id> --done ... --next ...(optionally--deltacorrections against the workspace seed); a fresh session continues viasession.py resumefrom the workspace alone, never by replaying history. Ending the session never ends the run. - 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.