diff --git a/.agents/CONTEXT.md b/.agents/CONTEXT.md deleted file mode 100644 index c5e57b1..0000000 --- a/.agents/CONTEXT.md +++ /dev/null @@ -1,58 +0,0 @@ -# Skills - -A personal collection of agent skills packaged through Nix. -The language below covers the knowledge-mining pipeline — the `consume` (write) and `wiki` (read) pair that move knowledge into and out of the user's Obsidian vault. - -## Language - -### Places - -**Vault**: -The user's personal Obsidian knowledge base, read through `wiki` and written only within one area by `consume`. -_Avoid_: notes folder, Obsidian - -**Pull channel**: -The vault area holding reusable knowledge, retrieved on demand by a future agent that goes looking for it. -_Avoid_: wiki proper, retrieval store - -**Push channel**: -The target's own always-loaded documentation (`AGENTS.md`), whose value is being in front of an agent unprompted. -_Avoid_: proactive store, always-on docs, `CLAUDE.md` - -**Target**: -The single source `consume` ingests in one run — currently a project directory. -_Avoid_: source (reserve for the raw material within the target), input - -**Compatibility surface**: -A legacy harness-specific file or directory that points an older agent harness to the canonical agent-neutral surface. -_Avoid_: duplicate source, mirror - -### Acceptance axes - -**Generalizes**: -A mined fact's property of teaching something true on a *different* target, not only the one it came from. -_Avoid_: reusable, transferable (use only informally) - -**Trigger-able**: -A mined fact's property of having a recognizable symptom, error, or task that would send a future agent to retrieve it. -_Avoid_: searchable, useful - -### What a source line yields - -**General lesson**: -The transferable principle split out of a source line. -_Avoid_: concept, insight - -**Specific residue**: -The concrete, target-only answer left after the general lesson is split off. -_Avoid_: leftover, detail - -**Proactive rule**: -A mined fact that generalizes but is not trigger-able — a verification-discipline or design-stance rule whose value is firing unprompted. -_Avoid_: habit, guideline - -### Planning - -**Contribution map**: -The many-to-many record of which consumed file fed which planned note, with the exact contributing sections, including files that fed nothing. -_Avoid_: provenance table, coverage map diff --git a/.agents/adr/0001-consume-writes-target-push-channel.md b/.agents/adr/0001-consume-writes-target-push-channel.md deleted file mode 100644 index 070d686..0000000 --- a/.agents/adr/0001-consume-writes-target-push-channel.md +++ /dev/null @@ -1,17 +0,0 @@ -# Consume writes the target's push channel, not only the vault - -`consume` was scoped to write only inside the vault's `01 sources/claude/` area. -A real run showed that most mined knowledge is not wiki-shaped — specific residue and proactive rules belong in the target's own always-loaded `AGENTS.md` — and dropping it lost real signal, while redoing the target-doc edits by hand after each run was toil. -We decided `consume` writes a second channel outside the vault, the target's `AGENTS.md`, rather than only planning those edits for the user to apply. - -## Considered Options - -- **Plan-only** — spell the target-doc edits out in the report and have the user apply them by hand. - Rejected: the whole value is not redoing what the run already worked out. -- **Auto-write both channels (chosen)** — apply the target edits too, but present them as a distinct, independently-approvable write-set under the one plan-approval gate, so a write outside the vault is never a surprise. - -## Consequences - -`consume`'s blast radius now includes files outside the vault and outside the spec/task scaffolding it deletes. -The plan-approval gate is what keeps that safe: the target write-set is approved separately from the vault write-set, and a declined target write-set degrades to flagged suggestions. -Destructive edits to `AGENTS.md` are gated on capture — an entry is removed or trimmed only when its general part is present in the wiki. diff --git a/.agents/adr/0002-agent-neutral-project-surfaces.md b/.agents/adr/0002-agent-neutral-project-surfaces.md deleted file mode 100644 index 8d85aec..0000000 --- a/.agents/adr/0002-agent-neutral-project-surfaces.md +++ /dev/null @@ -1,5 +0,0 @@ -# Agent-neutral project surfaces - -This repository uses `AGENTS.md` and `.agents/` as the canonical project instruction, context, ADR, spec, task, and project-local skill surfaces. -Claude Code compatibility remains through `CLAUDE.md` and `.claude/` shims because existing harnesses and skills still discover those paths. -The compatibility surfaces are pointers, not duplicate sources of truth, so future agents have one canonical place to read and update. diff --git a/.claude/CONTEXT.md b/.claude/CONTEXT.md deleted file mode 120000 index 2e1f285..0000000 --- a/.claude/CONTEXT.md +++ /dev/null @@ -1 +0,0 @@ -../.agents/CONTEXT.md \ No newline at end of file diff --git a/.claude/adr b/.claude/adr deleted file mode 120000 index 79553a9..0000000 --- a/.claude/adr +++ /dev/null @@ -1 +0,0 @@ -../.agents/adr \ No newline at end of file diff --git a/skills/grill/SKILL.md b/skills/grill/SKILL.md index cb08630..38b176e 100644 --- a/skills/grill/SKILL.md +++ b/skills/grill/SKILL.md @@ -21,10 +21,11 @@ This holds even when another skill invoked grill: grill delivers its summary and ## 1. Select the mode -Look for a context file, in order: `.agents/CONTEXT.md`, then `.claude/CONTEXT.md`. -The first that exists wins, and its directory owns the ADRs too (`.agents/adr/` or `.claude/adr/`). -If both files exist and resolve to different real files, stop and ask which is authoritative rather than guessing. -If `.claude/CONTEXT.md` is a compatibility symlink to `.agents/CONTEXT.md`, use `.agents/CONTEXT.md`. +Resolve the artifact root with `$(xdg-user-dir DOCUMENTS)/ai-artifacts`. +Use the lowercase basename of the current working directory as ``. +The context file is `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects//CONTEXT.md`. +Its sibling `adr/` directory owns the project's ADRs. +Create the project directory and `adr/` only when a write requires them. - **Domain Modeling Mode** — a context file was found. Run the interview and maintain the project's domain model as terms settle (see [Domain Modeling Mode](#domain-modeling-mode)). @@ -32,8 +33,8 @@ If `.claude/CONTEXT.md` is a compatibility symlink to `.agents/CONTEXT.md`, use Run the interview with no document side effects. - **Clarification** — no context file, 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, create it and continue in Domain Modeling Mode; if no, continue in Free Mode. - A created file goes in the sole existing agent directory (`.agents/` or `.claude/`), or in `.agents/` when neither exists yet. + If yes, create it at `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects//CONTEXT.md` and continue in Domain Modeling Mode. + If no, continue in Free Mode. Done when the interview is running in Domain Modeling Mode or Free Mode. @@ -79,7 +80,7 @@ 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 in the context file's `adr/` directory, numbered one past the highest already there (`0001-slug.md`), and can be a single paragraph: +A recorded decision lives in the sibling `adr/` directory, numbered one past the highest already there (`0001-slug.md`), and can be a single paragraph: > # {Short title of the decision} >