mainline

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Mainline

This skill is the agent-facing Mainline integration. It should be sufficient even when the repository does not yet have Mainline text in AGENTS.md and when Mainline hooks are not installed.

Mainline records why AI-driven changes happen, connects those intents to code commits, and surfaces semantic conflicts before PR review. Treat it as part of the coding workflow, not as optional documentation.

If the current session already contains a

mainline:context

block injected by Mainline hooks, treat that hook context as already loaded. Do not re-run generic bootstrap context commands just to duplicate it. Run task-specific context commands only when needed.

本技能是面向agent的Mainline集成方案。即使仓库的AGENTS.md中尚未包含Mainline相关文本，且未安装Mainline钩子，本技能也能正常生效。

Mainline会记录AI驱动变更的原因，将这些意图与代码提交关联，并在PR评审前识别语义冲突。请将其视为编码工作流的一部分，而非可选文档。

若当前会话已包含由Mainline钩子注入的

mainline:context

块，则视为该钩子上下文已加载。无需重新运行通用引导上下文命令来重复获取信息，仅在需要时运行特定任务的上下文命令。

Stop-Line Quick Matrix

停止速查矩阵

Use this as the first-pass boundary decision; detailed workflows below explain how to execute each boundary.

Interpret the latest user instruction semantically, not by keyword matching.

Instruction class	Effective boundary	Do not cross without a new explicit request
Advice-only / read-only	`assist`	edits, commits, seals, metadata publish, push, or PR
Finish local work / commit / seal / handoff	`handoff`	code branch push or PR
Push branch / open or update PR	`review` , capped by team `max_autonomy`	push to `main` , merge, release, deploy, or post-merge cleanup
Continue next task	keep the current effective boundary	lifecycle advancement unless it is naturally next and permitted
Merge / release / deploy / package publish / post-merge cleanup	explicit delivery task, not autonomy	ambiguous target or missing repository workflow checks

Vocabulary guardrails:

```
mainline publish
```
publishes Mainline intent metadata / actor-log state. It is distinct from pushing a Git branch, opening a PR, merging, package publishing, deployment, or product release. If the user says "publish" without a clear object, identify the target before acting.
Git branch push, PR creation, PR merge, and product release/deploy are separate delivery steps. Do not collapse them into one "publish" action.
A file overlap is only a signal. It becomes a conflict workflow only after inspection shows it is real and potentially contradictory.

将此作为边界决策的第一参考；下方详细工作流将解释如何执行每个边界操作。

请从语义层面解读最新用户指令，而非仅通过关键词匹配。

指令类别	有效边界	无新明确请求不得跨越
仅建议/只读	`assist`	编辑、提交、封存、元数据发布、推送或PR操作
完成本地工作/提交/封存/交接	`handoff`	代码分支推送或PR操作
推送分支/开启或更新PR	`review` ，受团队 `max_autonomy` 限制	推送到 `main` 分支、合并、发布、部署或合并后清理
继续下一项任务	保持当前有效边界	除非是自然且被允许的后续步骤，否则不得推进生命周期
合并/发布/部署/包发布/合并后清理	明确交付任务，非自主操作	目标模糊或缺少仓库工作流检查

词汇规范：

```
mainline publish
```
用于发布Mainline意图元数据/参与者日志状态，与推送Git分支、开启PR、合并、包发布、部署或产品发布是不同操作。若用户未明确说明发布对象，需先确认目标再执行。
Git分支推送、PR创建、PR合并和产品发布/部署是独立的交付步骤，不得将它们合并为单一的"publish"操作。
文件重叠仅为信号，只有经检查确认真实且可能存在矛盾时，才进入冲突工作流。

Language Rule (load-bearing)

语言规则（核心要求）

Match the user's language in everything you write into Mainline: the goal text on

mainline start

, every

mainline append

turn, the seal

summary.title

what

why

user_goal

/ decisions / review_notes, explicit signal command text, and PR description prose. If the user wrote in Chinese, seal in Chinese. English in, English out. Mixed inputs → match the dominant language.

Why this matters: the seal record is the team's long-term memory. A teammate reading

mainline show <id>

later must recognise the work as theirs. Translating a Chinese task into an English seal makes the corpus harder to read for the people whose memory it is.

Pass the user's substantive goal text through verbatim —

mainline start "<goal>"

becomes the headline in

mainline log

. If the latest instruction is only a context-dependent reference rather than a durable description of the work, expand it into a short, human-readable goal in the user's language. Preserve the reference in a turn or seal reference instead of making it the headline. Code identifiers, command names, file paths, and CLI snippets stay in their original form regardless of conversation language.

在写入Mainline的所有内容中匹配用户使用的语言：包括

mainline start

的目标文本、每次

mainline append

的内容、封存时的

summary.title

what

why

user_goal

/决策/评审说明、明确的信号命令文本以及PR描述文案。若用户使用中文，封存内容也用中文；英文输入则英文输出；混合输入时匹配主导语言。

此规则的重要性：封存记录是团队的长期记忆。后续队友查看

mainline show <id>

时，必须能识别这是团队的工作成果。将中文任务翻译成英文封存会让目标用户难以阅读这份记忆库。

直接保留用户的实质性目标文本——

mainline start "<goal>"

将成为

mainline log

中的标题。若最新指令仅为依赖上下文的引用，而非对工作的持久描述，则需将其扩展为用户语言的简短、易读目标，并将引用保留在回合或封存引用中，而非作为标题。代码标识符、命令名称、文件路径和CLI代码片段无论对话语言如何，均保持原始形式。

Trigger Policy

触发策略

Use this skill for any task in a Git repository when one of these is true:

The repository has
```
.mainline/config.toml
```
,
```
.ml-cache/
```
, a Mainline block in AGENTS.md, Mainline refs, or existing Mainline commands in project docs.
The user mentions Mainline, intents, conflict checks, agent guidance, hooks, sealing, proposals, coverage, gaps, uncovered commits, agent autonomy,
```
agent_authority
```
,
```
max_autonomy
```
, stop lines,
```
allowed_boundary
```
,
```
inspect_or_stop
```
, current-instruction overrides, handoff / review / delivery boundaries, or auto-submit / auto-commit / auto-seal behavior.
You are about to edit code, refactor, delete code, change tests or CI, commit, push, create a PR, review a PR, or investigate whether prior work already made a decision in a repository known to use Mainline.

If the skill triggers because the repository appears to use Mainline, run the Mainline checks before broad code search or edits. If the repository does not appear to use Mainline and the user did not ask to set it up, do not initialize Mainline without user confirmation.

当Git仓库中出现以下任一情况时，使用本技能：

仓库存在
```
.mainline/config.toml
```
、
```
.ml-cache/
```
、AGENTS.md中的Mainline块、Mainline引用或项目文档中的现有Mainline命令。
用户提及Mainline、意图、冲突检查、agent指引、钩子、封存、提案、覆盖范围、缺口、未覆盖提交、agent自主性、
```
agent_authority
```
、
```
max_autonomy
```
、停止线、
```
allowed_boundary
```
、
```
inspect_or_stop
```
、当前指令覆盖、交接/评审/交付边界或自动提交/自动封存行为。
即将执行代码编辑、重构、删除、测试或CI变更、提交、推送、创建PR、评审PR，或调查已知使用Mainline的仓库中是否已有相关决策。

若因仓库似乎使用Mainline而触发技能，需先运行Mainline检查，再进行广泛代码搜索或编辑。若仓库未显示使用Mainline且用户未要求配置，不得在未获用户确认的情况下初始化Mainline。

Setup Responsibility

配置职责

Do not assume the human has already installed or initialized Mainline. If the task needs Mainline and

mainline

is missing, install or help install it before continuing.

First check:

bash

command -v mainline
mainline status --json

If the CLI is missing, prefer the public install script on macOS/Linux:

bash

curl -fsSL https://raw.githubusercontent.com/mainline-org/mainline/main/install.sh | bash

If the user prefers Go's native installer or the install script is unavailable, use Go 1.22+:

bash

go install github.com/mainline-org/mainline@latest

Use

@main

only when the user explicitly wants the current unreleased development version:

bash

go install github.com/mainline-org/mainline@main

After install, ensure the install directory (commonly

~/.local/bin

for the script or

~/go/bin

for

go install

) is on PATH. Re-run

mainline status --json

If the CLI exists but the repository is not initialized and the user asked to set up Mainline, initialize it.

mainline init

installs the default Mainline skill and repo-local hook integrations. Fresh hook config files are kept clone-local via

.git/info/exclude

unless the repo already tracks them; it does not write AGENTS.md unless the user explicitly asks for repo-level policy:

bash

mainline init --actor-name "<name>"

Choose

<name>

from explicit user input, existing git identity, or a stable local actor name. If initialization would modify shared repository guidance or Git refspecs and the user only asked for a narrow code change, ask before initializing.

不要假设用户已安装或初始化Mainline。若任务需要Mainline但

mainline

命令缺失，需先安装或协助安装后再继续。

首次检查：

bash

command -v mainline
mainline status --json

若CLI缺失，优先使用macOS/Linux的公开安装脚本：

bash

curl -fsSL https://raw.githubusercontent.com/mainline-org/mainline/main/install.sh | bash

若用户偏好Go原生安装程序或安装脚本不可用，使用Go 1.22+版本：

bash

go install github.com/mainline-org/mainline@latest

仅当用户明确需要当前未发布的开发版本时，才使用

@main

：

bash

go install github.com/mainline-org/mainline@main

安装完成后，确保安装目录（脚本安装通常为

~/.local/bin

，

go install

通常为

~/go/bin

）已加入PATH。重新运行

mainline status --json

。

若CLI已存在但仓库未初始化，且用户要求配置Mainline，则进行初始化。

mainline init

会安装默认Mainline技能和仓库本地钩子集成。新的钩子配置文件通过

.git/info/exclude

保持克隆本地可见，除非仓库已跟踪这些文件；除非用户明确要求仓库级策略，否则不会写入AGENTS.md：

bash

mainline init --actor-name "<name>"

<name>

可从用户明确输入、现有Git身份或稳定的本地参与者名称中选择。若初始化会修改共享仓库指引或Git引用规范，而用户仅要求进行窄范围代码变更，需先询问用户再执行初始化。

Hooks

钩子

Hooks provide dynamic context and improve trigger rate, but they are not the source of truth. The skill remains the full workflow authority, and the agent must still make the semantic decisions itself.

mainline init

installs hooks by default. Use these commands when the user asks to inspect, repair, or manually install hook integrations:

bash

mainline hooks status
mainline hooks install

If hooks are not installed, continue with the command workflow below. Do not block code work solely because hooks are absent.

钩子提供动态上下文并提高触发率，但并非事实来源。技能仍是完整工作流的权威，agent仍需自行做出语义决策。

mainline init

默认安装钩子。当用户要求检查、修复或手动安装钩子集成时，使用以下命令：

bash

mainline hooks status
mainline hooks install

若未安装钩子，继续执行下方命令工作流。不得仅因钩子缺失而阻止代码工作。

Start Of Task

任务开始

If the goal is too vague to make a useful intent, prefer one quick clarifying question before

mainline start

; do not turn this into PRD/task planning. If you proceed anyway, use the safest narrow interpretation and record the assumption in the first

mainline append

Read-only diagnosis, history archaeology, plan review, and "look first / don't change yet" requests are Mainline-aware work, but they are not intent claims. Use read-only commands such as

preflight

status

context

show

, and

trace

as needed. Do not run

mainline start

until the current instruction authorizes non-trivial edits, commits/seal/handoff, or another durable engineering record. If investigation later turns into a change, start the intent at that transition and capture the useful diagnostic finding in the first append.

At the start of a Mainline-aware task, begin with the read-only gate:

bash

mainline preflight --json

preflight

is the low-noise readiness gate. If it returns

"level": "ok"

and

"ok_to_continue": true

, continue without expanding the context surface just to be safe. If it returns

warn

block

, read the

findings

overlaps

, and

recommended_next

fields and only then run the targeted follow-up commands it points to (

show

trace

context --files/--query

, or

check

History Rewrite And Notes Recovery

历史重写与Notes恢复

mainline preflight --json

reports a

notes_rewrite_drift

finding, or

mainline status --json

includes

notes_health.likely_history_rewrite: true

, run the read-only diagnosis first:

bash

mainline doctor --notes --json

Also run

mainline doctor --notes --json

when the user mentions a recent force-push, rebase, filter-repo rewrite, author rewrite, contributors cleanup, remote rollback, or a sudden spike in proposed intents / uncovered commits after history changed.

If doctor recommends a migration, preview only:

bash

mainline migrate notes --infer --dry-run --json

Show the safe / review-required / unresolved counts to the user before any write. Do not run

mainline migrate notes --write

--push

unless the user explicitly confirms the plan.

--push

changes the shared notes ref and must be treated like a high-impact Git operation.

If there is no active intent and the task has crossed into non-trivial changes or durable engineering record-keeping, start one using the user's actual goal:

bash

mainline start "<user goal>" --json

mainline start

returns an existing draft for the branch, verify it matches the user's task before appending. If it does not, stop and isolate the work.

If a sealed or proposed intent already exists for the same branch and the user is asking for follow-up changes, start a new intent for the follow-up rather than trying to mutate the sealed one.

Before designing the change, inspect in-flight work:

bash

mainline list-proposals --json

You do not need this separate

list-proposals

call when

preflight

is available and green;

preflight

already reads the proposed index and reports file overlap. Use

list-proposals

as the old-binary fallback or when

preflight

says an overlap needs investigation.

若

mainline preflight --json

报告

notes_rewrite_drift

发现，或

mainline status --json

包含

notes_health.likely_history_rewrite: true

，先运行只读诊断：

bash

mainline doctor --notes --json

当用户提及最近的强制推送、变基、filter-repo重写、作者重写、贡献者清理、远程回滚，或历史变更后拟议意图/未覆盖提交突然激增时，也需运行

mainline doctor --notes --json

。

若doctor建议迁移，仅进行预览：

bash

mainline migrate notes --infer --dry-run --json

在执行任何写入操作前，向用户展示安全/需评审/未解决的数量。除非用户明确确认计划，否则不得运行

mainline migrate notes --write

或

--push

。

--push

会修改共享notes引用，需视为高影响Git操作。

若当前无活跃意图，且任务已涉及非 trivial 变更或持久工程记录，使用用户实际目标启动一个新意图：

bash

mainline start "<user goal>" --json

若

mainline start

返回该分支的现有草稿，需先验证其是否匹配用户任务，再进行append。若不匹配，停止并隔离工作。

若同一分支已存在封存或拟议意图，且用户要求进行后续变更，为后续变更启动新意图，而非尝试修改已封存的意图。

在设计变更前，检查进行中的工作：

bash

mainline list-proposals --json

当

preflight

可用且返回正常时，无需单独调用

list-proposals

；

preflight

已读取拟议索引并报告文件重叠。

list-proposals

仅作为旧版本二进制的回退方案，或在

preflight

提示需要调查重叠时使用。

Intent-First Code Reading

意图优先的代码阅读

Before broad grep, file reads, or implementation on non-trivial work, prefer the compact preflight gate first:

bash

mainline preflight --json

If it reports an overlap, stale view, or branch drift, expand narrowly:

bash

mainline context --files <path>... --json

If the task is semantic:

bash

mainline context --query "<task summary>" --json

Read returned summaries, decisions, risks, and fingerprints. Use them as historical context, then verify against current code. Do not repeat abandoned or superseded approaches unless the user explicitly asks to revisit them.

For relevant intents:

bash

mainline show <intent_id> --json
mainline trace <intent_id> --json

Do not run broad

context --current

list-proposals

show

, and

trace

as a ritual on every task. The intended flow is: preflight first; green means continue; yellow/red means inspect the named intents/files and resolve the specific risk.

Overlap convergence tree:

Upstream already solved the user's goal → abandon the local draft or stop before duplicating it.
Local work still has incremental value → narrow it into a follow-up intent.
The two intents are semantically mutually exclusive → run
```
mainline check
```
or ask for human judgment before continuing.

在进行广泛grep、文件读取或非 trivial 工作的实现前，优先执行紧凑的preflight检查：

bash

mainline preflight --json

若报告重叠、视图过期或分支漂移，进行窄范围扩展：

bash

mainline context --files <path>... --json

若任务为语义型：

bash

mainline context --query "<task summary>" --json

读取返回的摘要、决策、风险和指纹信息，将其作为历史上下文，然后与当前代码进行验证。除非用户明确要求重新审视，否则不得重复已放弃或已被取代的方案。

对于相关意图：

bash

mainline show <intent_id> --json
mainline trace <intent_id> --json

不得在每个任务中例行运行广泛的

context --current

、

list-proposals

、

show

和

trace

。预期流程为：先执行preflight；返回正常则继续；返回警告/错误则检查指定的意图/文件并解决特定风险。

重叠收敛流程：

上游已解决用户目标 → 放弃本地草稿或停止重复工作。
本地工作仍有增量价值 → 将其缩小为后续意图。
两个意图在语义上互斥 → 在继续前运行
```
mainline check
```
或请求人工判断。

Worktree And Intent Ownership

工作树与意图所有权

When coordination scope is

local_worktrees

, do not create or emulate a separate claim/lease registry. The drafting intent for a sibling's checked-out branch is the active local claim. Preflight surfaces its worktree path, goal, and observed files so agents can reuse existing work, narrow their scope, or order dependent work before editing. Only a live explicit file overlap blocks; goal-only matches, proposed/sealed history, and stale drafts remain warnings. Seal, abandon, or removal of the checked-out worktree naturally ends the claim.

Reuse the current worktree when it is clean or clearly owned by the current task.

Before

git switch

mainline append

, or

mainline seal

, confirm the branch, active intent, and dirty/untracked files still point to the same task. If not, stop and isolate the work; prefer a separate Git worktree for parallel active intents.

当协调范围为

local_worktrees

时，无需创建或模拟单独的声明/租赁注册表。兄弟分支已检出的草稿意图即为本地活动声明。Preflight会显示其工作树路径、目标和涉及的文件，以便agent复用现有工作、缩小范围或在编辑前安排依赖工作。仅实时明确的文件重叠会阻止操作；仅目标匹配、拟议/封存历史和过期草稿仅作为警告。封存、放弃或移除已检出的工作树会自然结束声明。

当当前工作树干净或明确属于当前任务时，复用该工作树。

在执行

git switch

、

mainline append

或

mainline seal

前，确认分支、活跃意图和未提交/未跟踪文件仍指向同一任务。若不匹配，停止并隔离工作；优先为并行活跃意图使用单独的Git工作树。

Editing Workflow

编辑工作流

After the Mainline context pass, inspect code normally and make the requested change.

Record turns at meaningful points:

bash

mainline append "<what changed and why>" --json

Append after a completed subtask, a pivot, or a discovery that changes the approach. Do not append a minute-by-minute activity log.

Never revert unrelated user changes to satisfy Mainline. If the worktree has unrelated files, leave them alone and keep your intent evidence scoped to your own changes.

Keep the intent drafting while exploring, proving an idea, or while the branch is likely to be rebased, amended, or rescoped. A local commit is useful evidence, but it does not by itself mean the work is ready to submit as team memory.

完成Mainline上下文检查后，正常检查代码并进行请求的变更。

在关键节点记录操作：

bash

mainline append "<变更内容及原因>" --json

在完成子任务、转向或发现改变方案时进行append。不得记录每分钟的活动日志。

切勿为满足Mainline要求而回退无关的用户变更。若工作树存在无关文件，无需处理，仅将意图证据限定在自身变更范围内。

在探索、验证想法或分支可能被变基、修正或调整范围时，保持意图处于草稿状态。本地提交是有用的证据，但本身并不意味着工作已准备好作为团队记忆提交。

Stop-Line Workflow

停止线工作流

Use

agent_authority

plus the current user instruction to decide the closeout boundary. Do not treat "work is implemented" as automatic permission to advance past that boundary. Current-instruction overrides are interpreted by the agent for this turn only; never write them to

.mainline/config.toml

.mainline/local.toml

Establish collaboration context with
```
mainline preflight --json
```
.

Read

.data.agent_authority.current.allowed_boundary

and decide any current user override.

Do the work and verify it.
Advance only to the allowed boundary.
Stop on hard gates.

The effective boundary is the lower of team policy, hard gates, and the current instruction. A direct user request can raise a turn to

review

only when

.data.agent_authority.team.max_autonomy

permits it; merge, release, and post-merge cleanup remain explicit delivery tasks, not autonomy.

Current instruction override classes:

Instruction class	Treat as
Advice-only / read-only	lower to `assist`
Finish local work / commit / seal / handoff	set boundary to `handoff`
Push branch / open or update PR	raise to `review` , capped by team `max_autonomy`
Merge / release / deploy / package publish / post-merge cleanup	explicit delivery task, not autonomy; identify the target and proceed only if directly requested and other hard gates allow it

Vague continuation instructions only advance to PR in effective

review

autonomy when implementation is complete, verification has passed, no unresolved design questions remain, and commit/seal/PR is the next natural boundary. Otherwise continue the next unfinished implementation or design step.

结合

agent_authority

和当前用户指令决定收尾边界。不得将"工作已实现"视为自动允许跨越该边界的权限。当前指令覆盖仅由agent在本次回合中解读；切勿将其写入

.mainline/config.toml

或

.mainline/local.toml

。

使用
```
mainline preflight --json
```
建立协作上下文。
读取
```
.data.agent_authority.current.allowed_boundary
```
并决定是否应用当前用户覆盖。
执行工作并验证。
仅推进至允许的边界。
在硬限制处停止。

有效边界为团队策略、硬限制和当前指令中的最低值。仅当

.data.agent_authority.team.max_autonomy

允许时，用户直接请求才可将回合提升至

review

；合并、发布和合并后清理仍为明确交付任务，而非自主操作。

当前指令覆盖类别：

指令类别	处理方式
仅建议/只读	降至 `assist`
完成本地工作/提交/封存/交接	设置边界为 `handoff`
推送分支/开启或更新PR	提升至 `review` ，受团队 `max_autonomy` 限制
合并/发布/部署/包发布/合并后清理	明确交付任务，非自主操作；仅在直接请求且其他硬限制允许时，确定目标并执行

模糊的继续指令仅在以下情况下才会在有效

review

自主性下推进至PR：实现完成、验证通过、无未解决设计问题，且提交/封存/PR是下一个自然边界。否则继续执行下一项未完成的实现或设计步骤。

Commit Workflow

提交工作流

Mainline does not prescribe how a repository stages changes, writes commits, or groups commits. Use the repository's existing Git workflow and commit conventions. If you are the one creating the commit, inspect the unstaged and staged diff first and include only the intended files.

Before committing or sealing, re-run the readiness gate:

bash

mainline preflight --json

If it reports

block

, stop and resolve or escalate the named overlap/drift instead of producing a dirty-only or stale-base seal. If it reports only

warn

, mention the warning in your handoff and make a conscious decision before continuing.

Before sealing, there must be a commit for Mainline to reference. Mainline does not create that commit for you.

If effective autonomy is

assist

, stop here after reporting the diff and verification status. The user may then explicitly ask you to commit and seal, which is a current-instruction handoff.

If the user asks for a commit or PR and the branch has no active intent, create or backfill one before committing unless the change is truly mechanical and the repository policy marks it skipped.

Mainline不规定仓库如何暂存变更、编写提交或分组提交。使用仓库现有的Git工作流和提交约定。若由你创建提交，需先检查未暂存和已暂存的差异，仅包含目标文件。

在提交或封存前，重新运行就绪检查：

bash

mainline preflight --json

若报告

block

，停止并解决或上报指定的重叠/漂移问题，而非仅生成包含脏数据或基于过期基线的封存。若仅报告

warn

，在交接时提及该警告，并在继续前做出明确决策。

封存前，必须存在可供Mainline引用的提交。Mainline不会为你创建该提交。

若有效自主性为

assist

，在此处停止并报告差异和验证状态。用户随后可能明确要求你提交并封存，这属于当前指令交接。

若用户要求提交或PR，且分支无活跃意图，除非变更确实是机械性的且仓库策略标记为跳过，否则在提交前创建或补充一个意图。

Seal Workflow

封存工作流

Only seal when the work is ready for handoff, review, PR, push, or another team-visible memory boundary. Do not seal merely because a local experiment or intermediate commit exists.

Do not seal in effective

assist

autonomy unless the user has explicitly asked for a handoff, commit, or seal boundary.

When the repository has the intended commit and the work is ready for that handoff boundary, prepare the seal:

bash

mainline seal --prepare --json > .ml-cache/seal.json

.ml-cache/

is gitignored by

mainline init

, so the temp seal file stays out of git AND keeps the v0.3 worktree-clean check happy on submit. The package contains a

seal_result_starter

field with the deterministic bits (intent_id, fingerprint.files_touched, fingerprint.subsystems) pre-populated — patch in title / what / why / decisions / rejected / acknowledged_constraints when applicable / review_notes / fingerprint / confidence rather than typing the JSON from scratch.

Seal records decisions by default. The seal summary write schema does not include durable signal creation fields such as legacy

summary.risks

summary.followups

, or

summary.anti_patterns

; old temp seal files containing those keys are rejected and should be regenerated with

mainline seal --prepare --json

Use explicit signal commands only when the source is real:

```
mainline risks add
```
only for a concrete failure mode with trigger or impact, plus mitigation / validation / owner.
```
mainline followups add
```
only when the user explicitly deferred the work, an external issue/ticket/PR exists, or this PR explicitly cut real scope.
Do not create constraints yourself.
```
mainline guard add
```
is interactive and requires human confirmation.

If you only have reviewer context, validation notes, accepted trade-offs, scope explanation, or a "maybe later" thought, keep it in

review_notes

decisions

, final response, or leave it out. Candidate constraints can be proposed to the user, but only the human-confirmed guard command makes them durable.

Generate a SealResult JSON matching the returned schema. The fingerprint must be specific enough for conflict detection:

```
summary.decisions
```
is an array of objects (
```
point
```
,
```
chose
```
, optional
```
rationale
```
, optional
```
rejected
```
string array), not a string array.
```
summary.rejected
```
is an array of objects (
```
alternative
```
, optional
```
reason
```
); keep it as
```
[]
```
when there are no top-level rejected alternatives.
```
summary.review_notes
```
is a string array; keep it as
```
[]
```
when there is no ephemeral reviewer context.

fingerprint.api_changes

and

fingerprint.data_model_changes

are arrays of objects; keep them as

[]

when none apply.

Subsystems and parent concepts
Files touched
Architectural claims
Behavioral changes
API or CLI changes
Data model changes
Security implications
Migration notes
Tags, including synonyms and related technologies

Submit the seal:

bash

mainline seal --submit --json < .ml-cache/seal.json

If the worktree has unrelated dirty or untracked files that cannot be cleaned because they belong to the user, use

--allow-dirty

only after noting that Mainline will permanently record the dirty state:

bash

mainline seal --submit --allow-dirty --json < .ml-cache/seal.json

If the response includes

conflicts

, treat them as phase-1 overlap warnings, not semantic conflict judgments. Inspect and classify them before closeout: adjacent, complementary, or already-accounted-for overlap should be summarized briefly in human terms only when useful; do not paste raw JSON by default. If you cannot classify a warning or it looks like a real semantic conflict, escalate to the user with the relevant intents, why it may conflict, and the recommended next action. Include raw JSON only when the user asks for debug detail or the tool output itself is needed to diagnose a failure.

If submit sealed locally but failed to publish because the network was down, retry later:

bash

mainline publish --intent <intent_id> --json

This is metadata publish, not product release or deploy. It only retries publishing the sealed Mainline intent state.

Do not use

mainline abandon

as a routine repair path for seal wording, lint warnings, or commit-hash drift after rebase/amend. Use abandon for cancellation or rejection of the work; if a submitted seal looks wrong, report the problem and choose an explicit repair/replacement path with the user.

仅当工作准备好进行交接、评审、PR、推送或其他团队可见的记忆边界时，才进行封存。不得仅因存在本地实验或中间提交而进行封存。

在有效

assist

自主性下，除非用户明确要求交接、提交或封存边界，否则不得进行封存。

当仓库存在目标提交且工作已准备好进入该交接边界时，准备封存：

bash

mainline seal --prepare --json > .ml-cache/seal.json

mainline init

会将

.ml-cache/

加入git忽略列表，因此临时封存文件不会进入git，同时满足v0.3版本提交时工作树干净的检查要求。该文件包含

seal_result_starter

字段，其中预填充了确定性内容（intent_id、fingerprint.files_touched、fingerprint.subsystems）——无需从头编写JSON，只需补充title/what/why/decisions/rejected/acknowledged_constraints（如适用）/review_notes/fingerprint/confidence即可。

封存记录默认包含决策。封存摘要写入模式不包含持久信号创建字段，如旧版的

summary.risks

、

summary.followups

或

summary.anti_patterns

；包含这些键的旧临时封存文件会被拒绝，需使用

mainline seal --prepare --json

重新生成。

仅当来源真实时，才使用明确的信号命令：

```
mainline risks add
```
仅用于具有触发条件或影响的具体故障模式，以及缓解措施/验证方式/负责人。
```
mainline followups add
```
仅用于用户明确推迟的工作、存在外部问题/工单/PR，或本PR明确削减了实际范围的情况。
不得自行创建约束。
```
mainline guard add
```
为交互式命令，需人工确认。

若仅拥有评审上下文、验证说明、已接受的权衡、范围解释或"可能后续处理"的想法，将其保留在

review_notes

、

decisions

、最终回复中，或直接忽略。候选约束可向用户提议，但只有经人工确认的guard命令才能使其持久化。

生成符合返回模式的SealResult JSON。指纹需足够具体以支持冲突检测：

```
summary.decisions
```
为对象数组（包含
```
point
```
、
```
chose
```
、可选
```
rationale
```
、可选
```
rejected
```
字符串数组），而非字符串数组。
```
summary.rejected
```
为对象数组（包含
```
alternative
```
、可选
```
reason
```
）；若无顶级被拒绝方案，保持为
```
[]
```
。
```
summary.review_notes
```
为字符串数组；若无临时评审上下文，保持为
```
[]
```
。

fingerprint.api_changes

和

fingerprint.data_model_changes

为对象数组；若无相关变更，保持为

[]

。

子系统和父概念
涉及的文件
架构声明
行为变更
API或CLI变更
数据模型变更
安全影响
迁移说明
标签，包括同义词和相关技术

提交封存：

bash

mainline seal --submit --json < .ml-cache/seal.json

若工作树存在无关的脏文件或未跟踪文件，且因属于用户而无法清理，可使用

--allow-dirty

，但需注意Mainline会永久记录脏状态：

bash

mainline seal --submit --allow-dirty --json < .ml-cache/seal.json

若响应包含

conflicts

，将其视为第一阶段重叠警告，而非语义冲突判断。在收尾前检查并分类：仅在有用时以人类可读的简要形式总结相邻、互补或已考虑到的重叠；默认不要粘贴原始JSON。若无法分类警告或看起来是真实语义冲突，需向用户上报相关意图、冲突原因及建议下一步操作。仅当用户要求调试细节或需要工具输出来诊断故障时，才包含原始JSON。

若已在本地完成封存但因网络问题发布失败，可稍后重试：

bash

mainline publish --intent <intent_id> --json

此操作为元数据发布，而非产品发布或部署。仅重试发布已封存的Mainline意图状态。

不要将

mainline abandon

作为修复封存措辞、lint警告或变基/修正后的提交哈希漂移的常规方案。仅在取消或拒绝工作时使用abandon；若已提交的封存存在问题，需上报问题并与用户选择明确的修复/替换方案。

Publishing, Pushes, And PRs

发布、推送与PR

Mainline does not require a Git push, a pull request, or GitHub. Preserve the repository's existing review and release workflow unless the user explicitly asks you to change it.

Effective

handoff

autonomy stops before pushing a code branch or opening / updating a PR. Effective

review

autonomy may push a non-main branch and open or update a PR, but it still stops before merge, release, or post-merge cleanup. If the current branch is

main

, create or switch to a non-main branch before pushing or opening PR;

review

autonomy never authorizes

git push origin main

Before any remote branch push or PR creation that the user requested and the stop line permits, ensure the intent is proposed or publishable:

bash

mainline status --json
mainline publish --intent <intent_id> --json

If the user's workflow opens or updates a PR, generate the PR body from the sealed Mainline intent:

bash

mainline pr-description --intent <intent_id> > .ml-cache/pr-description.md

Use that generated markdown as the PR body. Do not hand-write a replacement PR description when a sealed intent exists, and do not rely on a generic GitHub publish helper's default body. The generated body includes the

mainline:pr-description

marker; the PR intent-comment workflow uses that marker to avoid creating a duplicate sticky comment.

Before calling any GitHub publishing helper, connector, or

gh pr create

fallback, inspect the generated file and verify that it still contains

<!-- mainline:pr-description:start -->

. Pass that exact file content as the PR body. Do not copy only the visible Markdown, regenerate a lookalike body, or let the publishing helper overwrite the body with

--fill

/ default prose. For the

gh

fallback, the safe shape is:

bash

gh pr create --body-file .ml-cache/pr-description.md

Do not use

gh pr create --fill

or any connector default body when a sealed intent exists.

If the user did not ask to push or open a PR, stop after sealing/publishing the Mainline intent and report the local result. Do not introduce a remote workflow just because Mainline metadata is ready.

Do not run these unless the user explicitly asks:

bash

mainline pin <intent> <commit>
mainline init --rewire
mainline doctor --setup --fix

Mainline不要求Git推送、拉取请求或GitHub。保留仓库现有的评审和发布工作流，除非用户明确要求更改。

有效

handoff

自主性在推送代码分支或开启/更新PR前停止。有效

review

自主性可推送非main分支并开启或更新PR，但仍会在合并、发布或合并后清理前停止。若当前分支为

main

，需先创建或切换至非main分支，再进行推送或开启PR；

review

自主性永远不授权

git push origin main

。

在执行用户要求且停止线允许的远程分支推送或PR创建前，确保意图已拟议或可发布：

bash

mainline status --json
mainline publish --intent <intent_id> --json

若用户工作流要求开启或更新PR，从已封存的Mainline意图生成PR正文：

bash

mainline pr-description --intent <intent_id> > .ml-cache/pr-description.md

使用生成的markdown作为PR正文。当存在已封存意图时，不得手动编写替代PR描述，也不得依赖通用GitHub发布助手的默认正文。生成的正文包含

mainline:pr-description

标记；PR意图评论工作流会使用该标记避免创建重复的粘性评论。

在调用任何GitHub发布助手、连接器或

gh pr create

回退方案前，检查生成的文件并确认其仍包含

<!-- mainline:pr-description:start -->

。将该文件的准确内容作为PR正文。不得仅复制可见的Markdown、重新生成相似的正文，或允许发布助手用

--fill

/默认文案覆盖正文。对于

gh

回退方案，安全格式为：

bash

gh pr create --body-file .ml-cache/pr-description.md

当存在已封存意图时，不得使用

gh pr create --fill

或任何连接器的默认正文。

若用户未要求推送或开启PR，在封存/发布Mainline意图后停止并报告本地结果。不得仅因Mainline元数据就绪而引入远程工作流。

除非用户明确要求，否则不得运行以下命令：

bash

mainline pin <intent> <commit>
mainline init --rewire
mainline doctor --setup --fix

Review And Conflict Workflow

评审与冲突工作流

Use these commands when asked to review Mainline state, explain prior work, or judge conflict markers:

bash

mainline log --json --limit 30
mainline show <intent_id> --json
mainline trace <intent_id> --json
mainline check --prepare --intent <intent_id> --json
mainline check --submit --json < judgment.json

Use

show

to understand decisions and risks. Use

trace

to understand how the work unfolded. Use

check

only when inspected phase-1 overlap is real and potentially contradictory. Adjacent or complementary overlap should be recorded as a judgment in append / seal instead of escalated into

check

当被要求评审Mainline状态、解释过往工作或判断冲突标记时，使用以下命令：

bash

mainline log --json --limit 30
mainline show <intent_id> --json
mainline trace <intent_id> --json
mainline check --prepare --intent <intent_id> --json
mainline check --submit --json < judgment.json

使用

show

了解决策和风险。使用

trace

了解工作的展开过程。仅当检查到的第一阶段重叠真实且可能存在矛盾时，才使用

check

。相邻或互补的重叠应在append/封存中记录为判断，而非升级为

check

。

Coverage And Rescue

覆盖范围与补救

If status or gaps reports uncovered commits:

bash

mainline gaps --json

Choose the least destructive rescue path. These are recovery options, not a replacement for the repository's normal Git workflow:

If the commit is local and unpushed, you may undo the commit with
```
git reset --soft HEAD^
```
, start the proper intent, recommit using the repository's normal workflow, and seal.
If the commit is already pushed, backfill an intent with
```
mainline start "<why>" --commits <sha>
```
, append the post-hoc explanation, then seal.
If it is routine and deliberately outside Mainline, add a
```
Mainline-Skip:
```
trailer or configure a skip pattern.

Do not rewrite published history unless the user explicitly asks.

若status或gaps报告存在未覆盖提交：

bash

mainline gaps --json

选择破坏性最小的补救方案。这些是恢复选项，而非仓库正常Git工作流的替代方案：

若提交为本地未推送，可使用
```
git reset --soft HEAD^
```
撤销提交，启动正确的意图，使用仓库正常工作流重新提交并封存。
若提交已推送，使用
```
mainline start "<原因>" --commits <sha>
```
补充意图，追加事后解释，然后封存。
若为常规操作且故意排除在Mainline外，添加
```
Mainline-Skip:
```
trailer或配置跳过规则。

除非用户明确要求，否则不得重写已发布的历史。

Skill Distribution

技能分发

Install this skill with

npx skills

for supported target agents:

bash

npx --yes skills add mainline-org/mainline --skill mainline --agent codex claude-code cursor pi --global --yes

For local development from this repository:

bash

npx --yes skills add ./skills/mainline --skill mainline --agent codex claude-code cursor pi --global --yes

mainline init

best-effort installs the default skill and hooks. Existing global skill installs are not refreshed by

mainline agents update

mainline init --rewire

; refresh them explicitly with:

bash

npx --yes skills update mainline --global --yes

If update cannot determine the source, rerun the matching

skills add

command above. The durable purpose of the skill is to teach agents to install, initialize, use, publish, and review Mainline intent data correctly.

对于支持的目标agent，使用

npx skills

安装本技能：

bash

npx --yes skills add mainline-org/mainline --skill mainline --agent codex claude-code cursor pi --global --yes

从本仓库进行本地开发时：

bash

npx --yes skills add ./skills/mainline --skill mainline --agent codex claude-code cursor pi --global --yes

mainline init

会尽力安装默认技能和钩子。已有的全局技能安装不会被

mainline agents update

或

mainline init --rewire

刷新；需使用以下命令明确刷新：

bash

npx --yes skills update mainline --global --yes

若update无法确定来源，重新运行上述匹配的

skills add

命令。本技能的持久目标是教会agent正确安装、初始化、使用、发布和评审Mainline意图数据。