Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .agents/skills/percolate-kb/AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Contents

- `SKILL.md` – reusable concept-and-relationship percolation workflow for a hraness/kb vault.
- `SKILL.md` – reusable concept-and-relationship percolation workflow for a hraness/wordcell vault.
- `agents/openai.yaml` – user-facing skill metadata and invocation prompt.

# Guidelines

- Keep this bundle self-contained under the public hraness/kb identity and free of repository-specific policy, paths, names, or provenance.
- Keep this bundle self-contained under the public hraness/wordcell identity and free of repository-specific policy, paths, names, or provenance.
- Keep percolation read-only until an agent reviews the cited Markdown and chooses a specific concept or relationship edit.
- Treat concepts as ordinary notes and outbound relationships as source-owned assertions; never direct agents to write reciprocal, inferred, or similarity-derived edges.
- During parallel work in a managed-catalog vault, defer the shared catalog refresh to the integrating agent and use the catalog-skipping check in each edit lane. In authored mode, refresh and check must leave the front door untouched.
Expand Down
32 changes: 16 additions & 16 deletions .agents/skills/percolate-kb/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
---
name: percolate-kb
description: Review a hraness/kb Markdown vault for recurring ideas and missing structural connections, then promote evidence-backed concepts and typed relationships with the KB CLI. Use after materially adding or revising notes, when organizing an accumulated vault, or when an agent needs to turn repeated tags and prose references into an explicit queryable knowledge graph.
description: Review a hraness/wordcell Markdown vault for recurring ideas and missing structural connections, then promote evidence-backed concepts and typed relationships with the Wordcell CLI. Use after materially adding or revising notes, when organizing an accumulated vault, or when an agent needs to turn repeated tags and prose references into an explicit queryable knowledge graph.
---

# Percolate concepts and relationships

Keep the graph authored, local, and reviewable. `kb percolate` proposes
Keep the graph authored, local, and reviewable. `wordcell percolate` proposes
candidates from deterministic evidence; it never changes a note. Backlinks,
graph reports, and QMD results are derived views, while Markdown remains the
authority.
Expand All @@ -24,13 +24,13 @@ authority.
Run percolation on the changed note when possible:

```sh
kb percolate notes/example --root "$KB_ROOT" --limit 25 --json
wordcell percolate notes/example --root "$KB_ROOT" --limit 25 --json
```

Run it without a note only when reviewing the whole vault:

```sh
kb percolate --root "$KB_ROOT" --min-support 2 --limit 50 --json
wordcell percolate --root "$KB_ROOT" --min-support 2 --limit 50 --json
```

Treat each result as a prompt to open the cited notes and read the relevant
Expand Down Expand Up @@ -61,7 +61,7 @@ Create a concept only when the idea is likely to be reused and its definition
can be stated from the source material:

```sh
kb note create notes/local-first \
wordcell note create notes/local-first \
--root "$KB_ROOT" \
--title "Local-first" \
--type concept \
Expand All @@ -81,15 +81,15 @@ concept may support relationships among its neighbors even when a run scoped to
the concept itself has no candidate:

```sh
kb percolate notes/write-path --root "$KB_ROOT" --limit 25 --json
wordcell percolate notes/write-path --root "$KB_ROOT" --limit 25 --json
```

## Author typed relationships

Add a relationship from the note that owns the assertion:

```sh
kb relation add notes/write-path supports notes/durable-agent-memory \
wordcell relation add notes/write-path supports notes/durable-agent-memory \
--root "$KB_ROOT"
```

Expand All @@ -100,8 +100,8 @@ frontmatter is an indexable statement, not a substitute for explanation.
List or remove relationships without editing reciprocal notes:

```sh
kb relation list notes/write-path --root "$KB_ROOT" --json
kb relation remove notes/write-path supports notes/durable-agent-memory \
wordcell relation list notes/write-path --root "$KB_ROOT" --json
wordcell relation remove notes/write-path supports notes/durable-agent-memory \
--root "$KB_ROOT"
```

Expand All @@ -114,9 +114,9 @@ views.
Use exact structure to verify that the promoted graph says what the prose says:

```sh
kb links notes/write-path --root "$KB_ROOT" --direction both --depth 2 --json
kb relation list notes/write-path --root "$KB_ROOT" --json
kb graph --root "$KB_ROOT" --json
wordcell links notes/write-path --root "$KB_ROOT" --direction both --depth 2 --json
wordcell relation list notes/write-path --root "$KB_ROOT" --json
wordcell graph --root "$KB_ROOT" --json
```

Prefer the note-scoped commands first. Use the whole-vault graph only when the
Expand All @@ -128,20 +128,20 @@ Markdown notes before reporting a conclusion.
When working alone or integrating several lanes:

```sh
kb refresh --root "$KB_ROOT"
kb check --root "$KB_ROOT"
wordcell refresh --root "$KB_ROOT"
wordcell check --root "$KB_ROOT"
```

When several agents are editing different notes in a managed-catalog vault,
each lane should validate authored structure and local attachments without
rewriting the shared catalog:

```sh
kb check --root "$KB_ROOT" --no-catalog
wordcell check --root "$KB_ROOT" --no-catalog
```

The integrating agent runs one final managed refresh and normal check. In an
authored-catalog vault, refresh and check leave the front door untouched, while
`kb catalog --root "$KB_ROOT"` renders an exhaustive disposable inventory.
`wordcell catalog --root "$KB_ROOT"` renders an exhaustive disposable inventory.
Resolve same-note Git conflicts from the prose and evidence; do not accept one
side's frontmatter mechanically.
2 changes: 1 addition & 1 deletion .agents/skills/plan-kb/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,4 +9,4 @@
- Keep the skill portable across repositories and independent of a specific product taxonomy.
- Require outcome, status, constraints, ordered work, and verification while allowing small plans to stay small.
- Evolve one plan in place; do not prescribe satellite progress or review files.
- Keep examples compatible with Obsidian, ordinary Markdown, and the installed `kb` command.
- Keep examples compatible with Obsidian, ordinary Markdown, and the installed `wordcell` command.
24 changes: 12 additions & 12 deletions .agents/skills/plan-kb/SKILL.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
name: plan-kb
description: Create or evolve a durable Markdown plan inside a hraness/kb vault. Use when a user asks for an implementation plan, proposal, RFC, migration plan, execution audit, phased checklist, or an update to an existing plan's decisions, progress, review findings, verification evidence, or final result.
description: Create or evolve a durable Markdown plan inside a hraness/wordcell vault. Use when a user asks for an implementation plan, proposal, RFC, migration plan, execution audit, phased checklist, or an update to an existing plan's decisions, progress, review findings, verification evidence, or final result.
---

# Write a durable plan
Expand All @@ -20,7 +20,7 @@ record, not a disposable answer or a duplicate task tracker.
`KB_REPO` and load that path's current memory before a whole-vault search:

```sh
kb context "<repository-path>" --root "$KB_ROOT" --repo "$KB_REPO"
wordcell context "<repository-path>" --root "$KB_ROOT" --repo "$KB_REPO"
```

Use `--kind file` or `--kind directory` when an absent future path cannot be
Expand All @@ -31,13 +31,13 @@ separate historical-plan group.
3. Search existing plans before creating one:

```sh
kb list --root "$KB_ROOT" --where type=plan --sort area --json
kb search "the intended outcome" --root "$KB_ROOT" --json
wordcell list --root "$KB_ROOT" --where type=plan --sort area --json
wordcell search "the intended outcome" --root "$KB_ROOT" --json
```

If `kb` is not installed, do not let retrieval tooling block the plan: use
If `wordcell` is not installed, do not let retrieval tooling block the plan: use
`rg` or the available file search over `<vault>/plans/`, titles, aliases, and relevant
terms. If the directory is not an initialized hraness/kb vault, follow the
terms. If the directory is not an initialized hraness/wordcell vault, follow the
repository's existing planning convention instead of initializing one without
being asked. Semantic search writes only a derived local cache; when that cache
location is not writable, use exact search or point `XDG_CACHE_HOME` at a
Expand Down Expand Up @@ -100,12 +100,12 @@ a useful connection. Review the changed plan for reusable concepts before
refreshing:

```sh
kb percolate "<plan-note-id>" --root "$KB_ROOT" --limit 25 --json
kb refresh --root "$KB_ROOT"
kb check --root "$KB_ROOT"
wordcell percolate "<plan-note-id>" --root "$KB_ROOT" --limit 25 --json
wordcell refresh --root "$KB_ROOT"
wordcell check --root "$KB_ROOT"
```

Run those commands when the plan lives in an initialized hraness/kb vault. In a
Run those commands when the plan lives in an initialized hraness/wordcell vault. In a
repository-native planning directory, use that repository's own validation
instead. Review broken links first, then inspect orphan and mention advisories
in context. Promote only concepts likely to be reused, and ground every typed
Expand All @@ -114,7 +114,7 @@ remain an orphan in a new or sparse vault. Record that disposition mentally or
in the task handoff; do not manufacture links or relations merely to improve
graph counts.

In an authored-catalog vault, refresh leaves the front door unchanged and `kb
In an authored-catalog vault, refresh leaves the front door unchanged and `wordcell
catalog --root "$KB_ROOT"` renders an exhaustive disposable inventory. In a
managed vault, independent edit lanes use `kb check --root "$KB_ROOT"
managed vault, independent edit lanes use `wordcell check --root "$KB_ROOT"
--no-catalog`; the integrating lane performs the single catalog refresh.
Loading
Loading