AGENT SKILL

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

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)

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

    submit validates (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. An accepted/woken false is an answer — relay the reason. resolve is 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.

  2. 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 with finish. Each firing of a recurring job is one wake. An invoke-skill directive also names the run's provisional-knowledge artifacts (knowledge: spine/seed paths with present flags — 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.

  3. Skill-target runs stay honest. While executing an invoke-skill directive, call account --run-id <rid> --turns 1 [--tokens N] every iteration; the moment it answers within_budget: false, end the run partial with 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> to finish when the worker reports one (its --output-format json result); omit it otherwise, never guess. finish records the terminal state and emits the run's job-run event — 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 rides summary.json and the finish response, 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).

  4. Durability is surfaced, never silently lost. A durable: true recurring job on this session-scoped substrate gets a durability_constraint in the submit response: relay it verbatim (attended) or include it in the status block reason context (headless). Bind durable jobs to a cloud routine or an external harness via the driver contract; otherwise they must be re-submitted each session.

  5. 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 ends partial with 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 config jobs[].
  • Guards and stop conditions are contracts, not suggestions: obey account verdicts immediately; a job never runs away (AD-10).
  • Run workspaces are the resumable truth: a fresh session continues a queued|running run from run.json alone (snapshot + checkpoint).
  • Every terminal run leaves summary.json in its workspace (core runs also land the full parsed result as output.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 --delta corrections against the workspace seed); a fresh session continues via session.py resume from the workspace alone, never by replaying history. Ending the session never ends the run.
  • 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