managing-obsidian-tasks

name	managing-obsidian-tasks
description	Use when the user explicitly says task, todo, or personal Kanban, or asks to find, review, update, wait, block, complete, or cancel an existing Obsidian task. Requests phrased only as "track this for later" belong to the issue workflow. Do not use for work bound for GitHub, Linear, or a Codex conversation; calendar events or reminders; checklist edits inside other notes; or immediate implementation not requested as a task.
license	MIT
compatibility	Requires a running Obsidian desktop app with the official Obsidian CLI. The core Bases plugin is required for setup, search, create, update, and close because each operation completes through Base views.

Managing Obsidian Tasks

Manage Obsidian tasks from capture to completion. Task notes are the source of truth; dashboards only display their properties.

Required References

• references/task-contract.md

Read references/task-contract.md before drafting, creating, changing, transitioning, or validating a task. A search-only run may delay reading it until task properties need interpretation.

Read assets/task-template.md when creating a task or when setting up or repairing the task system. Read the other files under assets/ only when setting up or repairing the task system; they define the Base and structure note.

Obsidian CLI boundary

Use the official Obsidian CLI for every vault search, read, create, update, rename, move, property change, and deletion. Run it through python3 scripts/obsidian_cli.py when the bundled wrapper is usable; otherwise invoke the official CLI binary directly. Always pass the intended vault and an exact vault-relative path for mutations. With the bundled wrapper, pass the vault as --vault <vault-name> so it is placed before the Obsidian command; never forward a raw vault= argument.

Preflight the CLI against the target vault before any write. When the app or CLI is unavailable, keep the proposed content as a draft and stop before mutation. Raw filesystem access is not a fallback for vault content.

Workflow

1. Resolve the request and vault

Classify the request as setup, create, search, update, transition, or close. If the request says only "capture this" and context does not identify the destination, ask whether the user wants an Obsidian task or a tracker issue. Resolve the target vault from the user's context or the CLI vault list; ask when more than one plausible vault remains. Confirm that the CLI can read the vault and inspect Tasks/, Bases/Tasks.base, Structure Notes/Tasks.md, and Templates/Task.md as applicable.

Completion: one operation branch and one reachable target vault are known.

2. Inspect task context

Use the CLI to inspect all task metadata, then read the closest matches by title, goal, project, people, and source. Read linked project or Person notes when they would improve classification. For creation, compare prior human_energy values and other repeated patterns before proposing metadata. State that a check succeeded only when its CLI result was obtained. When vault context is unavailable, label the draft provisional and stop before claiming that duplicates, links, or historical patterns were verified.

Apply the duplicate rules from the task contract. Prefer improving an active task that already owns the outcome; keep uncertain outcomes separate.

Completion: every plausible active duplicate is resolved and the relevant historical context has informed the operation.

3. Follow the operation branch

Setup or repair

Compare the three assets with the target paths. Present the files that would be created or replaced and wait for approval. After approval and immediately before each write, re-read the exact target or confirm that it remains absent, then compare that state with the approved baseline. On a mismatch, abort the write, recompute the proposal from the current state, present the revised preview, and request approval again. Write approved content through the CLI. For each of the three assets (the template, Base, and structure note), use the same quote-safe JSON/base64/helper transport required for task creation. Never interpolate asset Markdown or YAML into a shell content= argument. Preserve user customizations unless they violate the task contract.

Completion: the template, Base, and structure note are readable through the CLI, and every Base view queries without error.

Create

Draft from assets/task-template.md. Infer required values from the request, comparable tasks, and linked context; use unknown only when evidence remains insufficient. A required unknown keeps the proposed task in triage.

Present the proposed filename, complete metadata, and populated body. Wait for explicit approval before writing every new task, including when the request already says "create a task." Apply requested corrections to the preview and ask again.

Set the proposed status to todo when every required value is resolved and the task is ready to begin. Keep it in triage when any required value is unknown.

After approval and immediately before the write, confirm that the exact target remains absent and compare that state with the approved absence baseline. If it exists or otherwise differs, abort the write, recompute the proposal from the current state, present the revised preview, and request approval again. Then pass the complete approved note through a quote-safe transport, such as a serialized JSON/base64 payload or a helper that safely escapes content, and use the CLI create operation without overwrite. Never interpolate note Markdown into a shell content= argument. The transport must preserve apostrophes, backticks, shell substitutions, backslashes, and wikilinks literally. Re-read the exact path and query the All tasks Base view. Linter-owned properties remain outside this skill's completion gate.

Completion: the approved note exists once, matches the preview, and appears in the task Base.

Search or review

Query the narrowest relevant Base view, then inspect matching notes when the answer needs body context. Return concise results with status, priority, relevant dates, goal, and a link or vault-relative path for each task.

Completion: every task matching the stated filters is represented, or the response states that none matched.

Update or transition

Resolve one exact task path. Read it immediately before mutation. Apply property changes with CLI property:set or property:remove, and append Work log entries with CLI append. For a body-section replacement, use CLI eval with app.vault.process(file, updater) so the updater receives the current content. Avoid whole-note replacement so concurrent context and history survive.

When property:set creates or updates due, not_before, follow_up_on, blocked_since, or date_closed, explicitly pass type=date; for people, explicitly pass type=list. Use type=text for other scalar task properties unless an existing property type must be preserved.

Apply direct, unambiguous user updates without another confirmation. Follow the execution-shape and status gates in the task contract for agent-initiated transitions. Re-read the note after every mutation and query its applicable Base view.

Completion: the requested state is visible in both the note and derived view, with required conditional fields, sections, and Work log evidence present.

Close

Check every applicable Definition of done item and inspect Deliverables and Result. Apply the closure and execution-shape gates from the task contract.

Set closure properties through the CLI, append the final Work log entry, then verify the note appears in History and no longer appears in active views.

Completion: the closure contract passes and the derived views reflect the closed state.

4. Report the result

State what changed or what was found. Link the affected task notes and name any remaining unknown, waiting, blocked, or review condition. For a stopped mutation, preserve the preview and state the specific CLI or vault condition that must be restored.

Completion: the user can identify the affected task and its current state without reopening the full note.