robertbarclayy/conducty/conducty-obsidian

Conducty Obsidian — The Context Engine

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:

1. $CONDUCTY_VAULT environment variable, if set
2. ~/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

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

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 | index
date: YYYY-MM-DD          # for per-instance notes
time: HHmm                # for plan / design / improvement
project: {project-name}   # for context, and for plans/designs scoped to one project
topic: {short topic}      # 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:

1. Inline — wherever a name appears in prose, wikilink it on first reference within a section.
2. Related section at the bottom of per-instance notes:

## Related
 
-Index: [[Plans Index]]
-Built from: [[Design 2026-04-27 0930 Auth Cleanup]], [[Context My App]]
-Tests experiments from: [[Improvement 2026-04-26 1830]]
-Carries forward from: [[Plan 2026-04-26 0930]]
-Accumulates into: [[Failure Patterns]], [[Metrics]], [[Prompt Log]]

Index Notes

Index notes are flat lists with frontmatter. They serve two purposes:

1. Make Obsidian's left-sidebar useful (navigate by index, not file tree)
2. Catch orphaned per-instance notes — if a new note isn't in its index, it'll get lost

Each index follows this shape:

---
type: index
tags: [conducty, conducty/index]
---
 
# Plans Index
 
Conducty plans. Newest first.
 
-[[Plan 2026-04-27 1430 Bug Triage]]
-[[Plan 2026-04-27 0930 Auth Cleanup]]
-[[Plan 2026-04-26 0930]]
 
## Related
 
-Root: [[Conducty Index]]
-See also: [[Designs Index]], [[Improvements Index]], [[Failure Patterns]], [[Metrics]], [[Prompt Log]]

When you create a new per-instance note, always prepend its wikilink to the matching index in the same operation.

Conducty Index is the root and links every index plus the accumulating notes:

---
type: index
tags: [conducty, conducty/index, conducty/root]
---
 
# Conducty Index
 
The Conducty cycle: Shape → Plan → Trace → Execute → Verify → Improve.
 
## Indexes
 
-[[Plans Index]]
-[[Designs Index]]
-[[Context Index]]
-[[Improvements Index]]
 
## Accumulating
 
-[[Failure Patterns]]
-[[Metrics]]
-[[Prompt Log]]

Bootstrap

If the vault root doesn't exist, create it (with the standard subdirectories) before any other note write:

VAULT="${CONDUCTY_VAULT:-$HOME/Obsidian/Conducty}"
mkdir -p "$VAULT"/{Indexes,Accumulators,Plans,Designs,Improvements,"Code Reviews","Ship Reports",Context}

Context/{Project}/ and its Modules/ + Refreshes/ subfolders are created lazily by [[conducty-context]] when ingesting a project.

Seed these notes if missing: