[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M79RXY4AM8JM6ZK2MAR3W3X2":3,"skill-same:01M79RXY4AM8JM6ZK2MAR3W3X2":52},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M79RXY4AM8JM6ZK2MAR3W3X2","tk-studio-plan-sync",null,"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\u002Fstories.","thkennedy\u002Ftk-studio","thkennedy","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F4164502?v=4","01M79QZ8DMP5FF2HC6GS3S6FDF","Tim Kennedy","01M79QZ8EM9JBWJ15R5JNC4PW3",0,"MIT","https:\u002F\u002Fgithub.com\u002Fthkennedy\u002Ftk-studio\u002Fblob\u002Fmain\u002Fplugins\u002Ftk-studio\u002Fskills\u002Ftk-studio-plan-sync\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: tk-studio-plan-sync\ndescription: 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\u002Fstories.\n---\n\n# tk-studio-plan-sync\n\nThe adapter side of AD-4: stock BMad planning skills stay untouched; this\nskill canonicalizes what they produce. The normalized `_bmad-output\u002F`\nplanning artifacts are the single canonical local representation under every\nbinding, and this skill is the **sole id authority** (EP-\u002FST-\u002FTA-NNN from the\ncommitted per-project counter at `.tk-studio\u002Fplan-counter.yaml`).\n\n## Behavior (both modes)\n\n1. Run the full adapter verb through the plugin root:\n\n   ```bash\n   uv run \"${CLAUDE_PLUGIN_ROOT}\u002Flib\u002Fplansync.py\" sync --directory \u003Cproject-root>\n   ```\n\n   `sync` = normalize → validate → projection → plan index, where only the\n   projection step is binding-driven (resolved from `planning.backend`,\n   AD-15 order; `--backend NAME` is the runtime override). Under\n   `bmad-files` the canonical files are the backend: projection is a clean,\n   first-class no-op (FR14). Under `backlog-md` the projection is pull-back\n   → promote (AD-5): backend status-class changes (status, assignee) land on\n   canonical files first — echo-suppressed against the `external.backlog-md`\n   snapshot, both-changed entities surfaced as **conflicts** for a human,\n   never resolved silently — then canonical entities project into a\n   Backlog.md-compatible `backlog\u002F` (epic → milestone + label linkage;\n   story\u002Ftask → task files, native keys only with the canonical id as the\n   first label — Backlog.md 1.48.0 verifiably drops unknown frontmatter\n   keys; see `kb\u002Fbacklog-md-verified-behavior.md`). Under `jira` (AD-7) the\n   same pull-back → promote round runs against Atlassian Cloud: the\n   **preflight** first proves the API token AND the org-admin API-token\n   toggle in one probe (`GET \u002Fmyself`) and confirms the AD-6 default\n   issue-type mapping (epic → Epic, story → Story, task → Sub-task) against\n   the org's actual scheme; then pull-back ingests backend status\u002Fassignee\n   (echo-suppressed via `external.jira`, both-changed = conflict) and\n   promote creates\u002Fupdates issues (canonical id rides as the first label;\n   status set by transition into the matching Jira status *category*, which\n   keeps mapping round-trip stable). Binding config: `planning.jira.site` +\n   `planning.jira.project_key` (tracked). Credentials ride the environment\n   **only** — never any config file (AD-3): the agent seat's scoped token\n   `TK_ATLASSIAN_AGENT_TOKEN` with `TK_ATLASSIAN_AGENT_EMAIL`, through the\n   `https:\u002F\u002Fapi.atlassian.com\u002Fex\u002Fjira\u002F\u003CTK_ATLASSIAN_CLOUD_ID>` gateway\n   (`\u002Frest\u002Fapi\u002F2` kept); either agent token set without\n   `TK_ATLASSIAN_CLOUD_ID` refuses by name, never the site URL. With\n   `TK_ATLASSIAN_AGENT_TOKEN` unset, the legacy `JIRA_API_TOKEN` plus\n   `JIRA_EMAIL` (or `planning.jira.email`) against the site URL. Auth is\n   API-token, never OAuth (legacy-council ISS-008); any gap blocks with\n   every cause named — a 401 names the token, its email, its expiry and\n   the org toggle; the sandbox proxy's 403 (`Approval required for\n   \u003Chost>:443`) is the network approval step; any other 403 names the\n   missing scope and asks for a new token — never a silent 401 (AD-11).\n   `setup --directory \u003Croot> [--dry-run] [--owner-account-id \u003Cid> |\n   --owner-email \u003Cemail>]` creates the project's tracking from the studio\n   template — the Jira project (key from the project id), issue types Epic\n   and Story, the statuses `Blocked - Awaiting User` and `Block Resolved`\n   with their transition, the \"Needs you\" filter, the Confluence space\n   (`TK_ATLASSIAN_AGENT_CONFLUENCE_TOKEN`, gateway only) and its folders\n   Brief, GDD, Scope of Work, Decisions and Records — recognising each by\n   key first, and records the keys and ids under `planning.jira` and\n   `planning.confluence`. What the API refuses becomes the owner's\n   numbered steps (`owner_steps[]`) and the run ends `partial`; an\n   unregistered project or an absent agent-seat variable ends `blocked`\n   before any call; a dry run that would create anything ends `partial`\n   too (`would_create[]`). `tk-studio-onboard`'s optional tracking step\n   calls it. Payload mapping: `setup: true` runs `plansync.py setup\n   --directory \u003Cdirectory>`; `dry_run` adds `--dry-run`; `owner_account_id`\n   adds `--owner-account-id \u003Cid>`, else `owner_email` adds `--owner-email\n   \u003Cemail>`.\n   `publish --directory \u003Croot> [--dry-run] [--source \u003Ccategory>=\u003Cpath>]\n   [--attachment-max-bytes \u003Cn>]` (Story 31.3) publishes the design pages\n   (brief, GDD, scope of work, decisions — never the records folder) to\n   the folders setup recorded, by the stable title `\u003CFolder>: \u003Cslug>`,\n   Markdown converted to Confluence storage format with images attached,\n   each page ending with a provenance footer (source file, the last commit\n   that touched it, the content hash); an unchanged page is skipped. An\n   image over the per-file ceiling (100 MB assumed unless\n   `--attachment-max-bytes` supplies the site's smaller setting) is refused\n   by name and its page still publishes; `bytes_uploaded` reports the\n   upload against Confluence Free's 2 GB. It writes\n   `.tk-studio\u002Fconfluence-pages.json`, from which the `jira` promote adds a\n   `Design pages:` line to every epic and story; nothing from Confluence\n   changes an entity field (AD-5). An absent agent-seat Confluence variable,\n   no `planning.confluence` binding (\"run `plansync.py setup` first\"), a\n   bad `--source` or a duplicate title ends `blocked` before any call; a\n   category with no folder, a refused page or image, or a dry run that\n   would publish ends `partial`. Payload mapping: `publish: true` runs\n   `plansync.py publish --directory \u003Cdirectory>`; `dry_run` adds\n   `--dry-run`; `attachment_max_bytes` (the site's Attachment maximum\n   size, in bytes) adds `--attachment-max-bytes \u003Cn>` — the effective\n   ceiling is the smaller of it and 100 MB, and the result's `notes[]`\n   says which was used. An image outside the project root (an absolute\n   path, a non-http(s) scheme, a `..\u002F` escape or a symlink out) is refused\n   by name before any read and its page still publishes.\n   `sync-back --directory \u003Croot> [--dry-run]` (Story 31.4) pulls the\n   project's Atlassian state into local memory so that no agent queries\n   Atlassian live for context: each tracked issue's status (canonical by\n   name first — `Blocked - Awaiting User` and `Block Resolved` are\n   `blocked` — then by status category; the Jira original kept under\n   `external.jira`, `updated` stamped; no other entity field changes, and\n   `plan\u002Findex.md` is regenerated local-only when a status changed), its comments\n   append-only into `_bmad-output\u002Ftracking\u002F\u003CKEY>\u002Fcomments.jsonl` (a\n   comment seen twice is written once; an edit appends a line), its\n   attachments as links into `attachments.jsonl` (never downloaded or\n   uploaded), and every owner-authored page of the recorded Confluence\n   space into `kb\u002Fconfluence\u002F\u003Cslug>.md` with a provenance header (read-only:\n   a local edit is overwritten and named in `overwritten[]`). Story 32.4:\n   each engagement's scope page (the record's `scope_page.id`, agent-\n   published, so never in the owner-page mirror) is read by id; a version\n   above the record's `scope_page.version` is mirrored as Markdown into\n   `kb\u002Fconfluence\u002F\u003Cslug>.md` (the provenance header plus `engagement:\n   ENG-NNN`; its state under `sync-state.json` `engagement_pages`) and,\n   while the engagement is `scoping`, replaces its `scope.md` wholesale\n   (the page is authoritative, D9) and merges the version into the record;\n   in any other state only the mirror is written and `notes[]` says\n   `scope edit of ENG-NNN not applied: state \u003Cs> (send revise)` once per\n   version (no state moves). A page gone (404) is a note; counts gain\n   `engagement_pages_mirrored` and `scopes_replaced`. One paged JQL\n   search per tick, never a GET per issue — only an issue whose\n   `comment.total` exceeds the comments the search returned pages\n   `GET \u002Frest\u002Fapi\u002F2\u002Fissue\u002F{key}\u002Fcomment` (overflow only); the cursor in `_bmad-output\u002Ftracking\u002Fsync-state.json`\n   moves only after every page was read. Nothing local is promoted back.\n   The result names `counts`, `newest_comment`, `applied[]`,\n   `conflicts[]`, `overwritten[]`, `rate_limit`, `notes[]` and `written[]`.\n   No `planning.jira` binding or an absent Jira variable ends `blocked`\n   before any call; a failed preflight (unreachable, deactivated, the\n   401\u002F403 split, or a preflight answered with another, non-auth status:\n   run case `error`) ends `blocked`; an absent\n   `TK_ATLASSIAN_AGENT_CONFLUENCE_TOKEN` (the Jira half still runs), an\n   unrecorded `planning.confluence.space_id` (the mirror skipped), no\n   recorded owner accountId, a conflict, or a 429 or error that\n   interrupted a read ends `partial`. The shipped cron job\n   `atlassian-sync-back` runs it every 10 minutes. Payload mapping:\n   `sync_back: true` runs `plansync.py sync-back --directory \u003Cdirectory>`;\n   `dry_run` adds `--dry-run` (reads only, writes nothing).\n\n   `stage` (Story 35.8) writes the story spec's append-only `## Stage\n   Log` table — one row per stage occurrence, the columns `stage`, `pass`,\n   `started`, `ended`, `session_id`, `model`, `effort`, `tokens_in`,\n   `tokens_out`, `cost_usd`, `outcome` (`—` for empty; elapsed is never\n   stored, only derived) — after `## Consult Log` (else before `## Auto Run\n   Result`). The planner brackets its plan session with\n   `stage --start --story \u003Ckey> --stage plan --model \u003Cm> --effort \u003Ce>` and\n   `stage --stop --story \u003Ckey> --stage plan` (the epic's planning:\n   `--entity EP-NNN`); `--stop` with no open row is a refusal naming it. The\n   supervisor appends its legs with `stage --append --story \u003Ckey>\n   --row-json \u003Crows>`; the engine's studio-pipeline `post_session` hook\n   writes each pass with `stage --from-pass` (never by hand). A row written\n   before the spec exists waits in `\u003Cspec_folder>\u002Fstages\u002F\u003Ckey>.jsonl` and is\n   flushed by the next write; a row already on record is skipped\n   (`appended: 0`). `stage-post --directory \u003Croot> --id ST-NNN [--story\n   \u003Ckey>] [--dry-run]` mirrors the rows onto the story's Jira issue (the\n   agent seat, through the gateway): `Stage \u003Cname> [pass n] started —\n   \u003Cstamp>; model: X; effort: Y [stage:\u003Ckey> start]`, `… finished — \u003Cstamp>;\n   model: X; effort: Y; tokens: in\u002Fout; cost: $Z [stage:\u003Ckey> stop]` and a\n   worklog of the derived span (none under Jira's 60 s minimum: `worklog:\n   \"skipped: span \u003C60s\"`), each recorded in\n   `_bmad-output\u002Ftracking\u002Fstage-posts.json` and never posted twice (the\n   markers are looked up first). Not bound to Jira: nothing posted\n   (`posted: \"skipped: not bound\"`). `unposted` counts the rows not yet\n   mirrored (buffered, open, or a post missing): while any remain it ends\n   `partial`, `ok: false`, `retryable: true`; a failed Jira call ends\n   `blocked`, `retryable: true` — the supervisor retries both next pass; a\n   refusal (no `external.jira.key`, no agent token) carries no `retryable`\n   and is not retried. `stage --from-pass --repo-root \u003Croot>` also flushes\n   the planner's buffer left under the project root. Both end with the\n   status block.\n   `deferred mint --directory \u003Croot> [--count N] [--dry-run]` (Story 37.1) is\n   the deferred-work ledger's one id source: the operator's docs pass runs it,\n   then writes its entries under the answered `ids`, never minting from the\n   ledger's highest heading. It reads `next.deferred-work` in\n   `.tk-studio\u002Fplan-counter.yaml` (seeded when absent, one past the highest\n   `DW-N` in the ledger), bumps it, keeps the ledger header's marker line and\n   names both files in `written[]`; the engine's harvest reads the marker, and\n   the studio-pipeline `pre_commit` hook bumps the counter after a harvest. It\n   and `ledger-resolve` refuse a duplicate `### DW-N:` heading by name\n   (`LedgerDuplicateId`), and both end with the status block. An entry closed\n   from inside a run, where no PR number exists yet, reads `by Story N.M`,\n   never `by this story's PR`, which `test_no_placeholder_pr_number_remains`\n   fails.\n\n   `normalize --directory \u003Croot>` runs the canonicalization pass\n   alone. Add `--dry-run` to preview without writing (under `jira` a\n   dry-run never contacts the backend). The normalize pass:\n   - derives\u002Frepairs one canonical entity file per epic\u002Fstory under\n     `_bmad-output\u002Fplanning-artifacts\u002Fplan\u002F\u003CID>.md` from `epics.md` (matched\n     across runs by the `source` key — ids never move; `epics.md` itself is\n     never rewritten);\n   - mints missing ids from the committed counter (document order, counter\n     persisted atomically before entity files — a crash leaves a gap, never a\n     duplicate);\n   - stamps `canonical_id` into matching `implementation-artifacts\u002Fstory-N.M.md`\n     files textually (one line; every other byte preserved);\n   - pulls story status from `sprint-status.yaml` when present, mapped onto\n     the closed canonical enum (unmappable states reported, never guessed).\n\n   The result names **every file the run wrote** — `written[]` at both\n   levels (counter, entity files, story-file stamps, projection writes with\n   their canonical snapshot rewrites, index) plus `removed[]` (projection\n   files replaced on rename), with `normalize.counter` naming the committed\n   id counter — so commit staging derives from the response alone: stage\n   exactly the `written[]` and `removed[]` paths, nothing recalled by hand\n   (EP-017, PROP-020). A sync blocked at the projection still names\n   normalize's landed writes.\n\n2. Blocking conditions (exit 2, nothing written):\n   - **duplicate ids** anywhere under `_bmad-output\u002F` — both paths are named;\n     a human renumbers, then sync reruns (AD-4: never auto-pick a survivor);\n   - **invalid present values** in canonical frontmatter (bad status, id,\n     dates) — repair fills only *missing* keys, it never rewrites a present\n     value it cannot trust (AD-3 refuse-to-guess);\n   - **jira preflight failure** — missing binding config or credentials,\n     401\u002F403 (token or org toggle), or an issue-type scheme missing a\n     default-mapping target — each gap named (AD-7\u002FAD-11).\n   - **publish refusal** — an absent `TK_ATLASSIAN_AGENT_EMAIL`,\n     `TK_ATLASSIAN_AGENT_CONFLUENCE_TOKEN` or `TK_ATLASSIAN_CLOUD_ID`, no\n     `planning.confluence` binding, a bad `--source`, or two sources with\n     one title — each named, no Atlassian call.\n   - **sync-back refusal** — no `planning.jira` binding or an absent Jira\n     variable — each named, no Atlassian call.\n   - **stage refusal** — `stage --stop` with no open row, several specs\n     matching the story, or a row field outside the Stage Log's columns;\n     `stage-post` with an absent agent-seat variable or an entity with no\n     `external.jira.key` — each named, no Atlassian call.\n   - **deferred refusal** — `LedgerDuplicateId: DW-N at lines a and b`, a bad\n     `next.deferred-work`, a bad `--count` or no ledger — named, nothing\n     written.\n\n3. Report:\n   - **Attended:** summarize actions (created\u002Frepaired\u002Funchanged, minted\n     ids, stamps, notes); on a block, show the exact file paths and what to\n     fix — never fix ids silently.\n   - On **conflicts** (both sides changed since the last sync): list each\n     conflicted entity with both values and both file paths; the human picks\n     a side by editing one of them, then reruns sync.\n   - **Headless:** no prompts (AD-11). End with the status block. When\n     the core's result carries its own `status` (`setup`, `publish` and\n     `sync-back` do: `complete`, `partial` or `blocked`), relay that\n     `status`, its `reason` and its `artifacts` as they are — never infer\n     the status from the exit code (`setup`, `publish` and `sync-back`\n     exit 0 on `partial`); `stage` and `stage-post` carry theirs too\n     (`stage`: `complete` or `blocked`; `stage-post`: `complete`,\n     `partial` while rows are still unposted, or `blocked`). For `sync`,\n     `normalize` and `status`, whose results carry no `status`: `complete`\n     on exit 0 (report conflicts as `partial` with the conflict list in\n     `reason`), `blocked` on exit 2 with the blocking reason:\n\n     ```json\n     {\"status\": \"complete\", \"intent\": \"tk-studio-plan-sync\", \"artifacts\": [\"_bmad-output\u002Fplanning-artifacts\u002Fplan\u002F\"], \"reason\": null}\n     ```\n\nIf the deterministic core is unrunnable — a tool call denied by permissions, `uv`\u002Fpython 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).\n\n## Rules\n\n- Only this skill (via `lib\u002Fplansync.py`) mints ids or writes canonical\n  frontmatter keys — no other skill, stock or studio, ever does (AD-4).\n- Entity shape questions resolve against `contracts\u002Finterchange\u002Fshape.v1.json`\n  via `lib\u002Finterchange.py` — the single shipped validator.\n- Backend projection (promote \u002F status pull-back) is binding-driven;\n  `bmad-files` means normalize + validate + index with no projection — a\n  first-class no-op, not an error. Every backend, Jira included, is a\n  projection of the canonical files, never authoritative (AD-5); no skill\n  other than this one ever calls a planning backend (AD-4).\n- `plan\u002Findex.md` is generated — a foreign index.md in its place is refused,\n  never overwritten.\n- All paths resolve through `${CLAUDE_PLUGIN_ROOT}`.\n","# tk-studio-plan-sync\n\nThe adapter side of AD-4: stock BMad planning skills stay untouched; this\nskill canonicalizes what they produce. The normalized `_bmad-output\u002F`\nplanning artifacts are the single canonical local representation under every\nbinding, and this skill is the **sole id authority** (EP-\u002FST-\u002FTA-NNN from the\ncommitted per-project counter at `.tk-studio\u002Fplan-counter.yaml`).\n\n## Behavior (both modes)\n\n1. Run the full adapter verb through the plugin root:\n\n   ```bash\n   uv run \"${CLAUDE_PLUGIN_ROOT}\u002Flib\u002Fplansync.py\" sync --directory \u003Cproject-root>\n   ```\n\n   `sync` = normalize → validate → projection → plan index, where only the\n   projection step is binding-driven (resolved from `planning.backend`,\n   AD-15 order; `--backend NAME` is the runtime override). Under\n   `bmad-files` the canonical files are the backend: projection is a clean,\n   first-class no-op (FR14). Under `backlog-md` the projection is pull-back\n   → promote (AD-5): backend status-class changes (status, assignee) land on\n   canonical files first — echo-suppressed against the `external.backlog-md`\n   snapshot, both-changed entities surfaced as **conflicts** for a human,\n   never resolved silently — then canonical entities project into a\n   Backlog.md-compatible `backlog\u002F` (epic → milestone + label linkage;\n   story\u002Ftask → task files, native keys only with the canonical id as the\n   first label — Backlog.md 1.48.0 verifiably drops unknown frontmatter\n   keys; see `kb\u002Fbacklog-md-verified-behavior.md`). Under `jira` (AD-7) the\n   same pull-back → promote round runs against Atlassian Cloud: the\n   **preflight** first proves the API token AND the org-admin API-token\n   toggle in one probe (`GET \u002Fmyself`) and confirms the AD-6 default\n   issue-type mapping (epic → Epic, story → Story, task → Sub-task) against\n   the org's actual scheme; then pull-back ingests backend status\u002Fassignee\n   (echo-suppressed via `external.jira`, both-changed = conflict) and\n   promote creates\u002Fupdates issues (canonical id rides as the first label;\n   status set by transition into the matching Jira status *category*, which\n   keeps mapping round-trip stable). Binding config: `planning.jira.site` +\n   `planning.jira.project_key` (tracked). Credentials ride the environment\n   **only** — never any config file (AD-3): the agent seat's scoped token\n   `TK_ATLASSIAN_AGENT_TOKEN` with `TK_ATLASSIAN_AGENT_EMAIL`, through the\n   `https:\u002F\u002Fapi.atlassian.com\u002Fex\u002Fjira\u002F\u003CTK_ATLASSIAN_CLOUD_ID>` gateway\n   (`\u002Frest\u002Fapi\u002F2` kept); either agent token set without\n   `TK_ATLASSIAN_CLOUD_ID` refuses by name, never the site URL. With\n   `TK_ATLASSIAN_AGENT_TOKEN` unset, the legacy `JIRA_API_TOKEN` plus\n   `JIRA_EMAIL` (or `planning.jira.email`) against the site URL. Auth is\n   API-token, never OAuth (legacy-council ISS-008); any gap blocks with\n   every cause named — a 401 names the token, its email, its expiry and\n   the org toggle; the sandbox proxy's 403 (`Approval required for\n   \u003Chost>:443`) is the network approval step; any other 403 names the\n   missing scope and asks for a new token — never a silent 401 (AD-11).\n   `setup --directory \u003Croot> [--dry-run] [--owner-account-id \u003Cid> |\n   --owner-email \u003Cemail>]` creates the project's tracking from the studio\n   template — the Jira project (key from the project id), issue types Epic\n   and Story, the statuses `Blocked - Awaiting User` and `Block Resolved`\n   with their transition, the \"Needs you\" filter, the Confluence space\n   (`TK_ATLASSIAN_AGENT_CONFLUENCE_TOKEN`, gateway only) and its folders\n   Brief, GDD, Scope of Work, Decisions and Records — recognising each by\n   key first, and records the keys and ids under `planning.jira` and\n   `planning.confluence`. What the API refuses becomes the owner's\n   numbered steps (`owner_steps[]`) and the run ends `partial`; an\n   unregistered project or an absent agent-seat variable ends `blocked`\n   before any call; a dry run that would create anything ends `partial`\n   too (`would_create[]`). `tk-studio-onboard`'s optional tracking step\n   calls it. Payload mapping: `setup: true` runs `plansync.py setup\n   --directory \u003Cdirectory>`; `dry_run` adds `--dry-run`; `owner_account_id`\n   adds `--owner-account-id \u003Cid>`, else `owner_email` adds `--owner-email\n   \u003Cemail>`.\n   `publish --directory \u003Croot> [--dry-run] [--source \u003Ccategory>=\u003Cpath>]\n   [--attachment-max-bytes \u003Cn>]` (Story 31.3) publishes the design pages\n   (brief, GDD, scope of work, decisions — never the records folder) to\n   the folders setup recorded, by the stable title `\u003CFolder>: \u003Cslug>`,\n   Markdown converted to Confluence storage format with images attached,\n   each page ending with a provenance footer (source file, the last commit\n   that touched it, the content hash); an unchanged page is skipped. An\n   image over the per-file ceiling (100 MB assumed unless\n   `--attachment-max-bytes` supplies the site's smaller setting) is refused\n   by name and its page still publishes; `bytes_uploaded` reports the\n   upload against Confluence Free's 2 GB. It writes\n   `.tk-studio\u002Fconfluence-pages.json`, from which the `jira` promote adds a\n   `Design pages:` line to every epic and story; nothing from Confluence\n   changes an entity field (AD-5). An absent agent-seat Confluence variable,\n   no `planning.confluence` binding (\"run `plansync.py setup` first\"), a\n   bad `--source` or a duplicate title ends `blocked` before any call; a\n   category with no folder, a refused page or image, or a dry run that\n   would publish ends `partial`. Payload mapping: `publish: true` runs\n   `plansync.py publish --directory \u003Cdirectory>`; `dry_run` adds\n   `--dry-run`; `attachment_max_bytes` (the site's Attachment maximum\n   size, in bytes) adds `--attachment-max-bytes \u003Cn>` — the effective\n   ceiling is the smaller of it and 100 MB, and the result's `notes[]`\n   says which was used. An image outside the project root (an absolute\n   path, a non-http(s) scheme, a `..\u002F` escape or a symlink out) is refused\n   by name before any read and its page still publishes.\n   `sync-back --directory \u003Croot> [--dry-run]` (Story 31.4) pulls the\n   project's Atlassian state into local memory so that no agent queries\n   Atlassian live for context: each tracked issue's status (canonical by\n   name first — `Blocked - Awaiting User` and `Block Resolved` are\n   `blocked` — then by status category; the Jira original kept under\n   `external.jira`, `updated` stamped; no other entity field changes, and\n   `plan\u002Findex.md` is regenerated local-only when a status changed), its comments\n   append-only into `_bmad-output\u002Ftracking\u002F\u003CKEY>\u002Fcomments.jsonl` (a\n   comment seen twice is written once; an edit appends a line), its\n   attachments as links into `attachments.jsonl` (never downloaded or\n   uploaded), and every owner-authored page of the recorded Confluence\n   space into `kb\u002Fconfluence\u002F\u003Cslug>.md` with a provenance header (read-only:\n   a local edit is overwritten and named in `overwritten[]`). Story 32.4:\n   each engagement's scope page (the record's `scope_page.id`, agent-\n   published, so never in the owner-page mirror) is read by id; a version\n   above the record's `scope_page.version` is mirrored as Markdown into\n   `kb\u002Fconfluence\u002F\u003Cslug>.md` (the provenance header plus `engagement:\n   ENG-NNN`; its state under `sync-state.json` `engagement_pages`) and,\n   while the engagement is `scoping`, replaces its `scope.md` wholesale\n   (the page is authoritative, D9) and merges the version into the record;\n   in any other state only the mirror is written and `notes[]` says\n   `scope edit of ENG-NNN not applied: state \u003Cs> (send revise)` once per\n   version (no state moves). A page gone (404) is a note; counts gain\n   `engagement_pages_mirrored` and `scopes_replaced`. One paged JQL\n   search per tick, never a GET per issue — only an issue whose\n   `comment.total` exceeds the comments the search returned pages\n   `GET \u002Frest\u002Fapi\u002F2\u002Fissue\u002F{key}\u002Fcomment` (overflow only); the cursor in `_bmad-output\u002Ftracking\u002Fsync-state.json`\n   moves only after every page was read. Nothing local is promoted back.\n   The result names `counts`, `newest_comment`, `applied[]`,\n   `conflicts[]`, `overwritten[]`, `rate_limit`, `notes[]` and `written[]`.\n   No `planning.jira` binding or an absent Jira variable ends `blocked`\n   before any call; a failed preflight (unreachable, deactivated, the\n   401\u002F403 split, or a preflight answered with another, non-auth status:\n   run case `error`) ends `blocked`; an absent\n   `TK_ATLASSIAN_AGENT_CONFLUENCE_TOKEN` (the Jira half still runs), an\n   unrecorded `planning.confluence.space_id` (the mirror skipped), no\n   recorded owner accountId, a conflict, or a 429 or error that\n   interrupted a read ends `partial`. The shipped cron job\n   `atlassian-sync-back` runs it every 10 minutes. Payload mapping:\n   `sync_back: true` runs `plansync.py sync-back --directory \u003Cdirectory>`;\n   `dry_run` adds `--dry-run` (reads only, writes nothing).\n\n   `stage` (Story 35.8) writes the story spec's append-only `## Stage\n   Log` table — one row per stage occurrence, the columns `stage`, `pass`,\n   `started`, `ended`, `session_id`, `model`, `effort`, `tokens_in`,\n   `tokens_out`, `cost_usd`, `outcome` (`—` for empty; elapsed is never\n   stored, only derived) — after `## Consult Log` (else before `## Auto Run\n   Result`). The planner brackets its plan session with\n   `stage --start --story \u003Ckey> --stage plan --model \u003Cm> --effort \u003Ce>` and\n   `stage --stop --story \u003Ckey> --stage plan` (the epic's planning:\n   `--entity EP-NNN`); `--stop` with no open row is a refusal naming it. The\n   supervisor appends its legs with `stage --append --story \u003Ckey>\n   --row-json \u003Crows>`; the engine's studio-pipeline `post_session` hook\n   writes each pass with `stage --from-pass` (never by hand). A row written\n   before the spec exists waits in `\u003Cspec_folder>\u002Fstages\u002F\u003Ckey>.jsonl` and is\n   flushed by the next write; a row already on record is skipped\n   (`appended: 0`). `stage-post --directory \u003Croot> --id ST-NNN [--story\n   \u003Ckey>] [--dry-run]` mirrors the rows onto the story's Jira issue (the\n   agent seat, through the gateway): `Stage \u003Cname> [pass n] started —\n   \u003Cstamp>; model: X; effort: Y [stage:\u003Ckey> start]`, `… finished — \u003Cstamp>;\n   model: X; effort: Y; tokens: in\u002Fout; cost: $Z [stage:\u003Ckey> stop]` and a\n   worklog of the derived span (none under Jira's 60 s minimum: `worklog:\n   \"skipped: span \u003C60s\"`), each recorded in\n   `_bmad-output\u002Ftracking\u002Fstage-posts.json` and never posted twice (the\n   markers are looked up first). Not bound to Jira: nothing posted\n   (`posted: \"skipped: not bound\"`). `unposted` counts the rows not yet\n   mirrored (buffered, open, or a post missing): while any remain it ends\n   `partial`, `ok: false`, `retryable: true`; a failed Jira call ends\n   `blocked`, `retryable: true` — the supervisor retries both next pass; a\n   refusal (no `external.jira.key`, no agent token) carries no `retryable`\n   and is not retried. `stage --from-pass --repo-root \u003Croot>` also flushes\n   the planner's buffer left under the project root. Both end with the\n   status block.\n   `deferred mint --directory \u003Croot> [--count N] [--dry-run]` (Story 37.1) is\n   the deferred-work ledger's one id source: the operator's docs pass runs it,\n   then writes its entries under the answered `ids`, never minting from the\n   ledger's highest heading. It reads `next.deferred-work` in\n   `.tk-studio\u002Fplan-counter.yaml` (seeded when absent, one past the highest\n   `DW-N` in the ledger), bumps it, keeps the ledger header's marker line and\n   names both files in `written[]`; the engine's harvest reads the marker, and\n   the studio-pipeline `pre_commit` hook bumps the counter after a harvest. It\n   and `ledger-resolve` refuse a duplicate `### DW-N:` heading by name\n   (`LedgerDuplicateId`), and both end with the status block. An entry closed\n   from inside a run, where no PR number exists yet, reads `by Story N.M`,\n   never `by this story's PR`, which `test_no_placeholder_pr_number_remains`\n   fails.\n\n   `normalize --directory \u003Croot>` runs the canonicalization pass\n   alone. Add `--dry-run` to preview without writing (under `jira` a\n   dry-run never contacts the backend). The normalize pass:\n   - derives\u002Frepairs one canonical entity file per epic\u002Fstory under\n     `_bmad-output\u002Fplanning-artifacts\u002Fplan\u002F\u003CID>.md` from `epics.md` (matched\n     across runs by the `source` key — ids never move; `epics.md` itself is\n     never rewritten);\n   - mints missing ids from the committed counter (document order, counter\n     persisted atomically before entity files — a crash leaves a gap, never a\n     duplicate);\n   - stamps `canonical_id` into matching `implementation-artifacts\u002Fstory-N.M.md`\n     files textually (one line; every other byte preserved);\n   - pulls story status from `sprint-status.yaml` when present, mapped onto\n     the closed canonical enum (unmappable states reported, never guessed).\n\n   The result names **every file the run wrote** — `written[]` at both\n   levels (counter, entity files, story-file stamps, projection writes with\n   their canonical snapshot rewrites, index) plus `removed[]` (projection\n   files replaced on rename), with `normalize.counter` naming the committed\n   id counter — so commit staging derives from the response alone: stage\n   exactly the `written[]` and `removed[]` paths, nothing recalled by hand\n   (EP-017, PROP-020). A sync blocked at the projection still names\n   normalize's landed writes.\n\n2. Blocking conditions (exit 2, nothing written):\n   - **duplicate ids** anywhere under `_bmad-output\u002F` — both paths are named;\n     a human renumbers, then sync reruns (AD-4: never auto-pick a survivor);\n   - **invalid present values** in canonical frontmatter (bad status, id,\n     dates) — repair fills only *missing* keys, it never rewrites a present\n     value it cannot trust (AD-3 refuse-to-guess);\n   - **jira preflight failure** — missing binding config or credentials,\n     401\u002F403 (token or org toggle), or an issue-type scheme missing a\n     default-mapping target — each gap named (AD-7\u002FAD-11).\n   - **publish refusal** — an absent `TK_ATLASSIAN_AGENT_EMAIL`,\n     `TK_ATLASSIAN_AGENT_CONFLUENCE_TOKEN` or `TK_ATLASSIAN_CLOUD_ID`, no\n     `planning.confluence` binding, a bad `--source`, or two sources with\n     one title — each named, no Atlassian call.\n   - **sync-back refusal** — no `planning.jira` binding or an absent Jira\n     variable — each named, no Atlassian call.\n   - **stage refusal** — `stage --stop` with no open row, several specs\n     matching the story, or a row field outside the Stage Log's columns;\n     `stage-post` with an absent agent-seat variable or an entity with no\n     `external.jira.key` — each named, no Atlassian call.\n   - **deferred refusal** — `LedgerDuplicateId: DW-N at lines a and b`, a bad\n     `next.deferred-work`, a bad `--count` or no ledger — named, nothing\n     written.\n\n3. Report:\n   - **Attended:** summarize actions (created\u002Frepaired\u002Funchanged, minted\n     ids, stamps, notes); on a block, show the exact file paths and what to\n     fix — never fix ids silently.\n   - On **conflicts** (both sides changed since the last sync): list each\n     conflicted entity with both values and both file paths; the human picks\n     a side by editing one of them, then reruns sync.\n   - **Headless:** no prompts (AD-11). End with the status block. When\n     the core's result carries its own `status` (`setup`, `publish` and\n     `sync-back` do: `complete`, `partial` or `blocked`), relay that\n     `status`, its `reason` and its `artifacts` as they are — never infer\n     the status from the exit code (`setup`, `publish` and `sync-back`\n     exit 0 on `partial`); `stage` and `stage-post` carry theirs too\n     (`stage`: `complete` or `blocked`; `stage-post`: `complete`,\n     `partial` while rows are still unposted, or `blocked`). For `sync`,\n     `normalize` and `status`, whose results carry no `status`: `complete`\n     on exit 0 (report conflicts as `partial` with the conflict list in\n     `reason`), `blocked` on exit 2 with the blocking reason:\n\n     ```json\n     {\"status\": \"complete\", \"intent\": \"tk-studio-plan-sync\", \"artifacts\": [\"_bmad-output\u002Fplanning-artifacts\u002Fplan\u002F\"], \"reason\": null}\n     ```\n\nIf the deterministic core is unrunnable — a tool call denied by permissions, `uv`\u002Fpython 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).\n\n## Rules\n\n- Only this skill (via `lib\u002Fplansync.py`) mints ids or writes canonical\n  frontmatter keys — no other skill, stock or studio, ever does (AD-4).\n- Entity shape questions resolve against `contracts\u002Finterchange\u002Fshape.v1.json`\n  via `lib\u002Finterchange.py` — the single shipped validator.\n- Backend projection (promote \u002F status pull-back) is binding-driven;\n  `bmad-files` means normalize + validate + index with no projection — a\n  first-class no-op, not an error. Every backend, Jira included, is a\n  projection of the canonical files, never authoritative (AD-5); no skill\n  other than this one ever calls a planning backend (AD-4).\n- `plan\u002Findex.md` is generated — a foreign index.md in its place is refused,\n  never overwritten.\n- All paths resolve through `${CLAUDE_PLUGIN_ROOT}`.\n",{"name":5,"description":7},"main","ecd23b3c0458cd511812f643d9111e3d7c8235f4","plugins\u002Ftk-studio\u002Fskills\u002Ftk-studio-plan-sync","https:\u002F\u002Fgithub.com\u002Fthkennedy\u002Ftk-studio","https:\u002F\u002Fgithub.com\u002Fthkennedy","https:\u002F\u002Ftimothyhkennedy.com","Just a guy who loves making tools, automation and games.","2026-11-10 20:38:16",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add thkennedy\u002Ftk-studio --skill tk-studio-plan-sync",{"tool":38,"command":39},"bunx","bunx skills add thkennedy\u002Ftk-studio --skill tk-studio-plan-sync",{"tool":41,"command":42},"pnpm","pnpm dlx skills add thkennedy\u002Ftk-studio --skill tk-studio-plan-sync","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fthkennedy\u002Ftk-studio\u002Fblob\u002Fmain\u002Fplugins\u002Ftk-studio\u002Fskills\u002Ftk-studio-plan-sync\u002FSKILL.md",true,[46],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"customize.toml","OTHER","其他",512,"https:\u002F\u002Fgithub.com\u002Fthkennedy\u002Ftk-studio\u002Fblob\u002Fmain\u002Fplugins\u002Ftk-studio\u002Fskills\u002Ftk-studio-plan-sync\u002Fcustomize.toml",[53,60,67,74,81,88],{"skillNo":54,"name":55,"nameZh":6,"description":56,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":57,"categories":58,"keywords":59,"publishedAt":19},"01M79RYSQ8C3MWDFTDSRAYFJYA","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.","https:\u002F\u002Fgithub.com\u002Fthkennedy\u002Ftk-studio\u002Fblob\u002Fmain\u002Fplugins\u002Ftk-studio\u002Fskills\u002Ftk-studio-track\u002FSKILL.md",[],[],{"skillNo":61,"name":62,"nameZh":6,"description":63,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":64,"categories":65,"keywords":66,"publishedAt":19},"01M79RYMVE0031EV5B64MBGD8V","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\u002Fbudget trigger says the session must split.","https:\u002F\u002Fgithub.com\u002Fthkennedy\u002Ftk-studio\u002Fblob\u002Fmain\u002Fplugins\u002Ftk-studio\u002Fskills\u002Ftk-studio-session\u002FSKILL.md",[],[],{"skillNo":68,"name":69,"nameZh":6,"description":70,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":71,"categories":72,"keywords":73,"publishedAt":19},"01M79RYFM9ATWHM6HAXJ3D19WV","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.","https:\u002F\u002Fgithub.com\u002Fthkennedy\u002Ftk-studio\u002Fblob\u002Fmain\u002Fplugins\u002Ftk-studio\u002Fskills\u002Ftk-studio-research\u002FSKILL.md",[],[],{"skillNo":75,"name":76,"nameZh":6,"description":77,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":19},"01M79RYA1AWZZF83KBHGR6JDN3","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\".","https:\u002F\u002Fgithub.com\u002Fthkennedy\u002Ftk-studio\u002Fblob\u002Fmain\u002Fplugins\u002Ftk-studio\u002Fskills\u002Ftk-studio-report\u002FSKILL.md",[],[],{"skillNo":82,"name":83,"nameZh":6,"description":84,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":85,"categories":86,"keywords":87,"publishedAt":19},"01M79RY33VMYR5YNPVFKWRNW9S","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\".","https:\u002F\u002Fgithub.com\u002Fthkennedy\u002Ftk-studio\u002Fblob\u002Fmain\u002Fplugins\u002Ftk-studio\u002Fskills\u002Ftk-studio-playable-judge\u002FSKILL.md",[],[],{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":19},"01M79RXRDV34SQ7160973XEZ1A","tk-studio-orchestrator","The studio's front door — resolve who you are (role, per-user store), what this project needs (confirmed working_set.\u003Crole>), 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.","https:\u002F\u002Fgithub.com\u002Fthkennedy\u002Ftk-studio\u002Fblob\u002Fmain\u002Fplugins\u002Ftk-studio\u002Fskills\u002Ftk-studio-orchestrator\u002FSKILL.md",[],[]]