OpenSpec ↔ Issues (Jira / GitHub)
Espelha uma change OpenSpec (.md, canônica) para um rastreador externo — Jira e/ou GitHub Issues — no transporte que o usuário escolher (MCP ou CLI gh).
O OpenSpec permanece a fonte de verdade. O tracker é uma visão para o time. Não substituímos o store openspec/ nem o validate/archive do CLI.
Pré-requisito — tracker profile
A escolha de onde criar as tarefas e como (MCP vs CLI) é feita na criação do AGENTS.md (skill config-agents-md) e/ou registrada em <docsPath>/planning/<projeto>/tracker-profile.md.
Campos (ver references/tracker-config.md):
tracking:
trackers: [github] # jira | github | both | none
transport: auto # mcp | gh | auto (auto = MCP se disponível, senão gh/CLI)
github:
repo: org/repo # ou derivar do git remote
labels: [openspec] # + epic:/priority: por issue
jira:
project_key: PROJ
issue_type: Story
epic_link_field: customfield_100xx
direction: one-way # one-way (OpenSpec→tracker) | two-way
id_map: .openspec-sync.json
Se o profile não existir, pergunte antes de criar qualquer issue:
"Onde devo criar as tarefas deste projeto? [ ] Jira [ ] GitHub Issues [ ] Ambos [ ] Nenhum E como devo acessá-los? [ ] MCP [ ] CLI (
gh/API) [ ] Auto"
Pré-flight — o destino deve existir
Antes do primeiro write, verificar que os recursos do profile existem de fato:
- Repo:
gh repo view <org>/<repo>(ou equivalente MCP). Se não existir e houver remote local, propor o provisionamento (gh repo create) — confirmar com o usuário; se recusado, parar. - Project (quando o profile declarar
project):gh project view <n> --owner <org>. Se não existir, propor criação (gh project create+gh project link) — ou prosseguir sem project avisando que o fluxo de status fica desabilitado. - Campo de status: se houver project, conferir
status_field_id+status_optionsno profile. Se ausentes, propor provisionar o campo Status (Backlog → Em desenvolvimento → Revisão → Concluído) e gravar os IDs no profile (procedimento em../config-agents-md/SKILL.md§Fase 0.1.1). - Labels: criar as declaradas no profile se não existirem (
gh label create).
Sem destino provisionado, não criar issue "em algum lugar" — o espelho sem home é dívida.
Transporte (MCP vs CLI)
transport no profile decide a ferramenta. Regra da casa: preferir MCP quando existir; só cair para CLI se o MCP estiver indisponível — e avisar o usuário. Ver references/transports.md.
| Tracker | MCP (preferido) | CLI (fallback) |
|---|---|---|
| GitHub Issues | github_* (issue_write, search_issues, list_issues, sub_issue_write) |
gh issue create/edit/close, gh api |
| Jira | atlassian_jira_* (jira_create_issue, jira_search, jira_get_transitions, jira_transition_issue, jira_batch_create_issues) |
API REST / jira CLI (só se MCP indisponível) |
Workflow
Fase 0 — Contexto
- Ler a constituição do projeto (norma em
../skills-standards.md§4.2):AGENTS.mdda raiz, seção de rastreamento de tarefas. O formato de tasks, as labels e o tracker declarados pelo projeto prevalecem sobre os defaults desta skill. - Ler o
tracker-profile.md(ouskills.config.json→tracking). Se ausente, perguntar. Precedência: argumento do usuário >AGENTS.md>tracker-profile.md>skills.config.json>none. - Resolver o
--storedo OpenSpec, se houver:openspec store list --json. - Selecionar a change:
openspec list --json→--change "<name>"(se ambíguo, perguntar).
Fase 1 — Ler a change
openspec list --json
openspec show "<name>" --json # metadados + status dos artefatos
Ler o diretório openspec/changes/<name>/:
proposal.md— what & why (→ corpo do épico/issue principal)specs/<capability>/spec.md— delta (requirements/scenarios → stories/critérios)tasks.md— passos de implementação (→ subtasks/checklist)
Fase 2 — Mapear
| OpenSpec | Jira / GitHub Issues |
|---|---|
| change | Épico (Jira) / Issue principal (GitHub) |
| requirement/scenario (delta) | Story / item + critérios de aceite |
task (domain:*, app:*, infra:*, interface:*, test:*) |
Subtask / checklist item; prefixo e **Agent:** viram label/descrição |
O corpo da issue segue o template de spec de references/spec-issue-template.md (Problem / Solution / User Stories / Implementation Decisions / Testing Decisions / Out of Scope), preenchido a partir dos artefatos da change. O corpo aponta para a constituição do projeto (docs/ e AGENTS.md) pelo nome do documento e da seção, sem duplicar o conteúdo dela.
Detalhes e formato de tasks.md: references/mapping-openspec-tracker.md e docs/templates/openspec-task-template.yaml.
Fase 3 — Idempotência (ID map)
Antes de criar, consultar o ID map (.openspec-sync.json ou metadados em .openspec.yaml):
{
"fa-517-catalogo-pos": {
"epic": "PROJ-100",
"stories": { "REQ-1": "PROJ-101" },
"tasks": { "domain:entity": "PROJ-102" }
}
}
- Existe →
update(nunca recriar). - Não existe →
createe gravar o mapeamento. - Sempre marcar a origem: label
openspec:<change>+ link no corpo.
Fase 4 — Criar/atualizar
- GitHub (MCP): conforme
github.mode:single-issue(default/recomendado) — 1 issue por change com o corpo montado pelo template (references/spec-issue-template.md): Problem, Solution, User Stories, critérios de aceite do delta e as demais seções; artefatos completos em blocos<details>(seembed_artifacts) e tasks como checklist- [ ](o GitHub rastreia progresso). Labelopenspec,openspec:<change>,epic+priority:*+ labels de triagem declaradas pelo projeto.sub-issues— issue principal + 1 sub-issue por task (github_sub_issue_write); quando o repo suportar, criar as relações de bloqueio nativas (blocked by) a partir das dependências do plano.auto— tentasub-issues; se o repo não suportar, cai parasingle-issue.- Fallback CLI:
gh issue create/edit(ough api). - Project + status inicial: quando o profile declarar
project, adicionar a issue ao board (gh project item-add/addProjectV2ItemById) e setar Backlog (gh project item-edit --field-id <status_field_id> --single-select-option-id <backlog>). Guardar oitem_idno ID map — é ele que permite transicionar status depois.
- Jira (MCP): Épico → Story(s) → subtasks nativas por task (
jira_batch_create_issues/jira_create_issue+additional_fields.parent); linkar ao épico; criar as dependências como link nativo (is blocked by) quando o plano declarar bloqueios; setar campos (sprint/versão) se o profile declarar. Status inicial: coluna/to-do do fluxo do projeto. - Não duplicar: se já houver issue com a label
openspec:<change>, atualizar.
Ciclo de vida de status (project/board)
Quando o profile declarar project com status_options, o status segue o ciclo do projeto — quem transiciona é quem dispara o evento:
| Evento | De → Para | Quem |
|---|---|---|
| Change nova espelhada | → Backlog | esta skill (Fase 4) |
openspec-apply-change / opsx-apply inicia |
Backlog → Em desenvolvimento | esta skill (invocada no início do apply) |
| PR aberto ou CI validando | Em desenvolvimento → Revisão | esta skill (invocada ao abrir PR) ou o agente, reportando |
openspec-archive-change |
Revisão → Concluído + fechar issue | esta skill (Fase 5) |
Transição via CLI: gh project item-edit --project-id <project.id> --id <item_id do ID map> --field-id <status_field_id> --single-select-option-id <opção>. Sem item_id no ID map (issues antigas), re-obter com gh project item-list e filtrar pela issue. Em Jira: jira_get_transitions → jira_transition_issue.
Fase 5 — Archive → fechar
Ao rodar openspec archive (ou após arquivar):
- GitHub: setar status Concluído no project (quando houver) e fechar issues/subtasks (
state: closed,state_reason: completed). - Jira:
jira_get_transitions→jira_transition_issuepara Done; fechar subtasks. - Atualizar o ID map com o status final.
Guardrails
- Nunca tornar o tracker a fonte de verdade — o
.mdmanda; o tracker é espelho. - Nunca criar duplicata: sempre checar o ID map / label
openspec:<change>. - Não mudar status no tracker sem refletir o archive no OpenSpec.
- Respeitar a constituição do projeto (
AGENTS.md§rastreamento +../skills-standards.md§4.2): tracker, labels, formato de tasks e relação de bloqueio declarados pelo projeto prevalecem sobre os defaults desta skill. - Não duplicar documentos donos: o corpo da issue aponta para
docs/e para a change canônica pelo nome do documento e da seção, sem repetir arquitetura, contrato ou regras. - Confirmar com o usuário antes do primeiro write (criação em massa).
- Se o MCP não estiver disponível e o transporte for
mcp, pergunte antes de usargh/API REST. - Respeitar permissões: JSM
public=falsequando o projeto for interno (verJIRA_INTERNAL_ONLY_PROJECTS).
References
references/tracker-config.md— schema do tracker profile e como oconfig-agents-mdregistra a escolha.references/spec-issue-template.md— template do corpo da issue (spec) e de onde vem cada seção.references/mapping-openspec-tracker.md— mapeamento detalhado + formato do ID map.references/transports.md— comandos MCP vs CLI por tracker.../docs/templates/openspec-task-template.yaml— formato de task.../openspec-propose/SKILL.md— geração dos artefatos da change.../presets/pos/pos-tarefa/SKILL.md— precedente Jira → OpenSpec (preset de projeto).
Global Standards
- Consultar
../skills-standards.mdpara padrões globais de nomenclatura e convenções entre skills.