loom-init-project

name	loom-init-project
description	Bootstrap .loom/ context files for a new repository: constitution, structured memory, workflow, and agent entry files. Use when: initializing loom context for a repository that lacks .loom/ files or standard agent entry docs.
when_to_use	Bootstrap .loom context, workflow, memory, and agent entry files for a repository.
argument-hint	<project root>
user-invocable	true

项目初始化 Skill

• .loom/ 是唯一长期维护点，存放项目原则、结构化记忆和 workflow。
• AGENTS.md 是 Codex/OpenCode 等通用 agent 的标准入口。
• Claude、Cursor、Copilot 只接收薄 wrapper 或规则副本，避免多处规则漂移。
• 初始化尽量自动化；不确定的信息用 [TODO] 标记，交给用户确认。

触发条件

用户只需要说 /loom-init-project、初始化项目 或 扫描项目生成配置。

内部执行方式

触发本 skill 后，判断当前目录是不是项目根目录，如果不是根目录，询问用户是否在当前目录运行：

第一步：确认角色（多选）

如果用户没有明确指定角色，先询问这个项目给谁用（可多选，取并集）：

• pm：PM 视角，生成产品上下文 .loom/rules/product.md，走 需求 → spec → 原型 流水线
• dev：研发视角，生成工程上下文（宪章 / subagent-context），走完整工程流水线

角色决定生成哪些 .loom/ 文件；workflow.yaml 始终是含全部 pipeline 的单文件，不裁剪。未指定时默认 dev（与历史行为一致）。把选择通过 --roles 传给脚本，例如 --roles pm,dev。

第二步：确认 agent 工具

如果用户没有明确指定 agent 工具，再询问要为哪些工具生成入口文件。可选项为：

• claude-code：生成 AGENTS.md+ CLAUDE.md
• codex：生成 AGENTS.md
• opencode：生成 AGENTS.md 并合并 opencode.json watcher ignore
• cursor：生成 .cursor/rules/loom.mdc
• copilot：生成 .github/copilot-instructions.md

拿到用户选择后，把角色和工具通过 --roles / --tools 显式传给脚本，例如：

node <skill-dir>/scripts/init-project.mjs --cwd <project-root> --roles pm,dev --tools claude-code,codex

第三步：确认图后端（仅当选了 dev）

如果用户没有明确指定图后端，询问这个项目使用哪个代码图谱/知识库后端。可选项为：

• codegraph（默认推荐）：基于 tree-sitter AST 的本地代码图谱，通过 MCP 实时查询。需要 .codegraph/ 目录，脚本会在初始化时自动 codegraph init 建图。
• sourcegraph：基于 Sourcegraph 的代码搜索和引用查询。需要 Sourcegraph 实例或 MCP server，索引由用户自行搭建。
• scip：基于 SCIP/LSIF 精确索引。需要已生成的 .lsif 或 .scip 文件，索引由用户自行生成。
• none：不启用任何图后端，所有代码查询走源码搜索和 git diff。

未指定时默认 codegraph（与历史行为一致）。把选择通过 --graph-backend 传给脚本：

node <skill-dir>/scripts/init-project.mjs --cwd <project-root> --roles dev --tools codex --graph-backend codegraph

如果用户在调用 skill 时已经明确指定了图后端（例如"用 sourcegraph 初始化项目"），则跳过此询问。非交互环境（CI、脚本调用）未指定时默认 codegraph，不阻塞流程。

第四步：填充产品上下文（仅当选了 pm）

脚本对 pm 角色只写出 .loom/rules/product.md 模板（保留 {{...}} 占位符）。脚本运行后，问用户以下 5 题，再用 Edit 把答案填进 product.md，替换对应占位符：

1. 产品名 + 一句话描述 → {{PRODUCT_NAME}} / {{PRODUCT_ONELINE}}
2. 目标用户是谁 → {{TARGET_USERS}}
3. 核心价值 → {{CORE_VALUE}}
4. 主要平台（移动端 / PC / 两者）→ {{PLATFORM}}
5. UI 风格（Material / Ant Design / 简洁 / 无要求）+ 原型受众（研发评审 / 用户测试 / 投资人 demo）→ {{UI_STYLE}} / {{PROTOTYPE_AUDIENCE}}

填完确认无残留 {{...}} 占位符。## 设计原则 下的 [TODO] 提示用户后续补充，不强制此刻填。

如果当前环境已安装 loom CLI，也可以等价运行：

loom init-project

可选参数：

• --force：覆盖已有 loom 生成文件。
• --roles pm,dev：显式指定角色，决定生成哪些 .loom/ 文件；不传时默认 dev（与历史行为一致）。pm 多写 product.md，dev 写工程上下文，两者取并集。
• --tools claude-code,codex,cursor,copilot,opencode：显式指定要分发的工具；兼容历史别名 claude，不传时 CLI 在交互终端会询问用户，非交互环境会自动检测并默认生成 AGENTS.md。
• --graph-backend codegraph|sourcegraph|scip|none：显式指定图后端；不传时默认 codegraph（与历史行为一致）。codegraph 会自动 codegraph init 建图，其它后端不自动建图。也可通过环境变量 LOOM_GRAPH_BACKEND 覆盖；优先级：--graph-backend 参数 > LOOM_GRAPH_BACKEND 环境变量 > 默认 codegraph。
• --template-dir <path>：使用指定模板目录，主要用于测试或本地调试；CLI 入口不暴露该参数。

执行后检查输出报告中的 written 和 skipped。被跳过的文件通常是用户已有的非 loom 管理文件，不要擅自覆盖，除非用户明确同意或使用 --force。

输出结构

.loom/
  graph.config.json                       # dev 角色，图后端配置
  memory/store.json                       # 所有角色，结构化记忆源
  memory/MEMORY.md                        # 所有角色，只读导出视图
  workflow.yaml                           # 所有角色（单文件，含全部 pipeline）
  rules/product.md                        # 选择 pm 角色时
  rules/constitution.md                   # 选择 dev 角色时
  contexts/subagent-context.md            # 选择 dev 角色时
AGENTS.md                       # 选择 Codex/OpenCode/Claude Code 时
CLAUDE.md               # 选择 Claude Code 时
.cursor/rules/loom.mdc                  # 检测到 Cursor 时
.cursor/rules/loom-session-init.mdc     # Cursor 等价 session-start hook（新增）
.github/copilot-instructions.md         # 检测到 GitHub Copilot 时
.github/workflows/loom-verify.yml       # 可选：CI 规范门禁（询问用户是否生成）

人工检查清单

脚本完成后必须快速审阅（按所选角色）：

1. 【dev】.loom/rules/constitution.md 中技术栈、构建命令、测试命令、目录树和架构模式是否准确。
2. 【dev】图后端：确认 .loom/graph.config.json 中 backend 与用户选择一致；codegraph 后端可用时已自动建图，其它后端需用户自行初始化索引；后端不可用时确认图查询能力已跳过。
3. 【pm】.loom/rules/product.md 中 5 项产品上下文已填，无残留 {{...}} 占位符。
4. .loom/memory/MEMORY.md 是否有需要保留的用户偏好、踩坑和长期决策。
5. 入口文件是否轻量：它们应该指向 .loom/，不要复制大段规则。

约束

• 不修改业务代码。
• 不覆盖用户已有的非 loom 管理文件，除非用户明确要求。
• 生成后不得留下未渲染的 {{PLACEHOLDER}}。
• Cursor .mdc 必须有合法 frontmatter。
• subagent/并行流程只作为可选执行策略，不作为所有任务的默认要求。

完成标准

• 初始化脚本运行成功。
• 输出报告无异常。
• 所有生成文件路径与 .loom/ 目录结构一致。
• 如存在 [TODO]，已明确提示用户后续确认。