ai-sdlc-branching

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ai-sdlc-branching: Branching

ai-sdlc-branching: 分支管理

Internal AI SDLC skill, not client-facing by default. Every rule below is important to follow. None of it can be skipped. Before producing the final artifact, confirm required inputs, target audience, missing facts, output format, and constraints when they are unclear. Do not invent missing information. Ask concise clarification questions when required inputs are absent.

内部AI SDLC技能，默认不面向客户。以下每条规则都必须遵守，不可跳过任何一条。在生成最终产物前，若所需输入、目标受众、缺失信息、输出格式和约束条件不明确，请确认这些内容。不得编造缺失信息。当所需输入缺失时，提出简洁的澄清问题。

0. Skill Card

0. 技能卡片

Skill name:
```
ai-sdlc-branching
```
Primary audience: Dev
Supporting audience: PM, BA
Audience tags: Dev, PM, BA
SDLC stage: Git workflow setup
Purpose: Create or verify the correct Git-flow task branch before repo-tracked file mutation, keep branch names aligned with active specs, and hand completed work to validation and commit prep without mixing unrelated changes.
Output: Branching decision, branch name, base branch, dirty-tree assessment, and next handoff

技能名称：
```
ai-sdlc-branching
```
主要受众：开发人员（Dev）
支持受众：产品经理（PM）、业务分析师（BA）
受众标签：Dev、PM、BA
SDLC阶段：Git工作流设置
目的：在修改仓库跟踪文件前创建或验证正确的Git-flow任务分支，保持分支名称与有效规范一致，并将已完成的工作移交至验证和提交准备阶段，避免混入无关变更。
输出：分支决策、分支名称、基准分支、脏树评估以及后续移交信息

0.1 Required Inputs

0.1 必需输入

User-visible task name and change type.
Current branch and dirty tree state.
Active spec folder for medium or large work.

用户可见的任务名称和变更类型。
当前分支和脏树状态。
中大型工作对应的有效规范文件夹。

0.2 Clarification Rules

0.2 澄清规则

Ask concise questions before finalizing when role, artifact, requirements, scope, audience, or constraints are unclear.
If optional information is missing, mark it as
```
TBD
```
,
```
Not provided
```
, or
```
Assumption
```
instead of inventing it.
Separate confirmed facts from assumptions and open questions.
Do not proceed to downstream synthesis when a required upstream artifact or decision is missing.

当角色、产物、需求、范围、受众或约束条件不明确时，在最终确定前提出简洁的问题。
若可选信息缺失，标记为
```
TBD
```
、
```
Not provided
```
或
```
Assumption
```
，不得编造。
将已确认的事实与假设和未解决问题分开。
当所需的上游产物或决策缺失时，不得进行下游合成工作。

0.2.1 Flow Mode Flags

0.2.1 流程模式标志

Support two explicit execution flags:
```
--quick-flow
```
and
```
--full-flow
```
.
If both flags are supplied,
```
--full-flow
```
takes precedence because it is the stricter mode.
```
--quick-flow
```
: move fast, make high-quality progress with available context, avoid clarification questions unless continuing would create material product, security, compliance, data-loss, or irreversible implementation risk.
In
```
--quick-flow
```
, use documented assumptions, recommended defaults, existing repository patterns, and the nearest available artifact evidence; record important assumptions and decisions in
```
decision-log.md
```
.
In
```
--quick-flow
```
, run only focused checks that are directly relevant, cheap, and likely to catch regressions for the requested work; report any skipped broader checks as residual risk.
```
--full-flow
```
: ask concise clarification questions when inputs, scope, ownership, acceptance criteria, or decisions are unclear; do not silently assume material requirements.
In
```
--full-flow
```
, verify upstream and downstream artifacts, decision-log entries, traceability links, acceptance criteria, and validation evidence before finalizing.
In
```
--full-flow
```
, run or recommend the skill-appropriate gates, reviews, scripts, and validation commands needed for end-to-end confidence; document any blocked verification explicitly.
When neither flag is supplied, follow the skill default rules and choose the least risky behavior for the request size and domain.

支持两种明确的执行标志：
```
--quick-flow
```
和
```
--full-flow
```
。
若同时提供两个标志，
```
--full-flow
```
优先，因为它是更严格的模式。
```
--quick-flow
```
：快速推进，利用现有上下文取得高质量进展，除非继续执行会造成产品、安全、合规、数据丢失或不可逆的实施风险，否则避免提出澄清问题。
在
```
--quick-flow
```
模式下，使用文档化的假设、推荐的默认值、现有仓库模式以及最接近的可用产物证据；将重要的假设和决策记录在
```
decision-log.md
```
中。
在
```
--quick-flow
```
模式下，仅运行与请求工作直接相关、成本低且可能发现回归问题的聚焦检查；将任何跳过的更广泛检查报告为残留风险。
```
--full-flow
```
：当输入、范围、所有权、验收标准或决策不明确时，提出简洁的澄清问题；不得默认重要的需求。
在
```
--full-flow
```
模式下，在最终确定前验证上游和下游产物、决策日志条目、可追溯性链接、验收标准和验证证据。
在
```
--full-flow
```
模式下，运行或推荐适合技能的门控、评审、脚本和验证命令，以确保端到端的可信度；明确记录任何被阻止的验证。
当未提供任何标志时，遵循技能默认规则，并根据请求的规模和领域选择风险最低的行为。

0.3 Output Rules

0.3 输出规则

Keep output structured with headings and bullets.
Make findings, gaps, risks, and blockers explicit.
Tie recommendations to evidence from the provided artifact, repository,
```
specs-refiniment/<feature-name>/<file.md>
```
workspace, or user context.
Include role ownership when the output creates follow-up work for BA, QA, Dev, PM, or Delivery.
Return progress, completion, validation, and handoff summaries directly in the Codex response.

Before the final response, emit the

ai-sdlc-handoff/v1

contract with

result

blockers

next_required

, and

next_optional

; every action includes

reason

command

, and

expected_artifact

Do not create
```
summary.txt
```
,
```
*-summary.txt
```
, or another standalone summary file unless the user explicitly requests one.
Keep durable writes limited to the canonical lifecycle artifacts, decision log, human-readable index, and
```
_ai_sdlc
```
machine files.
Let shared helpers migrate legacy paths on the next write; never overwrite or manually merge divergent legacy and canonical files.

保持输出结构清晰，使用标题和项目符号。
明确指出发现的问题、缺口、风险和阻塞点。
将建议与提供的产物、仓库、
```
specs-refiniment/<feature-name>/<file.md>
```
工作区或用户上下文的证据关联起来。
当输出为BA、QA、Dev、PM或交付团队创建后续工作时，明确角色所有权。
在Codex响应中直接返回进度、完成情况、验证和移交摘要。

在最终响应前，发出包含

result

、

blockers

、

next_required

和

next_optional

的

ai-sdlc-handoff/v1

契约；每个操作都包含

reason

、

command

和

expected_artifact

。

除非用户明确要求，否则不得创建
```
summary.txt
```
、
```
*-summary.txt
```
或其他独立的摘要文件。
仅将持久化写入限制在规范生命周期产物、决策日志、人类可读索引和
```
_ai_sdlc
```
机器文件中。
让共享助手在下次写入时迁移旧路径；不得覆盖或手动合并不一致的旧文件和规范文件。

0.4 Artifact Routing

0.4 产物路由

Maintain a feature decision log whenever this skill records, resolves, changes, or depends on a product, delivery, QA, security, validation, branching, implementation, or rollout decision.
For PM, BA, QA, Delivery, discovery, planning, refinement, and readiness work, write decisions to
```
specs-refiniment/<feature-name>/decision-log.md
```
.
For developer implementation SDD work, write decisions to
```
specs/<feature-name>/decision-log.md
```
.
Each decision-log entry must include date, decision, context or evidence, options considered when relevant, owner, status, and links to affected artifacts, tasks, tests, or validation evidence.

Use this exact decision-log structure:

markdown

# Decision Log

| ID | Date | Status | Owner | Decision | Context/Evidence | Options Considered | Affected Artifacts | Validation/Trace Links |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DEC-001 | YYYY-MM-DD | proposed / accepted / superseded / rejected | role or name | concise decision | source facts, artifact links, or evidence | option A; option B; recommended default | affected docs, tasks, code, tests, or rollout notes | requirement IDs, test IDs, validation commands, PRs, commits, or tickets |

Use
```
specs/
```
only for developer implementation SDD packages and repo-governance artifacts.
Do not place PM, BA, QA, Delivery, discovery, planning, refinement, or readiness outputs in
```
specs/
```
; those belong at
```
specs-refiniment/<feature-name>/<file.md>
```
.
When consuming
```
specs-refiniment/<feature-name>/<file.md>
```
, treat it as upstream refinement context and create or update
```
specs/
```
only when implementation work is explicitly in scope.

每当本技能记录、解决、更改或依赖产品、交付、QA、安全、验证、分支、实施或发布决策时，维护功能决策日志。
对于PM、BA、QA、交付、发现、规划、细化和准备工作，将决策写入
```
specs-refiniment/<feature-name>/decision-log.md
```
。
对于开发人员实施SDD的工作，将决策写入
```
specs/<feature-name>/decision-log.md
```
。
每个决策日志条目必须包含日期、决策、上下文或证据、相关的备选方案（如有）、负责人、状态以及受影响的产物、任务、测试或验证证据的链接。

使用以下精确的决策日志结构：

markdown

# Decision Log

| ID | Date | Status | Owner | Decision | Context/Evidence | Options Considered | Affected Artifacts | Validation/Trace Links |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| DEC-001 | YYYY-MM-DD | proposed / accepted / superseded / rejected | role or name | concise decision | source facts, artifact links, or evidence | option A; option B; recommended default | affected docs, tasks, code, tests, or rollout notes | requirement IDs, test IDs, validation commands, PRs, commits, or tickets |

```
specs/
```
仅用于开发人员实施SDD的包和仓库治理产物。
不得将PM、BA、QA、交付、发现、规划、细化或准备工作的输出放在
```
specs/
```
中；这些内容应放在
```
specs-refiniment/<feature-name>/<file.md>
```
。
当使用
```
specs-refiniment/<feature-name>/<file.md>
```
时，将其视为上游细化上下文，仅当实施工作明确在范围内时才创建或更新
```
specs/
```
中的内容。

0.5 Feature State Machine

0.5 功能状态机

Maintain feature lifecycle state in TOON at

specs-refiniment/<feature-name>/_ai_sdlc/state.toon

for refinement work and

specs/<feature-name>/_ai_sdlc/state.toon

for implementation work.

Before executing this skill for a feature, check the state machine with

python3 skills/_shared/state_machine.py check --feature <feature-name> --skill <this-skill-name> --workspace <refinement|implementation> --quick-flow|--full-flow

When this skill starts durable work, mark it in progress with
```
begin
```
; when the skill's required artifact or review is complete, mark it done with
```
complete
```
and include
```
--artifacts <path>
```
plus
```
--decision-ref DEC-###
```
when a decision was involved.
In
```
--full-flow
```
, do not proceed when predecessor stages are incomplete, another lifecycle skill is active, or the state file reports a blocker.
In
```
--quick-flow
```
, a predecessor skip is allowed only when continuing is low risk and the command includes
```
--assumption "..."
```
or
```
--decision-ref DEC-###
```
; record the same assumption or decision in
```
decision-log.md
```
.

Use

python3 skills/_shared/state_machine.py status --feature <feature-name> --workspace <refinement|implementation> --format toon

to emit compact LLM-readable state before choosing the next skill.

The state machine is feature-scoped: do not reuse a
```
state.toon
```
across unrelated feature folders.

在TOON中维护功能生命周期状态：细化工作对应

specs-refiniment/<feature-name>/_ai_sdlc/state.toon

，实施工作对应

specs/<feature-name>/_ai_sdlc/state.toon

。

在为某个功能执行本技能前，使用以下命令检查状态机：

python3 skills/_shared/state_machine.py check --feature <feature-name> --skill <this-skill-name> --workspace <refinement|implementation> --quick-flow|--full-flow

。

当本技能开始持久化工作时，用
```
begin
```
标记为进行中；当技能所需的产物或评审完成时，用
```
complete
```
标记为完成，若涉及决策则添加
```
--artifacts <path>
```
和
```
--decision-ref DEC-###
```
。
在
```
--full-flow
```
模式下，当前驱阶段未完成、另一个生命周期技能处于活动状态或状态文件报告阻塞时，不得继续执行。
在
```
--quick-flow
```
模式下，仅当继续执行风险低且命令包含
```
--assumption "..."
```
或
```
--decision-ref DEC-###
```
时，才允许跳过前驱阶段；同时在
```
decision-log.md
```
中记录相同的假设或决策。

使用以下命令生成紧凑的LLM可读状态，再选择下一个技能：

python3 skills/_shared/state_machine.py status --feature <feature-name> --workspace <refinement|implementation> --format toon

。

状态机按功能划分范围：不得在无关的功能文件夹间复用
```
state.toon
```
。

0.6 Artifact Metadata And Metatags

0.6 产物元数据和元标签

Every Markdown artifact generated or updated by this skill must start with an
```
artifact_metadata
```
YAML frontmatter block before the first visible heading.

Use schema

ai-sdlc-artifact-metadata/v1

and keep these fields current:

feature

artifact

path

workspace

skill

flow_mode

state_file

decision_log

status

owner

created_at

updated_at

trace_ids

related_artifacts

validation

, and

metatags

```
metatags
```
must include at minimum
```
ai-sdlc
```
, the workspace (
```
refinement
```
or
```
implementation
```
), this skill name, the artifact type or filename stem, and a lifecycle/status tag such as
```
draft
```
,
```
review
```
,
```
approved
```
, or
```
validated
```
.
When
```
--quick-flow
```
is active, set
```
flow_mode: quick
```
, keep assumptions visible in the body, and add tags for major defaults or unresolved risk only when they help retrieval.
When
```
--full-flow
```
is active, set
```
flow_mode: full
```
, keep blockers and validation evidence reflected in
```
status
```
,
```
validation
```
,
```
trace_ids
```
, and
```
related_artifacts
```
.
Update metadata whenever the artifact path, status, owner, trace links, validation evidence, related artifacts, or decision references change.
Metadata is an index for routing, retrieval, and traceability; it does not replace the artifact body,
```
decision-log.md
```
, or
```
state.toon
```
.

本技能生成或更新的每个Markdown产物，在第一个可见标题前必须包含
```
artifact_metadata
```
YAML前置块。

使用

ai-sdlc-artifact-metadata/v1

schema，并保持以下字段最新：

feature

、

artifact

、

path

、

workspace

、

skill

、

flow_mode

、

state_file

、

decision_log

、

status

、

owner

、

created_at

、

updated_at

、

trace_ids

、

related_artifacts

、

validation

和

metatags

。

```
metatags
```
至少必须包含
```
ai-sdlc
```
、工作区（
```
refinement
```
或
```
implementation
```
）、本技能名称、产物类型或文件名主干，以及生命周期/状态标签（如
```
draft
```
、
```
review
```
、
```
approved
```
或
```
validated
```
）。
当
```
--quick-flow
```
激活时，设置
```
flow_mode: quick
```
，在正文中显示假设，仅当有助于检索时才添加主要默认值或未解决风险的标签。
当
```
--full-flow
```
激活时，设置
```
flow_mode: full
```
，在
```
status
```
、
```
validation
```
、
```
trace_ids
```
和
```
related_artifacts
```
中反映阻塞点和验证证据。
当产物路径、状态、负责人、跟踪链接、验证证据、相关产物或决策引用发生变化时，更新元数据。
元数据是用于路由、检索和可追溯性的索引；它不能替代产物正文、
```
decision-log.md
```
或
```
state.toon
```
。

0.7 Specs Index

0.7 规范索引

Before searching across feature folders, inspect the compact LLM index first:
```
specs-refiniment/_ai_sdlc/specs-index.toon
```
for refinement work or
```
specs/_ai_sdlc/specs-index.toon
```
for implementation work.
Use the human-readable index at
```
specs-refiniment/specs-index.md
```
or
```
specs/specs-index.md
```
when reporting feature coverage, artifact inventory, or handoff status to people.

After this skill creates or materially updates an artifact, refresh the matching workspace index with

python3 skills/_shared/ai_sdlc_specs_index.py --workspace <refinement|implementation> --quick-flow|--full-flow

In
```
--quick-flow
```
, rely on
```
specs-index.toon
```
to choose the smallest relevant artifact set before opening files.
In
```
--full-flow
```
, verify the updated artifact appears in both
```
specs-index.toon
```
and
```
specs-index.md
```
before final handoff.
The specs index summarizes artifact metadata and state; it does not replace reading the selected source artifacts when details, approvals, or validation evidence matter.

在跨功能文件夹搜索前，先查看紧凑的LLM索引：细化工作对应
```
specs-refiniment/_ai_sdlc/specs-index.toon
```
，实施工作对应
```
specs/_ai_sdlc/specs-index.toon
```
。
当向人员报告功能覆盖范围、产物清单或移交状态时，使用人类可读的索引：
```
specs-refiniment/specs-index.md
```
或
```
specs/specs-index.md
```
。

本技能创建或实质性更新产物后，使用以下命令刷新匹配的工作区索引：

python3 skills/_shared/ai_sdlc_specs_index.py --workspace <refinement|implementation> --quick-flow|--full-flow

。

在
```
--quick-flow
```
模式下，依靠
```
specs-index.toon
```
选择最小的相关产物集，再打开文件。
在
```
--full-flow
```
模式下，在最终移交前验证更新后的产物是否同时出现在
```
specs-index.toon
```
和
```
specs-index.md
```
中。
规范索引总结了产物元数据和状态；当细节、审批或验证证据很重要时，它不能替代阅读选定的源产物。

References

参考资料

Use
```
scripts/branch_plan.py
```
when deterministic scaffolding, planning, or formatting is useful for this workflow; pass the same
```
--quick-flow
```
or
```
--full-flow
```
flag that was supplied to the skill.
No external reference files are required for this skill.

当确定性脚手架、规划或格式化对本工作流有用时，使用
```
scripts/branch_plan.py
```
；传递与技能相同的
```
--quick-flow
```
或
```
--full-flow
```
标志。
本技能不需要外部参考文件。

Script Usage

脚本使用

Run
```
scripts/branch_plan.py
```
before drafting or updating this skill's artifact when inputs are longer than a few bullets, when traceability matters, or when a flow flag is supplied. For agent analysis, pass
```
--format toon
```
, read
```
anchors
```
first, and open only
```
next_reads
```
; without that flag the script keeps its human-readable Markdown output.

Quick flow analysis:

python3 skills/ai-sdlc-branching/scripts/branch_plan.py --feature <feature-name> --quick-flow <input.md>...

Full flow analysis:

python3 skills/ai-sdlc-branching/scripts/branch_plan.py --feature <feature-name> --full-flow <input.md>...

To write content, pass one canonical heading with
```
--section "<section>"
```
; provide only that section body on stdin, without H1, H2, frontmatter, or a temporary content file.
Repeat
```
--section
```
for each required section, then run the same script with
```
--finalize
```
to validate the artifact and refresh metadata and specs indexes.
The AI must not write or directly edit the routed Markdown artifact; the script owns scaffold creation, section placement, and durable file writes.
Use
```
--decision-row
```
with one nine-cell Markdown table row on stdin when a decision-log entry is required.

Legacy

--emit-template

--emit-decision-log-entry

, and

--write

remain available for compatibility.

Use
```
--quick-flow
```
for first-pass synthesis with assumptions; use
```
--full-flow
```
before readiness, handoff, signoff, or any decision-sensitive output.

当输入超过几个项目符号、可追溯性很重要或提供了流程标志时，在起草或更新本技能的产物前运行
```
scripts/branch_plan.py
```
。对于代理分析，传递
```
--format toon
```
，先读取
```
anchors
```
，再打开仅有的
```
next_reads
```
；不使用该标志时，脚本保持人类可读的Markdown输出。

快速流程分析：

python3 skills/ai-sdlc-branching/scripts/branch_plan.py --feature <feature-name> --quick-flow <input.md>...

完整流程分析：

python3 skills/ai-sdlc-branching/scripts/branch_plan.py --feature <feature-name> --full-flow <input.md>...

要写入内容，传递一个规范标题，格式为
```
--section "<section>"
```
；仅在标准输入中提供该部分的正文，不要包含H1、H2、前置内容或临时内容文件。
对每个所需部分重复使用
```
--section
```
，然后使用
```
--finalize
```
运行相同的脚本，以验证产物并刷新元数据和规范索引。
AI不得直接写入或编辑路由的Markdown产物；脚本负责脚手架创建、部分放置和持久化文件写入。
当需要决策日志条目时，使用
```
--decision-row
```
，并在标准输入中提供一行九列的Markdown表格行。

旧版的

--emit-template

、

--emit-decision-log-entry

和

--write

仍可用于兼容。

使用
```
--quick-flow
```
进行基于假设的首次合成；在准备、移交、签署或任何决策敏感的输出前，使用
```
--full-flow
```
。

Purpose

目的

Create or verify the correct Git-flow task branch before repo-tracked file mutation, keep branch names aligned with active specs, and hand completed work to validation and commit prep without mixing unrelated changes.

在修改仓库跟踪文件前创建或验证正确的Git-flow任务分支，保持分支名称与有效规范一致，并将已完成的工作移交至验证和提交准备阶段，避免混入无关变更。

Inputs

输入

Collect the user-visible task name and change classification.
Collect the active spec folder for medium or large work.
Collect the current branch and dirty tree from:
bash
```
git status --short --branch
```
Collect the repository's declared base branch before creating any new task branch.
Collect whether the intended change is feature, fix, docs-only, or repo-local maintenance/governance.
Collect sandbox or approval constraints from
```
$ai-sdlc-approvals-sandbox
```
if Git branch commands fail because Git refs cannot be written.

收集用户可见的任务名称和变更分类。
收集中大型工作对应的有效规范文件夹。
通过以下命令收集当前分支和脏树：
bash
```
git status --short --branch
```
在创建任何新任务分支前，收集仓库声明的基准分支。
收集预期变更是功能、修复、仅文档或仓库本地维护/治理类型。
如果Git分支命令因无法写入Git引用而失败，从
```
$ai-sdlc-approvals-sandbox
```
收集沙箱或审批约束。

Steps

步骤

Run
```
git status --short --branch
```
before mutating repo-tracked files.
Allow read-only planning, repository inspection, and SDD drafting before a task branch exists when those actions do not mutate repo-tracked files.
Classify dirty files as related, unrelated, or unclear.
Stop before branch creation or branch switching when unrelated or unclear dirty files would be carried into the task without explicit user approval.
Choose the branch name:
- Medium or large SDD work:
```
feature/NNN-short-feature-name
```
  .
- Small bug fix:
```
fix/<short-name>
```
  .
- Docs-only work:
```
docs/<short-name>
```
  .
- Repo-local governance or maintenance:
```
chore/<short-name>
```
  .
For medium or large work, preserve the full active spec slug after the prefix, for example
```
feature/191-branching-workflow
```
.
Resolve the base branch in this order: explicit repository policy (
```
ai-sdlc.baseBranch
```
),
```
origin/HEAD
```
, then an existing local
```
dev
```
,
```
main
```
, or
```
master
```
. Use
```
dev
```
only when it is declared or actually present.
If already on a correctly named task branch for the current task, continue and report
```
already correct
```
; do not recreate the branch.
Before creating a new task branch, switch to the resolved base and pull the latest remote state with fast-forward-only semantics:
bash
```
git checkout <base-branch>
git pull --ff-only origin <base-branch>
```
If the resolved base cannot be checked out or pulled cleanly, stop and report the blocker instead of branching from stale or divergent local state.
Create the new branch from the refreshed resolved base with a non-interactive command, for example:

bash

git checkout -b feature/191-branching-workflow

If checkout, pull, or branch creation fails because sandboxing blocks Git refs or network access, use
```
$ai-sdlc-approvals-sandbox
```
and request narrow approval for the specific Git command.
Perform implementation only after the branch is verified or created from refreshed
```
dev
```
.
When the user-visible task is complete, run
```
$ai-sdlc-validation
```
, then
```
$ai-sdlc-commit-prep
```
.
Use one branch and one commit per user-visible task by default. Do not treat individual
```
tasks.md
```
checkboxes as automatic branch or commit boundaries.

在修改仓库跟踪文件前运行
```
git status --short --branch
```
。
当任务分支不存在时，允许进行只读规划、仓库检查和SDD起草，前提是这些操作不会修改仓库跟踪文件。
将脏文件分类为相关、无关或不明确。
当无关或不明确的脏文件会被带入任务且未获得用户明确批准时，在分支创建或切换前停止。
选择分支名称：
- 中大型SDD工作：
```
feature/NNN-short-feature-name
```
  。
- 小型bug修复：
```
fix/<short-name>
```
  。
- 仅文档工作：
```
docs/<short-name>
```
  。
- 仓库本地治理或维护：
```
chore/<short-name>
```
  。
对于中大型工作，保留前缀后的完整有效规范slug，例如
```
feature/191-branching-workflow
```
。
按以下顺序确定基准分支：明确的仓库策略（
```
ai-sdlc.baseBranch
```
）、
```
origin/HEAD
```
，然后是现有的本地
```
dev
```
、
```
main
```
或
```
master
```
。仅当
```
dev
```
被声明或实际存在时才使用它。
如果已处于与当前任务匹配的正确命名的任务分支上，继续执行并报告
```
already correct
```
；不要重新创建分支。
在创建新任务分支前，切换到确定的基准分支，并使用仅快进语义拉取最新的远程状态：
bash
```
git checkout <base-branch>
git pull --ff-only origin <base-branch>
```
如果无法干净地检出或拉取确定的基准分支，停止并报告阻塞点，不要从陈旧或不一致的本地状态创建分支。
从刷新后的确定基准分支创建新分支，使用非交互式命令，例如：

bash

git checkout -b feature/191-branching-workflow

如果检出、拉取或分支创建因沙箱阻止Git引用或网络访问而失败，使用
```
$ai-sdlc-approvals-sandbox
```
并请求对特定Git命令的窄范围审批。
仅在从刷新后的
```
dev
```
分支验证或创建分支后，再进行实施工作。
当用户可见的任务完成时，运行
```
$ai-sdlc-validation
```
，然后运行
```
$ai-sdlc-commit-prep
```
。
默认情况下，每个用户可见任务使用一个分支和一个提交。不要将单个
```
tasks.md
```
复选框视为自动的分支或提交边界。

Output Spec

输出规范

Use this branch handoff report when branch state matters:

text

Branching:
- Task: user-visible task name
- Change size: small | medium | large
- Spec: specs/NNN-short-feature-name | none
- Base branch: resolved branch | blocked with reason
- Base refresh: pulled latest resolved base | reused existing task branch | blocked
- Current branch: branch-name
- Expected branch: branch-name
- Action: already correct | created | reused with reason | blocked
- Dirty tree: clean | related files listed | unrelated/unclear blocker
- Next phase: implementation | validation | commit-prep

Quality gate:

Pass when implementation starts on a branch that matches the task type and, for medium or large work, includes the active spec slug.
Fail when repo-tracked files are mutated on a shared/default branch, unrelated dirty files are carried silently, branch/spec mismatch is hidden, or Git command failures are ignored.

当分支状态很重要时，使用以下分支移交报告：

text

Branching:
- Task: user-visible task name
- Change size: small | medium | large
- Spec: specs/NNN-short-feature-name | none
- Base branch: resolved branch | blocked with reason
- Base refresh: pulled latest resolved base | reused existing task branch | blocked
- Current branch: branch-name
- Expected branch: branch-name
- Action: already correct | created | reused with reason | blocked
- Dirty tree: clean | related files listed | unrelated/unclear blocker
- Next phase: implementation | validation | commit-prep

质量门控：

当实施工作在与任务类型匹配的分支上启动，且对于中大型工作包含有效规范slug时，通过。
当在共享/默认分支上修改仓库跟踪文件、静默带入无关脏文件、隐藏分支/规范不匹配或忽略Git命令失败时，不通过。

Examples

示例

Valid medium-work start:

text

Branching:
- Task: AI SDLC Git-flow branching skill and workflow update
- Change size: medium
- Spec: specs/191-branching-workflow
- Base branch: main (origin/HEAD)
- Base refresh: pulled latest resolved base
- Current branch: main
- Expected branch: feature/191-branching-workflow
- Action: created
- Dirty tree: clean
- Next phase: implementation

Valid small fix:

text

Branching:
- Task: fix typo in validation warning
- Change size: small
- Spec: none
- Base branch: main (repository default)
- Base refresh: pulled latest resolved base
- Current branch: main
- Expected branch: fix/validation-warning-typo
- Action: created
- Dirty tree: clean
- Next phase: implementation

Invalid counter-example:

text

Edited files directly on the shared base and will make a branch later.

Reject this because branch verification must happen before repo-tracked file mutation for implementation work.

有效的中型工作启动：

text

Branching:
- Task: AI SDLC Git-flow branching skill and workflow update
- Change size: medium
- Spec: specs/191-branching-workflow
- Base branch: main (origin/HEAD)
- Base refresh: pulled latest resolved base
- Current branch: main
- Expected branch: feature/191-branching-workflow
- Action: created
- Dirty tree: clean
- Next phase: implementation

有效的小型修复：

text

Branching:
- Task: fix typo in validation warning
- Change size: small
- Spec: none
- Base branch: main (repository default)
- Base refresh: pulled latest resolved base
- Current branch: main
- Expected branch: fix/validation-warning-typo
- Action: created
- Dirty tree: clean
- Next phase: implementation

无效反例：

text

Edited files directly on the shared base and will make a branch later.

拒绝此操作，因为对于实施工作，必须在修改仓库跟踪文件前验证分支。

Edge Cases

边缘情况

If the repository has no declared/present base branch, stop and ask the owner to declare one; do not invent
```
dev
```
.
If already on a correctly named task branch, continue and report
```
already correct
```
.
If already on a non-default branch that clearly belongs to the same task, report
```
reused with reason
```
; do not create a second branch.
For new task branches, do not skip checkout/pull of the resolved base merely because it looks recent.
If
```
git pull --ff-only
```
reports divergence, stop and ask for repository maintenance instead of merge-committing during task setup.
If the branch name matches multiple specs or no spec for medium or large work, resolve the active spec with
```
$ai-sdlc-sdd
```
before implementation.
If unrelated dirty files exist, do not run destructive cleanup. Ask the user whether to keep, commit, stash, or otherwise handle them.
If branch creation fails from sandboxing, request escalation rather than inventing an alternate branch state.
Do not push branches unless the user explicitly asks or the commit workflow requires it.

如果仓库没有声明/存在的基准分支，停止并要求所有者声明一个；不得编造
```
dev
```
分支。
如果已处于正确命名的任务分支上，继续执行并报告
```
already correct
```
。
如果已处于非默认分支且明显属于同一任务，报告
```
reused with reason
```
；不要创建第二个分支。
对于新任务分支，不要仅仅因为基准分支看起来是最新的就跳过检出/拉取操作。
如果
```
git pull --ff-only
```
报告分歧，停止并要求进行仓库维护，不要在任务设置期间进行合并提交。
对于中大型工作，如果分支名称匹配多个规范或不匹配任何规范，在实施前使用
```
$ai-sdlc-sdd
```
确定有效规范。
如果存在无关脏文件，不要进行破坏性清理。询问用户是保留、提交、暂存还是以其他方式处理它们。
如果分支创建因沙箱而失败，请求升级，不要编造替代分支状态。
除非用户明确要求或提交工作流需要，否则不要推送分支。

Scope Boundary

范围边界

Do not create or update SDD artifacts; use
```
$ai-sdlc-sdd
```
.
Do not decide validation commands; use
```
$ai-sdlc-validation
```
.
Do not stage files or create commits; use
```
$ai-sdlc-commit-prep
```
.
Do not draft commit messages; use
```
$ai-sdlc-conventional-commit
```
.

不要创建或更新SDD产物；使用
```
$ai-sdlc-sdd
```
。
不要决定验证命令；使用
```
$ai-sdlc-validation
```
。
不要暂存文件或创建提交；使用
```
$ai-sdlc-commit-prep
```
。
不要起草提交消息；使用
```
$ai-sdlc-conventional-commit
```
。