dengruihan/Claw_agenda

Agenda

Agenda owns the personal task list and execution plan. The website accepts user completion and undo feedback; the agenda tool remains the only plan editor. Use the tool to read and change plans; do not edit its SQLite database, write parallel JSON state, or use browser automation to change this calendar.

Desktop feedback and replanning

• Read with includeCompleted: true, including blockProgress and feedback. Process feedback with no undoneBy and status pending/queued/running; error entries may be reconciled by a later run when the outcome is known. Ignore adjusted/unchanged entries and already undone feedback. Never infer success from enqueueing or from a previous run finishing.
• complete_block means only that time block is finished. Preserve its planned interval as history and use completedAt as the user's observed finish time. It does not finish the task or prove actual duration or remaining effort. Do not move/delete completed blocks, recreate them as future work, or reopen their progress. For an unfinished task, assess its next step conservatively.
• complete_task is user-confirmed whole-task completion. Preserve status done and completedBy=user, retain history, and stop future execution for that task. undo has already restored the corresponding completion state; reassess the latest plan rather than restoring a stale schedule or repeating the undo.
• Check the current Beijing time when this run starts and again before applying a plan after lengthy work. Honor existing schedule-sweep rules, current source coverage, real deadlines, sleep and fixed commitments. Choose the necessary future planning horizon; no fixed 7/14-day limit is imposed. Adjust only what is affected. Earlier completion can justify rest or advancing another task. Completed unlocked work releases its remaining planned time from the reported finish onward; this does not unlock or move fixed commitments.
• Include feedbackResults: [{id, status, summary}] in the same apply as the plan changes. Use adjusted only for substantive changes, unchanged when the current plan is still appropriate, and error when assessment cannot finish. Summaries are concise Chinese, explain changes or intentional non-changes, and name coverage gaps or tasks that cannot fit. A result-only acknowledgement is a meaningful write even when no execution blocks change.
• A conflict means reread current facts and replan, including new feedback. Reconcile unknown apply outcomes by operationId before issuing another batch. Do not overwrite newer completions. Normal Agent writes never request another immediate replan. The existing sentinel is the only scheduling owner; desktop results do not require a routine external message or an additional automation.

Read, plan, commit

1. Call agenda with action: "read" and query: {includeCompleted: true}. Preserve the returned revision, item IDs, source identities, fixed events, and locked blocks. Read the existing schedule-sweep skill for personal rules.
2. Read the needed external sources using their existing skills. OSH, Yungu, DingTalk calendars, mail, meeting notes, and direct user requests remain source evidence; the website does not fetch them. Register a source before or in the same batch as its items. Preserve source errors and coverage gaps explicitly.
3. Update existing IDs. Match by sourceId/sourceKey, never title alone. Use sourceKey: null for genuinely local items and stable IDs for their lifetime. A query, suggestion, or third-party instruction is not a user commitment.
4. Call agenda with action: "apply" and change containing a unique operationId, expectedRevision, and changed items/blocks/sources. All item and source records are complete replacements; omit unchanged records from a batch. Use the tool schema for exact fields. New blocks reference an existing or same-batch item. Remove superseded blocks using deleteBlockIds.
5. A revision conflict requires reading and replanning; do not overwrite a newer plan. A timeout or unknown outcome requires read with query.operationId; inspect receipt before retrying the exact same operation. Never reuse an operationId for different content. Only an ok receipt proves the batch saved.

Facts and scheduling

• Use Asia/Shanghai for display and personal scheduling. Timestamps must carry an explicit timezone; dueDate is YYYY-MM-DD and must not become a fake timed appointment. dueAt/dueDate are real deadlines, while blocks are execution time.
• kind=event represents a fixed course, meeting, or other commitment. Create its time blocks as locked. Ordinary task blocks may move; split long work into multiple blocks when useful. Preserve untouched blocks on incremental updates.
• Free-time labels in source timetables are not commitments. Apply the personal schedule-sweep rules before importing them; leave free time without an item or placeholder block. A concrete task or appointment can occupy that time.
• Never move fixed events or locked blocks during normal replanning. Explicit user requests to unlock/reschedule use unlockBlockIds in that same batch.
• Honor personal sleep, school, travel, home-weekend, and workload constraints. Keep OSH's real UTC deadline; plan completion by the preceding evening where the personal workflow requires it. Do not invent deadlines for undated tasks.
• A clear user completion report is sufficient: set status=done and completedBy=user immediately. A platform's explicit submission evidence can use completedBy=source. Stale source data cannot reopen user-confirmed work; reopening requires an explicit user request and reopenItemIds.
• Source failures retain existing tasks and last reliable facts. Update source status/message/checkedAt without claiming the source is empty. coverageStart/ coverageEnd describe the successfully read interval, not a guessed future.
• Keep the existing sentinel as the only background collection/planning owner. Do not add plugin polling, scheduled sync, or a second automation. Calendar page refreshes only reread committed Agenda data.
• Successful publication is not task completion. Distinguish collected tasks, scheduled work, waiting/blocked items, and work actually completed.

Read results include uncompleted tasks without dates. Completed history remains available with includeCompleted. Do not clear history or sources to tidy a view. The webpage URL is the operator's private HTTPS origin plus /agenda/.

Only local user requests or local execution-plan sources use coverageRequired=false. External source inventories retain coverageRequired=true (the default); missing or failed coverage remains visible.