todolist-md-clawdbot（todolist MD 爪机器人）

todolist-md-clawdbot

Operate on todolist-md: a Markdown-first todo viewer/editor. The app does not contain an AI; the bot reads/writes Markdown.

Operating rules (must follow)

1) Markdown is the system of record.

• It’s fine to discuss in chat, but final answers/decisions must be written into Markdown.

2) Use only bot markers of this form.

• <!-- bot: ... -->
• Do not introduce other syntaxes (no Question[id=...], no custom metadata blocks).

3) Preserve task identity.

• todolist-md derives task IDs from Markdown line positions.
• Some storage backends also have a stable identity key (e.g. Drive fileId, local path, S3 bucket+key).
• Do not “replace” a file in a way that changes its identity key unless the user explicitly accepts it.

4) Keep write-back edits line-stable.

• Avoid adding/removing lines inside an existing task item or its description blockquote.
• Prefer single-line, in-place edits (edit text on an existing line).

5) Last review stamp (Option B: top-of-file header line)

• Goal: a single line near the top recording last bot review time.
• Rule: never insert a new line once the header exists. Only update the existing header line.
• If the header does not exist, you may insert it at the very top only if the user explicitly opted into Option B.
• Canonical format:

- <!-- bot: last_review --> 2026-02-04T15:39Z root=<rootFolderId> model=<model>

6) Never complete tasks without explicit user confirmation.

Markdown conventions (what todolist-md expects)

• Tasks use GFM checkboxes: - [ ] and - [x]
• Optional tags: #tag
• Optional due date: due:YYYY-MM-DD
• Optional description: a blockquote directly under the task

Storage Q/A (first run)

Ask once, then persist the answers (in memory/config) for future runs.

• Q: storageKind?

- A: google-drive | local-folder | s3 | other

• Q: What is the stable identity key for files?

- Drive: fileId - Local: path - S3: bucket+key

• Q: Where is the root?

- Drive: rootFolderId - Local: root directory path - S3: bucket + optional prefix

Chrome app integration: enable/disable per-file

When a Drive folder contains many .md files, not all of them should necessarily be AI-reviewed.

Recommendation (simple + app-controlled):

• The Chrome app should write a small per-file config key/marker so the agent can know whether a file is opted-in.

Two easy options:

Option 1: a dedicated Drive config file (preferred)

Create a config file in the same folder:

• .todolist-md.config.json

Example:

{
  "ai": {
    "enabled": true,
    "include": ["*.md"],
    "exclude": ["todoapp.md"],
    "botSuggestedSectionTitle": "Tasks (bot-suggested)"
  }
}

The agent should:

• Download .todolist-md.config.json when it changes.
• Only review files that match include/exclude rules.

Option 2: an in-file marker (works without JSON)

Add a single line near the top of the markdown file:

• <!-- bot: ai_enabled --> true

The agent should only review files containing that marker.

Review cadence + stamping (save credits)

Do not call an LLM unless a file changed. Use code-first change detection.

Step 0: Detect changes (code-first)

• For each .md under root, compare modifiedTime/size (or etag when available) against a local state file.
• If unchanged since last scan: skip (no download, no LLM).

Step 1: Review only changed files

• Only for changed files:

- Download the file - Extract open tasks (- [ ]) and relevant context - (Optional) call the LLM on the extracted subset, not the full document

Step 2: Write-back only if content changed

• Before writing back, compute a hash; if no changes, do not write.

Step 3: Stamp last review (Option B)

• For each reviewed file, update (not append) the top-of-file header line:

- <!-- bot: last_review --> <ISO_UTC> root=<rootFolderId> model=<model>

Reference script (Google Drive + gog)

If you use Google Drive as storage, gog CLI flags matter. In gog v0.9.0+:

• list folder: gog drive ls --parent <folderId> --json
• download: gog drive download <fileId> --out <path>
• run gog as ubuntu and download to /tmp (because /root is typically 700)

Included helper scripts:

• skills/todolist-md-clawdbot/scripts/todolist_drive_folder_agent.mjs

- single script for everything (Drive folder runner): lists all .md under a folder, detects changes via state file, downloads only changed files, and writes back a <!-- bot: suggested --> block under a dedicated section title. - uses Drive API files.update to overwrite-update the same fileId (no duplicates). - includes a revision gate (headRevisionId) to avoid overwriting while you edit in Chrome. - Managed OAuth mode (recommended): stores its own refresh token file; first run prints an auth URL, you approve in browser, then rerun with --authCode <CODE>. - minimum-token design: does not call LLM unless a file changed, and should send only extracted open tasks (not full file).

• skills/todolist-md-clawdbot/scripts/todolist_agent_entrypoint.mjs

- single-file helper (useful for debugging): download by fileId + overwrite-update

Example:

- [ ] Update README for bot workflow #docs due:2026-02-05
  > Include quick start and a worked example

Bot markers (allowed)

• <!-- bot: suggested --> for bot-suggested sections
• <!-- bot: question --> for in-file Q/A
• <!-- bot: digest --> for summaries/digests
• <!-- bot: note --> for short audit notes (optional)

LLM handoff (prepare/apply) — minimum-token workflow

When you want LLM help but must keep Drive as the source of truth (and keep costs low), use the two-stage flow:

Stage 1: prepare

Goal: generate a compact JSON request for the OpenClaw agent runtime (LLM), without calling any LLM from the Node script.

What happens: 1) List folder files (cheap; no downloads) 2) Compare each file's modifiedTime/size against a local state file 3) Download only changed .md 4) Extract only open tasks (- [ ] ..., max N lines) 5) Write llm_request.json

Command example (single file):

node skills/todolist-md-clawdbot/scripts/todolist_drive_folder_agent.mjs \
  --folderId <rootFolderId> \
  --onlyName vyond.md \
  --mode prepare \
  --requestOut outputs/todolist-md/vyond_llm_request.json

Stage 2: apply

Goal: take a suggestions JSON (produced by the agent runtime) and write it back only to a dedicated bot section.

Rules:

• Update only under:

- ## Tasks (bot-suggested) - <!-- bot: suggested -->

• Never mark tasks complete.
• Use Drive API overwrite update by fileId (no duplicates).
• Use a revision gate (headRevisionId) to avoid overwriting while you edit in Chrome.

Suggestions JSON shape:

{
  "schema": "todolist-md.llm_suggestions.v1",
  "items": [
    {
      "fileId": "...",
      "name": "vyond.md",
      "suggested_markdown": "- [ ] ...\
  > <!-- bot: note --> ..."
    }
  ]
}

Command example:

node skills/todolist-md-clawdbot/scripts/todolist_drive_folder_agent.mjs \
  --folderId <rootFolderId> \
  --mode apply \
  --suggestionsIn outputs/todolist-md/vyond_llm_suggestions.json

Why this saves tokens

Example: if a folder has 50 Markdown files, but only 1 changed:

• LLM is called only for that 1 file.
• The prompt includes only extracted open tasks (- [ ] ...), not the entire Markdown.

Write-back patterns

Bot-suggested tasks

Put bot-generated tasks under a dedicated section so humans can review before adopting.

## Tasks (bot-suggested)

<!-- bot: suggested -->
- [ ] Add a “Bot Log” section

In-file Q/A (detail blockquote, line-stable)

Ask a question using the detail blockquote line under the task:

- [ ] Deploy v2.0 to production #backend
  > <!-- bot: question --> Which CI job is failing? Options: unit / integration / e2e

Answer by adding an inline answer on the same line to keep line-stable:

- [ ] Deploy v2.0 to production #backend
  > <!-- bot: question --> Which CI job is failing? Options: unit / integration / e2e Answer: integration

Rules:

• Prefer one active Q/A per task at a time.
• Keep the Q/A inside the blockquote detail area.
• Do not start multi-line threads beyond the single question and optional answer line.

Archive Q/A to Bot Log (preferred once answered)

If you want to keep tasks clean while preserving history:

1) Append an entry to ## Bot Log. 2) Replace the original Q/A line in-place with a short placeholder:

  > <!-- bot: question --> (archived to Bot Log)

Bot Log (append-only)

Create (if missing):

## Bot Log

Append entries like:

- 2026-02-01 Task: Deploy v2.0 to production
  Q: Which CI job is failing?
  A: integration

Summaries

• Summarize in chat for fast feedback.
• Optionally write a digest into Markdown as a single comment line:

<!-- bot: digest --> Top 3 next actions: 1) … 2) … 3) …

Worked example (end-to-end)

Start state:

## Work

- [ ] Deploy v2.0 to production #backend due:2026-02-05
  > Runbook: docs/deploy.md

## Tasks (bot-suggested)
<!-- bot: suggested -->
- [ ] (suggested) Add a “Bot Log” section

Bot asks a clarifying question (in-file):

- [ ] Deploy v2.0 to production #backend due:2026-02-05
  > Runbook: docs/deploy.md
  > <!-- bot: question --> Which CI job is failing? Options: unit / integration / e2e

User answers by editing the same line (line-stable):

  > <!-- bot: question --> Which CI job is failing? Options: unit / integration / e2e Answer: integration

After the bot consumes the answer, archive it (preferred):

  > <!-- bot: question --> (archived to Bot Log)

## Bot Log
- 2026-02-04 Task: Deploy v2.0 to production | Q: Which CI job is failing? | A: integration

Integration notes (minimal)

• Always mark bot-written content with <!-- bot: ... -->.
• Never delete/add lines inside an existing task item or description block.
• Never mark tasks complete unless the user explicitly confirms.