@mycodemap/mycodemap 1.9.0 → 2.0.0

package/docs/ideation/2026-04-29-ux-install-agent-experience-ideation.md

@@ -0,0 +1,256 @@
+# Ideation: CodeMap User Experience, Installation/Configuration, and Human vs AI Agent Experience
+
+**Date:** 2026-04-29  
+**Focus:** User experience, installation and configuration experience, human vs AI agent experience  
+**Run ID:** 9e3b69d4496d7cc8  
+**Agents dispatched:** 9 (codebase scan + learnings + web research + 6 ideation frames)
+
+---
+
+## Grounding Summary
+
+### Codebase Context
+CodeMap is a TypeScript/Node.js ESM CLI tool generating structured code maps (`AI_MAP.md`, `codemap.json`) for AI/Agent consumption. Uses `commander`, `tree-sitter`, `better-sqlite3`, `hono`. Layered architecture with `src/cli-new/` coexisting alongside `src/cli/`, signaling migration in progress. Heavy AI-agent governance docs (`AGENTS.md`, `CLAUDE.md`, `.claude/`, `.kimi/`, `.agents/`).
+
+### Key Pain Points
+- **Native dependency install friction** (`better-sqlite3`, `tree-sitter` often fail without build tools) — #1 drop-off point
+- **Broken promises in `package.json`** (`check:architecture`, `check:unused` are no-ops)
+- **Dual CLI confusion** (`cli/` + `cli-new/`)
+- **MCP underpowered** (only 2 tools: `codemap_query`, `codemap_impact`)
+- **Agent interface inconsistency** (`--json` not uniform, silent failures, low confidence on explicit paths)
+- **Onboarding overload** — manual skill copying from `examples/`
+- **Agent dogfood rated 6/10** agent-friendly (2026-04-17)
+
+### Past Learnings
+- `init` redesigned as "project state reconciler" with `.mycodemap/` workspace (v1.7 shipped)
+- v0.5.1 install bug: `devDependencies` used at runtime caused global install crashes
+- CLI surface cleanup (v1.0): removed commands with explicit failure + migration messages
+- Three-layer readiness gate (`hard`/`warn-only`/`fallback`) from v1.11
+
+### External Context
+- CLI is beating MCP for coding agents in 2025-2026 due to token efficiency
+- Agent-native patterns: JSON-first, structured errors, predictable exit codes, field filtering, `--help-json`, progress on stderr
+- Prior art: `hubspot-cli` (dual entry point), `gdelt-cli` (machine-readable help), `discord-cli` (YAML structured output)
+- Snyk praised for smoothest onboarding (`snyk test` = seconds)
+- Research pain points: false positives up to 60%, lack of meaningful messages, configuration effort
+
+---
+
+## Raw Candidate Pool
+
+52 candidates generated across 6 ideation frames + 4 cross-cutting combinations. Full list preserved in checkpoint:
+`/tmp/compound-engineering/ce-ideate/9e3b69d4496d7cc8/raw-candidates.md`
+
+### Frame Summary
+| Frame | Count | Key Themes |
+|-------|-------|------------|
+| Pain and friction | 8 | Graceful degradation, presumptive onboarding, unified CLI, agent handshake, streaming MCP, confidence metadata, pre-install check, doctor |
+| Inversion/removal/automation | 8 | Zero-command install, config-as-cache, honest CLI, intent router, JSON-RPC daemon, auto-provisioned skills, failure-to-action, CLI-as-MCP gateway |
+| Assumption-breaking | 8 | Zero-install runtime, split human/agent interface, self-healing init, SDK mode, confidence-first output, progressive disclosure, git-native maps, declarative contract |
+| Leverage/compounding | 8 | WASM-first build, auto-reconciling state, interface contract architecture, zero-config preview, structured errors, skill ecosystem, agent-native mode, uncertainty budget |
+| Cross-domain analogy | 8 | Auto-mode installer, RPG onboarding, Netflix recommendations, language server daemon, tasting menu presets, accessibility profiles, pairing mode, confidence routing |
+| Constraint-flipping | 8 | 100ms install, self-teaching CLI, AI-first default, fingerprint config, unconfigurable tool, MCP-primary, concierge daemon, self-healing promise |
+
+---
+
+## Explicit Rejections (Why These Did Not Survive)
+
+### Rejected: Incremental / Already In Progress
+- **Unified CLI Surface with Subcommand Shadows** — Addresses real pain but is essentially "finish the cli-new migration," already in progress. Not an ideation breakthrough.
+- **Presumptive Onboarding / Config Proposed Not Asked** — Overlaps with existing v1.7 init reconciler design; less precise than Zero-Config Preview.
+- **Streaming MCP with Progress Tokens** — Good but naturally follows from CLI-as-MCP Gateway; not a standalone priority.
+
+### Rejected: Over-Engineered / Heavy Solutions to Simple Problems
+- **Agent Handshake Protocol** — Over-engineered for the actual problem: inconsistent `--json` and silent failures. A formal pre-command negotiation adds complexity; explicit flags/env vars are simpler.
+- **Smart Home "Pairing Mode" Auto-Negotiation** — Auto-detecting agent vs human is fragile (env vars, parent process names). Explicit `--agent` or `CODEMAP_MACHINE=1` is more reliable.
+- **Intent-Based Unified Router / Natural Language** — "Map my backend API surface" is cool but adds NLP complexity for marginal gain over good subcommand naming.
+
+### Rejected: Too Speculative / Missing Prerequisites
+- **100ms Install Mandate: Pure-JS Mode** — More extreme than WASM-first. Node 22+ `node:sqlite` is not universally available. Pure-JS tree-sitter grammar pack doesn't exist yet.
+- **The Embedded CodeMap / SDK Mode** — Powerful but scope explosion. If WASM-first happens, SDK mode becomes natural. Doing both simultaneously is too much.
+- **10x Budget: Agent Concierge Mode / Daemon + IDE Extension** — Visionary but the project already deferred viz/TUI/API (MVP3 PRD). A daemon is an architectural commitment for a future milestone.
+- **No Users, Only Agents: MCP as Primary Interface** — Inverts reality: the CLI exists and works. Making MCP primary would discard human UX investment.
+
+### Rejected: Provocative but Not Actionable
+- **Team of One: The Unconfigurable Tool** — Radical convention-over-configuration that would alienate power users and non-standard projects.
+- **Self-Correcting CLI Surface / Honest CLI** — "CLI audits itself on startup" is harder to implement and explain than a `doctor` command. Overlaps with #7 survivor.
+- **The Declarative Project Contract / codemap.yaml** — Overlaps with existing `.mycodemap/config.json` approach. YAML doesn't add enough value to justify migration.
+
+### Rejected: Framing Devices, Not Technical Directions
+- **Video Game Accessibility Profiles** — Good analogy but essentially combines "split interface" + "AI-first default" into a framing device.
+- **RPG "First Quest" Tutorial Onboarding** — UX polish framing of Zero-Config Preview. The tutorial aspect is surface, not architecture.
+- **Fine Dining "Tasting Menu" Presets** — Same as accessibility profiles; a UX framing of modes that already exist in other forms.
+- **Airport Customs "Green Lane / Red Lane"** — Clever analogy but confidence routing is already captured by Confidence-First Output.
+
+### Rejected: Overlap with Stronger Survivors
+- **Pre-Install Environment Contract Check** — Narrower than WASM-first; solves same problem less completely.
+- **The Self-Healing Init** — Covered by existing init reconciler + doctor command.
+- **Auto-Reconciling Project State** — Extension of existing v1.7 init reconciler; incremental, not breakthrough.
+- **Netflix "Because You Watched" Config Recommendations** — Incremental enhancement to init; not a distinct direction.
+- **Structured Error Recovery Protocol** — Overlaps heavily with Failure-to-Action Protocol.
+- **Configuration as a Cache, Not a Contract** — Interesting reframing but risks making configuration opaque and hard to debug.
+- **Agent-Native Streaming Protocol / JSON-RPC Daemon** — High complexity; daemon mode deferred per project scope.
+- **No Docs Allowed: The Self-Teaching CLI** — Framing device; interactive help is a feature, not a strategic direction.
+- **1M Users, Zero Support: Auto-Configured by Fingerprint** — Overlaps with Zero-Config Preview + existing init reconciler.
+
+---
+
+## Top Survivors (Ranked)
+
+### 1. Machine-Readable Interface Contract as Core Architecture
+**Source:** Leverage frame  
+**Idea:** Define the entire CLI surface as a formal schema (commands, args, flags, output shapes, error codes) in a single source-of-truth file. Generate the human CLI parser, the MCP server, `--help-json`, shell completions, and documentation from this schema. Never hand-write argument parsing or output formatting again.
+
+**Why it survived:**
+- **Highest leverage:** Every new command automatically gets full agent support, MCP exposure, and perfect consistency.
+- **Addresses root cause:** `--json` inconsistency, MCP underpoweredness, and agent-friendly 6/10 rating all stem from hand-maintained dual surfaces.
+- **Compounding:** As the CLI grows, the benefit multiplies. Adding one schema entry creates CLI flag, MCP tool, help text, and completion in one shot.
+- **Grounded:** Agent-native patterns from external research explicitly demand JSON-first, structured errors, and `--help-json`. This makes them free.
+
+**Risks:** Upfront schema design effort; migration of existing commands. Mitigation: incremental adoption, one command at a time.
+
+---
+
+### 2. WASM-First Build, Native-Opt-In Runtime
+**Source:** Leverage frame / Constraint-flip frame  
+**Idea:** Ship `tree-sitter` and `better-sqlite3` as WASM modules by default; detect and opportunistically upgrade to native binaries only when the environment supports it and the user opts in. `npm install codemap` works on every platform, every CI image, every fresh laptop with zero build tools.
+
+**Why it survived:**
+- **#1 pain point killer:** Native dependency install friction is the top drop-off point. This eliminates it entirely.
+- **Proven pattern:** esbuild's WASM fallback mode works in the same ecosystem. `web-tree-sitter` exists. Node 22 ships `node:sqlite` built-in.
+- **Platform coverage:** Reaches 100% of users instead of 70% who have build tools installed.
+- **Agent value:** Eliminates environment-dependent failures that break automated workflows.
+
+**Risks:** Performance regression for very large repos. Mitigation: native opt-in for performance-sensitive users; benchmark WASM vs native.
+
+---
+
+### 3. CLI-as-MCP Automatic Gateway
+**Source:** Inversion frame  
+**Idea:** Implement a generic `--mcp-stdio` adapter that dynamically exposes every CodeMap CLI subcommand as an MCP tool with auto-generated JSON schemas derived from TypeScript types (or the Interface Contract schema). Adding a new CLI command instantly creates a new MCP tool with zero extra work. The entire CLI surface becomes the MCP surface.
+
+**Why it survived:**
+- **Closes the integration gap:** MCP is currently underpowered (2 tools) while CLI has 20+ commands. Agents route around MCP to CLI because of this.
+- **Eliminates drift:** No more hand-maintained MCP server that lags behind CLI features.
+- **Depends on #1:** Best paired with Interface Contract architecture, but can start with TypeScript type reflection.
+- **High agent impact:** Transforms MCP from a second-class citizen into a first-class, complete interface.
+
+**Risks:** MCP schema generation must handle complex nested types. Mitigation: start with simple commands, iterate.
+
+---
+
+### 4. AI-First Default, Human-Pretty Optional
+**Source:** Constraint-flip frame / Assumption-breaking frame  
+**Idea:** Flip the output paradigm. All commands emit structured JSON/NDJSON on stdout by default. A `--human` flag (or auto-detected TTY) pipes through a built-in renderer for tables, spinners, and color. Progress goes to stderr as structured events. This makes the CLI natively composable for agents without special flags.
+
+**Why it survived:**
+- **Directly fixes agent inconsistency:** The current `--json` bolt-on is inconsistent across commands. Making structured output the default forces consistency.
+- **External evidence:** Research confirms CLI beats MCP for token efficiency when structured. This maximizes that advantage.
+- **Low implementation risk:** TTY detection is standard; renderers can be built incrementally.
+- **Composable:** `codemap analyze | jq '.findings[] | select(.severity=="high")'` works out of the box.
+
+**Risks:** Breaking change for existing human users who expect pretty output. Mitigation: major version bump; TTY auto-detection preserves current behavior for interactive use.
+
+---
+
+### 5. Zero-Config Preview / Progressive Commitment Model
+**Source:** Leverage frame / Cross-domain analogy  
+**Idea:** `npx codemap` with no config, no init, no flags performs a full analysis and emits a rich preview (top-level summary, detected project type, sample map). It then offers: "Looks good? Run `codemap --persist` to save configuration and generate full artifacts." No setup, no decisions, no config files until the user sees value.
+
+**Why it survived:**
+- **Snyk-inspired:** Snyk is praised for smoothest onboarding because `snyk test` demonstrates value in seconds.
+- **Low implementation cost:** Can be built on top of existing init reconciler and analysis pipeline.
+- **High conversion impact:** Removes the fear of side effects from trying the tool.
+- **Dual audience:** Humans see a preview and decide; agents can run `--persist` non-interactively.
+
+**Risks:** Preview must be fast (<5 seconds) or it backfires. Mitigation: default to shallow/symbolic scan for preview; deep analysis on demand.
+
+---
+
+### 6. Failure-to-Action Protocol
+**Source:** Inversion frame / Leverage frame  
+**Idea:** Every error returns a structured document containing: what was attempted, the root cause, a machine-readable remediation plan, and a confidence score. For native dep failures: auto-suggest `--wasm-fallback` or a prebuilt binary URL. For agents, errors include the exact next command to try. Errors become state transitions, not dead ends.
+
+**Why it survived:**
+- **Addresses silent failures:** The dogfood report explicitly found `analyze -i find` failing silently with near-empty JSON. This makes every failure explicit and actionable.
+- **Research-backed:** Studies cite "lack of meaningful messages" as a top pain point for code analysis tools.
+- **Agent self-healing:** Agents can attempt remediation without human intervention.
+- **Incremental:** Can be adopted command by command; doesn't require a big-bang rewrite.
+
+**Risks:** Remediation suggestions can be wrong, creating cascading failures. Mitigation: confidence scoring on suggestions; never auto-execute without `--apply-suggestion`.
+
+---
+
+### 7. codemap doctor as Continuous Health Monitor
+**Source:** Pain frame / Constraint-flip frame  
+**Idea:** A living diagnostics command that audits the entire CodeMap ecosystem: detects no-op scripts in `package.json` (`check:architecture`, `check:unused`), verifies native dep health, checks `.mycodemap/` workspace drift, validates CLI vs MCP version skew, and runs agent interface regression checks. Emits both human-readable reports and machine-readable diagnostics. Can run in CI as a health gate.
+
+**Why it survived:**
+- **Familiar pattern:** `npm doctor`, `brew doctor`, `flutter doctor` — users know what to expect.
+- **Addresses broken promises directly:** Surfaces the no-op scripts and other latent brokenness that erodes trust.
+- **CI-friendly:** Machine-readable output enables automated health checks in CI pipelines.
+- **Incremental:** Each diagnostic is a small addition; the command grows over time.
+
+**Risks:** Can become a dumping ground for random checks. Mitigation: categorize diagnostics (install, config, runtime, agent); require evidence tags for each check.
+
+---
+
+### 8. Auto-Provisioned Agent Skills / Self-Distributing Integration
+**Source:** Inversion frame  
+**Idea:** When CodeMap detects it is being invoked by an AI agent (via `KIMI_`, `CLAUDE_`, or `CODEX_` env vars), it automatically writes or updates the appropriate skill files into the agent's skill directory (`.claude/skills/codemap/`, `.kimi/skills/codemap/`). The tool maintains its own bindings, ensuring agents always use the latest integration layer.
+
+**Why it survived:**
+- **Directly solves onboarding overload:** "Manual skill copying from `examples/`" is explicitly cited as a pain point.
+- **Self-describing:** CodeMap knows its own CLI schema better than any human; it should generate its own agent integration.
+- **Version safety:** Skills stay in sync with the installed CodeMap version.
+- **Low cost if paired with #1 and #3:** If we have an interface contract and auto-generated MCP, skill generation is a thin layer on top.
+
+**Risks:** Overwriting user-customized skill files. Mitigation: write to `.mycodemap/skills/` and symlink/copy to agent dirs; never modify existing files without `--force`.
+
+---
+
+## Cross-Cutting Synthesis
+
+Three meta-patterns emerge from the survivors:
+
+### A. Self-Describing Universal API (#1 + #3 + #8)
+If the CLI surface is defined as a machine-readable contract, then:
+- The MCP server generates automatically (#3)
+- Agent skills generate automatically (#8)
+- `--help-json`, shell completions, and docs generate automatically (#1)
+- Every new CLI command is instantly agent-ready
+
+This is the **highest-compounding architectural bet** in the entire ideation set.
+
+### B. Zero-Friction Installation & Onboarding (#2 + #5)
+WASM-first eliminates install failures (#2). Zero-config preview eliminates configuration anxiety (#5). Together they create a "Snyk-class" onboarding where a new user goes from "heard about it" to "seeing value" in under 10 seconds with zero prerequisites.
+
+### C. Trust Architecture (#6 + #7 + confidence implications of #1)
+Failure-to-action protocol makes errors recoverable (#6). Doctor command continuously audits health (#7). Interface contract ensures output schemas are predictable (#1). Together they address the agent-friendly 6/10 rating by making the tool transparent, honest, and self-healing.
+
+---
+
+## Ideas by Dimension
+
+| Dimension | Top Idea |
+|-----------|----------|
+| **Workflow / DX** | Zero-Config Preview (#5) — demonstrates value before asking commitment |
+| **Reliability** | WASM-First Build (#2) — eliminates #1 source of install failures |
+| **Extensibility** | Interface Contract Architecture (#1) — every new feature is agent-ready by construction |
+| **Missing capabilities** | CLI-as-MCP Gateway (#3) — closes the 2-tool gap |
+| **Docs / Knowledge compounding** | Auto-Provisioned Skills (#8) — self-generating agent integration |
+| **Quality / Maintenance** | codemap doctor (#7) — continuous health monitoring |
+| **Agent experience** | AI-First Default (#4) — JSON-first, consistent, composable |
+| **Error handling** | Failure-to-Action Protocol (#6) — structured, recoverable errors |
+
+---
+
+## Next Steps Menu
+
+This ideation artifact identifies promising directions. The next step depends on what you want to do with these ideas:
+
+1. **Refine** — Deep-dive into one or more survivors, exploring edge cases, implementation approaches, and interdependencies.
+2. **Brainstorm** — Select one survivor and define it precisely enough for planning (requirements, boundaries, acceptance criteria). This hands off to `ce:brainstorm`.
+3. **Save and end** — Archive this ideation and return to it later when priorities shift.
+
+> **Routing note:** `ce:ideate` answers "What are the strongest ideas worth exploring?" `ce:brainstorm` answers "What exactly should one chosen idea mean?" `ce:plan` answers "How should it be built?" Do not skip to planning from ideation output.

package/docs/plans/2026-04-30-install-guide-and-repo-analyzer-design.md

@@ -0,0 +1,394 @@
+# 安装引导增强 + mycodemap-repo-analyzer 技能 实施计划
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** 增强 mycodemap 的 AI CLI 安装引导体验，并新增基于 repo-analyzer 的深度架构分析技能
+
+**Architecture:** 需求1 在现有 `docs/AI_ASSISTANT_SETUP.md` 中增加 "AI CLI 一键安装引导" 章节；需求2 在 `examples/claude/skills/mycodemap-repo-analyzer/` 下创建衍生 skill，基于 repo-analyzer 的 8 阶段流程，替换执行层面操作为 mycodemap CLI
+
+**Tech Stack:** Markdown, mycodemap CLI, Claude Code skill format
+
+---
+
+## 前置说明
+
+### 关键发现
+
+1. **`docs/AI_ASSISTANT_SETUP.md` 已存在** — 当前是面向人类的分平台配置指南（Kimi/Claude/Codex/Copilot），需要在其基础上增加"AI CLI 一键安装引导"章节，而非创建新文件
+2. **现有 skill 文件** — `examples/claude/codemap-skill.md` 和 `examples/codex/codemap-agent.md` 是基础 skill 模板；`.claude/skills/codemap/SKILL.md` 是当前项目实际使用的完整 skill
+3. **README.md 已有 AI 文档索引** — 第 99-117 行有 "AI / Agent 专属文档" 章节，需在此增加新 skill 的链接
+
+### 文件路径约定
+
+| 文件 | 说明 |
+|------|------|
+| `docs/AI_ASSISTANT_SETUP.md` | 现有 AI 助手配置指南，需追加"一键安装引导"章节 |
+| `examples/claude/skills/mycodemap-repo-analyzer/SKILL.md` | 新增：衍生 skill 主文件 |
+| `examples/claude/skills/mycodemap-repo-analyzer/references/analysis-guide.md` | 新增：分析哲学（从 repo-analyzer 保留） |
+| `examples/claude/skills/mycodemap-repo-analyzer/references/module-analysis-guide.md` | 新增：模块分析指南（从 repo-analyzer 保留） |
+| `README.md` | 修改：AI 文档索引章节增加链接 |
+
+---
+
+### Task 1: 创建 mycodemap-repo-analyzer skill 目录结构
+
+**Files:**
+- Create: `examples/claude/skills/mycodemap-repo-analyzer/SKILL.md`
+- Create: `examples/claude/skills/mycodemap-repo-analyzer/references/analysis-guide.md`
+- Create: `examples/claude/skills/mycodemap-repo-analyzer/references/module-analysis-guide.md`
+
+**Step 1: 创建目录**
+
+```bash
+mkdir -p examples/claude/skills/mycodemap-repo-analyzer/references
+```
+
+**Step 2: 拷贝 references 文件**
+
+从 repo-analyzer 原版保留 analysis-guide.md 和 module-analysis-guide.md，不做修改。
+
+```bash
+# 从 GitHub 获取原版文件内容，写入本地
+gh api repos/yzddmr6/repo-analyzer/contents/skills/repo-analyzer/references/analysis-guide.md -q '.content' | base64 -d > examples/claude/skills/mycodemap-repo-analyzer/references/analysis-guide.md
+
+gh api repos/yzddmr6/repo-analyzer/contents/skills/repo-analyzer/references/module-analysis-guide.md -q '.content' | base64 -d > examples/claude/skills/mycodemap-repo-analyzer/references/module-analysis-guide.md
+```
+
+**Step 3: 验证文件**
+
+```bash
+ls -la examples/claude/skills/mycodemap-repo-analyzer/references/
+wc -l examples/claude/skills/mycodemap-repo-analyzer/references/*.md
+```
+
+Expected: 两个文件均存在，各 100-300 行
+
+**Step 4: Commit**
+
+```bash
+git add examples/claude/skills/mycodemap-repo-analyzer/references/
+git commit -m "feat: add repo-analyzer reference docs (unmodified from upstream)"
+```
+
+---
+
+### Task 2: 编写 mycodemap-repo-analyzer SKILL.md
+
+**Files:**
+- Create: `examples/claude/skills/mycodemap-repo-analyzer/SKILL.md`
+
+**Step 1: 编写 SKILL.md**
+
+基于 repo-analyzer 原版 SKILL.md，关键改动点：
+
+1. **frontmatter**：`name: mycodemap-repo-analyzer`，触发词加 `mycodemap` 前缀
+2. **阶段1**：git clone 后增加 `mycodemap generate` 生成 AI_MAP.md 作为分析基础
+3. **阶段2**：从 AI_MAP.md 读取模块统计替代手动 `find + wc`
+4. **阶段4**：增加 `mycodemap query/deps/cycles/complexity` 快速获取架构特征
+5. **阶段6**：subagent prompt 增加 mycodemap CLI 使用指令
+6. **阶段7**：增加 `mycodemap impact` 辅助交叉验证
+
+文件内容要点：
+
+```markdown
+---
+name: mycodemap-repo-analyzer
+description: Use when the user mentions "mycodemap 分析项目"、"mycodemap 架构分析"、"mycodemap 项目分析"、"mycodemap 源码分析"、"mycodemap 学习这个项目"、"mycodemap 研究这个框架"
+---
+
+# MyCodeMap 项目深度分析技能
+
+[保留 repo-analyzer 的核心原则、When to Use/Not to Use、输出语言]
+
+## 核心原则
+[同原版 5 条核心原则，不变]
+
+## 分析工作流
+
+### 阶段 1: 项目获取与初始化（改动）
+1. 解析输入（同原版）
+2. 创建工作区（同原版）
+3. git clone（同原版）
+4. **[新增]** 在项目目录运行 `mycodemap generate` 生成代码地图
+5. **[新增]** 阅读 `.mycodemap/AI_MAP.md` 获取项目结构概览
+6. 获取基本元数据（同原版）
+
+### 阶段 2: 项目规模评估（改动）
+1. **[替换]** 从 `.mycodemap/AI_MAP.md` 读取模块列表和代码统计
+2. **[替换]** 用 `mycodemap complexity` 获取复杂度分布
+3. 向用户报告并选择分析模式（同原版）
+4. 写入 drafts/03-plan.md（同原版）
+
+### 阶段 3: 外部调研（不变）
+[同原版]
+
+### 阶段 4: 项目特征识别（改动）
+1. 快速扫描（同原版）
+2. **[增强]** 用 mycodemap CLI 加速特征识别：
+   - `mycodemap deps` 查看模块依赖拓扑
+   - `mycodemap cycles` 检测循环依赖
+   - `mycodemap complexity` 了解复杂度热点
+3. 从特征中提炼问题（同原版）
+4. 向用户提问（同原版）
+
+### 阶段 5: 动态报告结构设计（不变）
+[同原版]
+
+### 阶段 6: 并行深度分析（改动）
+subagent prompt 模板增加：
+- **[新增]** 使用 mycodemap CLI 辅助分析：
+  - `mycodemap query -s "<symbol>"` 查询核心符号
+  - `mycodemap query -m "<module>"` 获取模块上下文
+  - `mycodemap analyze --intent overview -t "<path>"` 获取模块概览
+- **[替换]** 优先用 mycodemap 获取结构化信息，减少逐文件 Read
+
+### 阶段 7: 交叉验证（改动）
+1-3. 覆盖率门控/抽查验证（同原版）
+4. **[增强]** 用 `mycodemap impact -f "<file>"` 验证跨模块影响结论
+5. 写入 drafts/07-cross-validation.md（同原版）
+
+### 阶段 8: 最终报告（不变）
+[同原版]
+
+[其余章节：草稿文件清单、特殊场景、输出要求 — 同原版]
+```
+
+**Step 2: 验证文件**
+
+```bash
+wc -l examples/claude/skills/mycodemap-repo-analyzer/SKILL.md
+grep -c "mycodemap" examples/claude/skills/mycodemap-repo-analyzer/SKILL.md
+```
+
+Expected: 300-500 行，mycodemap 出现 10+ 次
+
+**Step 3: Commit**
+
+```bash
+git add examples/claude/skills/mycodemap-repo-analyzer/SKILL.md
+git commit -m "feat: add mycodemap-repo-analyzer skill with CLI integration"
+```
+
+---
+
+### Task 3: 增强 AI_ASSISTANT_SETUP.md — 增加一键安装引导章节
+
+**Files:**
+- Modify: `docs/AI_ASSISTANT_SETUP.md`
+
+**Step 1: 在文件末尾（"参考"章节之前）增加新章节**
+
+章节标题：`AI CLI 一键安装引导`
+
+内容结构：
+
+```markdown
+## AI CLI 一键安装引导
+
+> 本章节面向 AI CLI 工具（Claude Code、Codex CLI 等），提供结构化安装引导。
+> 当用户说"帮我安装 mycodemap"时，AI CLI 应按照以下步骤引导。
+
+### Step 1: 前置条件检查 [CONFIRM]
+
+在开始安装前，确认以下条件：
+
+- Node.js >= 18 是否已安装（`node --version`）
+- 当前项目是否有 package.json（`ls package.json`）
+- 向用户确认：是项目级别安装还是全局安装
+
+### Step 2: 安装依赖 [CONFIRM]
+
+```bash
+# 项目级别安装（推荐）
+npm install @mycodemap/mycodemap
+
+# 或全局安装
+npm install -g @mycodemap/mycodemap
+```
+
+### Step 3: 初始化 [CONFIRM]
+
+```bash
+# 先预览配置（不写入文件）
+mycodemap init
+
+# 确认后写入
+mycodemap init -y
+```
+
+### Step 4: 生成代码地图
+
+```bash
+mycodemap generate
+```
+
+安装完成后会生成：
+- `.mycodemap/AI_MAP.md` — 项目全局概览
+- `.mycodemap/codemap.json` — 结构化数据
+- `.mycodemap/CONTEXT.md` — 上下文入口
+
+### Step 5: 配置 AI 助手 skill [CONFIRM]
+
+根据使用的 AI 助手，拷贝对应的 skill 文件：
+
+**Claude Code:**
+```bash
+mkdir -p .claude/skills/codemap
+cp node_modules/@mycodemap/mycodemap/examples/claude/codemap-skill.md .claude/skills/codemap/SKILL.md
+
+# 可选：安装架构分析技能
+mkdir -p .claude/skills/mycodemap-repo-analyzer
+cp node_modules/@mycodemap/mycodemap/examples/claude/skills/mycodemap-repo-analyzer/SKILL.md .claude/skills/mycodemap-repo-analyzer/SKILL.md
+cp -r node_modules/@mycodemap/mycodemap/examples/claude/skills/mycodemap-repo-analyzer/references .claude/skills/mycodemap-repo-analyzer/
+```
+
+**Codex CLI:**
+```bash
+mkdir -p .agents/skills/codemap
+cp node_modules/@mycodemap/mycodemap/examples/codex/codemap-agent.md .agents/skills/codemap/SKILL.md
+```
+
+### Step 6: 更新项目 rules [CONFIRM]
+
+在项目的 `CLAUDE.md` 和 `AGENTS.md` 中追加以下内容：
+
+```markdown
+## CodeMap Skill
+
+### 何时使用
+- 需要理解项目整体结构或模块关系
+- 分析代码变更的影响范围
+- 查询符号定义、调用关系、依赖链
+- 评估代码复杂度或检测循环依赖
+
+### 何时不用
+- 简单的单文件修改或调试
+- 非代码文件操作（文档、配置等）
+- 已有明确上下文的局部改动
+
+### 如何使用
+- 参考 .claude/skills/codemap/ 中的 skill 指令
+- 使用 mycodemap CLI 命令（generate/query/impact/deps/cycles/complexity）
+
+### 索引维护
+- 代码变更后需运行 `mycodemap generate` 更新索引
+- 在重大功能开发/重构完成后，主动更新一次
+- 如发现 mycodemap 查询结果与代码不一致，先更新索引再使用
+```
+
+### Step 7: 验证安装
+
+```bash
+# 验证 CLI 可用
+mycodemap query --help
+
+# 验证 skill 文件已就位
+ls .claude/skills/codemap/SKILL.md
+```
+
+### 可选：MCP 服务器配置
+
+如需使用 MCP 协议与 AI 助手集成：
+
+```bash
+mycodemap generate --symbol-level
+mycodemap mcp install
+```
+```
+
+**Step 2: 验证文件**
+
+```bash
+grep -c "一键安装引导" docs/AI_ASSISTANT_SETUP.md
+grep -c "CONFIRM" docs/AI_ASSISTANT_SETUP.md
+```
+
+Expected: 一键安装引导出现 1 次，CONFIRM 出现 6 次
+
+**Step 3: Commit**
+
+```bash
+git add docs/AI_ASSISTANT_SETUP.md
+git commit -m "feat: add AI CLI one-click install guide to AI_ASSISTANT_SETUP.md"
+```
+
+---
+
+### Task 4: 更新 README.md — AI 文档索引增加新 skill 链接
+
+**Files:**
+- Modify: `README.md:99-117`（AI / Agent 专属文档章节）
+
+**Step 1: 在 AI 文档表格中增加一行**
+
+在第 114 行（`docs/AI_ASSISTANT_SETUP.md` 行）之后增加：
+
+```markdown
+| **[🔍 examples/claude/skills/mycodemap-repo-analyzer/](examples/claude/skills/mycodemap-repo-analyzer/)** | 项目深度架构分析技能（基于 repo-analyzer + mycodemap CLI） |
+```
+
+**Step 2: 验证**
+
+```bash
+grep "mycodemap-repo-analyzer" README.md
+```
+
+Expected: 1 行匹配
+
+**Step 3: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: add mycodemap-repo-analyzer skill link to README AI docs index"
+```
+
+---
+
+### Task 5: 端到端验证
+
+**Step 1: 验证安装引导文档可读性**
+
+```bash
+# 检查 AI_ASSISTANT_SETUP.md 中新增章节的格式
+grep -A 3 "一键安装引导" docs/AI_ASSISTANT_SETUP.md
+```
+
+**Step 2: 验证 skill 文件结构完整**
+
+```bash
+find examples/claude/skills/mycodemap-repo-analyzer -type f
+```
+
+Expected: 3 个文件（SKILL.md, analysis-guide.md, module-analysis-guide.md）
+
+**Step 3: 验证 SKILL.md 中 mycodemap 集成点**
+
+```bash
+grep "mycodemap" examples/claude/skills/mycodemap-repo-analyzer/SKILL.md | head -20
+```
+
+Expected: 阶段1/2/4/6/7 中都有 mycodemap 命令引用
+
+**Step 4: 运行文档检查**
+
+```bash
+npm run docs:check
+```
+
+Expected: 通过，无错误
+
+**Step 5: 最终 commit（如有修复）**
+
+```bash
+git add -A
+git commit -m "chore: fix docs check issues from install guide and skill additions"
+```
+
+---
+
+## 验证方案
+
+1. **安装引导**：用新的 AI CLI 会话，说"帮我安装 mycodemap"，验证 AI 能否按步骤引导完成
+2. **Rules 文本片段**：拷贝 Step 6 的内容到测试项目的 CLAUDE.md，验证格式和内容正确
+3. **repo-analyzer skill**：在 Claude Code 中安装 skill 后，说"mycodemap 分析项目 xxx"，验证 skill 激活和 mycodemap 命令调用
+4. **文档同步**：`npm run docs:check` 通过

package/docs/rules/README.md

@@ -12,6 +12,7 @@
 | 改分层、依赖方向、模块边界 | `architecture-guardrails.md` | `node dist/cli/index.js deps -m "<module>"` |
 | 改测试、fixture、测试文件布局 | `testing.md` | `npm test` |
 | 改 hooks、CI、验证顺序、repo-local guardrail | `validation.md` | `npm run docs:check` / `python3 scripts/validate-rules.py code --report-only` |
+| 改 harness、agent 控制、上下文分层、权限升级策略 | `harness.md` | `npm run docs:check` |
 | 改 agent 执行协议、CLI/CI 工程护栏 | `engineering-with-codex-openai.md` | `node dist/cli/index.js ci check-docs-sync` |
 | 改 `/release workflow`、milestone 绑定、确认门 | `release.md` | `npm run docs:check:pre-release` |
 | 改发布/打包 mechanics | `deployment.md` | `npm run build` / `npm run validate-pack` |

package/docs/rules/architecture-guardrails.md

@@ -26,9 +26,10 @@
 ```bash
 node dist/cli/index.js deps -m "src/domain"
 node dist/cli/index.js impact -f "src/interface/types/index.ts"
-npm run check:architecture
 ```
 
+> 架构依赖检查通过 `deps` 命令完成，不再使用单独的 npm script。
+
 ## 常见误区
 
 - `Server Layer` 是内部架构层，不等于公共产品面的 `mycodemap server`。