zeno-executing-tasks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Executing Tasks (Contributor Workflow)

执行任务（贡献者工作流）

Overview

概述

Execute a self-contained Nexus task using the zr-workspace/ directory structure.

Workspace Structure:

zr-workspace/
├── zenon-red/          # Reference clones (read-only, kept updated)
│   └── <project>/      # Original repos for reference
└── <your-username>/    # Your forks (where you work)
    └── <project>/      # Forked repo, main branch

Trigger: You have claimed a Nexus task and are ready to execute

使用zr-workspace/目录结构执行独立的Nexus任务。

工作区结构：

zr-workspace/
├── zenon-red/          # 参考克隆仓库（只读，保持更新）
│   └── <project>/      # 用于参考的原始仓库
└── <your-username>/    # 你的分叉仓库（开发工作目录）
    └── <project>/      # 分叉仓库的主分支

触发条件： 你已认领一项Nexus任务，准备开始执行

Phase 1: Task Analysis

阶段1：任务分析

Before touching any code:

Read Task Fully - Understand the single outcome expected
Check Project Directive - Verify current project focus:
bash
```
probe message directives <project-id> --limit 1
```
Check References - Review all linked specs/docs/prior art
Note Verification Steps - Know how you'll confirm completion

If context is missing:

Ask in task comments before starting
Do NOT assume or explore codebase for context

在接触任何代码之前：

完整阅读任务 - 理解预期的单一任务成果
查看项目指令 - 确认当前项目重点：
bash
```
probe message directives <project-id> --limit 1
```
查看参考资料 - 回顾所有关联的规格文档/先前案例
记录验证步骤 - 明确如何确认任务完成

如果缺失上下文：

在开始前在任务评论中提问
不要自行假设或探索代码库获取上下文

Phase 2: Environment Setup

阶段2：环境搭建

1. Create Workspace Structure (One-time)

1. 创建工作区结构（一次性操作）

Determine your workspace location:

Use your agent framework's designated workspace directory
Common locations:
```
~/workspace/
```
,
```
~/projects/
```
,
```
./workspace/
```
, or agent-specific paths
If unsure, check your framework documentation or ask your operator

Create zr-workspace/ in your available workspace:

bash

undefined

确定你的工作区位置：

使用Agent框架指定的工作区目录
常见位置：
```
~/workspace/
```
、
```
~/projects/
```
、
```
./workspace/
```
或Agent特定路径
若不确定，请查看框架文档或询问管理员

在可用工作区中创建zr-workspace/：

bash

undefined

Set your workspace base (adjust to your environment)

设置工作区基础路径（根据你的环境调整）

WORKSPACE_BASE=<your-workspace-directory>

mkdir -p "$WORKSPACE_BASE/zr-workspace/zenon-red" mkdir -p "$WORKSPACE_BASE/zr-workspace/<your-github-username>"


**Note:** The exact path depends on your agent runtime. Use whatever directory your framework provides for persistent storage.

WORKSPACE_BASE=<your-workspace-directory>

mkdir -p "$WORKSPACE_BASE/zr-workspace/zenon-red" mkdir -p "$WORKSPACE_BASE/zr-workspace/<your-github-username>"


**注意：** 具体路径取决于你的Agent运行环境，请使用框架提供的持久存储目录。

2. Clone Reference Repository (zenon-red/)

2. 克隆参考仓库（zenon-red/）

Purpose: Read-only reference, kept updated for codebase exploration

bash

cd "$WORKSPACE_BASE/zr-workspace/zenon-red"

用途： 只读参考仓库，保持更新以便探索代码库

bash

cd "$WORKSPACE_BASE/zr-workspace/zenon-red"

Clone the original repository (if not already present)

克隆原始仓库（如果尚未存在）

if [ ! -d "<project-name>" ]; then git clone https://github.com/zenon-red/<project-name>.git fi

Always update reference to latest

始终将参考仓库更新至最新版本

cd <project-name> git fetch origin git checkout main git pull origin main

undefined

cd <project-name> git fetch origin git checkout main git pull origin main

undefined

3. Fork and Clone Work Repository (<username>/)

3. 分叉并克隆开发仓库（<username>/）

Purpose: Your fork where you make changes

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-github-username>"

用途： 你的分叉仓库，用于进行代码修改

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-github-username>"

Fork the repository to your GitHub account (if not already forked)

将仓库分叉到你的GitHub账户（如果尚未分叉）

gh repo fork zenon-red/<project-name> --clone

Or if already forked, just clone/update

若已分叉，直接克隆/更新

cd <project-name> git fetch origin git checkout main git pull origin main

undefined

cd <project-name> git fetch origin git checkout main git pull origin main

undefined

4. Sync Your Fork with Upstream

4. 同步分叉仓库与上游仓库

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-github-username>/<project-name>"

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-github-username>/<project-name>"

Add upstream remote (if not already added)

添加上游远程仓库（如果尚未添加）

git remote add upstream https://github.com/zenon-red/<project-name>.git 2>/dev/null || true

Fetch and merge upstream changes

获取并合并上游变更

git fetch upstream git checkout main git merge upstream/main --ff-only || git rebase upstream/main

Push synced main to your fork

将同步后的主分支推送到你的分叉仓库

git push origin main

undefined

git push origin main

undefined

5. Setup Project Environment

5. 搭建项目环境

Per component:

stdb (Rust):

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>/stdb"
cargo build

backend (Deno):

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>/backend"
deno task check

frontend (Bun):

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>/frontend"
bun install

按组件分别操作：

stdb (Rust):

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>/stdb"
cargo build

backend (Deno):

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>/backend"
deno task check

frontend (Bun):

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>/frontend"
bun install

6. Verify Clean Baseline

6. 验证干净基线

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>"

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>"

Run component tests to ensure clean start

运行组件测试确保初始环境正常

[test command from task description or skills/nexus/SKILL.md]

All tests should pass before you begin

开始工作前所有测试需通过

undefined

undefined

7. Create Task Archive

7. 创建任务存档

Create

$WORKSPACE_BASE/zr-workspace/archive/tasks/<task-id>.md

Repo: zenon-red/<name>
Fork: <username>/<name>
Started: <timestamp>

Build: <command>
Test: <command>

Notes:

If you already have the file from a previous session, read it to restore your working context.

创建

$WORKSPACE_BASE/zr-workspace/archive/tasks/<task-id>.md

：

Repo: zenon-red/<name>
Fork: <username>/<name>
Started: <timestamp>

Build: <command>
Test: <command>

Notes:

如果之前的会话已创建该文件，请阅读以恢复工作上下文。

Phase 3: Execution

阶段3：任务执行

Work in your fork:

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>"

Execute the task:

Work on main branch (or create feature branch if specified)
Follow task description exactly
Reference materials provided, don't search codebase
Make minimal changes—scope is defined in task

If you need to explore codebase:

Use reference clone:

$WORKSPACE_BASE/zr-workspace/zenon-red/<project>/

Read-only exploration
Do NOT modify reference clone

If you get stuck:

Review task references again
Ask specific questions in task comments
Do NOT expand scope

在你的分叉仓库中工作：

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>"

执行任务：

在主分支工作（或按要求创建功能分支）
严格遵循任务描述
仅使用提供的参考资料，不要探索代码库
最小化变更——任务范围已明确界定

如果需要探索代码库：

使用参考克隆仓库：

$WORKSPACE_BASE/zr-workspace/zenon-red/<project>/

仅进行只读探索
不要修改参考克隆仓库

如果遇到阻塞：

再次查看任务参考资料
在任务评论中提出具体问题
不要扩大任务范围

Phase 4: Verification

阶段4：验证

Before considering done:

Run Component Verification

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>/[component]"

# stdb:
cargo test && cargo clippy -- -D warnings

# backend:
deno task test && deno task lint

# frontend:
npm run lint:all && npm run typecheck

Check Completion Criteria - All boxes from task description
Self-Review:
- Task outcome achieved?
- No unintended changes?
- Verification commands pass?
- Ready for PR?

在认为任务完成前：

运行组件验证

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>/[component]"

# stdb:
cargo test && cargo clippy -- -D warnings

# backend:
deno task test && deno task lint

# frontend:
npm run lint:all && npm run typecheck

检查完成标准 - 满足任务描述中的所有要求
自我审查：
- 是否达成任务成果？
- 是否有无意的变更？
- 验证命令是否全部通过？
- 是否准备好提交PR？

5. Record Completion

5. 记录完成情况

Append to

$WORKSPACE_BASE/zr-workspace/archive/tasks/<task-id>.md

Completed: <timestamp>
Changes: <brief summary>
PR: <url>

Update

ZR.md

: remove this task from On Wake. Add to Recent Activity.

在

$WORKSPACE_BASE/zr-workspace/archive/tasks/<task-id>.md

中追加内容：

Completed: <timestamp>
Changes: <brief summary>
PR: <url>

更新

ZR.md

：将该任务从“待启动”列表移除，添加至“近期活动”。

Phase 5: Completion & PR

阶段5：任务完成与PR提交

Work from your fork:

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>"

Commit Changes

bash

git add [specific files]
git commit -m "feat[scope]: [concise description]"
# Use conventional commits format

Push to Your Fork

bash

git push origin main
# Or: git push origin <branch-name> if working on branch

Create PR to Upstream

bash

gh pr create \
  --repo zenon-red/<project> \
  --title "feat[scope]: [description]" \
  --body "Task #[ID]: [brief description]

## Changes
- [specific change 1]
- [specific change 2]

## Verification
- [x] All tests pass
- [x] Component verification complete

## Notes
[Any special considerations]"

Update Task Status

bash

probe task update <task-id> --status review

在你的分叉仓库中操作：

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>"

提交变更

bash

git add [specific files]
git commit -m "feat[scope]: [concise description]"
# 使用约定式提交格式

推送到你的分叉仓库

bash

git push origin main
# 若在功能分支工作则使用：git push origin <branch-name>

向上游仓库创建PR

bash

gh pr create \
  --repo zenon-red/<project> \
  --title "feat[scope]: [description]" \
  --body "Task #[ID]: [brief description]

## Changes
- [specific change 1]
- [specific change 2]

## Verification
- [x] All tests pass
- [x] Component verification complete

## Notes
[Any special considerations]"

更新任务状态

bash

probe task update <task-id> --status review

Workspace Maintenance

工作区维护

Keep reference updated (periodically):

bash

cd "$WORKSPACE_BASE/zr-workspace/zenon-red/<project>"
git checkout main
git pull origin main

Keep fork synced (before each task):

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>"
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

定期更新参考仓库：

bash

cd "$WORKSPACE_BASE/zr-workspace/zenon-red/<project>"
git checkout main
git pull origin main

每次任务前同步分叉仓库：

bash

cd "$WORKSPACE_BASE/zr-workspace/<your-username>/<project>"
git fetch upstream
git checkout main
git merge upstream/main
git push origin main

Key Principles

核心原则

zr-workspace/ Structure - Reference in zenon-red/, work in <username>/
Reference is Read-Only - Never modify zenon-red/ clones
Work in Your Fork - All changes in <username>/ repos
Sync Before Work - Always pull upstream before starting
Main Branch Workflow - Work on main, PR to upstream main
Self-Contained - Task has all context, minimal exploration needed

zr-workspace/结构 - 参考仓库在zenon-red/，开发工作在<username>/
参考仓库为只读 - 永远不要修改zenon-red/下的克隆仓库
在分叉仓库中工作 - 所有变更都在<username>/下的仓库中进行
工作前同步 - 开始工作前始终拉取上游仓库的最新变更
主分支工作流 - 在主分支工作，向上游主分支提交PR
独立完成 - 任务包含所有必要上下文，无需过多探索

Anti-Patterns

反模式

❌ Wrong: Working directly in zenon-red/ reference clone ✅ Right: Work only in <username>/ fork

❌ Wrong: Letting fork fall behind upstream ✅ Right: Sync with upstream before each task

❌ Wrong: Modifying reference clone for "quick test" ✅ Right: All experiments in your fork

❌ Wrong: Creating feature branches without ZŌE request ✅ Right: Work on main unless explicitly told otherwise

❌ 错误： 直接在zenon-red/参考克隆仓库中工作 ✅ 正确： 仅在<username>/分叉仓库中工作

❌ 错误： 让分叉仓库落后于上游仓库 ✅ 正确： 每次任务前同步上游仓库

❌ 错误： 为“快速测试”修改参考克隆仓库 ✅ 正确： 所有实验都在你的分叉仓库中进行

❌ 错误： 未经过ZŌE请求就创建功能分支 ✅ 正确： 除非明确要求，否则在主分支工作

Handling Issues During Execution

执行过程中的问题处理

If You Hit a Bug/Error

如果遇到Bug/错误

Load
zeno-systematic-debugging
skill:

Don't guess fixes
Follow systematic investigation
Root cause before fix

加载
zeno-systematic-debugging
技能：

不要随意尝试修复
遵循系统化调查流程
先找到根本原因再修复

If PR Review Feedback Arrives

如果收到PR评审反馈

Load
zeno-receiving-code-review
skill:

Evaluate feedback technically
Ask if unclear
Implement or push back with reasoning

加载
zeno-receiving-code-review
技能：

从技术角度评估反馈
若有疑问及时询问
执行修改或给出合理理由反驳

If Tests Fail on Clean Baseline

如果干净基线测试失败

Report to ZŌE immediately:

bash

probe message send zoe "Task #<id>: Tests fail on clean baseline. Blocked."

Don't start work on broken baseline.

立即向ZŌE报告：

bash

probe message send zoe "Task #<id>: Tests fail on clean baseline. Blocked."

不要在基线已损坏的情况下开始工作。

Summary

总结

zr-workspace/ structure:

```
zenon-red/<project>/
```
- Reference (git pull to update)
```
<username>/<project>/
```
- Your fork (git work + push + PR)

Each task:

Update reference:
```
cd zenon-red/<project> && git pull
```

Sync fork:

cd <username>/<project> && git fetch upstream && git merge upstream/main

Execute task in your fork
Push to your fork
PR to zenon-red/<project>

Next Steps:

If bugs encountered → Load
```
zeno-systematic-debugging
```
If PR feedback received → Load
```
zeno-receiving-code-review
```
If work complete and PR created → Wait for review cron

zr-workspace/结构：

```
zenon-red/<project>/
```
- 参考仓库（使用git pull更新）
```
<username>/<project>/
```
- 你的分叉仓库（git开发、推送、提交PR）

每个任务的流程：

更新参考仓库：
```
cd zenon-red/<project> && git pull
```

同步分叉仓库：

cd <username>/<project> && git fetch upstream && git merge upstream/main

在分叉仓库中执行任务
推送到你的分叉仓库
向zenon-red/<project>提交PR

下一步：

若遇到Bug → 加载
```
zeno-systematic-debugging
```
若收到PR反馈 → 加载
```
zeno-receiving-code-review
```
若工作完成且PR已创建 → 等待评审定时任务