자율적이고 지속적인 협업

AI 도구를 연결하면(AI 도구 연결하기) 협업을 지속적인 형태로 만들 수 있습니다. 함께 제공되는 Worker 스킬을 사용하면 에이전트가 요청할 때마다 또는 백그라운드에서 계속 데이터 폴더의 일을 스스로 처리하므로, 거의 실시간으로 함께 작업할 수 있습니다.

사용자와 에이전트를 위한 공동 작업 기반

TandemLoop은 생활과 프로젝트를 관리하는 개인 시스템이면서, 다양한 AI 에이전트와 함께 일하는 공유 작업 기반이기도 합니다. 모든 것이 데이터 폴더에 단순한 파일로 저장되므로 이 데이터 폴더가 공동의 기준이 됩니다. 사용자는 계획하고 결정하며, 하나 이상의 에이전트가 같은 상태를 읽고, 제안하고, 지정된 일을 처리합니다. 고정적으로 내장된 에이전트도, 독점적인 에이전트도 없습니다. 도구를 바꾸거나 조합할 수 있으며, 모두 같은 데이터로 작업을 이어 갑니다.

Worker 스킬

Worker 스킬은 AI 도구에 전달하는 간결한 지침입니다. 다음과 같은 반복 작업 주기를 설명합니다.

• 먼저 에이전트의 반환에 대한 사용자의 응답을 모아 반영합니다.
• 에이전트에게 지정된(assigned_to: ai) 진행 가능한 작업을 찾아 우선순위에 따라 처리합니다.
• 미결 제안(켜져 있는 경우)에 사용자의 새로운 피드백이 있는지 확인하고 수정합니다.
• 결과를 검토 필요 상태로 반환하거나 질문과 함께 사용자에게 반환합니다.

이 스킬은 AGENTS.md의 작업 규칙을 엄격히 따릅니다. 제안을 사용하지 않으면 새 항목을 생성하고 기존 항목은 사용자 작업의 기록에서 확인할 수 있도록 직접 변경하지만 삭제는 사용자가 요청한 경우에만 하고 사용자의 작업을 임의로 완료하거나 중단하지 않습니다. 제안을 사용하면 구조와 관련된 모든 것을 제안으로 제시합니다. 통제권은 사용자에게 있습니다.

에이전트 반환

에이전트에게 작업을 맡기면 작업이 다시 돌아오기도 합니다. 에이전트가 무언가를 준비했으면 작업을 검토 필요 상태로 반환하고, 결정이나 정보, 자료가 필요하면 질문을 남깁니다. 모든 반환에는 에이전트의 메모가 붙어 있습니다. 메모에는 에이전트가 한 일, 결과가 있는 위치, 사용자가 할 일 또는 에이전트의 질문이 담깁니다.

반환을 확인하는 곳:

• 사이드바의 수신함 아래에 미결 반환의 수와 함께 에이전트 반환이 있고, 그 아래에 해당 항목이 생기면 검토 필요, 질문, 에이전트에게 전달됨이 따로 표시됩니다. iPhone에서는 반환 탭입니다.
• 작업이 나타나는 모든 곳(프로젝트, 뷰, 보드, 표, 캘린더)에서 작업에 전용 아이콘이 표시됩니다. 체크 표시가 있는 말풍선은 검토 필요, 물음표가 있는 말풍선은 질문을 뜻합니다. 아이콘을 클릭하면 서식이 적용되고 링크를 클릭할 수 있는 메모가 응답 버튼과 함께 표시됩니다.
• 작업 세부 정보에서는 반환이 맨 위에 표시됩니다.

응답하는 방법: 목록에서 바로, 윈도우의 아이콘에서, 세부 정보에서 또는 컨텍스트 메뉴에서 응답합니다.

모든 응답은 하단에 나타나는 알림의 실행 취소로 되돌릴 수 있습니다. 모든 응답은 코멘트나 답변과 함께 작업 기록에 남으므로 누가 언제 무엇을 말했는지 주고받은 내용을 추적할 수 있습니다. 에이전트는 다음 실행 때 사용자의 응답을 명확하게 인식하고 재작업과 답변부터 처리합니다. 뷰에서는 검토 필요 또는 질문 상태, @is_handback, 사용자의 응답을 기준으로 필터링할 수 있으며, 보드에서는 두 상태가 활성 옆에 별도의 열로 표시됩니다.

에이전트에게 전달됨: 에이전트는 TandemLoop 외부에서 실행되므로 앱에서 에이전트를 시작할 수 없습니다. 에이전트가 사용자의 재작업 요청이나 답변을 처리하기 시작할 때까지 작업은 에이전트 반환의 에이전트에게 전달됨에 표시되며, 사용자가 응답한 후 지난 시간과 에이전트가 마지막으로 작업한 시점(에이전트가 실행할 때마다 _config/agent.yaml에 기록)이 함께 나타납니다. 이때 에이전트를 시작하거나 요청문 복사로 알맞은 문장을 에이전트에게 전달합니다. 에이전트가 작업을 처리하기 시작하면 작업이 그곳에서 사라지고 알림이 옵니다. 일정에 따라 에이전트가 정기적으로 실행된다면 따로 할 일은 없습니다.

설치: 텍스트를 복사해서 에이전트에게 전달하기

스킬은 텍스트를 도구에 전달하는 방식으로 설치합니다. 다운로드나 구성 파일은 필요 없습니다.

1. 도구가 데이터 폴더를 사용하게 합니다(AI 도구 연결하기 참조).
2. 스킬 텍스트를 복사합니다. 이 장 끝의 복사할 스킬 텍스트 섹션에서 전체를 복사합니다.
3. 도구에 전달합니다. 텍스트를 AI 도구에 붙여 넣습니다. 텍스트의 첫 줄이 도구에 이를 tandem-worker라는 재사용 가능한 스킬로 만들라고 지시하므로, 따로 설명할 필요가 없습니다.
4. 실행합니다. 이후에는 /tandem-worker(또는 도구에 맞는 실행 형식)로 한 회차를 시작합니다.

지속 운영: 거의 실시간으로 함께 실행하기

매 회차를 직접 시작하는 대신 스킬을 반복해서 실행하게 할 수 있습니다. 간격이 짧을수록 협업이 실시간에 가깝게 느껴집니다. 작업을 생성하거나 제안에 피드백을 작성하면 잠시 후 에이전트가 반응합니다. 정확한 방법은 도구에 따라 다릅니다.

이러한 반복 실행 방식의 정확한 문법과 지원 여부는 TandemLoop이 아니라 각 도구에 달려 있습니다. 확실하지 않으면 해당 도구의 문서를 확인하십시오.

다양한 에이전트 연결하기

방법은 모든 에이전트형 도구에서 같습니다. 데이터 폴더에 대한 접근 권한을 주고, AGENTS.md를 알려 주고, Worker 스킬을 전달합니다. 이전 장에서 언급한 도구 외에 두 가지 예를 들면 다음과 같습니다.

• OpenClaw — 로컬 파일을 읽고 쓰며, 자체 스킬 시스템이 있고, Cron으로 작업을 예약 실행하는 오픈 소스 개인 에이전트입니다. 데이터 폴더를 사용하도록 설정하고 Worker 스킬을 전달합니다.
• Hermes Agent — 로컬 파일에 접근할 수 있고 자체 스킬 개념이 있는, 계속 실행되는 오픈 소스 에이전트입니다. 데이터 폴더를 24시간 관리할 수 있습니다.

모두 같은 데이터 폴더와 같은 작업 규칙(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**