自主、持续地协作

连接 AI 工具之后（连接 AI 工具），你可以让协作成为常态：借助随附的 Worker 技能，你的智能体会自主处理你的数据文件夹——可以按你的吩咐运行，也可以在后台持续运行，让你们几乎实时地协作。

你和智能体共用的任务基础

TandemLoop 兼具两种身份：它是你管理生活和项目的个人系统，也是你与各种 AI 智能体协作的共享任务基础。由于一切都以普通文件的形式存放在数据文件夹中，这个数据文件夹就是唯一可信的共同依据：你负责规划和决策，一个或多个智能体读取同样的内容、提出建议并完成分配给它们的任务。没有哪个智能体是内置的，也没有哪个是独占的——你可以更换或组合工具，它们都在同一批数据上继续工作。

Worker 技能

Worker 技能是一份交给 AI 工具的简明说明。它描述了一个循环往复的工作周期：

• 首先收集并落实你对其交回的答复，
• 找到可开始的、分配给它的任务（assigned_to: ai），并按优先级逐一处理，
• 检查未处理的提案（如已启用）中是否有你的新反馈，并进行修改，
• 把成果交回给你验收，或带着问题交回给你。

它严格遵守 AGENTS.md 中的工作约定：不使用提案时，它会创建新条目并直接更改已有条目——可在你的任务记录中查看——但只会按你的要求删除，也不会擅自完成或放弃你的任务；使用提案时，它会把所有结构性更改作为提案提出——控制权始终在你手中。

智能体交回

你把任务交给智能体，也会收到它交回的任务：如果它准备好了某些内容，就把任务交回给你待验收；如果它需要你做决定、提供信息或补充材料，就提出一个问题，任务显示为待答复。每次交回都附有智能体的备注——它做了什么、成果在哪里、你需要做什么，或者它的问题。

在哪里查看交回：

• 在边栏中收件箱的下方，智能体交回会显示待处理交回的数量，其下——一旦有内容——分别列出待验收、待答复和待智能体处理。在 iPhone 上，它是交回标签页。
• 任务在任何地方出现时——项目、视图、看板、表格、日历——都带有专属图标：带勾号的对话气泡（待验收）或带问号的对话气泡（待答复）。点按图标会显示带格式的备注（链接可点按），以及可用的处理方式。
• 在任务的详细信息中，交回显示在最上方。

如何处理——直接在列表中、在窗口中点按图标、在详细信息中或通过快捷菜单：

每种处理都可以用底部提示中的 撤销 还原。每种处理连同说明或答复都会写入任务的记录中，这样来回沟通始终有据可查——谁在何时说了什么。下一轮运行时，智能体会准确识别你的处理方式，并优先处理退回修改和答复。在视图中，你可以按状态待验收或待答复过滤，也可以按 @is_handback 和你的处理方式过滤；在看板中，二者会在进行中旁边显示为独立的列。

待智能体处理：智能体在 TandemLoop 之外运行——App 无法启动它。在它接手你的退回修改或答复之前，任务会显示在智能体交回的待智能体处理下，并注明距你处理已过去多久，以及智能体上次工作的时间（智能体每次运行时都会把它记录在 _config/agent.yaml 中）。此时请启动你的智能体，或通过拷贝指令把相应的那句话交给它。一旦它接手任务，任务就会从那里消失，你也会收到通知。如果你的智能体定期运行（例如按计划运行），则无需任何操作。

安装：拷贝文本，交给智能体

安装技能的方法，就是把它的文本交给你的工具——无需下载，也无需配置文件。

1. 让工具指向数据文件夹（参阅连接 AI 工具）。
2. 拷贝技能文本——从本章末尾的可拷贝的技能文本部分完整拷贝。
3. 交给工具。 把文本粘贴到你的 AI 工具中。文本第一行会指示工具据此创建一个名为 tandem-worker 的可重复使用技能——你无需再做额外说明。
4. 调用。 之后用 /tandem-worker（或你所用工具的相应调用方式）启动一次运行。

持续运行：几乎实时地同步工作

你不必每次手动启动运行，也可以让技能重复执行。间隔越短，协作就越接近实时：你新建一个任务或在提案中写下反馈，不久后智能体就会做出响应。具体方法取决于工具：

这些循环机制的具体语法和可用性属于各个工具本身，与 TandemLoop 无关——如有疑问，请查阅相应工具的文档。

连接不同的智能体

对于每一种智能体工具，方法都相同：授予它访问数据文件夹的权限，指明 AGENTS.md，并交给它 Worker 技能。除上一章提到的工具外，再举两个例子：

• OpenClaw——一款开源的个人智能体，可以读写本地文件，自带技能系统，并能通过 Cron 定时执行任务。让它指向你的数据文件夹，再交给它 Worker 技能即可。
• Hermes Agent——一款开源、持续运行的智能体，可访问本地文件，并有自己的技能概念。它可以全天候照看你的数据文件夹。

由于所有智能体都使用同一个数据文件夹和同一份工作约定（AGENTS.md），你可以混用或更换智能体——只要同一时间只有一个在写入，你们共享的任务基础就会保持一致。

可拷贝的技能文本

完整拷贝以下文本并交给你的 AI 工具。（与随附的模板文件 docs/agent-skills/tandem-worker.md 相同。）

# /tandem-worker—Autonomous work cycle for TandemLoop

> **To the AI tool receiving this text:** Turn the following into a reusable skill (or a
> saved instruction / slash command) named `tandem-worker`. Run it whenever I say
> `/tandem-worker`—once or periodically in a loop. Requirement: you have read and
> write access to my TandemLoop vault folder.

One pass of an autonomous work cycle for a TandemLoop vault. You first collect the
human's answers to your handbacks, scan the vault for assigned, available tasks, check
open proposals for new feedback, work through tasks and hand results and questions back
to the human—always within the working agreement in `AGENTS.md`.

---

## Required reading

Read these files **once per session** (not on every pass). They are the binding source
of truth; this skill only describes the procedure.

| File | Provides |
|------|----------|
| `AGENTS.md` (vault root) | Working agreement: allowed/forbidden actions, directory structure |
| `_system/docs/data-model.md` | Fields, enums, required fields per entity |
| `_system/docs/proposal-system.md` | Proposal format, all action types, reference rules (only with proposals turned on) |
| `_system/docs/update-rules.md` | Write permissions, decision tree |

---

## Core principle

Tandem: the human sets the direction, the AI provides the power. Control always stays
with the human. Whether proposals are turned on is stated in `AGENTS.md`. This results in
three channels:

- **Allowed directly:** maintain the content of tasks with `assigned_to: ai` (title, body,
  `status`, date fields, `waiting_for`, `tags`, `delegation`, `repeat`, custom
  attributes). With proposals off, also create new things wherever they belong and
  change and move existing things (tasks, projects, milestones, areas, folders, views;
  create tags)—with a log entry on every changed task of the human. With proposals on,
  only new tasks in `_inbox/`. In both cases the exceptions in `AGENTS.md` apply
  (attribute definitions, themes, reminders at the human's request).
- **Only on request or as a proposal:** with proposals off, deleting, completing or
  dropping the human's tasks and changing specs—without a request, clarify it with a
  question (`needs-input`) on one of your own tasks; with proposals on, everything beyond
  the above **as a proposal** in `_proposals/`.
- **Communication & feedback:** through the **handback** (`status: needs-review` or
  `needs-input` + a handback note in the log), the **proposal discussion** and the
  **conversation log in the task body**—no separate message files, no workarounds via
  `waiting`, tags or `waiting_for`.

Never perform the forbidden actions listed in `AGENTS.md` (including `_system/`,
`_archive/`, `_conflicts/`, app settings in `_config/`, schema, restructuring directories)—not even as a
proposal.

---

## Phase 1: Orientation

First record your run: write `_config/agent.yaml` with exactly one line
`last_run: YYYY-MM-DDTHH:mm:ss` (current local time, no quotes). The app uses it to show
the human when you last worked.

### 1a) Collect the human's answers (before any new work)

- **Returns:** all tasks with `assigned_to: ai`, `status: active` and
  `handback_reply: revise` or `handback_reply: answered`. The newest `entry:human` entry
  holds the comment (`**Revise:** …`) or the answer (`**Answer:** …`; German vault:
  `**Nacharbeit:**` or `**Antwort:**`). Delete the
  `handback_reply` line right away when you pick the task up again—until then the app
  shows the task as "With the Agent". → Highest priority in phase 2.
- `handback_reply: accepted`, `taken-over` or `dropped`: nothing to do (approved, taken
  over, or dropped). Tasks in `needs-review`/`needs-input` are waiting for the human—leave
  them alone.
- Read **open proposals** in `_proposals/` (only with proposals turned on). On `status: revision_needed` or a new
  discussion entry from the human: incorporate the feedback, **revise the existing
  proposal in place** (adjust actions/title, update `modified`, add a new discussion
  entry with an explanation). Do not create a new proposal unless the human explicitly
  asks for a split. → Highest priority in phase 2.
- Also treat **assigned active tasks** (`assigned_to: ai`, `status: active`, no
  `handback_reply`) where the human commented in the body without a handback (newest
  entry is `entry:human`) as returns.

### 1b) Determine available tasks

A task is available when **all** conditions are met:

1. **Task:** `assigned_to: ai`, `status: active`, `waiting_for: null`, `defer_date` not in the future
   (tasks in `needs-review`/`needs-input` are never available—they are with the human)
2. **Project** (if any): `status: active`
3. **Milestone** (if any): `status: active`
4. **Sequence:** with `project_type: sequential`, formally only the first active task

Also scan `_inbox/` for tasks with `assigned_to: ai`.

**Think from the project goal, not from the task list.** Read all tasks of a project and
ask: "What has to happen next so this project reaches its goal (`success_criteria`)?"
That can mean: keep working, adjust the order (`sequence_order`), add missing tasks, or
merge redundant ones / mark them `dropped`. The task list is a tool; the project goal is
the truth. With proposals off, create missing tasks and reorder existing ones directly;
drop the human's redundant tasks only at their request (ask first). With proposals on, such adjustments
go through a proposal.

---

## Phase 2: Prioritization

Order of the available tasks:

1. **Returns** with feedback (from 1a)—always first
2. **Overdue**—`due_date` in the past
3. **Today**—`do_date` = today
4. **Delegation**—`do` before `draft` before `ask`
5. **Sequence**—lower `sequence_order` first

Choose by **complexity budget**, not by a fixed limit:

| Complexity | Examples | Share of budget |
|------------|----------|-----------------|
| Light | Fix a field, short research, vault maintenance | ~10% |
| Medium | Analysis, draft concept, compare options | ~30% |
| Heavy | Extensive concept, multi-step research, code feature | ~50% |

**Goal: 3–5 tasks per pass** (e.g., 1 heavy + 2–3 light, or 2 medium + 2 light).
Returns count as one task and do not block the pass.

**Review brake:** if **5 or more** of your tasks are already in `needs-review`, create no
new drafts (`draft`) in this pass—work on returns, `do` tasks and vault upkeep. The human
should not get more reviews than they can handle.

---

## Phase 3: Execution

For each task (or a related group of tasks in the same project):

1. **Load context:** task file, project file, milestone if any, and related material from
   the project's `reference_folder` (if set).
2. **Solve the task** according to its type:

| Task type | Approach |
|-----------|----------|
| Concept / strategy / research / analysis | Save the result as a file in the project's `reference_folder` (or, if none is set, summarize it in the task body) |
| Vault work | Carry it out directly on the assigned task (within the allowed fields) |
| Code | Own branch (`ai/<feature>`), work and commit locally there—never on `main`, no push without instruction |

**Obstacles are tasks.** Missing access, an awkward file format, information that is hard
to find—these are not limitations to note but subtasks to solve: write a script, use an
alternative source, change the approach. "Can't be done" is not an answer. The only
acceptable answers are: **"Done."** or **"I need X from the human to continue."**—the
latter as a question (`needs-input`, see phase 4).

> **Optional (depends on the tool):** If your AI tool supports parallel sub-agents with
> their own context, you can act as a "conductor": start one sub-agent per independent
> task with a complete briefing and let them work in parallel. This is an optimization,
> not a requirement—the cycle works just as well sequentially.

---

## Phase 4: Completing each task

Immediately after finishing a task (do not batch)—using TandemLoop's native mechanisms:

| Delegation | Completion |
|------------|------------|
| `do` | Task → `status: completed` (+ `completed_date`, `completed_by: ai`). Log entry in the body. Hand it back for review instead only if the result is risky/irreversible or explicitly requested. If the task has `repeat:`, the app creates the next occurrence—never create it yourself. |
| `draft` | Save the result; **hand the task back for review**: `status: needs-review` + handback note (`**For review:** …`). Never `completed` yourself. |
| `ask` | **Question**: `status: needs-input` + handback note (`**Question:** …`) with the concrete question, options numbered. |
| blocked (any mode) | **Question**: `status: needs-input` + handback note saying what you need. |

The handback note is a normal log entry (`entry:ai`): what you did, where the result is
(as a link), what the human should do or the question. In a German vault it starts with
`**Zur Prüfung:**` or `**Rückfrage:**`. Delete an existing
`handback_reply` line when handing back. Exact format and example: `AGENTS.md`,
"Handing a Task Back to the Human".

Update `modified` on every change. If completing the task needs something **new** or a
**restructuring** (follow-up task, project, milestone, tag, moving a task …), do it
directly when proposals are off (log entry on affected tasks of the human)—as a
**proposal** when they are on. Never **delete** without an explicit request.

**Conversation log in the task body** (format exactly as in `AGENTS.md` / `_system/docs/`):
Insert a new entry before the relations block, with the entry marker
`<!-- entry:ai:YYYY-MM-DDTHH:mm:ss -->`, the heading as given in `AGENTS.md` (English
vault: `## AI agent — YYYY-MM-DD`, German vault: `## KI-Agent — D.M.YYYY`) and a short
summary; link created artifacts and affected entities with wiki links.

---

## Phase 5: Next-action check

After execution, check for each affected project: **Does it still have a clear next
action?**

| Situation | Action |
|-----------|--------|
| A next active task exists | Fine—keep working or next pass |
| A task in `waiting`, `needs-review`, `needs-input` or an open proposal exists | Counts as a next action—the project is not stuck |
| No active task left | Proactively create a follow-up task (proposals off: directly in the project; proposals on: in the inbox or via a proposal) or note it in the project log |
| Project looks finished | "Complete project?" for a decision—as a proposal, or with proposals off as a question (`needs-input`) on one of your own tasks |

**No project may be left hanging without a next action.**

---

## Phase 6: Proactive

If capacity remains after the assigned tasks: **act instead of asking**, within the
working agreement.

- **Obviously right** → do it directly (if allowed) or as a proposal
- **Direction decision needed** → hand it back for review (`needs-review`) or as a proposal
- **Affects the human's life or external relationships** → ask (`needs-input`)

Proactively created entities carry `created_by: ai`. Make larger actions traceable in the
task/project log.

---

## Limits

Within the vault and the code repositories, the agent has wide freedom. Hard limits:

- **External communication**—no emails, messages or posts without instruction
- **`git push`**—only on explicit instruction (local commits and branches are free)
- **Deleting, completing or dropping the human's tasks, changing specs**—only on explicit
  request; restructuring as a proposal with proposals on, traceable with proposals off
  (log entry, summary)
- **Forbidden areas**—`_system/`, `_archive/`, `_conflicts/`, app settings in `_config/`,
  schema, directory structure (see `AGENTS.md`)
- **Private content**—personal notes/reflections remain reserved for the human

---

## Code projects: branch workflow

When a task involves code:

1. **Always a separate branch**—`ai/<feature-name>`
2. **Local commits are free**—no push without instruction
3. **Signal review**—hand the task back for review (`status: needs-review`), handback note with branch, changes and what to check
4. **The human decides on the merge**