testdouble avatar

han-atlassian

Atlassian-facing extensions to the Han suite. Adds markdown-to-confluence, which publishes a local Markdown file to a user-specified Confluence page; project-documentation-to-confluence, which runs the han-documentation project-documentation skill and then publishes the result there; investigate-to-confluence, which runs the core investigate skill and publishes the resulting investigation report there; code-overview-to-confluence, which runs the core code-overview skill and publishes the resulting overview there; plan-a-feature-to-confluence, which runs the core plan-a-feature skill and publishes the spec and its companion artifacts there as a page tree; and work-items-to-jira, which creates one Jira ticket per slice from a work-items file. All work through the Atlassian MCP server. Depends on han-core, han-documentation, han-planning, and han-coding (its wrapper skills run skills from each and its wrapped skills dispatch the shared han-core agents), and on han-communication (its wrapped prose-producing skills source the shared readability standard), and requires a configured Atlassian MCP server. Opt-in: installed on its own, not pulled in by the han meta-plugin.

version
2.3.1
GitHub stars
352

Install

/plugin install han-atlassian@han

Run it inside Claude Code after adding the marketplace with /plugin marketplace add testdouble/han.

Contents

Discovered from source

Skills 6

Project Context

  • personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
  • project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Code Overview to Confluence

This skill runs a progressive-disclosure code overview with the core han-coding:code-overview skill, lets the user review the resulting overview, and then publishes it to a Confluence location that the user must specify. It is a thin orchestrator: the overview work belongs to han-coding:code-overview, and the publishing work belongs to han-atlassian:markdown-to-confluence. This skill only validates its inputs, runs the overview to a scratch file, gets the user's review and publish choice, and hands the file to the publisher.

han-coding:code-overview produces a single scratch file (the overview: what the code does, how it flows, where to start, and — in PR mode — what changed and what to watch when reviewing). It does not produce companion artifacts, so this skill publishes that one file as a single Confluence page — the single-page sibling of han-atlassian:investigate-to-confluence and han-atlassian:project-documentation-to-confluence, not the parent-plus-children tree of han-atlassian:plan-a-feature-to-confluence.

The five steps below are the whole skill. It does not resolve Confluence pages or call the Confluence MCP create/update tools itself; han-atlassian:markdown-to-confluence owns all of that.

Step 1: Validate Inputs

Confirm the skill has everything it needs before spending effort on an overview:

  1. Atlassian MCP reachable (hard requirement). Call mcp__claude_ai_Atlassian__getAccessibleAtlassianResources to confirm the server is connected and retrieve the cloud ID(s). If the tool is not available, the call errors, or it returns no accessible resources (typically an authentication or configuration problem), stop immediately. Tell the user this skill requires the Atlassian MCP server to be installed, configured, and authenticated, and that they can re-run it once it is connected. Do not fall back to a local-only run; for a local-only overview, point them at han-coding:code-overview. This preflight runs first so a missing server fails before any overview work begins.
  2. A target to overview (optional). The target may be a file, directory, symbol, or pull request reference, and an optional size (small, medium, or large). All of this — together with the relevant conversation context — is forwarded to han-coding:code-overview verbatim in Step 2. A target is not required: with none given, han-coding:code-overview defaults to the current branch's changes. Do not resolve or classify the target here; that is han-coding:code-overview's job.
  3. A Confluence destination. Confirm the request provides a target location: a Confluence page URL (to update that page, or create a child under it), or a space (key or name) plus an optional parent page. If none was provided, ask for one with AskUserQuestion, explaining plainly that the skill needs an exact destination because it does not search Confluence. Do not resolve the page tree here — only confirm a location was given. Carry it through to Step 5; han-atlassian:markdown-to-confluence resolves it.

Step 2: Produce the Overview to a Scratch File

Invoke the han-coding:code-overview skill with the Skill tool, forwarding all provided context verbatim: the target (file, directory, symbol, or PR reference, or none for the current branch's changes), any size the user gave, and the relevant conversation context. Do not summarize, trim, or reinterpret the user's context; pass it through so han-coding:code-overview runs exactly as it would on its own (target resolution, mode and size selection, parallel han-core:codebase-explorer exploration, synthesis, and the readability-review pass).

han-coding:code-overview already writes its overview to a scratch file outside the repository and changes no code — except add one explicit instruction: it must write the overview to an explicit scratch path this skill names (for example ${TMPDIR:-/tmp}/code-overview-<slug>.md). Passing the path explicitly keeps the file where this skill expects it even when either .han/config.md configures an output directory, because explicit input outranks the config (see ../../references/config-rule.md). Capture the exact scratch-file path it wrote. That markdown file is the source content for Confluence. Proceed to Step 3 once it finishes.

Step 3: Show the File for Review

Tell the user the exact scratch-file path of the generated overview so they can open and review it before deciding whether to publish. State plainly that the content has not been published anywhere yet, and that no code was changed.

Step 4: Confirm the Publish Choice

Publishing to Confluence puts the content where other people can see it, so require an explicit choice before posting. Ask with AskUserQuestion, restating the scratch-file path and the Confluence destination the user provided. Offer three options, listing the draft option first as the recommended default:

  • "Yes, save it as a draft to edit later (recommended)" — published as an unpublished Confluence draft for the user to review, edit, and publish themselves. This is the default. (Publish mode: draft.)
  • "Yes, publish it live now" — the page goes live immediately. (Publish mode: live.)
  • "No, keep it local only" — nothing is published.

If the user keeps it local only, stop. Report the scratch-file path and state clearly that nothing was published to Confluence. Otherwise, record the chosen publish mode (draft or live) for Step 5.

Step 5: Publish with markdown-to-confluence

Invoke the han-atlassian:markdown-to-confluence skill with the Skill tool, forwarding:

  • the scratch-file markdown path captured in Step 2,
  • the Confluence destination the user provided in Step 1 (the page URL, or the space plus optional parent page), passed through verbatim, and
  • the publish mode the user chose in Step 4 (draft or live), stated explicitly so han-atlassian:markdown-to-confluence does not re-ask.

han-atlassian:markdown-to-confluence resolves the location, reads the file, creates or updates the page in the chosen mode, handles Mermaid diagrams, and reports the resulting page URL. Relay its result to the user: the created or updated page's URL and whether it went live or was saved as a draft. If publishing fails, report the error and confirm the scratch-file markdown is unchanged and intact.

Verification

  1. Inputs validated: the Atlassian server was reachable and a Confluence location was provided — or the skill stopped before doing any work.
  2. Overview produced to a scratch file: han-coding:code-overview ran with the full forwarded context, wrote the overview to a scratch file whose path was captured, and changed no code.
  3. User reviewed: the scratch-file path was shown to the user before any publish.
  4. Explicit choice obtained: the user chose draft, live, or local-only.
  5. Publish delegated and reported: when the user chose to publish, han-atlassian:markdown-to-confluence created or updated the page in the chosen mode and its URL was relayed; when the user declined, only the scratch file exists.

Project Context

  • personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
  • project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Investigate to Confluence

This skill runs an evidence-based investigation with the core han-coding:investigate skill, lets the user review the resulting report, and then publishes it to a Confluence location that the user must specify. It is a thin orchestrator: the investigation work belongs to han-coding:investigate, and the publishing work belongs to han-atlassian:markdown-to-confluence. This skill only validates its inputs, runs the investigation to a temporary file, gets the user's review and publish choice, and hands the file to the publisher.

han-coding:investigate produces a single report file (the investigation plan: problem statement, evidence summary, root cause analysis, planned fix, validation results, and summary). It does not produce companion artifacts, so this skill publishes that one file as a single Confluence page — the single-page sibling of han-atlassian:project-documentation-to-confluence, not the parent-plus-children tree of han-atlassian:plan-a-feature-to-confluence.

The five steps below are the whole skill. It does not resolve Confluence pages or call the Confluence MCP create/update tools itself; han-atlassian:markdown-to-confluence owns all of that.

Step 1: Validate Inputs

Confirm the skill has everything it needs before spending effort on an investigation:

  1. Atlassian MCP reachable (hard requirement). Call mcp__claude_ai_Atlassian__getAccessibleAtlassianResources to confirm the server is connected and retrieve the cloud ID(s). If the tool is not available, the call errors, or it returns no accessible resources (typically an authentication or configuration problem), stop immediately. Tell the user this skill requires the Atlassian MCP server to be installed, configured, and authenticated, and that they can re-run it once it is connected. Do not fall back to a local-only run; for a local-only investigation, point them at han-coding:investigate. This preflight runs first so a missing server fails before any investigation work begins.
  2. A symptom or question to investigate. Confirm the request names a bug, failure, error, integration, or unexpected behavior to investigate. This — together with any relevant conversation context — is forwarded to han-coding:investigate verbatim in Step 2. If the request is too thin to start, let han-coding:investigate run its own investigation rather than pre-empting it here.
  3. A Confluence destination. Confirm the request provides a target location: a Confluence page URL (to update that page, or create a child under it), or a space (key or name) plus an optional parent page. If none was provided, ask for one with AskUserQuestion, explaining plainly that the skill needs an exact destination because it does not search Confluence. Do not resolve the page tree here — only confirm a location was given. Carry it through to Step 5; han-atlassian:markdown-to-confluence resolves it.

Step 2: Produce the Investigation Report to a Temporary File

Invoke the han-coding:investigate skill with the Skill tool, forwarding all provided context verbatim: the symptom or question, any known reproduction steps or error messages, any suspected entry points, and the relevant conversation context. Do not summarize, trim, or reinterpret the user's context; pass it through so han-coding:investigate runs exactly as it would on its own (parallel investigators, conditional specialist analysts, adversarial validation, and the final report) — except add two explicit instructions:

  • It must write the resulting investigation report to a file under /tmp/ (for example /tmp/<symptom-slug>.md) rather than into the project's docs or plans directory. This keeps the working report out of the repo until the user decides to publish it, and because the path is explicit input it outranks any output-directory the project or personal .han/config.md supplies (see ../../references/config-rule.md).
  • It must stop after producing the report. han-coding:investigate normally ends by presenting the plan for approval and can trigger the fix's implementation on approval; this skill wants the report only, so instruct it not to implement the fix or change any code — this skill publishes findings, it does not ship them.

Let han-coding:investigate complete its full investigation process. Capture the exact /tmp/ file path it wrote. That markdown file is the source content for Confluence. Proceed to Step 3 once it finishes.

Step 3: Show the File for Review

Tell the user the exact /tmp/ path of the generated investigation report so they can open and review it before deciding whether to publish. State plainly that the content has not been published anywhere yet, and that no code was changed.

Step 4: Confirm the Publish Choice

Publishing to Confluence puts the content where other people can see it, so require an explicit choice before posting. Ask with AskUserQuestion, restating the /tmp/ file path and the Confluence destination the user provided. Offer three options, listing the draft option first as the recommended default:

  • "Yes, save it as a draft to edit later (recommended)" — published as an unpublished Confluence draft for the user to review, edit, and publish themselves. This is the default. (Publish mode: draft.)
  • "Yes, publish it live now" — the page goes live immediately. (Publish mode: live.)
  • "No, keep it local only" — nothing is published.

If the user keeps it local only, stop. Report the /tmp/ report path and state clearly that nothing was published to Confluence. Otherwise, record the chosen publish mode (draft or live) for Step 5.

Step 5: Publish with markdown-to-confluence

Invoke the han-atlassian:markdown-to-confluence skill with the Skill tool, forwarding:

  • the /tmp/ markdown file path captured in Step 2,
  • the Confluence destination the user provided in Step 1 (the page URL, or the space plus optional parent page), passed through verbatim, and
  • the publish mode the user chose in Step 4 (draft or live), stated explicitly so han-atlassian:markdown-to-confluence does not re-ask.

han-atlassian:markdown-to-confluence resolves the location, reads the file, creates or updates the page in the chosen mode, handles Mermaid diagrams, and reports the resulting page URL. Relay its result to the user: the created or updated page's URL and whether it went live or was saved as a draft. If publishing fails, report the error and confirm the /tmp/ markdown file is unchanged and intact.

Verification

  1. Inputs validated: the Atlassian server was reachable, a symptom or question to investigate was present, and a Confluence location was provided — or the skill stopped before doing any work.
  2. Report produced to /tmp: han-coding:investigate ran with the full forwarded context, wrote the investigation report to a /tmp/ file whose path was captured, and did not implement the fix or change any code.
  3. User reviewed: the /tmp/ path was shown to the user before any publish.
  4. Explicit choice obtained: the user chose draft, live, or local-only.
  5. Publish delegated and reported: when the user chose to publish, han-atlassian:markdown-to-confluence created or updated the page in the chosen mode and its URL was relayed; when the user declined, only the /tmp/ report exists.

Project Context

  • personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
  • project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Markdown to Confluence

This skill takes one local Markdown file and publishes it to a Confluence location that the user must specify — creating a new page or updating an existing one through the Atlassian MCP server. It owns everything about the posting itself: the MCP preflight, resolving the destination, reading the file, the create-or-update call, and reporting the result. It does not write the Markdown; the caller supplies an existing file.

Callers that supply an explicit publish mode and location (for example han-atlassian:project-documentation-to-confluence) run this skill straight through without re-asking. Invoked on its own with pieces missing, it asks for them and defaults to a safe unpublished draft.

Step 0: Atlassian MCP Preflight (hard requirement)

This skill cannot run without a configured and connected Atlassian MCP server.

Confirm the server is reachable by calling mcp__claude_ai_Atlassian__getAccessibleAtlassianResources to retrieve the cloud ID(s). If the tool is not available, the call errors, or it returns no accessible resources (typically an authentication or configuration problem), stop immediately. Tell the user this skill requires the Atlassian MCP server to be installed, configured, and authenticated, and that they can re-run the skill once it is connected.

If more than one cloud / site is accessible, note which sites are available; you will confirm the correct one while resolving the location in Step 2.

Step 1: Confirm the Source Markdown File

Resolve the Markdown file path from the arguments or conversation. Read it and confirm it exists and has content. If no file path was provided, or the path does not resolve to a readable file, ask the user for the path with AskUserQuestion and do not proceed without one. This is the exact content that will be posted; do not rewrite, summarize, or restructure it.

A body may legitimately contain embedded Confluence storage macros mixed into the Markdown — for example, an orchestrating skill such as han-atlassian:plan-a-feature-to-confluence rewrites its cross-page links into title-based page-link macros (the <ac:link><ri:page ri:content-title="..."/>…</ac:link> form, link body included) before handing the file over. Post these verbatim along with the rest of the body; do not strip or escape them.

Step 2: Resolve the Target Confluence Location (required)

This skill does not search Confluence for the right place. A typical Confluence instance is large and full of duplicate or similarly-named pages, so guessing the destination is unreliable. The user must name the exact location.

  1. Find a location in the request. Check the arguments and conversation for either of:
    • a Confluence page URL (to update that page, or to create a child page under it), or
    • a space (key or name) plus an optional parent page (title, ID, or URL).
  2. If no location was provided, ask for one. Use AskUserQuestion to request it, and explain plainly that the skill needs an exact destination because it does not search Confluence. Offer both accepted forms (a page URL, or a space plus parent page). This is required: do not proceed without a location.
  3. Resolve the location concretely now, so failures surface early. Use the cloud ID from Step 0 for every call.
    • From a page URL: extract the page ID from the /pages/<id>/ segment and call mcp__claude_ai_Atlassian__getConfluencePage to confirm it exists and to read its space and title. Then determine the intent: update that page, or create a new child page under it. If the user did not already say, ask with AskUserQuestion.
    • From a space (+ parent): call mcp__claude_ai_Atlassian__getConfluenceSpaces to resolve the space ID from the key or name. If a parent page was named, find it with mcp__claude_ai_Atlassian__getPagesInConfluenceSpace or mcp__claude_ai_Atlassian__getConfluencePageDescendants (or by page ID/URL) to get the parent page ID. With no parent, the new page is created at the space root.
  4. Record the resolved target: cloud ID, space (ID + human name), parent page ID (if any), existing page ID (if updating), the mode (create a new page, or update an existing one), and the intended page title. If updating, default the title to the existing page's title unless the user asked to rename it.

Step 3: Determine the Publish Mode

The publish mode controls whether the page goes live or is saved as an unpublished draft.

  • If the caller supplied an explicit mode (draft or live), use it. A caller that already confirmed the choice with the user (such as han-atlassian:project-documentation-to-confluence) passes the mode through; do not ask again.
  • If no mode was supplied, default to draft so nothing is published live unintentionally. The user can re-run for live, or you may confirm with AskUserQuestion whether to save a draft (recommended default) or publish live now.

Step 4: Publish to Confluence

Read the Markdown file from Step 1 and publish it with the Atlassian MCP server. The Confluence MCP tools accept Markdown directly via contentFormat: "markdown", so post the document body as-is — no manual conversion to storage/XHTML is needed. Any embedded storage macros (such as the ac:link page-link macros described in Step 1) ride along in the same body; post them verbatim.

Apply the publish mode from Step 3 with the create/update tool's status parameter: draft → status: "draft" (unpublished draft), live → status: "current" (immediately visible). Confirm the exact field against the tool's input schema when you call it, and use whatever the tool exposes for draft-vs-published.

  • Create mode: call mcp__claude_ai_Atlassian__createConfluencePage with the cloud ID, space ID, title, the markdown body, contentFormat: "markdown", the chosen status ("draft" or "current"), and the parent page ID when one was resolved.
  • Update mode: call mcp__claude_ai_Atlassian__getConfluencePage first to read the current page (for its version and existing content), then call mcp__claude_ai_Atlassian__updateConfluencePage with the cloud ID, page ID, title, the markdown body, contentFormat: "markdown", and the chosen status. If the user chose draft for a page that is already published and the tool cannot hold an unpublished draft over a live page, do not silently publish it live: tell the user, and ask whether to publish the update live or keep the changes local only.

Diagram note: Markdown produced by Han's documentation skills emits Mermaid diagrams in fenced mermaid code blocks. Confluence does not render Mermaid natively without a Mermaid macro, so these blocks publish as code, not rendered diagrams. Leave them intact — do not silently strip them — and tell the user the diagrams posted as Mermaid source, in case their space has a macro that renders them or they want to convert them by hand.

On success, report the created or updated page's URL, and state whether it was published live or saved as a draft. For a draft, make clear the user still needs to review and publish it in Confluence. On failure, report the error and confirm the source Markdown file is unchanged and intact.

Step 5: Verification

  1. MCP preflight passed: the Atlassian server was reachable, or the skill stopped before doing any work.
  2. Source file confirmed: a readable Markdown file was supplied and read.
  3. Location was user-specified: the destination came from the user, never from an automated Confluence search.
  4. Publish reported: the page was created or updated in the chosen mode (live or draft) and its URL was returned.

Project Context

  • personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
  • project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Plan a Feature to Confluence

This skill builds a feature specification with the core han-planning:plan-a-feature skill, lets the user review the result, and then publishes it to a Confluence location that the user must specify. It is a thin orchestrator: the planning work belongs to han-planning:plan-a-feature, and the publishing work belongs to han-atlassian:markdown-to-confluence. This skill only validates its inputs, runs the planning skill to a temporary folder, gets the user's review and publish choice, and hands each file to the publisher.

han-planning:plan-a-feature produces a small set of files — the primary feature-specification.md plus companion artifacts under artifacts/ (the decision log, the team findings, and a lazily-created technical-notes file). This skill publishes the spec as a parent page and each companion artifact as a child page beneath it, so the whole plan lands in Confluence as one small page tree. The files cross-reference each other with relative links that do not resolve once each file is its own Confluence page. Because this skill decides every page's title up front, it rewrites those cross-file links into Confluence title-based page-link macros (the <ac:link><ri:page ri:content-title="..."/>…</ac:link> form; Step 5 gives the exact macro to emit, link body and all) before creating any page — these resolve by title at view time, so no page URL or ID has to exist first. That collapses publishing to a single create pass: there is no separate relink-and-update pass, and each page is created exactly once.

The six steps below are the whole skill. It does not resolve Confluence pages or call the Confluence MCP create/update tools itself; han-atlassian:markdown-to-confluence owns all of that.

Step 1: Validate Inputs

Confirm the skill has everything it needs before spending effort producing a plan:

  1. Atlassian MCP reachable (hard requirement). Call mcp__claude_ai_Atlassian__getAccessibleAtlassianResources to confirm the server is connected and retrieve the cloud ID(s). If the tool is not available, the call errors, or it returns no accessible resources (typically an authentication or configuration problem), stop immediately. Tell the user this skill requires the Atlassian MCP server to be installed, configured, and authenticated, and that they can re-run it once it is connected. Do not fall back to a local-only run; for local-only planning, point them at han-planning:plan-a-feature. This preflight runs first so a missing server fails before any planning work begins.
  2. A feature to plan. Confirm the request names a feature, capability, or system behavior to specify. This — together with the size argument and any relevant conversation context — is forwarded to han-planning:plan-a-feature verbatim in Step 2. If the request is too thin to start, let han-planning:plan-a-feature run its own interview; do not pre-empt it here.
  3. A Confluence destination. Confirm the request provides a target location: a Confluence page URL (to update that page, or create the spec as a child under it), or a space (key or name) plus an optional parent page. If none was provided, ask for one with AskUserQuestion, explaining plainly that the skill needs an exact destination because it does not search Confluence. Do not resolve the page tree here — only confirm a location was given. Carry it through to Step 5; han-atlassian:markdown-to-confluence resolves it.

Step 2: Produce the Plan to a Temporary Folder

Invoke the han-planning:plan-a-feature skill with the Skill tool, forwarding all provided context verbatim: the size argument (if the user passed small, medium, or large), the feature description, any known constraints or entry points, and the relevant conversation context. Do not summarize, trim, or reinterpret the user's context; pass it through so han-planning:plan-a-feature runs exactly as it would on its own — interview, review team, finding resolution, and plan-synthesizer synthesis included — except add one explicit instruction: it must write its output folder under /tmp/ (for example /tmp/<feature-slug>/) rather than into the repo's docs directory, and it should not prompt the user to choose or confirm an output location, because this skill owns that decision. This keeps the working plan out of the repo until the user decides to publish it, and because the path is explicit input it outranks any output-directory the project or personal .han/config.md supplies (see ../../references/config-rule.md).

Let han-planning:plan-a-feature complete its full process. Capture the exact /tmp/ paths of every file it wrote:

  • /tmp/<feature-slug>/feature-specification.md — the primary spec (always written).
  • /tmp/<feature-slug>/artifacts/decision-log.md — the decision history (always written).
  • /tmp/<feature-slug>/artifacts/team-findings.md — the review-team findings (always written).
  • /tmp/<feature-slug>/artifacts/feature-technical-notes.md — load-bearing mechanics. Lazily created — only present if at least one technical note qualified. Confirm whether it exists before relying on it.

Proceed to Step 3 once it finishes.

Step 3: Show the Files for Review

Tell the user the exact /tmp/ paths of every generated file — the spec and each companion artifact that was actually written (the technical-notes file only if it exists) — so they can open and review them before deciding whether to publish. State plainly that nothing has been published anywhere yet.

Step 4: Confirm the Publish Choice

Publishing to Confluence puts the content where other people can see it, so require an explicit choice before posting. Ask with AskUserQuestion, restating the /tmp/ file paths and the Confluence destination the user provided, and making clear that publishing creates one parent page (the spec) plus one child page per companion artifact, and that the cross-page links between them resolve by page title — so the published pages should not be renamed in Confluence afterward, or the inbound cross-links break. Offer three options, listing the draft option first as the recommended default:

  • "Yes, save them as drafts to edit later (recommended)" — every page is published as an unpublished Confluence draft for the user to review, edit, and publish themselves. This is the default. (Publish mode: draft.)
  • "Yes, publish them live now" — the pages go live immediately. (Publish mode: live.)
  • "No, keep them local only" — nothing is published.

If the user keeps it local only, stop. Report the /tmp/ folder path and state clearly that nothing was published to Confluence. Otherwise, record the chosen publish mode (draft or live) for Step 5. The chosen mode applies to every page in the tree.

Step 5: Rewrite Cross-Links to Title Macros, Then Publish the Tree

Publishing is a single create pass: rewrite the cross-file links into title-based page-link macros first, then create each page once with its final body. No second update pass is needed, because the macros resolve by title and do not depend on any page URL or ID.

Decide every page's final title up front. The title is used in two places — as the page's create-title, and as the ri:content-title in every macro that links to that page — so pick each title once and reuse it in both, so they can never drift apart:

  • Spec (the parent page): the feature name.
  • Decision log: <Feature Name> — Decision Log.
  • Team findings: <Feature Name> — Team Findings.
  • Technical notes (only if the file exists): <Feature Name> — Technical Notes.

These titles must be distinct within the target space for the macros to resolve unambiguously. A ri:content-title macro resolves against the whole space, not just this tree, so a title that collides with a page that already exists in the destination space is a real hazard: the link can resolve to the wrong page, and the create call may fail or be rejected for a duplicate title. The feature-name prefix keeps the four titles distinct from each other; pick a spec title specific enough that it is unlikely to already exist in the space, and if you have any signal that one does (for example the user pointed at a page that already carries the feature name), choose a more specific title before publishing.

  1. Rewrite cross-file links to title macros, leaving the /tmp/ originals intact. Write the rewritten copies to a dedicated subfolder (for example /tmp/<feature-slug>/.confluence-publish/) so the originals the user reviewed in Step 3 keep their working local markdown links. For each file, read it once and rewrite only the cross-file links:

    • Resolve each relative markdown link target against the directory of the file being rewritten. If it resolves to another file in the published set, replace the whole markdown link [text](target#fragment) with a Confluence title-based page-link macro pointing at that file's pre-decided title:

      <ac:link><ri:page ri:content-title="TARGET PAGE TITLE"/><ac:plain-text-link-body><![CDATA[text]]></ac:plain-text-link-body></ac:link>
      

      Omit ri:space-key — the whole tree lands in one space, so a same-space title reference resolves without it. Keep the original link text inside the link body. If that text contains the sequence ]]>, it would close the CDATA section early and produce malformed storage XML, so split it across two CDATA sections (]] in the first, > in the next) or drop the CDATA wrapper and XML-escape the text instead. Plain markdown emphasis in the link text (**bold**) is not rendered inside a plain-text link body; it posts as literal characters.

    • Drop the #fragment (the #d4-..., #t3-..., or section anchor). Confluence Cloud generates its own heading anchors with a scheme that does not match these slugs, so the link lands the reader at the top of the correct page, not the exact heading. (The macro form leaves the door open to add an explicit ri:anchor later if a space's heading-anchor scheme is pinned down; do not emit anchors now.)

    • Leave every other link, and all other content, exactly as written. Do not touch links that point outside the published set (external URLs, code references).

  2. Publish the tree in one create pass. Use the Skill tool for every call, and apply the publish mode the user chose in Step 4 to all of them — state it explicitly so han-atlassian:markdown-to-confluence does not re-ask.

    • Publish the spec (the parent page) first, from its rewritten copy. Invoke han-atlassian:markdown-to-confluence, forwarding the rewritten spec copy's path, the Confluence destination the user provided in Step 1 (passed through verbatim), the publish mode from Step 4, and the spec title decided above. Capture the resulting spec page's URL and page ID — the parent for the artifact pages, and needed for the final report.
    • Publish each existing artifact as a child of the spec page, from its rewritten copy. For each artifact file that exists (decision-log.md, team-findings.md, and feature-technical-notes.md only if it was created), invoke han-atlassian:markdown-to-confluence again, forwarding the rewritten artifact copy's path, the spec page's URL as the destination with the intent to create a new child page under it (state this explicitly so the publisher does not ask whether to update the spec page), the same publish mode, and the artifact's pre-decided title. Publish the artifacts one at a time so each create resolves against the same parent.

    han-atlassian:markdown-to-confluence owns location resolution, the create call, and Mermaid handling for each file. Because every body already carries its final title-macro links, each page is created exactly once — there is no update pass.

Mermaid still posts as source. As han-atlassian:markdown-to-confluence reports, Mermaid diagrams publish as fenced code blocks, not rendered diagrams, unless the space has a Mermaid macro. This is not something to silently fix.

Relay the result to the user: the spec parent page's URL, every artifact child page's URL, whether the tree went live or was saved as drafts, and the caveats: cross-page links resolve by page title and land at the top of the target page (heading-level anchors are not preserved); because they resolve by title, renaming a published page in Confluence may break inbound cross-page links; and the Mermaid note. If any create fails partway through the tree, report which file failed and its error, and note which pages were already created. Warn the user that those already-created pages carry title-macro links pointing at the pages that did not get created, so those links dangle until the missing pages exist under their intended titles — and that simply re-running the whole skill would re-create the pages that already succeeded, producing duplicate-title pages that break title resolution for the tree. Recommend they create the missing page(s) by hand under the intended titles, or delete the partial tree and re-publish from clean. Confirm the /tmp/ originals are unchanged and intact either way.

Step 6: Verification

  1. Inputs validated: the Atlassian server was reachable, a feature to plan was present, and a Confluence location was provided — or the skill stopped before doing any work.
  2. Plan produced to /tmp: han-planning:plan-a-feature ran with the full forwarded context and wrote its files under a /tmp/ folder whose paths were captured, including whether the lazily-created technical-notes file exists.
  3. User reviewed: the /tmp/ paths were shown to the user before any publish.
  4. Explicit choice obtained: the user chose draft, live, or local-only.
  5. Tree published in a single pass: when the user chose to publish, titles were decided up front, cross-file links were rewritten into title-based page-link macros in copies under .confluence-publish/ (fragments dropped, /tmp/ originals untouched), the spec was posted as the parent page and each existing companion artifact as a child page in the chosen mode, and each page was created exactly once with its URL captured.
  6. Reported: every page URL was relayed with the publish mode, the resolve-by-title and land-at-page-top caveat, the rename caveat, and the Mermaid note; when the user declined, only the /tmp/ files exist.

Project Context

  • personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
  • project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Project Documentation to Confluence

This skill produces project documentation with the han-documentation:project-documentation skill, lets the user review the result, and then publishes it to a Confluence location that the user must specify. It is a thin orchestrator: the documentation work belongs to han-documentation:project-documentation, and the publishing work belongs to han-atlassian:markdown-to-confluence. This skill only validates its inputs, runs the documentation to a temporary file, gets the user's review and publish choice, and hands the file to the publisher.

The five steps below are the whole skill. It does not resolve Confluence pages or call the Confluence MCP create/update tools itself; han-atlassian:markdown-to-confluence owns all of that.

Step 1: Validate Inputs

Confirm the skill has everything it needs before spending effort producing documentation:

  1. Atlassian MCP reachable (hard requirement). Call mcp__claude_ai_Atlassian__getAccessibleAtlassianResources to confirm the server is connected and retrieve the cloud ID(s). If the tool is not available, the call errors, or it returns no accessible resources (typically an authentication or configuration problem), stop immediately. Tell the user this skill requires the Atlassian MCP server to be installed, configured, and authenticated, and that they can re-run it once it is connected. Do not fall back to a local-only run; for local-only documentation, point them at han-documentation:project-documentation. This preflight runs first so a missing server fails before any documentation is generated.
  2. A documentation subject. Confirm the request names a feature, system, component, or existing doc to document. This is forwarded to han-documentation:project-documentation verbatim in Step 2.
  3. A Confluence destination. Confirm the request provides a target location: a Confluence page URL (to update that page, or create a child under it), or a space (key or name) plus an optional parent page. If none was provided, ask for one with AskUserQuestion, explaining plainly that the skill needs an exact destination because it does not search Confluence. Do not resolve the page tree here — only confirm a location was given. Carry it through to Step 5; han-atlassian:markdown-to-confluence resolves it.

Step 2: Produce the Documentation to a Temporary File

Invoke the han-documentation:project-documentation skill with the Skill tool, forwarding all provided context verbatim: the feature name or document path argument, the scope, any known entry points, and the relevant conversation context. Do not summarize, trim, or reinterpret the user's context; pass it through so han-documentation:project-documentation runs exactly as it would on its own — except add one explicit instruction: it must write the resulting documentation to a file under /tmp/ (for example /tmp/<feature-slug>.md) rather than into the project's docs directory. This keeps the working draft out of the repo until the user decides to publish it, and because the path is explicit input it outranks any output-directory the project or personal .han/config.md supplies (see ../../references/config-rule.md).

Let han-documentation:project-documentation complete its full process (codebase exploration, writing the doc, content audit, information-architecture review, and verification). Capture the exact /tmp/ file path it wrote. That markdown file is the source content for Confluence. Proceed to Step 3 once it finishes.

Step 3: Show the File for Review

Tell the user the exact /tmp/ path of the generated documentation so they can open and review it before deciding whether to publish. State plainly that the content has not been published anywhere yet.

Step 4: Confirm the Publish Choice

Publishing to Confluence puts the content where other people can see it, so require an explicit choice before posting. Ask with AskUserQuestion, restating the /tmp/ file path and the Confluence destination the user provided. Offer three options, listing the draft option first as the recommended default:

  • "Yes, save it as a draft to edit later (recommended)" — published as an unpublished Confluence draft for the user to review, edit, and publish themselves. This is the default. (Publish mode: draft.)
  • "Yes, publish it live now" — the page goes live immediately. (Publish mode: live.)
  • "No, keep it local only" — nothing is published.

If the user keeps it local only, stop. Report the /tmp/ doc path and state clearly that nothing was published to Confluence. Otherwise, record the chosen publish mode (draft or live) for Step 5.

Step 5: Publish with markdown-to-confluence

Invoke the han-atlassian:markdown-to-confluence skill with the Skill tool, forwarding:

  • the /tmp/ markdown file path captured in Step 2,
  • the Confluence destination the user provided in Step 1 (the page URL, or the space plus optional parent page), passed through verbatim, and
  • the publish mode the user chose in Step 4 (draft or live), stated explicitly so han-atlassian:markdown-to-confluence does not re-ask.

han-atlassian:markdown-to-confluence resolves the location, reads the file, creates or updates the page in the chosen mode, handles Mermaid diagrams, and reports the resulting page URL. Relay its result to the user: the created or updated page's URL and whether it went live or was saved as a draft. If publishing fails, report the error and confirm the /tmp/ markdown file is unchanged and intact.

Verification

  1. Inputs validated: the Atlassian server was reachable, a documentation subject was present, and a Confluence location was provided — or the skill stopped before doing any work.
  2. Doc produced to /tmp: han-documentation:project-documentation ran with the full forwarded context and wrote the documentation to a /tmp/ file whose path was captured.
  3. User reviewed: the /tmp/ path was shown to the user before any publish.
  4. Explicit choice obtained: the user chose draft, live, or local-only.
  5. Publish delegated and reported: when the user chose to publish, han-atlassian:markdown-to-confluence created or updated the page in the chosen mode and its URL was relayed; when the user declined, only the /tmp/ doc exists.

Project Context

  • personal config directory: !bash "${CLAUDE_PLUGIN_ROOT}/scripts/han-config-dir.sh" 2>/dev/null || echo "$HOME/.claude"
  • project .han/config.md: !cat .han/config.md 2>/dev/null || echo ""

As your first action, use the Read tool on .han/config.md inside the personal config directory path above. A read that returns no file is no personal configuration: continue silently. When that file or the project .han/config.md probe supplies content, apply it per config-rule.md, which governs precedence between the two files, relative-path resolution, and what to do with a file that reads but cannot be used.

Work Items to Jira Tickets

Take an already-broken-down work-items.md file (produced by /plan-work-items) and publish each slice as a Jira ticket in a single target project.

The breakdown work — drafting slices, assigning symbolic IDs, specifying dependencies, inventorying references — has already been done upstream. This skill's job is to validate the format, confirm the target, create one ticket per slice through the Atlassian MCP server, link the within-file dependencies, and place the tickets in the chosen column.

Rules

  • Every slice posts into one Jira project. This skill does not split work across repos or projects. A work-items.md that names multiple code repos still produces tickets in the single project you name; the repo prose is informational only.
  • Dependencies are within-file only. Every SYM named in a Depends on line must resolve to another slice in the same file. A Depends on that names an unknown SYM is a format error to surface for repair.
  • Symbolic-ID prefixes: accept whatever the input uses. Any uppercase prefix shape is valid (W-N, V2-N, EV-N, …); the prefix has no effect on Jira placement.
  • Defaults: issue type Story, no assignee, reporter taken from the Atlassian MCP identity, and the project's initial status (Backlog). Each is overridable per run; nothing is assigned or moved unless asked.
  • Parenting is optional and determines the child issue type. --parent <KEY> accepts an epic or a standard issue (a story, task, or bug). Under an epic, each item is a standard issue (default Story). Under a story (any standard issue), each item is a subtask (default the project's subtask issue type). You cannot parent under a subtask. --epic <KEY> is a deprecated alias for --parent; it resolves the same way regardless of the named issue's actual type.
  • Every slice ticket MUST carry the reference artifacts an implementer needs — API/event contracts, design references, schema docs, runbooks, ADRs, coding standards. Tickets that consume an HTTP endpoint or event payload MUST reference the contract section that defines it. Full include/exclude list in references/reference-artifact-inventory.md.
  • NEVER include process artifacts in ticket descriptions. Excluded: iteration histories, decision logs, review findings, team findings, facilitation summaries, gap analyses, and anything under an artifacts/ subfolder of the plan that is not a contract or design reference.
  • No screenshot upload or image embedding. Design references are carried as links, not uploaded into Jira. See references/jira-ticket-template.md.

Process

0. Atlassian MCP preflight (hard requirement)

This skill cannot run without a configured and connected Atlassian MCP server. Confirm it is reachable by calling mcp__claude_ai_Atlassian__getAccessibleAtlassianResources to retrieve the cloud ID(s). If the tool is unavailable, the call errors, or it returns no accessible resources, stop immediately and tell the user the skill requires the Atlassian MCP server to be installed, configured, and authenticated. Do not fall back to any other publishing target.

If more than one site is accessible, note which are available; you will confirm the right one while resolving the project in Step 3.

1. Locate the work-items file

If the path is not provided, ask for it. The input is a single work-items.md produced by /plan-work-items. Read it. Its format is described in references/work-items-file-format.md.

2. Gather the run options

Read these from the arguments and conversation; do not guess defaults the user did not ask for:

  • Target project or board — --project <KEY> (e.g., ACME) or --board <name/URL>. Required. If absent, ask for it in Step 3.
  • Parent — --parent <KEY> (an epic like ACME-12, or a story / standard issue like ACME-34) or an issue URL. Optional. When present, every created ticket is parented to it. --epic <KEY> is accepted as a deprecated alias for the same option; if both are given and name different keys, stop and ask which one. The parent's hierarchy level decides the child issue type (resolved in Step 3): standard issues under an epic, subtasks under a story.
  • Issue type — --type <name>. Optional; defaults to Story at the project top level or under an epic, and to the project's subtask issue type when the parent is a story.
  • Assignee — --assignee <accountId or email>. Optional; defaults to unassigned.
  • Column — --column <name>. Optional; defaults to the project's initial status (Backlog).

3. Resolve the target against Jira

Using the cloud ID from Step 0, resolve everything concretely now so failures surface before any ticket is created:

  • Project (required). If given a project key, confirm it with mcp__claude_ai_Atlassian__getVisibleJiraProjects. If given a board, resolve it to its underlying project (list projects and match; if a board maps to more than one project or is ambiguous, ask the user which project to use). If no project or board was provided, ask for one — do not proceed without a project key.

  • Parent (optional). If a parent was named (--parent, or the deprecated --epic), fetch it with mcp__claude_ai_Atlassian__getJiraIssue to confirm it exists and is in the target project, then read its issue type's hierarchy level to decide the child mode:

    • Epic (an epic-type issue, hierarchy level above standard) → children are standard-level issues; the effective default issue type is Story.
    • Standard issue (Story, Task, Bug — hierarchy level 0) → children must be subtasks; the effective default issue type is the project's subtask type (resolved in the next bullet).
    • Subtask → stop: a subtask cannot have children. Tell the user to name an epic or a standard issue instead.

    Record the parent's key and which child mode applies.

  • Issue type. Call mcp__claude_ai_Atlassian__getJiraProjectIssueTypesMetadata for the project. Determine the effective default from the parent mode above (no parent or epic parent → Story; story parent → the project's subtask issue type, the one flagged as a subtask in the metadata). Then confirm the chosen type — the --type override when given, otherwise the effective default — both exists in the project and sits at the correct hierarchy level for the parent: under a story it must be a subtask type, otherwise it must be a standard (non-subtask) type. If the chosen type is missing or at the wrong level, surface the available types at the correct level and ask the user to pick one. If a story parent is named but the project exposes no subtask type, stop and tell the user subtasks are not enabled in this project.

  • Assignee (optional). If an assignee was named, resolve it to an account ID with mcp__claude_ai_Atlassian__lookupJiraAccountId. If unset, leave tickets unassigned.

  • Column (optional). If a column was named, hold it for Step 8. Resolve the matching status when you transition (Step 8), since transitions are per-issue.

4. Validate the format with evidence-based repair

Check the work-items file against the invariants in references/jira-ticket-template.md and references/work-items-file-format.md:

  • Heading shape. Every slice heading matches ## <SYM-N> — <title> with an em-dash separator (already-published headings annotated as ## <SYM-N> (<KEY>) — <title> are valid too).
  • Depends on line. Literal bold marker **Depends on.**, trailing period, None. or comma-separated SYMs.
  • Within-file blockers. Every SYM named in a Depends on line resolves to another slice in this file.
  • References block. Present whenever the slice consumes an HTTP endpoint, event payload, design frame, ADR, coding standard, or other named artifact.
  • No process artifacts. No links to iteration histories, decision logs, review findings, team findings, facilitation summaries, gap analyses, or anything under an artifacts/ subfolder that is not a contract or design reference.

When a check fails, attempt evidence-based repair. Pull evidence from the source work-items.md, the parent plan referenced in its intro, the feature spec in the same folder, sibling files in the plan folder, and the relevant repo's ADRs / coding standards / docs:

  • Malformed heading — propose the corrected shape based on the surrounding text. Cite the line number.
  • Missing Depends on line — propose None. if no blockers are evident in the slice's prose. Cite the absence.
  • Unknown-SYM Depends on — propose either the correct in-file SYM (if a typo is evident) or None.. Cite the SYM list this file actually defines.
  • Missing References bullet for an HTTP-consuming slice — propose the contract section link from the parent plan's External Interfaces / API Contracts section. Cite the anchor.
  • Missing References bullet for a UI slice — propose the design frame and document path from the feature spec's Visual Reference table. Cite the spec section.
  • Process-artifact link found — propose removing the link and (if the slice still needs the context) restating the decision in plain language, with a Plan decisions References bullet naming the ID plus a one-sentence description. Cite the include/exclude list.

After validation, report findings in plain language. For each finding name: (1) what is wrong — slice SYM, line reference, failing invariant; (2) the proposed fill — corrected line, new bullet, removed link; (3) the evidence — file path with line number, document section, or named source.

Then give the user three actions: Continue with fills (apply the repairs to the source work-items.md and proceed), Correct the fills (user provides the right values; apply those and proceed), or Stop (exit without creating tickets). If validation passes with no findings, proceed to Step 5.

5. Show the plan for confirmation

Creating Jira tickets writes to a shared system, so confirm before doing it. Present a summary and wait for an explicit yes:

  • Destination: the Jira site, the target project (key and name), the parent (if any, named as the epic or story it is and what each item becomes under it — a standard issue or a subtask), the issue type, the assignee (or "unassigned"), and the target column (or "Backlog (default)").
  • The tickets to create: a table of every slice that does not already carry a (<KEY>) annotation.
SYMSummary (ticket title)Depends on
W-1Backend per-list validator generalizationNone
W-2…W-1

State the total count and that reporter will be the authenticated Atlassian user. Do not create anything until the user confirms.

6. Create one ticket per slice

Walk the slices in file order (blocker-first, as authored). Skip any slice whose heading already carries a (<KEY>) annotation so a re-run resumes cleanly. For each remaining slice, call mcp__claude_ai_Atlassian__createJiraIssue with:

  • the cloud ID and target project key,
  • issue type = the type resolved in Step 3 (default Story at the top level or under an epic; the project's subtask type when the parent is a story),
  • summary = the slice title (the text after — in the heading),
  • description = the rendered slice body (everything below the heading: Summary, Description, any notes, References, Tests, Acceptance criteria). Pass it as Markdown; if the create tool requires ADF, convert it. Confirm the expected format against the tool's input schema.
  • parent = the resolved parent key, when a parent was resolved (Step 3) — an epic for standard-issue children, or a story for subtask children. Use the parent field the project's create metadata exposes; for a subtask, Jira requires parent. If parent is rejected for an epic in a company-managed project, surface the legacy "Epic Link" field requirement rather than dropping the parent silently.
  • assignee = the resolved account ID only when the user provided one; otherwise omit it (unassigned).
  • reporter: never set it. Jira records the authenticated MCP user as reporter.

After each successful create, capture the returned Jira key and rewrite that slice's heading in place from ## <SYM-N> — <title> to ## <SYM-N> (<KEY>) — <title> using Edit, so dependencies resolve and re-runs skip it. Report each creation as created: <SYM-N> -> <KEY>.

7. Link dependencies

Once every slice has a Jira key, build the SYM→key map from the annotated headings and walk each slice's **Depends on.** line. For each blocker (skip None.):

  • Record it durably in the dependent ticket. Rewrite the dependent ticket's Depends on line in its description from symbolic IDs to the blockers' Jira keys (linked), via mcp__claude_ai_Atlassian__editJiraIssue. This survives regardless of native-link support.
  • Create a native link when available. If the configured Atlassian MCP exposes an issue-link capability, also create an "is blocked by" relationship from the dependent ticket to each blocker. If no issue-link tool is available, say so once in the final report rather than implying native links were made.

Report each as linked: <SYM-A>(<KEY-A>) blocked_by <SYM-B>(<KEY-B>).

8. Place tickets in the target column

By default, leave every ticket in the project's initial status (Backlog) and do nothing here.

When the user named a --column, transition each created ticket toward the matching status: call mcp__claude_ai_Atlassian__getTransitionsForJiraIssue for the ticket, find the transition whose target status matches the requested column, and apply it with mcp__claude_ai_Atlassian__transitionJiraIssue. If no transition leads to the requested column for a ticket, do not force it — report that ticket as left in Backlog and name the column it could not reach, so the user can move it by hand.

9. Report

Summarize: the project and parent (if any, named as the epic or story it is), the issue type used (noting "subtask" when items were nested under a story), the assignee (or unassigned), and the column. List every created ticket as <SYM-N> — <KEY> with its URL, the count of dependency links made (and whether they are native Jira links or description references), and any slices skipped because they already carried a key. If any step failed, report the error and confirm the source work-items.md annotations reflect exactly which tickets were created.

Sponsors

Details

Marketplace
testdouble/han
Source
han-atlassian
Category
Community

More from testdouble/han

All 14