kushi-agents 3.12.1 → 3.13.0

package/.github/copilot-instructions.kushi.md

@@ -0,0 +1,38 @@
+## Kushi — Project Evidence Agent
+
+This workspace has [Kushi](https://gim-home.github.io/kushi/) installed under `.kushi/`. Kushi captures multi-source project evidence (Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO) via **WorkIQ** and answers cited questions over the captured evidence.
+
+### Routing — no `@Kushi` prefix required
+
+When the user types any of the following verbs followed by a project name, route to the corresponding Kushi prompt in `.kushi/prompts/` (no `@Kushi` needed):
+
+| Verb                       | Prompt to run                              |
+| -------------------------- | ------------------------------------------ |
+| `bootstrap <project>`      | `/pull-all-bootstrap`                      |
+| `refresh <project>`        | `/pull-all-refresh`                        |
+| `aggregate <project>`      | `/pull-all-aggregate`                      |
+| `state <project>`          | `/rebuild-state`                           |
+| `consolidate <project>`    | `/consolidate-evidence`                    |
+| `status <project>`         | `/show-run-log`                            |
+| `ask <project> <question>` | `/ask-project` (auto-routes to evidence Q&A) |
+
+Project Q&A also auto-dispatches when the user names a known project under the engagement root **and** asks a question about it — no prefix needed.
+
+### Hard rules (enforced by Kushi skills)
+
+- **WorkIQ-first** for all M365 sources. `m365_*` / Microsoft Graph calls are only allowed as a classified fallback after a documented WorkIQ failure.
+- **Every assertion** in any Kushi output (State files, Evidence summaries, consolidated reports, Open Questions) MUST carry an inline citation: `[source: <alias>/<folder>/<file> · YYYY-MM-DD]`.
+- **Read-only Q&A** — `ask` never triggers any `pull-*` skill. Stale evidence (>14d) prompts the user to refresh; Kushi does not auto-refresh.
+- **No cross-project bleed** — answers must be grounded only in the named project's `Evidence/` + `State/` + `snapshot/`.
+- **Never reach out** — Kushi does not send Teams/email/CRM-note/ADO-comment on the user's behalf unless they explicitly request it that turn. Recommendations go into the project's Open Questions, not into outbound sends.
+
+### Layout
+
+- `.kushi/agents/kushi.agent.md` — orchestrator (also addressable as `@Kushi`)
+- `.kushi/prompts/` — verb prompts (`/pull-*`, `/ask-project`, etc.)
+- `.kushi/skills/` — per-source pull + render skills
+- `.kushi/instructions/` — doctrine (citations, WorkIQ-first, freshness gates)
+- `.kushi/reference-packs/` — bundled domain doctrine (override at project / user / packaged layers)
+- `.kushi/kushi-install.json` — profile manifest written by the installer
+
+Full docs: <https://gim-home.github.io/kushi/>

package/bin/cli.mjs

@@ -26,6 +26,7 @@ if (args.includes('--help') || args.includes('-h')) {
     --dest <path>       Override destination (relative for vscode, absolute for clawpilot)
     --force             Overwrite existing destination without asking
     --no-settings       Skip .vscode/settings.json update (vscode target only)
+    --no-instructions   Skip .github/copilot-instructions.md merge (vscode target only)
     --help, -h          Show this help
 
   After install, talk to Kushi:
@@ -55,6 +56,7 @@ const options = {
   dest: getFlag('--dest'),
   force: args.includes('--force'),
   noSettings: args.includes('--no-settings'),
+  noInstructions: args.includes('--no-instructions'),
   target,
   profile: getFlag('--profile'),
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "3.12.1",
+  "version": "3.13.0",
   "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {
@@ -11,7 +11,8 @@
     "src/",
     "plugin/",
     ".github/config/m365-auth.json.example",
-    ".github/config/m365-mutable.json.example"
+    ".github/config/m365-mutable.json.example",
+    ".github/copilot-instructions.kushi.md"
   ],
   "engines": {
     "node": ">=18.0.0"

package/src/copilot-instructions.mjs

@@ -0,0 +1,80 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const KUSHI_BEGIN_MARKER = '<!-- BEGIN kushi-agents (managed — do not edit between markers) -->';
+export const KUSHI_END_MARKER = '<!-- END kushi-agents -->';
+
+const MARKER_REGEX = new RegExp(
+  `${escapeRegex(KUSHI_BEGIN_MARKER)}[\\s\\S]*?${escapeRegex(KUSHI_END_MARKER)}`,
+);
+
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Wrap the source content in our managed-block markers.
+ * @param {string} source
+ * @returns {string}
+ */
+function buildBlock(source) {
+  return `${KUSHI_BEGIN_MARKER}\n${source.trim()}\n${KUSHI_END_MARKER}\n`;
+}
+
+/**
+ * Merge the Kushi section into .github/copilot-instructions.md using
+ * managed-block markers. Three behaviors:
+ *
+ *   - File missing       → create it with a brief header + our block
+ *   - File has markers   → replace block content in place (idempotent upgrade)
+ *   - File without markers → append our block at the end, preserving user content
+ *
+ * @param {string} projectRoot
+ * @param {string} sourcePkgDir – root of the npm package (for reading the source template)
+ * @returns {{ action: 'created' | 'updated-block' | 'appended-block' | 'unchanged', path: string }}
+ */
+export function mergeCopilotInstructions(projectRoot, sourcePkgDir) {
+  const srcTemplate = path.join(
+    sourcePkgDir,
+    '.github',
+    'copilot-instructions.kushi.md',
+  );
+
+  if (!fs.existsSync(srcTemplate)) {
+    return { action: 'unchanged', path: '', reason: 'source template missing' };
+  }
+
+  const sourceContent = fs.readFileSync(srcTemplate, 'utf-8');
+  const block = buildBlock(sourceContent);
+
+  const githubDir = path.join(projectRoot, '.github');
+  const targetPath = path.join(githubDir, 'copilot-instructions.md');
+  const displayPath = '.github/copilot-instructions.md';
+
+  fs.mkdirSync(githubDir, { recursive: true });
+
+  if (!fs.existsSync(targetPath)) {
+    const header = `# Copilot Instructions\n\n_This file is auto-loaded by GitHub Copilot Chat into every chat turn in this workspace._\n\n`;
+    fs.writeFileSync(targetPath, header + block, 'utf-8');
+    return { action: 'created', path: displayPath };
+  }
+
+  const existing = fs.readFileSync(targetPath, 'utf-8');
+
+  if (MARKER_REGEX.test(existing)) {
+    const updated = existing.replace(MARKER_REGEX, block.trimEnd());
+    if (updated === existing) {
+      return { action: 'unchanged', path: displayPath };
+    }
+    fs.writeFileSync(targetPath, updated, 'utf-8');
+    return { action: 'updated-block', path: displayPath };
+  }
+
+  const separator = existing.endsWith('\n\n')
+    ? ''
+    : existing.endsWith('\n')
+      ? '\n'
+      : '\n\n';
+  fs.writeFileSync(targetPath, existing + separator + block, 'utf-8');
+  return { action: 'appended-block', path: displayPath };
+}

package/src/main.mjs

@@ -14,6 +14,7 @@ import {
 import { promptForDestination } from './prompt.mjs';
 import { copyAssets, copyProjectFiles } from './copy-assets.mjs';
 import { mergeSettings } from './settings.mjs';
+import { mergeCopilotInstructions } from './copilot-instructions.mjs';
 import {
   resolveProfile,
   makeIncludeFilter,
@@ -48,7 +49,7 @@ function resolveProfileForInstall(profileName) {
 
 /**
  * Orchestrator: prompt -> copy -> settings -> summary.
- * @param {{ dest?: string, force?: boolean, noSettings?: boolean, target?: string, profile?: string }} options
+ * @param {{ dest?: string, force?: boolean, noSettings?: boolean, noInstructions?: boolean, target?: string, profile?: string }} options
  */
 export async function main(options = {}) {
   const version = getVersion();
@@ -150,6 +151,22 @@ async function installVscode(options, resolved, version) {
     console.log('\n  Skipped .vscode/settings.json (--no-settings)');
   }
 
+  if (!options.noInstructions) {
+    const result = mergeCopilotInstructions(projectRoot, PKG_ROOT);
+    const labelByAction = {
+      'created': 'Created',
+      'updated-block': 'Updated managed Kushi block in',
+      'appended-block': 'Appended managed Kushi block to existing',
+      'unchanged': 'Unchanged',
+    };
+    if (result.action !== 'unchanged' || result.path) {
+      const label = labelByAction[result.action] || 'Touched';
+      console.log(`\n  ${label} ${result.path}`);
+    }
+  } else {
+    console.log('\n  Skipped .github/copilot-instructions.md (--no-instructions)');
+  }
+
   const { copied: projCopied, skipped: projSkipped } = copyProjectFiles(PKG_ROOT);
   if (projCopied.length > 0) {
     console.log('\n  Copied project files to .github/');