# Ariadne:workspace Instructions

> Create or update workspace-level instruction files for code repositories or ordinary project folders, including AGENTS.md, CLAUDE.md, GEMINI.md, local override files, and Ariadne vault-link blocks. Use when a user wants to initialize, repair, or refresh workspace instructions, connect a workspace to a registered Ariadne vault or scope, or make instructions portable across Codex, Claude Code, Gemini CLI, and other agent runtimes without duplicating global discovery.

- Skill: `pariyar07/ariadne-workspace-instructions` (Agent Skill, multi-file: 47 files)
- Install (CLI): `npx skillmds@latest add pariyar07/ariadne-workspace-instructions`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pariyar07/ariadne-workspace-instructions/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: pariyar07 (https://skillmd.com/u/pariyar07)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pariyar07/ariadne-workspace-instructions

---


# Ariadne Workspace Instructions

Use this skill to make a workspace agent-readable and connect it to Ariadne vault context when useful.

This skill owns workspace-level instruction files. `ariadne:global-discovery` owns machine-level registry files and global adapter blocks.

## Core Model

Workspace instruction files are a bridge:

```text
global agent files -> registered vault discovery -> vault or scope context
workspace instruction files -> local workspace rules -> optional vault/scope link
```

Keep the bridge small. Do not copy vault navigation, private absolute paths, or long scope notes into public workspace files.

## Bounded Discovery

Inspect only the smallest useful workspace context:

1. Current directory and parents up to the nearest workspace root.
2. Existing `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `WORKSPACE.md`, and local override files in that root.
3. `.gitignore`.
4. High-signal workspace files such as `README.md`, package or build manifests, test config, and existing docs indexes.
5. Git state when relevant: whether the folder is inside a worktree, the repository root, tracked instruction files, ignored local files, and whether remotes suggest the workspace is shared.
6. Registered vault metadata only when the user asks to connect the workspace to Ariadne context, repair stale global discovery, or the prompt is ambiguous about which known workspace/vault it refers to.

Do not scan the whole computer. Do not scan an entire vault or repository to infer intent. Use filenames, manifests, and existing entry files first.

## Mechanical Signal Check

When the workspace shape is uncertain, or when repairing existing instruction files, you may run the deterministic checker:

```bash
node scripts/check_workspace.js "/path/to/workspace" --json
node scripts/check_workspace.js "/path/to/workspace" --json --vault "/confirmed/path/to/vault"
```

Resolve `scripts/check_workspace.js` relative to this `SKILL.md`. In an Ariadne repository checkout, the same script lives at `skills/workspace-instructions/scripts/check_workspace.js`.

Use the checker for mechanical signals only: Git/worktree state, tracked or ignored instruction files, local-file `.gitignore` coverage, private-path signals, instruction line counts, high line-count files, duplicated vault navigation, adapter duplication, copied global-discovery blocks, malformed, duplicate, legacy, or foreign marker blocks, stable scope identity and canonical-path checks inside workspace-vault-link markers, `WORKSPACE.md` references, fixed-depth child directories, child Git repos, exact child-name mentions by file, root Git plus child Git repo topology, Codex `AGENTS.override.md` bodies that have drifted out of sync with `AGENTS.md` (`codexOverrideOutOfSyncFiles`), Hermes `.hermes.md` / `HERMES.md` override signals, shared instruction files that exceed the ~150-line open-standard length (`oversizedForStandardFiles`), and a canonical `AGENTS.md` that carries no command guidance (`agentsMissingCommandGuidance`).

Pass `--vault` only after the user has confirmed the intended vault. The checker uses the shared scope-topology inventory and proves a unique valid mapping before making a canonical claim. Duplicate ID declarations, invalid or model-excluded descriptors, ambiguous roots/topology, case-fold or canonical-path collisions, escaping realpaths, and multiply linked descriptor files produce `ambiguousScopeIdFiles`, never current or stale. Without `--vault`, a complete identity is reported in `unverifiedScopeIdentityFiles`; it is never called current, stale, or unknown. Programmatic callers use `checkWorkspace(workspace, { vaultRoot })` under the same confirmation boundary.

Do not let checker output replace judgment. This skill decides whether to ask a question, preserve workspace-specific rules, split shared/local content, or perform conservative cleanup.

## Questions

Ask adaptively when missing information changes the files to write.

Useful questions:

- Which workspace root should receive these files?
- Is this workspace shared through Git, local-only on this machine, or should it have both shared and local/private instruction files?
- Which runtimes should be supported: Codex, Claude Code, Gemini CLI, or another adapter?
- Should the vault connection be public-safe in tracked files, private in local ignored files, or both?
- Which registered vault or scope should this workspace link to?
- Should existing instruction files be updated, split into canonical plus adapters, or left unchanged except for the Ariadne marker block?
- If `AGENTS.md` references a missing `WORKSPACE.md`, should I create `WORKSPACE.md`, fix the stale reference, or point to another file?

When multiple vaults, scopes, or workspace roots are plausible, show the top matches with short reasons and ask the user to choose. Search hits, current directory, or prior conversation alone are not permission to write an ambiguous vault/scope link.

## Workspace File Pattern

Use `references/workspace-instruction-files.md` when creating or restructuring files.

Use `references/workspace-instruction-scenarios.md` when edge-case behavior matters, such as Git shared/local mode, stale `.gitignore` coverage, private-path leakage, bulky instruction files, adapter normalization, duplicate or malformed markers, legacy marker migration, copied global-discovery blocks, nested subprojects, worktrees, `WORKSPACE.md` ownership, child repo/folder inventory, or ambiguous vault/scope links.

Use `references/instruction-file-rules.md` as the audit rubric when auditing or attesting instruction files against the open standard and cross-runtime portability rules.

Default shape:

- `AGENTS.md` - canonical workspace instructions, usually public-safe.
- `WORKSPACE.md` - optional workspace contract for parent folders, child repo/folder inventory, boundaries, and shared operating model. This is a supported Ariadne pattern, not a runtime convention; agents only read it reliably when `AGENTS.md` points to it.
- `CLAUDE.md` - thin Claude adapter, usually a short sentence plus `@AGENTS.md` and any Claude-only public deltas.
- `GEMINI.md` - thin Gemini adapter when Gemini CLI support is requested, usually a short sentence plus `@AGENTS.md` and any Gemini-only public deltas.
- `.hermes.md` / `HERMES.md` - Hermes-specific project context overrides. Do not create these by default because Hermes gives them priority over `AGENTS.md`; when they exist alongside `AGENTS.md`, verify they intentionally shadow the canonical file and do not rely on unsupported `@AGENTS.md` imports.
- `AGENTS.override.md` - optional Codex local replacement override, gitignored. Codex reads only one instruction file per directory and prefers the override, so it fully replaces `AGENTS.md` for that directory — it is not merged or supplemented. When you create or refresh it, write a verbatim copy of the current `AGENTS.md` body, then add the local vault section at the bottom inside the `ariadne:workspace-vault-link` marker block. Because it is a full copy, it drifts stale whenever `AGENTS.md` changes; re-sync the copied body on every refresh and treat a `codexOverrideOutOfSyncFiles` signal as a stale override to repair.
- `CLAUDE.local.md` - optional Claude local memory, gitignored.
- `GEMINI.local.md` - optional Ariadne local context convention for Gemini workflows, gitignored. Do not assume Gemini loads it automatically unless the local runtime configuration or user confirms that behavior.

If the workspace already has a different valid pattern, preserve it and add the smallest compatible Ariadne link.

Do not create `WORKSPACE.md` for plain single repos by default. Propose it proactively for non-Git parent workspaces with child Git repos, or use it when it already exists or the user asks for it.

## Sharing Mode

Before writing or restructuring files, decide the sharing mode.

Check whether the workspace is inside Git. If it is, inspect whether instruction files are tracked and whether local-only filenames are covered by `.gitignore`. If the answer changes what you would write and the prompt does not make the intent clear, ask one short question: should these instructions be shared in the repo, local-only for this machine, or split into shared plus local/private files?

When a single run could produce **both** shared/public tracked files and local/private ignored files — for example, public workspace rules in `AGENTS.md` plus a private vault link and machine paths in `CLAUDE.local.md` or `AGENTS.override.md` — do not silently pick one or split content by guess. Ask which the user wants (shared only, local only, or both) and, when the answer is both, confirm which content belongs in the tracked files versus the ignored local files. The only exception is when the current prompt already states the split or the existing file layout makes it unambiguous.

Use this mapping:

- Shared repo: tracked `AGENTS.md` contains public-safe workspace rules and a compact Ariadne link. Tracked `CLAUDE.md` and `GEMINI.md` stay thin adapters unless they have real runtime-specific public deltas. Hermes normally reads `AGENTS.md` directly; create tracked `.hermes.md` or `HERMES.md` only for explicit Hermes-specific overrides.
- Local-only in a Git repo: prefer ignored local files and add `.gitignore` coverage before creating them. Do not create or modify tracked instruction files unless the user asks.
- Shared plus local: put stable team/workspace rules in tracked files and put private vault paths, exact scope paths, personal workflow, sandbox paths, and machine-only commands in ignored local files.
- Non-Git folder: ask only when sharing intent is unclear and materially affects the file shape. If the user does not care, keep files portable and avoid private absolute paths in files likely to be copied elsewhere.

Do not invent a generic `AGENTS.local.md` convention. Use `AGENTS.override.md` only when a Codex replacement file is intended. Use `CLAUDE.local.md` for Claude local project memory. Use `GEMINI.local.md` only as an explicit local convention when the user's Gemini setup loads it or the user asks for it. Do not use Hermes `SOUL.md` for workspace or vault routing; it is identity/personality context, not a project instruction adapter.

`AGENTS.override.md` is a full replacement, not a supplement: Codex reads it instead of `AGENTS.md`, so it must restate the whole current `AGENTS.md` body and then carry local differences inside the `ariadne:workspace-vault-link` marker block. Generate it by copying the current `AGENTS.md` verbatim and appending the local block; keep the copied body in sync on every refresh so Codex never reads stale repo guidance. `CLAUDE.local.md` and `GEMINI.local.md` are supplements — Claude and Gemini also read their tracked files — so they hold only the local delta and do not restate `AGENTS.md`.

Never run destructive Git cleanup from this skill. If the user explicitly asks to make a parent workspace non-Git, explain a root-only, child-preserving plan and ask before any command that removes or rewrites root `.git`; child `.git` directories or gitfiles must be preserved.

## Proactive Maintenance Pass

When creating, refreshing, or connecting workspace instructions, do not only add or replace the Ariadne marker block. First classify existing content:

- Keep in shared workspace instructions: purpose, boundaries, commands, test/build/validation workflow, coding conventions, review expectations, and compact safety rules.
- Keep in `WORKSPACE.md` when present or clearly being created for a parent workspace: workspace purpose, parent boundaries, child repo/folder inventory, shared operating model, and root-only safety rules.
- Keep local-only: private vault paths, exact private scope paths, client names not meant for collaborators, personal defaults, machine-local commands, sandbox paths, and temporary migration notes.
- Leave in the vault: long navigation lists, destination maps, scope catalogs, decision history, roadmap details, customer context, raw transcripts, and long copied vault instructions.
- Keep as adapter deltas only when needed: runtime-specific instructions for Claude, Gemini, Copilot, or another adapter.
- Ask about: content that could be either repo operating policy or private/vault-owned context.

Act without asking when the cleanup is clearly low-risk: compact copied vault navigation into a small vault-link block, remove private/local details from tracked files, add missing `.gitignore` coverage for local files, normalize verbose adapters that only duplicate `AGENTS.md`, or move a child repo/folder map from `AGENTS.md` to an existing or explicitly requested `WORKSPACE.md` when the destination owner is clear.

Ask before removing or moving ambiguous workspace-specific rules, moving commands or safety rules out of `AGENTS.md`, changing a confirmed scope link, merging duplicate marker blocks, replacing a substantial runtime-specific adapter, converting between shared/local modes when the user has not made sharing intent clear, resolving conflicting `AGENTS.md` and `WORKSPACE.md` child maps, or creating a missing referenced `WORKSPACE.md`.

Use this ask-vs-act rule:

- Act when a signal is mechanical and the destination is clear: add missing `.gitignore` coverage for local-only files, remove private paths from tracked files by moving them to an existing ignored local file, compact copied vault navigation into a small vault-link block, normalize adapters that exactly duplicate `AGENTS.md`, move clear child repo/folder inventory into an owned `WORKSPACE.md`, or re-sync a stale `AGENTS.override.md` (`codexOverrideOutOfSyncFiles`) by replacing its copied body with the current `AGENTS.md` while preserving the local `ariadne:workspace-vault-link` block untouched.
- Ask when ownership or target is ambiguous: content could be workspace policy or private context, local-only mode would remove collaborator guidance, multiple vaults or scopes are plausible, a scope-specific link lacks current-turn confirmation, `WORKSPACE.md` is referenced but missing, child maps conflict, a nested `AGENTS.md` may contain meaningful local deltas, Hermes-specific context shadows `AGENTS.md` without clear intent, or marker blocks are duplicate or malformed.
- Stop rather than guess when a marker-managed region is malformed, when more than one Ariadne vault-link block exists, or when changing `AGENTS.override.md` would replace shared Codex guidance.

When `AGENTS.md` references `WORKSPACE.md`, cross-file consistency is required: a missing referenced `WORKSPACE.md` is a stop-and-ask finding, child repo/folder maps should live in `WORKSPACE.md` when it exists or is explicitly requested, and `AGENTS.md` should keep only a short pointer plus agent behavior. If both files mention child names, use checker facts as evidence; ask before resolving conflicting maps.

## Instruction-File Audit and Attestation

Whenever you create or update workspace instruction files, audit them against the shared rubric in `references/instruction-file-rules.md` and attest the result. The rubric has two rule groups: open-standard conformance (from the `AGENTS.md` standard) and agentic cross-runtime portability (adapters, override sync, marker discipline, no leakage). Each rule is either mechanical (a deterministic checker signal) or judgment (you assess and report).

Run the audit like this:

1. Run the checker and read the mechanical signals: `oversizedForStandardFiles`, `agentsMissingCommandGuidance`, `codexOverrideOutOfSyncFiles`, `adapterDuplicateFiles`, `privatePathLeakFiles`, `localFilesMissingGitignore`, Hermes override signals, marker signals, and `WORKSPACE.md` reference signals.
2. Assess the judgment rules by reading the canonical `AGENTS.md`: command-first ordering with exact invocations, version-pinned specifics over generic phrasing, explicit always/ask-first/never boundaries, a stated done/closure check, and hand-written project-specific content rather than generic boilerplate.
3. Fix the low-risk mechanical violations that this skill already acts on: re-sync a stale override, add missing `.gitignore` coverage, thin duplicated adapters, move private paths to ignored local files, and compact copied vault navigation. Report oversize and missing-command findings; only rewrite substantive `AGENTS.md` content after asking.
4. Attest in the completion report only. Do not write attestation markers, badges, or audit blocks into the user's files. State which rules pass, which are flagged, and which flagged rules you fixed versus left for the user.

Apply the audit to both new and existing files. New files: audit before reporting done and attest compliance. Existing/older files: run the same audit on every update, auto-fix the low-risk mechanical gaps, and report the judgment gaps that predate the rubric so the user can decide. Do not silently rewrite older files to satisfy a judgment rule; surface it and ask.

## Ariadne Vault Links

Use a marker-managed block for the workspace-to-vault bridge:

```md
<!-- ariadne:workspace-vault-link:start -->
...
<!-- ariadne:workspace-vault-link:end -->
```

Update only inside this block when refreshing the Ariadne link. Preserve all user content outside the block.

If an existing file has an older Ariadne vault-link marker block from a previous marker convention, migrate that block in place to `ariadne:workspace-vault-link` instead of appending a second block. If multiple Ariadne vault-link marker blocks exist, stop and ask whether to merge or remove duplicates.

The block may say how to consult registered vaults and which vault or scope is relevant, but it must not make the workspace file the source of truth for vault navigation.

Rules:

- A scope-specific block uses a closed three-field identity: one lower-kebab `scope_id`, one normalized vault-relative NFC `scope_path`, and one `Related Ariadne scope: [[...]]` target exactly equal to that path. `root` alone may use path `.`, and `.` is invalid for every other ID. Absolute paths, traversal, control characters, reserved segments, duplicate fields, malformed links, unequal path/link values, and every partial field combination are invalid.
- The return shape includes `workspaceScopeIdentityByFile` entries with `scopeId`, `scopePath`, `linkedScopePath`, `canonicalScopePath`, and `verification` (`invalid`, `unverified`, `ambiguous`, `unknown-id`, `stale`, or `current`); arrays `invalidScopeIdentityFiles`, `unverifiedScopeIdentityFiles`, `ambiguousScopeIdFiles`, `unknownScopeIdFiles`, and `staleScopePathFiles`; `scopeIdentityVaultConfirmed`; and exact `scopeLinkRepairGuidance`.
- `unknownScopeIdFiles` means a valid supplied ID is absent from the confirmed inventory. `staleScopePathFiles` means both marker paths agree but differ from that ID's canonical inventory path. Repair a stale path only after confirming the same unique `scope_id`: update only the declared path and linked target inside the marker to `canonicalScopePath`. Do not replace vault navigation or rewrite surrounding user content.
- If the link names a vault or scope, it must come from the current prompt, existing workspace instructions, or explicit user confirmation.
- If multiple registered vaults are plausible, ask before writing the link.
- Scope-specific links require a current-turn explicit target or user confirmation.
- Global discovery registers vaults, not individual project scopes.
- For private paths, client names, personal workflow defaults, or maintainer-only routing, use local ignored files instead of tracked workspace files.
- Add a vault-link block only when the user asks for Ariadne/vault context, existing files contain Ariadne markers, `~/.ariadne` registry references, `ariadne:*` skill triggers, registered-vault instructions, Vault Updates sections, or a local file with a vault link. A bare `Obsidian` mention is weak context only; ask or abstain instead of writing a link.
- When adding closeout guidance, place it inside marker-managed vault-link content and only when a vault link is being written. Mention `ariadne:closeout` only for meaningful completed work, checkpoints, handoffs, releases, evaluations, incidents, durable decisions, or safe-to-close questions; do not run closeout for every tiny edit.

## Creation Workflow

1. Identify the workspace root. Prefer the current directory when it is already the root; otherwise use the nearest `.git` root or ask.
2. Read existing workspace instruction files and `.gitignore`.
3. Inspect high-signal workspace files to infer workspace name, commands, tests, and public-safe context.
4. Run the checker when existing file shape, Git state, or marker state is unclear.
5. Decide sharing mode: shared, local-only, shared plus local, or non-Git portable.
6. Decide the runtime file set.
7. Decide whether the Ariadne connection belongs in tracked files, local ignored files, or both.
8. Run the proactive maintenance pass before writing.
9. If vault or scope target is ambiguous, ask before writing.
10. Create or update files using the patterns reference.
11. Add local-only filenames to `.gitignore` when local files exist or are created in a Git workspace.
12. Rerun the checker and inspect touched files.
13. Run the instruction-file audit against the rubric and attest the result.
14. Report which files changed, which mode was used, which checker signals remain, the audit attestation, and which context is intentionally left for the vault or local-only files.

## Update Workflow

When files already exist:

1. Preserve useful workspace-specific instructions.
2. Run the sharing-mode check and proactive maintenance pass.
3. Run the checker when marker state, local-file ignore coverage, adapter duplication, or private-path leakage is unclear.
4. Replace the Ariadne marker block in place when exactly one block exists.
5. Add a marker block only when the user asked for an Ariadne/vault connection or existing files clearly intend one.
6. Refuse to guess if duplicate or malformed Ariadne marker blocks exist. Name the markers, say which file contains them, and ask whether to merge, remove duplicates, or leave the file unchanged before editing.
7. Compact duplicated vault navigation, private/local details, and adapter duplication when the ownership is clear.
8. If `AGENTS.md` references `WORKSPACE.md`, ensure `WORKSPACE.md` owns child repo/folder inventory and `AGENTS.md` is only a pointer plus agent rules. Ask on missing referenced files or conflicting maps.
9. Avoid converting to a new adapter layout unless the user asked for normalization, the current files duplicate large instruction blocks, or the existing layout conflicts with the selected sharing mode.
10. If `AGENTS.override.md` exists, keep it in sync with `AGENTS.md`. When the checker reports `codexOverrideOutOfSyncFiles`, replace the copied body with the current `AGENTS.md` and preserve the local `ariadne:workspace-vault-link` block. Whenever you edit tracked `AGENTS.md`, refresh the override body in the same run.
11. Rerun the checker and inspect touched files.
12. Run the instruction-file audit against the rubric, auto-fix low-risk mechanical gaps, and attest the result in the report before reporting completion.

## Global Discovery

If machine-level discovery is absent or stale, offer `ariadne:global-discovery`. Do not silently modify global agent files from this skill.

When called from outside a clear workspace:

- If the user asks for global discovery, route to `ariadne:global-discovery`.
- If the user asks to initialize workspace instruction files, ask for the workspace folder or use an explicit path from the prompt.
- If multiple registered vaults plausibly contain the project context, show top matches and ask which one should link to the project.

## Related Skills

- Use `ariadne:global-discovery` for `~/.ariadne` registry files and global adapter blocks.
- Use `ariadne:vault` to bootstrap a Markdown knowledge vault with an optional Obsidian-compatible view layer.
- Use `ariadne:scope` to create or wire a vault scope before linking a project to it.
- Use `ariadne:navigation` when the vault needs new hubs or routing for the project.