kushi-agents 4.0.0 → 4.2.0

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

@@ -37,6 +37,7 @@ Project Q&A also auto-dispatches when the user names a known project under the e
 - `.kushi/instructions/` — doctrine (citations, WorkIQ-first, freshness gates)
 - `.kushi/reference-packs/` — bundled domain doctrine (override at project / workspace / packaged layers)
 - `.kushi/config/` — **user-editable** (project-evidence.yml, integrations.yml, reference-overrides). Seeded on first install; never overwritten on upgrade.
+- `.kushi/tracking/` — **agent working memory** (runs/, qa/, fde/, research/). Per-run Markdown journals: what was asked, what was done, what was decided, what's still open. Gitignored by default. See `instructions/tracking.instructions.md`.
 - `.kushi/kushi-install.json` — profile manifest written by the installer
 
 Full docs: <https://gim-home.github.io/kushi/>

package/bin/cli.mjs

@@ -29,6 +29,13 @@ if (args.includes('--help') || args.includes('-h')) {
                         check (useful for scripted or agent-driven installs)
     --no-settings       Skip .vscode/settings.json update (vscode target only)
     --no-instructions   Skip .github/copilot-instructions.md merge (vscode target only)
+
+  WorkIQ (REQUIRED — Kushi cannot pull evidence without it):
+    --with-workiq           Auto-install WorkIQ via winget (Windows) / brew (macOS)
+    --workiq-path <abs>     Use this explicit path to the workiq binary
+    --skip-workiq-check     Bypass the WorkIQ pre-flight check (CI / inspection only —
+                            bootstrap/refresh will block until WorkIQ is installed)
+
     --help, -h          Show this help
 
   After install, talk to Kushi:
@@ -62,6 +69,9 @@ const options = {
   noInstructions: args.includes('--no-instructions'),
   target,
   profile: getFlag('--profile'),
+  withWorkiq: args.includes('--with-workiq'),
+  workiqPath: getFlag('--workiq-path'),
+  skipWorkiqCheck: args.includes('--skip-workiq-check'),
 };
 
 main(options).catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "4.0.0",
+  "version": "4.2.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": {

package/plugin/instructions/identity-resolution.instructions.md

@@ -0,0 +1,66 @@
+---
+applyTo: "**"
+description: "Identity auto-resolution — Kushi never asks the user for alias / email / display_name. On the first bootstrap (or whenever those fields are <auto> / placeholder in .kushi/config/project-evidence.yml), Kushi resolves them from WorkIQ in a single call, persists them, and continues. Skipped entirely if the user has set explicit values."
+---
+
+# Identity Resolution — Don't Ask, Probe
+
+Kushi must not prompt the user for `alias`, `email`, or `display_name`. These are derivable from WorkIQ in one call, and asking is poor UX.
+
+## When to resolve
+
+On the **first step of every prompt** that reads contributor identity (bootstrap, refresh, aggregate, ask, fde-*, propose-ado, apply-ado), check `<workspace>/.kushi/config/project-evidence.yml`:
+
+* If `alias`, `email`, or `display_name` is **missing**, set to `<auto>`, or matches a placeholder pattern (`<your-alias>`, `<Your Full Name>`, `your.email@example.com`) → **resolve from WorkIQ**.
+* If all three are explicit non-placeholder values → **skip**. Respect the user's override.
+
+## How to resolve
+
+Single WorkIQ call:
+
+```bash
+workiq ask -q "Who am I? Return my UPN (email), display name, and mail nickname as JSON: {\"upn\":\"...\",\"displayName\":\"...\",\"mailNickname\":\"...\"}"
+```
+
+Map the response:
+
+| Config field   | Source                              | Fallback if missing                  |
+|----------------|-------------------------------------|--------------------------------------|
+| `email`        | `upn`                               | Block — must be present              |
+| `display_name` | `displayName`                       | Same as `alias`                      |
+| `alias`        | `mailNickname`                      | `upn.split('@')[0]` (lowercase)      |
+
+## After resolution
+
+1. **Persist back** to `<workspace>/.kushi/config/project-evidence.yml` (preserving comments + indentation). The user sees the resolved values on next open; no surprise.
+2. **Echo back** to the user, one line:
+   > ✓ Identity: `Alex Smith <alex@microsoft.com>` (alias=`alex`). Edit `.kushi/config/project-evidence.yml` to override.
+3. **Continue** the prompt.
+
+## Failure modes
+
+| Scenario                                      | Behavior                                                                                                                     |
+|-----------------------------------------------|------------------------------------------------------------------------------------------------------------------------------|
+| WorkIQ returns auth error                     | Block: "Sign in to WorkIQ first: `workiq accept-eula && workiq ask -q ping`". Do not proceed.                                |
+| WorkIQ returns empty / NO_RESULTS             | Block: "WorkIQ could not resolve your identity. Try `workiq ask -q 'who am I'` and retry."                                   |
+| WorkIQ binary missing                         | This should already have been caught by the installer's pre-flight. If reached, block with the same install hint.            |
+| User has explicit non-placeholder values      | Skip resolution entirely. Never overwrite user-set values.                                                                   |
+| Alias collision with another contributor      | Bootstrap detects existing `Evidence/<alias>/` whose `contributors.yml` records a different email → ask the user to disambiguate (suggest `<alias>-<tenant-prefix>` e.g. `alex-ms`). |
+
+## What NOT to do
+
+* Do NOT ask the user `What alias should Kushi use?`. The legacy onboarding prompt is gone.
+* Do NOT call `m365_*` / Graph as a fallback. WorkIQ is the single source of identity truth (`workiq-first.instructions.md`).
+* Do NOT resolve on every run. Once persisted, the config values are authoritative.
+
+## Integration with other doctrine
+
+* `workiq-first.instructions.md` — identity resolution is the canonical example of WorkIQ-first. Add to the inventory.
+* `bootstrap-project` SKILL — Step 0 is identity resolution. Step 1 is project context.
+* `tracking.instructions.md` — the resolved identity goes into the tracking artifact's frontmatter under `actor:`.
+
+## References
+
+* `workiq-first.instructions.md` — the parent doctrine.
+* `engagement-root-resolution.instructions.md` — `projects_root` resolution (separate from identity).
+* `templates/init/project-evidence.template.yml` — defaults to `<auto>` for these three fields.

package/plugin/instructions/tracking.instructions.md

@@ -0,0 +1,165 @@
+---
+applyTo: "**"
+description: "Kushi tracking convention — every Kushi prompt/skill writes its working memory (what it was asked, what it did, what it decided, what's still open) to `<workspace>/.kushi/tracking/` so users can see, edit, diff, and resume the agent's work. This is host-agnostic (VS Code Chat, Clawpilot, Cursor) and complements — never replaces — Evidence/ (canonical outputs) or State/ (rollups)."
+---
+
+# Tracking — Agent Working Memory
+
+Kushi agents must leave a visible trail. Every meaningful run produces a small Markdown artifact under `<workspace>/.kushi/tracking/` describing what was asked, what was done, what was decided, and what is still open.
+
+This is **the journey**, not the **output**. Outputs land under `Evidence/`, `State/`, `Reports/`, `ado-updates/`, etc. Tracking files explain *why* and *how* those outputs ended up the way they did, so the user (or a future agent) can pick up where you left off.
+
+## Why this exists
+
+* **Visible thinking.** The user can read what the agent considered and rejected, not just the final artifact.
+* **Reliable handoff.** Stable filenames mean Bootstrap → Refresh → State → Ask never loses context across `/clear`, new chats, or host swaps.
+* **Resumability.** A 60-minute pull that died at 80% can be resumed from its last tracking entry instead of restarted.
+* **Audit + replay.** Diff-able, grep-able, commit-able (or gitignored — user's choice).
+* **Single convention across hosts.** Same shape in VS Code Chat, Clawpilot, Cursor, Cline.
+
+## Folder layout
+
+```
+<workspace>/.kushi/tracking/
+  .gitignore                                          ← ignore everything by default
+  runs/{{YYYY-MM-DD}}-<project>-<verb>.md             ← bootstrap / refresh / aggregate / state / consolidate
+  qa/{{YYYY-MM-DD}}-<project>-<question-slug>.md      ← /ask answers + citations, archived
+  fde/intake/{{YYYY-MM-DD}}-<project>-<slug>.md       ← /fde-intake drafts
+  fde/report/{{YYYY-MM-DD}}-<project>-<slug>.md       ← /fde-report drafts
+  fde/triage/{{YYYY-MM-DD}}-<project>-<slug>.md       ← /fde-triage drafts
+  research/{{YYYY-MM-DD}}-<topic>.md                  ← optional deep-dive notes
+```
+
+Rules:
+
+* Filenames start with `YYYY-MM-DD` (ISO date, UTC if ambiguous) so chronological sort works everywhere.
+* `<project>` is the engagement folder name (slugified — lowercase, hyphenated, no spaces).
+* `<verb>` is the prompt name without slash (`bootstrap`, `refresh`, ...).
+* `<slug>` / `<question-slug>` is 3–6 word kebab-case derived from the user's ask.
+* Create directories as needed on first write.
+
+## On first write — seed `.gitignore`
+
+If `<workspace>/.kushi/tracking/` does not yet exist, create it and write `<workspace>/.kushi/tracking/.gitignore` with:
+
+```gitignore
+# Kushi tracking files are working memory, not source of truth.
+# Outputs live under Evidence/, State/, Reports/, ado-updates/.
+# Uncomment the next line to start committing tracking artifacts.
+*
+!.gitignore
+```
+
+A user who wants to commit their agent transcripts deletes `*` from this file. Default is private.
+
+## Required sections in every tracking artifact
+
+Every tracking file is Markdown with frontmatter + a small set of named sections. Keep it short — this is a journal, not a report.
+
+```markdown
+---
+prompt: bootstrap                        # /bootstrap, /refresh, /ask, /fde-intake, ...
+project: hca                             # slugified engagement folder name
+window: last 30 days                     # bootstrap/refresh only; otherwise omit
+started: 2026-05-19T14:02:00-04:00
+finished: 2026-05-19T14:38:12-04:00      # omit if still in progress
+status: complete                         # complete | in-progress | blocked | failed
+host: vscode                             # vscode | clawpilot | cursor | cline | other
+kushi_version: 4.1.0
+---
+
+## Ask
+
+> Verbatim or near-verbatim of what the user asked for. One short paragraph.
+
+## Inputs resolved
+
+- Engagement root: `C:/.../Engagement Assets`
+- Project folder: `HCA Healthcare`
+- Alias: `ushak`
+- Config: `<workspace>/.kushi/config/project-evidence.yml`
+
+## Steps taken
+
+1. Resolved project context via `engagement-root-resolution.instructions.md`.
+2. Ran `pull-email` (WorkIQ) → 142 messages, 30-day window.
+3. Ran `pull-teams` (WorkIQ) → 11 chats, 308 messages.
+4. … (one line per meaningful step)
+
+## Decisions
+
+- Skipped `pull-crm` — `integrations.yml` has no `crm.engagement_id` for this project.
+- Used WorkIQ-only path; no `m365_*` fallback triggered.
+
+## Outputs
+
+- `HCA Healthcare/Evidence/ushak/email/snapshot/2026-05-19.md`
+- `HCA Healthcare/Evidence/ushak/teams/snapshot/2026-05-19.md`
+- `HCA Healthcare/State/00_overview.md` (updated)
+
+## Open questions / next steps
+
+- ADO field `Custom.FDEStatusSummary` is empty — recommend running `/fde-report hca` next.
+- 3 OneNote pages returned `page-body-unavailable`; see notes in `Evidence/ushak/onenote/run-notes.md`.
+
+## Errors / fallbacks
+
+- None.
+
+## Citations
+
+- `Evidence/ushak/email/snapshot/2026-05-19.md` · 2026-05-19
+- `Evidence/ushak/teams/snapshot/2026-05-19.md` · 2026-05-19
+```
+
+Section rules:
+
+* **Ask** — required. One short paragraph.
+* **Steps taken** — required. One bullet per meaningful action. Skip trivial tool calls.
+* **Decisions** — required when you chose A over B, skipped a step, or applied a fallback.
+* **Outputs** — required. Bullet list of files written/updated this run.
+* **Open questions / next steps** — required, even if empty (write "None.").
+* **Errors / fallbacks** — required when anything failed, retried, or fell back to a classified-fallback path (e.g., WorkIQ → `m365_*`).
+* **Citations** — required when the artifact references Evidence files; same format as everywhere else in Kushi (`<source-path> · <YYYY-MM-DD>`).
+
+## When to write
+
+* **First step of every prompt run:** create the file with frontmatter (`status: in-progress`) so a crash leaves something behind.
+* **As you go:** append "Steps taken" lines. Update "Outputs" when files land.
+* **Last step of every prompt run:** set `status: complete` (or `blocked` / `failed`), set `finished`, and fill in the closing sections.
+
+If the prompt runs multiple sub-skills in parallel, the orchestrating prompt owns the tracking file. Sub-skills do not write their own runs/ entry; they report back and the parent appends.
+
+## When NOT to write
+
+* `intro`, `status`, `self-check` — trivial / introspective. Skip the tracking file.
+* Any prompt that does nothing but read a single file and answer.
+* Dry-run / preview invocations (`--dry-run`, `--preview`) — log to stdout only.
+
+## Interaction with other doctrine
+
+* `update-ledger.instructions.md` — write-path skills (ADO apply, future CRM apply) still write a **ledger** under `<project>/ado-updates/<date>/`. The tracking file additionally records that a write happened and links to the ledger. Ledger is authoritative for *what was written*; tracking is the *story around it*.
+* `evidence-layout-canonical.instructions.md` — tracking files are NEVER a substitute for Evidence/. Evidence/ is the contract; tracking is the journal.
+* `answer-from-evidence.instructions.md` — `/ask` writes its answer to `qa/` *in addition to* returning it in chat, so the same question asked tomorrow can be answered from the archive (with a freshness check).
+
+## Cross-host behavior
+
+* Path is always relative to the **workspace root** (the folder the user opened in VS Code / Clawpilot / Cursor).
+* In Clawpilot specifically, the workspace root is whichever folder the user is operating on (an engagement folder, a code repo, etc.) — *not* `~/.copilot/m-skills/kushi/`. The Kushi install location and the tracking location are independent.
+* The Clawpilot weekly automation (`~/.copilot/kushi-projects.json`) is unaffected — it operates on engagement folders and produces tracking artifacts in each engagement folder's `.kushi/tracking/`.
+
+## Self-check coverage
+
+Future self-check rule **C14: tracking-artifact required** will verify:
+
+* Every prompt under `plugin/prompts/` (except the opt-out list above) references this instruction file.
+* Every prompt's closing step is "write/update the tracking artifact".
+
+C14 is added when this convention reaches 1.0 across all prompts.
+
+## References
+
+* `evidence-layout-canonical.instructions.md` — Evidence/ shape (the canonical output).
+* `update-ledger.instructions.md` — write-path ledger (orthogonal, additive).
+* `citation-ledger.instructions.md` — citation format used inside tracking artifacts.
+* `engagement-root-resolution.instructions.md` — how to resolve `<project>` for the filename slug.

package/plugin/instructions/workiq-only.instructions.md

@@ -28,6 +28,7 @@ Applies to ALL evidence retrieval from these M365 sources:
 - Email bodies and attachments
 - SharePoint file contents (when text extraction is needed)
 - Calendar events (when not already known by id)
+- **Contributor identity** (UPN / displayName / mailNickname) — see `identity-resolution.instructions.md` for the canonical "who am I?" probe.
 
 **Out of scope** (these are NOT WorkIQ — they remain on their direct paths):
 

package/plugin/prompts/aggregate.prompt.md

@@ -22,3 +22,5 @@ This is the **pull-only** verb. Every enabled source is pulled and per-user stre
 ```
 
 See `skills/aggregate-project/SKILL.md` for the full sequence and output contract.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-aggregate.md` as the final step.

package/plugin/prompts/ask.prompt.md

@@ -14,3 +14,5 @@ Read-only. NEVER triggers a `pull-*` skill — if evidence is stale or missing,
 You don't actually need this prompt — `ask-project` auto-routes whenever your message names a known project and asks a question (what / who / when / status / summarize / etc.). The slash form just provides an explicit handle.
 
 Delegates to `ask-project` skill.
+
+Tracking: see `tracking.instructions.md`. Archive every answer to `<workspace>/.kushi/tracking/qa/{{YYYY-MM-DD}}-<project>-<question-slug>.md` (frontmatter + Ask + Answer + Citations + freshness note).

package/plugin/prompts/bootstrap.prompt.md

@@ -20,4 +20,6 @@ Produces:
 - `<engagement-root>/<project>/Evidence/{contributors.yml, run-log.yml, <alias>/.settings.yml, <alias>/{email,teams,meetings,onenote,sharepoint,crm,ado}/{snapshot,stream}/}`
 - `<engagement-root>/<project>/State/{00..09}_*.md`
 
-Delegates to `bootstrap-project` skill. After scaffolding, calls each `pull-<source>` skill, then `build-state`.
+Delegates to `bootstrap-project` skill. After scaffolding, calls each `pull-<source>` skill, then `build-state`.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-bootstrap.md` as the final step.

package/plugin/prompts/consolidate.prompt.md

@@ -18,4 +18,6 @@ Writes:
 
 Provenance tags retained (source: <alias>/<source>/<file>) per `citation-ledger.instructions.md`.
 
-Delegates to `consolidate-evidence` skill.
+Delegates to `consolidate-evidence` skill.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-consolidate.md` as the final step.

package/plugin/prompts/fde-intake.prompt.md

@@ -39,3 +39,5 @@ Authors (first time) or updates (subsequent runs) the **FDE Intake** at `<engage
 - `skills/fde-intake/SKILL.md` for the full step-by-step.
 - `@Kushi fde-triage <project>` — produces the 7-file triage bundle that builds ON the intake.
 - `@Kushi fde-report <project> stage-readiness` — separate "should we advance the stage?" check.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/fde/intake/{{YYYY-MM-DD}}-<project>-<slug>.md` as the final step.

package/plugin/prompts/fde-report.prompt.md

@@ -44,3 +44,5 @@ Generates an FDE-shaped engagement report. Read-only against Evidence; no outbou
 - `skills/fde-report/SKILL.md` for the full step-by-step.
 - `@Kushi fde-intake <project>` — precursor first-artifact intake document.
 - `@Kushi fde-triage <project>` — full 7-file triage bundle (analysis + fitness + risk + 6Q + mobilization readiness + executive readout + reuse lens + validation warnings).
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/fde/report/{{YYYY-MM-DD}}-<project>-<shape>.md` as the final step.

package/plugin/prompts/fde-triage.prompt.md

@@ -44,3 +44,5 @@ Re-running on the same day overwrites files 00–06 in place and **merges file 0
 - `skills/fde-triage/SKILL.md` for the full step-by-step.
 - `@Kushi fde-intake <project>` — first-artifact intake document (precursor to the bundle).
 - `@Kushi fde-report <project> [shape]` — individual report shapes (weekly / short / long / fitness / stage-readiness).
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/fde/triage/{{YYYY-MM-DD}}-<project>-bundle.md` as the final step (one summary entry, not 7 — the bundle itself lives under `Reports/triage/`).

package/plugin/prompts/refresh.prompt.md

@@ -14,4 +14,6 @@ Window resolution (per `refresh-project` skill):
 
 Output is always weekly-bucketed regardless of input window.
 
-Delegates to `refresh-project` skill. Skips `pull-<source>` for sources marked disabled in `integrations.yml` or whose config is missing.
+Delegates to `refresh-project` skill. Skips `pull-<source>` for sources marked disabled in `integrations.yml` or whose config is missing.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-refresh.md` as the final step.

package/plugin/prompts/state.prompt.md

@@ -14,4 +14,6 @@ Pure renderer. Reads:
 Writes:
 - `<engagement-root>/<project>/State/{00_overview, 01_decisions, 02_stakeholders, 03_architecture-and-solution, 04_workshops-and-key-meetings, 05_action-items, 06_risks-and-issues, 07_timeline-and-milestones, 08_artifacts-and-deliverables, 09_open-questions}.md`
 
-Delegates to `build-state` skill. Use this when you've manually edited Evidence files and want State refreshed without re-pulling.
+Delegates to `build-state` skill. Use this when you've manually edited Evidence files and want State refreshed without re-pulling.
+
+Tracking: see `tracking.instructions.md`. Write `<workspace>/.kushi/tracking/runs/{{YYYY-MM-DD}}-<project>-state.md` as the final step.

package/plugin/skills/bootstrap-project/SKILL.md

@@ -35,10 +35,25 @@ After every run (success or coverage-gaps), write `<project>/bootstrap-status.md
 
 - `<project>` — engagement name (fuzzy-matched per `engagement-root-resolution.instructions.md`).
 - `<window>` — defaults to **last 30 days** (override with `last N days` / `since <date>`).
-- Implicit: current contributor `<alias>` (from personal config).
+- Implicit: current contributor `<alias>` (resolved in Step 0 — see below).
 
 ## Steps
 
+### Step 0 — Identity resolution (REQUIRED, never asks the user)
+
+Per `identity-resolution.instructions.md`. Read `<workspace>/.kushi/config/project-evidence.yml`:
+
+* If `alias`, `email`, or `display_name` is missing / `<auto>` / matches a placeholder → call WorkIQ once:
+  ```
+  workiq ask -q "Who am I? Return UPN, displayName, mailNickname as JSON."
+  ```
+  Map `upn → email`, `displayName → display_name`, `mailNickname → alias` (fallback `email.split('@')[0]`).
+* Persist resolved values back to the YAML (preserve comments).
+* Echo one line: `✓ Identity: <displayName> <<UPN>> (alias=<alias>). Edit .kushi/config/project-evidence.yml to override.`
+* If all three are already explicit non-placeholder values → skip silently.
+
+Hard stop if WorkIQ returns auth error or empty — print the WorkIQ sign-in hint and exit. Never fall back to asking the user.
+
 ### Step 1 — Machine preflight (SETUP)
 
 Verify in order. Stop on hard failures.

package/plugin/templates/init/project-evidence.template.yml

@@ -5,14 +5,23 @@
 # maintains their own. Nothing here is a secret, but it IS personal —
 # add `.kushi/config/` to .gitignore before committing the rest of .kushi/.
 #
-# Edit the values below (lines marked FILL ME IN), then run `bootstrap <project>`.
+# IDENTITY — auto-detected on first bootstrap.
+#   On the first run of `bootstrap <project>`, Kushi asks WorkIQ "who am I?"
+#   and fills these three fields in for you (UPN, displayName, mailNickname).
+#   You only need to override them if you want a different folder name or
+#   a friendlier display label. Leave them at the placeholder values to
+#   trigger auto-detection.
 
-# FILL ME IN — short id used as your evidence subfolder name (e.g. "alex", "jordan").
-alias: <your-alias>
+# Optional override — short id used as your Evidence/ subfolder name.
+# Leave as <auto> to derive from the part before "@" in your email.
+alias: <auto>
 
-# FILL ME IN
-display_name: <Your Full Name>
-email: your.email@example.com
+# Optional override — friendly label used in run logs.
+# Leave as <auto> to pull from WorkIQ's displayName.
+display_name: <auto>
+
+# Optional override — your work email. Leave as <auto> to pull from WorkIQ.
+email: <auto>
 
 # FILL ME IN — where your engagement-root lives. The parent folder containing
 # one subfolder per project (typically synced from a team SharePoint library).
@@ -35,4 +44,5 @@ active_projects:
 #   2. `workiq` on PATH
 #   3. ~/.kushi/bin/workiq.cmd  (Windows) / ~/.kushi/bin/workiq  (Linux/macOS)
 # workiq:
-#   cli_path: 'C:\Users\<you>\.kushi\bin\workiq.cmd'
+#   cli_path: 'C:\Users\<you>\.kushi\bin\workiq.cmd'
+

package/src/check-workiq.mjs

@@ -0,0 +1,125 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+/**
+ * Probe for a working WorkIQ install.
+ *
+ * Resolution order:
+ *   1. explicit absolute path supplied via --workiq-path / opts.workiqPath
+ *   2. `workiq` on PATH (via `where` on Windows, `command -v` elsewhere)
+ *   3. Kushi-managed bin: ~/.kushi/bin/workiq.cmd (Win) or ~/.kushi/bin/workiq
+ *
+ * Returns:
+ *   { ok: true,  path, version }                       — usable WorkIQ found
+ *   { ok: false, reason, hint }                        — not found / not runnable
+ *
+ * Reasons:
+ *   'not-found'        — no workiq binary anywhere we looked
+ *   'path-invalid'     — explicit --workiq-path was given but the file doesn't exist
+ *   'not-executable'   — found but `--version` failed (corrupt install, missing deps, etc.)
+ */
+export function checkWorkIQ(opts = {}) {
+  const isWin = process.platform === 'win32';
+  const homeBin = path.join(
+    os.homedir(),
+    '.kushi',
+    'bin',
+    isWin ? 'workiq.cmd' : 'workiq',
+  );
+
+  if (opts.workiqPath) {
+    const abs = path.resolve(opts.workiqPath);
+    if (!existsSync(abs) || !statSync(abs).isFile()) {
+      return {
+        ok: false,
+        reason: 'path-invalid',
+        hint: `--workiq-path "${opts.workiqPath}" does not point at an existing file.`,
+      };
+    }
+    return runVersion(abs);
+  }
+
+  const onPath = findOnPath('workiq');
+  if (onPath) return runVersion(onPath);
+
+  if (existsSync(homeBin) && statSync(homeBin).isFile()) {
+    return runVersion(homeBin);
+  }
+
+  return {
+    ok: false,
+    reason: 'not-found',
+    hint: installHint(),
+  };
+}
+
+function findOnPath(name) {
+  const isWin = process.platform === 'win32';
+  const cmd = isWin ? 'where' : 'command';
+  const args = isWin ? [name] : ['-v', name];
+  const res = spawnSync(cmd, args, { encoding: 'utf-8', shell: !isWin });
+  if (res.status !== 0) return null;
+  const first = (res.stdout || '').split(/\r?\n/).map((s) => s.trim()).find(Boolean);
+  return first || null;
+}
+
+function runVersion(binPath) {
+  const res = spawnSync(binPath, ['--version'], { encoding: 'utf-8', timeout: 10_000 });
+  if (res.status !== 0) {
+    return {
+      ok: false,
+      reason: 'not-executable',
+      hint: `Found WorkIQ at ${binPath} but \`workiq --version\` failed (exit ${res.status}). Try reinstalling. ${installHint()}`,
+    };
+  }
+  const version = (res.stdout || res.stderr || '').trim().split(/\r?\n/)[0] || 'unknown';
+  return { ok: true, path: binPath, version };
+}
+
+function installHint() {
+  const plat = process.platform;
+  if (plat === 'win32') {
+    return 'Install with: winget install Microsoft.WorkIQ';
+  }
+  if (plat === 'darwin') {
+    return 'Install with: brew install --cask microsoft-workiq';
+  }
+  return 'See https://gim-home.github.io/kushi/getting-started/install-workiq/ for Linux instructions.';
+}
+
+/**
+ * Best-effort auto-install via the platform's package manager.
+ * Only invoked when --with-workiq is passed. Non-blocking on failure —
+ * caller decides whether to hard-fail.
+ *
+ * Returns { ok, reason, output }.
+ */
+export function tryInstallWorkIQ() {
+  const plat = process.platform;
+  let cmd, args;
+  if (plat === 'win32') {
+    cmd = 'winget';
+    args = ['install', '--id', 'Microsoft.WorkIQ', '-e', '--accept-package-agreements', '--accept-source-agreements'];
+  } else if (plat === 'darwin') {
+    cmd = 'brew';
+    args = ['install', '--cask', 'microsoft-workiq'];
+  } else {
+    return {
+      ok: false,
+      reason: 'unsupported-platform',
+      output: 'Auto-install is not supported on Linux. See https://gim-home.github.io/kushi/getting-started/install-workiq/',
+    };
+  }
+
+  const res = spawnSync(cmd, args, { encoding: 'utf-8', stdio: 'inherit' });
+  if (res.error || res.status !== 0) {
+    return {
+      ok: false,
+      reason: 'install-failed',
+      output: res.error ? res.error.message : `${cmd} exited with status ${res.status}`,
+    };
+  }
+  return { ok: true, output: `${cmd} ${args.join(' ')} succeeded` };
+}

package/src/main.mjs

@@ -17,6 +17,7 @@ import { copyAssets, copyProjectFiles } from './copy-assets.mjs';
 import { mergeSettings } from './settings.mjs';
 import { mergeCopilotInstructions } from './copilot-instructions.mjs';
 import { seedConfig } from './seed-config.mjs';
+import { checkWorkIQ, tryInstallWorkIQ } from './check-workiq.mjs';
 import {
   resolveProfile,
   makeIncludeFilter,
@@ -71,6 +72,9 @@ export async function main(options = {}) {
   console.log(`  Profile chain: ${resolved.chain.join(' -> ')}`);
   console.log(`  ${resolved.description}\n`);
 
+  // Hard prerequisite: WorkIQ. Kushi cannot pull evidence without it.
+  await preflightWorkIQ(options);
+
   if (target === TARGET_CLAWPILOT) {
     await installClawpilot(options, resolved, version);
   } else {
@@ -290,6 +294,56 @@ async function confirmOverwriteIfExists(fullDest, displayDest, force) {
   }
 }
 
+/**
+ * Hard prerequisite: WorkIQ must be installed and runnable before Kushi will
+ * copy any assets. Kushi's pull-* skills are useless without it. Three modes:
+ *
+ *   --skip-workiq-check  → print a warning and continue (CI / asset-inspection only)
+ *   --with-workiq        → attempt auto-install via winget/brew first, then re-check
+ *   default              → probe; on failure, print install hint and exit 1
+ *
+ * Always prints the resolved WorkIQ path + version on success so users have a
+ * record in their terminal scrollback.
+ */
+async function preflightWorkIQ(options) {
+  if (options.skipWorkiqCheck) {
+    console.warn(
+      '  ⚠️  WorkIQ pre-flight skipped (--skip-workiq-check).',
+    );
+    console.warn(
+      '      Kushi will install, but bootstrap/refresh will block until WorkIQ is present.\n',
+    );
+    return;
+  }
+
+  let result = checkWorkIQ({ workiqPath: options.workiqPath });
+
+  if (!result.ok && options.withWorkiq) {
+    console.log('  WorkIQ not found — attempting auto-install (--with-workiq)…\n');
+    const ins = tryInstallWorkIQ();
+    if (!ins.ok) {
+      console.error(`\n  ✖ Auto-install failed: ${ins.output}\n`);
+      console.error(`    ${result.hint || ''}\n`);
+      process.exit(1);
+    }
+    result = checkWorkIQ({ workiqPath: options.workiqPath });
+  }
+
+  if (!result.ok) {
+    console.error('\n  ✖ WorkIQ is required and was not found.\n');
+    console.error('    Kushi cannot capture evidence without WorkIQ. Install it first:\n');
+    console.error(`      ${result.hint}\n`);
+    console.error('    Then run `workiq ask -q "ping"` to confirm sign-in, and re-run this installer.\n');
+    console.error('    Escape hatches (NOT recommended):');
+    console.error('      • --workiq-path <abs>     supply a non-standard install path');
+    console.error('      • --with-workiq           let the installer try winget/brew');
+    console.error('      • --skip-workiq-check     install assets anyway (bootstrap will still block)\n');
+    process.exit(1);
+  }
+
+  console.log(`  ✓ WorkIQ detected at ${result.path} (${result.version})\n`);
+}
+
 /**
  * Detect whether the cwd looks like a sane install target and, if not, print
  * an actionable message. Three cases: