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

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,91 @@
 {
   "name": "@givolt/i3-composer-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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",
+    "CHANGELOG.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 rebrand/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",
+      "CHANGELOG.md"
+    ],
+    "upstreamVersion": "0.6.12",
+    "upstreamCommit": "1401c8b8030e023baeebb31781a6653fe8e93026",
+    "upstreamRepository": "https://github.com/addyosmani/agent-skills"
+  },
+  "version": "1.0.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/49780522/i3-composer-agent.git"
+  },
+  "homepage": "https://github.com/49780522/i3-composer-agent#readme"
+}

package/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "i3-composer-agent",
+  "version": "1.0.0",
+  "description": "Production-grade engineering skills for AI coding agents covering the development lifecycle from spec to ship.",
+  "homepage": "https://github.com/49780522/i3-composer-agent",
+  "repository": "https://github.com/49780522/i3-composer-agent"
+}

package/rebrand/MAINTENANCE.md

@@ -0,0 +1,112 @@
+# i3 Composer Agent 仓库维护
+
+本指南只适用于 Agent 仓库；GSD / i3 Composer Work 是另一个独立仓库。
+这里借鉴其维护方式，不复用其源码、安装产物或 Git 分支。
+
+## 仓库和分支
+
+- 品牌仓库：`https://github.com/49780522/i3-composer-agent`（Private）。
+- `origin` 指向品牌仓库；`upstream` 指向 `https://github.com/addyosmani/agent-skills.git`。
+- `agent/source`：原始上游源码与名称，加本项目 `rebrand/` 工具和规则。
+- `main`：经过重放与验证的品牌快照；npm 身份为 `@givolt/i3-composer-agent`。
+- `i3-composer-agent-v0.6.12`：已经发布的首次包所对应的原始品牌提交。
+
+源码工作树为 `/Users/howard/Workspace/composer-skills-source/agent-source`；
+品牌工作树为 `/Users/howard/Workspace/composer-skills-source/agent-skills`。
+旧的 Agent 本地 `i3/source` 分支已改为 `agent/source`，避免与 GSD 分支名称混淆。
+
+## 获取源码
+
+```bash
+git clone https://github.com/49780522/i3-composer-agent.git
+cd i3-composer-agent
+git remote add upstream https://github.com/addyosmani/agent-skills.git
+git fetch upstream --tags
+git worktree add --track -b agent/source ../agent-source origin/agent/source
+```
+
+源分支没有发行用的根 package.json。包入口、发行测试和配置由
+`rebrand/overlay/`、`package.template.json` 在品牌候选中生成。
+
+## 同步上游
+
+1. 在 Agent 源工作树获取上游，选择并审查一个明确的版本或提交。
+2. 从 `agent/source` 创建维护分支，合并该 ref 并解决源码冲突。
+3. 从同一 ref 记录上游目录和 Skill frontmatter；审查记录中的新增、删除和描述变化。
+4. 调整文字补丁、分发 overlay 和品牌模板；源码分支保持原始名称。
+5. 运行源验证，提交维护分支，通过 PR 合入 `agent/source`。
+6. 从更新后的源分支创建独立品牌候选工作树，重放、验证和打包。
+7. 将验证过的品牌快照通过发行 PR 更新 `main`；npm 发布单独执行。
+
+源维护阶段示例（把示例分支和 ref 替换为实际选定值）：
+
+```bash
+cd /Users/howard/Workspace/composer-skills-source/agent-source
+git fetch upstream --tags
+git switch -c sync/upstream-next agent/source
+git merge --no-commit --no-ff upstream/main
+# 审查并处理源码冲突后：
+node rebrand/record-upstream.cjs upstream/main
+node --test scripts/*-test.js scripts/lib/*-test.js rebrand/tests/*.test.cjs
+```
+
+记录工具读取 Git 对象中的上游文件，写入 `upstream.json` 和 `brand.json` 的基线。
+它不会把任意本地新增文件认定为上游。发布版本由 `brand.json.releaseVersion`
+控制，与 `upstream.json.upstreamVersion` 分开；按实际更改递增，保持六份清单一致。
+
+品牌版本从 `1.0.0` 开始使用独立编号；本次仅修改 i3，上游基线保留为 `0.6.12`。
+之后的当前基线以 `upstream.json` 记录为准。
+仅修改 i3 的修复或分发规则时，只递增品牌版本；上游版本和提交保持原值。
+README、CLI 帮助和准备完成提示同时显示这两个版本；`--version` 保留单一品牌版本输出。
+具体规则与历史版本处理见 [VERSIONING.md](VERSIONING.md)。
+
+## 创建品牌候选
+
+从源分支创建候选，每次换一个分支名和独立目录：
+
+```bash
+cd /Users/howard/Workspace/composer-skills-source/agent-skills
+git fetch origin
+git worktree add -b release/agent-next ../agent-candidate origin/agent/source
+cd ../agent-candidate
+bash rebrand/rebrand.sh --apply
+bash rebrand/rebrand.sh --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
+mkdir -p ../releases/next
+npm pack --pack-destination ../releases/next
+```
+
+在打包前先创建输出目录。对 tarball 重新解包，验证 CLI、完整文件目录及宿主清单。
+源码分支上执行 `--apply` 会在写入前失败；不得把未经重放的源分支直接更新到 `main`。
+源 PR 与发行 PR 的边界见 [PR-WORKFLOW.md](PR-WORKFLOW.md)。
+
+## 审查重放规则
+
+- `fork-patches.json`：明确的文字补丁，源文本不再匹配时失败，要求人工适配。
+- `overlay/`：本项目的 npm CLI、发行测试、品牌校验和发行 CI；上游相关文件改变时需合并审查。
+- `templates/`：品牌 README 和安装指南；上游对应说明改变时同步模板。
+- 目录数量、Skill 表、命令表和插件描述由已记录的目录生成，不固定为 25/9。
+- Skill frontmatter 保留原文；校验比较换行规范化后的哈希，兼容 LF/CRLF 检出。
+- LICENSE、NOTICE、真实上游链接、历史评估说明和标准名称保留。
+- 如果上游新增根 package.json，重放会失败，先适配分发配置和依赖再继续。
+
+## 发布及验收
+
+维护流程与安装能力分开验收。当前 npm CLI 准备文件并打印宿主注册命令；
+实际宿主安装范围、启用、命令执行以及交互向导仍需各自验证。
+Codex 的生命周期斜杠命令适配是独立工作，已有 Skill ID 不因维护流程改名。
+
+发布审核通过后，发布已经测过的 tarball，先使用试用标签，完成 registry 安装验证后再更新 latest：
+
+```bash
+npm publish /absolute/path/to/reviewed-package.tgz --access public --tag next
+npm dist-tag add @givolt/i3-composer-agent@<reviewed-version> latest
+```
+
+每个已发布包名和版本只用一次。GitHub Actions 与 GSD 品牌仓库一样先保持关闭，
+适配并验证 CI 后再启用。当前验证范围见 [VALIDATION.md](VALIDATION.md)。

package/rebrand/NOTICE.md

@@ -0,0 +1,9 @@
+# Attribution
+
+i3 Composer Agent is a branded distribution of
+[Agent Skills](https://github.com/addyosmani/agent-skills) by Addy Osmani.
+The initial distribution is based on upstream commit `1401c8b` (version 0.6.12).
+
+The original MIT license and copyright notice are preserved in LICENSE.
+Givolt maintains the branding, npm distribution, and bundle preparation CLI.
+The original skill IDs, command workflows, and persona definitions are retained.

package/rebrand/PR-WORKFLOW.md

@@ -0,0 +1,34 @@
+# Agent 源码与发行 PR
+
+此流程只操作 49780522/i3-composer-agent。GSD 仓库只是维护方法的参考。
+
+源码、修复和重放规则的 PR 以 `agent/source` 为 base，从该分支创建维护分支。
+保持上游文件的原始名称；本项目分发工具放在 `rebrand/`。
+
+```bash
+git fetch origin
+git worktree add -b fix/my-change ../agent-fix origin/agent/source
+cd ../agent-fix
+node --test scripts/*-test.js scripts/lib/*-test.js rebrand/tests/*.test.cjs
+```
+
+修改重放规则后，从维护提交另建品牌候选并执行 MAINTENANCE.md 中的完整验证。
+审查和暂存本次文件后提交，再推送并创建源码 PR：
+
+```bash
+git push -u origin fix/my-change
+gh pr create --base agent/source --head fix/my-change
+```
+
+源码 PR 合入后，从最新 `agent/source` 建立候选，重放、验证、打包并提交品牌内容。
+发行 PR 以 `main` 为 base；head 必须包含验证后的品牌快照。
+
+当 main 和源候选历史产生合并冲突时，从 main 创建发行 PR 分支，合入已验证的
+品牌候选并审查冲突。最终跟踪文件树必须与验证过的候选一致，然后提交：
+
+```bash
+git diff --cached <validated-candidate-commit>
+```
+
+上述差异应为空。若合并中需要实际代码调整，重新验证调整后的发行内容和 tarball。
+不要把原始 agent/source 直接作为发行 PR 的 head；不向 upstream 推送品牌提交。

package/rebrand/UNIFICATION-SPEC.md

@@ -0,0 +1,33 @@
+# Agent 项目维护流程统一
+
+用户已确认借鉴 GSD 项目维护方式，并要求项目互相独立。本规范只约束 Agent 仓库。
+
+## 目标与边界
+
+- `upstream` 指向 addyosmani/agent-skills；`origin` 指向私有品牌仓库 49780522/i3-composer-agent。
+- `agent/source` 保留上游原始名称和源码，在 `rebrand/` 保存本项目的分发工具与转换规则。
+- 候选从 `agent/source` 创建，在候选中重放；`main` 保存经过验证的品牌快照。
+- GSD 仓库只读，不使用它的源码、分支或安装产物。
+- Skill ID、流程命令内容、Persona、参考文件和 MIT 来源署名保持既有契约。
+- 本次完善源码同步和品牌重放；交互安装向导、Codex 命令适配及新的 npm 发布独立处理。
+
+## 实现与命令
+
+转换入口保持 Node.js 20+ 和零依赖：`node rebrand/apply.cjs --apply|--check`；另提供与 GSD 相同形式的 `bash rebrand/rebrand.sh` 入口。
+
+上游基线由 `node rebrand/record-upstream.cjs <明确的 ref>` 从 Git 对象记录；源码分支上运行 `node --test rebrand/tests/*.test.cjs`。候选执行 `npm run validate`、`npm test` 和既有路由/hook 检查。
+
+代码沿用 CommonJS、Node 内置 fs/path/assert。分发专属文件放在 `rebrand/overlay/`，发行包配置由模板生成，不把 branded README 或清单混入源码分支。
+
+## 验收条件
+
+1. 从干净上游源码及本项目规则能生成完整品牌包，重复重放不产生差异。
+2. 在 `agent/source` 上执行写入式重放必须失败且不修改源码。
+3. 记录上游新增 Skill/Command 后能生成相应清单和说明；删失或改写已记录 Skill ID 时校验失败。
+4. 上游的 25 个 Skill frontmatter、24 个非元 Skill、4 个 Persona、7 个共享参考保持原始内容；9 个流程只变品牌命名空间。
+5. 本地候选通过完整测试，并从打包结果运行 CLI 与校验。
+6. 独立品牌仓库中的源/发行分支及远程关系正确；首次发布标签保持原来的 0.6.12 提交。
+
+## 执行顺序
+
+先为源到品牌的重放、源码保护、目录增长与完整性写失败测试；实现工具及模板生成；验证真实上游归档；提交源分支；生成并审查品牌候选；最后建立远程并同步分支。