@sabaiway/agent-workflow-kit 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,30 @@ 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.3.0 — Skill authoring aligned with Anthropic's Skills guidance
+
+Internal refinements to how the kernel itself is written — no change to what gets deployed into a
+project, so **no migration is needed** (`upgrade` reconciles and re-stamps to `1.3.0` with nothing
+to apply). Drawn from [*Lessons from building Claude Code: how we use Skills*](https://claude.com/blog/lessons-from-building-claude-code-how-we-use-skills).
+
+- **Consolidated Gotchas section in `SKILL.md`** — the blog calls the Gotchas section "the highest-signal content in any skill". The non-obvious traps that were scattered through the procedure (harness-added `Co-Authored-By` vs prose, hidden mode never touching `package.json`, `CLAUDE.md` as a symlink not a copy, source-vs-target dir, no-Node → skip enforcement, never overwrite an existing entry point/hook) are now also a single scannable list.
+- **Setup contracts moved to `references/contracts.md`** — progressive disclosure: `SKILL.md` keeps a lean *Setup contracts* pointer (with one-line defaults), and the full Visibility / Communication / Attribution rules load only when needed. Trims the always-loaded `SKILL.md` by ~40 lines without losing any rule.
+- **Setup questions use structured prompts where supported** — the three bootstrap questions (visibility, language, attribution) and the equivalent `upgrade` migration questions now call for a structured multiple-choice prompt (`AskUserQuestion` in Claude Code) where the agent supports it, falling back to prose elsewhere — keeping cross-agent portability (Codex / Cursor / Devin) intact.
+
+## 1.2.0 — Agent attribution is opt-in
+
+**Attribution question at setup**
+
+- **Bootstrap now asks whether the agent may attribute work to itself / AI** — a new step 4 in `/agent-workflow-kit`, alongside the visibility and language questions. The answer is recorded in a new *Attribution* block in the project's `AGENTS.md`, so every agent that reads the entry point honours it.
+- **Default is `off`** — people are routinely surprised to find an AI listed as a repo contributor (a single `Co-Authored-By` trailer is enough to do it, and GitHub keeps it via permanent PR refs). So attribution is **opt-in**, never opt-out.
+- **`off` means nowhere** — no `Co-Authored-By` trailers, no "Generated with …" footers, and no AI/agent/model mentions in code, comments, commit messages, PR titles/bodies, branch names, or docs. The work reads as the human author's.
+- **Two enforcement layers** — the *Attribution* block binds everything an agent writes by hand; the automatic `Co-Authored-By` trailer is added by the **harness**, so for **Claude Code** the kit also sets `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (a doc directive alone can't stop a harness-added trailer). See the *Attribution contract* in `SKILL.md`.
+- **Existing deployments are covered** — `/agent-workflow-kit upgrade` backfills the block on a pre-1.2.0 project, asking (and defaulting to `off`). See `migrations/1.2.0-agent-attribution.md` (idempotent, additive).
+
+**Devin Desktop rebrand (formerly Windsurf)**
+
+- Cognition rebranded Windsurf → **Devin Desktop** (and Cascade → **Devin Local**) on 2026-06-02. Docs, install messages, and labels now say "Devin Desktop"; `windsurf`/`devin` are both kept as keywords. The launcher is unchanged functionally — the `~/.codeium/windsurf/global_workflows/` paths persist, and detection now also recognises a `devin` binary.
+
 ## 1.1.0 — Conversational language + unambiguous install guidance
 
 **Conversational language (dialogue only)**

package/README.md

@@ -7,7 +7,14 @@
 *Bootstrap it once — then every future session reconstructs project context in seconds
 instead of re-reading your whole repo.*
 
-`v1.1.0`  ·  `Claude Code · Codex · Cursor · Windsurf`  ·  `Node ≥ 18`  ·  `kernel-only · English`
+[![npm version](https://img.shields.io/npm/v/@sabaiway/agent-workflow-kit?logo=npm)](https://www.npmjs.com/package/@sabaiway/agent-workflow-kit)
+[![npm downloads](https://img.shields.io/npm/dm/@sabaiway/agent-workflow-kit)](https://www.npmjs.com/package/@sabaiway/agent-workflow-kit)
+[![license](https://img.shields.io/npm/l/@sabaiway/agent-workflow-kit)](./LICENSE)
+[![node](https://img.shields.io/node/v/@sabaiway/agent-workflow-kit)](https://nodejs.org)
+
+`v1.3.0`  ·  `Node ≥ 18`  ·  `kernel-only · English`
+
+**Works with any tool that reads `AGENTS.md`** — Claude Code · Codex · Cursor · Devin Desktop (formerly Windsurf) · GitHub Copilot · Gemini CLI · Cline · Aider · and 20+ more.
 
 </div>
 
@@ -98,7 +105,7 @@ Two visibility modes, chosen at bootstrap: **visible** (committed) or **hidden**
 
 ## 🚀 Install
 
-**One command** installs the kit into `~/.claude/skills/` and wires any Codex / Windsurf you have:
+**One command** installs the kit into `~/.claude/skills/` and wires any Codex / Devin Desktop you have:
 
 ```bash
 npx @sabaiway/agent-workflow-kit init
@@ -110,9 +117,9 @@ Then invoke it **inside a project** — first time vs. already-deployed use diff
 |-------|---------------------------|-----------------------------|
 | **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` |
+| **Devin Desktop** (Windsurf · Devin Local) | `/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>
+<sub>`/agent-workflow-kit` bootstraps a fresh deployment (and asks your **visibility**, **conversational language**, and whether the agent may **attribute work to itself / AI** — default off); `/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`:
 
@@ -134,7 +141,7 @@ cd ~/.claude/skills/agent-workflow-kit
 bash launchers/install-launchers.sh
 ```
 
-`install-launchers.sh` auto-detects Codex **and** Windsurf — it only touches tools you actually
+`install-launchers.sh` auto-detects Codex **and** Devin Desktop — it only touches tools you actually
 have. See [`launchers/README.md`](launchers/README.md) for the full matrix (incl. Cursor / any
 other agent). The manual path works identically but **isn't reflected in install stats** — prefer
 `npx` if you don't mind.
@@ -149,9 +156,9 @@ other agent). The manual path works identically but **isn't reflected in install
 |------|------|
 | `~/.claude/skills/agent-workflow-kit/` | the kit itself (refreshed on every `init`) |
 | `~/.codex/skills/agent-workflow-kit` | a symlink — only if you have Codex |
-| `…/global_workflows/agent-workflow-kit.md` | a managed file — only if you have Windsurf |
+| `…/global_workflows/agent-workflow-kit.md` | a managed file — only if you have Devin Desktop |
 
-Your other Codex skills and Windsurf workflows are never touched. If one of those exact slots
+Your other Codex skills and Devin Desktop workflows are never touched. If one of those exact slots
 already holds a file the kit didn't write, it is **left alone** and you're told — re-run with
 `--force` to replace it (the original is first copied to `*.bak.<timestamp>` and the restore
 command is printed).
@@ -165,7 +172,7 @@ command is printed).
 
 | Command | When | What happens |
 |---------|------|--------------|
-| `/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` | new / empty project | recon → **asks visible-or-hidden** + **conversational language** + **agent attribution** (default off) → 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.
@@ -191,8 +198,8 @@ Enforcement ships as dependency-free **Node** scripts (`node --test`, no package
 ## 🤝 Cross-agent by design
 
 One kit, three front doors — the *output* (`AGENTS.md` + `docs/ai/`) is read natively by
-Codex, Cursor, Windsurf, Copilot, Gemini CLI & 20+ tools, and the *bootstrapper* runs from
-Claude Code, Codex, or Windsurf. No logic is duplicated per tool.
+Codex, Cursor, Devin Desktop, Copilot, Gemini CLI & 20+ tools, and the *bootstrapper* runs from
+Claude Code, Codex, or Devin Desktop. No logic is duplicated per tool.
 
 ---
 
@@ -206,8 +213,9 @@ agent-workflow-kit/
 ├── references/
     ├── templates/   ← AGENTS.md + every docs/ai file
     ├── scripts/     ← caps / archive / index + tests
+    ├── contracts.md ← visibility / language / attribution rules
     └── planning.md  ← plan lifecycle + continuity
-├── launchers/       ← Codex / Windsurf / Cursor entries
+├── launchers/       ← Codex / Devin Desktop / Cursor entries
 └── migrations/      ← per-version upgrade steps
 ```
 

package/SKILL.md

@@ -3,7 +3,7 @@ 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.1.0'
+  version: '1.3.0'
 ---
 
 # agent-workflow-kit
@@ -29,6 +29,8 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
 
 > Bundled sources below (templates, scripts) live in **this skill's own directory** — `${CLAUDE_SKILL_DIR}/` in Claude Code, or the folder containing this `SKILL.md` in Codex / other agents. Use that as the copy/read source; the working directory is the **target project**, not the skill.
 
+> The three setup questions (steps 2–4) are decisions only the user can make and are hard to reverse after a commit. Ask each as a **structured multiple-choice prompt where your agent supports it** (`AskUserQuestion` in Claude Code — one option per choice, recommended one first), otherwise in prose — and **wait for the answer before writing anything**.
+
 1. **Recon (read-only).** Before writing anything:
    - `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` → stack, package manager, scripts.
    - `ls -la` root → `README`, existing `AGENTS.md`/`CLAUDE.md`, CI configs, linter/formatter configs.
@@ -36,15 +38,16 @@ Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to
    - `src/` (or equivalent) 2–3 levels deep → modules, routes/pages, components, services, types.
    - 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. **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.
+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](references/contracts.md#visibility-contract).
+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 5). See [Communication contract](references/contracts.md#communication-contract). This sets the **dialogue** language only — never the files.
+4. **Choose agent attribution — ASK the user explicitly and wait for the answer.** May the agent attribute work to itself / to AI — `Co-Authored-By` trailers, "Generated with …" footers, "AI"/agent/model mentions in code, comments, commit messages, PR titles/bodies, or docs? **Default to `off`** (no agent/AI mention anywhere) unless they opt in — people are routinely surprised to find an AI listed as a repo contributor. Carry the answer into the `{{AGENT_ATTRIBUTION}}` slot of the *Attribution* block when `AGENTS.md` is created (step 5). **If `off` and the project uses Claude Code**, also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent) — the trailer is added by the harness, so a doc directive alone won't stop it. See [Attribution contract](references/contracts.md#attribution-contract).
+5. **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 / Devin Desktop / 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).
+6. **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`).
+7. **Fill templates** per the table below.
+8. **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 9 — follow the cap/archive/index policy manually, or port the scripts to the project's language.
+9. **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.
+10. **Stamp version.** Write the skill's `version` into `docs/ai/.workflow-version` (one semver line).
+11. **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:
 
@@ -62,33 +65,29 @@ 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). 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`.
+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). Any user question a migration raises follows the same rule as bootstrap — **structured multiple-choice where supported** (`AskUserQuestion` in Claude Code), otherwise prose. 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`. If it has no *Attribution* block (pre-1.2.0 deployment), **ask whether the agent may attribute work to itself / AI** and insert the block (defaulting to `off`) — see `migrations/1.2.0-agent-attribution.md`.
 6. Re-stamp `docs/ai/.workflow-version` to the skill's `version`. Report changes; **ask before committing**.
 
 ---
 
-## Visibility contract
-
-The user chooses at bootstrap whether the AI artifacts are visible in the repo or hidden — an **explicit up-front question** (step 2), never an assumed default. The two modes then diverge:
+## Gotchas
 
-- **visible** — artifacts are committed. Wire the project's `package.json` scripts (`docs:check` / `docs:index` / `docs:index:check` / `docs:archive` / `docs:archive:check` / `docs:archive:issues` / `docs:archive:issues:check` / `prepare: node scripts/install-git-hooks.mjs`) and add a minimal `.gitignore` (`docs/plans/`, `.claude/settings.local.json`). This is the canonical model.
-- **hidden** (in-tree) — same files on disk, but the repo "looks normal": append the artifact paths (`AGENTS.md`, `CLAUDE.md`, `docs/ai/`, `docs/plans/`, `scripts/*.mjs` you added, `docs/ai/.workflow-version`) to the global excludes file git **already uses** (`git config --get core.excludesFile`); if none is set, point it at `~/.gitignore_global` (`git config --global core.excludesFile ~/.gitignore_global`) and append there. **Verify `git status` shows the artifacts as ignored** afterwards. **Do not edit `package.json`** — that is a tracked change and would leak; the pre-commit hook (always untracked in `.git/hooks/`) calls the scripts via `node scripts/<x>.mjs` directly.
+The non-obvious traps — scan these before bootstrapping or upgrading. Each is also enforced inline in the procedure above; this is the consolidated high-signal list.
 
-Not in this version: a fully-external hidden mode (artifacts relocated outside the repo tree). Deferred to a later release + migration.
+- **Source vs target directory.** Templates and scripts are read from the skill's own dir (`${CLAUDE_SKILL_DIR}/` in Claude Code, the `SKILL.md` folder elsewhere). The **working directory is the target project** — never write kernel files back into the skill.
+- **The `Co-Authored-By` trailer is added by the harness, not by prose.** When attribution is `off`, a doc directive alone won't stop it — for Claude Code you **must** also set `"includeCoAuthoredBy": false` in the project's `.claude/settings.json` (create it if absent). Other tools: disable their equivalent co-author/footer setting.
+- **Hidden mode must never touch `package.json`.** Editing it is a *tracked* change and leaks the whole system. Hidden mode wires nothing into `package.json`; the pre-commit hook (untracked in `.git/hooks/`) calls `node scripts/<x>.mjs` directly. After hiding, **verify `git status` shows the artifacts as ignored**.
+- **`CLAUDE.md` is a symlink, not a copy.** `ln -s AGENTS.md CLAUDE.md` — single source, no duplication. A copy drifts; a symlink can't.
+- **Never overwrite an existing entry point or hook.** If `AGENTS.md` / `CLAUDE.md` already exist, or the installer reports a pre-existing non-marker git hook, **stop and ask** the user to merge vs replace — don't clobber.
+- **No Node runtime → skip enforcement.** If the project has no Node (recon step 1), skip bootstrap steps 8–9 (scripts + hook) and follow the cap/archive/index policy manually, or port the scripts to the project's language.
+- **Conversational language never translates artifacts.** It governs *dialogue only*. Code, identifiers, paths, commands, log output, abbreviations, and every deployed `docs/ai/` / `AGENTS.md` file stay English. See [Communication contract](references/contracts.md#communication-contract).
+- **Never auto-commit.** Report quality-gate results and wait for explicit approval — in both modes.
 
 ---
 
-## 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*.
+## Setup contracts
 
-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).
+The three setup choices — **visibility** (step 2), **conversational language** (step 3), and **agent attribution** (step 4) — each have a full contract in [`references/contracts.md`](references/contracts.md). Load it when you need the complete rule (e.g. while filling the matching `AGENTS.md` block, or when an `upgrade` migration touches one). Defaults, in brief: visibility = `visible` (committed); language = whatever the user is already writing in; attribution = `off`. Ask each as a structured multiple-choice prompt where supported (`AskUserQuestion` in Claude Code), otherwise in prose.
 
 ---
 
@@ -105,6 +104,7 @@ Default to the language the user is already writing in; confirm rather than assu
 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*.
+12. **Attribution is opt-in.** Honour the *Attribution* block: by default no agent/AI/model mention anywhere (commits, PRs, code, comments, docs), and no `Co-Authored-By` trailer. See *Attribution contract*.
 
 ---
 
@@ -131,9 +131,10 @@ Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
 
 ## References
 
+- [`references/contracts.md`](references/contracts.md) — the three setup contracts (visibility, conversational language, agent attribution) in full; the *Setup contracts* section above points here.
 - [`references/planning.md`](references/planning.md) — plan vocabulary (Plan→Phase→Step→Substep), lifecycle, `queue.md` series-index, mandatory Cleanup, session-continuity heuristic.
 - [`references/templates/`](references/templates/) — stack-agnostic `AGENTS.md`, `agent_rules.md`, and all `docs/ai/` files to deploy.
 - [`references/scripts/`](references/scripts/) — the Node enforcement scripts (caps + staleness + index-freshness gate, 3-tier archive, hook installer) and their unit tests.
 - [`migrations/`](migrations/) — per-version upgrade steps; see `migrations/README.md`.
-- [`launchers/`](launchers/) — run the bootstrapper from non-Claude agents (`SKILL.md` is a native Codex skill; a Windsurf workflow launcher + install script). See `launchers/README.md`.
+- [`launchers/`](launchers/) — run the bootstrapper from non-Claude agents (`SKILL.md` is a native Codex skill; a Devin Desktop workflow launcher + install script). See `launchers/README.md`.
 - [`CHANGELOG.md`](CHANGELOG.md) — version history of this kernel.

package/bin/install.mjs

@@ -4,7 +4,7 @@
 //   npx @sabaiway/agent-workflow-kit init
 //
 // Copies the kit into the canonical skill home (~/.claude/skills/agent-workflow-kit),
-// then runs the cross-agent launcher (auto-detects Codex / Windsurf — only touches tools
+// then runs the cross-agent launcher (auto-detects Codex / Devin Desktop — only touches tools
 // you actually have). Re-running refreshes the skill to this package's version, which is
 // how you upgrade the *skill files* themselves:
 //
@@ -85,14 +85,14 @@ Usage:
 
 Installs/refreshes the kit at ~/.claude/skills/agent-workflow-kit
   (override with --dir <path> or AGENT_WORKFLOW_KIT_DIR), then wires any
-  Codex / Windsurf you have. --no-launchers skips that wiring; --force replaces a
+  Codex / Devin Desktop you have. --no-launchers skips that wiring; --force replaces a
   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, 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.)
+  (Claude Code / Codex / Devin Desktop 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.`);
@@ -123,14 +123,14 @@ const main = async () => {
   // Wire non-Claude agents — best-effort; the launcher only touches tools you have.
   const launcher = resolve(target, 'launchers/install-launchers.sh');
   if (args.noLaunchers) {
-    console.log('[agent-workflow-kit] --no-launchers: skipped Codex/Windsurf wiring.');
+    console.log('[agent-workflow-kit] --no-launchers: skipped Codex/Devin Desktop wiring.');
   } else if (process.platform === 'win32') {
     console.log('[agent-workflow-kit] Windows: skipped POSIX launcher. Claude Code reads the kit natively.');
   } else if (existsSync(launcher)) {
     const launcherArgs = args.force ? [launcher, '--force'] : [launcher];
     const launcherRun = spawnSync('bash', launcherArgs, { stdio: 'inherit' });
     if (launcherRun.status !== 0) {
-      console.warn('[agent-workflow-kit] launcher step skipped/failed — run it by hand if you use Codex/Windsurf:');
+      console.warn('[agent-workflow-kit] launcher step skipped/failed — run it by hand if you use Codex/Devin Desktop:');
       console.warn(`  bash ${tildify(launcher)}`);
     }
   }

package/launchers/README.md

@@ -13,8 +13,8 @@ already — these launchers make the *bootstrapper itself* runnable from non-Cla
 |-------|-----------|---------|--------|
 | **Claude Code** | native skill | already at `~/.claude/skills/agent-workflow-kit/` | `/agent-workflow-kit` |
 | **Codex** | native skill (same `SKILL.md` cross-agent standard) | symlink the kit into a Codex skill scope: `ln -sfn <KIT_DIR> ~/.codex/skills/agent-workflow-kit` (or `~/.agents/skills/`) | Codex `/skills` menu → `agent-workflow-kit` |
-| **Windsurf** | workflow (Cascade doesn't read `SKILL.md`) | `sed "s#<KIT_DIR>#$KIT#g" <KIT_DIR>/launchers/windsurf-workflow.md > ~/.codeium/windsurf/global_workflows/agent-workflow-kit.md` | `/agent-workflow-kit` in Cascade |
-| **Cursor** (bonus) | command/rule | point a `.cursor/commands` entry at `<KIT_DIR>/SKILL.md` (same pattern as the Windsurf launcher) | the command name |
+| **Devin Desktop** (formerly Windsurf) | workflow (Devin Local / Cascade doesn't read `SKILL.md`) | `sed "s#<KIT_DIR>#$KIT#g" <KIT_DIR>/launchers/windsurf-workflow.md > ~/.codeium/windsurf/global_workflows/agent-workflow-kit.md` | `/agent-workflow-kit` in Devin Local |
+| **Cursor** (bonus) | command/rule | point a `.cursor/commands` entry at `<KIT_DIR>/SKILL.md` (same pattern as the Devin Desktop launcher) | the command name |
 | **Any other** | manual | tell the agent: "execute the bootstrap in `<KIT_DIR>/SKILL.md`" | — |
 
 Or run [`install-launchers.sh`](install-launchers.sh) — it auto-detects which of these tools

package/launchers/install-launchers.sh

@@ -6,7 +6,7 @@
 #   - Writes only the kit's OWN namespaced slots:
 #       ~/.codex/skills/agent-workflow-kit                     (a symlink)
 #       ~/.codeium/.../global_workflows/agent-workflow-kit.md  (a managed file)
-#   - NEVER touches your other Codex skills or Windsurf workflows.
+#   - NEVER touches your other Codex skills or Devin Desktop workflows.
 #   - If one of those exact slots already holds a file the kit did NOT write, it is
 #     left untouched and you are told. Re-run with --force to replace it; --force first
 #     backs the file up (.bak.<timestamp>) and prints the command to restore it.
@@ -61,34 +61,36 @@ if command -v codex >/dev/null 2>&1 || [ -d "$HOME/.codex" ]; then
   fi
 fi
 
-# --- Windsurf: needs a workflow launcher (Cascade does not read SKILL.md).
-if command -v windsurf >/dev/null 2>&1 || [ -d "$HOME/.codeium/windsurf" ]; then
+# --- Devin Desktop (formerly Windsurf): needs a workflow launcher (Devin Local, ex-Cascade,
+#     does not read SKILL.md). Cognition rebranded Windsurf -> Devin Desktop on 2026-06-02;
+#     the ~/.codeium/windsurf/ paths are unchanged, so this launcher keeps working as-is.
+if command -v devin >/dev/null 2>&1 || command -v windsurf >/dev/null 2>&1 || [ -d "$HOME/.codeium/windsurf" ]; then
   WF_DIR="$HOME/.codeium/windsurf/global_workflows"
   mkdir -p "$WF_DIR"
   WF="$WF_DIR/agent-workflow-kit.md"
   write_wf() { sed "s#<KIT_DIR>#$KIT_DIR#g" "$KIT_DIR/launchers/windsurf-workflow.md" > "$WF"; }
   if [ ! -e "$WF" ]; then
     write_wf
-    echo "[launchers] Windsurf → wrote $WF (/agent-workflow-kit in Cascade)"
+    echo "[launchers] Devin Desktop → wrote $WF (/agent-workflow-kit in Devin Local / Cascade)"
     installed_any=1
   elif grep -q "$MARKER" "$WF" 2>/dev/null; then
     write_wf
-    echo "[launchers] Windsurf → refreshed $WF (kit-managed)"
+    echo "[launchers] Devin Desktop → refreshed $WF (kit-managed)"
     installed_any=1
   elif [ "$FORCE" -eq 1 ]; then
     backup_and_note "$WF"
     write_wf
-    echo "[launchers] Windsurf → replaced (forced) $WF"
+    echo "[launchers] Devin Desktop → replaced (forced) $WF"
     installed_any=1
   else
-    echo "[launchers] Windsurf ⚠ $WF exists and was not written by the kit — left untouched."
+    echo "[launchers] Devin Desktop ⚠ $WF exists and was not written by the kit — left untouched."
     echo "[launchers]            re-run with --force to replace it (a backup is made first)."
     skipped_any=1
   fi
 fi
 
 if [ "$installed_any" -eq 0 ] && [ "$skipped_any" -eq 0 ]; then
-  echo "[launchers] No Codex/Windsurf install detected. Claude Code (if present) already has the kit natively."
+  echo "[launchers] No Codex/Devin Desktop install detected. Claude Code (if present) already has the kit natively."
 fi
 echo "[launchers] Uninstall later: delete the kit's own slot(s) above (the symlink / the agent-workflow-kit.md file)."
 echo "[launchers] done."

package/launchers/windsurf-workflow.md

@@ -3,7 +3,7 @@ description: Bootstrap or upgrade the agent-workflow-kit AI memory & workflow sy
 ---
 
 <!-- agent-workflow-kit:managed — generated by the kit installer. Safe to overwrite on
-     reinstall; delete this file to remove the Windsurf launcher. -->
+     reinstall; delete this file to remove the Devin Desktop launcher. -->
 
 # agent-workflow-kit
 

package/migrations/1.2.0-agent-attribution.md

@@ -0,0 +1,57 @@
+# Migration 1.2.0-agent-attribution
+
+**From:** versions < 1.2.0   **To:** 1.2.0
+
+## Why
+
+1.2.0 makes **agent attribution opt-in**. The agent may attribute work to itself / AI —
+`Co-Authored-By` trailers, "Generated with …" footers, AI/agent/model mentions in code,
+comments, commit messages, PR titles/bodies, branch names, or docs — **only if the user
+allows it**. Default is `off`. The choice is recorded in an *Attribution* block in the
+project's `AGENTS.md`; pre-1.2.0 deployments have no such block.
+
+A single `Co-Authored-By` trailer is enough to list an AI as a repo contributor, and GitHub
+keeps it permanently via PR refs — so the safe default is "no mention anywhere".
+
+## 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 `## ✍️ Attribution` heading, skip to Verification.
+3. **Ask the user**: may the agent attribute work to itself / AI anywhere (commits, PRs, code,
+   comments, docs)? **Default to `off`** unless they opt in.
+4. Insert this block immediately **after the *Communication language* block** (or, if that is
+   absent, after the opening blockquote — before `## 🧭 Memory Map`), replacing `<off|on>` with
+   the answer from step 3:
+
+   ```markdown
+   ---
+
+   ## ✍️ Attribution
+
+   > **Agent attribution: <off|on>** (chosen at setup).
+   > **off** → never attribute work to the agent, AI, or the model: no `Co-Authored-By` trailers, no "Generated with …" footers, no AI/agent/model mentions in code, comments, commit messages, PR titles/bodies, branch names, or docs. Author everything as the human.
+   > **on** → the agent may add its standard `Co-Authored-By` trailer / footer per your tooling defaults.
+   > Claude Code also honours `includeCoAuthoredBy` in `.claude/settings.json`; this block binds every agent for everything written by hand.
+   ```
+
+5. **If the answer is `off` and the project uses Claude Code**, also set the harness flag so the
+   automatic trailer stops (a doc directive cannot stop a harness-added trailer):
+   - Ensure `.claude/settings.json` exists in the project root; create it as `{}` if absent.
+   - Set `"includeCoAuthoredBy": false` (merge into the existing JSON; do not clobber other keys).
+   - For other tools, disable their equivalent co-author / footer setting if present.
+6. Keep `AGENTS.md` within its ≤100-line budget (the block is ~7 lines; it fits). Do **not**
+   retroactively rewrite existing git history here — that is a separate, deliberate operation.
+
+## Verification
+
+- `AGENTS.md` has exactly one `## ✍️ Attribution` block, with `off` or `on` (no leftover
+  `{{AGENT_ATTRIBUTION}}` placeholder).
+- If `off` + Claude Code: `.claude/settings.json` contains `"includeCoAuthoredBy": false`, and
+  the file is valid JSON (`node -e "JSON.parse(require('fs').readFileSync('.claude/settings.json'))"`).
+- The docs cap-validator is still green (`node scripts/check-docs-size.mjs` for Node projects).
+
+## Rollback
+
+Delete the inserted `## ✍️ Attribution` block (and its trailing `---`) from `AGENTS.md`, and
+remove the `includeCoAuthoredBy` key from `.claude/settings.json` if you added it. No other
+files were changed.

package/package.json

@@ -1,16 +1,27 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "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.",
+  "version": "1.3.0",
+  "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",
+    "ai-coding",
+    "coding-agent",
+    "llm",
+    "ai-tools",
     "claude-code",
     "codex",
     "cursor",
     "windsurf",
+    "devin",
+    "github-copilot",
+    "gemini-cli",
+    "cline",
+    "aider",
     "agents-md",
+    "agent-memory",
+    "context-engineering",
+    "cross-agent",
     "workflow",
-    "skill",
     "memory",
     "developer-tools"
   ],

package/references/contracts.md

@@ -0,0 +1,62 @@
+# Setup contracts
+
+The three choices the bootstrap makes with the user — **visibility**, **conversational
+language**, and **agent attribution** — each have a contract below. `SKILL.md` links here so the
+main procedure stays lean; load this file when you need the full rule for a contract (e.g. while
+filling the matching `AGENTS.md` block, or when an `upgrade` migration touches it).
+
+Ask each as a **structured multiple-choice prompt where your agent supports it** (`AskUserQuestion`
+in Claude Code), otherwise in prose — and always wait for the answer before writing.
+
+---
+
+## Visibility contract
+
+The user chooses at bootstrap whether the AI artifacts are visible in the repo or hidden — an
+**explicit up-front question** (bootstrap step 2), never an assumed default. The two modes then
+diverge:
+
+- **visible** — artifacts are committed. Wire the project's `package.json` scripts (`docs:check` / `docs:index` / `docs:index:check` / `docs:archive` / `docs:archive:check` / `docs:archive:issues` / `docs:archive:issues:check` / `prepare: node scripts/install-git-hooks.mjs`) and add a minimal `.gitignore` (`docs/plans/`, `.claude/settings.local.json`). This is the canonical model.
+- **hidden** (in-tree) — same files on disk, but the repo "looks normal": append the artifact paths (`AGENTS.md`, `CLAUDE.md`, `docs/ai/`, `docs/plans/`, `scripts/*.mjs` you added, `docs/ai/.workflow-version`) to the global excludes file git **already uses** (`git config --get core.excludesFile`); if none is set, point it at `~/.gitignore_global` (`git config --global core.excludesFile ~/.gitignore_global`) and append there. **Verify `git status` shows the artifacts as ignored** afterwards. **Do not edit `package.json`** — that is a tracked change and would leak; the pre-commit hook (always untracked in `.git/hooks/`) calls the scripts via `node scripts/<x>.mjs` directly.
+
+Not in this version: a fully-external hidden mode (artifacts relocated outside the repo tree).
+Deferred to a later release + migration.
+
+---
+
+## 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).
+
+---
+
+## Attribution contract
+
+The user chooses at bootstrap (step 4) whether the agent may **attribute work to itself or to AI**.
+The choice is recorded in the *Attribution* block of the project's `AGENTS.md`, so every agent that
+reads the entry point honours it. **Default is `off`** — people are routinely surprised to find an
+AI listed as a repo contributor (a `Co-Authored-By` trailer is enough to do it), so opt-in, never
+opt-out.
+
+When attribution is **`off`**, no mention of the agent, AI, or the model appears **anywhere**:
+
+- **No `Co-Authored-By` trailers** and **no "Generated with …" footers** on commits or PRs.
+- **No AI/agent/model references** in code, comments, commit messages, PR titles/bodies, branch names, or `docs/` prose. The work reads as the human author's.
+- **Two enforcement layers** — the *Attribution* block binds everything an agent writes **by hand**; the automatic `Co-Authored-By` trailer is added by the **harness**, not the prose, so for **Claude Code** the kit also sets `"includeCoAuthoredBy": false` in the project's `.claude/settings.json`. Other tools: disable their equivalent co-author/footer setting if present.
+
+When **`on`**, the agent may add its standard trailer / footer per the user's tooling defaults. This
+block is about *attribution*, not authorship of the actual changes — quality, tests, and the "ask
+before commit" rule are unchanged either way.
+
+On `upgrade`, a pre-1.2.0 deployment with no block gets one (the agent asks, defaulting to `off`).

package/references/templates/AGENTS.md

@@ -2,7 +2,7 @@
 
 > **Execution protocol for AI agents working on this project.**
 > **This file is your entry point. Read it first, then follow the Memory Map.**
-> `AGENTS.md` is the cross-agent standard — Codex / Cursor / Windsurf / Copilot read it natively. Tool-specific aliases (e.g. `CLAUDE.md` for Claude Code) are symlinks to this file — single source, no duplication.
+> `AGENTS.md` is the cross-agent standard — Codex / Cursor / Devin Desktop / Copilot read it natively. Tool-specific aliases (e.g. `CLAUDE.md` for Claude Code) are symlinks to this file — single source, no duplication.
 
 ---
 
@@ -14,6 +14,15 @@
 
 ---
 
+## ✍️ Attribution
+
+> **Agent attribution: {{AGENT_ATTRIBUTION}}** (chosen at setup).
+> **off** → never attribute work to the agent, AI, or the model: no `Co-Authored-By` trailers, no "Generated with …" footers, no AI/agent/model mentions in code, comments, commit messages, PR titles/bodies, branch names, or docs. Author everything as the human.
+> **on** → the agent may add its standard `Co-Authored-By` trailer / footer per your tooling defaults.
+> Claude Code also honours `includeCoAuthoredBy` in `.claude/settings.json`; this block binds every agent for everything written by hand.
+
+---
+
 ## 🧭 Memory Map
 
 All project knowledge lives in `docs/ai/`. Layered, lazy-loaded context: