Compare commits
5 Commits
b541251f98
...
fbd009337d
| Author | SHA1 | Date | |
|---|---|---|---|
| fbd009337d | |||
| 920517e623 | |||
| 6bb3242e7f | |||
| fb16c891b2 | |||
| 5886017976 |
@@ -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
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
@@ -1 +0,0 @@
|
||||
../.agents/CONTEXT.md
|
||||
@@ -1 +0,0 @@
|
||||
../.agents/adr
|
||||
@@ -1 +0,0 @@
|
||||
../.agents/spec
|
||||
@@ -1 +0,0 @@
|
||||
../.agents/tasks
|
||||
3
.gitignore
vendored
3
.gitignore
vendored
@@ -11,6 +11,7 @@ tests/.reports/
|
||||
|
||||
# BEGIN mkSkillsShellHook
|
||||
# Generated by mkSkillsShellHook. Nix-delivered skill symlinks, kept out of git.
|
||||
.claude/skills
|
||||
.agents/skills/gitea-axi
|
||||
.agents/skills/benchmark-skill
|
||||
# END mkSkillsShellHook
|
||||
|
||||
|
||||
10
AGENTS.md
10
AGENTS.md
@@ -1,12 +1,12 @@
|
||||
# skills
|
||||
|
||||
Personal agent skills packaged through Nix.
|
||||
The domain glossary lives in `.agents/CONTEXT.md`.
|
||||
The domain glossary lives at `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/skills/CONTEXT.md`.
|
||||
|
||||
## Conventions
|
||||
|
||||
- `AGENTS.md` and `.agents/` are canonical for agent-facing project instructions, context, ADRs, specs, tasks, and project-local skill links.
|
||||
`CLAUDE.md` and `.claude/` exist only as Claude Code compatibility surfaces.
|
||||
- `AGENTS.md` is canonical for project instructions.
|
||||
Context, ADRs, specs, and tasks live under `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/skills/`.
|
||||
- Skill source lives under `skills/<name>/`.
|
||||
Do not edit generated links under `.agents/skills/` or `.claude/skills/` as source.
|
||||
- Run `nix flake check` before considering a repository-wide change complete.
|
||||
@@ -16,5 +16,5 @@ The domain glossary lives in `.agents/CONTEXT.md`.
|
||||
|
||||
## Gotchas
|
||||
|
||||
- The vault write area remains `01 sources/claude/` for now.
|
||||
That path is a historical vault taxonomy and is not the canonical project metadata namespace.
|
||||
- `python3` is supplied by the default Nix dev shell, not the ambient environment.
|
||||
Enter `nix develop` before running Python-based project tools.
|
||||
|
||||
45
flake.lock
generated
45
flake.lock
generated
@@ -18,7 +18,49 @@
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"gitea-axi": {
|
||||
"inputs": {
|
||||
"home-manager": "home-manager",
|
||||
"nixpkgs": [
|
||||
"nixpkgs"
|
||||
]
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1785340481,
|
||||
"narHash": "sha256-GSxdQ7w8yYfZnfkXUuZ2fYIKibe9ZU8xDGyqpeTb2tE=",
|
||||
"ref": "refs/heads/main",
|
||||
"rev": "627fc9a32bb80d97923540fc0d3e9661961462ba",
|
||||
"revCount": 83,
|
||||
"type": "git",
|
||||
"url": "https://git.alexion.dev/alexion/gitea-axi"
|
||||
},
|
||||
"original": {
|
||||
"type": "git",
|
||||
"url": "https://git.alexion.dev/alexion/gitea-axi"
|
||||
}
|
||||
},
|
||||
"home-manager": {
|
||||
"inputs": {
|
||||
"nixpkgs": [
|
||||
"gitea-axi",
|
||||
"nixpkgs"
|
||||
]
|
||||
},
|
||||
"locked": {
|
||||
"lastModified": 1784588016,
|
||||
"narHash": "sha256-ouZe80aWEhMLVMkqICFDN+JUw+0FJtCr/bh+hHtRtMg=",
|
||||
"owner": "nix-community",
|
||||
"repo": "home-manager",
|
||||
"rev": "deeb6b7eb7e0c44ae1819c051ce175bd92a85100",
|
||||
"type": "github"
|
||||
},
|
||||
"original": {
|
||||
"owner": "nix-community",
|
||||
"repo": "home-manager",
|
||||
"type": "github"
|
||||
}
|
||||
},
|
||||
"home-manager_2": {
|
||||
"inputs": {
|
||||
"nixpkgs": [
|
||||
"nixpkgs"
|
||||
@@ -57,7 +99,8 @@
|
||||
"root": {
|
||||
"inputs": {
|
||||
"flake-utils": "flake-utils",
|
||||
"home-manager": "home-manager",
|
||||
"gitea-axi": "gitea-axi",
|
||||
"home-manager": "home-manager_2",
|
||||
"nixpkgs": "nixpkgs"
|
||||
}
|
||||
},
|
||||
|
||||
21
flake.nix
21
flake.nix
@@ -4,6 +4,11 @@
|
||||
inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
|
||||
inputs.flake-utils.url = "github:numtide/flake-utils";
|
||||
|
||||
inputs.gitea-axi = {
|
||||
url = "git+https://git.alexion.dev/alexion/gitea-axi";
|
||||
inputs.nixpkgs.follows = "nixpkgs";
|
||||
};
|
||||
|
||||
# Present only so `nix flake check` can evaluate `homeModules.default` against
|
||||
# real home-manager (the home-manager-module check). Its nixpkgs follows this
|
||||
# flake's, so the module is checked against the same nixpkgs-and-home-manager
|
||||
@@ -14,7 +19,7 @@
|
||||
inputs.home-manager.inputs.nixpkgs.follows = "nixpkgs";
|
||||
|
||||
outputs =
|
||||
{ self, nixpkgs, flake-utils, home-manager }:
|
||||
{ self, nixpkgs, flake-utils, home-manager, gitea-axi }:
|
||||
let
|
||||
mkSkill = import ./lib/mk-skill.nix;
|
||||
mkSkillsShellHook = import ./lib/mk-skills-shell-hook.nix;
|
||||
@@ -94,12 +99,18 @@
|
||||
};
|
||||
|
||||
# A working shell for developing skills in this repo.
|
||||
# python3 runs the benchmark skill's deterministic core.
|
||||
# The benchmark-skill is placed into ./.agents/skills/ on entry, with
|
||||
# Python runs the benchmark core, while gitea-axi backs its project skill.
|
||||
# Both project skills are placed into ./.agents/skills/ on entry, with
|
||||
# ./.claude/skills as a compatibility symlink.
|
||||
devShells.default = pkgs.mkShell {
|
||||
packages = [ pkgs.python3 ];
|
||||
shellHook = mkSkillsShellHook [ (skillPackages pkgs).benchmark-skill ];
|
||||
packages = [
|
||||
pkgs.python3
|
||||
gitea-axi.packages.${system}.gitea-axi
|
||||
];
|
||||
shellHook = mkSkillsShellHook [
|
||||
gitea-axi.packages.${system}.gitea-axi-skill
|
||||
(skillPackages pkgs).benchmark-skill
|
||||
];
|
||||
};
|
||||
}
|
||||
);
|
||||
|
||||
@@ -1,15 +1,15 @@
|
||||
---
|
||||
name: consume
|
||||
description: "Consume a project (or, later, another source) into the agent's personal wiki — distil generalized, transferable knowledge from it into the Obsidian vault's agent-owned area, then clear the consumed scaffolding. Deliberate: run as /skill:consume [target], never automatically."
|
||||
description: "Consume a project (or, later, another source) into the agent's AI-managed wiki — distil generalized, transferable knowledge into the artifact store, then clear the consumed scaffolding. Deliberate: run as /skill:consume [target], never automatically."
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# consume
|
||||
|
||||
Mine a source for its knowledge, routing each fact to the agent's own wiki or the target's always-loaded docs, then clear the consumed scaffolding once the knowledge is safely captured.
|
||||
Mine a source for its knowledge, routing each fact to the agent's AI-managed wiki or the target's always-loaded docs, then clear the consumed scaffolding once the knowledge is safely captured.
|
||||
|
||||
`/consume [target]` ingests one target — a filesystem path, defaulting to the current directory — and distils what it mines into two channels.
|
||||
It is the write side of a pair with the read-only `/wiki`, which it invokes to read the rest of the vault.
|
||||
It is the write side of a pair with the read-only `/wiki`, which it invokes to read the rest of the AI-managed wiki.
|
||||
|
||||
The **pull channel** is the wiki — reusable knowledge a future agent retrieves on demand — and a fact earns a note there only if it both **generalizes** past the target it came from and is **trigger-able**, meaning some symptom, error, or task would send that agent looking for it.
|
||||
The **push channel** is the target's own always-loaded documentation, its `AGENTS.md`, which carries what is useful but not wiki-shaped: a concrete repo-specific answer, or a proactive rule whose value is firing unprompted.
|
||||
@@ -21,21 +21,20 @@ Nothing is written and nothing is deleted until the user approves the plan.
|
||||
|
||||
Consume writes to two channels and nowhere else.
|
||||
|
||||
The vault lives at `$(xdg-user-dir DOCUMENTS)/notes`.
|
||||
Resolve it, and if it does not exist report that the vault is unreachable and stop.
|
||||
Inside the vault, write only under `01 sources/claude/`, treating every other vault path as off-limits to writes.
|
||||
Outside the vault, the sanctioned content write is the target's own always-loaded documentation, its `AGENTS.md` — the push channel of step 6.
|
||||
If the target has Claude Code markers such as `.claude/` or `CLAUDE.md`, `consume` may also create or update `CLAUDE.md` as a compatibility shim pointing to `AGENTS.md`.
|
||||
Everything else in the target is read-only, save for that shim and for the scaffolding step 7 deletes.
|
||||
The AI-managed wiki lives at `$(xdg-user-dir DOCUMENTS)/ai-artifacts/wiki`.
|
||||
Resolve it, and if it does not exist report that the wiki is unreachable and stop.
|
||||
Write pull-channel notes only directly under that flat directory.
|
||||
Outside the wiki, the sanctioned content write is the target's own always-loaded documentation, its `AGENTS.md` — the push channel of step 6.
|
||||
Everything else in the target is read-only.
|
||||
|
||||
The harness does not apply the vault's own permission rules when you run from outside it, so enforcing the vault boundary is the skill's job.
|
||||
All reading of the wider vault goes through `/wiki` (step 3), which enforces the vault's read boundary itself.
|
||||
All reading of the wider AI-managed wiki goes through `/wiki` (step 3).
|
||||
|
||||
## 1. Select the branch
|
||||
|
||||
Resolve the artifact project directory as `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>`, where `<project>` is the lowercase basename of the target directory.
|
||||
Route the target through this ladder, first match wins:
|
||||
|
||||
- A directory containing `.agents/spec/`, `.agents/tasks/`, `.claude/spec/`, or `.claude/tasks/` → a project: follow [`project.md`](project.md).
|
||||
- An artifact project directory containing `spec/` or `tasks/` → a project: follow [`project.md`](project.md).
|
||||
- No rung matches → report that the target is not something consume knows how to read, write nothing, and stop.
|
||||
|
||||
Done when a branch file is selected, or consume has stopped on an unsupported target.
|
||||
@@ -51,8 +50,8 @@ Done when you understand what the target actually is now, from its branch's sour
|
||||
|
||||
Two reads with different jobs:
|
||||
|
||||
- Invoke `/wiki` on the concepts the target raised, to learn what the whole vault already holds — so new notes link to existing notes and hubs, and you do not re-capture knowledge the vault already has.
|
||||
- Scan `01 sources/claude/` directly for the concept notes you may need to enrich.
|
||||
- Invoke `/wiki` on the concepts the target raised, to learn what the whole AI-managed wiki already holds — so new notes link to existing notes and hubs, and you do not re-capture knowledge the wiki already has.
|
||||
- Scan the AI-managed wiki directly for the concept notes you may need to enrich.
|
||||
|
||||
Done when you know which existing notes bear on what you are about to write.
|
||||
|
||||
@@ -88,16 +87,16 @@ Done when every mined fact has a decided destination — pull note, push item, o
|
||||
Write the plan as a self-contained HTML file to the session's scratchpad directory and give the user its path.
|
||||
The report is a complete ledger of every mined fact's disposition, not only of what gets written, so the selection bar itself can be reviewed:
|
||||
|
||||
1. **Vault write-set (pull)** — each note to write or update, with its **trigger line**: one sentence naming the symptom, error, or task that would send a reader to retrieve it, and the `[[hub]]` wikilinks it belongs under.
|
||||
1. **Wiki write-set (pull)** — each note to write or update, with its **trigger line**: one sentence naming the symptom, error, or task that would send a reader to retrieve it, and the `[[hub]]` wikilinks it belongs under.
|
||||
2. **Contribution map** — for every consumed file, the notes it feeds and the exact contributing sections, including any file that fed nothing.
|
||||
3. **Push write-set (target `AGENTS.md`)** — each proactive rule and each specific residue to add, each existing entry to trim to its residue, and each pure-general entry to remove, with the exact text and where it lands.
|
||||
4. **Ref-fixes** — each file holding a reference to a spec or task file about to be deleted, and how the reference is fixed or removed. These accompany the scaffolding deletion of step 7, not the target write-set.
|
||||
5. **Flagged, not authored** — any `[[hub]]` a note links that does not yet exist under `02 tags/` or `03 index/`, and any push knowledge whose home is a hook or checklist rather than `AGENTS.md` — surfaced for the user to act on by hand.
|
||||
5. **Flagged, not authored** — any `[[hub]]` a note links that does not yet exist under `tags/`, and any push knowledge whose home is a hook or checklist rather than `AGENTS.md` — surfaced for the user to act on by hand.
|
||||
6. **Drops** — every mined fact considered and cut, one line of why each.
|
||||
|
||||
The vault write-set and the target-`AGENTS.md` write-set are approved independently: the user may accept one and decline the other.
|
||||
The wiki write-set and the target-`AGENTS.md` write-set are approved independently: the user may accept one and decline the other.
|
||||
A declined target write-set degrades to flagged suggestions — reported for the user to apply by hand, written nowhere.
|
||||
The ref-fixes and the scaffolding deletion are not a write-set to accept or decline — they follow from proceeding with the run and execute in step 7, gated only behind the vault writes.
|
||||
The ref-fixes and the scaffolding deletion are not a write-set to accept or decline — they follow from proceeding with the run and execute in step 7, gated only behind the wiki writes.
|
||||
|
||||
Stop and wait for the user's explicit approval.
|
||||
Write nothing and delete nothing until they approve.
|
||||
@@ -106,16 +105,16 @@ Done when the user has ruled on each write-set.
|
||||
|
||||
## 6. Write the notes and reconcile the push channel
|
||||
|
||||
Write the approved vault write-set first.
|
||||
Write each new note and update each changed one under the output area the branch declares, using the vault's note template (`99 meta/templates/note.md`): fill its `Tags:` line with the `[[hub]]` wikilinks the note belongs under, and its body with the distilled knowledge.
|
||||
Write the approved wiki write-set first.
|
||||
Write each new note directly under the output area the branch declares as distilled markdown.
|
||||
When updating an existing note, preserve its format.
|
||||
Link a hub whether or not its note exists yet — a dangling `[[hub]]` is a valid link and still feeds `/wiki` recall.
|
||||
|
||||
Then, if the target write-set was approved, reconcile the target's `AGENTS.md`: add the proactive rules and any specific residue the file does not already hold, trim mixed entries to their specific residue, and remove the pure-general entries.
|
||||
When Claude Code markers are present, create or update `CLAUDE.md` as a compatibility shim to `AGENTS.md` rather than duplicating the push-channel content.
|
||||
Removal is gated on capture — trim or remove an entry only when its general part is present in the wiki, written just now in this run or confirmed already there via `/wiki`, never on the intention to write a note.
|
||||
If the target write-set was declined, write nothing to the target and leave its items as the flagged suggestions of step 5.
|
||||
|
||||
Done when the approved vault notes are written and, if approved, the target's `AGENTS.md` is reconciled.
|
||||
Done when the approved wiki notes are written and, if approved, the target's `AGENTS.md` is reconciled.
|
||||
|
||||
## 7. Clear the consumed scaffolding
|
||||
|
||||
@@ -126,7 +125,7 @@ Done when the branch's cleanup has run.
|
||||
|
||||
## 8. Report
|
||||
|
||||
Tell the user what you created, updated, and left untouched across both channels — vault notes written or updated, and the target's `AGENTS.md` reconciliation applied or, if declined, left as flagged suggestions.
|
||||
Repeat the suggested new hubs and any hook-or-checklist items from the report, so the vault's `02 tags/` and `03 index/` and the target's other channels can be filled in by hand.
|
||||
Tell the user what you created, updated, and left untouched across both channels — wiki notes written or updated, and the target's `AGENTS.md` reconciliation applied or, if declined, left as flagged suggestions.
|
||||
Repeat the suggested new hubs and any hook-or-checklist items from the report, so the wiki's `tags/` and the target's other channels can be filled in by hand.
|
||||
|
||||
Done when the summary names every note written or updated, every target edit applied or flagged, and every suggested hub.
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# project branch
|
||||
|
||||
How consume reads a project target, and what it clears afterward.
|
||||
Reached from step 1 of [`SKILL.md`](SKILL.md) when the target is a directory containing `.agents/spec/`, `.agents/tasks/`, `.claude/spec/`, or `.claude/tasks/`.
|
||||
Reached from step 1 of [`SKILL.md`](SKILL.md) when the target's artifact project directory contains `spec/` or `tasks/`.
|
||||
|
||||
## Read the source, mine the specs
|
||||
|
||||
@@ -10,8 +10,7 @@ Read it thoroughly enough to understand its current state and to surface the reu
|
||||
A gotcha usually carries two separable things — a transferable principle and a concrete repo-specific answer — so surface both.
|
||||
Step 4 of SKILL.md routes the principle to the pull channel and the residue to the target's push channel.
|
||||
|
||||
`.agents/spec/` and `.agents/tasks/` are the canonical record of *why* — the reasoning, trade-offs, and intent behind what the code became.
|
||||
Claude Code compatibility paths under `.claude/spec/` and `.claude/tasks/` count as the same record only when they resolve to the canonical `.agents/` paths.
|
||||
The artifact project's `spec/` and `tasks/` directories are the canonical record of *why* — the reasoning, trade-offs, and intent behind what the code became.
|
||||
They are the richest source of the generalizable lessons, and cleanup destroys them, so mine their reasoning now or lose it.
|
||||
But they are not current fact: where a spec or task disagrees with the source, the source wins, and where one describes work later abandoned or changed, the source is what actually happened.
|
||||
|
||||
@@ -21,19 +20,14 @@ Done when you understand the project's current state from its source and have mi
|
||||
|
||||
## Output location
|
||||
|
||||
Project notes land flat under `01 sources/claude/projects/`, this branch's own area within the vault write boundary.
|
||||
This is the source-type carve — other consume source types get their own sibling areas later, so project output never mixes with them.
|
||||
Keep the area flat by default and never reorganize it.
|
||||
If the user has already grouped some notes into subfolders under `projects/`, write a new note into the matching group rather than at the top level.
|
||||
Project notes land flat under `$(xdg-user-dir DOCUMENTS)/ai-artifacts/wiki/`.
|
||||
Do not create subdirectories there.
|
||||
|
||||
## Cleanup
|
||||
|
||||
After the notes are written (step 6 of SKILL.md), delete the spec and task files that were present under `.agents/spec/` and `.agents/tasks/` when you read the project in step 2 — the scaffolding this run consumed.
|
||||
If a target only has legacy `.claude/spec/` or `.claude/tasks/`, consume those paths instead.
|
||||
If both canonical `.agents/` scaffolding and real distinct legacy `.claude/` scaffolding exist, stop and ask which is authoritative.
|
||||
A `.claude/` compatibility symlink to `.agents/` is not a distinct tree.
|
||||
After the notes are written (step 6 of SKILL.md), delete the spec and task files that were present under the artifact project's `spec/` and `tasks/` directories when you read the project in step 2 — the scaffolding this run consumed.
|
||||
A file added after that read is not swept up.
|
||||
Leave the now-empty `.agents/spec/` and `.agents/tasks/` directories in place, along with any compatibility symlinks under `.claude/`.
|
||||
Remove `spec/` or `tasks/` when the cleanup leaves it empty.
|
||||
|
||||
Deleting those files can strand references to them.
|
||||
Scan the target for pointers to each file about to be deleted — in `AGENTS.md`, `CLAUDE.md`, `CONTEXT.md`, ADRs, and sibling specs — and fix or remove each one, following the pointer wherever it lands rather than checking the push channel alone.
|
||||
Scan the target and its artifact project directory for pointers to each file about to be deleted — in `AGENTS.md`, `CONTEXT.md`, ADRs, and sibling specs — and fix or remove each one, following the pointer wherever it lands rather than checking the push channel alone.
|
||||
|
||||
@@ -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 `<project>`.
|
||||
The context file is `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>/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/<project>/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}
|
||||
>
|
||||
|
||||
@@ -1,34 +1,30 @@
|
||||
---
|
||||
name: wiki
|
||||
description: Answer from the user's personal Obsidian notes — their "vault", "wiki", or "notes" — read-only. Fires when a question plausibly concerns the user's own recorded knowledge (projects, setup, config, decisions, preferences, or how-to notes they wrote) rather than general world facts, or on "check my notes/vault/wiki", "what do my notes say about…", "do I have anything on…". Returns a synthesized answer with the source note paths, or states plainly that the vault has nothing relevant.
|
||||
description: Answer from the user's AI-managed wiki — read-only. Fires when a question plausibly concerns the user's recorded project knowledge, setup, config, decisions, preferences, or how-to notes rather than general world facts, or on "check my notes/vault/wiki", "what do my notes say about…", "do I have anything on…". Returns a synthesized answer with the source note paths, or states plainly that the wiki has nothing relevant.
|
||||
---
|
||||
|
||||
# wiki
|
||||
|
||||
Answer a question from the user's personal Obsidian vault, read-only.
|
||||
The vault is a knowledge base the user maintains, and this skill only ever reads it.
|
||||
It searches the vault and nothing else — not the web, not general knowledge — and the caller decides whether to combine the result with other sources.
|
||||
Answer a question from the user's AI-managed wiki, read-only.
|
||||
The wiki is a knowledge base the user maintains, and this skill only ever reads it.
|
||||
It searches the wiki and nothing else — not the web, not general knowledge — and the caller decides whether to combine the result with other sources.
|
||||
The caller may be the user directly, a subagent, or another skill such as `/consume`, and the process below is the same for all three.
|
||||
|
||||
## 1. Resolve the vault and its read boundary
|
||||
## 1. Resolve the wiki
|
||||
|
||||
The vault lives at `$(xdg-user-dir DOCUMENTS)/notes`.
|
||||
If that path does not resolve or does not exist, report that the vault is unreachable and stop.
|
||||
The artifact root lives at `$(xdg-user-dir DOCUMENTS)/ai-artifacts`.
|
||||
Its notes live under `wiki/` and its topic hubs live under `tags/`.
|
||||
If either directory does not resolve or does not exist, report that the wiki is unreachable and stop.
|
||||
|
||||
Read `<vault>/.agents/settings.json` and `<vault>/.claude/settings.json` when they exist, and collect every `permissions.deny` entry of the form `Read(<glob>)`.
|
||||
The glob inside each is a path relative to the vault root, so normalize it — drop the leading `./` and trailing `/**` — to get the off-limits path, turning `Read(./05 journal/**)` into `05 journal/`.
|
||||
Those paths are off-limits: never read or search under one, and never let its contents reach an answer.
|
||||
The harness does not apply these rules when you run from outside the vault, so enforcing them is this skill's job.
|
||||
|
||||
Done when you have the vault path and the set of off-limits paths (currently `05 journal/`).
|
||||
Done when you have the wiki and tag paths.
|
||||
|
||||
## 2. Gather candidate notes
|
||||
|
||||
Expand the question into several search terms — synonyms, related concepts, and named entities — so a note worded differently than the question is still found.
|
||||
Search with ripgrep over the Markdown files directly, not obsidian-cli, so retrieval works whether or not Obsidian is running: `rg -l -i` each term over `*.md` under the vault, excluding each off-limits path with ripgrep's own `-g '!<path>'` syntax.
|
||||
Search with ripgrep over the Markdown files directly, not obsidian-cli, so retrieval works whether or not Obsidian is running: `rg -l -i` each term over `*.md` under `wiki/`.
|
||||
|
||||
Then widen for recall through the vault's topic hubs.
|
||||
Each note in `02 tags/` names a topic, and every note on that topic links to it with a `[[topic]]` wikilink, so for any hub matching the question, add its members — the notes containing `[[<hub-name>]]` — to the candidates.
|
||||
Then widen for recall through the topic hubs under `tags/`.
|
||||
Each note in `tags/` names a topic, and every note on that topic links to it with a bare `[[topic]]` wikilink, so for any hub matching the question, add its members — the notes containing `[[<hub-name>]]` — to the candidates.
|
||||
|
||||
Done when you have a candidate set of note paths.
|
||||
|
||||
@@ -38,17 +34,16 @@ Read every candidate note.
|
||||
Within each, follow every `[[wikilink]]` that bears on the question to its note and read that one too, then repeat on those notes' links.
|
||||
Continue until a full pass surfaces no note you have not already read — saturation.
|
||||
There is no cap on how many notes you read, and a broad question legitimately pulls in many.
|
||||
Never follow a link into a denied glob, and read only Markdown — attachments and other binaries are not sources.
|
||||
Read only Markdown — attachments and other binaries are not sources.
|
||||
|
||||
Done when every note bearing on the question has been read and a further pass finds nothing new.
|
||||
|
||||
## 4. Answer with provenance, or report nothing
|
||||
|
||||
If the notes answer the question, synthesize the answer, then list the notes whose content you drew on by path, each with its key excerpt, and cite that path for every claim taken from the vault.
|
||||
If the notes answer the question, synthesize the answer, then list the notes whose content you drew on by path, each with its key excerpt, and cite that path for every claim taken from the wiki.
|
||||
A note that only led you to others, such as an empty topic hub, is a discovery aid rather than a source, so leave it out of the list.
|
||||
Mark anything sourced from `00 INBOX/` as unvetted, since that folder is raw capture the user has not yet curated.
|
||||
|
||||
If nothing relevant was found, say plainly that the vault has nothing on the question.
|
||||
Do not pad the answer with vault-flavored prose that no note supports, and do not create a note to fill the gap.
|
||||
If nothing relevant was found, say plainly that the wiki has nothing on the question.
|
||||
Do not pad the answer with wiki-flavored prose that no note supports, and do not create a note to fill the gap.
|
||||
|
||||
Done when the answer cites its source notes, or explicitly reports that the vault has nothing relevant.
|
||||
Done when the answer cites its source notes, or explicitly reports that the wiki has nothing relevant.
|
||||
|
||||
Reference in New Issue
Block a user