name	graph-task
description	Manage graph-task work runs with the md-first protocol: canonical markdown files, YAML frontmatter validation, and tree-first Obsidian collaboration. Use when you need to inspect or author the md-first run layout, validate frontmatter/file structure, review the legacy JSON CLI, or understand how markdown-canonical graph-task projects should be organized.

graph-task

Canonical rule

vNext graph-task is md-first.

Canonical state lives in markdown files arranged as the project/step/phase/node tree, with required YAML frontmatter on every canonical entity note.

Treat JSON as support-only in this direction:

schema references
parser fixtures / tests
optional snapshots or exports
legacy prototype compatibility

Do not treat graph.json as the durable source of truth for md-first runs.

Read these references first

references/md-first-vnext-spec.md — canonical md-first protocol
references/obsidian-plugin-mvp-spec.md — deterministic Obsidian client expectations
examples/md-first-minimal/ — smallest canonical markdown example

Legacy prototype status

This repo still includes a legacy graph.json CLI prototype in scripts/graph_task.py. That prototype is useful for learning, migration, and fixture generation, but it is no longer the primary contract.

If you touch legacy JSON paths, label them clearly as one of:

legacy prototype behavior
migration aid
derived snapshot / export

Current operating model

Canonical md-first discovery comes from folder structure + required frontmatter.
Use one shared minimal status vocabulary everywhere: pending | active | done | blocked | cancelled.
Preserve history; prefer append-only logs/results over destructive rewrites.
Keep tree/containment semantics primary; use graph relationships as secondary metadata.
Validate frontmatter and filesystem reachability before claiming the structure is sound.
For repo-backed vault work, treat the vault repo as one GitHub-synced workset: local edits should be reconciled back to the shared remote rather than drifting as a separate local-only truth.

Recommended workflow

Start from references/md-first-vnext-spec.md or examples/md-first-minimal/.
Create or edit canonical markdown entities (index.md, node notes, result notes) in the md-first folder layout.
Keep required frontmatter valid and stable.
Record outcomes in append-only result notes and log files.
Use Obsidian/plugin surfaces as working clients for the markdown tree.
If you use the legacy CLI or export paths, describe them as derived/non-canonical.

Legacy CLI note

The bundled CLI remains:

python3 scripts/graph_task.py <command> ...

But unless a task is explicitly about the legacy prototype, assume markdown-canonical work is the real target.

Repo-backed vault workflow

init --repo-url <repo> --repo-branch <branch> creates or refreshes a local checkout, then writes the run into <checkout>/<project-id-slug>/.
Repo metadata is recorded in project.repo so later sync commands can find the checkout again.
Treat the repo-backed vault as a shared canonical workset, not a disposable local scratch copy.
Use git-status before and after meaningful work blocks.
Use git-pull when you need the latest remote state and your local repo is clean.
Use git-push --message ... when you only want to commit/push current local changes.
Use git-sync --message ... as the normal manual sync path: fast-forward pull first, then commit all pending changes, then push.
If local changes cannot be synced safely, stop and surface the divergence instead of pretending the local vault is authoritative.
These commands operate on the entire repo checkout. Be honest if unrelated dirty files in the same repo make sync unsafe.
Avoid hidden merge behavior: this workflow intentionally prefers pull --ff-only and surfaces divergence instead of auto-resolving it.

Minimum validation before claiming success

Run:

python3 scripts/graph_task.py validate <run-dir>
python3 scripts/graph_task.py summary <run-dir>

If you changed the skill itself, also run:

python3 -m unittest tests/test_graph_task_cli.py
python3 /home/jimmy/.npm-global/lib/node_modules/openclaw/skills/skill-creator/scripts/package_skill.py <skill-dir> <output-dir>

name	graph-task
description	Manage graph-task work runs with the md-first protocol: canonical markdown files, YAML frontmatter validation, and tree-first Obsidian collaboration. Use when you need to inspect or author the md-first run layout, validate frontmatter/file structure, review the legacy JSON CLI, or understand how markdown-canonical graph-task projects should be organized.