97 lines
4.6 KiB
Markdown
97 lines
4.6 KiB
Markdown
# 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.
|