Conducty's context engine lives in an Obsidian vault. This skill defines the vault layout, naming, linking, and index conventions every other Conducty skill must follow when reading or writing notes. Use when reading/writing any plan, design, context, improvement, failure pattern, metrics, or prompt-log note — or when the user says "vault", "Obsidian", "context engine", "where is X stored".
Conducty's context engine lives in an Obsidian vault. This skill defines the vault layout, naming, linking, and index conventions every other Conducty skill must follow when reading or writing notes. Use when reading/writing any plan, design, context, improvement, failure pattern, metrics, or prompt-log note — or when the user says "vault", "Obsidian", "context engine", "where is X stored".
Conducty's plans, designs, context, improvements, failure patterns, metrics, and prompt logs all live in an Obsidian vault. The vault is not a backup or export target — it IS the context engine. Every Conducty note is written there, linked to its peers, and re-read on future sessions to inform planning.
[!important] Read this first
Before writing or reading any state file (plan, design, context, etc.), check this skill for naming and linking conventions. Other Conducty skills assume you've internalized these rules.
Vault Location
Resolve the vault root in this order:
$CONDUCTY_VAULT environment variable, if set
~/Obsidian/Conducty/ fallback
When this skill says "the vault" or {vault}/..., substitute the resolved path. Always use absolute paths when invoking Bash/Read/Write/Edit.
# Resolve in shell:
VAULT="${CONDUCTY_VAULT:-$HOME/Obsidian/Conducty}"
If the vault directory doesn't exist, create it (and the seed index notes — see Bootstrap) before writing anything.
Why a Vault, Not Folders
Earlier Conducty stored state under ~/.conducty/{plans,designs,history,context}/ as flat folders. That worked but produced a write-only log: each file was an island. The vault model fixes this:
Wikilinks make the relationships first-class. A plan links the designs it consumed, the context files it pulled from, and the improvement experiments it's testing.
Backlinks are free. Open Context My-App and Obsidian shows every plan and design that referenced it.
Graph view turns the orchestration history into a navigable knowledge map.
Future plans read the past by following links, not by re-grepping flat files.
The vault is the memory of the orchestrator. Treat every note as a node in a graph, not a row in a log.
Layout
Nested by category, flat-within-category. Subfolders organize by note type and scope; basenames stay unique and descriptive so wikilinks (which resolve by basename across all subfolders) are unaffected by directory placement.
Title Case filenames. Wikilinks resolve by basename, so the filename is the canonical title — never rely on the directory path to disambiguate a wikilink target.
{vault}/
├── Conducty Index.md # root hub
│
├── Indexes/
│ ├── Plans Index.md # links every plan note
│ ├── Designs Index.md # links every design doc
│ ├── Context Index.md # links every project context hub
│ └── Improvements Index.md # links every improvement entry
│
├── Accumulators/
│ ├── Failure Patterns.md # accumulating, append-prepend
│ ├── Metrics.md # one row per plan run
│ └── Prompt Log.md # one entry per prompt outcome
│
├── Plans/
│ ├── Plan 2026-04-27 0930 Auth Cleanup.md
│ └── Plan 2026-04-27 1430 Bug Triage.md
│
├── Designs/
│ └── Design 2026-04-27 0930 Auth Cleanup.md
│
├── Improvements/
│ └── Improvement 2026-04-27 1830.md
│
├── Code Reviews/
│ └── Code Review 2026-04-27 1900.md
│
├── Ship Reports/
│ └── Ship Report 2026-04-27 1915.md
│
└── Context/
└── My App/ # one folder per project
├── Context My App.md # hub
├── Context My App Architecture.md
├── Context My App Conventions.md
├── Context My App Invariants.md
├── Context My App Hotspots.md
├── Context My App Tests.md
├── Context My App Glossary.md
├── Modules/
│ └── Context My App Auth.md # per bounded-context deep note
└── Refreshes/
└── Context Refresh My App 2026-04-27 1830.md
Why nested: flat root broke at scale — a vault with 50+ plans + multi-project context becomes a wall of files. Nesting by category makes Obsidian's file tree navigable. Wikilinks are unaffected because Obsidian resolves them by basename across the whole vault, not by path.
Why long unique basenames inside Context/{Project}/ (e.g. Context My App Architecture.md, not just Architecture.md): wikilinks like [[Architecture]] would collide across projects. Keeping Context {Project} {Slice} as the basename makes every wikilink unambiguous forever.
Two note categories:
Per-instance notes (timestamped or per-project) — get an index
Accumulating notes (singular files appended to over time) — no index, they self-index
Naming Conventions
Per-instance notes
Note type
Directory
Filename pattern
Example
Plan
Plans/
Plan YYYY-MM-DD HHmm [{Topic Title Case}].md
Plans/Plan 2026-04-27 0930 Auth Cleanup.md
Design
Designs/
Design YYYY-MM-DD HHmm {Topic Title Case}.md
Designs/Design 2026-04-27 0930 Auth Cleanup.md
Improvement
Improvements/
Improvement YYYY-MM-DD HHmm.md
Improvements/Improvement 2026-04-27 1830.md
Code review
Code Reviews/
Code Review YYYY-MM-DD HHmm.md
Code Reviews/Code Review 2026-04-27 1900.md
Ship report
Ship Reports/
Ship Report YYYY-MM-DD HHmm.md
Ship Reports/Ship Report 2026-04-27 1915.md
Index
Indexes/
{Topic} Index.md
Indexes/Plans Index.md
Per-project notes (the context sub-graph — see [[conducty-context]])
All per-project notes live under Context/{Project}/. Optional bounded-context deep notes go under Context/{Project}/Modules/. Refresh delta notes go under Context/{Project}/Refreshes/.
Multiple plans per day are expected — that's why plans (and the artifacts derived from them) carry an HHmm timestamp. The topic suffix on plans is optional but encouraged when more than one plan runs in a day, so the filename alone tells you which plan is which.
Accumulating notes
All accumulating notes live under Accumulators/.
Note type
Path
Behavior
Failure Patterns
Accumulators/Failure Patterns.md
Append-prepend: newest pattern at top
Metrics
Accumulators/Metrics.md
Append-prepend: one row per plan run, newest at top
Prompt Log
Accumulators/Prompt Log.md
Append-prepend: one entry per prompt outcome, newest at top
Accumulating notes never get a timestamp in their filename — they hold every entry across all plan runs and serve as the cross-time learning corpus.
Always Title Case. Always full ISO date for any dated note.
Frontmatter
Every Conducty note carries frontmatter. Minimum required fields:
---type:plan|design|context|improvement|failure-patterns|metrics|prompt-log|indexdate:YYYY-MM-DD# for per-instance notestime:HHmm# for plan / design / improvementproject: {project-name} # for context, and for plans/designs scoped to one projecttopic: {shorttopic} # for plan / design (optional but recommended)tags: [conducty, conducty/<type>]
---
Add type-specific fields as the skill requires (e.g., plans add appetite, metrics rows add pass_rate).
Linking
Every per-instance note links its peers and at least one index. A note with no outgoing links has been written into a void.
Standard link patterns:
A plan links: [[Plans Index]], the design(s) it decomposed ([[Design 2026-04-27 0930 Auth Cleanup]]), the context note(s) it loaded ([[Context My App]]), the prior improvement entry whose experiments it's testing ([[Improvement 2026-04-26 1830]]), and any prior plan whose work carries forward ([[Plan 2026-04-26 0930]]). Plans also link the accumulating notes they will append to: [[Failure Patterns]], [[Metrics]], [[Prompt Log]].
A design links: [[Designs Index]], the plan(s) that consume it, the context note(s) for relevant projects, related dialectic decisions.
A context note links: [[Context Index]] and any plan/design that depends on the project. Backlinks accumulate naturally as plans reference it.
An improvement entry links: [[Improvements Index]], the plan it reflects on, [[Failure Patterns]], prior improvements being evaluated.
Failure Patterns (accumulating) — each entry inside the file links the plan that surfaced it ([[Plan 2026-04-27 0930 Auth Cleanup]]) and the prompt entry in [[Prompt Log]].
Metrics (accumulating) — each row links its plan.
Prompt Log (accumulating) — each entry links its plan and, if a failure pattern was extracted, the entry in [[Failure Patterns]].
Place links in two zones:
Inline — wherever a name appears in prose, wikilink it on first reference within a section.
Related section at the bottom of per-instance notes:
Accumulating (under Accumulators/): Failure Patterns, Metrics, Prompt Log (each with its frontmatter and an empty body)
The installer (install-claude-code.sh) does this on first run. This skill creates them lazily if a write would otherwise create an orphan.
Cross-Skill Handoff Protocol
Plans, code reviews, and ship reports must find each other reliably. The rules:
Active Plan Resolution
The "active plan" is the most recent Plans/Plan *.md whose ## End-of-Plan Summary is not yet filled (i.e., [[conducty-review]] hasn't closed it). Resolve by:
# List all plans, newest firstls -t "$VAULT"/Plans/Plan*.md
Read the newest first. If its End-of-Plan Summary is filled, walk backward until one is found that isn't, OR conclude no active plan exists. [[conducty-plan]] starting a new plan creates a fresh active plan; [[conducty-review]] closes the prior one.
Plan ↔ Code Review
[[conducty-code-review]] reads:
The plan(s) whose execution window matches the diff. If the user is reviewing a single completed plan, it's the latest closed plan. If reviewing a multi-plan branch, it's all plans whose timestamps fall within the commit range.
[[conducty-code-review]] writes:
A new Code Review YYYY-MM-DD HHmm.md note with ## Related linking each plan
An Edit on each linked plan's ## Review Notes section to add the wikilink to the code-review note
Plan ↔ Ship Report
[[conducty-ship]] reads:
The latest Code Reviews/Code Review *.md note. Its verdict field gates the ship battery.
The plan(s) referenced by that code review.
Context {Project} Tests for the command set.
[[conducty-ship]] writes:
A new Ship Report YYYY-MM-DD HHmm.md
An Edit on the code-review note's ## Related section: add the ship report wikilink
An Edit on each plan's ## Review Notes section: add the ship report wikilink
Long-Running Branch (Multiple Plans, One Branch)
When a branch accumulates work from multiple plans before merging:
Each plan still produces its own Improvement note via [[conducty-improve]] at plan-close
A singleCode Review runs against the cumulative branch diff at the end (not per-plan)
A singleShip Report runs after the code review
The code-review note's ## Related lists every plan that contributed to the branch
The ship report does the same
Discovery Glob Patterns
Standard globs every skill can rely on. All globs are relative to the resolved $VAULT root.
To find
Glob
Plans
Plans/Plan *.md
Designs
Designs/Design *.md
Improvements
Improvements/Improvement *.md
Code reviews
Code Reviews/Code Review *.md
Ship reports
Ship Reports/Ship Report *.md
Project hubs
Context/*/Context *.md (filter to depth-2 — the hub sits directly under each project folder)
Project slices
Context/*/Context * Architecture.md, Context/*/Context * Conventions.md, etc.
All project hubs: glob Context/*/Context *.md (the hub sits at the top of each project folder)
Accumulators/Failure Patterns.md — the accumulating learning corpus, especially recent entries
Accumulators/Metrics.md — last 7-14 rows for trend data
Use Glob with patterns like Plans/Plan *.md against the resolved vault root. Read the resulting notes, follow their wikilinks via Read on the targets, and the orchestrator inherits the full context graph.
Writing Conventions
Every Write to a new per-instance note must include frontmatter, a ## Related section, and an index update in the same Conducty action.
Use Edit (not Write) to update existing notes — preserve frontmatter, prepend new entries above older ones.
Never rename a per-instance note silently — wikilinks resolve by basename, so a rename breaks every backlink. If a rename is needed, do it in Obsidian (it updates links) or grep+sed across the vault.
Code spans (`~/.conducty/...` or `./skills/foo/SKILL.md`) are still appropriate for shell paths or external state. Use wikilinks only for vault-resident notes.
Edit-Prepend Contract for Accumulating Notes
Failure Patterns, Metrics, and Prompt Log are append-mostly but written by multiple skills (sometimes within the same plan). The contract:
Each accumulating note has a stable two-line header anchor — the H1 plus a one-line intro. New entries are prepended immediately after the anchor, never inside it, never appended at the bottom.
Every entry begins with a level-3 heading containing a timestamp: ### YYYY-MM-DD HHmm — {short label}. Newest entry is at the top; chronological order descends.
Every entry links its source plan via wikilink in the body. This is what makes the accumulating note a graph node, not a flat log.
Use Edit, not Write — Write would clobber prior entries. The Edit's old_string is the anchor (H1 + intro), the new_string is anchor + new entry.
Atomic per skill invocation — within a single skill action, prepend all entries the skill is contributing as one Edit (or a sequence on the same anchor with each new entry shifting the anchor down). Don't interleave with other skills' writes inside the same action.
Example anchor for Accumulators/Failure Patterns.md:
To prepend, Edit replaces the intro line with intro line\n\n### {new entry}. The H1 + intro stay constant — they're the anchor.
If two plans run in parallel, each appends through Edit on the same anchor. Edit is line-precise so collisions surface as Edit failures (the second one finds the prior one's text and stops). Resolve by re-reading and re-editing.
Cross-Plan Concurrency
Conducty assumes one orchestrator per vault at a time. Running two conducty-execute sessions against the same vault concurrently is supported only when:
They write to different per-instance notes (different timestamps — fine)
They append to different accumulating notes (rare — usually they share)
Or one is read-only ([[conducty-vault-graph]], [[conducty-code-review]] reading)
When two orchestrators must append to the same accumulating note, serialize: finish one, then the other.
The vault replaces all of it. If you find a Conducty skill that still references the old path, treat the vault path as authoritative and update the skill (or flag the inconsistency). The legacy ~/.conducty/ directory is not used.
Integration
[[conducty-plan]] reads/writes Plan YYYY-MM-DD HHmm [Topic].md
