Agent Instructions

This repository stores agent-generated artifacts across projects.

Layout

Use projects/<project>/ for project-specific artifacts, where <project> is the lowercase basename of the project directory.
Keep every project directory flat. Do not create artifact-type or effort subdirectories.
Store an artifact's attachments beside its Markdown note.
Use wiki/ for cross-project Markdown knowledge entries.
Do not write to wiki/ unless the user explicitly instructs you to do so through a dedicated skill.
Keep wiki/ flat.
Do not create subdirectories under wiki/.
Use tags/ for Tags.
Keep tags/ flat.
Do not create subdirectories under tags/.
Do not create .gitkeep files.
Keep user-facing top-level artifact directories limited to projects/, wiki/, and tags/.
Hidden tool directories such as .git/ and .obsidian/ are allowed.

File names must be lowercase unless an established tool convention requires otherwise.
Spaces are allowed unless a location-specific rule says otherwise.

Name each Markdown artifact <NNN>-<scope-slug>[-<subject-slug>]-<artifact-type>.md.
NNN is the next value after .counter.
Pad NNN to at least three digits and expand naturally after 999.
Use the project slug as the scope slug for project-wide artifacts.
Use the effort slug as the scope slug for effort-scoped artifacts.
Do not use subsystem or topic slugs as scope slugs.
Use the optional subject slug to distinguish multiple artifacts of one type within a scope.
Use slugs for scope-slug, subject-slug, and artifact-type. Slugs are lowercase and use hyphens instead of spaces.
Let the creating skill define its artifact-type slug. There is no vault-wide type registry.
Name a project's context artifact <NNN>-<project-slug>-context.md.
Name each attachment from its owning artifact's complete stem plus a numeric suffix, such as 042-wayfinder-layout-prototype-01.png. Attachments do not receive their own identifiers.
Preserve an artifact's identifier when renaming its other filename components.
Update every wikilink to a renamed artifact in the same change.

.counter at the vault root is the tracked source of the most recently allocated identifier.
To allocate an identifier, increment .counter and persist it before creating the artifact.
Never reuse an allocated identifier, including after failed creation or deletion.
Do not lock .counter.
After parallel creation, the coordinating agent must find duplicate identifiers, preserve pre-existing artifacts, renumber its current outputs, update their wikilinks, and advance .counter as needed.

Store machine-readable artifact metadata in YAML frontmatter.
Store Obsidian wikilinks in YAML as quoted text or quoted list values.
Use a singular parent property for the earlier artifact that directly caused the current artifact to exist.
Use a blocked-by list for zero or more upstream artifacts that must resolve before the current artifact can be acted on.
Use bare wikilinks without display aliases.

Use Obsidian hashtags for note metadata through the YAML tags property.
A Tag is a content-free Markdown note under tags/ used only to form clusters in the Obsidian graph view.
A trailing newline in a Tag is acceptable.
Link to Tags with bare Obsidian wikilinks, such as [[example]].
Do not define the internal structure of wiki entries yet.

Do not apply project-specific artifact structure rules to wiki entries. Wiki entry structure is intentionally undecided.
Context artifacts under projects/ are normal identifier-bearing project artifacts. They use the next value after .counter, not a reserved 000 prefix.
Do not invent naming conventions for new directories. The vault layout is fixed unless the user explicitly changes it.
Wayfinder map artifacts under projects/ still need the normal artifact-type suffix. Use -map.md, not a filename that ends at the effort slug.
Preserve blocked-by dependency links after blockers resolve. Do not remove entries merely because a dependency is no longer actively blocking the next action.