@kentwynn/kgraph 0.2.3 → 0.2.4

package/README.md

@@ -267,7 +267,7 @@ kgraph integrate list
 kgraph integrate remove cursor
 ```
 
-New integrations default to `always` mode because coding agents often under-classify small UI, route, button, and link changes as not needing repo context.
+New integrations default to `smart` mode. Use `--mode always` to force KGraph on every chat, or `--mode manual` to run only when explicitly asked.
 
 | Mode     | Behavior                                                                                                                                                                                                |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

package/dist/cli/commands/init.js

@@ -14,7 +14,7 @@ export function registerInitCommand(program) {
         .description('Initialize a .kgraph workspace')
         .option('--integration <name>', 'Configure an AI tool integration', collectOption, [])
         .option('--integrations <names>', 'Configure comma-separated AI tool integrations')
-        .option('--mode <mode>', 'Integration mode: always, smart, manual, or off', 'always')
+        .option('--mode <mode>', 'Integration mode: always, smart, manual, or off', 'smart')
         .action((options) => runCommand(async () => {
         const workspace = await ensureWorkspace(process.cwd());
         const wroteConfig = await writeDefaultConfig(workspace);
@@ -53,7 +53,7 @@ export function registerInitCommand(program) {
         })) {
             const selected = await promptForInitIntegrations(recommendedIntegrations);
             if (selected.length > 0) {
-                const changed = await addIntegrations(workspace, selected, 'always');
+                const changed = await addIntegrations(workspace, selected, 'smart');
                 console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
                 config = await loadConfig(workspace);
                 recommendedIntegrations = recommendedIntegrationsForInit({

package/dist/cli/commands/integrate.js

@@ -25,7 +25,7 @@ export function registerIntegrateCommand(program) {
         .command('add')
         .description('Add AI tool integrations')
         .argument('<names...>')
-        .option('--mode <mode>', 'always, smart, manual, or off', 'always')
+        .option('--mode <mode>', 'always, smart, manual, or off', 'smart')
         .action((names, options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);

package/dist/integrations/adapters/claude-code.js

@@ -1,3 +1,4 @@
+import { numberedWorkflow } from '../workflow-steps.js';
 export const claudeCodeAdapter = {
     name: 'claude-code',
     label: 'Claude Code',
@@ -11,18 +12,7 @@ export const claudeCodeAdapter = {
             path: '.claude/commands/kgraph.md',
             content: `Use KGraph persistent repo intelligence for the current request.
 
-1. Infer the topic from the user's request.
-2. {{KGRAPH_CONTEXT_POLICY}}
-3. Use the returned files, symbols, relationships, and cognition before broad exploration.
-4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-5. Track meaningful session activity with \`kgraph session start --agent claude-code\`, \`kgraph session read <path> --agent claude-code\`, \`kgraph session write <path> --agent claude-code\`, and \`kgraph session end --agent claude-code\` when native hooks are unavailable.
-6. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-
-{{KGRAPH_CAPTURE_POLICY}}
-
-7. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
-8. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-9. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
+${numberedWorkflow('claude-code', { sessionQualifier: 'when native hooks are unavailable' })}
 `,
         },
         {

package/dist/integrations/adapters/cline.js

@@ -1,16 +1,10 @@
+import { bulletWorkflow } from '../workflow-steps.js';
 export const clineAdapter = {
     name: 'cline',
     label: 'Cline',
     targetPath: '.clinerules/kgraph.md',
     instructions: `# KGraph Workflow
 
-- {{KGRAPH_CONTEXT_POLICY}}
-- Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-- Track meaningful session activity with \`kgraph session start --agent cline\`, \`kgraph session read <path> --agent cline\`, \`kgraph session write <path> --agent cline\`, and \`kgraph session end --agent cline\`.
-- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-{{KGRAPH_CAPTURE_POLICY}}
-- Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
-- Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
-- Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
+${bulletWorkflow('cline')}
 `,
 };

package/dist/integrations/adapters/codex.js

@@ -1,3 +1,4 @@
+import { numberedWorkflow } from '../workflow-steps.js';
 export const codexAdapter = {
     name: 'codex',
     label: 'Codex',
@@ -18,23 +19,12 @@ description: Use KGraph persistent repo intelligence according to the configured
 
 Workflow:
 
-1. Infer the current topic from the user request.
-2. {{KGRAPH_CONTEXT_POLICY}}
-3. Use KGraph's returned files, symbols, relationships, and cognition as navigation hints.
-4. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-5. Track meaningful session activity with \`kgraph session start --agent codex\`, \`kgraph session read <path> --agent codex\`, \`kgraph session write <path> --agent codex\`, and \`kgraph session end --agent codex\`.
-6. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-
-{{KGRAPH_CAPTURE_POLICY}}
-
-7. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
-8. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
-9. Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
+${numberedWorkflow('codex')}
 `,
         },
     ],
     obsoleteCommandFiles: [
-        '.agents/skills/kgraph-update',
-        '.agents/skills/kgraph-scan',
+        '.agents/skills/kgraph-scan/SKILL.md',
+        '.agents/skills/kgraph-update/SKILL.md',
     ],
 };

package/dist/integrations/adapters/copilot.js

@@ -1,19 +1,33 @@
+import { numberedWorkflow } from '../workflow-steps.js';
 export const copilotAdapter = {
     name: 'copilot',
     label: 'GitHub Copilot',
     targetPath: '.github/copilot-instructions.md',
     instructions: `## KGraph Workflow
 
-1. {{KGRAPH_CONTEXT_POLICY}}
-2. Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-3. Track meaningful session activity with \`kgraph session start --agent copilot\`, \`kgraph session read <path> --agent copilot\`, \`kgraph session write <path> --agent copilot\`, and \`kgraph session end --agent copilot\`.
-4. Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
+${numberedWorkflow('copilot')}
+`,
+    commandFiles: [
+        {
+            path: '.github/agents/kgraph.agent.md',
+            content: `---
+name: kgraph
+description: Use KGraph persistent repo intelligence to answer questions about this codebase. Runs kgraph context, scan, update, impact, history, and session commands to ground responses in durable local knowledge.
+tools:
+  - run_in_terminal
+  - read_file
+  - file_search
+  - grep_search
+  - semantic_search
+---
 
-{{KGRAPH_CAPTURE_POLICY}}
+## KGraph Agent
+
+You are a KGraph-powered agent. Before exploring the repository freely, always:
 
-5. Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
+${numberedWorkflow('copilot')}
 `,
-    commandFiles: [
+        },
         {
             path: '.github/prompts/kgraph-doctor.prompt.md',
             content: `---
@@ -112,5 +126,8 @@ Run \`kgraph history\` or \`kgraph history "$ARGUMENTS"\` to display processed c
 `,
         },
     ],
-    obsoleteCommandFiles: ['.github/prompts/kgraph.prompt.md'],
+    obsoleteCommandFiles: [
+        '.github/prompts/kgraph.prompt.md',
+        '.github/kgraph.agent.md',
+    ],
 };

package/dist/integrations/adapters/cursor.js

@@ -1,3 +1,4 @@
+import { bulletWorkflow } from '../workflow-steps.js';
 export const cursorAdapter = {
     name: 'cursor',
     label: 'Cursor',
@@ -9,14 +10,7 @@ alwaysApply: true
 
 ## KGraph Workflow
 
-- {{KGRAPH_CONTEXT_POLICY}}
-- Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-- Track meaningful session activity with \`kgraph session start --agent cursor\`, \`kgraph session read <path> --agent cursor\`, \`kgraph session write <path> --agent cursor\`, and \`kgraph session end --agent cursor\`.
-- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-{{KGRAPH_CAPTURE_POLICY}}
-- Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
-- Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
-- Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
+${bulletWorkflow('cursor')}
 `,
     obsoleteCommandFiles: ['.cursor/rules/kgraph-commands.mdc'],
 };

package/dist/integrations/adapters/gemini.js

@@ -1,16 +1,10 @@
+import { bulletWorkflow } from '../workflow-steps.js';
 export const geminiAdapter = {
     name: 'gemini',
     label: 'Gemini CLI',
     targetPath: 'GEMINI.md',
     instructions: `## KGraph Workflow
 
-- {{KGRAPH_CONTEXT_POLICY}}
-- Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-- Track meaningful session activity with \`kgraph session start --agent gemini\`, \`kgraph session read <path> --agent gemini\`, \`kgraph session write <path> --agent gemini\`, and \`kgraph session end --agent gemini\`.
-- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-{{KGRAPH_CAPTURE_POLICY}}
-- Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
-- Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
-- Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
+${bulletWorkflow('gemini')}
 `,
 };

package/dist/integrations/adapters/windsurf.js

@@ -1,16 +1,10 @@
+import { bulletWorkflow } from '../workflow-steps.js';
 export const windsurfAdapter = {
     name: 'windsurf',
     label: 'Windsurf',
     targetPath: '.windsurf/rules/kgraph.md',
     instructions: `# KGraph Workflow
 
-- {{KGRAPH_CONTEXT_POLICY}}
-- Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.
-- Track meaningful session activity with \`kgraph session start --agent windsurf\`, \`kgraph session read <path> --agent windsurf\`, \`kgraph session write <path> --agent windsurf\`, and \`kgraph session end --agent windsurf\`.
-- Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.
-{{KGRAPH_CAPTURE_POLICY}}
-- Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.
-- Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
-- Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.
+${bulletWorkflow('windsurf')}
 `,
 };

package/dist/integrations/integration-store.js

@@ -15,7 +15,7 @@ export async function listIntegrations(workspace) {
     })));
     return statuses.sort((left, right) => left.name.localeCompare(right.name));
 }
-export async function addIntegrations(workspace, names, mode = 'always') {
+export async function addIntegrations(workspace, names, mode = 'smart') {
     const config = await loadConfig(workspace);
     const byName = new Map(config.integrations.map((integration) => [integration.name, integration]));
     const changed = [];

package/dist/integrations/workflow-steps.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared KGraph workflow step strings used across all AI tool adapters.
+ * Update here once instead of in each adapter file.
+ */
+export interface WorkflowOptions {
+    /** Qualifier appended to the session step, e.g. "when native hooks are unavailable" */
+    sessionQualifier?: string;
+}
+/**
+ * Returns the 9-step numbered workflow for skill/agent/command files.
+ * Used by: copilot (agent file), codex (skill file), claude-code (command file).
+ */
+export declare function numberedWorkflow(agentName: string, options?: WorkflowOptions): string;
+/**
+ * Returns the bullet-list workflow for rules files.
+ * Used by: cursor, cline, windsurf, gemini.
+ */
+export declare function bulletWorkflow(agentName: string, options?: WorkflowOptions): string;

package/dist/integrations/workflow-steps.js

@@ -0,0 +1,44 @@
+/**
+ * Shared KGraph workflow step strings used across all AI tool adapters.
+ * Update here once instead of in each adapter file.
+ */
+const DOCTOR_STEP = `Run \`kgraph doctor\` when setup, maps, inbox processing, or integrations look wrong. Run \`kgraph doctor --quality\` when context shows stale/noisy cognition references.`;
+const IMPACT_STEP = `Run \`kgraph impact "<file-or-symbol>"\` when the user asks what a change may affect. Run \`kgraph history "<topic>"\` when prior work or decisions matter.`;
+const REPAIR_STEP = `Run \`kgraph repair --dry-run\` before cleanup when stale/noisy cognition needs fixing. Run \`kgraph repair\` only when the user asks to apply that cleanup.`;
+const HISTORY_STEP = `Run \`kgraph history\` or \`kgraph history "<topic>"\` to review past cognition sessions with git author attribution.`;
+function sessionStep(agentName, qualifier) {
+    const base = `Track meaningful session activity with \`kgraph session start --agent ${agentName}\`, \`kgraph session read <path> --agent ${agentName}\`, \`kgraph session write <path> --agent ${agentName}\`, and \`kgraph session end --agent ${agentName}\``;
+    return qualifier ? `${base} ${qualifier}.` : `${base}.`;
+}
+/**
+ * Returns the 9-step numbered workflow for skill/agent/command files.
+ * Used by: copilot (agent file), codex (skill file), claude-code (command file).
+ */
+export function numberedWorkflow(agentName, options = {}) {
+    return `1. Infer the topic from the user's request.
+2. {{KGRAPH_CONTEXT_POLICY}}
+3. Use the returned files, symbols, relationships, and cognition before broad exploration.
+4. ${DOCTOR_STEP}
+5. ${sessionStep(agentName, options.sessionQualifier)}
+6. ${IMPACT_STEP}
+
+{{KGRAPH_CAPTURE_POLICY}}
+
+7. ${REPAIR_STEP}
+8. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph at http://localhost:4242 with PNG export.
+9. ${HISTORY_STEP}`;
+}
+/**
+ * Returns the bullet-list workflow for rules files.
+ * Used by: cursor, cline, windsurf, gemini.
+ */
+export function bulletWorkflow(agentName, options = {}) {
+    return `- {{KGRAPH_CONTEXT_POLICY}}
+- ${DOCTOR_STEP}
+- ${sessionStep(agentName, options.sessionQualifier)}
+- ${IMPACT_STEP}
+{{KGRAPH_CAPTURE_POLICY}}
+- ${REPAIR_STEP}
+- Run \`kgraph visualize\` to open the interactive dependency graph at http://localhost:4242 with PNG export.
+- ${HISTORY_STEP}`;
+}

package/package.json

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