feat(skills): add jira-workflow, repo-map, docs-map, go-standards

- descriptions state WHEN each skill applies - jira-workflow ships curl scripts reading TRACKER_URL/JIRA_TOKEN from env, no hardcoded secrets/URLs - repo-map/docs-map defer values to session corporate context; company specifics left as TODO - go-standards uses realistic Go defaults, company-specific bits marked TODO
2026-07-16 10:57:00 +03:00
parent fe99b404fa
commit 0725b6b034
7 changed files with 250 additions and 0 deletions
--- a/skills/docs-map/SKILL.md
+++ b/skills/docs-map/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: docs-map
+description: Используй, когда нужно найти или написать внутреннюю документацию — где искать по теме, какие есть ключевые пространства/разделы, куда класть новую страницу или RFC. Применяй при вопросах «где документация», «куда записать», «есть ли дока по», а также в команде /rfc.
+---
+
+# Работа с документацией
+
+Скилл помогает искать существующую документацию и правильно размещать новую.
+
+## Адрес документации
+
+Адрес портала документации — в поле `docsUrl` корпоративного конфига. Его текущее значение
+инжектится в **корпоративный контекст сессии** расширением `company-context` — бери адрес
+оттуда, здесь он намеренно не дублируется (единый источник правды — `config/company.json`).
+
+## Ключевые пространства/разделы
+
+<!-- TODO: заполнить реальными значениями компании -->
+
+- **Архитектура и RFC:** `<!-- TODO: пространство/раздел -->`
+- **Гайды по сервисам:** `<!-- TODO -->`
+- **Онбординг:** `<!-- TODO -->`
+- **Runbooks / эксплуатация:** `<!-- TODO -->`
+
+## Как искать
+
+1. Начни с портала документации (адрес — из корпоративного контекста сессии).
+2. `<!-- TODO: описать, где встроенный поиск, теги/лейблы, как называть страницы -->`
+
+## Куда писать новое
+
+<!-- TODO: заполнить -->
+
+- Новую страницу по фиче: `<!-- TODO: в какое пространство/раздел -->`
+- RFC/ADR: `<!-- TODO: где живут, шаблон -->`
+- Правило: не дублируй информацию — сначала поищи существующую страницу и обнови её.
--- a/skills/go-standards/SKILL.md
+++ b/skills/go-standards/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: go-standards
+description: Используй при написании, ревью и проверке кода на Go в наших сервисах — структура сервиса, запуск линтеров и тестов, формат коммитов и merge request. Применяй всегда, когда пишешь или правишь Go-код, готовишь MR, а также в командах /bugfix, /feature и /review.
+---
+
+# Стандарты Go
+
+Наш основной стек — **Go**. Скилл описывает, как писать, проверять и оформлять код.
+Реалистичные общепринятые дефолты приведены ниже; то, что специфично для компании,
+помечено `TODO` — уточняй, не выдумывай.
+
+## Структура сервиса
+
+Ориентир (уточняется под компанию):
+
+```
+cmd/<service>/main.go      # точка входа
+internal/                  # приватный код сервиса
+  <domain>/                # доменные пакеты
+pkg/                       # переиспользуемый публичный код (если есть)
+api/                       # спецификации API (proto/openapi)
+```
+
+<!-- TODO: заполнить реальной эталонной структурой сервиса компании -->
+
+## Линтеры
+
+- Форматирование: `gofmt -l -w .` и `goimports -w .` — код должен быть отформатирован.
+- Статический анализ: `go vet ./...`.
+- Основной линтер: **golangci-lint** — `golangci-lint run ./...`.
+  Набор линтеров задаётся в `.golangci.yml` в корне репозитория.
+  <!-- TODO: указать корпоративный .golangci.yml / общий пресет, если он есть -->
+
+## Тесты
+
+- Прогон всех тестов: `go test ./...`.
+- С гонками и покрытием: `go test -race -cover ./...`.
+- Требования к покрытию и обязательные виды тестов: `<!-- TODO: пороги покрытия, интеграционные тесты -->`.
+- Именование: `TestXxx`, табличные тесты приветствуются.
+
+## Коммиты и MR
+
+- **Формат коммитов:** `<!-- TODO: например Conventional Commits (feat:, fix:, chore:) или свой -->`.
+- **Ветки:** от основной, именование `<!-- TODO: напр. feature/PROJ-123-short-desc -->`.
+- **MR обязателен** (см. корпоративные правила из контекста сессии). Прямой push в защищённые
+  ветки запрещён — расширение `permission-gate` дополнительно переспросит.
+- **Описание MR:** что и зачем изменено, как проверено (линтеры + тесты), ссылка на тикет
+  (см. скилл `jira-workflow`).
+- Перед MR прогони линтеры и тесты — всё должно быть зелёным.
+
+## Чек-лист перед MR
+
+- [ ] `gofmt`/`goimports` без изменений
+- [ ] `go vet ./...` чисто
+- [ ] `golangci-lint run ./...` чисто
+- [ ] `go test ./...` (или `-race`) зелёные
+- [ ] есть тесты на новую логику / фикс
+- [ ] нет секретов и закоммиченных `.env`
+- [ ] описание MR со ссылкой на тикет
--- a/skills/jira-workflow/SKILL.md
+++ b/skills/jira-workflow/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: jira-workflow
+description: Используй, когда нужно работать с корпоративным трекером задач (Jira) — прочитать тикет по ключу, добавить комментарий, приложить ссылку на MR, разобраться в статусах и переходах. Применяй при упоминании ключей задач, «тикет», «задача в трекере», «переведи в статус», а также в командах /bugfix и /feature.
+---
+
+# Работа с трекером задач (Jira)
+
+Скилл описывает, как читать и обновлять задачи в нашем трекере через REST API.
+
+## Откуда берутся адрес и токен
+
+**Никогда не хардкодь и не спрашивай их отдельно — они уже есть в окружении.**
+
+- **Базовый адрес трекера** — из переменной окружения `TRACKER_URL`. Если она не задана,
+  возьми адрес трекера из корпоративного контекста сессии (его инжектит расширение
+  `company-context`).
+- **Токен доступа** — из переменной окружения `JIRA_TOKEN` (personal access token).
+- Токен в команды и логи не подставляй в открытом виде — скрипты читают его из окружения сами.
+
+Быстрая проверка окружения:
+
+```bash
+: "${TRACKER_URL:?установи TRACKER_URL или возьми адрес из корпоративного контекста}"
+: "${JIRA_TOKEN:?установи JIRA_TOKEN (personal access token трекера)}"
+```
+
+## Готовые скрипты
+
+Все скрипты лежат в `scripts/` и читают `TRACKER_URL` и `JIRA_TOKEN` из окружения:
+
+- `./scripts/get-issue.sh <KEY>` — получить тикет (поля summary, status, description).
+- `./scripts/add-comment.sh <KEY> "<текст>"` — добавить комментарий.
+- `./scripts/link-mr.sh <KEY> "<url-MR>" ["<заголовок>"]` — приложить ссылку на MR
+  (добавляется комментарием со ссылкой; при доступном remote link API — см. TODO в скрипте).
+
+Пример:
+
+```bash
+./scripts/get-issue.sh PROJ-123
+./scripts/add-comment.sh PROJ-123 "Начал работу, воспроизвёл баг"
+./scripts/link-mr.sh PROJ-123 "https://<git-host>/ai/foo/-/merge_requests/42" "Fix PROJ-123"
+```
+
+## Соглашения
+
+<!-- TODO: заполнить реальными значениями компании -->
+
+- **Формат ключей задач:** `<!-- TODO: например PROJ-123, префиксы проектов -->`
+- **Статусы и переходы:** `<!-- TODO: рабочий процесс, напр. To Do → In Progress → In Review → Done -->`
+- **Кто и когда меняет статус:** `<!-- TODO: договорённости команды -->`
+- **Что писать в комментарии при старте/готовности:** `<!-- TODO -->`
+
+## Полезное
+
+- ID переходов статуса можно получить через `GET /rest/api/2/issue/<KEY>/transitions`,
+  выполнить переход — `POST` туда же с `{"transition":{"id":"<id>"}}`.
+- Если API возвращает 401/403 — проверь `JIRA_TOKEN` и права. Не логируй сам токен.
--- a/skills/jira-workflow/scripts/add-comment.sh
+++ b/skills/jira-workflow/scripts/add-comment.sh
@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# add-comment.sh <ISSUE_KEY> "<comment text>"
+# Adds a comment to a tracker issue.
+# Reads TRACKER_URL and JIRA_TOKEN from the environment. No secrets are hardcoded.
+set -euo pipefail
+
+KEY="${1:?usage: add-comment.sh <ISSUE_KEY> \"<text>\"}"
+TEXT="${2:?usage: add-comment.sh <ISSUE_KEY> \"<text>\"}"
+: "${TRACKER_URL:?set TRACKER_URL (or take the tracker address from the session corporate context)}"
+: "${JIRA_TOKEN:?set JIRA_TOKEN (tracker personal access token)}"
+
+BASE="${TRACKER_URL%/}"
+
+# Build JSON body safely (jq escapes the text); fall back to a naive body if jq is absent.
+if command -v jq >/dev/null 2>&1; then
+  BODY="$(jq -n --arg b "$TEXT" '{body: $b}')"
+else
+  BODY="{\"body\": \"${TEXT//\"/\\\"}\"}"
+fi
+
+curl -fsS -X POST \
+  -H "Authorization: Bearer ${JIRA_TOKEN}" \
+  -H "Content-Type: application/json" \
+  -d "$BODY" \
+  "${BASE}/rest/api/2/issue/${KEY}/comment" >/dev/null
+
+echo "Comment added to ${KEY}"
--- a/skills/jira-workflow/scripts/get-issue.sh
+++ b/skills/jira-workflow/scripts/get-issue.sh
@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# get-issue.sh <ISSUE_KEY>
+# Prints summary, status and description of a tracker issue.
+# Reads TRACKER_URL and JIRA_TOKEN from the environment. No secrets are hardcoded.
+set -euo pipefail
+
+KEY="${1:?usage: get-issue.sh <ISSUE_KEY>}"
+: "${TRACKER_URL:?set TRACKER_URL (or take the tracker address from the session corporate context)}"
+: "${JIRA_TOKEN:?set JIRA_TOKEN (tracker personal access token)}"
+
+BASE="${TRACKER_URL%/}"
+
+curl -fsS \
+  -H "Authorization: Bearer ${JIRA_TOKEN}" \
+  -H "Accept: application/json" \
+  "${BASE}/rest/api/2/issue/${KEY}?fields=summary,status,description" \
+  | { jq -r '"\(.key)\t\(.fields.status.name)\n\(.fields.summary)\n\n\(.fields.description // "")"' 2>/dev/null || cat; }
--- a/skills/jira-workflow/scripts/link-mr.sh
+++ b/skills/jira-workflow/scripts/link-mr.sh
@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# link-mr.sh <ISSUE_KEY> "<mr-url>" ["<title>"]
+# Attaches a merge request link to a tracker issue.
+# Default implementation posts a comment with the link (works on any Jira).
+# Reads TRACKER_URL and JIRA_TOKEN from the environment. No secrets are hardcoded.
+set -euo pipefail
+
+KEY="${1:?usage: link-mr.sh <ISSUE_KEY> \"<mr-url>\" [\"<title>\"]}"
+URL="${2:?usage: link-mr.sh <ISSUE_KEY> \"<mr-url>\" [\"<title>\"]}"
+TITLE="${3:-Merge request}"
+: "${TRACKER_URL:?set TRACKER_URL (or take the tracker address from the session corporate context)}"
+: "${JIRA_TOKEN:?set JIRA_TOKEN (tracker personal access token)}"
+
+BASE="${TRACKER_URL%/}"
+
+# Default: comment with the MR link.
+COMMENT="${TITLE}: ${URL}"
+exec "$(dirname "$0")/add-comment.sh" "$KEY" "$COMMENT"
+
+# TODO: если в компании используется remote issue link API, заменить на:
+#   POST ${BASE}/rest/api/2/issue/${KEY}/remotelink
+#   с телом {"object":{"url":"<URL>","title":"<TITLE>"}}
--- a/skills/repo-map/SKILL.md
+++ b/skills/repo-map/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: repo-map
+description: Используй, когда нужно сориентироваться в наших репозиториях — найти нужный сервис, понять соглашения по именованию репозиториев, где лежат CI-конфиги, куда добавлять новый сервис. Применяй при вопросах «где код», «в каком репозитории», «как найти сервис», а также в начале работы по /feature и /bugfix.
+---
+
+# Карта репозиториев
+
+Скилл помогает понять, где что лежит, и быстро найти нужный сервис.
+
+## Актуальная карта
+
+Конкретная карта репозиториев — в поле `repoMap` корпоративного конфига. Её текущее значение
+инжектится в **корпоративный контекст сессии** расширением `company-context` — смотри туда,
+здесь оно намеренно не дублируется (единый источник правды — `config/company.json`).
+
+Адрес git-хоста также берётся из корпоративного контекста сессии.
+
+## Соглашения
+
+<!-- TODO: заполнить реальными значениями компании -->
+
+- **Именование репозиториев:** `<!-- TODO: напр. <домен>-<сервис>, service-*, lib-* -->`
+- **Группы/неймспейсы в git:** `<!-- TODO: какие группы за что отвечают -->`
+- **Где CI-конфиги:** `<!-- TODO: напр. .gitlab-ci.yml в корне, шаблоны в группе ci/ -->`
+- **Общие библиотеки:** `<!-- TODO: где переиспользуемый код -->`
+- **Как заводится новый сервис:** `<!-- TODO: шаблон/cookiecutter, чек-лист -->`
+
+## Как искать сервис
+
+1. Загляни в `repoMap` из корпоративного контекста сессии — там верхнеуровневая карта.
+2. Если нужен поиск по коду — используй поиск по git-хосту (адрес из корп. контекста).
+3. Определи владельца по неймспейсу/группе репозитория.