diff --git a/skills/grill/SKILL.md b/skills/grill/SKILL.md index 8d78261..9889423 100644 --- a/skills/grill/SKILL.md +++ b/skills/grill/SKILL.md @@ -21,10 +21,12 @@ This holds even when another skill invoked grill: grill delivers its summary and ## 1. Select the mode -Resolve the artifact root with `$(xdg-user-dir DOCUMENTS)/ai-artifacts`. -Use the lowercase basename of the current working directory as `` and inspect `projects//` directly for its numbered `-context.md` artifact. -Read the artifact root's `AGENTS.md` before any artifact write. -Create the project directory only when a write requires it. +Resolve the artifact destination before looking for or creating artifacts. +Default to `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/` when the AI artifacts vault is available, where `` is the lowercase basename of the current working directory. +If that vault is unavailable, fall back to `./docs` in the current project. +Create the destination directory only when a write requires it. +Read the destination's `AGENTS.md` before any artifact write. +Inspect the destination directly for its context artifact, using the destination naming convention instead of assuming a filename. - **Domain Modeling Mode** — exactly one context artifact was found. Run the interview and maintain the project's domain model as terms settle (see [Domain Modeling Mode](#domain-modeling-mode)). @@ -32,7 +34,7 @@ Create the project directory only when a write requires it. Run the interview with no document side effects. - **Clarification** — no context artifact was found, but the plan introduces terms specific to this project that later work will need to use consistently — the kind of terms [`CONTEXT-FORMAT.md`](CONTEXT-FORMAT.md) admits, not general programming concepts. Before interviewing, ask whether to create a glossary. - If yes, allocate the next vault identifier through `.counter`, create `--context.md`, and continue in Domain Modeling Mode. + If yes, choose the context artifact filename from the destination's `AGENTS.md` and nearby artifact convention, allocate any required identifier, and continue in Domain Modeling Mode. If no, continue in Free Mode. Stop and report the conflicting paths if more than one matching context artifact exists. @@ -80,8 +82,8 @@ Offer to record an architectural decision only when all three hold: 3. **The result of a real trade-off** — there were genuine alternatives and you picked one for specific reasons. If any of the three is missing, skip it. -A recorded decision lives directly in the project's flat artifact directory. -Allocate its identifier through the vault-root `.counter` and name it `---adr.md` according to the vault convention. +A recorded decision lives directly in the resolved artifact destination. +Choose its filename from the destination's `AGENTS.md` and nearby artifact convention, allocating an identifier only when that convention requires one. It can be a single paragraph: > # {Short title of the decision} diff --git a/skills/prototype/SKILL.md b/skills/prototype/SKILL.md index 15f9d0d..1d79495 100644 --- a/skills/prototype/SKILL.md +++ b/skills/prototype/SKILL.md @@ -50,20 +50,27 @@ Done when the user has reached an explicit verdict or stated that the prototype Commit the complete prototype to a throwaway branch outside main. The branch is the primary source. -Resolve the AI artifacts vault through `$(xdg-user-dir DOCUMENTS)/ai-artifacts` and read its `AGENTS.md` before writing. -Use the lowercase basename of the current working directory as the project. +Resolve the artifact destination before naming the file. +When the caller provides a destination directory, use it exactly. +Otherwise, default to `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/` when the AI artifacts vault is available, where `` is the lowercase basename of the current working directory. +If that vault is unavailable, fall back to `./docs` in the current project. +Create the destination directory only when needed. -When the caller provides an allocated filename and `parent`, use them exactly and do not advance `.counter`. +Before choosing a filename, read the destination's `AGENTS.md`. +Use the naming convention declared there, or infer it from nearby artifacts when the file delegates naming to local context. +Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it. +If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention. + +When the caller provides an allocated filename and `parent`, use them exactly and do not advance any counter. Create only the Prototype artifact and leave the parent artifact unchanged. -Otherwise, allocate the next vault-sequence identifier and name the artifact `---prototype.md`. -Include `parent` only when an earlier artifact directly caused the prototype. +Otherwise, allocate any identifier required by the destination convention and include `parent` only when an earlier artifact directly caused the prototype. The Prototype artifact links the throwaway branch and preserves the question, run instructions, verdict, and branch-appropriate evidence: - UI evidence uses screenshots. - Logic evidence uses useful code snippets and, where needed, a short interaction transcript. -Done when the complete prototype is committed outside main and exactly one Prototype artifact preserves the result according to the vault convention. +Done when the complete prototype is committed outside main and exactly one Prototype artifact preserves the result according to the destination convention. ## 4. Fold in the decision when permitted diff --git a/skills/research/SKILL.md b/skills/research/SKILL.md index 7e21895..d6cab70 100644 --- a/skills/research/SKILL.md +++ b/skills/research/SKILL.md @@ -1,6 +1,6 @@ --- name: research -description: Investigate a question against high-trust primary sources and capture the cited findings as a Research artifact in the AI artifacts vault. Use when a topic needs documentation, API, specification, source-code, or other reading legwork. +description: Investigate a question against high-trust primary sources and capture the cited findings as a Research artifact. Use when a topic needs documentation, API, specification, source-code, or other reading legwork. --- # Research @@ -11,16 +11,22 @@ Isolation and concurrency belong to the caller. ## 1. Resolve the artifact -Resolve the vault through `$(xdg-user-dir DOCUMENTS)/ai-artifacts` and read its `AGENTS.md` before writing. -Use the lowercase basename of the current working directory as the project and create its flat `projects//` directory only when needed. +Resolve the artifact destination before naming the file. +When the caller provides a destination directory, use it exactly. +Otherwise, default to `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/` when the AI artifacts vault is available, where `` is the lowercase basename of the current working directory. +If that vault is unavailable, fall back to `./docs` in the current project. +Create the destination directory only when needed. -When the caller provides an allocated filename and `parent`, use them exactly and do not advance `.counter`. +Before choosing a filename, read the destination's `AGENTS.md`. +Use the naming convention declared there, or infer it from nearby artifacts when the file delegates naming to local context. +Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it. +If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention. + +When the caller provides an allocated filename and `parent`, use them exactly and do not advance any counter. Create only the Research artifact and leave the parent artifact unchanged. +Otherwise, allocate any identifier required by the destination convention and include `parent` only when an earlier artifact directly caused the research. -Otherwise, allocate the next vault-sequence identifier through `.counter` and name the artifact `---research.md`. -Include `parent` only when an earlier artifact directly caused the research. - -Done when one authoritative output path and its metadata are settled according to the vault convention. +Done when one authoritative output path and its metadata are settled according to the destination convention. ## 2. Investigate the question @@ -33,7 +39,7 @@ Done when the question is answered as far as primary evidence permits and every ## 3. Write the Research artifact -Write the findings to the resolved Markdown file and follow the vault's artifact conventions. +Write the findings to the resolved Markdown file and follow the destination's artifact conventions. Keep the question, findings, limitations, and citations sufficient for a future reader to evaluate the result without reconstructing the research session. Do not create a source dump or research log. diff --git a/skills/wayfinder/ARTIFACTS.md b/skills/wayfinder/ARTIFACTS.md index d2d9d16..1fd42bb 100644 --- a/skills/wayfinder/ARTIFACTS.md +++ b/skills/wayfinder/ARTIFACTS.md @@ -2,24 +2,23 @@ ## Resolve the project -Resolve the vault through `$(xdg-user-dir DOCUMENTS)/ai-artifacts` and read its `AGENTS.md` before any artifact write. -Use the lowercase basename of the current working directory as the project slug. -Create `projects//` when a new project first needs a map. -Keep the project directory flat. +Resolve the artifact destination before naming files. +When the caller provides a destination directory, use it exactly. +Otherwise, default to `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/` when the AI artifacts vault is available, where `` is the lowercase basename of the current working directory. +If that vault is unavailable, fall back to `./docs` in the current project. +Create the destination directory only when a new artifact requires it. +Read the destination's `AGENTS.md` before any artifact write. -Allocate every new artifact through the vault-root `.counter`. +Allocate identifiers only when the destination convention requires them. ## Names -Use an effort slug that identifies one durable effort and is not reused for another map in the project. -Use these filenames: +Use an effort name that identifies one durable effort and is not reused for another map in the project. +Choose each filename from the destination's `AGENTS.md` and nearby artifact convention. +Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it. +If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention. -- Map: `--map.md` -- Ticket: `---ticket.md` -- Research result: `---research.md` -- Prototype result: `---prototype.md` - -Refer to artifacts through bare Obsidian wikilinks such as `[[042-wayfinder-session-auth-ticket]]`. +Refer to artifacts through the link style used by the destination. Never use a bare identifier as a human-facing reference. ## Map @@ -67,7 +66,8 @@ Map status is `open` while any live ticket or fog remains and `complete` when ne The Frontier is a derived navigation index and the map's only artifact-link section. Ticket metadata is authoritative. Repair the Frontier whenever it is missing, stale, or inconsistent with ticket state. -Order Frontier links by artifact identifier unless the user chooses another ticket. +Order Frontier links by the destination's declared ordering unless the user chooses another ticket. +Fall back to filename order when no ordering is declared. Under **Decisions so far**, record one concise, self-contained decision for each resolved ticket. Do not link the ticket or its result artifacts, identify the ticket, or copy supporting detail from the canonical resolution into the map. @@ -133,7 +133,7 @@ An out-of-scope ticket is closed, while **Out of scope** states the excluded wor A Grill or Task ticket stores its canonical result under a `## Resolution` section in that ticket. Research and Prototype tickets leave their question in the ticket and store the result in a child artifact whose `parent` points to the ticket. -When invoking `research` or `prototype`, provide the project artifact directory, allocated filename, and ticket wikilink that the result must use as its `parent`. +When invoking `research` or `prototype`, provide the resolved artifact destination, the filename chosen from that destination's convention, and the ticket link that the result must use as its `parent`. The called skill creates the result artifact but does not edit the ticket or map. The coordinating Wayfinder agent validates the returned artifact, marks the ticket resolved, and updates the map. If a called skill cannot honor this artifact contract, leave the ticket unresolved and record the incompatibility instead of silently storing the result elsewhere. @@ -144,5 +144,5 @@ Do not duplicate those relationships through per-artifact Next sections. ## Concurrent writes Re-read every shared artifact immediately before editing it. -After concurrent workers return, detect duplicate identifiers, preserve pre-existing artifacts, renumber current outputs, update their wikilinks, and advance `.counter` as required by the vault convention. +After concurrent workers return, detect duplicate identifiers or filenames, preserve pre-existing artifacts, rename current outputs when required by the destination convention, update their links, and advance any counter required by that convention. Recompute the Frontier only after returned artifacts and ticket states have been reconciled. diff --git a/skills/wayfinder/SKILL.md b/skills/wayfinder/SKILL.md index af338d7..47be7e7 100644 --- a/skills/wayfinder/SKILL.md +++ b/skills/wayfinder/SKILL.md @@ -11,7 +11,7 @@ Wayfinding charts the way to a **destination** rather than charging at it. It creates a durable map of questions whose resolutions are decisions, findings, prototypes, or completed prerequisites rather than slices of the destination work. Read [`ARTIFACTS.md`](ARTIFACTS.md) before charting or working a map. -It is the single source of truth for how maps, tickets, claims, blocking, resolutions, and the Frontier live in the AI artifacts vault. +It is the single source of truth for how maps, tickets, claims, blocking, resolutions, and the Frontier live in the resolved artifact destination. ## Plan, don't do @@ -25,8 +25,8 @@ It may be a spec to hand off, a decision to lock before planning, or a change wh ## Refer by name -Refer to every map and ticket by its human-readable title as a wikilink, never by a bare identifier, filename, or slug. -The artifact identifier remains inside the wikilink without standing in for the name. +Refer to every map and ticket by its human-readable title using the destination's link style, never by a bare identifier, filename, or slug. +When the destination convention includes an artifact identifier, keep it inside the link without letting it stand in for the name. ## Ticket types @@ -101,7 +101,7 @@ Never resolve more than one non-Research ticket in a session. Done when the destination, Notes, prior decisions, fog, scope boundary, and current Frontier agree with the artifacts. 2. **Claim one ticket.** Use the user-named ticket when it is actionable. - Otherwise take the first Frontier ticket in artifact-identifier order. + Otherwise take the first Frontier ticket in the destination's declared ordering, falling back to filename order when no ordering is declared. Persist the claim before doing any work. Done when exactly one unblocked ticket records this session's claim with `status: claimed`. 3. **Resolve by type.**