Commit 305e2d3c8091
Changed files (8)
dots
agents
skills
jayrat
dots/agents/skills/jayrat/agents/openai.yaml
@@ -0,0 +1,6 @@
+interface:
+ display_name: "Jayrat"
+ short_description: "Manage Jira workflows with the jrc CLI"
+ default_prompt: "Use $jayrat to inspect or update Jira safely with jrc."
+policy:
+ allow_implicit_invocation: true
dots/agents/skills/jayrat/references/bulk-and-api.md
@@ -0,0 +1,44 @@
+# Bulk transitions and raw API
+
+## Immutable bulk transition plans
+
+Never pipe a JQL result directly into live mutations. Resolve it into a saved
+plan:
+
+```bash
+jrc issue bulk transition plan \
+ --jql 'sprint in openSprints() AND status != Done' \
+ --to Done --max 50 \
+ --out /tmp/jayrat-transition-plan.json --output json
+```
+
+`--max` defaults to 50. Choose it deliberately for JQL plans, then verify the
+saved item count covers the user's intended scope before application.
+
+Inspect the saved keys and transition IDs, then validate application without
+writing:
+
+```bash
+jrc issue bulk transition apply /tmp/jayrat-transition-plan.json \
+ --dry-run --output json
+```
+
+If the user's request clearly authorises the complete saved set, apply that
+same file with `--confirm`. Do not rerun the JQL. Stop on the first error unless
+the user explicitly asks for `--continue-on-error`. Report every `applied`,
+`failed`, and `not_run` result.
+
+Plans may also use `--keys` or `--keys-file`. Do not overwrite an existing plan
+without `--force`.
+
+## Raw API escape hatch
+
+Use `jrc api` only when no typed command covers the request. Inspect the method,
+relative endpoint, and JSON body explicitly. Prefer `--data-file`.
+
+- Permit relative REST paths.
+- Permit an absolute URL only when its scheme, host, and port match the
+ configured Jira origin.
+- Reject cross-origin URLs, embedded credentials, and redirects.
+- Treat POST, PUT, PATCH, and DELETE as mutations and dry-run them first.
+- Treat DELETE as destructive and require an unambiguous user request.
dots/agents/skills/jayrat/references/issues.md
@@ -0,0 +1,56 @@
+# Issue workflows
+
+## Read and discover
+
+```bash
+jrc issue list --jql 'assignee = currentUser() AND resolution = Unresolved' \
+ --fields key,summary,status,priority --output json
+jrc issue list --board my-board --max 50 --output json
+jrc issue get PROJ-123 --output json
+jrc issue children PROJ-123 --fields key,summary,status --output json
+jrc issue custom-fields --all --output json
+```
+
+Use `jrc describe fields issue list` or `issue get` before requesting filtered
+fields.
+
+## Create and edit
+
+Use `project create-metadata` to discover required and allowed fields. Apply
+configured components, priorities, and type-specific description templates
+unless the user supplies replacements. Omit optional fields the user did not
+request and the config does not default.
+
+Prefer direct create flags for `--due-date`, `--parent`, and `--fix-version`.
+Use repeatable `--custom-field 'Name=value'` for configured custom fields.
+
+Editing labels, components, fix versions, and affects versions replaces the
+existing values. Fetch the issue first when preserving existing values matters.
+
+```bash
+jrc issue edit PROJ-123 --priority High --story-points 5 --dry-run
+jrc issue edit PROJ-123 --issue-type Story --parent PROJ-10 --dry-run
+```
+
+## Transitions and people
+
+List transitions before choosing a target unless the user supplied an exact
+transition or status:
+
+```bash
+jrc issue transition PROJ-123 --list --output json
+jrc issue transition PROJ-123 --to 'In Progress' --dry-run
+jrc issue transition PROJ-123 --auto --dry-run
+```
+
+Resolve assignees with `jrc user list --query` when names are ambiguous. Use
+`issue assign`, `watch`, `unwatch`, `watchers`, `vote`, and `unvote` only for
+the requested issue.
+
+## Comments, cloning, and deletion
+
+Use `issue comment list/add/edit/delete`. Prefer `--body-file` for substantial
+comments. Comment and issue deletion require `--confirm`; dry-run first.
+
+`issue clone` copies summary, type, and description only. It does not copy
+links, attachments, or subtasks. Tell the user when those omissions matter.
dots/agents/skills/jayrat/references/links-and-attachments.md
@@ -0,0 +1,26 @@
+# Links and attachments
+
+Discover link types and existing link IDs before writing:
+
+```bash
+jrc issue link-types --output json
+jrc issue links PROJ-123 --output json
+jrc issue link PROJ-123 --link-type Blocks --to PROJ-456 --dry-run
+jrc issue unlink LINK_ID --dry-run
+```
+
+Treat unlinking as destructive even when the CLI does not require `--confirm`.
+Ensure the requested direction matches Jira's inward and outward link wording.
+
+List attachments before downloading or deleting:
+
+```bash
+jrc issue attachment list PROJ-123 --output json
+jrc issue attachment upload PROJ-123 ./report.txt --dry-run
+jrc issue attachment download PROJ-123 ATTACHMENT_ID --out ./report.txt
+jrc issue attachment delete ATTACHMENT_ID --confirm --dry-run
+```
+
+Uploading and deleting mutate Jira. Downloading writes locally: do not
+overwrite an existing destination without the user's intent. Never infer an
+attachment ID from a filename when multiple entries match.
dots/agents/skills/jayrat/references/projects-releases-automation.md
@@ -0,0 +1,34 @@
+# Projects, agile resources, releases, and automation
+
+## Discovery
+
+Use `project list/get/issue-types/priorities/components`, `board list`, and
+`board config list` to resolve names into keys or IDs. Use `sprint list` and
+`sprint issues` only after resolving the board and sprint.
+
+Search users with `user list --query`. Use `server info` for deployment and API
+diagnostics. Generate completions only when the user requests shell setup.
+
+## Releases
+
+Use `release list --fields` to identify the version ID. Mutations support
+dry-run:
+
+```bash
+jrc release create --project PROJ --name v1.2.0 --start 2026-07-01 \
+ --release 2026-08-01 --description-file ./notes.md --dry-run
+jrc release update VERSION_ID --release 2026-08-08 --dry-run
+jrc release release VERSION_ID --date 2026-08-08 --dry-run
+jrc release archive VERSION_ID --dry-run
+jrc release delete VERSION_ID --move-fix-to OTHER_ID --confirm --dry-run
+```
+
+Deleting a version can clear references. Supply replacement version IDs when
+the user asks to retain fix- or affects-version associations.
+
+## Automation
+
+Use `automation list/get/runs` to inspect rules before enabling, disabling, or
+triggering them. Rule mutations can affect many issues; show the selected rule
+ID and dry-run payload, then act only when the request names or unambiguously
+identifies that rule.
dots/agents/skills/jayrat/SKILL.md
@@ -0,0 +1,102 @@
+---
+name: jayrat
+description: Manage Jira with the jrc CLI. Use for reading, creating, editing,
+ transitioning, assigning, commenting on, linking, cloning, watching, voting on,
+ or deleting issues; attachments, projects, boards, sprints, users, releases,
+ automation rules, bulk transitions, custom fields, server diagnostics, and raw
+ Jira API requests.
+---
+
+# Jayrat Jira workflows
+
+Use `jrc` as the sole Jira interface. Do not extract credentials or call Jira
+with another HTTP client.
+
+## Establish capabilities
+
+1. Confirm that `jrc` is on `PATH`.
+2. Run `jrc version --output json` when available.
+3. Inspect every command before constructing it:
+
+```bash
+jrc describe commands <command> <subcommand>
+```
+
+For commands exposing `--fields`, inspect the supported output names with
+`jrc describe fields <command> <subcommand>`. The bare `describe fields`
+command lists the registered field-filtering commands; other command paths
+correctly have no field schema.
+
+Treat the active schema as authoritative. If a documented flag is unavailable,
+do not invent it; use an available safe workflow or tell the user that `jrc`
+must be upgraded.
+
+## Safety contract
+
+- Run every Jira mutation with `--dry-run` first and inspect the complete
+ structured payload.
+- Treat a clear user request as authority to apply the matching mutation after
+ a successful dry-run. Ask only when scope, target, or destructive impact is
+ ambiguous.
+- Pass mandatory `--confirm` flags only when the user's request clearly covers
+ that destructive or bulk action.
+- Never use `jrc config dump --show-token`. Filter ordinary config dumps to the
+ minimum required fields.
+- Use `--description-file`, `--body-file`, or `--data-file` for multiline or
+ shell-sensitive input. Use `-` for stdin when appropriate.
+- Use only relative paths or same-origin absolute URLs with `jrc api`. Reject
+ cross-origin requests.
+- Use `--output json` and `jq` for scripting. Do not parse human text.
+
+## Resolve context before writing
+
+Read only the needed defaults:
+
+```bash
+jrc config dump --output json | jq '{jira_project, create_defaults, custom_fields}'
+```
+
+Discover project-specific values rather than guessing:
+
+```bash
+jrc project issue-types --project PROJ --output json
+jrc project create-metadata --project PROJ --issue-type Bug --output json
+jrc project components --project PROJ --output json
+jrc project priorities --project PROJ --output json
+jrc user list --query 'Ada' --output json
+```
+
+Use configured description templates and defaults unless the user overrides
+them. Use Markdown, never Jira wiki markup. Do not assume that every Epic needs
+an `Epic Name`; follow create metadata and configured custom fields.
+
+## Core workflow
+
+For reads, execute directly. For writes, construct one set of arguments, run it
+with `--dry-run`, inspect it, then rerun the same arguments without `--dry-run`.
+
+Create due dates, parents, and fix versions in the initial request when the
+active schema supports them:
+
+```bash
+jrc issue create --project PROJ --summary 'Concise title' \
+ --issue-type Bug --description-file /tmp/description.md \
+ --due-date 2026-08-01 --parent PROJ-10 --fix-version v1.2.0 \
+ --dry-run --output json
+```
+
+Report structured results, including the issue key and URL returned by `jrc`.
+If a mutation partially succeeds, report the created or changed resource and
+the failed follow-up precisely; do not silently retry with weaker fields.
+
+## Load task-specific guidance
+
+- Read [issues.md](references/issues.md) for issue reads, creation, editing,
+ transitions, comments, assignment, watchers, votes, and cloning.
+- Read [links-and-attachments.md](references/links-and-attachments.md) for
+ relationships, children, watchers, and attachment workflows.
+- Read [projects-releases-automation.md](references/projects-releases-automation.md)
+ for projects, boards, sprints, users, releases, automation, server info, and
+ completions.
+- Read [bulk-and-api.md](references/bulk-and-api.md) for immutable bulk plans
+ and raw REST escape-hatch rules.
systems/kyushu/home.nix
@@ -10,7 +10,6 @@
home.packages = with pkgs; [
oath-toolkit
gmailctl
- jayrah
jayrat
tekton-lsp
pi-acp
systems/okinawa/home.nix
@@ -116,7 +116,6 @@ in
ssh-to-age
- jayrah
jayrat
daily-plan
];