Kushi

A multi-skill GitHub Copilot agent for grounded engagement evidence — across Email, Teams, Meetings, OneNote, SharePoint, Dataverse (CRM), and Azure DevOps.

KUSHI — Knowledge Unification for Stakeholder Handoff & Insight.

Also: Kushi (குஷி) is Tamil for "happiness" — the kind you feel when every "what was decided?" question has a cited answer in seconds.

📖 Full docs: https://gim-home.github.io/kushi/

The essence: aggregate, then answer

Kushi has two halves that work as one loop:

1. Aggregate — pull evidence from every M365 + CRM + ADO surface (email, Teams, meetings, OneNote, SharePoint, Dataverse, Azure DevOps) into a structured per-engagement folder on disk. Captured as snapshot (current truth) + stream (timestamped events), with provenance.
2. Answer — a read-only ask-me-anything agent over that evidence. Every assertion cites the source file + date. No new pulls at answer time. No hallucination. Freshness-gated. Auto-routes when a message names a known project and asks a question — no special prefix needed.

> @Kushi bootstrap Acme           # aggregate: pull 30d baseline + build State
> what's the MACC for Acme?       # answer: cited, grounded, instant
> who is the EM on Acme?          # answer: auto-routes, no prefix
> @Kushi refresh Acme             # aggregate: incremental from last watermark

The split is deliberate: aggregation is heavy, scheduled, replayable; answering is cheap, instant, citable. A weekly refresh keeps the corpus fresh so every question is already grounded.

See Concepts → Aggregate, then Answer for the full pattern.

Two-way sync to ADO — preview shipped

Kushi can now propose updates back to ADO from the cited evidence it already has. Two skills under the opt-in preview profile:

• ✅ propose-ado-update — fully working, read-only. Reads the latest _Consolidated/ evidence and writes <project>/ado-updates/<date>/proposed.md with a field-update preview + Discussion comment + per-bullet citations + per-item confidence scores. Safe to run on the same Monday-9am schedule as refresh.
• ✅ apply-ado-update — preview-stub. Re-fetches live ADO state, runs the approval gate, writes a planned.jsonl of what would be PATCH/POST'd. Real ADO calls land in v0.1.x once the proposal format is validated against multiple projects.

> @Kushi propose ado Acme

  #4821  Status: Active → Resolved
         Evidence: Email 2026-05-12 from Priya — "shipped to prod Monday"
         Confidence: high

  #4837  AssignedTo: Sam → Priya
         Evidence: Teams 2026-05-11 — "I'll take this one over from Sam"
         Confidence: medium

Apply [a]ll · [s]elect · [n]one?

Safety guarantees — preview-first diffs, approval gate or per-project allowlist, ledger with reverse op for every applied write, hard tenant-allowlist guard, no bulk migrations, no CRM writes (ADO first).

Try it: npx kushi-agents --clawpilot --profile preview · How-to: Two-way ADO update · Roadmap: docs/concepts/roadmap.md.

Three install profiles

Kushi ships in three tiers. Pick how much you take — the default (standard) matches v2.x behavior end-to-end.

| Profile | What's installed | Pick this if… | |---|---|---| | core | Aggregator only: aggregate, consolidate, status, pull, ask | You want raw Evidence/ + cited Q&A — typically to feed an external rollup repo or BI system. | | standard (default) | core + bootstrap, refresh, FDE authoring trio (fde-intake, fde-report, fde-triage) + FDE reference pack | Kushi's default opinion. No State/ rollup. | | full | standard + state (renders the opinionated State/ rollup) | You want everything, including the outcome-based State/ files. |

npx kushi-agents --clawpilot                       # default = standard
npx kushi-agents --clawpilot --profile core        # aggregator only
npx kushi-agents --clawpilot --profile full        # everything

The Evidence/ folder produced by every profile is a stable public contract — external systems can read from it without depending on Kushi internals. See Concepts → Profiles and report packs and the Evidence contract.

Verbs

| Verb | Profile | Window | What it does | |------|---------|--------|--------------| | setup | core+ | n/a | Functionally verify WorkIQ is reachable + auto-fill contributor identity. Idempotent. Run once per machine before first bootstrap/refresh. | | aggregate | core+ | last watermark → now | Pull every enabled source + consolidate. No State/ rebuild. | | bootstrap | standard+ | 30 days (default) | First-time setup — scaffold folders, lay configs side-by-side, initial pull. Profile-aware (builds State only on full). | | refresh | standard+ | last watermark → now | Pull only what changed. Profile-aware (rebuilds State only on full). | | state | full | n/a | Render the outcome-based State/ files from existing evidence. No new pulls. | | consolidate | core+ | per week | Merge per-user streams into _Consolidated/<YYYY-MM-DD>_consolidated.md. | | status | core+ | n/a | Show the run-log for a project. | | ask | core+ | n/a | Read-only natural-language Q&A. Always cites. Auto-routes. | | fde-intake | standard+ | n/a | Capture the 6 FDE intake questions → Reports/00-FDE-Intake-<project>.md (updated in place). | | fde-report | standard+ | n/a | FDE report generator. 5 shapes: weekly (default), short, long, fitness, stage-readiness. | | fde-triage | standard+ | n/a | 7-file FDE triage bundle at Reports/triage/<YYYY-MM-DD>/. File 07 merges across re-runs. | | propose-ado | preview | n/a | Read-only ADO update proposal from latest _Consolidated/ → ado-updates/<date>/proposed.md. Safe to schedule. No ADO writes. | | apply-ado | preview | n/a | Gated apply skill. v0.1.0-preview is dry-mode only (writes planned.jsonl); real ADO PATCH/POST lands in v0.1.x. |

See Quickstart for the full workflow.

Install

Two install targets — pick the one that matches how you talk to Copilot, optionally combined with a profile.

VS Code Chat — .kushi/ in your workspace:

npx kushi-agents                               # default profile (standard)
npx kushi-agents --profile core                # aggregator only

Clawpilot CLI — ~/.copilot/m-skills/kushi/:

npx kushi-agents --clawpilot
npx kushi-agents --clawpilot --profile full

To switch profiles later, re-run with --force (cleanly handles downgrades):

npx kushi-agents --clawpilot --profile core --force

Bleeding-edge from GitHub (Microsoft org members only): npx github:gim-home/kushi … works identically and pulls straight from the source repo — useful for testing pre-release commits. Stick to npx kushi-agents for everything else.

See Install for flags, prerequisites, and per-user config.

What it does

Engagement context lives in too many places. By the time someone asks "what was decided about the architecture?" or "who is the EM on project X?" the answer is buried across emails, Teams threads, OneNote pages, SharePoint files, meeting transcripts, CRM records, and ADO work items.

Kushi pulls all of those into a structured, citable, per-engagement folder — and lets you ask grounded questions that always cite the source.

• WorkIQ-only: every source pull uses WorkIQ. We walk you through installing it — Microsoft Graph isn't a viable fallback here. When WorkIQ can't answer, Kushi asks you to paste rather than producing thin metadata.
• Snapshot + stream: current truth and the trail of how we got there.
• Citation per assertion: every claim in State files and answers points back to a real source file with a date.
• Host-agnostic: works in VS Code Chat or Clawpilot CLI.

Output shapes (what aggregation writes to disk)

For each source, Kushi produces two output shapes:

| Shape | What | Filename | Refresh behavior | |-------|------|----------|------------------| | Snapshot | Current state of an entity (page body, work item, CRM record, file content) | snapshot/<entity>.md (NO date in filename) | Replace on every refresh | | Stream | Timestamped events (emails, messages, edits, comments, state changes) | stream/<YYYY-MM-DD>_<source>-stream.md (Monday of ISO week) | Append, dedupe by event ID |

Email is stream-only (emails ARE events). Every other source has both. ask-project reads both shapes when answering.

Documentation

| | | |---|---| | 🚀 Getting started | Install + quickstart — pick a target, run one npx command | | 💡 Concepts | Hosts, storage backends, snapshot vs stream, multi-user model | | 🛠️ How-to guides | Schedule refreshes, add contributors, switch backends, upgrade, uninstall | | 📖 Reference | Verbs, CLI options, config files, path map, self-check | | 📋 Changelog | Release history |

Repository layout (high level)

kushi/
├── bin/cli.mjs              Installer entry point
├── src/                     Installer source
├── plugin/                  ← THE PAYLOAD that ships into .kushi/ (or ~/.copilot/m-skills/kushi/)
│   ├── plugin.json
│   ├── agents/
│   ├── instructions/
│   ├── prompts/
│   ├── skills/
│   └── templates/
├── docs/                    MkDocs Material site (deployed to GitHub Pages)
├── mkdocs.yml
├── requirements-docs.txt
├── README.md
├── CHANGELOG.md
└── LICENSE

See docs/reference/where-things-live.md for the complete layout.

Contributing

See CONTRIBUTING.md for the full contributor guide — repo layout, dev environment setup, the pre-commit checklist (self-check + mkdocs + npm pack), commit conventions, and how to add new skills/instructions/templates.

Quick pre-commit check:

pwsh plugin/skills/self-check/run.ps1 -Deep
mkdocs build --strict
npm pack --dry-run

The self-check validates frontmatter, agent inventory, prompt → skill routing, profile manifest, reference packs, cross-links, the verbs table in this README, and the layout diagram in docs/reference/where-things-live.md. Full reference: docs/reference/self-check.md.

License

See LICENSE.