@sabaiway/agent-workflow-kit 1.0.0

package/launchers/install-launchers.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# Install agent-workflow-kit launchers for whichever non-Claude agents you have.
+# Claude Code needs no launcher — it reads the kit natively from ~/.claude/skills/.
+#
+# SAFE BY DEFAULT — additive only:
+#   - 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.
+#   - 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.
+#
+#   bash <KIT_DIR>/launchers/install-launchers.sh [--force]
+set -euo pipefail
+
+FORCE=0
+for arg in "$@"; do
+  case "$arg" in
+    --force) FORCE=1 ;;
+    *) echo "[launchers] unknown arg: $arg" >&2; exit 2 ;;
+  esac
+done
+
+# Kit dir = parent of this script's directory (launchers/..).
+KIT_DIR="$(cd "$(dirname "$0")/.." && pwd)"
+MARKER="agent-workflow-kit:managed"
+TS="$(date +%Y%m%d-%H%M%S)"
+echo "[launchers] kit: $KIT_DIR"
+
+installed_any=0
+skipped_any=0
+
+backup_and_note() { # $1 = path to back up before we replace it
+  local path="$1"
+  local bak="${path}.bak.${TS}"
+  cp -a "$path" "$bak"
+  echo "[launchers]   backed up existing → $bak"
+  echo "[launchers]   restore with:  rm -rf \"$path\" && mv \"$bak\" \"$path\""
+}
+
+# --- Codex: SKILL.md is a native cross-agent skill → symlink into a Codex skill scope.
+if command -v codex >/dev/null 2>&1 || [ -d "$HOME/.codex" ]; then
+  mkdir -p "$HOME/.codex/skills"
+  LINK="$HOME/.codex/skills/agent-workflow-kit"
+  if [ -L "$LINK" ] || { [ ! -e "$LINK" ] && [ ! -L "$LINK" ]; }; then
+    # Our own symlink slot, or empty — a symlink is a pointer, not user data.
+    ln -sfn "$KIT_DIR" "$LINK"
+    echo "[launchers] Codex    → linked $LINK -> $KIT_DIR"
+    installed_any=1
+  elif [ "$FORCE" -eq 1 ]; then
+    backup_and_note "$LINK"
+    rm -rf "$LINK"
+    ln -sfn "$KIT_DIR" "$LINK"
+    echo "[launchers] Codex    → replaced (forced) $LINK -> $KIT_DIR"
+    installed_any=1
+  else
+    echo "[launchers] Codex    ⚠ $LINK exists and was not created by the kit — left untouched."
+    echo "[launchers]            re-run with --force to replace it (a backup is made first)."
+    skipped_any=1
+  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
+  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)"
+    installed_any=1
+  elif grep -q "$MARKER" "$WF" 2>/dev/null; then
+    write_wf
+    echo "[launchers] Windsurf → refreshed $WF (kit-managed)"
+    installed_any=1
+  elif [ "$FORCE" -eq 1 ]; then
+    backup_and_note "$WF"
+    write_wf
+    echo "[launchers] Windsurf → replaced (forced) $WF"
+    installed_any=1
+  else
+    echo "[launchers] Windsurf ⚠ $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."
+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

@@ -0,0 +1,30 @@
+---
+description: Bootstrap or upgrade the agent-workflow-kit AI memory & workflow system (docs/ai + AGENTS.md + enforcement) in this project.
+---
+
+<!-- agent-workflow-kit:managed — generated by the kit installer. Safe to overwrite on
+     reinstall; delete this file to remove the Windsurf launcher. -->
+
+# agent-workflow-kit
+
+Thin launcher — the full algorithm, templates, and scripts live in the kit. Do **not**
+reinvent any of it here; the kit's `SKILL.md` is the single source of truth.
+
+`<KIT_DIR>` = the kit's directory on this machine (the installer substitutes the real path).
+
+## Steps
+
+1. Read the kit instructions in full: `<KIT_DIR>/SKILL.md`, plus the `references/` files it
+   points to. Wherever it says `${CLAUDE_SKILL_DIR}`, read that as `<KIT_DIR>`.
+2. Pick the mode:
+   - No `docs/ai/` in this project → **bootstrap**.
+   - `docs/ai/` already exists → ask the user whether to run **upgrade** instead.
+3. Execute every step from `SKILL.md` for THIS repository:
+   - Recon (read-only) → **ask the user: visible or hidden** (wait for the answer) →
+     create `AGENTS.md` (+ `CLAUDE.md` symlink) from `<KIT_DIR>/references/templates/` →
+     deploy `docs/ai/` → copy `<KIT_DIR>/references/scripts/*.mjs` (Node projects) →
+     wire/hide per visibility → install the pre-commit hook → stamp `docs/ai/.workflow-version`.
+4. Report what was filled with real data vs left as TODO, then **ask before committing** —
+   never auto-commit.
+
+This workflow is manual-only; run it deliberately, like a deploy.

package/migrations/README.md

@@ -0,0 +1,41 @@
+# Migrations
+
+Each upgrade step is one file: `migrations/<version>-<slug>.md`, where `<version>` is the
+skill release that introduced the change (matches a `CHANGELOG.md` heading) and `<slug>`
+is a short kebab-case name. Empty until the first change that needs migrating — most
+releases add files/templates, which `upgrade` reconciles without a migration.
+
+## How `upgrade` applies them
+
+1. Read the project's stamped version from `docs/ai/.workflow-version`.
+2. Select every migration whose `<version>` is **strictly newer** than the stamp.
+3. Apply them in **ascending semver order**.
+4. Re-stamp `docs/ai/.workflow-version` to the skill's current `version`.
+
+## Authoring rules
+
+- **Idempotent** — safe to re-run; check before mutating (e.g. "if the file already has X, skip").
+- **Non-destructive** — never clobber project-authored content (their `decisions.md`, `known_issues.md`, page specs). Add/rename/restructure only what the kernel owns.
+- **Self-contained** — exact paths + commands, readable cold, like a mini-plan.
+- **Mention rollback** — note how to undo if the step is risky.
+
+## Template
+
+```markdown
+# Migration <version>-<slug>
+
+**From:** versions < <version>   **To:** <version>
+
+## Why
+<what changed in the kernel and why a project needs to follow>
+
+## Steps
+1. <exact, idempotent action with paths/commands>
+2. ...
+
+## Verification
+<how to confirm the project is now consistent — e.g. docs cap-validator green>
+
+## Rollback
+<how to undo, or "n/a — additive only">
+```

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@sabaiway/agent-workflow-kit",
+  "version": "1.0.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",
+    "claude-code",
+    "codex",
+    "cursor",
+    "windsurf",
+    "agents-md",
+    "workflow",
+    "skill",
+    "memory",
+    "developer-tools"
+  ],
+  "homepage": "https://github.com/sabaiway/agent-workflow-kit#readme",
+  "bugs": {
+    "url": "https://github.com/sabaiway/agent-workflow-kit/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sabaiway/agent-workflow-kit.git"
+  },
+  "license": "MIT",
+  "author": "sabaiway",
+  "type": "module",
+  "bin": {
+    "agent-workflow-kit": "bin/install.mjs"
+  },
+  "files": [
+    "bin/",
+    "SKILL.md",
+    "README.md",
+    "CHANGELOG.md",
+    "references/",
+    "launchers/",
+    "migrations/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/references/planning.md

@@ -0,0 +1,105 @@
+# Planning Workflow
+
+Source of truth for **how plans are written, stored, executed, and torn down**. Overrides the generic `writing-plans` skill — if both trigger, this one wins. Runtime series status (which plan is Current / Pending) lives in `docs/plans/queue.md`.
+
+---
+
+## 1. Plan vocabulary
+
+Strict four-level hierarchy, used in plan files (`docs/plans/*.md`) and in verbal summaries:
+
+- **Plan** — top-level container = the plan file itself. One file = one Plan. A series of related plans is not grouped under any wrapper noun; refer to them as "Plan 1 of N", "the next plan". Series order lives in `queue.md` (§3).
+- **Phase** — a large block inside the Plan. Exactly one execution session. Ends with its own verification block. `## Phase 1: …`, `## Phase 2: …`.
+- **Step** — an atomic change inside a Phase. Numbered `<phase>.<step>`: `### 1.1. …`. One Step → one logical commit.
+- **Substep** — optional split of a complex Step. Lettered: `**1.2.a**`, `**1.2.b**`. Use only when a Step cannot be one command.
+
+Reserve the word "task" for the todo list and `active_plan.md` — not for plan structure.
+
+## 2. Plan directory & lifecycle
+
+Plan files are **ephemeral, machine-local scratch space**, gitignored (`.gitignore` contains `docs/plans/`).
+
+**Lifecycle:** Creation (untracked file) → Execution (Phases 1..N-1) → mandatory **Phase N: Cleanup** (§4) → Post-deletion (only `changelog.md` + ADRs remain). Plans are **NEVER committed** — full stop. Even if a plan looks load-bearing (referenced by an ADR), inline the load-bearing content into a persistent doc and delete the plan file.
+
+**Forbidden:** `git add` of any plan file; plan-file paths in committed docs; leaving plan files on disk after Cleanup. If the user says "commit the plan" — ask back: "the plan is ephemeral — what exactly should I inline into `decisions.md` / `changelog.md`?".
+
+## 3. Series & queue.md
+
+A **series** = 2+ related plans that share a roadmap. The index lives at `docs/plans/queue.md` (gitignored, machine-local):
+
+```markdown
+## Series: <name>
+
+### Current
+- **Plan N / M** — <slug> — <one-line description>
+
+### Pending
+- **Plan N+1 / M** — <slug or TBD> — <description>
+
+### Done
+- **Plan K / M** — <slug> — done YYYY-MM-DD. Outputs: <pointers>.
+```
+
+`queue.md` is initialised when the **first** plan of a series is written, not during its Cleanup — without an upfront index the execution agent has no map of the series. Each plan's Cleanup then marks itself Done (with outputs) and promotes the next plan to Current. A single, unrelated plan does not need a series entry.
+
+## 4. Required Cleanup phase
+
+Every Plan MUST end with a final **Phase N: Cleanup** — the last numbered Phase. Without it the Plan is not done.
+
+Minimum content:
+
+- **Migrate outputs** → `docs/ai/decisions.md` (AD-XXX), `changelog.md`, `known_issues.md` (Issue-XXX), `current_state.md`, `pages/<page>.md`.
+- **Inline cross-references** — `grep -rn "<plan-slug>" docs/` must be empty. Every pointer is rewritten inline or removed.
+- **Update `queue.md`** — if part of a series, mark Done + promote next.
+- **Delete the plan file** — `rm docs/plans/<slug>.md`.
+- **Verification** — `grep -rn "<slug>" .` empty; `ls docs/plans/<slug>.md` → No such file; docs cap-validator green.
+
+If a Plan is aborted mid-flight, Cleanup still runs — partial outputs land in `known_issues.md`, then the file is deleted.
+
+## 5. All work in plans
+
+Anything required for the task is a **Step inside the Plan**. Nothing "before the plan", "between plans", or "don't forget" — those evaporate at execution time because the execution agent reads only the plan file, not chat scrollback. Every dependency, check, and install is its own Step or Substep. The final "Next steps" section contains **only user-actionable** items.
+
+## 6. Plan-then-execute split
+
+Default workflow for non-trivial features (multi-file change, new service + hook + UI, architectural choices): write a **self-contained Plan** and stop. Implementation runs in a fresh session via the `executing-plans` skill.
+
+- Triggers: any feature, refactor, or change touching more than ~1 file, or non-obvious architectural choices.
+- Does NOT apply to typos, one-line fixes, doc-only edits, or pure "where is X" research — those run inline.
+- The Plan must be readable cold by a fresh agent: file paths, contracts, execution order, verification, gotchas — all inside the file.
+
+This split is a token-efficiency strategy: exploration context stays out of the execution window.
+
+### Session-continuity heuristic (split vs continue)
+
+The volume trigger above (files / LoC / tokens) is necessary but not sufficient. The deeper question is whether the planning context is the execution **payload** or **noise**:
+
+- **Split** (fresh session) when planning exploration was *broad fan-out* — many files skimmed, sub-agent dumps, wide searches to *locate* things. That context is noise for execution; discard it.
+- **Continue** in the current session when ALL hold: (1) exploration was *targeted-deep* — you read the exact files to be created/modified/copied, so execution would just re-read them; (2) no new heavy exploration is needed to execute; (3) the context budget is healthy (far from the window limit / Lost-in-the-Middle).
+- When continuing, each Phase's Verification block is a natural checkpoint. If different Phases need different cold context, continue only through the warm Phases, then split.
+
+## 7. Plan-document structure
+
+```
+# Plan: <human-readable title>
+
+## Context              ← why this Plan exists, current state, why now (reads cold)
+## Approach             ← chosen design + an explicit "What we are NOT doing"
+## Phase 1: <name>
+   ### 1.1. <step>      ← exact paths + commands
+## Phase 2: <name>
+   ...
+## Phase N: Cleanup     ← mandatory (§4)
+## Critical files       ← table: file → change kind (new / modify / delete / move)
+## Reuse                ← pointers to existing patterns/snippets to copy, not re-derive
+## Verification         ← full check sequence (mechanical + behavioural)
+## Next steps           ← user-actionable only (§5)
+```
+
+## 8. Self-review checklist (before finalizing a Plan)
+
+- Every Step has exact file paths and exact commands.
+- Every recommendation that used to live outside the Plan is now a Step (§5).
+- Vocabulary is strict (§1); the Plan ends with **Phase N: Cleanup** (§4).
+- If part of a series: `queue.md` is initialised / updated (§3).
+- No `git add <plan>` and no "commit the plan" wording in the final report.

package/references/scripts/_expect-shim.mjs

@@ -0,0 +1,41 @@
+// Minimal dependency-free `expect` shim mapping the Vitest matchers used by the
+// kernel's *.test.mjs onto node:assert, so the suite runs under `node --test` with
+// zero dependencies. Supports only the matchers these tests use.
+import assert from 'node:assert/strict';
+
+const has = (actual, expected) => {
+  if (typeof actual === 'string') return actual.includes(expected);
+  if (Array.isArray(actual)) return actual.includes(expected);
+  return false;
+};
+
+const matchers = (actual, negate) => ({
+  toBe: (expected) =>
+    negate ? assert.notStrictEqual(actual, expected) : assert.strictEqual(actual, expected),
+  toEqual: (expected) =>
+    negate ? assert.notDeepStrictEqual(actual, expected) : assert.deepStrictEqual(actual, expected),
+  toContain: (expected) =>
+    assert.ok(
+      negate ? !has(actual, expected) : has(actual, expected),
+      `expected ${JSON.stringify(actual)} ${negate ? 'not ' : ''}to contain ${JSON.stringify(expected)}`,
+    ),
+  toMatch: (re) => (negate ? assert.doesNotMatch(actual, re) : assert.match(actual, re)),
+  toHaveLength: (n) =>
+    negate ? assert.notStrictEqual(actual.length, n) : assert.strictEqual(actual.length, n),
+  toBeNull: () => (negate ? assert.notStrictEqual(actual, null) : assert.strictEqual(actual, null)),
+  toBeInstanceOf: (Ctor) =>
+    assert.ok(
+      negate ? !(actual instanceof Ctor) : actual instanceof Ctor,
+      `expected value ${negate ? 'not ' : ''}to be instance of ${Ctor.name}`,
+    ),
+  toBeGreaterThan: (n) =>
+    assert.ok(negate ? !(actual > n) : actual > n, `expected ${actual} ${negate ? 'not ' : ''}> ${n}`),
+  toBeLessThan: (n) =>
+    assert.ok(negate ? !(actual < n) : actual < n, `expected ${actual} ${negate ? 'not ' : ''}< ${n}`),
+});
+
+export const expect = (actual) => {
+  const api = matchers(actual, false);
+  api.not = matchers(actual, true);
+  return api;
+};