@greeana/jira-dev-workflow

Publishable npm CLI plus Codex skill template for Jira-backed development workflows.

What it does

• find matching Jira issues for a diff or free text
• reuse open issues and avoid reusing closed ones
• create a new issue when no suitable open issue exists
• prepare commit plans from staged or working-tree changes
• save the selected Jira issue locally for later commands
• post implementation comments, reports, and screenshots
• create git commits with Jira key prefixes
• import Jira issues from CSV

Package model

This package is designed to be published as:

@greeana/jira-dev-workflow

The included Codex skill calls the published CLI through npx, so consumers do not need to vendor the source code into each repo.

Consumer repo layout

Each consumer repo keeps its own local workflow state and secrets under:

.jira-dev-workflow/config.json
.jira-dev-workflow/.env.local
.jira-dev-workflow/state/current-issue.json

The CLI searches upward from the current working directory until it finds .jira-dev-workflow/.

See the examples under examples/.jira-dev-workflow/.

Minimal config:

{
  "projectKey": "JDW",
  "defaultIssueType": "Task",
  "issueLinkType": "Relates",
  "commitMessageFormat": "{issueKey} {message}",
  "searchLimit": 5,
  "reuseClosedAsRelatedLink": true,
  "stateFile": "state/current-issue.json"
}

Minimal env:

JIRA_BASE_URL=https://your-company.atlassian.net
[email protected]
JIRA_API_TOKEN=your_jira_api_token

Local development

npm install
npm test
npm run test-install
node ./bin/jira-dev-workflow.mjs help

Bootstrap the current repo with the local skill and required workflow files:

npx -y @greeana/jira-dev-workflow install

Test the skill locally before any npm publish by generating a skill that calls this checkout directly:

node ./bin/jira-dev-workflow.mjs install --local

Generate a repo-local skill that keeps using the npm preview dist-tag:

npx -y @greeana/jira-dev-workflow@preview install --preview

Generate a repo-local skill pinned to an exact published version:

npx -y @greeana/[email protected] install --version 0.1.1-preview.0

Smoke-test the current checkout as if it were published by packing it locally and running the packaged install command against the current repo:

npm run test-install

Pass extra install flags through the smoke test:

npm run test-install -- --force --project-key JDW

To run the same dev-only smoke test against a different repo, change into that repo and invoke this checkout's script directly:

node --import tsx /absolute/path/to/jira-dev-workflow/scripts/test-install.ts

This creates:

.codex/skills/jira-dev-workflow/SKILL.md
.jira-dev-workflow/config.json
.jira-dev-workflow/.env.local

It also ensures .gitignore contains:

.codex/skills/jira-dev-workflow/
.jira-dev-workflow/config.json
.jira-dev-workflow/.env.local
.jira-dev-workflow/state/

Published CLI examples

Show all commands:

npx -y @greeana/jira-dev-workflow help

Install into the current repo:

npx -y @greeana/jira-dev-workflow install

Install into the current repo and write the Jira project key up front:

npx -y @greeana/jira-dev-workflow install --project-key JDW

Install into the current repo and make the generated skill keep using the npm preview tag:

npx -y @greeana/jira-dev-workflow@preview install --preview

Install into the current repo and pin the generated skill to an exact published version:

npx -y @greeana/[email protected] install --version 0.1.1-preview.0

Install into the current repo and make the generated skill call a local checkout directly:

node /absolute/path/to/jira-dev-workflow/bin/jira-dev-workflow.mjs install --local

Test Jira access:

npx -y @greeana/jira-dev-workflow test

Prepare a commit plan from staged changes:

npx -y @greeana/jira-dev-workflow prepare-commit --json

Expected interactive flow for agents:

1. User stages changes and asks to prepare a Jira commit.
2. Agent runs prepare-commit --json.
3. Agent shows matching open issues, or a drafted new issue if no open issue fits, and asks the user which path to take.
4. Agent does not create an issue, commit, or post back to Jira yet.
5. After the user selects an issue or approves a new one, the agent previews the final commit message with commit --dry-run and asks for confirmation.
6. Only after explicit confirmation does the agent create the commit.
7. Posting an implementation comment or attachments back to Jira is a separate confirmation step unless the user explicitly asked for that as part of the workflow.

Prepare a commit plan from working-tree changes:

npx -y @greeana/jira-dev-workflow prepare-commit --working-tree --json

Search Jira directly:

npx -y @greeana/jira-dev-workflow find --text "qa agent isolation" --json

Create a new Jira issue:

npx -y @greeana/jira-dev-workflow create \
  --summary "Improve QA agent isolation" \
  --description-file /tmp/issue.md

Create a new Jira issue related to a closed one:

npx -y @greeana/jira-dev-workflow create \
  --summary "Improve QA agent isolation" \
  --description-file /tmp/issue.md \
  --related-issue JDW-19

Save the selected issue for later commands:

npx -y @greeana/jira-dev-workflow use --issue JDW-23

Show the current saved issue:

npx -y @greeana/jira-dev-workflow current

Attach a screenshot or artifact:

npx -y @greeana/jira-dev-workflow attach --issue JDW-23 --file /absolute/path/to/screenshot.png

Add an implementation report comment:

npx -y @greeana/jira-dev-workflow comment \
  --issue JDW-23 \
  --text $'Implemented in:\nhttps://git.example.com/commit/abcdef'

Add a comment with inline screenshots:

npx -y @greeana/jira-dev-workflow comment \
  --issue JDW-23 \
  --text $'Implementation report:\n\nPrepared commit result:\n\n[[inline-file]]\n\nJira issue after preparation:\n\n[[inline-file]]' \
  --inline-file /absolute/path/to/screenshot-1.png \
  --inline-file /absolute/path/to/screenshot-2.png

Inline screenshot placement rules:

• [[inline-file]] inserts the next inline screenshot in order.
• [[inline-file:2]] inserts a specific inline screenshot by 1-based index.
• Place placeholders as their own paragraphs to position screenshots between report sections.
• If you pass inline screenshots without placeholders, they are appended after the text for backward compatibility.

Preview the final commit message:

npx -y @greeana/jira-dev-workflow commit --issue JDW-23 -m "Improve QA agent isolation" --dry-run

Create the git commit:

npx -y @greeana/jira-dev-workflow commit --issue JDW-23 -m "Improve QA agent isolation"

Import issues from CSV:

npx -y @greeana/jira-dev-workflow import --file .jira-dev-workflow/import.csv

Codex skill

The portable skill template lives in:

skill/jira-dev-workflow/SKILL.md

Install it into either:

~/.codex/skills/jira-dev-workflow/

or:

.codex/skills/jira-dev-workflow/

The skill assumes the published package name is @greeana/jira-dev-workflow. If you publish under a different scope or package name, update the npx commands in the skill file.

Release checklist

1. Update version in package.json.
2. Run npm test.
3. Run npm run test-install from this repo, or invoke scripts/test-install.ts from a scratch repo.
4. Run npm pack --dry-run and confirm only the intended files are included.
5. Confirm skill/jira-dev-workflow/SKILL.md still points to npx -y @greeana/jira-dev-workflow.
6. Publish with npm publish --access public.
7. Smoke-test the published package:

npx -y @greeana/jira-dev-workflow help
npx -y @greeana/jira-dev-workflow test