skill-youtrack-management

YouTrack workflow skill for Codex and Claude Code, built around the Go-based youtrack-mgmt CLI. The Go CLI is the canonical runtime. Legacy yt / ytx entrypoints are deprecated thin shims that forward to youtrack-mgmt.

What It Covers

• label-based auth bootstrap through youtrack-mgmt auth *
• token storage via keychain on macOS and Windows, with env_or_file as the explicit fallback
• current-instance pinning per local repository context
• instance rename and scoped-board management
• board reads: list, current, show, sprints, issues, scoped-issues, tasks, my-tasks
• issue reads: brief, show, search
• preview-first issue mutations: create, create-subtask, link, update
• issue comment workflows: comment-list, comment-add, comment-update, comment-delete
• YouTrack command preview/apply via issue command
• explicit board membership mutations via issue board-add and issue board-remove
• board-scoped create aliases via board create-task and board create-subtask
• agent-facing read/write DSL through youtrack-mgmt q and youtrack-mgmt m

Layout

• SKILL.md: agent instructions and workflow contract
• cmd/youtrack-mgmt: CLI entrypoint
• internal/config: auth/config resolver and storage logic
• internal/youtrackmgmt: YouTrack runtime and command handlers
• internal/query: agent-facing read DSL
• internal/mutation: agent-facing mutation DSL
• internal/install: repo-local skill install/runtime packaging
• setup.sh, setup.ps1: root setup entrypoints
• scripts/setup.sh: source-repo install/setup entrypoint
• scripts/setup.ps1: Windows source-repo install/setup entrypoint
• scripts/bootstrap_runtime.sh: committed runtime bootstrap
• scripts/bootstrap_runtime.ps1: Windows committed runtime bootstrap
• scripts/youtrack-mgmt, scripts/youtrack-mgmt.cmd: wrappers for the built Go CLI
• scripts/yt, scripts/ytx: deprecated forwarding shims

Prerequisites

• Go
• access to one or more YouTrack instances
• git when current-developer resolution is needed for board my-tasks or --assignee me

Setup

Canonical setup entrypoints:

./setup.sh
./setup.sh --install-only

On Windows:

.\setup.ps1
.\setup.ps1 -InstallOnly

Install the skill into one repository-local runtime and bootstrap it immediately:

./setup.sh --project-dir /abs/path/to/repo --locale ru-en

This flow:

• builds youtrack-mgmt with embedded version, commit, and build-date metadata
• installs ~/.local/bin/youtrack-mgmt
• refreshes ~/.agents/skills/skill-youtrack-management
• links the installed skill into ~/.claude/skills/ and ~/.codex/skills/
• writes install-state metadata into the standard user config directory
• optionally installs the committed runtime into <repo>/.agents/skills/skill-youtrack-management
• bootstraps that committed runtime via the matching bootstrap_runtime script
• verifies the installed binary with version, auth config-path, and doctor

Install-state path follows os.UserConfigDir():

• macOS: ~/Library/Application Support/youtrack-mgmt/install.json
• Windows: %AppData%\youtrack-mgmt\install.json
• Linux: ~/.config/youtrack-mgmt/install.json

Supported setup/release matrix:

• macOS arm64
• macOS x86_64
• Windows x86_64
• Windows arm64

Runtime Bootstrap

Inside a committed runtime copy on Unix:

make -C <repo>/.agents/skills/skill-youtrack-management skill

On Windows:

<repo>\.agents\skills\skill-youtrack-management\scripts\bootstrap_runtime.ps1 -Quiet

That builds the local youtrack-mgmt binary inside the runtime copy with embedded metadata and runs youtrack-mgmt doctor.

Auth Model

youtrack-mgmt stores label-based auth profiles in the standard user config directory:

• macOS example: ~/Library/Application Support/youtrack-mgmt/auth.json
• Windows example: %AppData%\youtrack-mgmt\auth.json
• Linux example: ~/.config/youtrack-mgmt/auth.json

Inspect the actual path on the current machine:

youtrack-mgmt auth config-path

Bootstrap a profile:

youtrack-mgmt auth bootstrap --label main https://youtrack.example.com/
youtrack-mgmt auth bootstrap --label main https://youtrack.example.com/ --source env_or_file
youtrack-mgmt auth bootstrap --label main https://youtrack.example.com/ --source keychain

Default source policy:

• darwin -> keychain
• windows -> keychain
• everything else -> env_or_file

Fill the access payload according to the selected source:

youtrack-mgmt auth set-access main --token YOUR_TOKEN
youtrack-mgmt auth resolve main
youtrack-mgmt auth whoami main --check=false
youtrack-mgmt auth whoami main
youtrack-mgmt auth clean main

auth set-token remains as a compatibility alias, but auth set-access is the main user-facing contract.

Usage Examples

youtrack-mgmt instances list
youtrack-mgmt instances current
youtrack-mgmt instances rename main prod
youtrack-mgmt instances scope set prod 83-1 83-2

youtrack-mgmt board list --label prod
youtrack-mgmt board show --label prod 83-1
youtrack-mgmt board my-tasks --label prod
youtrack-mgmt board tasks --label prod --board 83-1 --assignee me --active-only

youtrack-mgmt issue brief --label prod ABC-123
youtrack-mgmt issue show --label prod ABC-123
youtrack-mgmt issue search --label prod 'Assignee: me'
youtrack-mgmt issue create --label prod --project CORE --summary 'Investigate' --description 'Details' --assignee alexis --initiator alexis
youtrack-mgmt issue create --label prod --project CORE --summary 'Investigate' --description 'Details' --assignee alexis --initiator alexis --apply
youtrack-mgmt issue create-subtask --label prod --parent-issue-id CORE-1 --summary 'Implement' --description 'Details' --assignee alexis --initiator alexis
youtrack-mgmt issue link --label prod --source CORE-1 --target CORE-2 --type duplicates
youtrack-mgmt issue update --label prod CORE-1 --state 'In Progress'
youtrack-mgmt issue update --label prod CORE-1 --state 'In Progress' --apply
youtrack-mgmt issue comment-list --label prod ABC-123
youtrack-mgmt issue board-add --label prod ABC-123 --board 83-1 --current-sprint --dry-run

youtrack-mgmt q 'schema()'
youtrack-mgmt q 'board_my_tasks(label="prod") { default }'
youtrack-mgmt m 'schema()'
youtrack-mgmt m --dry-run 'issue_create(summary="Investigate", project="CORE", description="Details", assignee="alexis", initiator="alexis")'

Agent DSL

Read operations:

• schema()
• auth_resolve(...)
• auth_whoami(...)
• instances_list()
• instances_current(...)
• board_list(...)
• board_current(...)
• board_show(...)
• board_sprints(...)
• board_issues(...)
• board_scoped_issues(...)
• board_tasks(...)
• board_my_tasks(...)
• issue_brief(...)
• issue_show(...)
• issue_search(...)
• issue_comments(...)

Write operations:

• schema()
• issue_create(...)
• issue_create_subtask(...)
• issue_link(...)
• issue_update(...)
• issue_command(...)
• issue_board_add(...)
• issue_board_remove(...)
• issue_comment_add(...)
• issue_comment_update(...)
• issue_comment_delete(...)

Example:

youtrack-mgmt q 'schema()'
youtrack-mgmt q 'instances_current() { instance }'
youtrack-mgmt q 'board_show("83-1") { default }'
youtrack-mgmt q 'board_my_tasks(label="prod") { default }'
youtrack-mgmt q 'issue_comments("ABC-123") { default }'
youtrack-mgmt m 'schema()'
youtrack-mgmt m --dry-run 'issue_update("ABC-123", state="In Progress")'

About Relux Works

This project is part of the open-source ecosystem of Relux Works, an AI-native software development studio. We build fixed-price MVPs, rescue vibe-coded apps, run local AI inference, and train teams to work with coding agents. Much of the infrastructure behind that work is open source.

• Full catalog: relux.works/en/open-source
• Agentic enablement: agent harnesses & team training
• Hire us the agent-native way: point your assistant at https://api.relux.works/mcp
• Contact: ivan@relux.works