@sabaiway/agent-workflow-kit 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,32 @@
+# Changelog — agent-workflow-kit
+
+Semantically versioned ([semver](https://semver.org)), newest first. The `version:` in `SKILL.md`
+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.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.
+
+**The kernel — a portable AI-agent memory & workflow system**
+
+- **Entry point** — `AGENTS.md` (cross-agent open standard: Codex / Cursor / Windsurf / Copilot read it natively) + `CLAUDE.md` symlink for Claude Code; concise Memory Map, protocols delegated to `agent_rules.md`.
+- **`docs/ai/` structure** — `handover`, `active_plan`, `current_state`, `technical_specification`, `architecture`, `known_issues`, `decisions`, `changelog`, `env_commands`, `tech_reference`, `agent_rules` + `pages/` (`index`, `shared-patterns`, `PAGE_TEMPLATE`). Layered lazy-loading: always-loaded / on-demand / hierarchical subdir `AGENTS.md` / archive.
+- **Frontmatter caps** — every file declares `maxLines` + `staleAfter`; the validator errors over cap, warns when stale.
+- **Index-freshness gate** — `check-docs-size.mjs --check-index` regenerates the navigator in memory and diffs it against the on-disk `index.md`, using the on-disk header date so a day-rollover is not a false positive.
+- **3-tier rolling archive** — `archive-changelog.mjs` (HOT changelog → WARM `recent.md` → COLD `YYYY-MM.md`) + condensed-index META; `archive-issues.mjs` for resolved issues.
+- **Pre-commit hook** — `install-git-hooks.mjs` wires caps + index freshness + archive checks + the `scripts/` test suite; package-manager-agnostic (`node` directly).
+- **Tests** — rotation/cap pure functions covered by `*.test.mjs`, runnable under `node --test` via a zero-dependency `expect` shim.
+- **Planning** — `references/planning.md`: Plan→Phase→Step→Substep, ephemeral plan lifecycle, `queue.md` series-index, mandatory Cleanup, plan-then-execute split + session-continuity heuristic.
+- **Two modes** — `/agent-workflow-kit` (new) and `/agent-workflow-kit upgrade` (existing).
+- **Cross-agent invocation** — `launchers/`: `SKILL.md` is a native Codex skill (same cross-agent standard); a Windsurf workflow launcher + `install-launchers.sh` let Codex/Windsurf users run the bootstrapper too, not just Claude Code.
+- **Visibility** — `visible` (committed) and `hidden` (in-tree, hidden via `~/.gitignore_global`).
+
+**Distribution & install**
+
+- **`npx @sabaiway/agent-workflow-kit init`** — `bin/install.mjs` (dependency-free, Node ≥ 18) copies the kit into `~/.claude/skills/agent-workflow-kit/` and runs `launchers/install-launchers.sh` (auto-detects Codex / Windsurf). `--dir` / `AGENT_WORKFLOW_KIT_DIR` override the target; `--no-launchers` skips the wiring.
+- **Self-upgrade** — `npx @sabaiway/agent-workflow-kit@latest init` refreshes the kit's own files; distinct from `/agent-workflow-kit upgrade`, which migrates a project's `docs/ai/` deployment.
+- **Manual install still supported** — `git clone` + `install-launchers.sh`; only the npx path is reflected in install stats.
+- **Additive & safe** — the installer writes only the kit's own namespaced slots and never deletes your settings. A pre-existing non-kit Codex link or Windsurf workflow is left untouched unless you pass `--force`, which backs it up to `*.bak.<timestamp>` and prints a restore command first. Windsurf launcher files carry an `agent-workflow-kit:managed` marker so the installer can tell its own file from yours.
+
+**Known limitation** — condensed-index grows O(total archived entries); shard per-year on a multi-year horizon (noted in `archive-changelog.mjs`). Fully-external hidden mode is deferred to a later release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sabaiway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,216 @@
+<div align="center">
+
+# 🧠 agent-workflow-kit
+
+**A portable, cross-agent memory & workflow system for AI coding agents.**
+
+*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`
+
+</div>
+
+---
+
+## ❓ The problem
+
+AI coding agents are **stateless between sessions**. Every new chat starts from zero:
+
+```
+── new session, no kit ───────────────────
+    ▶ "continue the feature"
+        ↓
+    reads 18 files… greps ×6…
+    re-infers the architecture…
+    re-asks a decision you settled…
+        ↓  (15k–40k tokens later)
+    …finally starts working
+──────────────────────────────────────────
+→ re-derives what it knew yesterday, and
+  re-introduces a bug you already fixed
+```
+
+No durable handover ⇒ **drift between sessions, repeated mistakes, ballooning token cost.**
+
+---
+
+## ⚡ Without vs. With
+
+The kit gives the agent a small, structured **memory** it reads at the start of every
+session — instead of rebuilding context from source each time.
+
+```
+WITHOUT the kit · cold start, cost grows
+  s1  ~30k tok  ██████████
+  s2  ~28k tok  █████████    ← repeats a fixed bug
+  s3  ~34k tok  ███████████  ← drift
+
+WITH the kit · boots from memory, cost flat
+  s1   ~4k tok  █
+  s2   ~4k tok  █            ← no drift
+  s3   ~5k tok  █            ← decisions kept
+```
+
+<sub>*Illustrative — exact numbers scale with repo size. The point is the **shape**: cold re-reads that grow vs. a flat, cache-warm boot.*</sub>
+
+| | 🚫 Without | ✅ With `agent-workflow-kit` |
+|---|---|---|
+| **Session boot** | re-read source + grep to rebuild context | read 4 small docs, ~constant |
+| **Boot cost** | grows with repo, paid every session | flat; stable layer stays prompt-cache-warm |
+| **Cross-session memory** | none | `handover` (where we left off) |
+| **Past decisions** | re-litigated | `decisions.md` (ADRs) — settled once |
+| **Known bugs** | re-discovered | `known_issues.md` — impact + workaround |
+| **Doc growth** | unbounded sprawl | frontmatter caps + 3-tier rolling archive |
+| **Drift** | docs ≠ code over time | pre-commit gate keeps them honest |
+
+---
+
+## 📦 What it deploys into your project
+
+```
+your-repo/
+├── AGENTS.md              ← single entry point
+├── CLAUDE.md → AGENTS.md  ← symlink, for Claude Code
+└── docs/ai/
+    ├── index.md           ← auto-generated navigator
+    ├── handover.md        ← where we left off (read first)
+    ├── active_plan.md     ← current task
+    ├── agent_rules.md     ← session protocols + self-review
+    ├── current_state.md   ← snapshot of the codebase now
+    ├── architecture.md    ← layers & boundaries
+    ├── technical_specification.md
+    ├── decisions.md       ← ADRs — settled once
+    ├── known_issues.md    ← bugs + workarounds
+    ├── changelog.md       ← rolling, then archived
+    ├── env_commands.md    ← daily commands
+    ├── tech_reference.md  ← configs & patterns
+    ├── pages/             ← one spec per page/route
+    └── history/           ← archive (HOT→WARM→COLD)
+  + scripts/               ← caps · index · archive (Node)
+  + pre-commit hook        ← keeps it all honest
+```
+
+Two visibility modes, chosen at bootstrap: **visible** (committed) or **hidden**
+(in-tree but git-ignored, so the repo "looks normal").
+
+---
+
+## 🚀 Install
+
+**One command** installs the kit into `~/.claude/skills/` and wires any Codex / Windsurf you have:
+
+```bash
+npx @sabaiway/agent-workflow-kit init
+```
+
+Then invoke it in any project:
+
+| Agent | Invoke |
+|-------|--------|
+| **Claude Code** | `/agent-workflow-kit` |
+| **Codex** | `/skills` menu → `agent-workflow-kit` |
+| **Windsurf** (Cascade) | `/agent-workflow-kit` |
+
+**Upgrade the kit itself** later — same command with `@latest`:
+
+```bash
+npx @sabaiway/agent-workflow-kit@latest init
+```
+
+<sub>That refreshes the **kit's own files** — distinct from `/agent-workflow-kit upgrade`, which migrates a **project's** deployment (see **Use** below).</sub>
+
+<details>
+<summary><b>Manual install</b> — no <code>npx</code></summary>
+
+The kit is a single self-contained folder. Clone it into a skill scope yourself, then run the launcher:
+
+```bash
+git clone https://github.com/sabaiway/agent-workflow-kit \
+  ~/.claude/skills/agent-workflow-kit
+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
+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.
+</details>
+
+<details>
+<summary><b>What <code>init</code> touches — and how to undo it</b></summary>
+
+`init` is **additive — it never deletes your settings.** It writes only its own namespaced slots:
+
+| Path | What |
+|------|------|
+| `~/.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 |
+
+Your other Codex skills and Windsurf 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).
+
+**Uninstall:** delete the slots above (the kit folder, the symlink, the workflow file).
+</details>
+
+---
+
+## 🛠️ Use
+
+| 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 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.
+
+> **Two kinds of "upgrade":** `npx @sabaiway/agent-workflow-kit@latest init` updates the **kit's
+> own files** in `~/.claude/skills/`; `/agent-workflow-kit upgrade` then migrates a **project's**
+> `docs/ai/` deployment to that kit version.
+
+---
+
+## 🔍 How it works (60 seconds)
+
+- **Layered, lazy loading** — *always-loaded* = `AGENTS.md` + `index.md` (~160 lines, cache-warm). *On-demand* = open a `docs/ai/` file only when its "Read When" applies. *Hierarchical* = subdir `AGENTS.md` loads when you work in that folder. *Archive* = old history rolls out of the hot files.
+- **Caps + freshness** — every doc declares a `maxLines` cap; a pre-commit hook blocks commits that bust a cap or let the auto-generated index go stale.
+- **3-tier rolling archive** — `changelog.md` (HOT, last days) → `history/recent.md` (WARM) → per-month COLD + a one-line condensed index. Hot files stay small forever.
+- **Plan lifecycle** — Plan → Phase → Step → Substep, ephemeral plan files, a mandatory Cleanup phase, and a session-continuity heuristic tuned for large-context models (e.g. Opus 4.8).
+- **No silent failures** — every guard that rejects an action logs structured context.
+
+Enforcement ships as dependency-free **Node** scripts (`node --test`, no package manager assumed). Non-Node projects follow the same policy by hand.
+
+---
+
+## 🤝 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.
+
+---
+
+## 📁 What's in the kit
+
+```
+agent-workflow-kit/
+├── README.md        ← you are here
+├── SKILL.md         ← agent-facing algorithm
+├── CHANGELOG.md     ← version history
+├── references/
+    ├── templates/   ← AGENTS.md + every docs/ai file
+    ├── scripts/     ← caps / archive / index + tests
+    └── planning.md  ← plan lifecycle + continuity
+├── launchers/       ← Codex / Windsurf / Cursor entries
+└── migrations/      ← per-version upgrade steps
+```
+
+---
+
+<div align="center">
+<sub>Kernel-only · stack-agnostic · English · distilled from a multi-year-verified reference implementation.</sub>
+</div>

package/SKILL.md

@@ -0,0 +1,121 @@
+---
+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'
+---
+
+# 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**.
+
+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.
+
+---
+
+## Two modes
+
+Pick the mode from the user's invocation. Auto-detect an existing `docs/ai/` to guard against bootstrapping over a live system, but the user makes the final call.
+
+- **`/agent-workflow-kit`** (default) — bootstrap a new or empty project. If `docs/ai/` already exists, stop and ask whether they meant `upgrade`.
+- **`/agent-workflow-kit upgrade`** — upgrade an existing deployment to the skill's current `version`.
+
+### Mode: bootstrap
+
+> 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.
+
+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.
+   - `git log --oneline -30` + `git status` → recent activity, branch, uncommitted changes.
+   - `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. **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.
+
+Fill strategy:
+
+| File | Strategy |
+|------|----------|
+| `current_state.md`, `architecture.md`, `env_commands.md`, `technical_specification.md`, `pages/index.md` | Fill with **real** recon data (stack, scripts, layers, routes). |
+| `tech_reference.md` | Carry over real configs/patterns found in deps. |
+| `active_plan.md`, `handover.md` | TODO seed (e.g. "Bootstrap session — fill domain sections after first real work"). |
+| `decisions.md` | Seed `AD-001` (adopting this memory system). |
+| `known_issues.md`, `changelog.md`, `pages/shared-patterns.md` | Empty template / first bootstrap entry. |
+
+### Mode: upgrade
+
+1. Read `docs/ai/.workflow-version` (the project's stamped version). If missing, treat as a pre-versioned deployment and offer to re-bootstrap conservatively.
+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).
+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:
+
+- **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.
+
+---
+
+## 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/`.
+2. **Memory Map.** A "read-when / update-when" table for every file. Without it agents get lost.
+3. **Three protocols.** Start of Session → During Work → Task Completion, each a short checklist.
+4. **Update docs BEFORE code.** Page behaviour changing? Update `pages/<page>.md` first, then the code.
+5. **No silent failures.** Every internal validation/guard that rejects an action logs structured context (component, action, ids, inputs); user-facing failures also surface in the UI.
+6. **TDD by default.** Test before code (unit for functions, E2E for user flows).
+7. **ADR for strategic choices.** Long-term-consequence decisions get a `decisions.md` entry.
+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.
+
+---
+
+## Hard Constraints (template — adapt to the stack)
+
+Deploy these into `AGENTS.md`; remove rows that don't apply to the stack.
+
+| Rule | Enforcement |
+|------|-------------|
+| No `export default` (named exports only) | Linter |
+| No `any` / no unsafe casts | Linter / type-checker |
+| Functional style (no mutation in app code) | Linter |
+| No single-letter variables | Code review |
+| Interactive elements semantic (button/link, not div+onClick) | Linter / a11y |
+| No hardcoded colors — design tokens only | Code review |
+| No business logic in components → hooks/services | Architecture review |
+| No changes without tests (TDD) | Required |
+| Check page docs before changes; update them after | Process |
+| Ask user before committing | Process |
+| Every page has an HTML-validity / a11y E2E test | Required |
+| **No silent failures** — structured logging on every rejected action | Required |
+
+---
+
+## References
+
+- [`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`.
+- [`CHANGELOG.md`](CHANGELOG.md) — version history of this kernel.

package/bin/install.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// One-shot installer for @sabaiway/agent-workflow-kit.
+//
+//   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
+// you actually have). Re-running refreshes the skill to this package's version, which is
+// how you upgrade the *skill files* themselves:
+//
+//   npx @sabaiway/agent-workflow-kit@latest init
+//
+// That is distinct from `/agent-workflow-kit upgrade`, which migrates a *project's*
+// docs/ai deployment — see README "Use".
+//
+// No telemetry, no phone-home: adoption is the npm registry's public, passive per-version
+// download numbers (api.npmjs.org/downloads). Nothing here contacts a server.
+//
+// Dependency-free, Node >= 18.
+
+import { readFile, mkdir, readdir, copyFile, lstat, readlink, symlink } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { homedir } from 'node:os';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = resolve(__dirname, '..');
+
+// The deployable skill = everything except the npm wrapper (package.json, bin/).
+const PAYLOAD = ['SKILL.md', 'README.md', 'CHANGELOG.md', 'references', 'launchers', 'migrations'];
+
+const tildify = (path) => path.replace(homedir(), '~');
+
+const readVersion = async () => {
+  try {
+    const pkg = JSON.parse(await readFile(resolve(PKG_ROOT, 'package.json'), 'utf8'));
+    return pkg.version ?? 'unknown';
+  } catch {
+    return 'unknown';
+  }
+};
+
+const copyRecursive = async (src, dest) => {
+  const stat = await lstat(src);
+  if (stat.isSymbolicLink()) {
+    if (existsSync(dest)) return; // additive: never delete/replace an existing entry
+    const linkTarget = await readlink(src);
+    await symlink(linkTarget, dest);
+  } else if (stat.isDirectory()) {
+    await mkdir(dest, { recursive: true });
+    const entries = await readdir(src);
+    await Promise.all(entries.map((entry) => copyRecursive(join(src, entry), join(dest, entry))));
+  } else {
+    await mkdir(dirname(dest), { recursive: true });
+    await copyFile(src, dest);
+  }
+};
+
+const parseArgs = (argv) => {
+  const dirFlag = argv.indexOf('--dir');
+  return {
+    help: argv.includes('--help') || argv.includes('-h'),
+    version: argv.includes('--version') || argv.includes('-v'),
+    noLaunchers: argv.includes('--no-launchers'),
+    force: argv.includes('--force'),
+    dir: dirFlag >= 0 ? argv[dirFlag + 1] : undefined,
+  };
+};
+
+const resolveTarget = (dirArg) => {
+  if (dirArg) return resolve(dirArg);
+  if (process.env.AGENT_WORKFLOW_KIT_DIR) return resolve(process.env.AGENT_WORKFLOW_KIT_DIR);
+  return resolve(homedir(), '.claude/skills/agent-workflow-kit');
+};
+
+const printHelp = (version) => {
+  console.log(`agent-workflow-kit ${version}
+
+Usage:
+  npx @sabaiway/agent-workflow-kit init [--dir <path>] [--no-launchers] [--force]
+  npx @sabaiway/agent-workflow-kit --version
+  npx @sabaiway/agent-workflow-kit --help
+
+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
+  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`);
+};
+
+const main = async () => {
+  const version = await readVersion();
+  const args = parseArgs(process.argv.slice(2));
+
+  if (args.help) return printHelp(version);
+  if (args.version) return console.log(version);
+
+  if (!existsSync(resolve(PKG_ROOT, 'SKILL.md'))) {
+    console.error('[agent-workflow-kit] package payload missing (no SKILL.md) — corrupt install?');
+    process.exit(1);
+  }
+
+  const target = resolveTarget(args.dir);
+  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)}`);
+
+  // 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.');
+  } 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(`  bash ${tildify(launcher)}`);
+    }
+  }
+
+  console.log('\nNext: open your agent and run  /agent-workflow-kit');
+};
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/launchers/README.md

@@ -0,0 +1,33 @@
+# Cross-agent launchers
+
+`agent-workflow-kit` is one kit with **three front doors**. The logic lives once in
+[`../SKILL.md`](../SKILL.md) + [`../references/`](../references/); each launcher is a thin
+pointer, no duplicated logic. The kit's *output* (`AGENTS.md` + `docs/ai/`) is cross-agent
+already — these launchers make the *bootstrapper itself* runnable from non-Claude agents.
+
+`<KIT_DIR>` below = this kit's directory (e.g. `~/.claude/skills/agent-workflow-kit`).
+
+## Install matrix
+
+| Agent | Mechanism | Install | Invoke |
+|-------|-----------|---------|--------|
+| **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 |
+| **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
+you have and installs the matching launcher (Claude Code needs none).
+
+## Notes
+
+- **`${CLAUDE_SKILL_DIR}`** in `SKILL.md` means "this skill's own directory". Claude Code expands
+  it; other agents should read it as `<KIT_DIR>` (the folder containing `SKILL.md`).
+- **Codex invocation policy**: `SKILL.md`'s `disable-model-invocation` is Claude-Code-specific.
+  To make the skill user-only in Codex too, add an `agents/openai.yaml` to the kit per the
+  [Codex skills docs](https://developers.openai.com/codex/skills). Without it, Codex may
+  auto-trigger; the kit's internal "ask before writing / ask before commit" gates still hold.
+- **Where the kit lives for non-Claude users**: it does not have to be under `~/.claude/`. Clone
+  the kit anywhere (or to `~/.agents/skills/agent-workflow-kit`, which Codex scans) and point the
+  launchers at that path.