codex-obsidian-loop

name

codex-obsidian-loop

description

Use for task-driven Codex work that should preserve agent memory and durable results in an Obsidian or Markdown LLM+wiki vault: query planning, source boundaries, project workbench notes, checkpoints, decision logs, result writeback, and lint. Always use this skill when the user mentions Codex plus Obsidian, LLM+wiki, agent memory, result sedimentation, project vaults, writeback, checkpoints, source boundaries, or a query/work/writeback/lint loop.

Codex Obsidian Loop

Use this as a thin entrypoint for a task-driven Codex + Obsidian loop. Codex drives the work; the vault preserves durable project memory and reusable outcomes. Keep the skill focused on context discipline, source boundaries, writeback, and validation. Load detailed vault rules only when the current task needs them.

Vault

Ask for the vault path if it is not already clear from the user, workspace, or local configuration.

Expected vault structure:

raw/          immutable source material
wiki/         stable reusable knowledge
workbench/    active task notes, drafts, explorations, checkpoints
decisions/    append-only decision records
system/       vault rules, source map, usage notes, scripts

If the vault does not exist yet, offer to scaffold it from vault-template/ before starting substantial work.

Core Contract

Follow:

query -> work -> checkpoint/closeout writeback -> lint

The point is not to make the agent read everything or trust chat history as memory. The point is to read the right small set of context, do the work, preserve durable learning in the Obsidian/wiki layer, and keep the vault clean.

Start A New Task

Run this bootstrap once per distinct task, or when context is missing, stale, or ambiguous:

1. Read AGENTS.md if present.
2. Read wiki/index.md.
3. Read wiki/source-of-truth.md.
4. Read wiki/current-direction.md.
5. Read system/context-loop.md.
6. Read system/source-map.md when source priority matters.
7. Build a short query plan:
   • task type;
   • minimum context to read;
   • sources that are current, stale, legacy, exploratory, or unverified;
   • likely writeback target, if any;
   • artifact format (.md, .base, .canvas, code, deck, spreadsheet, or other) and any helper skill needed.

Then read only the extra files needed for the task.

Common Task Areas

Task area	Read as needed
Product / strategy / positioning	wiki/source-of-truth.md, wiki/current-direction.md, wiki/principles.md, system/source-map.md
Users / scenarios / research	wiki/users.md, wiki/scenarios.md, relevant raw/ or workbench/ research notes
UX flows / IA / product copy	wiki/current-direction.md, wiki/flows.md, wiki/glossary.md, related screenshots or prototypes
Metrics / release tracking	relevant workbench/ tracker, wiki/current-direction.md, decisions/decision-log.md
Risk / review	wiki/principles.md, wiki/risks.md, relevant workbench review note
Source/code calibration	system/source-map.md, source snapshots, code maps, external repo or docs
Prior decisions	decisions/decision-log.md

These names are conventions, not requirements. If a vault uses different names, map to the closest equivalent.

Same Task Follow-Ups

• Do not repeat the full bootstrap.
• Identify the active artifact, decision, or workbench note.
• Read only touched files or narrow excerpts needed.
• Reload stable wiki context only when a new source, contradiction, product area, or context compaction makes it necessary.
• For UI or prototype changes, use cheap static checks first; use browser or screenshot checks when visual behavior matters.

Work Rules

• Separate source-backed facts, user-provided preferences, design hypotheses, decisions, and open questions.
• Do not invent facts to fill gaps.
• Do not let old notes, exploratory prototypes, or unverified summaries override the current source of truth.
• If live product evidence, source data, or user confirmation conflicts with the vault, mark the conflict and update the vault before relying on the old fact.
• For high-impact judgments, preserve the strongest alternative path or counterargument.

Obsidian Artifact Routing

This skill owns project judgment, source boundaries, and writeback decisions. Delegate generic file-format details to helper skills when available:

• For .md notes, use Obsidian-flavored Markdown conventions when the vault is used in Obsidian: frontmatter, wikilinks for vault notes, Markdown links for external URLs, callouts when helpful.
• For .base files, write valid YAML, quote filters and formulas safely, and verify referenced formulas and properties exist.
• For .canvas files, parse JSON, keep node and edge IDs unique, avoid overlapping nodes, and ensure every edge references an existing node.
• For live Obsidian app operations, use a CLI or app-control helper only when the user asks to interact with the running app or when app state, screenshots, backlinks, tasks, or properties must be verified inside Obsidian. Ordinary vault file edits can use the filesystem.
• For external web pages that need to become source notes or workbench material, extract clean Markdown when possible, then preserve the source URL and access date.

Project-specific source rules always take priority over generic formatting.

Writeback Levels

Do not write every turn and do not ask every turn whether to write.

Use three levels:

• none: ordinary discussion, temporary exploration, small tweaks, status-only turns.
• checkpoint: compact update to an existing or clearly named workbench/ note when an intermediate conclusion would be costly to lose.
• closeout: fuller sync when a task or major phase is complete.

Write a checkpoint automatically when all are true:

• the work clearly belongs to this project vault;
• it has future reuse value: source-backed finding, metric, PRD structure, trade-off, narrowed open question, decision candidate, risk, or release signal;
• it can be saved without chat transcript or process logs;
• the user has not said not to write the vault.

Checkpoint format:

## Checkpoint - YYYY-MM-DD

- Current conclusion:
- Evidence / sources:
- Decisions or decision candidates:
- Open questions:
- Next action:

If unsure, ask once at a natural boundary.

Closeout Shape

When closeout is warranted:

1. Update or create the relevant workbench/ note.
2. Update workbench/active-work-index.md if present.
3. Promote stable facts to the right wiki/ page only if justified.
4. Append important decisions to decisions/decision-log.md.
5. Update wiki/open-questions.md for real open questions.
6. Run lint and any artifact-specific validation needed:
   • .md: durable notes have frontmatter; wikilinks resolve or are intentionally pending.
   • .base: YAML parses; formulas and properties referenced by views are defined.
   • .canvas: JSON parses; IDs are unique; edges do not dangle.
7. Report updated files, verification, and remaining high-value open questions.

Hard Rules

• Do not copy secrets, credentials, private raw exports, or sensitive source content into public-facing wiki or workbench notes.
• Keep raw/ immutable unless the user explicitly asks to import a new source snapshot.
• Keep decisions/decision-log.md append-only.
• Promote to wiki/ only stable, source-backed or user-confirmed facts.
• New durable .md notes should include frontmatter with at least title, type, tags, and updated unless the surrounding folder has a different established pattern.
• After writeback, run the vault lint script if present, commonly node system/scripts/vault-lint.mjs.

References

Read these project files when present and relevant:

• system/context-loop.md
• system/source-map.md
• system/agent-usage.md
• workbench/new-task-template.md
• workbench/closeout-template.md