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

## Naming conventions

### Global filename rules

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

### `projects/`

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

### `wiki/`

- Name each wiki entry with a lowercase human-readable filename.
- Spaces are allowed.
- Do not use artifact identifiers in wiki entry filenames.
- Do not apply project artifact naming rules to wiki entries.

### `tags/`

- Name each Tag with a lowercase tag name.
- Spaces are allowed.
- Do not use artifact identifiers in Tag filenames.

## Identifier allocation

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

## Metadata and links

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

## Hashtags and Tags

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

## Gotchas

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