ns-execution-gitlab-issue

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Execute GitLab Issue

执行GitLab Issue

Entry priority 1 for GitLab
ISSUE_URL
. Owns GitLab issue state end to end — status, branch/worktree lifecycle, MR, comments, delivery, review gate. Delegates actual coding to the
ns-autonomous
engine (Phase 2). Full routing:
../../ns-harness/references/code-skill-routing.md
.
针对GitLab
ISSUE_URL
的入口优先级为1。全权负责GitLab issue的全生命周期状态——包括状态、分支/工作树生命周期、MR、评论、交付、审核校验。实际编码任务委托给
ns-autonomous
引擎(第二阶段)。完整路由:
../../ns-harness/references/code-skill-routing.md

Routing (read first)

路由(请先阅读)

Entry priority 1. Harness table:
../../ns-harness/references/code-skill-routing.md
. Trigger phrases:
references/entry-triggers.md
.
HandoffTarget
Phase 2 execution
ns-autonomous
(Engine mode)
MR / status / time / comments
mcp-gitlab-usage
Phase 4 review gate
reviewer-agent
ns-reviewer
Rejected fix loop
ns-autonomous
C2
subagents (same worktree; no re-entry to this skill from
A
/
C2
)
G
remains the single GitLab lifecycle owner until delivery completes. Work units under
A
must not re-open this skill.
入口优先级1。路由对照表:
../../ns-harness/references/code-skill-routing.md
。触发短语:
references/entry-triggers.md
交接对象目标
第二阶段执行
ns-autonomous
(引擎模式)
MR / 状态 / 时间 / 评论
mcp-gitlab-usage
第四阶段审核校验
reviewer-agent
ns-reviewer
修复循环驳回
ns-autonomous
C2
子代理(同一工作树;禁止从
A
/
C2
重新进入此技能)
在交付完成前,
G
始终是GitLab生命周期的唯一负责人。
A
下的工作单元不得重新启动此技能。

Session boot

会话启动

See
../../ns-harness/references/session-boot.md
. Complete Session boot (blocking) there before any MCP call. Read
mcp-gitlab-usage
after Session boot.
详见
../../ns-harness/references/session-boot.md
在调用任何MCP之前,必须完成会话启动(阻塞式)。会话启动后阅读
mcp-gitlab-usage
文档。

Inputs

输入参数

VariableRequired
ISSUE_URL
Yes
SOURCE_BRANCH
No — resolved by Gate 1 if omitted
Single worktree, single branch, single MR, single commit per issue:
  • WORKTREE_ROOT = .worktrees/{ISSUE_ID}
  • WORK_BRANCH = work/{ISSUE_ID}-{ISSUE_SLUG}
变量名是否必填
ISSUE_URL
SOURCE_BRANCH
否 — 若未填写则由第一阶段校验自动解析
每个issue对应单一工作树、单一分支、单一MR、单一提交:
  • WORKTREE_ROOT = .worktrees/{ISSUE_ID}
  • WORK_BRANCH = work/{ISSUE_ID}-{ISSUE_SLUG}

Phase 0 — Context (boot before MCP)

第0阶段 — 上下文(调用MCP前启动)

  1. Session boot (blocking) — complete
    ../../ns-harness/references/session-boot.md
    before any MCP call.
  2. Ensure
    .worktrees/
    is gitignored (see
    references/worktree-setup.md
    ).
  3. Read
    mcp-gitlab-usage
    before the first MCP call.
  1. 会话启动(阻塞式) — 在调用任何MCP之前,完成
    ../../ns-harness/references/session-boot.md
    中的步骤。
  2. 确保
    .worktrees/
    已加入git忽略规则(详见
    references/worktree-setup.md
    )。
  3. 首次调用MCP前阅读
    mcp-gitlab-usage
    文档。

Phase 1 — Prepare

第1阶段 — 准备

First act (mandatory, before any gate)

首要操作(必填,任何校验前执行)

Apply
status_in_progress
(Em andamento) to the issue via MCP. If this call fails, abort immediately and wait for human intervention — nothing below runs on an issue that isn't marked in progress.
通过MCP将issue状态设为
status_in_progress
(进行中)。若此调用失败,立即终止流程并等待人工干预——未标记为进行中的issue不得执行后续任何操作。

Gate 0 — Existing branch/MR reuse

校验0 — 复用已有分支/MR

An issue may already have a work branch (e.g. returned by a human reviewer). Detect it before Gate 1 so you never open a duplicate branch/MR:
  1. list_issue_merge_requests
    — look for an open MR whose
    source_branch
    matches
    work/{ISSUE_ID}-*
    ; record its
    source_branch
    and
    target_branch
    .
  2. git ls-remote --heads origin "work/{ISSUE_ID}-*"
    as a second signal.
  3. Found →
    REUSE_MODE = true
    ,
    WORK_BRANCH = {existing branch}
    ,
    SOURCE_BRANCH = {existing MR target}
    . Skip
    WORK_BRANCH
    derivation below and skip Gate 1 (only re-validate the branch still exists on the remote).
  4. Not found →
    REUSE_MODE = false
    , proceed to Gate 1.
issue可能已存在工作分支(例如由人工审核者返回的分支)。在执行校验1前检测该分支,避免创建重复分支/MR:
  1. list_issue_merge_requests
    — 查找
    source_branch
    匹配
    work/{ISSUE_ID}-*
    的开放MR;记录其
    source_branch
    target_branch
  2. 执行
    git ls-remote --heads origin "work/{ISSUE_ID}-*"
    作为二次验证。
  3. 找到分支 → 设置
    REUSE_MODE = true
    WORK_BRANCH = {existing branch}
    SOURCE_BRANCH = {existing MR target}
    。跳过下方
    WORK_BRANCH
    推导步骤及校验1(仅需重新验证远程分支是否仍存在)。
  4. 未找到分支 → 设置
    REUSE_MODE = false
    ,继续执行校验1。

Gate 1 — SOURCE_BRANCH (mandatory, blocking; skipped when
REUSE_MODE = true
)

校验1 — SOURCE_BRANCH(必填,阻塞式;
REUSE_MODE = true
时跳过)

Resolve
SOURCE_BRANCH
only via
references/source-branch-resolution.md
(priority order: human → issue text → product rule → milestone/version discovery → mandatory
develop
fallback).
  • Never infer from the current checkout or ad hoc heuristics.
  • Never auto-use any branch except a discovered version-relative
    develop_*
    /
    develop-*
    or the
    develop
    fallback — other bases (
    homolog
    ,
    release/*
    ,
    main
    ,
    master
    , etc.) require explicit human confirmation this run.
  • main
    /
    master
    are allowed as
    SOURCE_BRANCH
    only with express human authorization this run — never auto; issue text naming them alone is not enough (ask once).
After resolution, validate on the remote (fetch,
ls-remote
,
_
-
alternates) per the same reference. When the mandatory
develop
fallback is missing on the remote → abort with the exact error; ask the operator once.
仅通过
references/source-branch-resolution.md
解析
SOURCE_BRANCH
(优先级顺序:人工指定 → issue文本 → 产品规则 → 里程碑/版本发现 → 强制
develop
分支兜底)。
  • 禁止从当前检出分支或临时启发式规则推导。
  • 禁止自动使用除已发现的版本关联
    develop_*
    /
    develop-*
    分支或
    develop
    兜底分支之外的任何分支——其他基准分支(
    homolog
    release/*
    main
    master
    等)需本次运行的明确人工确认。
  • main
    /
    master
    仅在本次运行获得明确人工授权时才可作为
    SOURCE_BRANCH
    ——禁止自动使用;仅issue文本提及不足以生效(需询问一次)。
解析完成后,参照同一文档在远程仓库验证(拉取、
ls-remote
_
-
替代规则)。若强制兜底的
develop
分支在远程不存在 → 终止流程并返回明确错误;询问操作者一次。

Gate 1.5 — Single worktree (monorepo)

校验1.5 — 单一工作树(单体仓库)

Create
WORKTREE_ROOT
per
references/worktree-setup.md
— always
.worktrees/{ISSUE_ID}
, never under
.cursor/
. Abort if a worktree already exists for this
ISSUE_ID
and is in use by another run, unless this is an explicit resume. Never implement in the main checkout or on
main
/
master
/
SOURCE_BRANCH
. If
git worktree add
fails → abort with the exact error (do not fall back to the main checkout "to keep going"). Isolation is a hard gate before Phase 2.
按照
references/worktree-setup.md
创建
WORKTREE_ROOT
——固定为
.worktrees/{ISSUE_ID}
,禁止在
.cursor/
下创建。若此
ISSUE_ID
对应的工作树已存在且被其他运行占用,除非是明确的恢复操作,否则终止流程。禁止在主检出分支或
main
/
master
/
SOURCE_BRANCH
上执行实现逻辑。若
git worktree add
失败 → 终止流程并返回明确错误(不得回退到主检出分支继续执行)。隔离性是进入第二阶段前的硬性校验规则。

MCP setup

MCP配置

  • due_date
    if empty: current date + 5 business days.
  • Do not set
    START_TIME
    here — wall-clock for spent time starts at Phase 2 (see
    references/time-tracking.md
    ).
  • due_date
    为空:设为当前日期 + 5个工作日。
  • 请勿在此处设置
    START_TIME
    ——耗时统计的实际开始时间为第二阶段(详见
    references/time-tracking.md
    )。

Phase 2 — Execution (delegated)

第2阶段 — 执行(委托式)

  1. Read the full issue payload via MCP (title, description, comments, attachments). Note
    time_stats.time_estimate
    for the estimate gate below.
  2. Set
    START_TIME
    /
    START_EPOCH
    now (UTC + Unix epoch) — immediately before the first Engine invoke. See
    references/time-tracking.md
    .
  3. Invoke the
    ns-autonomous
    skill in Engine mode, passing: issue payload,
    WORKTREE_ROOT
    ,
    WORK_BRANCH
    ,
    SOURCE_BRANCH
    . The engine self-decides planning depth, runs its doubt protocol, and dispatches implementation (single- or multi-agent) inside
    WORKTREE_ROOT
    — see
    ns-autonomous
    's
    references/routing.md
    for what "Engine mode" means and what it returns.
  4. Estimate (first invocation only): call
    set_issue_estimate
    only if
    time_stats.time_estimate
    is empty (
    0
    / missing) and the engine returned
    estimate_seconds
    ≥ 60. If an estimate already exists, or the engine value is < 60 — skip; never overwrite, never write a 1-second estimate. Full rules:
    references/time-tracking.md
    .
  5. Doubt escalation contract — the engine never mutates GitLab state itself. When it returns a destructive-doubt event instead of (or alongside) unit results:
    • Record
      PAUSE_START
      epoch (exclude wait from spent time).
    • Apply
      status_blocked
      (Em Impedimento).
    • Post a comment mentioning the issue author (
      @{author.username}
      from
      read_issue
      ) with the questions, options, and recommended default.
    • Mirror the same question in the interactive chat and wait.
    • On answer (chat and/or issue comment): add pause duration to
      PAUSED_SECONDS
      , set status back to
      status_in_progress
      (Em andamento), and re-invoke the engine with the resolved doubt appended to its context.
  6. No intermediate confirmations otherwise — this loop is the only pause point until Phase 4's review gate.
  1. 通过MCP读取完整issue payload(标题、描述、评论、附件)。记录
    time_stats.time_estimate
    用于后续预估校验。
  2. 立即设置
    START_TIME
    /
    START_EPOCH
    (UTC + Unix时间戳)——就在首次调用引擎之前。详见
    references/time-tracking.md
  3. 引擎模式调用
    ns-autonomous
    技能,传入:issue payload、
    WORKTREE_ROOT
    WORK_BRANCH
    SOURCE_BRANCH
    。引擎将自行决定规划深度、执行疑问协议,并在
    WORKTREE_ROOT
    内调度实现逻辑(单代理或多代理)——详见
    ns-autonomous
    references/routing.md
    中关于“引擎模式”的定义及返回内容。
  4. 预估(仅首次调用):仅当
    time_stats.time_estimate
    为空(
    0
    /缺失)引擎返回的
    estimate_seconds
    ≥60时,调用
    set_issue_estimate
    。若已有预估,或引擎返回值<60 —— 跳过;禁止覆盖已有预估,禁止写入1秒预估。完整规则:
    references/time-tracking.md
  5. 疑问升级约定 — 引擎不得自行修改GitLab状态。当引擎返回破坏性疑问事件而非(或同时返回)单元结果时:
    • 记录
      PAUSE_START
      时间戳(暂停时间不计入耗时)。
    • 将状态设为
      status_blocked
      (阻塞)。
    • 发布一条**@issue作者**的评论(从
      read_issue
      获取
      @{author.username}
      ),包含问题、选项及推荐默认值。
    • 在交互式聊天中同步相同问题并等待回复。
    • 收到回复(聊天和/或issue评论)后:将暂停时长加入
      PAUSED_SECONDS
      ,将状态改回
      status_in_progress
      (进行中),并将已解决的疑问追加到上下文后重新调用引擎。
  6. 除此循环外,无其他中间确认环节——直至第四阶段审核校验前均无暂停点。

Phase 3 — Delivery

第3阶段 — 交付

  1. Squash to one Conventional Commit before push (
    <type>(#{ISSUE_ID}): <imperative description in English>
    , types: feat/fix/refactor/test/docs/chore). The engine may leave internal checkpoint commits per work unit in the worktree during Phase 2 — squash them here to preserve one-commit-per-delivery atomicity. See
    ../../ns-harness/references/agent-git-identity.md
    for attribution.
  2. Push
    WORK_BRANCH
    .
  3. Run Phase 4 (review gate). Do not set
    END_TIME
    , spent time, or Dev 100% until Phase 4 returns
    Approved
    .
  4. On
    Approved
    only — close the clock and board
    (same instant):
    • Set
      END_TIME
      /
      END_EPOCH
      now.
    • add_issue_spent_time
      with
      duration = ELAPSED_SECONDS
      from
      references/time-tracking.md
      (epoch delta minus
      PAUSED_SECONDS
      ). Never use
      estimate_seconds
      or any plan estimate as
      duration
      .
    • Status →
      status_done
      (Dev 100%).
    • Internal delivery comment (
      internal: true
      ) using
      references/delivery-report.template.md
      .
  1. 合并为单一规范提交后再推送(格式:
    <type>(#{ISSUE_ID}): <英文祈使句描述>
    ,类型包括:feat/fix/refactor/test/docs/chore)。引擎在第二阶段可能会在工作树中留下各工作单元的内部检查点提交——在此处合并这些提交,以保持“每次交付对应单一提交”的原子性。署名规则详见
    ../../ns-harness/references/agent-git-identity.md
  2. 推送
    WORK_BRANCH
  3. 执行第四阶段(审核校验)。仅当第四阶段返回
    Approved
    后,才可设置
    END_TIME
    、耗时统计及标记Dev 100%完成。
  4. 仅在
    Approved
    时——关闭计时与看板
    (同一时刻):
    • 立即设置
      END_TIME
      /
      END_EPOCH
    • 调用
      add_issue_spent_time
      ,传入
      duration = ELAPSED_SECONDS
      (来自
      references/time-tracking.md
      ,时间戳差值减去
      PAUSED_SECONDS
      )。禁止使用
      estimate_seconds
      或任何计划预估作为
      duration
    • 状态改为
      status_done
      (开发完成100%)。
    • 使用
      references/delivery-report.template.md
      发布内部交付评论(
      internal: true
      )。

Phase 4 — Review gate (blocking, bounded fix loop)

第4阶段 — 审核校验(阻塞式,有限修复循环)

Canonical rules:
../ns-reviewer/references/review-gate-workflow.md
.
  1. MUST invoke
    reviewer-agent
    when available (else
    ns-reviewer
    ) in Issue review mode (
    ISSUE_URL
    ) only — bridge/skill loads
    AGENTS.md
    then reviewer workflow. Read-only official gate; posts the internal GitLab comment. Forbidden: Task subagents (
    senior-tech-lead-reviewer
    ,
    bugbot
    ,
    security-review
    ) or any substitute unless the human explicitly requests it for this run. Allowed: harness
    reviewer-agent
    . See
    ../../ns-harness/references/subagent-dispatch.md
    .
  2. Loop, max 3 rounds:
    • Approved
      → return to Phase 3 step 4 (END + spent + Dev 100% + delivery comment).
    • Rejected
      with rounds remaining → re-invoke
      ns-autonomous
      (same worktree/branch) with the findings as a fix work unit, then mandatory re-review via
      reviewer-agent
      (MUST when available; else
      ns-reviewer
      ). Keep the original
      START_TIME
      ; do not call spent/Dev 100% yet.
    • Blocked
      , or rounds exhausted →
      status_blocked
      (Em Impedimento), post the findings, stop. Do not set
      END_TIME
      , spent time, or Dev 100%.
  3. Final output:
    Fatto!
    +
    MR_URLS
    +
    Code Review: {verdict}
    — exactly the verdict string
    ns-reviewer
    returned.
标准规则:
../ns-reviewer/references/review-gate-workflow.md
  1. 必须调用**
    reviewer-agent
    (若不可用则调用
    ns-reviewer
    ),且仅以Issue审核模式**(
    ISSUE_URL
    )调用——桥接/技能将加载
    AGENTS.md
    并执行审核流程。此为只读官方校验环节;将发布内部GitLab评论。禁止:调用任务子代理(
    senior-tech-lead-reviewer
    bugbot
    security-review
    )或任何替代工具,除非人工明确要求本次运行使用。允许:调用harness的
    reviewer-agent
    。详见
    ../../ns-harness/references/subagent-dispatch.md
  2. 循环最多3轮:
    • Approved
      → 返回第3阶段步骤4(结束计时 + 耗时统计 + Dev 100% + 交付评论)。
    • Rejected
      且仍有剩余轮次 → 重新调用
      ns-autonomous
      (同一工作树/分支),将审核结果作为修复工作单元传入,然后必须再次通过
      reviewer-agent
      (可用时必须调用;否则调用
      ns-reviewer
      )进行重新审核。保留原始
      START_TIME
      ;暂不调用耗时统计/标记Dev 100%。
    • Blocked
      或轮次耗尽 → 设置
      status_blocked
      (阻塞),发布审核结果,终止流程。禁止设置
      END_TIME
      、耗时统计及标记Dev 100%。
  3. 最终输出:
    Fatto!
    +
    MR_URLS
    +
    Code Review: {verdict}
    —— 完全使用
    ns-reviewer
    返回的判定字符串。

Stop and ask the human

终止流程并询问人工

ConditionAction
Gate 1:
develop
fallback missing on remote
Stop — ask once
Gate 1: non-default base (
main
/
master
/
homolog
/…) without express human confirmation this run
Stop — ask once
Worktree conflict (same issue, another run)Stop unless explicit resume
Ambiguous or conflicting acceptance criteriaStop — ask once
MCP unavailable or auth failureStop — state blocker
project_id
trio not confirmed
Stop per
mcp-gitlab-usage
Work on protected/base branch per
gitlab-sync-config.md
Stop
Destructive ops (issue delete, force-push main/master)Stop — require explicit human
Product decision not stated in the issueStop — ask once
Engine reports a destructive doubtPause/resume per Phase 2 step 4 — not a hard stop
See
mcp-gitlab-usage
for MCP tool contracts and confirmation gates.
条件操作
校验1:远程仓库缺失
develop
兜底分支
终止流程 — 询问一次
校验1:使用非默认基准分支(
main
/
master
/
homolog
/…)且未获得本次运行的明确人工确认
终止流程 — 询问一次
工作树冲突(同一issue被其他运行占用)终止流程,除非是明确的恢复操作
验收标准模糊或冲突终止流程 — 询问一次
MCP不可用或认证失败终止流程 — 标记为阻塞
project_id
三元组未确认
按照
mcp-gitlab-usage
终止流程
在受保护/基准分支上操作(依据
gitlab-sync-config.md
终止流程
破坏性操作(删除issue、强制推送main/master)终止流程 — 需明确人工授权
issue中未明确产品决策终止流程 — 询问一次
引擎报告破坏性疑问按照第2阶段步骤4暂停/恢复 — 并非硬性终止
MCP工具约定及确认校验规则详见
mcp-gitlab-usage

Related skills

相关技能

SkillRole
mcp-gitlab-usage
All GitLab tools
ns-gitlab-board-sync
Status label semantics
ns-reviewer
Phase 4 gate (MUST
reviewer-agent
when available)
ns-autonomous
Phase 2 execution engine
ns-coder
Non-GitLab ad-hoc implementation
技能角色
mcp-gitlab-usage
所有GitLab工具的操作入口
ns-gitlab-board-sync
状态标签语义同步
ns-reviewer
第四阶段校验环节(可用时必须调用
reviewer-agent
ns-autonomous
第二阶段执行引擎
ns-coder
非GitLab场景的临时编码实现

References

参考文档

FileWhen
references/source-branch-resolution.md
Gate 1 — milestone/version discovery,
develop
fallback, remote validation
references/worktree-setup.md
ISSUE_ID
run_id
override (canonical mechanics in
ns-harness
)
references/mr-conventions.md
MR title, draft, linking, reuse note
references/delivery-report.template.md
Phase 3 internal delivery comment
references/time-tracking.md
Estimate fill-if-empty; spent-time wall-clock + pause rules
文件路径使用场景
references/source-branch-resolution.md
校验1 — 里程碑/版本发现、
develop
分支兜底、远程仓库验证
references/worktree-setup.md
ISSUE_ID
run_id
覆盖规则(标准机制在
ns-harness
中)
references/mr-conventions.md
MR标题、草稿状态、关联规则、复用说明
references/delivery-report.template.md
第3阶段内部交付评论模板
references/time-tracking.md
预估补全规则;耗时统计的时钟计时+暂停规则