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.
- License 许可
- MIT
- 最近更新
- 2026-11-10
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- tk-studio-plan-sync
- description
- 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.
02 资源文件 1
- 其他customize.toml512 B
03 SKILL.md 正文
tk-studio-plan-sync
The adapter side of AD-4: stock BMad planning skills stay untouched; this
skill canonicalizes what they produce. The normalized _bmad-output/
planning artifacts are the single canonical local representation under every
binding, and this skill is the sole id authority (EP-/ST-/TA-NNN from the
committed per-project counter at .tk-studio/plan-counter.yaml).
Behavior (both modes)
-
Run the full adapter verb through the plugin root:
uv run "${CLAUDE_PLUGIN_ROOT}/lib/plansync.py" sync --directory <project-root>sync= normalize → validate → projection → plan index, where only the projection step is binding-driven (resolved fromplanning.backend, AD-15 order;--backend NAMEis the runtime override). Underbmad-filesthe canonical files are the backend: projection is a clean, first-class no-op (FR14). Underbacklog-mdthe projection is pull-back → promote (AD-5): backend status-class changes (status, assignee) land on canonical files first — echo-suppressed against theexternal.backlog-mdsnapshot, both-changed entities surfaced as conflicts for a human, never resolved silently — then canonical entities project into a Backlog.md-compatiblebacklog/(epic → milestone + label linkage; story/task → task files, native keys only with the canonical id as the first label — Backlog.md 1.48.0 verifiably drops unknown frontmatter keys; seekb/backlog-md-verified-behavior.md). Underjira(AD-7) the same pull-back → promote round runs against Atlassian Cloud: the preflight first proves the API token AND the org-admin API-token toggle in one probe (GET /myself) and confirms the AD-6 default issue-type mapping (epic → Epic, story → Story, task → Sub-task) against the org's actual scheme; then pull-back ingests backend status/assignee (echo-suppressed viaexternal.jira, both-changed = conflict) and promote creates/updates issues (canonical id rides as the first label; status set by transition into the matching Jira status category, which keeps mapping round-trip stable). Binding config:planning.jira.site+planning.jira.project_key(tracked). Credentials ride the environment only — never any config file (AD-3): the agent seat's scoped tokenTK_ATLASSIAN_AGENT_TOKENwithTK_ATLASSIAN_AGENT_EMAIL, through thehttps://api.atlassian.com/ex/jira/<TK_ATLASSIAN_CLOUD_ID>gateway (/rest/api/2kept); either agent token set withoutTK_ATLASSIAN_CLOUD_IDrefuses by name, never the site URL. WithTK_ATLASSIAN_AGENT_TOKENunset, the legacyJIRA_API_TOKENplusJIRA_EMAIL(orplanning.jira.email) against the site URL. Auth is API-token, never OAuth (legacy-council ISS-008); any gap blocks with every cause named — a 401 names the token, its email, its expiry and the org toggle; the sandbox proxy's 403 (Approval required for <host>:443) is the network approval step; any other 403 names the missing scope and asks for a new token — never a silent 401 (AD-11).setup --directory <root> [--dry-run] [--owner-account-id <id> | --owner-email <email>]creates the project's tracking from the studio template — the Jira project (key from the project id), issue types Epic and Story, the statusesBlocked - Awaiting UserandBlock Resolvedwith their transition, the "Needs you" filter, the Confluence space (TK_ATLASSIAN_AGENT_CONFLUENCE_TOKEN, gateway only) and its folders Brief, GDD, Scope of Work, Decisions and Records — recognising each by key first, and records the keys and ids underplanning.jiraandplanning.confluence. What the API refuses becomes the owner's numbered steps (owner_steps[]) and the run endspartial; an unregistered project or an absent agent-seat variable endsblockedbefore any call; a dry run that would create anything endspartialtoo (would_create[]).tk-studio-onboard's optional tracking step calls it. Payload mapping:setup: truerunsplansync.py setup --directory <directory>;dry_runadds--dry-run;owner_account_idadds--owner-account-id <id>, elseowner_emailadds--owner-email <email>.publish --directory <root> [--dry-run] [--source <category>=<path>] [--attachment-max-bytes <n>](Story 31.3) publishes the design pages (brief, GDD, scope of work, decisions — never the records folder) to the folders setup recorded, by the stable title<Folder>: <slug>, Markdown converted to Confluence storage format with images attached, each page ending with a provenance footer (source file, the last commit that touched it, the content hash); an unchanged page is skipped. An image over the per-file ceiling (100 MB assumed unless--attachment-max-bytessupplies the site's smaller setting) is refused by name and its page still publishes;bytes_uploadedreports the upload against Confluence Free's 2 GB. It writes.tk-studio/confluence-pages.json, from which thejirapromote adds aDesign pages:line to every epic and story; nothing from Confluence changes an entity field (AD-5). An absent agent-seat Confluence variable, noplanning.confluencebinding ("runplansync.py setupfirst"), a bad--sourceor a duplicate title endsblockedbefore any call; a category with no folder, a refused page or image, or a dry run that would publish endspartial. Payload mapping:publish: truerunsplansync.py publish --directory <directory>;dry_runadds--dry-run;attachment_max_bytes(the site's Attachment maximum size, in bytes) adds--attachment-max-bytes <n>— the effective ceiling is the smaller of it and 100 MB, and the result'snotes[]says which was used. An image outside the project root (an absolute path, a non-http(s) scheme, a../escape or a symlink out) is refused by name before any read and its page still publishes.sync-back --directory <root> [--dry-run](Story 31.4) pulls the project's Atlassian state into local memory so that no agent queries Atlassian live for context: each tracked issue's status (canonical by name first —Blocked - Awaiting UserandBlock Resolvedareblocked— then by status category; the Jira original kept underexternal.jira,updatedstamped; no other entity field changes, andplan/index.mdis regenerated local-only when a status changed), its comments append-only into_bmad-output/tracking/<KEY>/comments.jsonl(a comment seen twice is written once; an edit appends a line), its attachments as links intoattachments.jsonl(never downloaded or uploaded), and every owner-authored page of the recorded Confluence space intokb/confluence/<slug>.mdwith a provenance header (read-only: a local edit is overwritten and named inoverwritten[]). Story 32.4: each engagement's scope page (the record'sscope_page.id, agent- published, so never in the owner-page mirror) is read by id; a version above the record'sscope_page.versionis mirrored as Markdown intokb/confluence/<slug>.md(the provenance header plusengagement: ENG-NNN; its state undersync-state.jsonengagement_pages) and, while the engagement isscoping, replaces itsscope.mdwholesale (the page is authoritative, D9) and merges the version into the record; in any other state only the mirror is written andnotes[]saysscope edit of ENG-NNN not applied: state <s> (send revise)once per version (no state moves). A page gone (404) is a note; counts gainengagement_pages_mirroredandscopes_replaced. One paged JQL search per tick, never a GET per issue — only an issue whosecomment.totalexceeds the comments the search returned pagesGET /rest/api/2/issue/{key}/comment(overflow only); the cursor in_bmad-output/tracking/sync-state.jsonmoves only after every page was read. Nothing local is promoted back. The result namescounts,newest_comment,applied[],conflicts[],overwritten[],rate_limit,notes[]andwritten[]. Noplanning.jirabinding or an absent Jira variable endsblockedbefore any call; a failed preflight (unreachable, deactivated, the 401/403 split, or a preflight answered with another, non-auth status: run caseerror) endsblocked; an absentTK_ATLASSIAN_AGENT_CONFLUENCE_TOKEN(the Jira half still runs), an unrecordedplanning.confluence.space_id(the mirror skipped), no recorded owner accountId, a conflict, or a 429 or error that interrupted a read endspartial. The shipped cron jobatlassian-sync-backruns it every 10 minutes. Payload mapping:sync_back: truerunsplansync.py sync-back --directory <directory>;dry_runadds--dry-run(reads only, writes nothing).stage(Story 35.8) writes the story spec's append-only## Stage Logtable — one row per stage occurrence, the columnsstage,pass,started,ended,session_id,model,effort,tokens_in,tokens_out,cost_usd,outcome(—for empty; elapsed is never stored, only derived) — after## Consult Log(else before## Auto Run Result). The planner brackets its plan session withstage --start --story <key> --stage plan --model <m> --effort <e>andstage --stop --story <key> --stage plan(the epic's planning:--entity EP-NNN);--stopwith no open row is a refusal naming it. The supervisor appends its legs withstage --append --story <key> --row-json <rows>; the engine's studio-pipelinepost_sessionhook writes each pass withstage --from-pass(never by hand). A row written before the spec exists waits in<spec_folder>/stages/<key>.jsonland is flushed by the next write; a row already on record is skipped (appended: 0).stage-post --directory <root> --id ST-NNN [--story <key>] [--dry-run]mirrors the rows onto the story's Jira issue (the agent seat, through the gateway):Stage <name> [pass n] started — <stamp>; model: X; effort: Y [stage:<key> start],… finished — <stamp>; model: X; effort: Y; tokens: in/out; cost: $Z [stage:<key> stop]and a worklog of the derived span (none under Jira's 60 s minimum:worklog: "skipped: span <60s"), each recorded in_bmad-output/tracking/stage-posts.jsonand never posted twice (the markers are looked up first). Not bound to Jira: nothing posted (posted: "skipped: not bound").unpostedcounts the rows not yet mirrored (buffered, open, or a post missing): while any remain it endspartial,ok: false,retryable: true; a failed Jira call endsblocked,retryable: true— the supervisor retries both next pass; a refusal (noexternal.jira.key, no agent token) carries noretryableand is not retried.stage --from-pass --repo-root <root>also flushes the planner's buffer left under the project root. Both end with the status block.deferred mint --directory <root> [--count N] [--dry-run](Story 37.1) is the deferred-work ledger's one id source: the operator's docs pass runs it, then writes its entries under the answeredids, never minting from the ledger's highest heading. It readsnext.deferred-workin.tk-studio/plan-counter.yaml(seeded when absent, one past the highestDW-Nin the ledger), bumps it, keeps the ledger header's marker line and names both files inwritten[]; the engine's harvest reads the marker, and the studio-pipelinepre_commithook bumps the counter after a harvest. It andledger-resolverefuse a duplicate### DW-N:heading by name (LedgerDuplicateId), and both end with the status block. An entry closed from inside a run, where no PR number exists yet, readsby Story N.M, neverby this story's PR, whichtest_no_placeholder_pr_number_remainsfails.normalize --directory <root>runs the canonicalization pass alone. Add--dry-runto preview without writing (underjiraa dry-run never contacts the backend). The normalize pass:- derives/repairs one canonical entity file per epic/story under
_bmad-output/planning-artifacts/plan/<ID>.mdfromepics.md(matched across runs by thesourcekey — ids never move;epics.mditself is never rewritten); - mints missing ids from the committed counter (document order, counter persisted atomically before entity files — a crash leaves a gap, never a duplicate);
- stamps
canonical_idinto matchingimplementation-artifacts/story-N.M.mdfiles textually (one line; every other byte preserved); - pulls story status from
sprint-status.yamlwhen present, mapped onto the closed canonical enum (unmappable states reported, never guessed).
The result names every file the run wrote —
written[]at both levels (counter, entity files, story-file stamps, projection writes with their canonical snapshot rewrites, index) plusremoved[](projection files replaced on rename), withnormalize.counternaming the committed id counter — so commit staging derives from the response alone: stage exactly thewritten[]andremoved[]paths, nothing recalled by hand (EP-017, PROP-020). A sync blocked at the projection still names normalize's landed writes. - derives/repairs one canonical entity file per epic/story under
-
Blocking conditions (exit 2, nothing written):
- duplicate ids anywhere under
_bmad-output/— both paths are named; a human renumbers, then sync reruns (AD-4: never auto-pick a survivor); - invalid present values in canonical frontmatter (bad status, id, dates) — repair fills only missing keys, it never rewrites a present value it cannot trust (AD-3 refuse-to-guess);
- jira preflight failure — missing binding config or credentials, 401/403 (token or org toggle), or an issue-type scheme missing a default-mapping target — each gap named (AD-7/AD-11).
- publish refusal — an absent
TK_ATLASSIAN_AGENT_EMAIL,TK_ATLASSIAN_AGENT_CONFLUENCE_TOKENorTK_ATLASSIAN_CLOUD_ID, noplanning.confluencebinding, a bad--source, or two sources with one title — each named, no Atlassian call. - sync-back refusal — no
planning.jirabinding or an absent Jira variable — each named, no Atlassian call. - stage refusal —
stage --stopwith no open row, several specs matching the story, or a row field outside the Stage Log's columns;stage-postwith an absent agent-seat variable or an entity with noexternal.jira.key— each named, no Atlassian call. - deferred refusal —
LedgerDuplicateId: DW-N at lines a and b, a badnext.deferred-work, a bad--countor no ledger — named, nothing written.
- duplicate ids anywhere under
-
Report:
-
Attended: summarize actions (created/repaired/unchanged, minted ids, stamps, notes); on a block, show the exact file paths and what to fix — never fix ids silently.
-
On conflicts (both sides changed since the last sync): list each conflicted entity with both values and both file paths; the human picks a side by editing one of them, then reruns sync.
-
Headless: no prompts (AD-11). End with the status block. When the core's result carries its own
status(setup,publishandsync-backdo:complete,partialorblocked), relay thatstatus, itsreasonand itsartifactsas they are — never infer the status from the exit code (setup,publishandsync-backexit 0 onpartial);stageandstage-postcarry theirs too (stage:completeorblocked;stage-post:complete,partialwhile rows are still unposted, orblocked). Forsync,normalizeandstatus, whose results carry nostatus:completeon exit 0 (report conflicts aspartialwith the conflict list inreason),blockedon exit 2 with the blocking reason:{"status": "complete", "intent": "tk-studio-plan-sync", "artifacts": ["_bmad-output/planning-artifacts/plan/"], "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
- Only this skill (via
lib/plansync.py) mints ids or writes canonical frontmatter keys — no other skill, stock or studio, ever does (AD-4). - Entity shape questions resolve against
contracts/interchange/shape.v1.jsonvialib/interchange.py— the single shipped validator. - Backend projection (promote / status pull-back) is binding-driven;
bmad-filesmeans normalize + validate + index with no projection — a first-class no-op, not an error. Every backend, Jira included, is a projection of the canonical files, never authoritative (AD-5); no skill other than this one ever calls a planning backend (AD-4). plan/index.mdis generated — a foreign index.md in its place is refused, never overwritten.- 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-orchestrator
The studio's front door — resolve who you are (role, per-user store), what this project needs (confirmed working_set.<role>), and route to resources by name, statelessly. Use when the user says "enter the studio", "tk studio", "orchestrate", "convene the council", or asks what to work on through the studio.