@kentwynn/kgraph 0.2.17 → 0.2.18

package/dist/integrations/adapters/codex.js

@@ -1,4 +1,4 @@
-import { numberedWorkflow } from '../workflow-steps.js';
+import { agentSkillFiles } from '../agent-skills.js';
 export const codexAdapter = {
     name: 'codex',
     label: 'Codex',
@@ -7,24 +7,6 @@ export const codexAdapter = {
 
 {{KGRAPH_CONTEXT_POLICY}} The /kgraph skill handles the full automated workflow. Run \`kgraph pack "<task>" --budget 8000 --json\` for a machine-readable token-budgeted context pack, \`kgraph knowledge list\` or \`kgraph knowledge get <atom-id>\` to inspect durable atoms, \`kgraph stale\` and \`kgraph blame <atom-id>\` when lifecycle/provenance matters, \`kgraph conclude\` for durable typed engineering memory, and \`kgraph compact --dry-run\` when cognition looks duplicated or stale. Run \`kgraph doctor\` when setup or generated maps look wrong. Run \`kgraph scan\`, \`kgraph update\`, and \`kgraph context\` manually only when you need one specific step.
 `,
-    commandFiles: [
-        {
-            path: '.agents/skills/kgraph/SKILL.md',
-            content: `---
-name: kgraph
-description: Use KGraph persistent repo intelligence according to the configured integration mode. Use when asked about repo structure, debugging context, architecture decisions, or to avoid rediscovering what is already known.
----
-
-# KGraph Skill
-
-Workflow:
-
-${numberedWorkflow('codex')}
-`,
-        },
-    ],
-    obsoleteCommandFiles: [
-        '.agents/skills/kgraph-scan/SKILL.md',
-        '.agents/skills/kgraph-update/SKILL.md',
-    ],
+    commandFiles: agentSkillFiles('codex'),
+    obsoleteCommandFiles: [],
 };

package/dist/integrations/adapters/copilot.js

@@ -1,3 +1,4 @@
+import { agentSkillFiles } from '../agent-skills.js';
 import { numberedWorkflow } from '../workflow-steps.js';
 export const copilotAdapter = {
     name: 'copilot',
@@ -7,172 +8,6 @@ export const copilotAdapter = {
 
 ${numberedWorkflow('copilot')}
 `,
-    commandFiles: [
-        {
-            path: '.github/prompts/kgraph-doctor.prompt.md',
-            content: `---
-description: Check KGraph workspace health and next actions
-agent: agent
----
-
-Run \`kgraph doctor\` to check whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Use \`kgraph doctor --quality\` when the user asks about stale or noisy cognition references. Summarize any failed checks and the next command to run.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-repair.prompt.md',
-            content: `---
-description: Preview or clean stale/noisy KGraph cognition references
-agent: agent
-argument-hint: "--dry-run or apply"
----
-
-Run \`kgraph repair --dry-run\` first and summarize the proposed atom-reference cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-compact.prompt.md',
-            content: `---
-description: Merge duplicate KGraph cognition and archive stale low-value entries
-agent: agent
-argument-hint: "--dry-run or apply"
----
-
-Run \`kgraph compact --dry-run\` first and summarize duplicate cognition groups and stale low-confidence notes. Run \`kgraph compact\` only when the user asks to apply compaction.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-pack.prompt.md',
-            content: `---
-description: Build a budget-aware KGraph context pack
-agent: agent
-argument-hint: "Task description"
----
-
-Run \`kgraph pack "$ARGUMENTS" --budget 8000 --json\` to build a machine-readable context pack. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-knowledge.prompt.md',
-            content: `---
-description: Inspect or manage KGraph canonical knowledge atoms
-agent: agent
-argument-hint: "list, get <atom-id>, archive <atom-id>, or supersede <old-id> <new-id>"
----
-
-Use \`kgraph knowledge list\` and \`kgraph knowledge get <atom-id>\` to inspect durable atoms, evidence, provenance, and lifecycle. Run \`kgraph knowledge archive <atom-id>\` or \`kgraph knowledge supersede <old-id> <new-id>\` only when the user explicitly asks to mutate atom lifecycle.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-stale.prompt.md',
-            content: `---
-description: Show KGraph knowledge invalidated by changed or missing refs
-agent: agent
----
-
-Run \`kgraph stale\` to refresh atom status against the current scan and summarize stale or needs-review atoms with invalidation reasons.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-blame.prompt.md',
-            content: `---
-description: Show KGraph atom provenance and evidence
-agent: agent
-argument-hint: "Atom id"
----
-
-Run \`kgraph blame "$ARGUMENTS"\` to show who or what created a knowledge atom, the source command/session/commit, evidence refs, and lifecycle links.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-scan.prompt.md',
-            content: `---
-description: Refresh KGraph file, symbol, import, and relationship maps
-agent: agent
----
-
-Run \`kgraph scan\` to refresh the repository maps, then summarize what changed.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-update.prompt.md',
-            content: `---
-description: Process KGraph inbox notes into durable cognition
-agent: agent
----
-
-Run \`kgraph update\` to process any pending Markdown notes in \`.kgraph/inbox/\` into durable cognition.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-visualize.prompt.md',
-            content: `---
-description: Open interactive KGraph dependency graph in browser
-agent: agent
----
-
-Run \`kgraph visualize\` to start the interactive dependency graph at http://localhost:4242, then summarize what nodes and connections are visible.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-capture.prompt.md',
-            content: `---
-description: Save what was just built or changed into KGraph cognition
-agent: agent
-argument-hint: "Brief description of what was done"
----
-
-Capture this session into KGraph cognition.
-
-{{KGRAPH_CAPTURE_POLICY}}
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-conclude.prompt.md',
-            content: `---
-description: Store a typed durable KGraph engineering conclusion
-agent: agent
-argument-hint: "Topic plus optional type, confidence, files, and symbols"
----
-
-Use \`kgraph conclude "$ARGUMENTS"\` when the session produced reusable engineering knowledge. Choose one type from finding, decision, gotcha, summary, relationship, and one confidence from high, medium, low. Store only durable conclusions, not raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-impact.prompt.md',
-            content: `---
-description: Show KGraph change impact for a file, symbol, or topic
-agent: agent
-argument-hint: "File, symbol, or topic"
----
-
-Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related knowledge atoms, and risk hints.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-session.prompt.md',
-            content: `---
-description: Track KGraph session read/write activity and token estimates
-agent: agent
-argument-hint: "start, read <path>, write <path>, end, or status"
----
-
-Use \`kgraph session\` to inspect current session activity. Record meaningful events with \`kgraph session start --agent copilot\`, \`kgraph session read <path> --agent copilot\`, \`kgraph session write <path> --agent copilot\`, and \`kgraph session end --agent copilot --conclude --topic "<topic>"\` when durable session memory is useful.
-`,
-        },
-        {
-            path: '.github/prompts/kgraph-history.prompt.md',
-            content: `---
-description: Show timeline of KGraph cognition sessions with git attribution
-agent: agent
-argument-hint: "Optional topic"
----
-
-Run \`kgraph history\` or \`kgraph history "$ARGUMENTS"\` to display processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
-`,
-        },
-    ],
-    obsoleteCommandFiles: [
-        '.github/prompts/kgraph.prompt.md',
-        '.github/kgraph.agent.md',
-    ],
+    commandFiles: agentSkillFiles('copilot'),
+    obsoleteCommandFiles: [],
 };

package/dist/integrations/agent-skills.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared agent skill definitions used by any integration that writes
+ * `.agents/skills/` SKILL.md files (copilot, codex, etc.).
+ *
+ * Per-command skills are agent-name-agnostic.
+ * The main kgraph workflow skill is parameterised by agent name.
+ */
+import type { IntegrationCommandFile } from './integration-registry.js';
+/** Per-command skills shared across all agent-skill integrations. */
+export declare const SHARED_AGENT_SKILLS: IntegrationCommandFile[];
+/**
+ * Build the full agent skill list for an adapter: the main workflow skill
+ * (parameterised by agent name) plus all shared per-command skills.
+ */
+export declare function agentSkillFiles(agentName: string): IntegrationCommandFile[];

package/dist/integrations/agent-skills.js

@@ -0,0 +1,186 @@
+/**
+ * Shared agent skill definitions used by any integration that writes
+ * `.agents/skills/` SKILL.md files (copilot, codex, etc.).
+ *
+ * Per-command skills are agent-name-agnostic.
+ * The main kgraph workflow skill is parameterised by agent name.
+ */
+import { numberedWorkflow } from './workflow-steps.js';
+/** Per-command skills shared across all agent-skill integrations. */
+export const SHARED_AGENT_SKILLS = [
+    {
+        path: '.agents/skills/kgraph-doctor/SKILL.md',
+        content: `---
+name: kgraph-doctor
+description: Check KGraph workspace health and next actions
+---
+
+Run \`kgraph doctor\` to check whether the workspace is initialized, maps exist, inbox notes are pending, and configured integrations point to real files. Use \`kgraph doctor --quality\` when the user asks about stale or noisy cognition references. Summarize any failed checks and the next command to run.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-repair/SKILL.md',
+        content: `---
+name: kgraph-repair
+description: Preview or clean stale/noisy KGraph cognition references
+---
+
+Run \`kgraph repair --dry-run\` first and summarize the proposed atom-reference cleanup. Run \`kgraph repair\` only when the user asks to apply the cleanup.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-compact/SKILL.md',
+        content: `---
+name: kgraph-compact
+description: Merge duplicate KGraph cognition and archive stale low-value entries
+---
+
+Run \`kgraph compact --dry-run\` first and summarize duplicate cognition groups and stale low-confidence notes. Run \`kgraph compact\` only when the user asks to apply compaction.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-pack/SKILL.md',
+        content: `---
+name: kgraph-pack
+description: Build a budget-aware KGraph context pack
+---
+
+Run \`kgraph pack "$ARGUMENTS" --budget 8000 --json\` to build a machine-readable context pack. Summarize token use, included files, symbols, relationships, git changes, session history, atoms, and omitted items with the inclusion reasons.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-knowledge/SKILL.md',
+        content: `---
+name: kgraph-knowledge
+description: Inspect or manage KGraph canonical knowledge atoms
+---
+
+Use \`kgraph knowledge list\` and \`kgraph knowledge get <atom-id>\` to inspect durable atoms, evidence, provenance, and lifecycle. Run \`kgraph knowledge archive <atom-id>\` or \`kgraph knowledge supersede <old-id> <new-id>\` only when the user explicitly asks to mutate atom lifecycle.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-stale/SKILL.md',
+        content: `---
+name: kgraph-stale
+description: Show KGraph knowledge invalidated by changed or missing refs
+---
+
+Run \`kgraph stale\` to refresh atom status against the current scan and summarize stale or needs-review atoms with invalidation reasons.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-blame/SKILL.md',
+        content: `---
+name: kgraph-blame
+description: Show KGraph atom provenance and evidence
+---
+
+Run \`kgraph blame "$ARGUMENTS"\` to show who or what created a knowledge atom, the source command/session/commit, evidence refs, and lifecycle links.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-scan/SKILL.md',
+        content: `---
+name: kgraph-scan
+description: Refresh KGraph file, symbol, import, and relationship maps
+---
+
+Run \`kgraph scan\` to refresh the repository maps, then summarize what changed.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-update/SKILL.md',
+        content: `---
+name: kgraph-update
+description: Process KGraph inbox notes into durable cognition
+---
+
+Run \`kgraph update\` to process any pending Markdown notes in \`.kgraph/inbox/\` into durable cognition.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-visualize/SKILL.md',
+        content: `---
+name: kgraph-visualize
+description: Open interactive KGraph dependency graph in browser
+---
+
+Run \`kgraph visualize\` to start the interactive dependency graph at http://localhost:4242, then summarize what nodes and connections are visible.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-capture/SKILL.md',
+        content: `---
+name: kgraph-capture
+description: Save what was just built or changed into KGraph cognition
+---
+
+Capture this session into KGraph cognition.
+
+{{KGRAPH_CAPTURE_POLICY}}
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-conclude/SKILL.md',
+        content: `---
+name: kgraph-conclude
+description: Store a typed durable KGraph engineering conclusion
+---
+
+Use \`kgraph conclude "$ARGUMENTS"\` when the session produced reusable engineering knowledge. Choose one type from finding, decision, gotcha, summary, relationship, and one confidence from high, medium, low. Store only durable conclusions, not raw chain-of-thought, temporary reasoning, speculative exploration, or low-value observations.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-impact/SKILL.md',
+        content: `---
+name: kgraph-impact
+description: Show KGraph change impact for a file, symbol, or topic
+---
+
+Run \`kgraph impact "$ARGUMENTS"\` to show matched files/symbols, import users, callers, callees, related knowledge atoms, and risk hints.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-session/SKILL.md',
+        content: `---
+name: kgraph-session
+description: Track KGraph session read/write activity and token estimates
+---
+
+Use \`kgraph session\` to inspect current session activity. Record meaningful events with \`kgraph session start --agent $AGENT\`, \`kgraph session read <path> --agent $AGENT\`, \`kgraph session write <path> --agent $AGENT\`, and \`kgraph session end --agent $AGENT --conclude --topic "<topic>"\` when durable session memory is useful.
+`,
+    },
+    {
+        path: '.agents/skills/kgraph-history/SKILL.md',
+        content: `---
+name: kgraph-history
+description: Show timeline of KGraph cognition sessions with git attribution
+---
+
+Run \`kgraph history\` or \`kgraph history "$ARGUMENTS"\` to display processed cognition sessions. Summarize who contributed what and when. Use \`--last <n>\` to limit entries.
+`,
+    },
+];
+/**
+ * Build the full agent skill list for an adapter: the main workflow skill
+ * (parameterised by agent name) plus all shared per-command skills.
+ */
+export function agentSkillFiles(agentName) {
+    return [
+        {
+            path: '.agents/skills/kgraph/SKILL.md',
+            content: `---
+name: kgraph
+description: Use KGraph persistent repo intelligence according to the configured integration mode. Use when asked about repo structure, debugging context, architecture decisions, or to avoid rediscovering what is already known.
+---
+
+# KGraph Skill
+
+Workflow:
+
+${numberedWorkflow(agentName)}
+`,
+        },
+        ...SHARED_AGENT_SKILLS,
+    ];
+}

package/dist/integrations/integration-store.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { mkdir, readdir, readFile, rm, rmdir, writeFile, } from 'node:fs/promises';
 import path from 'node:path';
 import { loadConfig, saveConfig } from '../config/config.js';
 import { pathExists } from '../storage/kgraph-paths.js';
@@ -19,6 +19,7 @@ export async function addIntegrations(workspace, names, mode = 'always') {
     const config = await loadConfig(workspace);
     const byName = new Map(config.integrations.map((integration) => [integration.name, integration]));
     const changed = [];
+    const writtenCommandFiles = new Set();
     for (const name of names) {
         const adapter = getIntegrationAdapter(name);
         const next = {
@@ -34,10 +35,14 @@ export async function addIntegrations(workspace, names, mode = 'always') {
         }
         else {
             await writeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name, applyContextPolicy(adapter.instructions, mode));
-            await writeIntegrationCommandFiles(workspace.rootPath, (adapter.commandFiles ?? []).map((file) => ({
+            const deduped = (adapter.commandFiles ?? []).filter((file) => !writtenCommandFiles.has(file.path));
+            await writeIntegrationCommandFiles(workspace.rootPath, deduped.map((file) => ({
                 ...file,
                 content: applyContextPolicy(file.content, mode),
             })));
+            for (const file of adapter.commandFiles ?? []) {
+                writtenCommandFiles.add(file.path);
+            }
         }
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
         changed.push(next);
@@ -53,10 +58,21 @@ export async function removeIntegrations(workspace, names) {
     const config = await loadConfig(workspace);
     const removeNames = new Set(names);
     const removed = [];
+    // Collect command-file paths still owned by remaining enabled integrations
+    const retainedPaths = new Set();
+    for (const integration of config.integrations) {
+        if (removeNames.has(integration.name) || !integration.enabled) {
+            continue;
+        }
+        const adapter = getIntegrationAdapter(integration.name);
+        for (const file of adapter.commandFiles ?? []) {
+            retainedPaths.add(file.path);
+        }
+    }
     for (const name of removeNames) {
         const adapter = getIntegrationAdapter(name);
         await removeIntegrationInstructions(workspace.rootPath, adapter.targetPath, adapter.name);
-        await removeIntegrationCommandFiles(workspace.rootPath, adapter.commandFiles ?? []);
+        await removeIntegrationCommandFiles(workspace.rootPath, (adapter.commandFiles ?? []).filter((file) => !retainedPaths.has(file.path)));
         await removeIntegrationCommandFiles(workspace.rootPath, adapter.obsoleteCommandFiles ?? []);
         removed.push(adapter.name);
     }
@@ -96,6 +112,21 @@ async function writeIntegrationCommandFiles(rootPath, files) {
 async function removeIntegrationCommandFiles(rootPath, files) {
     for (const file of files) {
         const filePath = typeof file === 'string' ? file : file.path;
-        await rm(path.join(rootPath, filePath), { force: true, recursive: true });
+        const fullPath = path.join(rootPath, filePath);
+        await rm(fullPath, { force: true, recursive: true });
+        // Remove empty parent directories up to (but not including) rootPath
+        let dir = path.dirname(fullPath);
+        while (dir !== rootPath && dir.startsWith(rootPath)) {
+            try {
+                const entries = await readdir(dir);
+                if (entries.length > 0)
+                    break;
+                await rmdir(dir);
+                dir = path.dirname(dir);
+            }
+            catch {
+                break;
+            }
+        }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.17",
+  "version": "0.2.18",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {