jira-to-local

Files (36)

• SKILL.md
• evals.json · evals/
• confluence-links.md · references/
• format-guide.md · references/
• jira-fields.md · references/
• output-json.md · references/
• refactor-guide.md · references/
• comments.schema.json · schemas/
• config.schema.json · schemas/
• content.schema.json · schemas/
• development.schema.json · schemas/
• tasks.schema.json · schemas/
• worklogs.schema.json · schemas/
• adf.mjs · scripts/
• check-json.mjs · scripts/
• check-markdown.mjs · scripts/
• config.mjs · scripts/
• confluence-format.mjs · scripts/
• dev-status.mjs · scripts/
• fetch-confluence.mjs · scripts/
• fetch-issue.mjs · scripts/
• inspect.mjs · scripts/
• jira-api.mjs · scripts/
• package.json · scripts/
• setup-choices.mjs · scripts/
• comments.md · templates/
• confluence-page.md · templates/
• content.md · templates/
• development.md · templates/
• jira.config.json · templates/
• subagent-instruction.md · templates/
• tasks.md · templates/
• worklogs.md · templates/
• bulk-pull.md · workflows/
• pull.md · workflows/
• setup.md · workflows/

SKILL.md (first lines)

# Pull a Jira issue into a local folder

One job: an issue key goes in, a folder of readable files comes out. One issue,
one folder, everything in it — fields, comments, subtasks, worklogs, attachments, and
any Confluence page the issue links to.

`<skill-path>` below is this skill's directory.

## The seven rules

**1. Pull only.** This skill never creates, edits, transitions, comments on,
assigns, or deletes anything in Jira. Every request reads: every REST call is a GET,
and the one POST is a GraphQL *query* — the only way to read the deployment list,
which no REST endpoint serves. Nothing here mutates anything. If the user wants a
write, say so plainly and route to `atlassian-rest` — do not improvise it here.

**2. Config first, and the config records the user's ticks.** No
`.jira.config.json` means run [`workflows/setup.md`](workflows/setup.md) before
anything else. Setup's five decisions — project, issue types, fields per type,
board, output — are the user's, and each is settled by a box in a file that
`setup-choices.mjs` generates from the API's own answer. The agent fetches the
options and records what the user did — never narrowing a list, summarising it, or
marking one option as recommended before they have seen all of it.

Only the starting state differs. Project, issue types, board and output arrive
**unticked**, so a tick is the answer. A per-type fields file arrives **fully
ticked**, because its options are the fields that issue type's screen shows — Jira's
own answer to what the type holds — so keeping it all is the honest default and the
user's job is to untick what they do not want. Either way their edit is the decision,
and a fresh file is not one.

Setup also records one thing that is not a tick file: which of this site's custom
fields fills each metadata row (`project.metaFields`). Propose that mapping from the
field list already on screen, then let the user confirm it. An unmapped row is
written `—`, never guessed.

**3. One part per call.** `fetch-issue.mjs` writes one document per run. Never
reach for a single call that fetches everything: the parts are separate so each
can be checked while it is still small enough to check.

**4. Complete or failed, never partial.** Every comment and every worklog entry is
written. Any list read from the API is paged to the server's own `total`, and the
count is asserted before the file is written. **A file holding one page of a longer
list is a failed pull, not a pull with a caveat.** Never read a list out of
`fields=*all` — that response is capped, silently.

The same rule decides when a pull is done: **the folder is the evidence, not the
report.** An agent that says it finished, or that reports itself idle, has stated a
hypothesis. Check the counts against Jira before believing it — and when many issues
are in flight, stop the agent before reading its folder, because idle is reported
while a write is still in flight.

**5. Every document is versioned, and every JSON file is validated.** Markdown
declares `schema:` in its frontmatter; JSON declares `$schema` as its first key. In
`json` or `both` mode, `check-json.mjs` must exit clean on every JSON file before
the pull is reported done. A file that fails validation, or carries no `$schema`,
is a failed pull. A pulled Confluence page is markdown in every mode, so
`check-markdown.mjs` covers it and `check-json.mjs` never runs on it.

**6. The format pass changes formatting, never words.** Layout, headings, table
syntax, list markers, unfilled boilerplate: all fair game. Wording, terminology,
spelling, code, ids, dates, names, URLs: never. A ticket written in mixed
languages, or with a typo in an acceptance criterion, stays exactly as written —
that is what the ticket says. The one exception is image alt text, written from
what the image shows. Detail in
[`references/refactor-guide.md`](references/refactor-guide.md).

Within that boundary the target is a document a person can read, not a document
the checker accepts. `check-markdown.mjs` covers what someone thought to automate,
so a clean exit is the floor: the agent still reads the file as the reader will and
fixes what renders wrong or breaks the reading, whether or not a rule names it. A
clean gate on a visibly badly formatted file is a failed part.

**7. Write for someone who has never seen the issue or the code.** The reader
cannot open Jira, has not read the repository, and does not know the project's
shorthand. An unexplained ticket key, field name, or file path costs them a
lookup they cannot make. Name what a thing is, once, in a short clause.

## Pick the workflow

| The request is… | Workflow |
|---|---|
| "pull PROJ-123", "fetch this story", a pasted issue URL | [`workflows/pull.md`](workflows/pull.md) |
| "sync sprint 62", "pull every bug in the backlog", any JQL or sprint | [`workflows/bulk-pull.md`](workflows/bulk-pull.md) |
| No `.jira.config.json` exists yet, or a new issue type needs configuring | [`workflows/setup.md`](workflows/setup.md) |

Setup runs once per project. Pull runs every time after that.

## The scripts

All are Node 18+, zero dependencies, run from anywhere inside the workspace.

| Script | Does |
|---|---|
| `config.mjs` | Finds, reads and validates `.jira.config.json`. `path`, `validate`, `instructions [TYPE]`, `types`, `type <TYPE>`, `meta`, `where [KEY]`, and `show` for the whole file — thousands of lines on a real project, so prefer a narrower one |
| `jira-api.mjs` | Credentials, the one paged GET, and a read-only GraphQL query for what REST will not serve. `whoami`, `get`, `count`, `pages` |
| `inspect.mjs` | Setup's read-only probes: `projects`, `issue-types`, `fields`, `sample`, `board`, `count-type` |
| `setup-choices.mjs` | Setup's decision files. `generate`/`read <kind> [--type T] [--sample KEY]`, `status`. Project, issue types, board and output arrive unticked; a per-type fields file arrives fully ticked. `--force` re-generates over existing ticks. Exit 2 = nothing ticked, 3 = no file, 4 = would erase a tick |
| `fetch-issue.mjs` | One part per run: `<KEY>` with `--part` set to `content`, `comments`, `tasks`, `worklogs` or `development` |
| `fetch-confluence.mjs` | `--issue KEY` pulls the pages that issue links, into its folder |
| `check-markdown.mjs` | 18 rendering and readability rules. Exit 1 while any remain |
| `check-json.mjs` | Validates a JSON file against the schema its `$schema` names |

Run any of them with `--help` for the full flag list.

Three more files in `scripts/` are libraries with no command line, imported by the
scripts above: `adf.mjs` converts Atlassian Document Format to markdown,
`confluence-format.mjs` does the same for a wiki page, and `dev-status.mjs` reads
the development panel.

## What the config holds

`.jira.config.json` sits at the workspace root. It runs to thousands of lines,
almost all of it `issueTypes`, so read it with `config.mjs types`,
`config.mjs type <TYPE>`, `config.mjs meta` and `config.mjs where` rather than
`config.mjs show`.

| Block | Decides |
|---|---|

From bmad-labs/skills, MIT.

More from bmad-labs/skills