From 3f5b9a0115bcd4acf78dfa74a9a9afaff2c0bca7 Mon Sep 17 00:00:00 2001 From: German Meza Date: Sat, 23 May 2026 19:03:36 -0600 Subject: [PATCH 1/2] chore(gilbreth): mark Elephant initiative and descendants complete Final status bump for the Elephant initiative, the gilbreth-refactor story, and the gilbreth-wbs project node. Shipped as a discrete commit ahead of the WBS tracking-tree retirement, per `conventions.md`'s "Retiring a completed project" procedure. --- wbs/gilbreth-wbs.md | 2 +- wbs/gilbreth-wbs/elephant.md | 2 +- wbs/gilbreth-wbs/elephant/gilbreth-refactor.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/wbs/gilbreth-wbs.md b/wbs/gilbreth-wbs.md index 8dbdc42..904a86c 100644 --- a/wbs/gilbreth-wbs.md +++ b/wbs/gilbreth-wbs.md @@ -2,7 +2,7 @@ type: wbs-node title: Build out the Gilbreth WBS level: project -status: drafted +status: completed order: 0 --- diff --git a/wbs/gilbreth-wbs/elephant.md b/wbs/gilbreth-wbs/elephant.md index 9e14164..a37162c 100644 --- a/wbs/gilbreth-wbs/elephant.md +++ b/wbs/gilbreth-wbs/elephant.md @@ -1,9 +1,9 @@ --- type: wbs-node title: Elephant — Tusk as agent memory +status: completed order: 0 level: initiative -status: ready-to-decompose --- # Elephant — Tusk as agent memory diff --git a/wbs/gilbreth-wbs/elephant/gilbreth-refactor.md b/wbs/gilbreth-wbs/elephant/gilbreth-refactor.md index ebf1b2b..1af4fcb 100644 --- a/wbs/gilbreth-wbs/elephant/gilbreth-refactor.md +++ b/wbs/gilbreth-wbs/elephant/gilbreth-refactor.md @@ -1,9 +1,9 @@ --- type: wbs-node title: "gilbreth refactor: defer to elephant + drop type prefixes" -order: 4 level: story -status: plan-ready +status: completed +order: 4 --- # gilbreth refactor: defer to elephant + drop type prefixes From 906ef814ba661f1d26fa606c25787820b9d7c941 Mon Sep 17 00:00:00 2001 From: German Meza Date: Sat, 23 May 2026 19:06:40 -0600 Subject: [PATCH 2/2] chore(gilbreth): retire completed Elephant WBS tracking tree MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Elephant initiative shipped across PRs #45-49, #51-54, and #56 — all five stories (knowledge pack, conventions skill, capture skill, recall skill, gilbreth refactor) plus the Phase-3 /wbs-migrate helper. Initiative + descendants are all `status=completed`. Per `plugins/gilbreth/templates/wbs/conventions.md` "Retiring a completed project": once tracking files stop being coordination tools, they become noise for future agents querying the graph. This commit removes `wbs/gilbreth-wbs/` + `wbs/gilbreth-wbs.md` and moves the roadmap row to Done. Recoverable: every retired file is in git history (parent commit `3f5b9a0`). Spec/plan/brainstorm/reshape-audit notes are not lost, just no longer in the live graph. --- docs/superpowers/gilbreth-wbs-roadmap.md | 7 +- wbs/gilbreth-wbs.md | 48 -- wbs/gilbreth-wbs/elephant.md | 64 --- .../elephant/capture-skill-plan.md | 134 ----- .../elephant/capture-skill-spec.md | 75 --- wbs/gilbreth-wbs/elephant/capture-skill.md | 55 -- .../elephant/conventions-skill-plan.md | 128 ----- .../elephant/conventions-skill-spec.md | 67 --- .../elephant/conventions-skill.md | 54 -- .../elephant/gilbreth-refactor-phase-1.md | 39 -- .../elephant/gilbreth-refactor-plan.md | 231 --------- .../elephant/gilbreth-refactor-spec.md | 83 ---- .../elephant/gilbreth-refactor.md | 55 -- .../elephant/knowledge-pack-plan.md | 468 ------------------ .../elephant/knowledge-pack-spec.md | 98 ---- wbs/gilbreth-wbs/elephant/knowledge-pack.md | 60 --- .../elephant/recall-skill-plan.md | 134 ----- .../elephant/recall-skill-spec.md | 78 --- wbs/gilbreth-wbs/elephant/recall-skill.md | 54 -- wbs/gilbreth-wbs/elephant/spec.md | 65 --- 20 files changed, 2 insertions(+), 1995 deletions(-) delete mode 100644 wbs/gilbreth-wbs.md delete mode 100644 wbs/gilbreth-wbs/elephant.md delete mode 100644 wbs/gilbreth-wbs/elephant/capture-skill-plan.md delete mode 100644 wbs/gilbreth-wbs/elephant/capture-skill-spec.md delete mode 100644 wbs/gilbreth-wbs/elephant/capture-skill.md delete mode 100644 wbs/gilbreth-wbs/elephant/conventions-skill-plan.md delete mode 100644 wbs/gilbreth-wbs/elephant/conventions-skill-spec.md delete mode 100644 wbs/gilbreth-wbs/elephant/conventions-skill.md delete mode 100644 wbs/gilbreth-wbs/elephant/gilbreth-refactor-phase-1.md delete mode 100644 wbs/gilbreth-wbs/elephant/gilbreth-refactor-plan.md delete mode 100644 wbs/gilbreth-wbs/elephant/gilbreth-refactor-spec.md delete mode 100644 wbs/gilbreth-wbs/elephant/gilbreth-refactor.md delete mode 100644 wbs/gilbreth-wbs/elephant/knowledge-pack-plan.md delete mode 100644 wbs/gilbreth-wbs/elephant/knowledge-pack-spec.md delete mode 100644 wbs/gilbreth-wbs/elephant/knowledge-pack.md delete mode 100644 wbs/gilbreth-wbs/elephant/recall-skill-plan.md delete mode 100644 wbs/gilbreth-wbs/elephant/recall-skill-spec.md delete mode 100644 wbs/gilbreth-wbs/elephant/recall-skill.md delete mode 100644 wbs/gilbreth-wbs/elephant/spec.md diff --git a/docs/superpowers/gilbreth-wbs-roadmap.md b/docs/superpowers/gilbreth-wbs-roadmap.md index e5ba8d4..0b20853 100644 --- a/docs/superpowers/gilbreth-wbs-roadmap.md +++ b/docs/superpowers/gilbreth-wbs-roadmap.md @@ -19,12 +19,9 @@ Numbered for reference, not strict execution order. Order is reviewed each time | 1 | **WBS spine** — the inverted-flame decomposition model, the skill set that walks a user from wide scope to narrow scope, and the data shape of a "node" at each level | — | — | | 2 | **Phase skills relocation + polish** — move the three phase skills (`phase-planning-rules`, `phase-continuity-review`, `phase-post-implementation-review`) from `~/.claude/skills/` into the `gilbreth` plugin, reshape for WBS context | — | — | | 3 | **WBS reshape** — `/wbs-reshape` command + `wbs-reshape` skill that lets WBS authors change direction mid-flight via context-aware re-brainstorm; auto-invokes from `wbs-orientation` on contradiction gates | — | — | +| 4 | **Elephant** — a plugin that guides the agent to use [Tusk](https://github.com/germanamz/tusk) well as a short-to-medium-term memory keeper: capture learnings broadly into the graph and recall them narrowly (windowed) so knowledge transfers seamlessly across sessions. Shipped as the standalone `elephant` plugin (`core` type pack + `conventions`/`capture`/`recall` skills + `/bootstrap`) plus a gilbreth refactor that defers generic Tusk discipline to `elephant:conventions` and adopts the canonical unprefixed types. | `wbs/gilbreth-wbs/elephant/spec.md` † | per-story † | -### In progress - -| # | Sub-project | Spec | Plan | -|---|---|---|---| -| 4 | **Elephant** — a plugin that guides the agent to use [Tusk](https://github.com/germanamz/tusk) well as a short-to-medium-term memory keeper: capture learnings broadly into the graph and recall them narrowly (windowed) so knowledge transfers seamlessly across sessions. Tracked as WBS initiative `wbs/gilbreth-wbs/elephant`, decomposed into 5 stories (knowledge pack, conventions skill, capture skill, recall skill, gilbreth refactor). | `wbs/gilbreth-wbs/elephant/spec` (Tusk note) | per-story | +† Elephant's WBS tracking tree under `wbs/gilbreth-wbs/` was retired once the initiative completed — the live graph no longer carries planning data for shipped work (per `plugins/gilbreth/templates/wbs/conventions.md` "Retiring a completed project"). The full planning record (initiative + 5 story nodes, every spec/plan/brainstorm/reshape-audit note) is recoverable from git history at the parent of the retirement commit. ### Not started diff --git a/wbs/gilbreth-wbs.md b/wbs/gilbreth-wbs.md deleted file mode 100644 index 904a86c..0000000 --- a/wbs/gilbreth-wbs.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -type: wbs-node -title: Build out the Gilbreth WBS -level: project -status: completed -order: 0 ---- - -# Build out the Gilbreth WBS - -## Outcome - -Grow the `gilbreth` plugin from scaffolding into an opinionated, end-to-end workflow that walks a user from a fuzzy idea down to atomic, agent-executable tasks — with graph-backed note-taking, conventions, and Tusk integration throughout. The durable change: user + agent collaborate on software work through an inverted-flame Work Breakdown Structure where every node carries Karpathy forcing-functions and every learning is captured for narrow, windowed recall by future sessions. - -## Success Criteria - -- The WBS spine (levels, decomposition gate, phasing, reshape) ships and is dogfood-usable. (Done — sub-projects #1–3.) -- Knowledge capture/recall works as a cross-session memory layer (Elephant). -- Engineering conventions and a staged-research workflow (Researcher) build on top. -- Each sub-project ships its own spec + plan + implementation through the superpowers loop. - -## Assumptions Made - -- Tusk v1.3.0+ is the backing store; nodes/notes are git-tracked markdown. -- The full design rationale and live ordering live in the roadmap doc, `docs/superpowers/gilbreth-wbs-roadmap.md` — this node is the WBS container for it. - -## Open Questions - -none, because the roadmap doc is the living plan and re-evaluates ordering each time a sub-project completes. - -## Tradeoffs Considered - -- Tracking this initiative in Tusk vs. the markdown roadmap alone: we track active sub-projects as WBS nodes (dogfooding + windowed recall) while keeping the roadmap as the human-facing index. Completed sub-projects (#1–3) are not seeded as nodes — they'd be noise. - -## Out of Scope - -- Re-tracking already-completed sub-projects (#1–3) as WBS nodes. -- Building Researcher (#6) or Engineering conventions (#5) right now. - -## Phasing - -No phases needed. Sub-projects are sequenced via the roadmap, not WBS phases. - -## Milestones - -Sub-projects are tracked directly as initiatives under this project (the `milestone` rank is intentionally skipped — the roadmap groups sub-projects without an intermediate tier). - -- **Elephant** (initiative) — Tusk as the agent's short-to-medium-term memory keeper. diff --git a/wbs/gilbreth-wbs/elephant.md b/wbs/gilbreth-wbs/elephant.md deleted file mode 100644 index a37162c..0000000 --- a/wbs/gilbreth-wbs/elephant.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -type: wbs-node -title: Elephant — Tusk as agent memory -status: completed -order: 0 -level: initiative ---- - -# Elephant — Tusk as agent memory - -## Outcome - -A standalone `elephant` plugin that makes Tusk the agent's short-to-medium-term memory keeper, so knowledge transfer across sessions is seamless. Elephant ships WBS-agnostic Tusk-usage skills that fire on the work itself (not on the user mentioning Tusk): it captures learnings broadly into a knowledge graph and recalls them narrowly (windowed), so a future session resumes with just-enough relevant context instead of a flooded window. gilbreth's generic Tusk discipline is refactored to defer to Elephant. - -## Success Criteria - -- A new `elephant` plugin is registered in the marketplace with three skills (`conventions`, `capture`, `recall`), a generic `knowledge` Tusk pack, a `/bootstrap` command, and note templates. -- `capture` auto-invokes on note-worthy work (hard-won learnings, decisions, open threads, boundary checkpoints — all of them) and writes small, well-linked notes to the graph. -- `recall` auto-invokes at start-of-work / context switch and pulls only the relevant slice via structural + semantic query. -- When no Tusk graph exists, Elephant offers to bootstrap once per session; if declined, it goes dormant; if a graph exists, it operates silently. -- gilbreth's `conventions.md` and `wbs-orientation` defer to `elephant:conventions` for generic Tusk discipline, keeping only WBS-specific rules. - -## Assumptions Made - -- Tusk v1.3.0+ with git-tracked markdown nodes; the same MCP-preferred / CLI-fallback access pattern wbs-orientation uses. -- Semantic recall is additive and degrades gracefully when `[embeddings]` is unconfigured (mirrors the WBS semantic-gate availability pattern). -- Claude Code resolves cross-plugin skill references by `plugin:skill` name (as gilbreth already does for its own skills), so gilbreth can invoke `elephant:conventions`. - -## Open Questions - -- Exact node/edge model of the `knowledge` pack (node kinds, edges, composition with the `wbs` pack) — resolved at the knowledge-pack story's brainstorm. -- Whether `capture`/`recall` should themselves be invokable as named entry points by subagents, or purely auto-invoke — resolved per-story. - -## Tradeoffs Considered - -- **Generalize-and-extract** (chosen) vs. net-new-no-refactor vs. fold-into-gilbreth vs. sync-only. Chose extraction so the Tusk discipline has one home and Researcher (#6) can build on it; accepts a gilbreth refactor as the cost. -- **Focused skill trio** (chosen) vs. a single orchestrator skill vs. thin-conventions-plus-one-skill. Capture and recall have genuinely different triggers and failure modes, so separate skills keep each one's context tight. -- **Capture broadly / recall narrowly** vs. a single tunable threshold. The point is cross-session memory, so capture spans learnings + decisions + open threads + boundary checkpoints; the graph + indexation is what keeps recall windowed despite broad capture. -- Prefix-free skill names (`capture`/`recall`/`conventions`) rely on the `elephant:` plugin namespace for disambiguation. - -## Out of Scope - -- Researcher (#6) and Engineering conventions (#5). -- Re-implementing WBS-specific concerns (levels, Karpathy gate, phasing) — those stay in gilbreth. -- A human-facing query UI; Elephant is agent-facing guidance plus a pack/command. - -## Contracts - -- **Depends on:** the gilbreth-wbs spine's Tusk conventions (the material being generalized). -- **Depended on by:** gilbreth (post-refactor) and the future Researcher initiative (#6), which will write into Elephant's knowledge graph. - -## Phasing - -No phases needed at the initiative level. Sequencing is expressed through story order (see Stories). - -## Stories - -Built in order; each is a focused implement-by-parts session. - -1. **knowledge pack + /bootstrap + availability check** — the generic Tusk types, the one-time init command, and the shared "is there a graph?" probe the skills depend on. -2. **conventions skill** — the WBS-agnostic graph-hygiene rulebook the other two skills read. -3. **capture skill** — broad, auto-invoking note capture. -4. **recall skill** — windowed, auto-invoking retrieval. -5. **gilbreth refactor** — make gilbreth's conventions/orientation defer to `elephant:conventions`. diff --git a/wbs/gilbreth-wbs/elephant/capture-skill-plan.md b/wbs/gilbreth-wbs/elephant/capture-skill-plan.md deleted file mode 100644 index 08a4ce0..0000000 --- a/wbs/gilbreth-wbs/elephant/capture-skill-plan.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -type: wbs-note -title: Plan — capture skill -kind: plan -archived: false -wbs-about: wbs/gilbreth-wbs/elephant/capture-skill ---- - -# capture skill — Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development. Steps use checkbox (`- [ ]`) syntax. -> -> **WBS note:** Plan for story `wbs/gilbreth-wbs/elephant/capture-skill`. Spec: [[wbs/gilbreth-wbs/elephant/capture-skill-spec]]. - -**Goal:** Ship `elephant:capture` — an auto-invoking AND explicitly-invocable skill that proactively writes note-worthy work into the knowledge graph, applying `conventions` and gating on the availability check. - -**Architecture:** A single `plugins/elephant/skills/capture/SKILL.md` (rigid write procedure that reads the flexible `conventions` rulebook). One `feat(elephant)` PR; no catalog/release-please changes (`elephant` already registered). `conventions` is on `main`. - -**Tech Stack:** Claude Code skill markdown. "Tests" are content-validation commands (`grep`, frontmatter check) plus a manual smoke note. - ---- - -## File structure - -PR (`feat(elephant)`): -- Create `plugins/elephant/skills/capture/SKILL.md` — the capture skill -- Modify `plugins/elephant/README.md` — move `capture` from "coming later" to a shipped skill - ---- - -## Task 1: Write the capture SKILL - -**Files:** -- Create: `plugins/elephant/skills/capture/SKILL.md` - -Read first for grounding: `plugins/elephant/skills/conventions/SKILL.md` (the rules capture applies — reference it, don't restate), `plugins/elephant/references/availability-check.md` (the gate), `plugins/elephant/packs/knowledge.toml` (vocabulary), and `plugins/gilbreth/skills/wbs-orientation/SKILL.md` (tone + how it names MCP/CLI tools). Match the imperative, skimmable tone. - -- [ ] **Step 1: Write `SKILL.md` frontmatter exactly** - -```markdown ---- -name: capture -description: Use proactively to capture note-worthy work into the Tusk knowledge graph so future sessions can recall it — at natural work boundaries (finishing an investigation, before a context switch, task completion) and the moment a hard-won learning, a decision + rationale, a discovered constraint, or an open thread surfaces. Fires regardless of whether the user mentioned Tusk. Also invocable by name to persist learnings on demand (e.g. a subagent before reporting back). ---- -``` - -- [ ] **Step 2: Write the body — intro + procedure + behavior** - -Skimmable prose. Cover: - -- **One-line intro:** capture is the write side of Tusk-as-memory; it applies the `conventions` rulebook (link it) and gates on `references/availability-check.md` (link it). Both auto-invoking and an explicit entry point. -- **`## Behavior`:** autonomous (writes without per-note approval — asking each time defeats proactive memory) + announced (emit a terse one-line acknowledgment per capture, e.g. `📝 captured learning: `); batch multiple items at a boundary rather than interrupting per item. -- **`## Procedure`** (numbered, rigid): - 1. **Gate.** Run the availability check (`references/availability-check.md`): absent graph → offer `/bootstrap` once then dormant; present → continue silently. - 2. **Identify items.** Enumerate the note-worthy items from the work (or the explicit request); assign each a `kind` (`learning|decision|open-thread|checkpoint`) per `conventions`. Skip trivia that is re-derivable from code/docs. - 3. **Dedup check (lightweight).** For each item, look for an existing note on the same topic — `tusk_query` by `tagged:<topic>` / title match, plus `--semantic`/`semantic` when embeddings are configured. This is a targeted existence check, NOT full retrieval (that's `recall`). - 4. **Create / append / supersede** per `conventions`: new note for a distinct idea; append for the same idea; `archived=true` + a `supersedes` edge to replace an outdated note. - 5. **Model the note** per `conventions`: small + atomic, discoverable title/body, topic `tags`, `[[wikilinks]]` to related notes. - 6. **Write** via MCP (`tusk_node_create` / `tusk_node_modify`, `tusk_edge_add`); MCP-preferred, CLI-fallback. - 7. **Acknowledge** with the terse one-line-per-capture summary; batch at boundaries. -- **`## When NOT to capture`:** trivia, secrets/credentials, or anything re-derivable from the codebase; if no graph and the user already declined `/bootstrap` this session, stay dormant. - -Do NOT restate the `conventions` rules or the availability-check procedure — link to them. - -- [ ] **Step 3: Verify frontmatter + structure** - -```bash -head -5 plugins/elephant/skills/capture/SKILL.md # name: capture + description -grep -iE 'conventions|availability-check' plugins/elephant/skills/capture/SKILL.md # links both -grep -iE 'tusk_node_create|tusk_edge_add|tusk_query' plugins/elephant/skills/capture/SKILL.md # names MCP tools -``` -Expected: frontmatter present (`name: capture`, a `description` that mentions both auto + named-entry use); references both `conventions` and `availability-check`; names the MCP write/query tools. - -- [ ] **Step 4: Verify WBS-agnostic + no rule duplication** - -```bash -grep -iE 'wbs|karpathy|milestone|initiative|level=' plugins/elephant/skills/capture/SKILL.md && echo "LEAK" || echo "clean: no WBS vocabulary" -``` -Expected: `clean: no WBS vocabulary`. Also eyeball that it links to `conventions` rather than re-listing the modeling rules. - -- [ ] **Step 5: Commit** - -```bash -git add plugins/elephant/skills/capture/SKILL.md -git commit -m "feat(elephant): add capture skill" -``` - ---- - -## Task 2: Update the plugin README - -**Files:** -- Modify: `plugins/elephant/README.md` - -- [ ] **Step 1: Move `capture` to a shipped skill** - -In `### Skills`, list `capture` as shipped and leave only `recall` under "coming in later stories": -```markdown -### Skills -- `conventions` — auto-invoking graph-hygiene rulebook for the knowledge pack. -- `capture` — proactively writes note-worthy work (learnings, decisions, open-threads, checkpoints) into the graph; auto-invoking and invocable by name. -- _Coming in a later story_: `recall` (windowed retrieval). -``` - -- [ ] **Step 2: Commit** - -```bash -git add plugins/elephant/README.md -git commit -m "docs(elephant): list capture skill in README" -``` - ---- - -## Task 3: Open the PR (controller) - -- [ ] **Step 1: Push + open** - -```bash -git push -u origin feat/elephant-capture -gh pr create --title "feat(elephant): add capture skill" --body "<summary + link to story>" -``` -Expected: `lint-commits` + `lint-pr-title` pass (`elephant` scope already on `main`). - ---- - -## Post-merge - -Flip the story to `completed` on this PR's branch (single-PR story; completion bump rides it). release-please opens an `elephant` release PR. - -## Out of scope (later stories) - -- `recall` (story 4) — capture's dedup is deliberately lightweight; full retrieval is recall. -- gilbreth defer-to-elephant refactor (story 5). -- Restating `conventions` rules or the availability-check procedure (link them). diff --git a/wbs/gilbreth-wbs/elephant/capture-skill-spec.md b/wbs/gilbreth-wbs/elephant/capture-skill-spec.md deleted file mode 100644 index bd56f05..0000000 --- a/wbs/gilbreth-wbs/elephant/capture-skill-spec.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -type: wbs-note -title: Spec — capture skill -kind: spec -archived: false -wbs-about: wbs/gilbreth-wbs/elephant/capture-skill ---- - -# Spec — capture skill - -**wbs-note frontmatter:** `kind=spec` (linked to `wbs/gilbreth-wbs/elephant/capture-skill` by a `wbs-about` edge) - -## Goal - -Ship `elephant:capture` — the write side of Tusk-as-memory. It captures note-worthy work *broadly* (learnings, decisions, open-threads, boundary checkpoints) into the knowledge graph, autonomously and proactively (regardless of whether the user mentioned Tusk), so a future session can recall it. It applies the `conventions` rulebook for *how* to model each note and gates on the availability check. - -## Architecture - -A `plugins/elephant/skills/capture/SKILL.md`. It is **both** auto-invoking (fires on note-worthy moments) **and** an explicit named entry point (`elephant:capture` — the user or a dispatched subagent can invoke it directly to persist learnings). It is a rigid procedure (the write sequence is enforced) that reads the flexible `conventions` rulebook for modeling judgment. - -### Behavior: autonomous + announced, boundary-batched - -- Writes notes on its own — no per-note approval (that would defeat the proactive-memory goal). -- Transparent: emits a terse one-line acknowledgment per capture (e.g., `📝 captured learning: <title>`), so the user has visibility and can course-correct, without a blocking prompt. -- Batches multiple items at a natural boundary rather than interrupting mid-flow per item. - -### Trigger - -Auto-invokes at: -- (i) natural work boundaries — finishing an investigation, before a context switch, task/subtask completion; and -- (ii) the moment a clearly note-worthy item surfaces — a hard-won/non-obvious learning, a decision + its rationale, a discovered constraint, an open thread/loose end. - -Also invocable explicitly by name. Both paths run the same procedure. - -## Components - -`skills/capture/SKILL.md` procedure: - -1. **Gate.** Run the availability check (`references/availability-check.md`). Absent graph → offer `/bootstrap` once, else dormant; present → continue silently. -2. **Identify items.** From the work (or the explicit request), enumerate the note-worthy items and assign each a `kind` (`learning|decision|open-thread|checkpoint`) per `conventions`. -3. **Dedup check (lightweight).** For each item, check for an existing note on the same topic — by tag/title match, plus semantic ranking when embeddings are configured. This is a *targeted* existence check, NOT full retrieval (that is `recall`, story 4). -4. **Create / append / supersede** per `conventions`: new note for a distinct idea; append for the same idea; `archived=true` + a `supersedes` edge when replacing an outdated note. -5. **Model the note** per `conventions`: small + atomic, discoverable title/body, topic `tags`, `[[wikilinks]]` to related notes (→ `references`). -6. **Write** via MCP (`tusk_node_create` / `tusk_node_modify` + `tusk_edge_add`); MCP-preferred, CLI-fallback. -7. **Acknowledge** with a terse one-line-per-capture summary; batch at boundaries. - -## Data flow - -1. Agent hits a note-worthy moment / boundary (or is explicitly told to capture) → `capture` runs → gate → identify → dedup → write → acknowledge. -2. Notes land in the graph well-modeled and linked, so `recall` (story 4) can later surface them narrowly. - -## Error handling - -- No graph: offer-bootstrap-once then dormant (no nagging) — per the availability check. -- Embeddings absent: dedup falls back to structural (tag/title) match only; never blocks the write. -- MCP write-lock contention: prefer MCP tools (the server holds the lock). -- Ambiguous kind / not clearly note-worthy: prefer NOT writing trivia (capture broadly, but skip what's re-derivable from code/docs — `conventions` "windowed memory" judgment applies). - -## Verification - -- `skills/capture/SKILL.md` exists with valid frontmatter; `description` auto-invokes on note-worthy work AND it is invocable by name. -- Manual smoke (in a knowledge-pack workspace): a session that learns something non-obvious results in a well-formed `note` (right `kind`, tags, a `[[wikilink]]`), with a terse acknowledgment; re-capturing the same topic appends/supersedes rather than duplicating. -- Explicit invocation path writes a note on demand. -- Gating: in a non-Tusk workspace, the first note-worthy moment offers `/bootstrap` once, then goes quiet. - -## Out of scope - -- `recall` / full retrieval (story 4) — capture's dedup check is deliberately lightweight. -- gilbreth's defer-to-elephant refactor (story 5). -- The `conventions` rules themselves (story 2) — capture *applies* them, doesn't restate them. -- An `open → resolved` note workflow (knowledge-pack v2). - -## Open questions - -- None. Autonomy (autonomous + announced, boundary-batched), dedup approach (lightweight, conventions-driven), and the named-entry-point question (yes — both auto and explicit) are all resolved. diff --git a/wbs/gilbreth-wbs/elephant/capture-skill.md b/wbs/gilbreth-wbs/elephant/capture-skill.md deleted file mode 100644 index 1b72199..0000000 --- a/wbs/gilbreth-wbs/elephant/capture-skill.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -type: wbs-node -title: capture skill -status: completed -order: 2 -level: story ---- - -# capture skill - -## Outcome - -`elephant:capture` — the write side of Tusk-as-memory. Captures note-worthy work broadly (learnings, decisions, open-threads, boundary checkpoints) into the knowledge graph, autonomously and proactively (regardless of whether the user mentioned Tusk), applying the `conventions` rulebook and gating on the availability check. Both auto-invoking and an explicit named entry point. - -## Success Criteria - -- `plugins/elephant/skills/capture/SKILL.md` auto-invokes on note-worthy moments/boundaries AND is invocable by name. -- Behavior is autonomous + announced (terse one-line acknowledgment per capture), boundary-batched. -- Notes are small/atomic, correctly `kind`-ed, tagged, and `[[wikilink]]`-linked; a lightweight dedup check appends/supersedes instead of duplicating. -- Gates on the availability check (offer-bootstrap-once / dormant / silent). - -## Assumptions Made - -- conventions skill (story 2) is shipped and defines the modeling rules capture applies. -- The knowledge pack (story 1) and `references/availability-check.md` exist. - -## Open Questions - -none — autonomy (autonomous + announced, boundary-batched), dedup (lightweight, conventions-driven), and named entry point (yes, both auto + explicit) are resolved. - -## Tradeoffs Considered - -- Autonomous+announced (chosen) vs. silent vs. propose-then-confirm: chose announced autonomy — proactive memory without per-note ceremony, but transparent. -- Lightweight dedup check (chosen) vs. full retrieval before write: full retrieval is `recall` (story 4); capture stays targeted. -- Auto + explicit entry point (chosen) vs. auto-only: explicit lets a subagent persist learnings before reporting back. - -## Out of Scope - -- recall / full retrieval (story 4); gilbreth defer-to-elephant (story 5); the conventions rules themselves (story 2). - -## Spec note - -[[wbs/gilbreth-wbs/elephant/capture-skill-spec]] - -## Plan note - -[[wbs/gilbreth-wbs/elephant/capture-skill-plan]] - -## Phasing - -No phases needed. - -## Tasks - -To be decomposed after planning. diff --git a/wbs/gilbreth-wbs/elephant/conventions-skill-plan.md b/wbs/gilbreth-wbs/elephant/conventions-skill-plan.md deleted file mode 100644 index 5173568..0000000 --- a/wbs/gilbreth-wbs/elephant/conventions-skill-plan.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -type: wbs-note -title: Plan — conventions skill -kind: plan -archived: false -wbs-about: wbs/gilbreth-wbs/elephant/conventions-skill ---- - -# conventions skill — Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax. -> -> **WBS note:** Plan for story `wbs/gilbreth-wbs/elephant/conventions-skill`. Spec: [[wbs/gilbreth-wbs/elephant/conventions-skill-spec]]. - -**Goal:** Ship `elephant:conventions`, an auto-invoking SKILL that is the WBS-agnostic graph-hygiene rulebook for the `knowledge` pack. - -**Architecture:** A single skimmable `plugins/elephant/skills/conventions/SKILL.md` (reference/flexible skill). One `feat(elephant)` PR; `elephant` is already registered in the marketplace, so no catalog/release-please changes are needed. - -**Tech Stack:** Claude Code skill markdown (YAML frontmatter + body). "Tests" are content-validation commands (`grep`, frontmatter check). - ---- - -## File structure - -PR (`feat(elephant)`): -- Create `plugins/elephant/skills/conventions/SKILL.md` — the rulebook skill -- Modify `plugins/elephant/README.md` — move `conventions` from "coming in later stories" to a shipped skill - ---- - -## Task 1: Write the conventions SKILL - -**Files:** -- Create: `plugins/elephant/skills/conventions/SKILL.md` - -Ground the prose in two existing sources (read them first): `plugins/gilbreth/templates/wbs/conventions.md` (the Tusk-usage discipline to generalize — strip all WBS vocabulary) and `plugins/elephant/packs/knowledge.toml` + `plugins/elephant/references/availability-check.md` (the exact vocabulary: `note` type, `kind` enum `learning|decision|open-thread|checkpoint`, `references`/`supersedes` edges, the `tags` pack). Match the skimmable, imperative tone of gilbreth's `wbs-orientation` SKILL. - -- [ ] **Step 1: Write `SKILL.md` frontmatter exactly** - -```markdown ---- -name: conventions -description: Use whenever about to read or write a Tusk knowledge graph — creating, editing, linking, tagging, or archiving `note`s, or querying the graph. Auto-invokes to surface Elephant's knowledge-modeling rules (Tusk is not a default-known tool): how to size and kind a note, when to create vs append vs supersede, how to keep notes discoverable for windowed recall, and archive/tool discipline. ---- -``` - -- [ ] **Step 2: Write the body — six sections** - -Write skimmable prose (headings + tight bullets), WBS-agnostic, grounded as above. Each section must cover: - -1. `## Windowed memory` — the why: capture broadly, keep each note small and atomic (one idea), recall narrowly. The graph + indexation is what makes broad capture compatible with a small context window. This is the load-bearing principle. -2. `## Note granularity & kind` — one idea per `note`. How to choose `kind`: `learning` (a durable non-obvious finding), `decision` (a choice + its rationale), `open-thread` (an unresolved question / loose end), `checkpoint` (a "where I left off / start here next" summary at a work boundary). -3. `## Create vs. append vs. supersede` — write a NEW note for a distinct idea; APPEND to an existing note only when adding to the same idea; when a note is wrong/outdated, set `archived=true` and create a replacement linked with a `supersedes` edge (append-only history — never silently rewrite a superseded fact). -4. `## Discoverability` — write titles and bodies the indexer and semantic search can find (state the topic explicitly, avoid pronouns-only); link related notes with `[[wikilinks]]` (materialize `references` edges); tag topics via the `tags` pack so "everything about X" is queryable by `tagged`. The point: future agents recall narrowly because notes are well-titled, linked, and tagged. -5. `## Archive, don't delete` — `archived=true` is the soft-delete/supersede marker; never hard-delete a note (history is the value). Querying excludes archived by default. -6. `## Tool discipline` — MCP-preferred / CLI-fallback (the MCP server may hold the write lock; prefer `tusk_*` MCP tools). For "is there a graph here?" and the bootstrap-offer behavior, point to `references/availability-check.md` (do NOT restate it). - -Add a one-line intro stating this is the WBS-agnostic rulebook for the `knowledge` pack, read/built-on by `capture`, `recall`, and (later) gilbreth. - -- [ ] **Step 3: Verify frontmatter + content** - -```bash -head -5 plugins/elephant/skills/conventions/SKILL.md # name + description present -grep -c '^## ' plugins/elephant/skills/conventions/SKILL.md # expect 6 -grep -i 'availability-check' plugins/elephant/skills/conventions/SKILL.md # references the doc -``` -Expected: frontmatter has `name: conventions` + a `description:`; six `##` sections; one reference to `availability-check`. - -- [ ] **Step 4: Verify WBS-agnostic (no leaked vocabulary)** - -```bash -grep -iE 'wbs|karpathy|milestone|initiative|decompos|phase-plan|level=' plugins/elephant/skills/conventions/SKILL.md && echo "LEAK — remove WBS terms" || echo "clean: no WBS vocabulary" -``` -Expected: `clean: no WBS vocabulary`. If anything matches, rewrite that line generically. - -- [ ] **Step 5: Commit** - -```bash -git add plugins/elephant/skills/conventions/SKILL.md -git commit -m "feat(elephant): add conventions rulebook skill" -``` - ---- - -## Task 2: Update the plugin README - -**Files:** -- Modify: `plugins/elephant/README.md` - -- [ ] **Step 1: Move `conventions` to a shipped skill** - -In the `### Skills` section, remove `conventions` from the "coming in later stories" line and list it as shipped, e.g.: -```markdown -### Skills -- `conventions` — auto-invoking graph-hygiene rulebook for the knowledge pack (how to model and recall knowledge well). -- _Coming in later stories_: `capture` (broad note capture), `recall` (windowed retrieval). -``` -Also add `skills/` to the `## Layout` section if it isn't already listed. - -- [ ] **Step 2: Commit** - -```bash -git add plugins/elephant/README.md -git commit -m "docs(elephant): list conventions skill in README" -``` - ---- - -## Task 3: Open the PR - -- [ ] **Step 1: Push and open** (controller handles) - -```bash -git push -u origin <branch> -gh pr create --title "feat(elephant): add conventions rulebook skill" --body "<summary + link to story>" -``` -Expected: `lint-commits` + `lint-pr-title` pass (the `elephant` scope is already on `main`, so no scope risk this time). - ---- - -## Post-merge - -Mark the story `completed` on this PR's branch (last commit flips status), per the WBS completion rule — this story is a single PR, so the completion bump rides it directly. release-please opens an `elephant` patch/minor release PR. - -## Out of scope (later stories) - -- `capture` (story 3), `recall` (story 4) — they will reference this skill. -- gilbreth's defer-to-elephant refactor (story 5). diff --git a/wbs/gilbreth-wbs/elephant/conventions-skill-spec.md b/wbs/gilbreth-wbs/elephant/conventions-skill-spec.md deleted file mode 100644 index fe683ed..0000000 --- a/wbs/gilbreth-wbs/elephant/conventions-skill-spec.md +++ /dev/null @@ -1,67 +0,0 @@ ---- -type: wbs-note -title: Spec — conventions skill -archived: false -wbs-about: wbs/gilbreth-wbs/elephant/conventions-skill -kind: spec ---- - -# Spec — conventions skill - -**wbs-note frontmatter:** `kind=spec` (linked to `wbs/gilbreth-wbs/elephant/conventions-skill` by a `wbs-about` edge) - -## Goal - -Ship `elephant:conventions` — an auto-invoking skill that is the WBS-agnostic graph-hygiene rulebook for the `knowledge` pack. It makes Tusk's (unfamiliar-to-the-model) knowledge-modeling discipline explicit whenever the agent touches a knowledge graph, so notes are captured well and stay discoverable for windowed recall. It generalizes the Tusk-usage parts of gilbreth's `conventions.md` without any WBS vocabulary, and is the single source of modeling truth that `capture`, `recall` (later stories), and gilbreth (story #5) build on. - -## Architecture - -A single, skimmable `skills/conventions/SKILL.md` (a reference/flexible skill — principles adapted to context, not a rigid procedure). It auto-invokes via its `description` and points at the existing `references/availability-check.md` rather than restating it. - -### Trigger - -Auto-invokes whenever the agent is about to **model or query a Tusk knowledge graph** — read or write: creating/editing `note`s, choosing edges, tagging, archiving, or running queries. Rationale: Tusk is not a tool the base model knows, so explicit, proactively-surfaced rules prevent wrong assumptions. Because the trigger covers graph interaction generally (not just capture/recall flows), the rules surface even when the agent hand-models the graph directly. - -### Relationship to other skills - -- `capture` and `recall` (later stories) auto-fire for *their* moments (note-worthy work / start-of-work) and build on / may invoke `conventions` by name for the *how*. -- gilbreth's `conventions.md` defers to this skill for generic Tusk discipline (story #5), keeping only WBS-specific rules. -- Overlapping triggers (conventions + capture both firing on a write) are acceptable and intended — conventions supplies modeling rules; capture supplies the "write this now" action. - -## Components - -`skills/conventions/SKILL.md` sections (WBS-agnostic, grounded in the shipped `knowledge` pack — `note` type, `kind` enum, `references`/`supersedes` edges, `tags` pack): - -1. **Windowed memory principle** — the why: capture broadly, keep each note small and atomic, recall narrowly; the graph + indexation is what keeps recall windowed. -2. **Note granularity & `kind`** — one idea per note; how to choose `learning | decision | open-thread | checkpoint`. -3. **Create vs. append vs. supersede** — when to write a new `note`, extend an existing one, or `archived=true` + a `supersedes` edge (append-only history). -4. **Discoverability** — write titles/bodies the indexer and semantic search can find; link related notes with `[[wikilinks]]` (→ `references`); tag topics via the `tags` pack so "everything about X" is queryable. -5. **Archive semantics** — `archived=true` is the soft-delete/supersede marker; never hard-delete. -6. **Tool discipline** — MCP-preferred / CLI-fallback; the write-lock note; pointer to `references/availability-check.md`. - -## Data flow - -1. Agent is about to read/write a Tusk knowledge graph → `conventions` auto-invokes → the agent has the modeling rules in context. -2. `capture`/`recall` (later) and gilbreth (story #5) reference these rules instead of re-encoding them. - -## Error handling - -- No knowledge graph present: the rules still apply once a graph exists; the availability-check / bootstrap-offer behavior lives in `references/availability-check.md` (and capture/recall), not here. `conventions` is guidance, not a graph mutation, so it has no failure modes of its own. - -## Verification - -- `skills/conventions/SKILL.md` exists with valid skill frontmatter (`name`, `description`); the `description` triggers on Tusk knowledge-graph interaction. -- Content covers all six sections above, uses only the `knowledge`-pack vocabulary (no `wbs-node`/levels/Karpathy), and references `availability-check.md` rather than duplicating it. -- Plugin still loads (`elephant` appears in the catalog; skill is discoverable). -- Manual smoke: in a workspace with the knowledge pack, a graph-modeling prompt surfaces the skill and its rules. - -## Out of scope - -- `capture` / `recall` skill logic (stories 3–4). -- gilbreth's refactor to defer to this skill (story #5). -- Re-stating the availability-check procedure (lives in `references/availability-check.md`). -- Any WBS-specific modeling rules. - -## Open questions - -- None. The rulebook content follows from the shipped knowledge pack and gilbreth's existing conventions; the trigger scope (read+write graph interaction) is settled. diff --git a/wbs/gilbreth-wbs/elephant/conventions-skill.md b/wbs/gilbreth-wbs/elephant/conventions-skill.md deleted file mode 100644 index bdbab84..0000000 --- a/wbs/gilbreth-wbs/elephant/conventions-skill.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -type: wbs-node -title: conventions skill -status: completed -order: 1 -level: story ---- - -# conventions skill - -## Outcome - -`elephant:conventions` — an auto-invoking skill that is the WBS-agnostic graph-hygiene rulebook for the `knowledge` pack. It makes Tusk's knowledge-modeling discipline explicit whenever the agent reads or writes a knowledge graph, so notes are captured well and stay discoverable for windowed recall. Generalizes gilbreth's `conventions.md` (Tusk-usage parts) without WBS vocabulary; the single source of modeling truth `capture`/`recall`/gilbreth build on. - -## Success Criteria - -- `plugins/elephant/skills/conventions/SKILL.md` exists with valid frontmatter; `description` auto-invokes on Tusk knowledge-graph interaction (read or write). -- Covers the six rulebook sections (windowed memory; note granularity & kind; create/append/supersede; discoverability; archive semantics; tool discipline). -- Uses only `knowledge`-pack vocabulary (no `wbs-node`/levels/Karpathy); references `references/availability-check.md` instead of restating it. -- Plugin still loads; skill is discoverable. - -## Assumptions Made - -- The knowledge pack (story 1) is shipped and its `note`/`kind`/`references`/`supersedes` + `tags` model is the vocabulary. - -## Open Questions - -none — content follows from the shipped pack and gilbreth's conventions; trigger scope (read+write graph interaction) settled. - -## Tradeoffs Considered - -- Auto-invoking skill (chosen) vs. a passive referenced rulebook: chose auto-invoke because Tusk is unfamiliar to the base model, so proactively surfacing the rules on any graph interaction prevents wrong assumptions; accepts benign trigger overlap with capture/recall. -- Single SKILL.md (chosen) vs. SKILL + split reference docs: chose one skimmable file; availability-check stays its own doc. - -## Out of Scope - -- `capture`/`recall` logic (stories 3–4); gilbreth's defer-to-elephant refactor (story 5). -- Re-stating the availability-check procedure; any WBS-specific rules. - -## Spec note - -[[wbs/gilbreth-wbs/elephant/conventions-skill-spec]] - -## Plan note - -[[wbs/gilbreth-wbs/elephant/conventions-skill-plan]] - -## Phasing - -No phases needed. - -## Tasks - -To be decomposed after planning. diff --git a/wbs/gilbreth-wbs/elephant/gilbreth-refactor-phase-1.md b/wbs/gilbreth-wbs/elephant/gilbreth-refactor-phase-1.md deleted file mode 100644 index 1e3854c..0000000 --- a/wbs/gilbreth-wbs/elephant/gilbreth-refactor-phase-1.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -type: wbs-note -title: Phase 1 handoff — Elephant core pack -phase: phase-1 -archived: false -kind: phase-plan -wbs-about: wbs/gilbreth-wbs/elephant/gilbreth-refactor ---- - -# Phase 1 handoff — Elephant `core` pack - -**wbs-note** `kind=phase-plan, phase=phase-1` on `wbs/gilbreth-wbs/elephant/gilbreth-refactor`. Cold-start handoff for a fresh session implementing Phase 1 only. - -## Read first (pull via Tusk) -- Plan (authoritative task detail): [[wbs/gilbreth-wbs/elephant/gilbreth-refactor-plan]] — **only the `PHASE 1` section**. -- Spec (rationale): [[wbs/gilbreth-wbs/elephant/gilbreth-refactor-spec]]. -- The MCP server holds the workspace write lock — prefer `tusk_*` MCP tools for graph reads. - -## Objective (Phase 1 only) -Turn Elephant's `knowledge.toml` into the marketplace's single canonical `core.toml` pack and repoint Elephant's own artifacts at it. Scope is **`elephant` only** — do NOT touch gilbreth (that's Phase 2) and do NOT migrate/retire anything (Phase 3). - -## Branch -`feat/elephant-core-pack` (off latest `main`). The planning notes (spec/plan/this handoff) are committed on it. - -## Tasks (see plan PHASE 1 for exact content) -1. **Task 1.1** — `git mv plugins/elephant/packs/knowledge.toml plugins/elephant/packs/core.toml` and rewrite it as the generic canonical pack: `node` (+ `kind`/`level`/`phase` string, `archived` bool, `order` int), `note` (`kind` string, `phase`, `archived`), edges `parent`/`about`/`supersedes`/`blocks`/`references` (`wikilinks=true`). The exact TOML is in the plan. Verify in a **scratch** workspace (`tusk doctor` clean; `note.kind` accepts arbitrary strings; `parent`+wikilink+`about` materialize). -2. **Task 1.2** — repoint `plugins/elephant/{commands/bootstrap.md, skills/conventions, skills/capture, skills/recall, references/availability-check.md, README.md}` from `knowledge.toml`→`core.toml`. The `note.kind` enum is now an open string — `conventions` documents learning|decision|open-thread|checkpoint as the *recommended* values. `capture`/`recall` are otherwise unaffected (they use `note`/`tags`/`references`/`supersedes`, all still present). -3. **Task 1.3** — open the PR. - -## Guardrails -- **Never mutate THIS repo's `tusk.toml` or live `wbs-*` nodes.** All pack verification happens in throwaway `mktemp -d` workspaces. This workspace stays on the old `gilbreth-wbs` pack until Phase 3. -- This is **breaking**: the PR title must be `feat(elephant)!: …` (or include a `BREAKING CHANGE:` footer) so release-please majors `elephant` (1.0.0 → 2.0.0). -- Keep `tusk doctor` clean. Tusk v1.4.0+ (already installed) for `wikilinks = true`. - -## Execution -Subagent-driven (superpowers:subagent-driven-development): dispatch one implementer for Tasks 1.1–1.2 (point it at this note + the plan via Tusk IDs), then a combined spec+quality review, then the controller opens the PR (Task 1.3). - -## Definition of done -`core.toml` loads clean; Elephant skills/bootstrap reference `core`; no `knowledge.toml` references remain; `feat(elephant)!` PR opened and green. Then STOP — Phase 2 (gilbreth) is a separate session, started only after this PR merges. diff --git a/wbs/gilbreth-wbs/elephant/gilbreth-refactor-plan.md b/wbs/gilbreth-wbs/elephant/gilbreth-refactor-plan.md deleted file mode 100644 index 6f6b4af..0000000 --- a/wbs/gilbreth-wbs/elephant/gilbreth-refactor-plan.md +++ /dev/null @@ -1,231 +0,0 @@ ---- -type: wbs-note -title: "Plan — gilbreth refactor: defer to elephant + unify on canonical types" -archived: false -kind: plan -wbs-about: wbs/gilbreth-wbs/elephant/gilbreth-refactor ---- - -# gilbreth refactor — Implementation Plan (phased) - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development. Steps use checkbox (`- [ ]`) syntax. -> -> **WBS note:** Plan for story `wbs/gilbreth-wbs/elephant/gilbreth-refactor`. Spec: [[wbs/gilbreth-wbs/elephant/gilbreth-refactor-spec]]. This is a single phased plan (light phasing); each phase is its own PR by scope. - -**Goal:** Converge the marketplace on one canonical Tusk type vocabulary owned by Elephant, make gilbreth defer to `elephant:conventions`, and migrate/retire accordingly. - -**Architecture:** Elephant ships the single canonical `core` pack (generic `node`/`note` with string `kind`/`level` + `parent`/`about`/`supersedes`/`blocks`/`references`); gilbreth consumes it and adds only the `wbs-workflow` behavior + retypes its artifacts. Breaking for both plugins (major bumps); two scopes → phase-1 is `elephant`, phase-2 is `gilbreth`, phase-3 is migration/retirement. - -**Tech stack:** Tusk type pack (TOML), Claude Code skills/commands/templates (markdown), `tusk` CLI for verification. - ---- - -## Phasing overview - -- **Phase 1 — Elephant `core` pack** (scope `elephant`, breaking). Rename `knowledge.toml`→`core.toml`; add generic structural types; `note.kind` enum→string; update Elephant's 3 skills + README. PR: `feat(elephant)!`. -- **Phase 2 — gilbreth defer + retype** (scope `gilbreth`, breaking). Consume `core`; add `wbs-workflow`; defer `conventions.md` to `elephant:conventions`; retype orientation/commands/templates; update `/wbs-bootstrap`. PR: `feat(gilbreth)!`. -- **Phase 3 — migration + retirement.** Ship `/wbs-migrate` (or a documented migration) in gilbreth; after phases 1–2 merge AND the initiative's nodes are marked completed, retire this repo's WBS tree. - -Do phases in order; each merges before the next starts (phase 2 consumes phase-1's published `core` pack; phase 3 retires only after both merge). - ---- - -## PHASE 1 — Elephant `core` pack - -### Task 1.1: Rebuild the pack as `core.toml` - -**Files:** -- Rename/Create: `plugins/elephant/packs/knowledge.toml` → `plugins/elephant/packs/core.toml` - -- [ ] **Step 1: `git mv` the pack and rewrite it** - -`git mv plugins/elephant/packs/knowledge.toml plugins/elephant/packs/core.toml`, then make `core.toml`: - -```toml -# Elephant — core type pack -# -# The marketplace's single canonical Tusk graph vocabulary. Generic: no -# WBS or domain semantics. `kind`/`level` are free strings so consumers -# (elephant's knowledge skills, gilbreth's WBS workflow, future plugins) -# specialize via string values without coupling enums. Tusk v1.4.0+. -# -# Compose with the built-in `tags` pack for topics. Other built-in packs -# (kanban/vault) are seeds you extend via `tusk pack add --force`. - -[node-types.node] -description = "A graph node — specialized by `kind`/`level` string values" -properties = [ - { name = "kind", type = "string" }, - { name = "level", type = "string" }, - { name = "phase", type = "string" }, - { name = "archived", type = "bool" }, - { name = "order", type = "int" }, -] - -[node-types.note] -description = "A note attached to nodes / the graph — specialized by `kind` string" -properties = [ - { name = "kind", type = "string" }, - { name = "phase", type = "string" }, - { name = "archived", type = "bool" }, -] - -[edge-types.parent] -description = "Hierarchy: this node is a child of another node" -from = ["node"] -to = ["node"] -cardinality = "many-to-one" -ordered = true -acyclic = true -inverse = "children" -hierarchy = "parent" - -[edge-types.about] -description = "This note is about a node" -from = ["note"] -to = ["node"] -cardinality = "many-to-one" -ordered = false -acyclic = true -inverse = "notes" - -[edge-types.supersedes] -description = "This note replaces a prior note (append-only history)" -from = ["note"] -to = ["note"] -cardinality = "many-to-one" -ordered = false -acyclic = true -inverse = "superseded-by" - -[edge-types.blocks] -description = "This node blocks another node" -from = ["node"] -to = ["node"] -cardinality = "many-to-many" -ordered = false -acyclic = true -inverse = "blocked-by" - -[edge-types.references] -description = "Implicit edge materialized from body [[wikilinks]] (wikilinks = true marks the materialization target, Tusk v1.4.0)." -from = ["*"] -to = ["*"] -cardinality = "many-to-many" -ordered = false -acyclic = false -inverse = "referenced-by" -wikilinks = true -``` - -Note: `parent` requires a sortable `order` property on its `from` node type (Tusk v1.3.0+ `ordered=true` rule) — `node` has `order`. No workflow behavior here (gilbreth adds `wbs-workflow` in phase 2). - -- [ ] **Step 2: Verify the pack loads + types behave** (scratch workspace) - -```bash -TMP=$(mktemp -d) && cd "$TMP" && git init -q && tusk init --name core-test -tusk pack add tags -tusk pack add "file://$OLDPWD/plugins/elephant/packs/core.toml" -tusk doctor -# note.kind accepts arbitrary strings; node + parent + wikilink work: -printf '# n1\n' | tusk node create --type node --path n/n1.md --prop level=project --prop order=0 -printf '# k\nSee [[n/n1]].\n' | tusk node create --type note --path k/k1.md --prop kind=learning -tusk node create --type note --path k/k2.md --prop kind=spec # arbitrary kind string OK -tusk edge add --type about --source k/k1 --target n/n1 -tusk edge list --from k/k1 # expect: references→n/n1 (wikilink) and about→n/n1 -cd - && rm -rf "$TMP" -``` -Expected: `doctor: no issues`; both `kind` values accepted; `references` + `about` edges present. If anything fails, STOP and report. - -- [ ] **Step 3: Commit** — `git add -A plugins/elephant/packs && git commit -m "feat(elephant)!: replace knowledge pack with canonical core pack"` - -### Task 1.2: Update Elephant skills + bootstrap + README for `core` - -**Files:** `plugins/elephant/commands/bootstrap.md`, `plugins/elephant/skills/conventions/SKILL.md`, `plugins/elephant/skills/capture/SKILL.md`, `plugins/elephant/skills/recall/SKILL.md`, `plugins/elephant/references/availability-check.md`, `plugins/elephant/README.md` - -- [ ] **Step 1: Repoint pack path + probe** - -`grep -rl 'knowledge.toml\|knowledge pack\|node-types.note\|type=note\|type:note' plugins/elephant` and update: `/bootstrap` adds `core.toml` (not `knowledge.toml`); the availability-check probe still uses `type=note`/`type:note` (unchanged — `note` still exists). The `kind` enum is now open — `conventions` documents the knowledge kinds (learning|decision|open-thread|checkpoint) as the **recommended** values, noting `kind` is a free string at the pack level. - -- [ ] **Step 2: Verify** — `grep -r 'knowledge.toml' plugins/elephant` returns nothing; `conventions` still lists the four knowledge kinds; capture/recall unaffected (they use `note`/`tags`/`references`/`supersedes`, all still present). - -- [ ] **Step 3: Commit** — `git commit -am "feat(elephant): point skills/bootstrap at the core pack"` - -### Task 1.3: Open Phase-1 PR (controller) - -- [ ] Push; `gh pr create --title "feat(elephant)!: canonical core type pack" --body "<summary; BREAKING: knowledge.toml→core.toml, note.kind enum→string, adds node/parent/about/blocks>"`. Ensure a `!`/`BREAKING CHANGE:` so release-please majors `elephant`. Merge before Phase 2. - ---- - -## PHASE 2 — gilbreth defer + retype - -Starts after Phase 1 merges. Read the spec + Elephant's `core.toml` first. - -### Task 2.1: Replace gilbreth's pack with the workflow extension - -**Files:** `plugins/gilbreth/packs/wbs.toml` - -- [ ] **Step 1:** Rewrite `wbs.toml` to declare ONLY the `[behaviors.workflow.wbs-workflow]` block (unchanged states/transitions) now targeting `node` (`applies-to = ["node"]`). Remove all `node-types.*`/`edge-types.*` (they come from `core`). Add a header comment: gilbreth consumes Elephant's `core` pack; this pack adds only the WBS workflow. - -- [ ] **Step 2: Verify** (scratch workspace): `tusk pack add core` then `tusk pack add wbs.toml`; `tusk doctor` clean; a `node` accepts `status` transitions per `wbs-workflow`. - -- [ ] **Step 3: Commit** — `git commit -am "feat(gilbreth)!: consume elephant core pack; keep only wbs-workflow"` - -### Task 2.2: Retype all gilbreth artifacts to canonical names - -**Files:** everything under `plugins/gilbreth/` referencing `wbs-`-prefixed TYPES (skills, commands, templates). - -- [ ] **Step 1: Find every reference** — `grep -rnE 'wbs-node|wbs-note|wbs-parent|wbs-about|wbs-supersedes|wbs-blocks|wbs-children|wbs-notes' plugins/gilbreth`. Map: `wbs-node`→`node`, `wbs-note`→`note`, `wbs-parent`→`parent`, `wbs-about`→`about`, `wbs-supersedes`→`supersedes`, `wbs-blocks`→`blocks`, inverses `wbs-children`→`children`, `wbs-notes`→`notes`. Apply across `wbs-orientation/SKILL.md`, the phase skills, all `commands/wbs-*.md`, and `templates/wbs/*`. **Do NOT** rename the pack name `gilbreth-wbs`, the `wbs-workflow` behavior, the `/wbs-*` command names, `level`/`kind` string values, or doc prose about "WBS" — only the Tusk TYPE/EDGE identifiers. - -- [ ] **Step 2: Verify** — the grep above returns nothing (no prefixed type identifiers remain); spot-check that `tusk_query 'type:node ...'` examples read correctly. - -- [ ] **Step 3: Commit** — `git commit -am "feat(gilbreth)!: retype WBS artifacts to canonical unprefixed types"` - -### Task 2.3: Defer conventions + update bootstrap - -**Files:** `plugins/gilbreth/templates/wbs/conventions.md`, `plugins/gilbreth/commands/wbs-bootstrap.md`, `plugins/gilbreth/skills/wbs-orientation/SKILL.md` - -- [ ] **Step 1:** In `conventions.md`, replace the generic Tusk-discipline sections (windowed access, node/append/supersede, naming, wikilinks, archive) with a pointer to `elephant:conventions`, keeping only WBS-specific rules (levels, Karpathy gate, phasing, reshape, completion/retirement). In `wbs-orientation`, add a line that it relies on `elephant:conventions` for generic graph hygiene. Update `/wbs-bootstrap` to `tusk pack add` Elephant's `core` pack (+ `tags`) then add the `wbs-workflow` (gilbreth's `wbs.toml`). - -- [ ] **Step 2: Verify** — `conventions.md` references `elephant:conventions`; no duplicated generic rules; `/wbs-bootstrap` installs `core` + workflow; `tusk doctor` clean in a fresh scratch bootstrap. - -- [ ] **Step 3: Commit** — `git commit -am "feat(gilbreth): defer generic conventions to elephant; bootstrap core pack"` - -### Task 2.4: Open Phase-2 PR (controller) - -- [ ] Push; `gh pr create --title "feat(gilbreth)!: consume elephant core pack and defer conventions" --body "<summary; BREAKING: type rename + pack change>"`. Ensure `!` for a `gilbreth` major bump. Merge before Phase 3. - ---- - -## PHASE 3 — migration + retirement - -### Task 3.1: Ship the migration helper/doc - -**Files:** `plugins/gilbreth/commands/wbs-migrate.md` (new) + a section in `conventions.md` or README - -- [ ] **Step 1:** Add a `/wbs-migrate` command documenting + performing the one-time migration for an existing workspace: rewrite node frontmatter `type: wbs-node`→`node` and `type: wbs-note`→`note`; rename edge keys `wbs-parent`→`parent`, `wbs-about`→`about`, `wbs-supersedes`→`supersedes`, `wbs-blocks`→`blocks` (and inverses) across `wbs/**/*.md`; replace the pack section in `tusk.toml` (drop old `wbs-*` type decls; `tusk pack add core --force` + add `wbs-workflow`); `tusk reindex`. Idempotent; instruct committing the result. Surface that markdown is git-tracked so it's recoverable. - -- [ ] **Step 2: Verify** (scratch workspace seeded with a couple of old `wbs-node`/`wbs-parent` files + the old pack): run the procedure; `tusk doctor` clean; `tusk query 'type:node'` returns the migrated nodes; edges intact. - -- [ ] **Step 3: Commit + PR** — `feat(gilbreth): add /wbs-migrate for the canonical-type migration`. - -### Task 3.2: Retire this repo's WBS tree (after the initiative is complete) - -**Files:** `wbs/gilbreth-wbs/**`, roadmap doc - -- [ ] **Step 1: Pre-req** — only after Phases 1–2 are merged AND every Elephant initiative node (incl. this story) is marked `completed`. Per `conventions.md` "Retiring a completed project": confirm terminal states, then `git rm -r wbs/gilbreth-wbs/` and `wbs/gilbreth-wbs.md`. -- [ ] **Step 2:** Update `docs/superpowers/gilbreth-wbs-roadmap.md`: move Elephant (#4) to **Done**, link spec/plan record (note: tracking tree retired; recoverable from git history). -- [ ] **Step 3: Commit + PR** — `chore(gilbreth): retire completed Elephant WBS tracking tree` (or `docs` scope for the roadmap). This is the commit that follows the initiative's completion. - ---- - -## Self-review notes / risks - -- Sequence strictly: phase 2 needs phase-1's `core` pack published; phase 3 retires only after 1–2 merge. -- This workspace runs on `wbs-*` types NOW; do not change *this repo's* `tusk.toml`/nodes until phase 3 (retirement) — phases 1–2 change shipped plugin artifacts, not this repo's live tracking graph. (If a phase-2 verification needs the new types in THIS workspace, use a scratch workspace, never the live one.) -- Each phase keeps `tusk doctor` clean and is independently reviewable. - -## Out of scope - -- New capabilities; Researcher (#6); roadmap Engineering-conventions (#5). -- Changing WBS semantics — only type names + generic-discipline delegation change. diff --git a/wbs/gilbreth-wbs/elephant/gilbreth-refactor-spec.md b/wbs/gilbreth-wbs/elephant/gilbreth-refactor-spec.md deleted file mode 100644 index 403d177..0000000 --- a/wbs/gilbreth-wbs/elephant/gilbreth-refactor-spec.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -type: wbs-note -title: "Spec — gilbreth refactor: defer to elephant + unify on canonical types" -kind: spec -archived: false -wbs-about: wbs/gilbreth-wbs/elephant/gilbreth-refactor ---- - -# Spec — gilbreth refactor: defer to elephant + unify on canonical types - -**wbs-note frontmatter:** `kind=spec` (linked to `wbs/gilbreth-wbs/elephant/gilbreth-refactor` by a `wbs-about` edge) - -## Goal - -Converge the marketplace on a single canonical Tusk type vocabulary owned by Elephant, and make gilbreth defer to `elephant:conventions` for generic graph discipline. This removes the duplication created by extracting Elephant and replaces the `wbs-`-prefixed types with unprefixed canonical types shared across plugins. - -## Architecture - -### One canonical pack, owned by Elephant - -Elephant's `knowledge.toml` becomes the marketplace's single canonical graph-vocabulary pack, renamed `core.toml`. All types are generic (no WBS semantics); `kind`/`level` are free **strings** (not enums) so the vocabulary stays generic and the plugins stay decoupled — each plugin documents its own `kind`/`level` values. - -- `node` — props: `kind` (string), `level` (string), `phase` (string), `archived` (bool), `order` (int) -- `note` — props: `kind` (string), `phase` (string), `archived` (bool) -- `parent` — node→node, ordered, acyclic, hierarchy (the structural hierarchy edge) -- `about` — note→node -- `supersedes` — note→note (append-only history; unifies gilbreth's `wbs-supersedes` and Elephant's `supersedes`) -- `blocks` — node→node -- `references` — `*`→`*`, `wikilinks = true` -- composes with the built-in `tags` pack (`tag` nodes + `tagged` edge) - -Elephant's own skills (`conventions`/`capture`/`recall`) use only `note`/`references`/`supersedes`/`tags`; the generic `node`/`parent`/`about`/`blocks` live in the canonical pack for gilbreth and other consumers (Elephant owns the canonical vocabulary even for types it doesn't itself use). - -### gilbreth extends what's in place - -gilbreth stops declaring its own node/note/edge types. It consumes Elephant's `core` pack and adds only the genuinely WBS-specific part: the **`wbs-workflow` behavior** (the status state machine on `node`). Concretely: - -- `conventions.md` defers to `elephant:conventions` for generic Tusk discipline; keeps only WBS-specific rules (levels, Karpathy gate, phasing, reshape). -- `wbs-orientation`, all `/wbs-*` commands, and the `templates/wbs/*` switch to the unprefixed canonical types (`node`/`note`/`parent`/`about`/`supersedes`/`blocks`). -- `level` and note `kind` are populated as string values (project|milestone|… and spec|plan|…) on the canonical types; validated by gilbreth convention, not a pack enum. - -### Bootstrap - -- Elephant's `/bootstrap` installs `core` + `tags`. -- gilbreth's `/wbs-bootstrap` installs Elephant's `core` pack (+ `tags`) and adds the `wbs-workflow` behavior to the manifest. - -## Migration - -- **This repo's WBS tree:** do NOT hand-rewrite the live `wbs-*` nodes. This is the last Elephant story — once it completes, the initiative is done, so **retire the WBS tracking tree** (per the `conventions.md` "Retiring a completed project" procedure: `git rm` the `wbs/gilbreth-wbs/` subtree + node after marking everything completed). Sidesteps migrating historical nodes. -- **Other workspaces + gilbreth's own artifacts:** ship a documented migration (or a small `/wbs-migrate` helper) that rewrites prefixed frontmatter (`type: wbs-node`→`node`, edge keys `wbs-parent`→`parent`, etc.) and updates the pack section in `tusk.toml`, then reindexes. Markdown is git-tracked, so the migration is recoverable. - -## Phasing - -Phased (light, at story level). Proposed phases — confirmed/refined at planning: - -1. **Elephant core pack.** Rename `knowledge.toml`→`core.toml`; add the generic `node`/`parent`/`about`/`blocks` types; change `note.kind` enum→string; declare `supersedes`/`references` canonically. Update Elephant's three skills for the (mostly unchanged) generic vocabulary. Scope `elephant` (breaking → major bump). -2. **gilbreth defer + retype.** Remove gilbreth's type declarations; add the `wbs-workflow` behavior on `node`; point `conventions.md` at `elephant:conventions`; retype `wbs-orientation`/commands/templates to canonical names; update `/wbs-bootstrap`. Scope `gilbreth` (breaking → major bump). -3. **Migration + retirement.** Ship the migration doc/helper; retire this repo's WBS tree after the initiative is marked complete. - -## Error handling / risk - -- **Breaking for both plugins** (Elephant `note.kind` enum→string + pack rename; gilbreth's entire type vocabulary) → major version bumps for `elephant` and `gilbreth`. -- **Two component scopes** (`elephant`, `gilbreth`) + `marketplace` if catalog metadata changes → separate PRs per the repo's one-scope-per-squash-commit rule. -- **Live-graph risk:** the workspace we're working in uses `wbs-*` types. Sequence so gilbreth's pack/type changes don't break the in-flight tree before retirement; do phase 3 (retire) only after phases 1–2 are merged and the initiative's nodes are marked completed. -- `tusk doctor` must stay clean after each phase; `--force` reconciles identical re-adds. - -## Verification - -- Elephant `core` pack loads; `tusk doctor` clean; `note.kind` accepts arbitrary strings; `node`/`parent`/`about`/`blocks` declared. -- gilbreth: `wbs-orientation` + gates still drive WBS flows with the canonical types (no behavioral regression); `conventions.md` references `elephant:conventions`; no `wbs-`-prefixed type names remain in gilbreth artifacts. -- Migration doc/helper rewrites a sample prefixed node + tusk.toml correctly and reindexes clean. -- This repo's WBS tree retired (subtree removed) only after the initiative is marked complete. -- Both plugins still load; release-please opens major-bump release PRs for `elephant` and `gilbreth`. - -## Out of scope - -- New Elephant capabilities; Researcher (#6); Engineering conventions (#5 of the roadmap). -- Changing WBS semantics (levels, Karpathy gate, phasing, reshape stay — only their type names + the generic-discipline delegation change). - -## Open questions - -- `/wbs-migrate` helper vs. a documented manual migration — decided at planning (leaning: documented steps + a thin command, since other workspaces need it). -- Whether gilbreth declares a formal plugin dependency on elephant or just relies on the `core` pack being installed — decided at planning. diff --git a/wbs/gilbreth-wbs/elephant/gilbreth-refactor.md b/wbs/gilbreth-wbs/elephant/gilbreth-refactor.md deleted file mode 100644 index 1af4fcb..0000000 --- a/wbs/gilbreth-wbs/elephant/gilbreth-refactor.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -type: wbs-node -title: "gilbreth refactor: defer to elephant + drop type prefixes" -level: story -status: completed -order: 4 ---- - -# gilbreth refactor: defer to elephant + drop type prefixes - -## Outcome - -gilbreth is brought in line with Elephant on two fronts: (1) its generic Tusk discipline defers to `elephant:conventions` (keeping only WBS-specific rules — levels, Karpathy gate, phasing, reshape); and (2) it adopts the cross-plugin unprefixed canonical type convention, stripping the `wbs-` prefixes (`wbs-node`→`node`, `wbs-note`→`note`, `wbs-parent`→`parent`, `wbs-about`→`about`, `wbs-supersedes`→`supersedes`, `wbs-blocks`→`blocks`). Built-in packs (kanban/vault) become seeds extended via `--force` rather than packs to avoid. - -## Success Criteria - -- gilbreth's `conventions.md` / `wbs-orientation` reference `elephant:conventions` for generic Tusk discipline; no behavioral regression in WBS flows or gates. -- The WBS pack and all skill/command/template references use unprefixed canonical types; `tusk doctor` clean. -- A migration path exists for existing `wbs-`-prefixed node frontmatter (rename or reindex). -- Documentation records that gilbreth intentionally owns the canonical `node`/`note`/`parent`/`blocks`/`references` types and that kanban/vault are seeds, not collisions. - -## Assumptions Made - -- Elephant stories 1–4 (pack, conventions, capture, recall) ship first. -- Claude Code resolves `elephant:conventions` cross-plugin references at runtime. -- `--force` cleanly handles identical-type re-adds. - -## Open Questions - -- Migration mechanism for existing prefixed frontmatter (in-place rename + reindex vs. regenerate) — resolved at this story's brainstorm. -- Whether gilbreth declares a formal dependency on elephant or references it by name. - -## Tradeoffs Considered - -- Resolved at this story's brainstorm. Note the accepted trade: unprefixed names mean WBS + kanban/vault coexist only via the canonical-type + `--force` convention, not via prefix isolation. - -## Out of Scope - -- Building Elephant's skills/pack (stories 1–4). - -## Spec note - -[[wbs/gilbreth-wbs/elephant/gilbreth-refactor-spec]] - -## Plan note - -[[wbs/gilbreth-wbs/elephant/gilbreth-refactor-plan]] - -## Phasing - -Likely phased (defer-to-elephant vs. prefix migration are separable chunks) — confirmed at planning. - -## Tasks - -To be decomposed after this story is brainstormed and planned. diff --git a/wbs/gilbreth-wbs/elephant/knowledge-pack-plan.md b/wbs/gilbreth-wbs/elephant/knowledge-pack-plan.md deleted file mode 100644 index 2ceb2ed..0000000 --- a/wbs/gilbreth-wbs/elephant/knowledge-pack-plan.md +++ /dev/null @@ -1,468 +0,0 @@ ---- -type: wbs-note -title: Plan — knowledge pack + /bootstrap + availability check -kind: plan -archived: false -wbs-about: wbs/gilbreth-wbs/elephant/knowledge-pack ---- - -# Knowledge pack + /bootstrap + availability check — Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. -> -> **WBS note:** This plan is the `kind=plan` note for story `wbs/gilbreth-wbs/elephant/knowledge-pack`. Tasks below become `level=task` child wbs-nodes via `/wbs-new … task=wbs/gilbreth-wbs/elephant/knowledge-pack`. Spec: [[wbs/gilbreth-wbs/elephant/knowledge-pack-spec]]. - -**Goal:** Scaffold the `elephant` plugin and ship its generic `knowledge` Tusk pack (`note` type + `references`/`supersedes` edges), a `/bootstrap` command, and a shared availability-check doc — registered in the marketplace and release-please. - -**Architecture:** A new inline plugin under `plugins/elephant/` following the gilbreth plugin's layout. The pack declares unprefixed canonical types per the cross-plugin convention; `references` uses Tusk v1.4.0's `wikilinks = true` flag. Work lands as **two squash PRs** by scope: PR-A `feat(elephant)` (plugin + pack + command + doc + release-please onboarding), PR-B `feat(marketplace)` (catalog entry). - -**Tech Stack:** Claude Code plugin manifests (JSON), Tusk v1.4.0 type pack (TOML), markdown command/skill docs, release-please + commitlint config. "Tests" are validation commands (`jq`, `tusk doctor`, `tusk pack add`, wikilink probe, `npx commitlint`). - ---- - -## File structure - -PR-A (`feat(elephant)`): -- Create `plugins/elephant/.claude-plugin/plugin.json` — plugin manifest (version 0.0.0) -- Create `plugins/elephant/package.json` — release-please package (version 0.0.0) -- Create `plugins/elephant/packs/knowledge.toml` — the knowledge type pack -- Create `plugins/elephant/commands/bootstrap.md` — `/bootstrap` command -- Create `plugins/elephant/references/availability-check.md` — shared availability-check procedure -- Create `plugins/elephant/README.md` — plugin overview -- Modify `release-please-config.json` — add `plugins/elephant` package entry -- Modify `.release-please-manifest.json` — seed `"plugins/elephant": "0.0.0"` -- Modify `commitlint.config.mjs` — add `elephant` to `scope-enum` -- Modify `.github/workflows/lint-pr-title.yml` — add `elephant` to `scopes` - -PR-B (`feat(marketplace)`): -- Modify `.claude-plugin/marketplace.json` — append `elephant` to `plugins[]` - ---- - -## Task 1: Scaffold the elephant plugin manifest - -**Files:** -- Create: `plugins/elephant/.claude-plugin/plugin.json` -- Create: `plugins/elephant/package.json` - -- [ ] **Step 1: Write `plugins/elephant/.claude-plugin/plugin.json`** - -```json -{ - "name": "elephant", - "description": "Makes Tusk the agent's short-to-medium-term memory keeper: capture learnings broadly into a knowledge graph and recall them narrowly (windowed) so knowledge transfers seamlessly across sessions.", - "version": "0.0.0", - "author": { - "name": "German Meza", - "email": "iam@germanamz.com" - }, - "homepage": "https://github.com/germanamz/superhuman", - "repository": "https://github.com/germanamz/superhuman", - "license": "MIT", - "keywords": [] -} -``` - -- [ ] **Step 2: Write `plugins/elephant/package.json`** - -```json -{ "name": "elephant", "version": "0.0.0", "private": true } -``` - -- [ ] **Step 3: Validate JSON** - -Run: `jq . plugins/elephant/.claude-plugin/plugin.json plugins/elephant/package.json` -Expected: both pretty-print with no parse error; `version` is `"0.0.0"` in each. - -- [ ] **Step 4: Commit** - -```bash -git add plugins/elephant/.claude-plugin/plugin.json plugins/elephant/package.json -git commit -m "feat(elephant): scaffold plugin manifest" -``` - ---- - -## Task 2: Create the knowledge pack - -**Files:** -- Create: `plugins/elephant/packs/knowledge.toml` - -- [ ] **Step 1: Write `plugins/elephant/packs/knowledge.toml`** - -```toml -# Elephant — knowledge type pack -# -# A generic, WBS-agnostic knowledge graph for capturing learnings as the -# agent's short-to-medium-term memory. Declares canonical, UNPREFIXED types -# per the cross-plugin convention (built-in packs are seeds extended via -# `--force`, not collisions to avoid). -# -# Minimum Tusk version: v1.4.0 — the `references` edge uses the -# `wikilinks = true` flag to mark itself as the wikilink-materialization -# target (configurable as of v1.4.0; in v1.3.0 the materializer hard-coded -# the edge name `references`). -# -# Composition: layer the built-in `tags` pack (`tusk pack add tags`) for -# topics (`tag` nodes + `tagged` edge). `references` is `--force`-safe -# against the vault/WBS packs because the declaration is identical. - -[node-types.note] -description = "A captured knowledge note — a learning, decision, open thread, or checkpoint" -properties = [ - { name = "kind", type = "enum", values = ["learning","decision","open-thread","checkpoint"] }, - { name = "archived", type = "bool" }, -] - -[edge-types.references] -description = "Implicit edge materialized from body [[wikilinks]]. `wikilinks = true` marks this edge as the materialization target (Tusk v1.4.0)." -from = ["*"] -to = ["*"] -cardinality = "many-to-many" -ordered = false -acyclic = false -inverse = "referenced-by" -wikilinks = true - -[edge-types.supersedes] -description = "This note replaces a prior note (append-only knowledge history)" -from = ["note"] -to = ["note"] -cardinality = "many-to-one" -ordered = false -acyclic = true -inverse = "superseded-by" -``` - -- [ ] **Step 2: Verify the pack loads in a scratch workspace** - -```bash -TMP=$(mktemp -d) && cd "$TMP" && git init -q && tusk init --name elephant-pack-test -tusk pack add tags -tusk pack add "file://$OLDPWD/plugins/elephant/packs/knowledge.toml" -tusk doctor -``` -Expected: `tusk doctor` reports `doctor: no issues` (a legacy `[undeclared-property] … status` warning, if any, is tolerable per the gilbreth precedent). - -- [ ] **Step 3: Verify the `wikilinks = true` materialization works (the v1.4.0 assumption)** - -```bash -printf '# t1\nSee [[notes/t2]].\n' | tusk node create --type note --path notes/t1.md --prop kind=learning -printf '# t2\n' | tusk node create --type note --path notes/t2.md --prop kind=learning -tusk edge list --from notes/t1 -``` -Expected: a `references` edge from `notes/t1` to `notes/t2` appears (materialized from the `[[notes/t2]]` wikilink). If it does NOT, the `wikilinks` key name is wrong for this Tusk build — STOP and confirm the exact flag via `tusk` docs / the v1.4.0 changelog (issue #410) before proceeding. - -- [ ] **Step 4: Verify `supersedes`** - -```bash -tusk edge add --type supersedes --source notes/t2 --target notes/t1 -tusk edge list --from notes/t2 -``` -Expected: a `supersedes` edge from `notes/t2` to `notes/t1`. Then `cd - && rm -rf "$TMP"`. - -- [ ] **Step 5: Commit** - -```bash -git add plugins/elephant/packs/knowledge.toml -git commit -m "feat(elephant): add knowledge type pack" -``` - ---- - -## Task 3: Create the /bootstrap command - -**Files:** -- Create: `plugins/elephant/commands/bootstrap.md` - -Model on `plugins/gilbreth/commands/wbs-bootstrap.md` (same idempotent shape). - -- [ ] **Step 1: Write `plugins/elephant/commands/bootstrap.md`** - -````markdown ---- -description: Initialize the current repo as a Tusk workspace and install Elephant's knowledge pack (plus the built-in tags pack) so capture/recall can write the agent's memory graph. -argument-hint: [name=<workspace-name>] ---- - -# /bootstrap - -Bootstrap the current working directory for Elephant's knowledge graph on Tusk v1.4.0+. Idempotent: safe to re-run. Initializes a Tusk workspace (if absent), adds the built-in `tags` pack and Elephant's `knowledge` pack, then prints what-to-do-next. - -This is the one-time init that Elephant's `capture`/`recall` skills offer when they detect no graph. Once the pack is in place it's a no-op. - -## Input - -Optional free-form text. Recognized keyword params: - -- `name=<workspace-name>` — override the workspace name. Defaults to the basename of the current directory. - -## Procedure - -1. **Detect existing workspace.** Run `tusk status`. If it succeeds, skip step 2 with a soft note: "Tusk workspace already initialized at <root>." If it fails because no workspace was found, continue. - -2. **Initialize the workspace.** Run `tusk init --name <name>` (`<name>` = the `name=` keyword if supplied, else `$(basename "$PWD")`). Hard error on failure. Ensure `.tusk/` is gitignored — append a `.tusk/` line to `.gitignore` if absent. - -3. **Add the tags pack.** Run `tusk pack add tags`. Idempotent; surface stderr verbatim on failure. - -4. **Detect existing knowledge pack.** Read `tusk.toml`; if `[node-types.note]` is present, skip step 5 with a soft note: "knowledge pack already present." - -5. **Add the knowledge pack.** Run: - - ```sh - tusk pack add "file://${CLAUDE_PLUGIN_ROOT}/packs/knowledge.toml" - ``` - - Use `--force` only if step 4 detected a colliding but equivalent declaration. Hard error on other failures. - -6. **Verify with `tusk doctor`.** Surface output verbatim. Expect `doctor: no issues`. - -7. **Print what to do next.** - - > Knowledge graph ready. Elephant's capture/recall will now use it automatically. Tag notes by topic (the `tags` pack is installed). To enable semantic recall, configure `[embeddings]` in `tusk.toml`. - -## Errors - -- **Tusk CLI not on PATH** — hard error; point at the Tusk v1.4.0+ install (`github.com/germanamz/tusk` releases). -- **Tusk older than v1.4.0** — the `wikilinks = true` flag in `knowledge.toml` requires v1.4.0; surface a clear version error. -- **`${CLAUDE_PLUGIN_ROOT}/packs/knowledge.toml` not found** — corrupted install; recommend reinstalling the `elephant` plugin. - -## Examples - -``` -/bootstrap -/bootstrap name=my-project -``` -```` - -- [ ] **Step 2: Validate frontmatter present** - -Run: `head -4 plugins/elephant/commands/bootstrap.md` -Expected: a YAML frontmatter block with `description:` and `argument-hint:`. - -- [ ] **Step 3: Commit** - -```bash -git add plugins/elephant/commands/bootstrap.md -git commit -m "feat(elephant): add /bootstrap command" -``` - ---- - -## Task 4: Create the shared availability-check doc - -**Files:** -- Create: `plugins/elephant/references/availability-check.md` - -Resolves the spec's open question: the procedure lives in its own `references/` doc (decoupled from the `conventions` skill, which ships in a later story). `capture` and `recall` will link to it. - -- [ ] **Step 1: Write `plugins/elephant/references/availability-check.md`** - -```markdown -# Availability check - -Both `capture` and `recall` gate on this before touching the graph. - -## Procedure - -1. **Probe for the knowledge pack.** Query the `note` type: - - MCP: `tusk_query type=note take=1` - - CLI: `tusk query 'type:note' --take 1` - An "unknown node type" / undeclared-type error means the `knowledge` pack is NOT installed. A success (even zero rows) means it is. - -2. **If present:** proceed silently. Operate on the graph. - -3. **If absent:** emit the bootstrap offer ONCE per session: - - > No knowledge graph here yet. Run `/bootstrap` to let me start keeping notes for this workspace, or I'll stay quiet about it for now. - - Record that the offer was made. If the user declines (or doesn't act), go **dormant for the session** — do not re-offer, do not re-probe on every note-worthy moment. - -## Notes - -- MCP-preferred, CLI-fallback (the MCP server may hold the write lock; prefer MCP tools). -- "Once per session" is per Elephant skill activation context; mirror wbs-orientation's once-per-session degraded-mode hint discipline. -``` - -- [ ] **Step 2: Commit** - -```bash -git add plugins/elephant/references/availability-check.md -git commit -m "feat(elephant): add shared availability-check doc" -``` - ---- - -## Task 5: Plugin README - -**Files:** -- Create: `plugins/elephant/README.md` - -- [ ] **Step 1: Write `plugins/elephant/README.md`** - -```markdown -# elephant - -Makes Tusk the agent's short-to-medium-term memory keeper. Capture learnings broadly into a knowledge graph and recall them narrowly (windowed) so knowledge transfers seamlessly across sessions. - -## What ships - -### Commands -- `/bootstrap` — initialize a Tusk workspace and install the `knowledge` + `tags` packs. - -### Packs -- `packs/knowledge.toml` — a generic, WBS-agnostic knowledge graph: a `note` type (`kind`: learning | decision | open-thread | checkpoint) with `references` (wikilink-materialized) and `supersedes` edges. Requires Tusk v1.4.0+. - -### Skills -- _Coming in later stories_: `conventions` (graph-hygiene rulebook), `capture` (broad note capture), `recall` (windowed retrieval). - -## Conventions - -Declares canonical, unprefixed Tusk types. Built-in packs (`tags`, `kanban`, `vault`) are seeds you extend via `tusk pack add … --force`, not collisions to avoid. -``` - -- [ ] **Step 2: Commit** - -```bash -git add plugins/elephant/README.md -git commit -m "docs(elephant): add plugin README" -``` - ---- - -## Task 6: Register with release-please + lint scopes - -**Files:** -- Modify: `release-please-config.json` -- Modify: `.release-please-manifest.json` -- Modify: `commitlint.config.mjs` -- Modify: `.github/workflows/lint-pr-title.yml` - -- [ ] **Step 1: Add the package entry to `release-please-config.json`** (inside `packages`, after the `plugins/gilbreth` block) - -```json - "plugins/elephant": { - "component": "elephant", - "package-name": "elephant", - "changelog-path": "CHANGELOG.md", - "pull-request-title-pattern": "chore(elephant): release ${version}", - "extra-files": [ - { - "type": "json", - "path": ".claude-plugin/plugin.json", - "jsonpath": "$.version" - }, - { - "type": "json", - "path": "/.claude-plugin/marketplace.json", - "jsonpath": "$.plugins[?(@.name==\"elephant\")].version" - } - ] - } -``` - -- [ ] **Step 2: Seed `.release-please-manifest.json`** - -```json -{ - ".": "0.3.0", - "plugins/gilbreth": "0.4.0", - "plugins/elephant": "0.0.0" -} -``` - -- [ ] **Step 3: Add `elephant` to the commitlint `scope-enum`** - -In `commitlint.config.mjs`, change the scope-enum line to: -```js - 'scope-enum': [2, 'always', ['marketplace', 'gilbreth', 'elephant']], -``` - -- [ ] **Step 4: Add `elephant` to the lint-pr-title `scopes`** - -In `.github/workflows/lint-pr-title.yml`, the `scopes:` block becomes: -```yaml - scopes: | - marketplace - gilbreth - elephant -``` - -- [ ] **Step 5: Validate** - -Run: `jq . release-please-config.json .release-please-manifest.json && node -e "import('./commitlint.config.mjs').then(m=>console.log(m.default.rules['scope-enum'][2]))"` -Expected: both JSON files parse; the printed array includes `elephant`. - -- [ ] **Step 6: Commit** - -```bash -git add release-please-config.json .release-please-manifest.json commitlint.config.mjs .github/workflows/lint-pr-title.yml -git commit -m "feat(elephant): onboard elephant to release-please and lint scopes" -``` - ---- - -## Task 7: Open PR-A - -- [ ] **Step 1: Push and open the PR** - -```bash -git push -u origin <branch> -gh pr create --title "feat(elephant): scaffold elephant plugin with knowledge pack" --body "<summary + link to story wbs/gilbreth-wbs/elephant/knowledge-pack>" -``` - -- [ ] **Step 2: Watch the required checks** - -Run: `gh pr checks --watch` -Expected: `lint-commits` and `lint-pr-title` pass. -**Known risk:** `lint-pr-title` may evaluate the `scopes` list from `main` (base branch), where `elephant` isn't present yet, and reject the `feat(elephant)` title. If it fails for that reason: either (a) land the scope additions (Task 6 steps 3–4) as a tiny precursor `chore(marketplace)` PR first, then rebase PR-A; or (b) confirm the action reads the head ref and retry. Do NOT `--no-verify`-bypass; the CI checks are unbypassable. - ---- - -## Task 8: Register in the marketplace (PR-B, separate scope) - -**Files:** -- Modify: `.claude-plugin/marketplace.json` - -- [ ] **Step 1: Branch from main** (after PR-A merges, so the catalog points at a real plugin dir) - -```bash -git checkout main && git pull && git checkout -b feat/register-elephant -``` - -- [ ] **Step 2: Append to `plugins[]` in `.claude-plugin/marketplace.json`** - -```json - { - "name": "elephant", - "version": "0.0.0", - "description": "Makes Tusk the agent's short-to-medium-term memory keeper: capture learnings broadly into a knowledge graph and recall them narrowly across sessions.", - "source": "./plugins/elephant" - } -``` - -- [ ] **Step 3: Validate** - -Run: `jq '.plugins[] | select(.name=="elephant") | .source' .claude-plugin/marketplace.json && test -f plugins/elephant/.claude-plugin/plugin.json && echo "source resolves"` -Expected: prints `"./plugins/elephant"` and `source resolves`. - -- [ ] **Step 4: Commit, push, open PR-B** - -```bash -git add .claude-plugin/marketplace.json -git commit -m "feat(marketplace): register elephant plugin" -git push -u origin feat/register-elephant -gh pr create --title "feat(marketplace): register elephant plugin" --body "Registers the elephant plugin scaffolded in PR-A." -``` - ---- - -## Post-merge - -After both PRs merge, release-please opens two release PRs: `elephant` (0.0.0 → 0.1.0, tag `elephant-v0.1.0`) and `marketplace` (catalog bump). Merge both to publish. Then mark this story `completed` on its own PR per the WBS "Marking a node completed" convention — i.e., the status bump rides PR-A (the plugin work), not a later story's branch. - -## Out of scope (deferred to later stories) - -- `conventions`, `capture`, `recall` skill logic. -- Stripping `wbs-` prefixes from gilbreth (story #5). -- `[embeddings]` configuration. diff --git a/wbs/gilbreth-wbs/elephant/knowledge-pack-spec.md b/wbs/gilbreth-wbs/elephant/knowledge-pack-spec.md deleted file mode 100644 index 5ae409b..0000000 --- a/wbs/gilbreth-wbs/elephant/knowledge-pack-spec.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -type: wbs-note -title: Spec — knowledge pack + /bootstrap + availability check -archived: false -kind: spec ---- - -# Spec — knowledge pack + /bootstrap + availability check - -**wbs-note frontmatter:** `kind=spec` (linked to `wbs/gilbreth-wbs/elephant/knowledge-pack` by a `wbs-about` edge) - -## Goal - -Deliver the foundation the rest of the Elephant initiative builds on: a generic, WBS-agnostic `knowledge` Tusk pack, a `/bootstrap` command that installs it (composing with the built-in `tags` pack), and a shared availability-check routine that `capture` and `recall` gate on. This story also scaffolds the `elephant` plugin itself and registers it in the marketplace. - -## Architecture - -A Tusk type pack + a slash command + a small reusable availability-check procedure, shipped inside a new `elephant` plugin directory. - -### Type model — unprefixed, canonical - -Following the cross-plugin convention decision (drop the `wbs-`-style prefixes; declare canonical unprefixed types and use built-in packs as a seed), the `knowledge` pack declares: - -**Node type `note`** -- `kind` — enum: `learning | decision | open-thread | checkpoint` -- `archived` — bool (append-only / supersede pattern, same discipline as the WBS notes) -- No lifecycle/status property in v1. Resolving an open-thread = archive it (and optionally a superseding note). An `open → resolved` workflow is a possible v2. - -**Edge `references`** -- Declared with `wikilinks = true` (Tusk v1.4.0): this edge is the materialization target for body `[[wikilinks]]`. In v1.3.0 the materializer hard-coded the edge name `references`; v1.4.0 makes the target configurable via the flag (changelog: "configurable wikilink-materialization edge via wikilinks flag", issue #410). We keep the name `references` by convention, not constraint. -- `from`/`to` = `["*"]`, identical to the canonical declaration the WBS/vault packs use, so it is `--force`-safe when multiple packs are present (re-adding strips the duplicate and re-appends). -- Only one edge type carries `wikilinks = true` per workspace; all packs that declare it must agree (they declare the identical edge). - -**Edge `supersedes`** -- `note` → `note`. "This note replaces that one." Append-only knowledge history (the windowed-memory analogue of `wbs-supersedes`, now unprefixed under the unified convention). Set deliberately, not via wikilinks. - -### Composition - -- Layers with the built-in **`tags`** pack (`tag` nodes + `tagged` edge) — topics are tags, not custom anchor nodes. Recall pulls "everything known about topic X" via `tagged`. -- `--force` is the intended mechanism for identical-type coexistence: because canonical declarations match across packs, `tusk pack add … --force` removes colliding sections and re-appends cleanly. The built-in packs (kanban/vault) are usable as a *starting point* you then extend, not competitors to avoid. - -## Components - -### `packs/knowledge.toml` -Declares `note`, `references` (`wikilinks = true`), `supersedes`. No workflow behavior (notes are append-only + archived, not state machines). - -### `commands/bootstrap.md` -One-time, idempotent init for a workspace: -1. `tusk init` if no `tusk.toml` exists. -2. `tusk pack add tags` (idempotent). -3. Add the `knowledge` pack (`--force`-safe). -4. Confirm via `tusk doctor` / a `note`-type probe. -Invoked by the offer-to-bootstrap-once path, or directly by the user. - -### Availability check (shared procedure) -A small routine (documented once, referenced by `capture` and `recall`): probe whether the `note` type is declared (e.g. a `tusk_node_list`/`tusk_query type=note` that errors on undeclared type, mirroring wbs-orientation's pack-presence probe). Returns present / absent. Absent → offer `/bootstrap` once per session, then dormant; present → silent. Where this procedure physically lives (a shared `references/` doc in the plugin, or inlined in `conventions`) is a plan-time detail. - -### Plugin scaffold -`plugins/elephant/.claude-plugin/plugin.json`, `plugins/elephant/package.json` (`version 0.0.0`), and the release-please onboarding from CONTRIBUTING (config entry, manifest seed, commitlint + lint-pr-title scope additions). Marketplace registration is a **separate PR** (`feat(marketplace)`), per the two-scope rule. - -## Data flow - -1. `/bootstrap` (or the offer path) → installs `tags` + `knowledge` → workspace now has the `note` type. -2. `capture` (later story) writes `note`s with a `kind`, `[[wikilinks]]` (→ `references`), and `tagged` topic links. -3. `recall` (later story) queries `type=note` + `tagged`/semantic to surface a narrow slice. - -## Error handling - -- No `tusk.toml`: `/bootstrap` runs `tusk init` first; the offer-once path surfaces the bootstrap offer rather than erroring. -- Pack already present: idempotent / `--force`-safe; re-running is a no-op or clean re-append. -- MCP write-lock contention: prefer MCP tools over the CLI (the MCP server holds the lock). -- Declined bootstrap: dormant for the session (no nagging), per the initiative spec. - -## Verification - -- `tusk pack add` of the `knowledge` pack + `tags` leaves `tusk doctor` clean. -- A `note` can be created with each `kind`; a body `[[wikilink]]` materializes a `references` edge (confirming `wikilinks = true` works on v1.4.0); a `supersedes` edge links two notes. -- `/bootstrap` is idempotent (second run is a no-op / clean). -- The availability check correctly reports present vs. absent. -- Plugin loads; `elephant` appears in the marketplace catalog after the registration PR; release-please opens the expected version PRs. - -## Out of scope - -- `capture`, `recall`, and `conventions` skill logic (later stories). -- Stripping the `wbs-` prefixes from gilbreth (story #5 — rescoped to include it; note the `references` "can't be prefixed" caveat dissolves under v1.4.0). -- Embeddings configuration (recall story handles degraded mode). -- An `open → resolved` note workflow (possible v2). - -## Assumptions - -- Tusk **v1.4.0+** (required for the configurable `wikilinks = true` materialization flag). Confirmed installed on the dev machine. -- The built-in `tags` pack provides `tag` nodes + a `tagged` edge. -- MCP-preferred / CLI-fallback access. - -## Open questions - -- Exact home of the shared availability-check procedure (own `references/` doc vs. inlined in `conventions`) — resolved at plan time. -- Whether `/bootstrap` should also offer to configure `[embeddings]` — leaning no for this story (keep it about the pack); recall story revisits. diff --git a/wbs/gilbreth-wbs/elephant/knowledge-pack.md b/wbs/gilbreth-wbs/elephant/knowledge-pack.md deleted file mode 100644 index 4ce927b..0000000 --- a/wbs/gilbreth-wbs/elephant/knowledge-pack.md +++ /dev/null @@ -1,60 +0,0 @@ ---- -type: wbs-node -title: Knowledge pack + /bootstrap + availability check -order: 0 -level: story -status: completed ---- - -# Knowledge pack + /bootstrap + availability check - -## Outcome - -The foundation the other stories build on: a generic `knowledge` Tusk pack declaring an unprefixed canonical `note` type (with a `kind` enum) plus `references` and `supersedes` edges, a `/bootstrap` command that installs it alongside the built-in `tags` pack, and the shared availability-check routine `capture`/`recall` gate on. Also scaffolds the `elephant` plugin and registers it in the marketplace. - -## Success Criteria - -- `packs/knowledge.toml` declares `note` (`kind` enum: learning|decision|open-thread|checkpoint, `archived` bool), `references`, `supersedes`; `tusk doctor` stays clean alongside `tags` (and the WBS pack). -- `/bootstrap` installs `tags` + the knowledge pack idempotently (`--force`-safe; runs `tusk init` if needed). -- The availability check reports present/absent and drives offer-once-then-dormant. -- The `elephant` plugin loads and is registered in the marketplace (via the two-scope PR onboarding). - -## Assumptions Made - -- Tusk v1.4.0+ (configurable `wikilinks = true` materialization); MCP-preferred / CLI-fallback access. -- Cross-plugin convention: declare canonical unprefixed types, use built-in packs as a seed, rely on `--force` for identical-type coexistence. -- The built-in `tags` pack provides `tag` nodes + a `tagged` edge (per the WBS composition matrix). - -## Open Questions - -- Home of the shared availability-check procedure (own `references/` doc vs. inlined in `conventions`) — resolved at plan time. -- Whether `/bootstrap` also offers `[embeddings]` config — leaning no; recall story revisits. - -## Tradeoffs Considered - -- One `note` type + `kind` enum vs. separate types per kind: chose one type (recall's "all knowledge on topic X" is the load-bearing query; consistent with the single-type-many-kinds precedent). -- Topics as `tags` (built-in pack) vs. custom anchor nodes: chose tags (reuse existing infra). -- v1 lifecycle-free (resolve = archive) vs. an open→resolved workflow: chose minimal v1 (YAGNI). -- Unprefixed canonical types vs. `wbs-`-style prefixes: chose unprefixed cross-plugin convention; accepts that built-in kanban/vault are seeds extended via `--force`, not avoided. - -## Out of Scope - -- capture / recall / conventions skill logic (later stories). -- Stripping `wbs-` prefixes from gilbreth (story #5, rescoped). -- Embeddings configuration; an open→resolved note workflow (possible v2). - -## Spec note - -[[wbs/gilbreth-wbs/elephant/knowledge-pack-spec]] - -## Plan note - -[[wbs/gilbreth-wbs/elephant/knowledge-pack-plan]] - -## Phasing - -No phases needed. - -## Tasks - -To be decomposed after planning. diff --git a/wbs/gilbreth-wbs/elephant/recall-skill-plan.md b/wbs/gilbreth-wbs/elephant/recall-skill-plan.md deleted file mode 100644 index 3f8fbb4..0000000 --- a/wbs/gilbreth-wbs/elephant/recall-skill-plan.md +++ /dev/null @@ -1,134 +0,0 @@ ---- -type: wbs-note -title: Plan — recall skill -kind: plan -wbs-about: wbs/gilbreth-wbs/elephant/recall-skill -archived: false ---- - -# recall skill — Implementation Plan - -> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development. Steps use checkbox (`- [ ]`) syntax. -> -> **WBS note:** Plan for story `wbs/gilbreth-wbs/elephant/recall-skill`. Spec: [[wbs/gilbreth-wbs/elephant/recall-skill-spec]]. - -**Goal:** Ship `elephant:recall` — an auto-invoking (need-driven) AND explicitly-invocable skill that pulls a narrow, windowed slice of the knowledge graph into context when the agent needs it. - -**Architecture:** A single `plugins/elephant/skills/recall/SKILL.md` (rigid retrieval procedure that reads the flexible `conventions` rulebook, gates on the availability check). One `feat(elephant)` PR; no catalog/release-please changes (`elephant` already registered). `conventions` + `capture` are on `main`. - -**Tech Stack:** Claude Code skill markdown. "Tests" are content-validation commands (`grep`, frontmatter check) + a manual smoke. - ---- - -## File structure - -PR (`feat(elephant)`): -- Create `plugins/elephant/skills/recall/SKILL.md` — the recall skill -- Modify `plugins/elephant/README.md` — move `recall` from "coming later" to a shipped skill (completes the skill trio) - ---- - -## Task 1: Write the recall SKILL - -**Files:** -- Create: `plugins/elephant/skills/recall/SKILL.md` - -Read first for grounding: `plugins/elephant/skills/conventions/SKILL.md` (rules — link, don't restate), `plugins/elephant/skills/capture/SKILL.md` (match its tone + structure; recall is its read-side mirror), `plugins/elephant/references/availability-check.md` (the gate), `plugins/elephant/packs/knowledge.toml` (vocabulary). Match the imperative, skimmable tone. - -- [ ] **Step 1: Write `SKILL.md` frontmatter exactly** - -```markdown ---- -name: recall -description: Use whenever you need context or background to proceed — regardless of whether the user asked — to pull the relevant slice of prior knowledge from the Tusk knowledge graph into the window. Fires when starting a substantive piece of work, switching to a new topic, or hitting a question prior sessions may have answered. Pulls a narrow, windowed slice (not the whole graph). Also invocable by name ("what do we know about X?"). ---- -``` - -- [ ] **Step 2: Write the body — intro + behavior + procedure** - -Skimmable prose. Cover: - -- **One-line intro:** recall is the read side of Tusk-as-memory and the windowed mirror of `capture` (link it); it applies the `conventions` rulebook (link `../conventions/SKILL.md`) and gates on `../../references/availability-check.md` (link). Both auto-invoking (need-driven) and an explicit entry point. -- **`## When to recall`:** the need-driven trigger — recall when you need context to proceed, regardless of whether the user asked (starting work, context switch, a question prior sessions may have captured). NOT a per-turn reflex (that floods context and defeats windowed memory). A once-per-slice guard: don't re-pull a slice already recalled this session. -- **`## Procedure`** (numbered, rigid): - 1. **Gate.** Availability check ([`references/availability-check.md`](../../references/availability-check.md)): absent → offer `/bootstrap` once then dormant; present → continue. - 2. **Frame the need.** Derive the topic/query from what you're about to do (or the explicit request). - 3. **Once-per-slice guard.** If already recalled this slice this session, skip. - 4. **Structural query** via MCP `tusk_query` — `tagged:<topic>`, recent `checkpoint`s, `references`-linked notes; exclude `archived`. - 5. **Semantic query** when `[embeddings]` is configured (`tusk_query … --semantic '<need>'` / MCP `semantic`); else emit a one-time degraded hint and skip this step. Never block on its absence. - 6. **Merge + window.** Union, de-dupe, exclude `archived`, cap at a small N — a slice, not the graph. - 7. **Surface + use.** Announce a terse summary (e.g. `🧠 recalled 3 notes on <topic>: …`), then proceed using the recalled notes. If nothing matched, say so briefly and proceed — never fabricate. -- **`## Degraded mode`:** one sentence — without `[embeddings]`, structural recall still runs; the semantic step is skipped with a one-time hint (mirrors the wbs-orientation degraded-mode discipline). - -Do NOT restate the `conventions` rules or the availability-check procedure — link them. - -- [ ] **Step 3: Verify frontmatter + structure** - -```bash -head -5 plugins/elephant/skills/recall/SKILL.md # name: recall + description (need-driven + named entry) -grep -iE 'conventions|availability-check|capture' plugins/elephant/skills/recall/SKILL.md # links peers -grep -iE 'tusk_query|semantic|tagged|archived' plugins/elephant/skills/recall/SKILL.md # query mechanics -``` -Expected: frontmatter present; links `conventions`/`availability-check`/`capture`; names the structural+semantic query mechanics, archived exclusion. - -- [ ] **Step 4: Verify WBS-agnostic + no rule duplication** - -```bash -grep -iE 'wbs|karpathy|milestone|initiative|level=' plugins/elephant/skills/recall/SKILL.md && echo "LEAK" || echo "clean: no WBS vocabulary" -``` -Expected: `clean: no WBS vocabulary`. Also eyeball that it links to `conventions` rather than re-listing modeling rules. - -- [ ] **Step 5: Commit** - -```bash -git add plugins/elephant/skills/recall/SKILL.md -git commit -m "feat(elephant): add recall skill" -``` - ---- - -## Task 2: Update the plugin README - -**Files:** -- Modify: `plugins/elephant/README.md` - -- [ ] **Step 1: List `recall` as shipped (completes the trio)** - -In `### Skills`, list all three as shipped and remove the "coming later" line: -```markdown -### Skills -- `conventions` — auto-invoking graph-hygiene rulebook for the knowledge pack. -- `capture` — proactively writes note-worthy work into the graph; auto-invoking and invocable by name. -- `recall` — pulls the relevant windowed slice of prior knowledge into context when needed; auto-invoking and invocable by name. -``` - -- [ ] **Step 2: Commit** - -```bash -git add plugins/elephant/README.md -git commit -m "docs(elephant): list recall skill in README" -``` - ---- - -## Task 3: Open the PR (controller) - -- [ ] **Step 1: Push + open** - -```bash -git push -u origin feat/elephant-recall -gh pr create --title "feat(elephant): add recall skill" --body "<summary + link to story>" -``` -Expected: `lint-commits` + `lint-pr-title` pass (`elephant` scope already on `main`). - ---- - -## Post-merge - -Flip the story to `completed` on this PR's branch (single-PR story). release-please opens an `elephant` release PR. With this story done, only story #5 (gilbreth refactor) remains in the initiative. - -## Out of scope (later story) - -- gilbreth's defer-to-elephant refactor + prefix removal (story 5). -- Restating `conventions` rules or the availability-check procedure (link them). -- `[embeddings]` configuration — recall only degrades gracefully without it. diff --git a/wbs/gilbreth-wbs/elephant/recall-skill-spec.md b/wbs/gilbreth-wbs/elephant/recall-skill-spec.md deleted file mode 100644 index d060338..0000000 --- a/wbs/gilbreth-wbs/elephant/recall-skill-spec.md +++ /dev/null @@ -1,78 +0,0 @@ ---- -type: wbs-note -title: Spec — recall skill -archived: false -kind: spec -wbs-about: wbs/gilbreth-wbs/elephant/recall-skill ---- - -# Spec — recall skill - -**wbs-note frontmatter:** `kind=spec` (linked to `wbs/gilbreth-wbs/elephant/recall-skill` by a `wbs-about` edge) - -## Goal - -Ship `elephant:recall` — the read side of Tusk-as-memory and the windowed counterpart to broad `capture`. Whenever the agent needs context to proceed, recall pulls only the *relevant slice* of the knowledge graph into the window (never the whole graph), so prior-session knowledge transfers seamlessly without flooding the context. - -## Architecture - -A `plugins/elephant/skills/recall/SKILL.md`. **Both** auto-invoking (the agent recognizes an information need and recalls) **and** an explicit named entry point (`elephant:recall` — "what do we know about X?"). A rigid retrieval procedure that reads the flexible `conventions` rulebook and gates on the availability check. - -### Trigger: need-driven - -Auto-invokes whenever the agent **needs to gather context/information to proceed — regardless of whether the user asked for it.** The agent recognizes its own information need and decides to recall. Common cases: starting a substantive piece of work, a context switch to a new topic the graph might know about, or hitting a question whose answer prior sessions may have captured. - -It is NOT a per-turn reflex — firing every message would flood context and defeat windowed memory. A **once-per-slice guard** prevents re-pulling the same slice within a session. - -### Windowing: how "narrow" is enforced - -- **Structural (always):** notes `tagged` with the topic; recent `checkpoint`s; notes linked via `references` to what's in play. -- **Semantic (when `[embeddings]` is configured):** top-K by similarity to the topic/need. -- De-duplicate the union, exclude `archived`, and cap at a small N — a slice, not the graph. -- **Degraded mode:** no `[embeddings]` → structural-only + a one-time degraded hint (the established wbs-orientation pattern). Never block on the absence of the semantic layer. - -### Surfacing: announced + terse - -Surface a brief summary of what was pulled (e.g. `🧠 recalled 3 notes on <topic>: …`) so the user sees the basis, then proceed using them. Consistent with `capture`'s announced behavior. - -## Components - -`skills/recall/SKILL.md` procedure: - -1. **Gate.** Availability check (`references/availability-check.md`): absent graph → offer `/bootstrap` once then dormant; present → continue. -2. **Frame the need.** Derive the topic/query from what the agent is about to do (or the explicit request). -3. **Once-per-slice guard.** If this slice was already recalled this session, skip (don't re-pull). -4. **Structural query** via MCP (`tusk_query` by `tagged:<topic>`, recent `checkpoint`s, `references`-linked notes); exclude `archived`. -5. **Semantic query** when embeddings available (`tusk_query … --semantic '<need>'`); else emit the one-time degraded hint and skip. -6. **Merge + window.** Union, de-dupe, exclude archived, cap at small N. -7. **Surface** the terse summary; use the recalled notes as context. - -## Data flow - -1. Agent needs context (auto) or is asked to recall (explicit) → gate → frame need → guard → structural + (semantic) query → window → surface → proceed. -2. Pairs with `capture`: capture writes well-modeled notes; recall reads them back narrowly. Capture's lightweight dedup check and recall share the same query shape but recall is the full retrieval. - -## Error handling - -- No graph: offer-bootstrap-once then dormant. -- No `[embeddings]`: structural-only + one-time hint; never block. -- MCP write-lock contention / unreachable: prefer MCP, CLI-fallback. -- Empty result: say so briefly (nothing recalled) and proceed; don't fabricate. - -## Verification - -- `skills/recall/SKILL.md` exists with valid frontmatter; `description` triggers on a need-for-context (auto) AND it is invocable by name. -- Manual smoke (knowledge-pack workspace with notes): starting work on a known topic surfaces the relevant slice (tagged/linked/semantic), de-duped and capped, with a terse summary; re-triggering the same slice in-session does not re-pull. -- Degraded mode: with no `[embeddings]`, structural recall still runs and the one-time hint fires once. -- Links to `conventions` and `availability-check` rather than restating them; no WBS vocabulary. - -## Out of scope - -- `capture` (story 3) — recall is read-only; it does not write notes. -- gilbreth's defer-to-elephant refactor (story 5). -- The `conventions` rules and the availability-check procedure (link them). -- Configuring `[embeddings]` (knowledge-pack/bootstrap concern); recall only degrades gracefully. - -## Open questions - -- None. Trigger (need-driven, agent-decided, once-per-slice guard, + named entry), windowing (structural + optional semantic, capped, archived-excluded), and surfacing (announced + terse) are resolved. diff --git a/wbs/gilbreth-wbs/elephant/recall-skill.md b/wbs/gilbreth-wbs/elephant/recall-skill.md deleted file mode 100644 index 16933ff..0000000 --- a/wbs/gilbreth-wbs/elephant/recall-skill.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -type: wbs-node -title: recall skill -order: 3 -level: story -status: completed ---- - -# recall skill - -## Outcome - -`elephant:recall` — the read side of Tusk-as-memory and the windowed counterpart to broad capture. Whenever the agent needs context to proceed (regardless of whether the user asked), it pulls only the relevant slice of the knowledge graph into the window — never the whole graph. Both auto-invoking (agent-decided, need-driven) and an explicit named entry point. - -## Success Criteria - -- `plugins/elephant/skills/recall/SKILL.md` auto-invokes when the agent needs context AND is invocable by name. -- Surfaces a narrow, de-duplicated, archived-excluded, capped slice — not the whole graph; announced with a terse summary. -- Structural recall always runs; semantic runs when `[embeddings]` is configured, with a one-time degraded hint otherwise. -- A once-per-slice guard prevents re-pulling the same slice in a session. -- Gates on availability check; reads `conventions`; links (not restates) both. - -## Assumptions Made - -- conventions (story 2) and the knowledge pack (story 1) are shipped and define what's queryable. - -## Open Questions - -none — trigger (need-driven, agent-decided, once-per-slice guard, + named entry), windowing (structural + optional semantic, capped, archived-excluded), and surfacing (announced + terse) are resolved. - -## Tradeoffs Considered - -- Need-driven trigger (chosen) vs. per-turn vs. explicit-only: per-turn floods context; explicit-only loses proactive cross-session memory. Need-driven (agent recognizes an information need) with a once-per-slice guard balances both. -- Structural-first windowing with optional semantic + small cap (chosen) — enforces "slice, not graph." - -## Out of Scope - -- capture (story 3); gilbreth defer-to-elephant (story 5); the conventions rules + availability-check procedure (link them); `[embeddings]` configuration. - -## Spec note - -[[wbs/gilbreth-wbs/elephant/recall-skill-spec]] - -## Plan note - -[[wbs/gilbreth-wbs/elephant/recall-skill-plan]] - -## Phasing - -No phases needed. - -## Tasks - -To be decomposed after planning. diff --git a/wbs/gilbreth-wbs/elephant/spec.md b/wbs/gilbreth-wbs/elephant/spec.md deleted file mode 100644 index ce8b6ea..0000000 --- a/wbs/gilbreth-wbs/elephant/spec.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -type: wbs-note -title: Spec — Elephant plugin -archived: false -kind: spec -wbs-about: wbs/gilbreth-wbs/elephant ---- - -# Spec — Elephant plugin - -**wbs-note frontmatter:** `kind=spec` (linked to `wbs/gilbreth-wbs/elephant` by a `wbs-about` edge) - -## Goal - -Make Tusk the agent's short-to-medium-term memory keeper. Elephant is a standalone, WBS-agnostic plugin whose skills fire on the work itself: they capture learnings broadly into a knowledge graph and recall them narrowly so a future session resumes with just-enough context. It generalizes the Tusk discipline currently encoded inline in the gilbreth WBS spine, and gilbreth is refactored to defer to it. - -## Architecture - -Three auto-invoking skills over a shared availability check, backed by a generic Tusk pack: - -| Artifact | Type | Role | -|---|---|---| -| `skills/conventions/` | reference skill | Graph-hygiene rulebook: model knowledge as nodes/edges, create-vs-append-vs-supersede, naming, `[[wikilink]]` discoverability, archive semantics. WBS-agnostic sibling of gilbreth's `conventions.md`. Read by `capture` and `recall`. | -| `skills/capture/` | rigid skill | Auto-invokes on note-worthy work (learnings, decisions, open threads, boundary checkpoints). Writes small, well-linked notes. Broad capture. | -| `skills/recall/` | rigid skill | Auto-invokes at start-of-work / context switch. Query-first (structural + semantic) retrieval of the relevant slice only. Windowed. | -| `packs/knowledge.toml` | Tusk pack | Generic knowledge node/edge types, independent of WBS; composes with the `wbs` pack. The graph non-WBS workflows write into. | -| `commands/bootstrap.md` | command | One-time init: add the `knowledge` pack to a workspace's Tusk. Invoked by the offer-to-bootstrap-once path. | -| `templates/` | templates | Note templates per kind (learning / decision / checkpoint / open-thread). | - -## Components - -- **Shared availability check.** Both `capture` and `recall` probe for a Tusk graph + `knowledge` pack. Absent → offer `/bootstrap` once per session; declined → dormant for the session; present → operate silently. Mirrors wbs-orientation's pack-presence check and once-per-session degraded-mode hint discipline. -- **conventions** is the single source of modeling truth; capture/recall reference it rather than re-encoding rules. Flexible (principles adapted to context). -- **capture** decides node-vs-append, writes a small note, links it with `[[wikilinks]]`/edges so indexation makes it discoverable. Rigid procedure. -- **recall** runs structural + semantic queries, de-dupes, and surfaces a narrow set; semantic layer degrades gracefully without `[embeddings]`. Rigid procedure. -- **knowledge pack** declares the node/edge types (exact shape resolved in the knowledge-pack story); composes with `wbs` (shares the `references` wikilink edge, `wbs-`-prefix keeps WBS edges distinct). - -## Data flow - -1. Agent does work → hits a note-worthy moment → `capture` auto-invokes → availability check → write note + links into graph. -2. Agent starts work / switches context → `recall` auto-invokes → availability check → query graph (structural + semantic) → surface narrow relevant slice into the window. -3. No graph present → first such moment offers `/bootstrap`; thereafter dormant if declined. - -## Error handling - -- No Tusk graph / pack: offer-bootstrap-once, then dormant (no nagging). -- MCP unreachable: CLI fallback (same dual-path pattern as wbs-orientation). -- No `[embeddings]`: semantic recall skipped, structural recall still runs, one-time degraded hint. -- Write-lock contention (MCP server holds the lock): prefer MCP tools over CLI. - -## Verification - -- Plugin registered in marketplace + release-please (two PRs: `feat(elephant)` scaffold, `feat(marketplace)` register) per CONTRIBUTING. -- Manual: in a Tusk workspace, note-worthy work triggers capture; a fresh session's recall surfaces it. In a non-Tusk workspace, first note-worthy moment offers bootstrap once. -- gilbreth refactor: `conventions.md`/`wbs-orientation` reference `elephant:conventions`; WBS flows still pass their gates. - -## Out of scope - -- Researcher (#6), Engineering conventions (#5). -- WBS-specific concerns (levels, Karpathy gate, phasing) — stay in gilbreth. -- A human-facing query UI. - -## Per-story design - -Each of the five stories gets its own focused brainstorm → spec → plan → implement session. Open design questions (exact knowledge-pack node/edge model; whether capture/recall are also named entry points for subagents) are resolved at the relevant story's brainstorm, not here.