@givolt/i3-composer-agent 0.0.0-stage → 0.6.12

package/hooks/simplify-ignore.sh

@@ -0,0 +1,352 @@
+#!/bin/bash
+# simplify-ignore.sh — Hook for Read (PreToolUse), Edit|Write (PostToolUse), Stop
+#
+# PreToolUse Read   → backs up file, replaces blocks with BLOCK_<hash> in-place
+# PostToolUse Edit  → expands placeholders, re-filters so file stays hidden
+# PostToolUse Write → expands placeholders, re-filters so file stays hidden
+# Stop              → expands the placeholders still in the file on disk, so a
+#                     change made by any route survives; the backup is used
+#                     only when no placeholder is left to expand
+#
+# The file on disk ALWAYS has placeholders while the session is active.
+# The real content is that file with its placeholders expanded; the backup
+# holds the last state the hook itself saw.
+#
+# Dependencies: jq, shasum or sha1sum (auto-detected)
+
+set -euo pipefail
+
+# Bash 5.2+ turns on patsub_replacement by default, which makes `&` and
+# backslash special on the replacement side of ${var//pattern/replacement}:
+# `&` expands to the matched text and `\\` collapses. expand_file substitutes
+# raw block content there, and code routinely contains `&&` and backslashes,
+# so the option must be off or protected blocks come back corrupted on Linux.
+# Older bashes do not know the option; ignore the error there.
+shopt -u patsub_replacement 2>/dev/null || true
+
+if ! command -v jq >/dev/null 2>&1; then
+  printf '%s\n' "error: missing jq" >&2; exit 1
+fi
+
+CACHE="${CLAUDE_PROJECT_DIR:-.}/.claude/.simplify-ignore-cache"
+if [ -t 0 ]; then INPUT="{}"; else INPUT=$(cat); fi
+
+# Parse hook input — trap errors explicitly so set -e doesn't cause
+# a silent exit on malformed JSON, and surface a useful diagnostic.
+parse_error=""
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null) || {
+  parse_error="failed to parse .tool_name from hook input"
+  TOOL_NAME=""
+}
+FILE_PATH=$(printf '%s' "$INPUT" | jq -r '.tool_input.file_path // empty' 2>/dev/null) || {
+  parse_error="failed to parse .tool_input.file_path from hook input"
+  FILE_PATH=""
+}
+if [ -n "$parse_error" ]; then
+  printf 'Warning: %s (input: %.120s)\n' "$parse_error" "$INPUT" >&2
+fi
+
+hash_cmd() {
+  if command -v shasum >/dev/null 2>&1; then shasum
+  elif command -v sha1sum >/dev/null 2>&1; then sha1sum
+  else printf '%s\n' "error: missing shasum or sha1sum" >&2; exit 1; fi
+}
+file_id() { printf '%s' "$1" | hash_cmd | cut -c1-16; }
+block_hash() { printf '%s' "$1" | hash_cmd | cut -c1-8; }
+# Escape glob metacharacters so ${var/pattern/repl} treats pattern as literal.
+# Needed for Bash 3.2 (macOS) where quotes don't suppress globbing in PE patterns.
+escape_glob() {
+  local s="$1"
+  s="${s//\\/\\\\}"
+  s="${s//\*/\\*}"
+  s="${s//\?/\\?}"
+  s="${s//\[/\\[}"
+  printf '%s' "$s"
+}
+
+# ── filter_file: replace simplify-ignore blocks with BLOCK_<hash> placeholders ─
+# Reads $1 (source), writes filtered version to $2 (dest), saves blocks to cache.
+# Returns 0 if blocks were found, 1 if none.
+filter_file() {
+  local src="$1" dest="$2" fid="$3"
+  : > "$dest"
+  rm -f "$CACHE/${fid}".block.* "$CACHE/${fid}".reason.* "$CACHE/${fid}".prefix.* "$CACHE/${fid}".suffix.*
+
+  local count=0 in_block=0 buf="" reason="" prefix="" suffix=""
+
+  while IFS= read -r line || [ -n "$line" ]; do
+    # Check for start marker (no fork — uses bash case)
+    if [ $in_block -eq 0 ]; then
+      case "$line" in *simplify-ignore-start*)
+        in_block=1
+        buf="$line"
+        # Extract comment prefix/suffix to preserve language-appropriate syntax
+        prefix="${line%%simplify-ignore-start*}"
+        suffix=""
+        case "$line" in *'*/'*) suffix=" */" ;; *'-->'*) suffix=" -->" ;; esac
+        reason=$(printf '%s' "$line" | sed -n 's/.*simplify-ignore-start:[[:space:]]*//p' \
+          | sed 's/[[:space:]]*\*\/.*$//' | sed 's/[[:space:]]*-->.*$//' | sed 's/[[:space:]]*$//')
+        # Handle single-line block (start + end on same line)
+        case "$line" in *simplify-ignore-end*)
+          in_block=0
+          # Write single-line block immediately and skip to next line
+          # to avoid the end-marker check below firing again
+          local h; h=$(block_hash "$buf")
+          count=$((count + 1))
+          printf '%s' "$buf" > "$CACHE/${fid}.block.${h}"
+          [ -n "$reason" ] && printf '%s' "$reason" > "$CACHE/${fid}.reason.${h}"
+          printf '%s' "$prefix" > "$CACHE/${fid}.prefix.${h}"
+          printf '%s' "$suffix" > "$CACHE/${fid}.suffix.${h}"
+          if [ -n "$reason" ]; then
+            printf '%s\n' "${prefix}BLOCK_${h}: ${reason}${suffix}" >> "$dest"
+          else
+            printf '%s\n' "${prefix}BLOCK_${h}${suffix}" >> "$dest"
+          fi
+          buf=""; reason=""; prefix=""; suffix=""
+          continue
+          ;; *)
+          continue
+          ;;
+        esac
+      ;; esac
+    fi
+    # Accumulate block content
+    if [ $in_block -eq 1 ]; then
+      buf="${buf}
+${line}"
+    fi
+    # Check for end marker
+    case "$line" in *simplify-ignore-end*)
+      if [ $in_block -eq 1 ]; then
+        local h; h=$(block_hash "$buf")
+        count=$((count + 1))
+        printf '%s' "$buf" > "$CACHE/${fid}.block.${h}"
+        [ -n "$reason" ] && printf '%s' "$reason" > "$CACHE/${fid}.reason.${h}"
+        printf '%s' "$prefix" > "$CACHE/${fid}.prefix.${h}"
+        printf '%s' "$suffix" > "$CACHE/${fid}.suffix.${h}"
+        if [ -n "$reason" ]; then
+          printf '%s\n' "${prefix}BLOCK_${h}: ${reason}${suffix}" >> "$dest"
+        else
+          printf '%s\n' "${prefix}BLOCK_${h}${suffix}" >> "$dest"
+        fi
+        in_block=0; buf=""; reason=""; prefix=""; suffix=""
+        continue
+      fi
+      ;;
+    esac
+    [ $in_block -eq 0 ] && printf '%s\n' "$line" >> "$dest"
+  done < "$src"
+
+  # Unclosed block → flush as-is
+  if [ $in_block -eq 1 ] && [ -n "$buf" ]; then
+    printf 'Warning: unclosed simplify-ignore-start in %s (block not hidden)\n' "$src" >&2
+    printf '%s\n' "$buf" >> "$dest"
+  fi
+
+  # Preserve trailing newline status of source
+  if [ -s "$dest" ] && [ -s "$src" ] && [ -n "$(tail -c 1 "$src")" ]; then
+    perl -pe 'chomp if eof' "$dest" > "${dest}.nnl" && \
+      cat "${dest}.nnl" > "$dest" && rm -f "${dest}.nnl"
+  fi
+
+  [ $count -gt 0 ] && return 0 || return 1
+}
+
+# ── expand_file: replace BLOCK_<hash> placeholders with the real block code ───
+# Reads $1 (source), writes the expanded version to $2 (dest), using the blocks
+# cached under $3 (file id). Warns on placeholders that were altered or deleted.
+expand_file() {
+  local src="$1" dest="$2" fid="$3"
+  local line bf h bp bs br placeholder block_content esc_placeholder esc_fuzzy bh first_line
+  rm -f "$dest"
+  while IFS= read -r line || [ -n "$line" ]; do
+    case "$line" in *BLOCK_*)
+      # Expand all placeholders on this line (supports multiple per line)
+      for bf in "$CACHE/${fid}".block.*; do
+        [ -f "$bf" ] || continue
+        h="${bf##*.}"
+        case "$line" in *"BLOCK_${h}"*)
+          # Reconstruct the exact placeholder pattern
+          bp=""; bs=""; br=""
+          [ -f "$CACHE/${fid}.prefix.${h}" ] && bp=$(cat "$CACHE/${fid}.prefix.${h}")
+          [ -f "$CACHE/${fid}.suffix.${h}" ] && bs=$(cat "$CACHE/${fid}.suffix.${h}")
+          [ -f "$CACHE/${fid}.reason.${h}" ] && br=$(cat "$CACHE/${fid}.reason.${h}")
+          if [ -n "$br" ]; then
+            placeholder="${bp}BLOCK_${h}: ${br}${bs}"
+          else
+            placeholder="${bp}BLOCK_${h}${bs}"
+          fi
+          block_content=$(cat "$bf"; printf x); block_content="${block_content%x}"
+          # Escape glob metacharacters (* ? [ \) in the pattern
+          esc_placeholder=$(escape_glob "$placeholder")
+          # Bash native substitution (// = global replace): replace placeholder, keep surrounding code
+          line="${line//$esc_placeholder/$block_content}"
+          # Fallback: if model altered the reason text, try without reason
+          # (only trigger if BLOCK_hash is still present AND wasn't in the original block content)
+          case "$block_content" in *"BLOCK_${h}"*) ;; *)
+            case "$line" in *"BLOCK_${h}"*)
+              printf 'Warning: placeholder BLOCK_%s was modified by model, using fuzzy match\n' "$h" >&2
+              esc_fuzzy=$(escape_glob "${bp}BLOCK_${h}${bs}")
+              line="${line//$esc_fuzzy/$block_content}"
+              # Last resort: match just the hash token
+              case "$line" in *"BLOCK_${h}"*)
+                line="${line//BLOCK_${h}/$block_content}"
+              ;; esac
+            ;; esac
+          ;; esac
+        ;; esac
+      done
+    ;; esac
+    printf '%s\n' "$line" >> "$dest"
+  done < "$src"
+  # Preserve trailing newline status
+  if [ -s "$dest" ] && [ -s "$src" ] && [ -n "$(tail -c 1 "$src")" ]; then
+    perl -pe 'chomp if eof' "$dest" > "${dest}.nnl" && \
+      cat "${dest}.nnl" > "$dest" && rm -f "${dest}.nnl"
+  fi
+  # Warn if model deleted a protected block entirely
+  for bf in "$CACHE/${fid}".block.*; do
+    [ -f "$bf" ] || continue
+    bh="${bf##*.}"
+    # After expansion, blocks appear as original code (simplify-ignore-start).
+    # If neither the expanded code nor the placeholder is in EXPANDED, it was deleted.
+    if ! grep -qF "BLOCK_${bh}" "$dest" 2>/dev/null; then
+      # Get first line of block to check if it was expanded back
+      first_line=$(head -1 "$bf")
+      if ! grep -qF "$first_line" "$dest" 2>/dev/null; then
+        printf 'Warning: protected block BLOCK_%s was deleted by model\n' "$bh" >&2
+      fi
+    fi
+  done
+  return 0
+}
+
+# ── has_placeholders: is a cached BLOCK_<hash> for $2 still present in file $1? ─
+has_placeholders() {
+  local f="$1" fid="$2" bf h
+  for bf in "$CACHE/${fid}".block.*; do
+    [ -f "$bf" ] || continue
+    h="${bf##*.}"
+    grep -qF "BLOCK_${h}" "$f" 2>/dev/null && return 0
+  done
+  return 1
+}
+
+# ── Stop: expand each cached file in place, backup only as fallback ──────────
+if [ -z "$TOOL_NAME" ]; then
+  [ -d "$CACHE" ] || exit 0
+  for bak in "$CACHE"/*.bak; do
+    [ -f "$bak" ] || continue
+    fid="${bak##*/}"; fid="${fid%.bak}"
+    pathfile="$CACHE/${fid}.path"
+    [ -f "$pathfile" ] || { rm -f "$bak"; continue; }
+    orig=$(cat "$pathfile")
+    if [ -f "$orig" ]; then
+      # A change can reach the file through a route that fires no Edit or Write
+      # event (a Bash command, a formatter, an external editor), and the backup
+      # is stale for all of them. Expand what is on disk rather than overwrite it.
+      if has_placeholders "$orig" "$fid"; then
+        EXPANDED="$CACHE/${fid}.$$.expanded"
+        expand_file "$orig" "$EXPANDED" "$fid"
+        cat "$EXPANDED" > "$orig"
+        rm -f "$EXPANDED"
+      else
+        # Nothing left to expand — the file was rewritten wholesale, so the
+        # backup is the only remaining copy of the protected blocks. Keep the
+        # rewrite in the cache before the backup overwrites it, so the work is
+        # recoverable rather than lost.
+        rewritten="$CACHE/${fid}.recovered"
+        cat "$orig" > "$rewritten"
+        cat "$bak" > "$orig"
+        printf 'Warning: no BLOCK_ placeholder left in %s, restored from backup. Rewrite kept at %s\n' \
+          "$orig" "$rewritten" >&2
+      fi
+      rm -f "$bak" "$pathfile" "$CACHE/${fid}".block.* "$CACHE/${fid}".reason.* "$CACHE/${fid}".prefix.* "$CACHE/${fid}".suffix.*
+      rmdir "$CACHE/${fid}.lock" 2>/dev/null
+    else
+      # File was moved/deleted — save backup as .recovered, don't destroy it
+      mkdir -p "$(dirname "${orig}.recovered")"
+      mv "$bak" "${orig}.recovered"
+      rm -f "$pathfile" "$CACHE/${fid}".block.* "$CACHE/${fid}".reason.* "$CACHE/${fid}".prefix.* "$CACHE/${fid}".suffix.*
+      rmdir "$CACHE/${fid}.lock" 2>/dev/null
+      printf 'Warning: %s was moved/deleted. Recovered original to %s.recovered\n' "$orig" "$orig" >&2
+    fi
+  done
+  # Clean orphan locks (created but crash before backup)
+  for lockdir in "$CACHE"/*.lock; do
+    [ -d "$lockdir" ] || continue
+    rmdir "$lockdir" 2>/dev/null
+  done
+  exit 0
+fi
+
+[ -z "$FILE_PATH" ] && exit 0
+
+# ── PreToolUse Read: filter in-place ──────────────────────────────────────────
+if [ "$TOOL_NAME" = "Read" ]; then
+  [ -f "$FILE_PATH" ] || exit 0
+  case "$(basename "$FILE_PATH")" in simplify-ignore*|SIMPLIFY-IGNORE*) exit 0 ;; esac
+
+  mkdir -p "$CACHE"
+  ID=$(file_id "$FILE_PATH")
+
+  # If backup exists, file is already filtered — skip
+  [ -f "$CACHE/${ID}.bak" ] && exit 0
+
+  grep -q 'simplify-ignore-start' -- "$FILE_PATH" || exit 0
+
+  # Atomic lock: mkdir fails if another session races us
+  if ! mkdir "$CACHE/${ID}.lock" 2>/dev/null; then
+    # Lock exists — reclaim only if stale (>60s old, no backup = crash leftover)
+    if [ ! -f "$CACHE/${ID}.bak" ] && \
+       [ -n "$(find "$CACHE/${ID}.lock" -maxdepth 0 -mmin +1 2>/dev/null)" ]; then
+      rmdir "$CACHE/${ID}.lock" 2>/dev/null || true
+      mkdir "$CACHE/${ID}.lock" 2>/dev/null || exit 0
+    else
+      exit 0
+    fi
+  fi
+
+  # Back up the original (preserve trailing newline status)
+  cp -p "$FILE_PATH" "$CACHE/${ID}.bak" 2>/dev/null || cp "$FILE_PATH" "$CACHE/${ID}.bak"
+  printf '%s' "$FILE_PATH" > "$CACHE/${ID}.path"
+
+  # Filter in-place (cat > preserves inode and permissions)
+  FILTERED="$CACHE/${ID}.$$.tmp"
+  rm -f "$FILTERED"
+  if filter_file "$FILE_PATH" "$FILTERED" "$ID"; then
+    cat "$FILTERED" > "$FILE_PATH"
+    rm -f "$FILTERED"
+  else
+    rm -f "$FILTERED" "$CACHE/${ID}.bak" "$CACHE/${ID}.path"
+    rmdir "$CACHE/${ID}.lock" 2>/dev/null
+  fi
+  exit 0
+fi
+
+# ── PostToolUse Edit|Write: expand, then re-filter ────────────────────────────
+if [ "$TOOL_NAME" = "Edit" ] || [ "$TOOL_NAME" = "Write" ]; then
+  ID=$(file_id "$FILE_PATH")
+  [ -f "$CACHE/${ID}.bak" ] || exit 0
+  ls "$CACHE/${ID}".block.* >/dev/null 2>&1 || exit 0
+
+  # Expand placeholders, preserving any inline code the model added around them
+  EXPANDED="$CACHE/${ID}.$$.expanded"
+  expand_file "$FILE_PATH" "$EXPANDED" "$ID"
+  # Preserve inode and permissions
+  cat "$EXPANDED" > "$FILE_PATH"
+  rm -f "$EXPANDED"
+
+  # Save expanded version as new backup (this is the "real" file with model's changes)
+  cp "$FILE_PATH" "$CACHE/${ID}.bak"
+
+  # Re-filter in-place so the file on disk stays with placeholders
+  FILTERED="$CACHE/${ID}.$$.tmp"
+  rm -f "$FILTERED"
+  if filter_file "$FILE_PATH" "$FILTERED" "$ID"; then
+    cat "$FILTERED" > "$FILE_PATH"
+    rm -f "$FILTERED"
+  fi
+
+  exit 0
+fi

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@givolt/i3-composer-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.12",
+  "description": "i3 Composer Agent: production-grade engineering skills and lifecycle commands for AI coding agents.",
+  "license": "MIT",
+  "author": "Givolt",
+  "contributors": [{ "name": "Addy Osmani" }],
+  "bin": { "i3-composer-agent": "bin/i3-composer-agent.cjs" },
+  "engines": { "node": ">=20" },
+  "publishConfig": { "access": "public", "registry": "https://registry.npmjs.org/" },
+  "files": [
+    "bin/", "skills/", "references/", "agents/", "commands/",
+    ".claude/commands/", ".gemini/commands/", ".claude-plugin/",
+    ".codex-plugin/", ".agents/plugins/", "hooks/", "docs/",
+    "scripts/", "evals/", "rebrand/", "tests/", "plugin.json", "NOTICE.md"
+  ],
+  "scripts": {
+    "rebrand": "node rebrand/apply.cjs --apply",
+    "rebrand:check": "node rebrand/apply.cjs --check",
+    "validate": "node scripts/validate-brand.cjs && node scripts/validate-skills.js && node scripts/validate-versions.js && node scripts/validate-commands.js && node scripts/validate-reference-links.js && node scripts/validate-artifact-paths.js",
+    "test": "node --test scripts/*-test.js scripts/lib/*-test.js tests/*.test.cjs",
+    "prepack": "npm run validate"
+  },
+  "keywords": ["i3-composer", "agent-skills", "codebuddy", "codex", "claude-code"],
+  "i3ComposerAgent": {
+    "pluginFiles": [
+      "bin", "skills", "references", "agents", "commands", ".claude/commands",
+      ".gemini/commands", ".claude-plugin", ".codex-plugin", ".agents/plugins",
+      "hooks", "docs", "scripts", "evals", "rebrand", "tests", "plugin.json",
+      "package.json", "README.md", "LICENSE", "NOTICE.md"
+    ]
+  }
+}

package/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "i3-composer-agent",
+  "version": "0.6.12",
+  "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship."
+}

package/rebrand/MAINTENANCE.md

@@ -0,0 +1,51 @@
+# Maintaining i3 Composer Agent
+
+The product and plugin ID is `i3-composer-agent`; the npm package is
+`@givolt/i3-composer-agent`. The separate GSD-based project is maintained in its
+own repository and is outside this conversion.
+
+`brand.json` records the identity and upstream baseline. `apply.cjs` replays the
+brand substitutions and marketplace normalization; `templates/` holds the
+branded installation pages. Preserve LICENSE, NOTICE, upstream URLs, historical
+eval reports, the upstream comparison, and the skill ID `using-agent-skills`.
+References to the independent Agent Skills specification retain that name.
+
+## Source and release workflow
+
+Keep the upstream source on `i3/source`, with its original names. Perform source
+updates there. Start release candidates from the current branded branch, bringing
+in the upstream changes while retaining the npm CLI and `rebrand/` files, then
+replay the brand transformation. A fresh checkout of `i3/source` alone does not
+contain the distribution tools.
+Keep the original upstream remote until a dedicated fork repository is created;
+do not push branded changes to `addyosmani/agent-skills`.
+
+```bash
+node rebrand/apply.cjs --apply
+node rebrand/apply.cjs --check
+npm run validate
+npm test
+node scripts/run-evals.js --min-rank1 95
+bash hooks/session-start-test.sh
+bash hooks/sdd-cache-test.sh
+bash hooks/simplify-ignore-test.sh
+npm pack --pack-destination /path/to/release-directory
+```
+
+The transform is idempotent. The check exits with a failure when another replay
+would change files. Keep package.json and all plugin manifest versions in sync.
+Inspect the tarball and test its CLI in an isolated directory before publishing.
+
+The CLI prepares a self-contained plugin directory and prints native host
+registration commands. It does not write business-project AGENTS.md, change
+existing plugin settings, or register lifecycle slash commands in Codex.
+
+Publishing is a separate step after the package is reviewed:
+
+```bash
+npm publish /path/to/givolt-i3-composer-agent-0.6.12.tgz --access public
+```
+
+Verify the registry version, integrity, and a fresh registry install after
+publication. A local tarball test does not prove registry publication or actual
+model execution of a command.

package/rebrand/apply.cjs

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const brand = require('./brand.json');
+const root = path.resolve(__dirname, '..');
+const mode = process.argv[2];
+if (!['--apply', '--check'].includes(mode)) {
+  console.error('Usage: node rebrand/apply.cjs --apply | --check');
+  process.exit(1);
+}
+const changes = new Map();
+function update(relative, content) {
+  const file = path.join(root, relative);
+  if (!fs.existsSync(file) || fs.readFileSync(file, 'utf8') !== content) changes.set(relative, content);
+}
+function transform(content, relative) {
+  // Agent Skills is also the name of an independent specification.
+  const standard = '__I3_AGENT_SKILLS_STANDARD__';
+  let result = content
+    .replace('agents working on the [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills) repository itself',
+      'agents working on the i3 Composer Agent repository itself, derived from [`addyosmani/agent-skills`](https://github.com/addyosmani/agent-skills)')
+    .replace(/Agent Skills(?=\s+(?:specification|spec\b|format\b|standard\b))/g, standard)
+    .replaceAll('addy-agent-skills', brand.name)
+    .replaceAll('agent-skills@addy-agent-skills', `${brand.name}@${brand.name}`)
+    .replaceAll('agent-skills@agent-skills', `${brand.name}@${brand.name}`)
+    .replaceAll('agent-skills:', `${brand.name}:`)
+    .replaceAll('/path/to/agent-skills', `/path/to/${brand.name}`)
+    .replaceAll('./agent-skills', `./${brand.name}`)
+    .replace(/(?<![\w/.-])agent-skills(?![\w-])/g, brand.name)
+    .replaceAll('Agent Skills', brand.displayName)
+    .replaceAll(standard, 'Agent Skills');
+  if (relative.startsWith('docs/')) {
+    result = result.split('\n').map(line => {
+      if (/^\s*git clone https:\/\/github\.com\/addyosmani\/agent-skills(?:\.git)?\s*$/.test(line)) {
+        return `${line.match(/^\s*/)[0]}npx ${brand.npmName} --extract --dir ./${brand.name}`;
+      }
+      if (/^\s*(?:npx |codex |copilot |cmd |agy |gemini |\/plugin )/.test(line)) {
+        return line.replaceAll('https://github.com/addyosmani/agent-skills.git', `/path/to/${brand.name}`)
+          .replaceAll('https://github.com/addyosmani/agent-skills', `/path/to/${brand.name}`)
+          .replaceAll('addyosmani/agent-skills', `/path/to/${brand.name}`);
+      }
+      return line;
+    }).join('\n');
+    result = result
+      .replace(/^cmd skills add \/path\/to\/i3-composer-agent@main[^\n]*$/gm,
+        '# Branch selectors apply to Git sources; prepared npm bundles have no Git history.')
+      .replaceAll('Clone the repository', 'Prepare the plugin bundle')
+      .replaceAll('Clone this repository', 'Prepare the plugin bundle')
+      .replaceAll('Install from the remote repository', 'Install from a prepared local bundle')
+      .replaceAll('npx skills add addyosmani/agent-skills', `npx skills add /path/to/${brand.name}`)
+      .replaceAll('plugin marketplace add addyosmani/agent-skills', `plugin marketplace add /path/to/${brand.name}`)
+      .replaceAll('~/.gemini/config/plugins/agent-skills/', `~/.gemini/config/plugins/${brand.name}/`)
+      .replaceAll('.cursor/rules/agent-skills.mdc', `.cursor/rules/${brand.name}.mdc`)
+      .replace(/\[[^\]]+\]\(https:\/\/github\.com\/addyosmani\/agent-skills\/issues\/(\d+)\)/g,
+        (_, issue) => `[upstream agent-skills #${issue}](https://github.com/addyosmani/agent-skills/issues/${issue})`);
+  }
+  return result;
+}
+const skipDirectories = new Set(['.git', 'node_modules', 'rebrand', 'dist', 'tests', 'bin']);
+const skipFiles = new Set(['LICENSE', 'NOTICE.md', 'package.json', 'README.md', 'evals/README.md', 'evals/skill-impact.md', 'docs/comparison.md', 'scripts/validate-brand.cjs', 'scripts/lib/skill-lint.js', 'scripts/lib/skill-lint-test.js']);
+function walk(directory, prefix = '') {
+  for (const entry of fs.readdirSync(directory, { withFileTypes: true })) {
+    const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      if (!skipDirectories.has(entry.name) && !relative.startsWith('evals/results')) walk(path.join(directory, entry.name), relative);
+    } else if (entry.isFile() && !skipFiles.has(relative) && /\.(?:md|js|cjs|sh|toml|yml)$/.test(entry.name)) {
+      const original = fs.readFileSync(path.join(root, relative), 'utf8');
+      update(relative, transform(original, relative));
+    }
+  }
+}
+walk(root);
+const comparisonPath = 'docs/comparison.md';
+const comparison = fs.readFileSync(path.join(root, comparisonPath), 'utf8');
+if (!comparison.includes('> **Upstream research:**')) {
+  const note = `> **Upstream research:** This comparison is retained from Addy Osmani's \`agent-skills\` at commit \`${brand.upstreamCommit}\`. Its experiments describe the upstream project; they are not independent evaluations of ${brand.displayName}.\n\n`;
+  update(comparisonPath, comparison.replace('# How agent-skills compares\n\n', '# How agent-skills compares\n\n' + note));
+}
+for (const relative of ['plugin.json', '.claude-plugin/plugin.json', '.codex-plugin/plugin.json']) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, relative), 'utf8'));
+  manifest.name = brand.name;
+  manifest.description = brand.description;
+  if (manifest.author) manifest.author = { name: brand.maintainer };
+  delete manifest.homepage;
+  delete manifest.repository;
+  if (manifest.interface) {
+    manifest.interface.displayName = brand.displayName;
+    manifest.interface.developerName = brand.maintainer;
+    manifest.interface.shortDescription = 'Engineering workflow skills';
+    manifest.interface.longDescription = `${brand.displayName} packages 25 engineering skills from Addy Osmani's Agent Skills, covering requirements, planning, implementation, testing, review, and shipping.`;
+    manifest.interface.defaultPrompt = manifest.interface.defaultPrompt.map(prompt => prompt.replaceAll('Agent Skills', brand.displayName));
+  }
+  update(relative, JSON.stringify(manifest, null, 2) + '\n');
+}
+for (const relative of ['.claude-plugin/marketplace.json', '.agents/plugins/marketplace.json']) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(root, relative), 'utf8'));
+  manifest.name = brand.name;
+  if (manifest.description) manifest.description = brand.description;
+  if (manifest.owner) manifest.owner = { name: brand.maintainer };
+  if (manifest.interface) manifest.interface.displayName = brand.displayName;
+  for (const plugin of manifest.plugins) {
+    plugin.name = brand.name;
+    plugin.description = brand.description;
+    plugin.source = relative.startsWith('.agents/') ? { source: 'local', path: './' } : './';
+    delete plugin.homepage;
+  }
+  update(relative, JSON.stringify(manifest, null, 2) + '\n');
+}
+for (const [relative, template] of [
+  ['README.md', 'README.md'], ['docs/codex-setup.md', 'codex-setup.md'], ['docs/codebuddy-setup.md', 'codebuddy-setup.md'],
+]) {
+  update(relative, fs.readFileSync(path.join(__dirname, 'templates', template), 'utf8'));
+}
+if (mode === '--apply') for (const [relative, content] of changes) {
+  fs.mkdirSync(path.dirname(path.join(root, relative)), { recursive: true });
+  fs.writeFileSync(path.join(root, relative), content);
+}
+console.log(JSON.stringify({ mode, changedFiles: [...changes.keys()] }, null, 2));
+if (mode === '--check' && changes.size) process.exitCode = 1;

package/rebrand/brand.json

@@ -0,0 +1,9 @@
+{
+  "name": "i3-composer-agent",
+  "displayName": "i3 Composer Agent",
+  "npmName": "@givolt/i3-composer-agent",
+  "maintainer": "Givolt",
+  "upstream": "https://github.com/addyosmani/agent-skills",
+  "upstreamCommit": "1401c8b",
+  "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship."
+}