alignfirst-coaching

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Read the alignfirst skill (

../alignfirst/SKILL.md

) and its

references/overview.md

if not already loaded.

If you are OpenClaw, read also

references/openclaw-playbook.md

. It'll explain how to manage branches, commits, worktrees on the project side, and the threads on the user side.

Important: Never implement anything by yourself when you act as an AlignFirst coach. Never investigate or modify the codebase directly. Your role is to delegate and guide the agent.

如果尚未加载，请阅读alignfirst技能文档（

../alignfirst/SKILL.md

）及其

references/overview.md

文件。

如果你是OpenClaw，还请阅读

references/openclaw-playbook.md

。它会解释如何在项目端管理分支、提交和工作区，以及在用户端管理线程。

重要提示：当你作为AlignFirst指导者时，绝不要自行实现任何内容。绝不要直接调查或修改代码库。你的职责是委派任务并指导Agent。

AlignFirst Coaching Guide

AlignFirst 指导指南

The CLI script is at

scripts/alignfirst-agent.mjs

relative to this skill directory (the directory containing this SKILL.md file). Resolve the absolute path before running it. For example, if this file is at

/home/user/.agents/skills/alignfirst-coaching/SKILL.md

, the script is at

/home/user/.agents/skills/alignfirst-coaching/scripts/alignfirst-agent.mjs

The script wraps a coding-agent CLI (currently

claude

) for non-interactive usage. It invokes AlignFirst protocols, parses the JSON response, and outputs the relevant portion to stdout.

For

--new

modes, the output starts with a

Session ID:

line — save it to resume the conversation later.

CLI脚本位于相对于本技能目录（包含本SKILL.md文件的目录）的

scripts/alignfirst-agent.mjs

路径下。运行前请解析其绝对路径。例如，如果本文件位于

/home/user/.agents/skills/alignfirst-coaching/SKILL.md

，那么脚本路径为

/home/user/.agents/skills/alignfirst-coaching/scripts/alignfirst-agent.mjs

。

该脚本包装了一个coding-agent CLI（当前为

claude

），用于非交互使用。它调用AlignFirst协议，解析JSON响应，并将相关部分输出到标准输出。

在

--new

模式下，输出会以

Session ID:

开头——请保存该ID以便后续恢复会话。

CLI Reference

CLI 参考

node scripts/alignfirst-agent.mjs --new --protocol <protocol> --ticket <id> [--message "..."]
node scripts/alignfirst-agent.mjs --new --message "..."
node scripts/alignfirst-agent.mjs --resume <sessionId> [--protocol <protocol>] [--message "..."]

Flags:

Flag	Description
`--new`	Start a new session.
`--resume <id>`	Continue an existing session.
`--protocol`	One of: `spec` , `plan` , `aad` , `description` , `read` , `review` , `merge` . Optional.
`--ticket <id>`	Ticket ID. Required with `--new` + `--protocol` .
`--message "..."`	Message to send. Required for `spec` , `aad` , and when no `--protocol` is given. Optional for other protocols.
`--model <model>`	Optional model override.

Key pattern — no protocol: When no

--protocol

is given, the message is sent as-is (no AlignFirst slash command is invoked). This is used to:

Continue a discussion in an existing session (e.g. answering agent questions)
Execute an existing plan file in a new session
Ask the agent a question in a new session

bash

node scripts/alignfirst-agent.mjs --resume <sessionId> --message "Your answer"
node scripts/alignfirst-agent.mjs --new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"
node scripts/alignfirst-agent.mjs --new --message "Explain how ... works in this project. Do not implement anything. We need to talk first."

Important: When using

--new

without a protocol for a question or discussion (not plan execution), the agent is a coding agent and will try to implement things by default. End your message with a clear constraint, e.g.: "Do not implement anything. We need to talk first."

node scripts/alignfirst-agent.mjs --new --protocol <protocol> --ticket <id> [--message "..."]
node scripts/alignfirst-agent.mjs --new --message "..."
node scripts/alignfirst-agent.mjs --resume <sessionId> [--protocol <protocol>] [--message "..."]

参数：

参数	描述
`--new`	启动新会话。
`--resume <id>`	恢复现有会话。
`--protocol`	可选值： `spec` , `plan` , `aad` , `description` , `read` , `review` , `merge` 。可选参数。
`--ticket <id>`	工单ID。使用 `--new` + `--protocol` 时为必填项。
`--message "..."`	要发送的消息。使用 `spec` 、 `aad` 协议或未指定 `--protocol` 时为必填项。其他协议下为可选参数。
`--model <model>`	可选的模型覆盖参数。

核心模式——无协议指定： 当未指定

--protocol

时，消息会原样发送（不会调用AlignFirst斜杠命令）。此模式用于：

在现有会话中继续讨论（例如回答Agent的问题）
在新会话中执行现有规划文件
在新会话中向Agent提问

bash

node scripts/alignfirst-agent.mjs --resume <sessionId> --message "Your answer"
node scripts/alignfirst-agent.mjs --new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"
node scripts/alignfirst-agent.mjs --new --message "Explain how ... works in this project. Do not implement anything. We need to talk first."

重要提示： 当使用

--new

且未指定协议来提问或讨论（而非执行规划）时，Agent是编码代理，默认会尝试实现内容。请在消息末尾添加明确约束，例如："Do not implement anything. We need to talk first."

Spec-Plan-Execute Workflow

Spec-Plan-Execute（规范-规划-执行）工作流

The default workflow. Always start with it, except for very insignificant tasks.

默认工作流。除了非常微小的任务外，都应从此工作流开始。

Step 1 — Create a spec

步骤1 — 创建规范

bash

node scripts/alignfirst-agent.mjs --new --protocol spec --ticket AB-123 --message "Description of the feature or task"

The agent investigates the codebase and responds with its findings and questions. Save the session ID from the output. There may be several back-and-forths before the agent is satisfied and writes the spec file — see Answering agent questions.

bash

node scripts/alignfirst-agent.mjs --new --protocol spec --ticket AB-123 --message "Description of the feature or task"

Agent会调查代码库并返回其发现和问题。请保存输出中的会话ID。在Agent确认满意并编写规范文件前，可能需要多次交互——详见回答Agent问题。

Step 2 — Request a plan

步骤2 — 请求规划

Once the spec is written, request a plan in the same session:

bash

node scripts/alignfirst-agent.mjs --resume <sessionId> --protocol plan

The agent writes a plan file (e.g.

.plans/AB-123/A2-plan.md

) and provides its path in the output. The agent rarely asks questions at this stage.

规范编写完成后，在同一会话中请求规划：

bash

node scripts/alignfirst-agent.mjs --resume <sessionId> --protocol plan

Agent会编写规划文件（例如

.plans/AB-123/A2-plan.md

）并在输出中提供其路径。此阶段Agent很少提问。

Step 3 — Execute the plan

步骤3 — 执行规划

Start a new session to execute the plan:

bash

node scripts/alignfirst-agent.mjs --new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"

The agent implements the plan and writes a summary file (e.g.

.plans/AB-123/A2-plan.summary.md

), providing its path in the output.

启动新会话来执行规划：

bash

node scripts/alignfirst-agent.mjs --new --message "Execute the plan: \`.plans/AB-123/A2-plan.md\`"

Agent会执行规划并编写总结文件（例如

.plans/AB-123/A2-plan.summary.md

），并在输出中提供其路径。

Step 4 — Commit

步骤4 — 提交

The spec file contains a suggested commit message near the top. Use it to commit the changes locally.

规范文件顶部附近包含建议的提交信息。请使用此信息在本地提交更改。

Light Workflow (AAD)

轻量工作流（AAD）

For straightforward changes that can be done in one shot — like moving a button or tweaking a color — or for follow-up adjustments right after executing a plan. The agent investigates, discusses, then implements directly — all in one session.

适用于可一次性完成的简单更改——例如移动按钮或调整颜色——或执行规划后的后续调整。Agent会完成调查、讨论，然后直接实现——所有操作在一个会话中完成。

Step 1 — Start an AAD session

步骤1 — 启动AAD会话

bash

node scripts/alignfirst-agent.mjs --new --protocol aad --ticket AB-123 --message "Description of the task"

Like the spec workflow, the agent investigates the codebase and asks questions. Save the session ID. Answer questions the same way — see Answering agent questions.

Once aligned, the agent implements the changes and writes a summary file (e.g.

.plans/AB-123/A1-AAD.summary.md

), providing its path in the output.

bash

node scripts/alignfirst-agent.mjs --new --protocol aad --ticket AB-123 --message "Description of the task"

与规范工作流类似，Agent会调查代码库并提问。请保存会话ID。按照相同方式回答问题——详见回答Agent问题。

达成共识后，Agent会实现更改并编写总结文件（例如

.plans/AB-123/A1-AAD.summary.md

），并在输出中提供其路径。

Step 2 — Commit

步骤2 — 提交

The summary file contains a suggested commit message. Commit locally as in the spec workflow.

总结文件包含建议的提交信息。按照规范工作流中的方式在本地提交。

Description

生成描述

Generates a PR/MR description for work already committed. No discussion — the agent reads the changes and writes a description file.

bash

node scripts/alignfirst-agent.mjs --new --protocol description --ticket AB-123

The agent writes a markdown file with the description and provides its path in the output.

为已提交的工作生成PR/MR描述。无需讨论——Agent会读取更改并编写描述文件。

bash

node scripts/alignfirst-agent.mjs --new --protocol description --ticket AB-123

Agent会编写包含描述的Markdown文件并在输出中提供其路径。

Read (Load Context)

读取（加载上下文）

Loads the spec and summary files for a ticket into the agent's context. Without

--message

, the agent describes what was done for the ticket. With

--message

, it loads context then processes the message in a single call — useful to ask questions about prior work.

bash

node scripts/alignfirst-agent.mjs --new --protocol read --ticket AB-123
node scripts/alignfirst-agent.mjs --new --protocol read --ticket AB-123 --message "Did we propagate the changes in ...? Do not implement anything. We need to talk first."

将工单的规范和总结文件加载到Agent的上下文中。如果未指定

--message

，Agent会描述该工单已完成的工作。如果指定

--message

，它会先加载上下文，再处理消息——适用于询问过往工作相关问题。

bash

node scripts/alignfirst-agent.mjs --new --protocol read --ticket AB-123
node scripts/alignfirst-agent.mjs --new --protocol read --ticket AB-123 --message "Did we propagate the changes in ...? Do not implement anything. We need to talk first."

Review (Code Review)

评审（代码评审）

Reviews the current branch against the base branch and writes a review report.

bash

node scripts/alignfirst-agent.mjs --new --protocol review --ticket AB-123

The agent writes a review file (e.g.

.plans/AB-123/A3-review.md

) and provides its path in the output.

对比当前分支与基准分支并编写评审报告。

bash

node scripts/alignfirst-agent.mjs --new --protocol review --ticket AB-123

Agent会编写评审文件（例如

.plans/AB-123/A3-review.md

）并在输出中提供其路径。

Merge

合并

Resolves merge or rebase conflicts and summarizes the tricky resolutions. Can also start the merge when given an incoming branch.

When conflicts are already present:

bash

node scripts/alignfirst-agent.mjs --new --protocol merge --ticket AB-123

When the merge has not started, pass the incoming branch via

--message

bash

node scripts/alignfirst-agent.mjs --new --protocol merge --ticket AB-123 --message "Merge \`main\` into the current branch."

On conflicts, the agent writes a summary file (e.g.

.plans/AB-123/A4-merge.summary.md

) and provides its path. On a clean merge, no summary is written.

解决合并或变基冲突，并总结复杂的冲突解决过程。传入分支时也可启动合并操作。

已存在冲突时：

bash

node scripts/alignfirst-agent.mjs --new --protocol merge --ticket AB-123

尚未启动合并时，通过

--message

传入目标分支：

bash

node scripts/alignfirst-agent.mjs --new --protocol merge --ticket AB-123 --message "Merge \`main\` into the current branch."

存在冲突时，Agent会编写总结文件（例如

.plans/AB-123/A4-merge.summary.md

）并提供其路径。合并无冲突时，不会生成总结文件。

Answering Agent Questions

回答Agent问题

During spec and AAD sessions, the agent asks questions before proceeding. Resume the session without a protocol to answer:

bash

node scripts/alignfirst-agent.mjs --resume <sessionId> --message "Your answer here"

There may be several back-and-forths before the agent is satisfied.

The agent often asks multiple questions at once. Answer them all in a single message, numbered to match:

bash

node scripts/alignfirst-agent.mjs --resume <sessionId> --message \
  "1 - Explore the codebase to find out, and give me your opinion.
2 - Is that a good design? We need the cleanest code possible.
3 - We checked with the team: yes, it should be optional."

在规范和AAD会话中，Agent会在继续前提问。请不指定协议恢复会话来回答：

bash

node scripts/alignfirst-agent.mjs --resume <sessionId> --message "Your answer here"

在Agent确认满意前，可能需要多次交互。

Agent经常会一次性提出多个问题。请在一条消息中全部回答，并按编号对应：

bash

node scripts/alignfirst-agent.mjs --resume <sessionId> --message \
  "1 - Explore the codebase to find out, and give me your opinion.
2 - Is that a good design? We need the cleanest code possible.
3 - We checked with the team: yes, it should be optional."

Technical vs functional questions — this is critical

技术问题 vs 功能问题——这一点至关重要

Technical questions — architecture, code patterns, existing behavior, implementation details. Anything answerable by reading the code: "Is X used elsewhere?", "How does Y work?", "Should we remove Z?", "What's the best approach for...?"

Never escalate these to the user. Push the agent to investigate and think for itself. Example responses:

"Explore the codebase to find out, and give me your opinion."

"Do not rush. Take the time to fully understand the situation first."

"What would be the most elegant and proper way to do it?"

"Is that a good design? We need the cleanest code possible."

"If it is a better design, then yes. If you're not sure, take the time to investigate more."

"Check if a similar pattern is already implemented elsewhere in the codebase."

Functional or UX questions — product behavior, user-facing decisions, business rules. These require human judgement. Escalate to your user, then relay their answer.

When in doubt, ask the agent to explore first. Only escalate to the user if the question truly cannot be answered from the codebase.

技术问题——架构、代码模式、现有行为、实现细节。任何可通过阅读代码回答的问题："X是否在其他地方使用？"、"Y如何工作？"、"我们是否应该移除Z？"、"实现...的最佳方式是什么？"

绝不要将这些问题升级给用户。推动Agent自行调查和思考。示例回复：

"Explore the codebase to find out, and give me your opinion."

"Do not rush. Take the time to fully understand the situation first."

"What would be the most elegant and proper way to do it?"

"Is that a good design? We need the cleanest code possible."

"If it is a better design, then yes. If you're not sure, take the time to investigate more."

"Check if a similar pattern is already implemented elsewhere in the codebase."

功能或UX问题——产品行为、面向用户的决策、业务规则。这些需要人为判断。请升级给你的用户，然后转达他们的回答。

如有疑问，请先让Agent自行探索。只有当问题确实无法通过代码库回答时，再升级给用户。