write-report

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

write-report

撰写报告

Write a correctly named, correctly placed mission report and post it to the Quest dashboard. Encapsulates the full boilerplate from CONVENTIONS.md so agents don't copy-paste (or forget) it.

撰写命名规范、存放位置正确的任务报告并发布至Quest dashboard。封装了CONVENTIONS.md中的完整模板，避免Agent复制粘贴（或遗漏）内容。

When to Use

使用场景

At the end of every mission to write the mission report
When writing rollcall team reports
When writing speckit, deps, review, or crew-runner reports
When dispatching a fan-out batch and writing the supervisor manifest

每次任务结束时撰写任务报告
撰写rollcall团队报告时
撰写speckit、deps、review或crew-runner报告时
分发批量任务并撰写主管清单时

When NOT to Use

禁用场景

Inside
```
crew/*/
```
subdirectories — all reports go to repo root
```
reports/
```
For another team's report — each agent writes its own

在
```
crew/*/
```
子目录内使用——所有报告均需存放至仓库根目录的
```
reports/
```
文件夹
替其他团队撰写报告——每个Agent需自行撰写各自的报告

Invocation Examples

调用示例

bash

undefined

bash

undefined

Standard mission report

标准任务报告

/write-report --group crew-runner --id "fellowship-dev-navvi-42" --type crew-runner

Rollcall team report

Rollcall团队报告

/write-report --group rollcall --id lexgo --type rollcall

Fan-out manifest (written at dispatch time by supervisor)

批量任务清单（由主管在分发时撰写）

/write-report --manifest --group rollcall --jobs "lexgo:pending,tooling:pending,navvi:pending"

undefined

/write-report --manifest --group rollcall --jobs "lexgo:pending,tooling:pending,navvi:pending"

undefined

Workflow

工作流程

Step 1: Resolve the report directory

步骤1：确定报告目录

Always resolve from git repo root — NEVER hardcode or use

crew/*/

bash

REPORT_DIR="$(git rev-parse --show-toplevel)/reports"

git rev-parse

fails, you are not in a git repo.

cd

to the correct project root and retry.

始终从Git仓库根目录解析路径——绝对不要硬编码或使用

crew/*/

路径：

bash

REPORT_DIR="$(git rev-parse --show-toplevel)/reports"

如果

git rev-parse

执行失败，说明当前不在Git仓库中。请切换到正确的项目根目录后重试。

Step 2: Generate the filename

步骤2：生成文件名

All timestamps are UTC:

bash

TIMESTAMP=$(date -u +"%Y%m%d-%H%M")

Filename patterns:

Report type	Filename
Standard (speckit, deps, review, crew-runner)	`{TIMESTAMP}_{group}_{id}.md`
Rollcall team	`{TIMESTAMP}_rollcall_{team}.md`
Rollcall assembly	`{TIMESTAMP}_rollcall_assembly.md`
Fan-out manifest	`{TIMESTAMP}_{group}_manifest.json`

Examples:

20260413-1100_rollcall_lexgo.md
20260413-1115_crew-runner_fellowship-dev-navvi-42.md
20260413-1100_rollcall_manifest.json

所有时间戳均采用UTC时区：

bash

TIMESTAMP=$(date -u +"%Y%m%d-%H%M")

文件名规则：

报告类型	文件名
标准报告（speckit、deps、review、crew-runner）	`{TIMESTAMP}_{group}_{id}.md`
Rollcall团队报告	`{TIMESTAMP}_rollcall_{team}.md`
Rollcall集合报告	`{TIMESTAMP}_rollcall_assembly.md`
批量任务清单	`{TIMESTAMP}_{group}_manifest.json`

示例：

20260413-1100_rollcall_lexgo.md
20260413-1115_crew-runner_fellowship-dev-navvi-42.md
20260413-1100_rollcall_manifest.json

Step 3: Write the file

步骤3：写入文件

For markdown reports — use the Write tool if available, otherwise fall back to Bash:

REPORT_PATH="${REPORT_DIR}/${TIMESTAMP}_${GROUP}_${ID}.md"

Write the full report content to that path. If the Write tool is not in your

allowed-tools

(e.g., CEO/CTO roles), use Bash instead:

bash

cat > "$REPORT_PATH" << 'REPORT_EOF'
[report content here]
REPORT_EOF

For fan-out manifests (

--manifest

flag):

bash

MANIFEST_PATH="${REPORT_DIR}/${TIMESTAMP}_${GROUP}_manifest.json"

Required JSON structure (all fields mandatory):

json

{
  "group_id": "{group}-{YYYYMMDD}-{HHMM}",
  "origin_job": "~/.local/share/pylot/missions/done/{job-file}.job",
  "jobs": {
    "job-id-1": "pending",
    "job-id-2": "pending"
  },
  "created_at": "2026-04-13T11:00:00Z"
}

Parse the

--jobs

argument (format:

"id1:state1,id2:state2,..."

bash

python3 -c "
import json, sys
jobs_str = sys.argv[1]
jobs = {}
for pair in jobs_str.split(','):
    job_id, state = pair.strip().split(':')
    jobs[job_id.strip()] = state.strip()
manifest = {
    'group_id': sys.argv[2],
    'origin_job': sys.argv[3] if len(sys.argv) > 3 else 'unknown',
    'jobs': jobs,
    'created_at': sys.argv[4]
}
print(json.dumps(manifest, indent=2))
" "$JOBS_ARG" "${GROUP}-${YYYYMMDD}-${HHMM}" "${ORIGIN_JOB:-unknown}" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$MANIFEST_PATH"

Job states:

pending

done

failed

对于Markdown报告——如果有Write工具可用则使用该工具，否则使用Bash命令：

REPORT_PATH="${REPORT_DIR}/${TIMESTAMP}_${GROUP}_${ID}.md"

将完整报告内容写入该路径。如果Write工具不在你的

allowed-tools

列表中（例如CEO/CTO角色），请使用Bash命令替代：

bash

cat > "$REPORT_PATH" << 'REPORT_EOF'
[报告内容此处]
REPORT_EOF

对于批量任务清单（使用

--manifest

参数）：

bash

MANIFEST_PATH="${REPORT_DIR}/${TIMESTAMP}_${GROUP}_manifest.json"

必填JSON结构（所有字段均为必填项）：

json

{
  "group_id": "{group}-{YYYYMMDD}-{HHMM}",
  "origin_job": "~/.local/share/pylot/missions/done/{job-file}.job",
  "jobs": {
    "job-id-1": "pending",
    "job-id-2": "pending"
  },
  "created_at": "2026-04-13T11:00:00Z"
}

解析

--jobs

参数（格式：

"id1:state1,id2:state2,..."

）：

bash

python3 -c "
import json, sys
jobs_str = sys.argv[1]
jobs = {}
for pair in jobs_str.split(','):
    job_id, state = pair.strip().split(':')
    jobs[job_id.strip()] = state.strip()
manifest = {
    'group_id': sys.argv[2],
    'origin_job': sys.argv[3] if len(sys.argv) > 3 else 'unknown',
    'jobs': jobs,
    'created_at': sys.argv[4]
}
print(json.dumps(manifest, indent=2))
" "$JOBS_ARG" "${GROUP}-${YYYYMMDD}-${HHMM}" "${ORIGIN_JOB:-unknown}" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$MANIFEST_PATH"

任务状态：

pending

done

failed

Step 4: Post to Quest DB

步骤4：发布至Quest DB

Always attempt — skip silently on failure. Manifests are NOT posted, only

.md

reports:

bash

QUEST_TOKEN=$(grep '^QUEST_TOKEN=' /home/ubuntu/projects/fellowship-dev/claude-buddy/.env | cut -d= -f2)
curl -s -X POST "http://127.0.0.1:4242/api/event" \
  -H "Authorization: Bearer $QUEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(python3 -c "
import json
content = open('$REPORT_PATH').read()
print(json.dumps({
  'source': 'commander',
  'type': 'commander.report',
  'title': '$REPORT_TITLE',
  'meta': {'content': content, 'report_type': '$GROUP'}
}))
")" 2>/dev/null || true

始终尝试执行——失败时静默跳过。仅

.md

报告需发布，批量任务清单无需发布：

bash

QUEST_TOKEN=$(grep '^QUEST_TOKEN=' /home/ubuntu/projects/fellowship-dev/claude-buddy/.env | cut -d= -f2)
curl -s -X POST "http://127.0.0.1:4242/api/event" \
  -H "Authorization: Bearer $QUEST_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(python3 -c "
import json
content = open('$REPORT_PATH').read()
print(json.dumps({
  'source': 'commander',
  'type': 'commander.report',
  'title': '$REPORT_TITLE',
  'meta': {'content': content, 'report_type': '$GROUP'}
}))
")" 2>/dev/null || true

Step 5: Commit and push

步骤5：提交并推送至Git

bash

cd "$(git rev-parse --show-toplevel)"
git add reports/
git commit -m "report: ${GROUP} ${ID}"
git push

bash

cd "$(git rev-parse --show-toplevel)"
git add reports/
git commit -m "report: ${GROUP} ${ID}"
git push

Error Handling

错误处理

git rev-parse
fails — not in a git repo.

cd

to the correct project root before invoking.

Quest unreachable — expected in offline/pod environments. The

|| true

guard handles this. Do not retry.

--jobs
parse error — malformed jobs string. Expected:

"id1:state1,id2:state2"

. Each pair needs exactly one

separator.

File already exists — Write tool will overwrite. If writing multiple reports in the same minute, append a suffix to

ID

git rev-parse
执行失败——当前不在Git仓库中。调用前请切换到正确的项目根目录。

Quest服务不可达——在离线/容器环境中属于预期情况。

|| true

语句会处理该情况，无需重试。

--jobs
参数解析错误——任务字符串格式错误。正确格式应为：

"id1:state1,id2:state2"

。每组键值对需包含且仅包含一个

分隔符。

文件已存在——Write工具会自动覆盖文件。如果在同一分钟内撰写多个报告，请在

ID

后添加后缀。

Critical Rules

核心规则

NEVER write to
crew/*/
— resolve path from
```
git rev-parse --show-toplevel
```
All timestamps in UTC — always use
```
date -u
```
Manifests are NOT posted to Quest — only
```
.md
```
files get posted
Workers write their own reports — never write another team's report
Quest skip must be silent —
```
|| true
```
is required, not optional

绝对不要写入
crew/*/
目录——通过
```
git rev-parse --show-toplevel
```
解析路径
所有时间戳均采用UTC时区——始终使用
```
date -u
```
命令
批量任务清单无需发布至Quest——仅
```
.md
```
文件需要发布
工作人员自行撰写报告——切勿替其他团队撰写报告
Quest提交失败需静默处理——必须添加
```
|| true
```
语句，不可省略