name: todolist-md-clawdbot description: Operate on todolist-md Markdown todo files. Read + summarize tasks, propose edits, and write outcomes back into Markdown using only markers (line-stable write-back).

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)

Markdown is the system of record.

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

Use only bot markers of this form.


Do not introduce other syntaxes (no Question[id=...], no custom metadata blocks).

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.

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).

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:
-  2026-02-04T15:39Z root=<rootFolderId> model=<model>

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:

 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:
-  <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  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)

 for bot-suggested sections
 for in-file Q/A
 for summaries/digests
 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:

List folder files (cheap; no downloads)
Compare each file's modifiedTime/size against a local state file
Download only changed .md
Extract only open tasks (- [ ] ..., max N lines)
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)
- 
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": "- [ ] ...\n  > <!-- 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:

Append an entry to ## Bot Log.
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 .
Never delete/add lines inside an existing task item or description block.
Never mark tasks complete unless the user explicitly confirms.

Todolist Md Clawdbot Copy

Description