@sabaiway/agent-workflow-kit 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 1.1.0 — Conversational language + unambiguous install guidance
+
+**Conversational language (dialogue only)**
+
+- **Bootstrap now asks the conversational language** — a new step 3 in `/agent-workflow-kit`, alongside the visibility question. The agent records the answer in a new *Communication language* block in the project's `AGENTS.md`, so every agent that reads the entry point talks to the user in that language and stops drifting between languages mid-session.
+- **Dialogue-only scope, by design** — the choice governs what the agent writes *for the user to read* (questions, explanations, summaries, status). Code, identifiers, file paths, shell commands, log output, and abbreviations stay in their source language; the deployed `docs/ai/` files and `AGENTS.md` stay English (the kernel stays English-only for cross-agent / cross-team portability). See the *Communication contract* in `SKILL.md`.
+- **Existing deployments are covered** — `/agent-workflow-kit upgrade` backfills the block on a pre-1.1.0 project, asking the user their language. See `migrations/1.1.0-communication-language.md` (idempotent, additive).
+
+**Clearer install / upgrade guidance**
+
+- **`init` now distinguishes a fresh kit install from a refresh** — prints `installed v…` the first time and `updated the kit to v…` on re-run, so it's obvious the command targets the *kit*, not a project.
+- **The "Next" message is unambiguous about which path to take** — it spells out *first time in a project* (`/agent-workflow-kit`) vs *project already has the kit* (`/agent-workflow-kit upgrade`), and reminds that re-running `npx … init` updates the kit's own files. `--help` and the README install table say the same. Resolves the prior single-line hint that read the same for first-timers and upgraders.
+
 ## 1.0.0 — Initial public release
 
 First public release of `@sabaiway/agent-workflow-kit`. The kernel — distilled from a battle-tested, multi-year-verified reference implementation — ships on npm + GitHub so it installs (and self-upgrades) in one command. Adoption is countable from the registry's public per-version download numbers — no telemetry, no phone-home.

package/README.md

@@ -7,7 +7,7 @@
 *Bootstrap it once — then every future session reconstructs project context in seconds
 instead of re-reading your whole repo.*
 
-`v1.0.0`  ·  `Claude Code · Codex · Cursor · Windsurf`  ·  `Node ≥ 18`  ·  `kernel-only · English`
+`v1.1.0`  ·  `Claude Code · Codex · Cursor · Windsurf`  ·  `Node ≥ 18`  ·  `kernel-only · English`
 
 </div>
 
@@ -104,13 +104,15 @@ Two visibility modes, chosen at bootstrap: **visible** (committed) or **hidden**
 npx @sabaiway/agent-workflow-kit init
 ```
 
-Then invoke it in any project:
+Then invoke it **inside a project** — first time vs. already-deployed use different sub-commands:
 
-| Agent | Invoke |
-|-------|--------|
-| **Claude Code** | `/agent-workflow-kit` |
-| **Codex** | `/skills` menu → `agent-workflow-kit` |
-| **Windsurf** (Cascade) | `/agent-workflow-kit` |
+| Agent | First time in the project | Project already has the kit |
+|-------|---------------------------|-----------------------------|
+| **Claude Code** | `/agent-workflow-kit` | `/agent-workflow-kit upgrade` |
+| **Codex** | `/skills` menu → `agent-workflow-kit` | …→ `agent-workflow-kit upgrade` |
+| **Windsurf** (Cascade) | `/agent-workflow-kit` | `/agent-workflow-kit upgrade` |
+
+<sub>`/agent-workflow-kit` bootstraps a fresh deployment (and asks your **visibility** and **conversational language**); `/agent-workflow-kit upgrade` migrates an existing one to the kit's current version. The `npx … init` above is a third, separate thing — it updates the **kit itself**, not any project.</sub>
 
 **Upgrade the kit itself** later — same command with `@latest`:
 
@@ -163,7 +165,7 @@ command is printed).
 
 | Command | When | What happens |
 |---------|------|--------------|
-| `/agent-workflow-kit` | new / empty project | recon → **asks visible-or-hidden** → deploys `AGENTS.md` + `docs/ai/` filled with real recon data → installs enforcement → **asks before committing** |
+| `/agent-workflow-kit` | new / empty project | recon → **asks visible-or-hidden** + **conversational language** → deploys `AGENTS.md` + `docs/ai/` filled with real recon data → installs enforcement → **asks before committing** |
 | `/agent-workflow-kit upgrade` | existing deployment | reads `docs/ai/.workflow-version`, shows the changelog diff, applies migrations, re-stamps |
 
 It **never auto-commits** and **never overwrites** an existing `AGENTS.md` without asking.

package/SKILL.md

@@ -3,14 +3,16 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow".
 disable-model-invocation: true
 metadata:
-  version: '1.0.0'
+  version: '1.1.0'
 ---
 
 # agent-workflow-kit
 
 Deploys a **portable AI-agent memory-and-workflow system** into a project, and upgrades it as the kernel evolves. After it runs, any future agent (including a fresh session of yourself) can reconstruct project context in ~60 seconds, find the current task, and avoid repeating past mistakes.
 
-The kernel is **stack-agnostic workflow** — `docs/ai/` structure, entry-point doc, session protocols, plan lifecycle, frontmatter caps, 3-tier archive, index-freshness gate. Enforcement ships as **Node `.mjs` scripts** (the reference implementation; non-Node stacks follow the same policy manually). This skill is **English-only**.
+The kernel is **stack-agnostic workflow** — `docs/ai/` structure, entry-point doc, session protocols, plan lifecycle, frontmatter caps, 3-tier archive, index-freshness gate. Enforcement ships as **Node `.mjs` scripts** (the reference implementation; non-Node stacks follow the same policy manually).
+
+The kernel **artifacts** (this skill, the templates, the deployed `docs/ai/` files) are **English-only** — for cross-agent and cross-team portability. That is separate from the **conversational language**: the language the agent *talks to the user* in (questions, explanations, summaries, status). That is chosen once at bootstrap (step 3), recorded in the project's `AGENTS.md`, and applied to dialogue only — it never translates file contents, code, identifiers, paths, commands, or abbreviations.
 
 This kernel is distilled from a canonical, battle-tested reference implementation. The skill is the single source of truth — projects deploy from it and upgrade against it.
 
@@ -35,13 +37,14 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
    - Tests (framework, location, E2E?) and linter rules.
    - Record: stack, package manager, daily commands (`dev`/`test`/`lint`/`type-check`), routes/pages, architecture layers.
 2. **Choose visibility — ASK the user explicitly and wait for the answer, before writing anything.** This decides what gets tracked and is hard to reverse after a commit, so never assume the default silently: `visible` (committed — canonical, recommended) or `hidden` (in-tree, hidden via `~/.gitignore_global`). See *Visibility contract*.
-3. **Entry-point doc.** If `AGENTS.md` / `CLAUDE.md` already exist (step-1 recon), do **not** overwrite — show the user and ask whether to merge or replace. Otherwise create `AGENTS.md` (the cross-agent standard — Codex / Cursor / Windsurf / Copilot read it natively) from `${CLAUDE_SKILL_DIR}/references/templates/AGENTS.md`, and symlink `CLAUDE.md -> AGENTS.md` (`ln -s AGENTS.md CLAUDE.md`) for Claude Code — single source, no duplication. For nested context, add a subdir `AGENTS.md` (+ a `CLAUDE.md` symlink beside it for Claude Code).
-4. **Deploy `docs/ai/`.** Create the 11 files + `pages/` from `${CLAUDE_SKILL_DIR}/references/templates/`. Keep each file's frontmatter (`type / lastUpdated / scope / staleAfter / owner / maxLines`).
-5. **Fill templates** per the table below.
-6. **Install enforcement (Node projects).** Copy `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs` (+ `*.test.mjs`) into the project's `scripts/`. They self-configure (project name from `package.json`, hierarchical/on-demand sections auto-discovered). **If the project has no Node runtime** (step-1 recon), skip this step and the hook in step 7 — follow the cap/archive/index policy manually, or port the scripts to the project's language.
-7. **Wire / hide** per visibility (see contract). Install the pre-commit hook (Node projects): `node scripts/install-git-hooks.mjs`. If the installer reports a pre-existing non-marker hook, stop and ask the user to merge it manually rather than overwriting.
-8. **Stamp version.** Write the skill's `version` into `docs/ai/.workflow-version` (one semver line).
-9. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then **ask before committing** — never auto-commit.
+3. **Choose conversational language — ASK the user explicitly and wait for the answer.** Which language should the agent *talk to them* in — questions, explanations, summaries, status updates? Offer the language they're already writing in as the default. Carry the answer into the `{{COMM_LANGUAGE}}` slot of the *Communication language* block when `AGENTS.md` is created (step 4). See *Communication contract*. This sets the **dialogue** language only — never the files.
+4. **Entry-point doc.** If `AGENTS.md` / `CLAUDE.md` already exist (step-1 recon), do **not** overwrite — show the user and ask whether to merge or replace. Otherwise create `AGENTS.md` (the cross-agent standard — Codex / Cursor / Windsurf / Copilot read it natively) from `${CLAUDE_SKILL_DIR}/references/templates/AGENTS.md`, and symlink `CLAUDE.md -> AGENTS.md` (`ln -s AGENTS.md CLAUDE.md`) for Claude Code — single source, no duplication. For nested context, add a subdir `AGENTS.md` (+ a `CLAUDE.md` symlink beside it for Claude Code).
+5. **Deploy `docs/ai/`.** Create the 11 files + `pages/` from `${CLAUDE_SKILL_DIR}/references/templates/`. Keep each file's frontmatter (`type / lastUpdated / scope / staleAfter / owner / maxLines`).
+6. **Fill templates** per the table below.
+7. **Install enforcement (Node projects).** Copy `${CLAUDE_SKILL_DIR}/references/scripts/*.mjs` (+ `*.test.mjs`) into the project's `scripts/`. They self-configure (project name from `package.json`, hierarchical/on-demand sections auto-discovered). **If the project has no Node runtime** (step-1 recon), skip this step and the hook in step 8 — follow the cap/archive/index policy manually, or port the scripts to the project's language.
+8. **Wire / hide** per visibility (see contract). Install the pre-commit hook (Node projects): `node scripts/install-git-hooks.mjs`. If the installer reports a pre-existing non-marker hook, stop and ask the user to merge it manually rather than overwriting.
+9. **Stamp version.** Write the skill's `version` into `docs/ai/.workflow-version` (one semver line).
+10. **Report & ask.** Show `tree docs/ai/`, 2–3 lines on what was filled with real data vs left as TODO, then **ask before committing** — never auto-commit.
 
 Fill strategy:
 
@@ -59,7 +62,7 @@ Fill strategy:
 2. Compare to this skill's `metadata.version` (frontmatter). If equal → report "up to date" and stop.
 3. Show the relevant `${CLAUDE_SKILL_DIR}/CHANGELOG.md` diff (entries newer than the project's stamp).
 4. Apply `${CLAUDE_SKILL_DIR}/migrations/<version>-<slug>.md` in **semver order**, only those newer than the project's stamp. Migrations are **idempotent** — safe to re-run.
-5. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay).
+5. Reconcile drift: add any kernel files/scripts the project is missing; never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs stay). If `AGENTS.md` has no *Communication language* block (pre-1.1.0 deployment), **ask the user their conversational language** and insert the block — see `migrations/1.1.0-communication-language.md`.
 6. Re-stamp `docs/ai/.workflow-version` to the skill's `version`. Report changes; **ask before committing**.
 
 ---
@@ -75,6 +78,20 @@ Not in this version: a fully-external hidden mode (artifacts relocated outside t
 
 ---
 
+## Communication contract
+
+The user chooses at bootstrap (step 3) which language the agent **talks to them** in. The choice is recorded in the *Communication language* block of the project's `AGENTS.md`, so every agent that reads the entry point honours it — and stops drifting between languages mid-session.
+
+Scope — **dialogue only**:
+
+- **In the chosen language** — everything the agent produces *for the user to read*: questions, explanations, plan summaries, status updates, commit-message prose if asked, review notes.
+- **Always in their source language (usually English)** — code, identifiers, file paths, shell commands, log/console output, error strings, config keys, and abbreviations/acronyms. Translating these breaks copy-paste, search, and tooling.
+- **Files stay English** — the deployed `docs/ai/` files, `AGENTS.md`, and this kernel are English-only regardless of the chosen language (cross-agent / cross-team portability). The conversational language is about the *chat*, not the *artifacts*.
+
+Default to the language the user is already writing in; confirm rather than assume. On `upgrade`, a pre-1.1.0 deployment with no block gets one (the agent asks).
+
+---
+
 ## System principles (encode these into the project's `AGENTS.md`)
 
 1. **Single entry point.** `AGENTS.md` is the only entry point (tool aliases like `CLAUDE.md` symlink to it); it never bloats — details live in `docs/ai/`.
@@ -87,6 +104,7 @@ Not in this version: a fully-external hidden mode (artifacts relocated outside t
 8. **Hard Constraints are tool-enforced.** Style rules live in linter/type-checker configs, not prose.
 9. **Ask before commit.** The agent reports quality-gate results and waits for explicit approval; it never auto-commits.
 10. **Honest `known_issues.md`.** Every bug with a workaround gets Impact + Plan so it isn't re-discovered later.
+11. **One conversational language.** Talk to the user in the language chosen at bootstrap; keep code, paths, commands, and abbreviations in their source language. See *Communication contract*.
 
 ---
 

package/bin/install.mjs

@@ -89,9 +89,13 @@ Installs/refreshes the kit at ~/.claude/skills/agent-workflow-kit
   pre-existing non-kit launcher file (backed up first). init is additive — it never
   deletes your settings.
 
-After install, invoke the skill in your agent:
-  Claude Code / Codex:  /agent-workflow-kit
-  Windsurf Cascade:     /agent-workflow-kit`);
+After install, invoke the skill in your agent, inside a project:
+  first time in the project  ->  /agent-workflow-kit
+  project already has it     ->  /agent-workflow-kit upgrade
+  (Claude Code / Codex / Windsurf Cascade all use the same /agent-workflow-kit.)
+
+Re-running this npx command updates the kit's own files; /agent-workflow-kit
+upgrade then migrates a project's deployment to that version.`);
 };
 
 const main = async () => {
@@ -107,13 +111,14 @@ const main = async () => {
   }
 
   const target = resolveTarget(args.dir);
+  const wasPresent = existsSync(resolve(target, 'SKILL.md'));
   await mkdir(target, { recursive: true });
   await Promise.all(
     PAYLOAD.filter((entry) => existsSync(resolve(PKG_ROOT, entry))).map((entry) =>
       copyRecursive(resolve(PKG_ROOT, entry), resolve(target, entry)),
     ),
   );
-  console.log(`[agent-workflow-kit] installed v${version} -> ${tildify(target)}`);
+  console.log(`[agent-workflow-kit] ${wasPresent ? 'updated the kit to' : 'installed'} v${version} -> ${tildify(target)}`);
 
   // Wire non-Claude agents — best-effort; the launcher only touches tools you have.
   const launcher = resolve(target, 'launchers/install-launchers.sh');
@@ -130,7 +135,16 @@ const main = async () => {
     }
   }
 
-  console.log('\nNext: open your agent and run  /agent-workflow-kit');
+  // This command (de)installed the *kit* globally. Deploying it into a project is a
+  // separate, in-agent step — and which sub-command depends on whether that project
+  // already has the kit. Spell both out so it's unambiguous (see README "Use").
+  console.log(`
+Next — open your agent inside a project and run the skill:
+  • first time in this project  ->  /agent-workflow-kit
+  • project already has the kit  ->  /agent-workflow-kit upgrade
+
+This command only installs/updates the kit itself (in ${tildify(target)}).
+To update the kit later, re-run:  npx @sabaiway/agent-workflow-kit@latest init`);
 };
 
 main().catch((err) => {

package/migrations/1.1.0-communication-language.md

@@ -0,0 +1,51 @@
+# Migration 1.1.0-communication-language
+
+**From:** versions < 1.1.0   **To:** 1.1.0
+
+## Why
+
+1.1.0 adds a **conversational language** setting: the language the agent *talks to the
+user* in (questions, explanations, summaries, status). It is recorded in a *Communication
+language* block in the project's `AGENTS.md` so every agent that reads the entry point
+honours it instead of drifting between languages. Pre-1.1.0 deployments have no such block.
+
+Scope is **dialogue only** — code, identifiers, paths, commands, log output, and
+abbreviations stay in their source language, and the `docs/ai/` files + `AGENTS.md` stay
+English (the kernel is English-only). This migration changes *one* doc block, nothing else.
+
+## Steps
+
+1. Open the project's entry point `AGENTS.md` (the real file; `CLAUDE.md` is a symlink to it).
+2. **Idempotency check** — if it already contains a `## 🗣️ Communication language` heading,
+   this migration is done; skip to Verification.
+3. **Ask the user** which language the agent should converse in (questions, explanations,
+   summaries, status). Offer the language they're already writing in as the default.
+4. Insert this block immediately **after the opening blockquote** (before `## 🧭 Memory Map`),
+   replacing `<their language>` with the answer from step 3:
+
+   ```markdown
+   ---
+
+   ## 🗣️ Communication language
+
+   > **Talk to the user in <their language>** — every question, explanation, summary, and status update.
+   > Keep code, identifiers, file paths, shell commands, log output, and abbreviations in their **source language** (usually English) — translating them breaks copy-paste, search, and tooling.
+   > This sets the **dialogue** language only. The files in `docs/ai/` and this entry point stay in English (kernel is English-only, for cross-agent / cross-team portability).
+   ```
+
+5. Keep `AGENTS.md` within its ≤100-line budget (the block is ~6 lines; it fits). Do **not**
+   touch any other section, and do **not** translate existing file contents.
+
+## Verification
+
+- `AGENTS.md` has exactly one `## 🗣️ Communication language` block, with a real language in
+  place of `<their language>` (no leftover `{{COMM_LANGUAGE}}` placeholder).
+- The docs cap-validator is still green (`node scripts/check-docs-size.mjs` for Node projects)
+  — the entry point did not bust its line budget.
+- From now on the agent's replies are in the chosen language; paths/commands/identifiers
+  remain English.
+
+## Rollback
+
+Delete the inserted `## 🗣️ Communication language` block (and its trailing `---`) from
+`AGENTS.md`. No other files were changed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "A portable, cross-agent memory & workflow system for AI coding agents. One command deploys docs/ai + an entry-point AGENTS.md + cap/archive/index enforcement into any project.",
   "keywords": [
     "ai-agents",

package/references/templates/AGENTS.md

@@ -6,6 +6,14 @@
 
 ---
 
+## 🗣️ Communication language
+
+> **Talk to the user in {{COMM_LANGUAGE}}** — every question, explanation, summary, and status update.
+> Keep code, identifiers, file paths, shell commands, log output, and abbreviations in their **source language** (usually English) — translating them breaks copy-paste, search, and tooling.
+> This sets the **dialogue** language only. The files in `docs/ai/` and this entry point stay in English (kernel is English-only, for cross-agent / cross-team portability).
+
+---
+
 ## 🧭 Memory Map
 
 All project knowledge lives in `docs/ai/`. Layered, lazy-loaded context: