skills/skills/init-workspace/SKILL.md

name, description, disable-model-invocation

name	description	disable-model-invocation
init-workspace	检查开发环境；首次初始化个人执行工作区，重复使用时按更新策略补全规则、目录和文档。	true

Init Workspace

先检查环境，再根据用户要求决定只报告、初始化新目录或补全已有工作区。一个工作区可以容纳多个源码仓、docs/ 本地文档和 pkgs/ 参考库。环境检查不是初始化授权，也不是启动 worker 的授权。

Step 1 — 确认 Herdr 环境与 skills

先检查 HERDR_ENV 和 PATH 上的 herdr，再查找当前宿主列出或用户指定的 herdr、think-twice、why-here skill，并实际读取文件。记录来源和能否读取；目录存在不等于宿主可用，同名副本以宿主当前选择为准。

• HERDR_ENV 不为 1：不查询或控制 Herdr 会话。可以记录 CLI 存在，并按用户要求为以后生成条件式规则。
• 在 Herdr 内：读取可访问的 Herdr skill。宿主没有列出时，可运行 herdr --skill 获取内置文本并读取；记录其来源为 CLI，不声称已安装到所有宿主。
• 缺少 skill：报告缺口，不自动安装，也不生成无法执行的 skill 引用。用户明确允许安装后，重新检查。

完成条件： 是否处于 Herdr 环境及三个 skill 的可读性明确。

Step 2 — 检查协作环境、工具与目标目录

读取 references/environment-checks.md，按其中的命令和边界运行检查。脚本路径相对本 skill，不相对目标工作区。

• 有 Python 3.9+ 时使用 scripts/inspect_environment.py。默认检查 PATH、受支持 CLI 的版本/帮助、Herdr 内的 integration 状态、受限 Pi package 列表和目标文件存在性；输出 JSON，不写工作区。扫描做过的检查直接引用结果，不重复执行。
• 将宿主找到的 skill 路径用 --skill NAME=PATH 传给脚本；Shepherdr 的 git/local、项目级或显式加载来源，可用 --shepherdr-path PACKAGE_DIR 提供确认的包根目录。脚本只检查文件，不加载扩展。
• 在 Herdr 内按其 skill 核验当前会话；结合宿主提供的工具来源，报告 Shepherdr 的安装线索与当前加载状态。不为检查启动 worker。
• 包含 pi、claude、opencode、grok；codex、gemini 只查 PATH。用户要求列表时，按参考说明显式开启 Pi/Grok/OpenCode 模型查询和 OpenCode agent 定义查询。其他宿主接口按需补充，没有接口或无法确认副作用时标记未查。
• 区分 agent 定义与运行实例，模型配置与 CLI 列表；这些都不证明真实调用成功。不推断额度，不发测试 prompt、不登录、不启动 worker。
• 检查目标的 AGENTS.md、CLAUDE.md 桥、CODINGRULES.md、skills 连接、*.code-workspace 和 PATH 上的 just。新目录尚不存在时先扫描其现有父目录，并注明这不是目标目录现状。
• 无 Python 时按同一清单人工检查并报告，不自动安装，不执行无法核验的命令。

只输出允许的字段，不展示配置全文、密钥或原始命令错误日志。脚本输出统一屏蔽 sk-[0-9a-zA-Z-]+；人工报告同样检查。匹配串可能不是密钥，其他格式也可能漏检；不据此宣称报告完全无敏感数据，不将脱敏后的路径或 ID 自动用于执行。

完成条件： 提供简短能力/缺口报告及检查范围。用户只要求检查时，到此结束；报告默认不持久化，需要保留时先确认位置。

Step 3 — 选择初始化或更新

先按目标目录现状和用户要求选择路径：

• 只要求检查环境：在 Step 2 结束，不进入初始化或更新。
• 用户说明已用过本 skill，或目标已有 AGENTS.md、CLAUDE.md 等工作区规则：读取 references/update-workspace.md，走更新策略，不重跑完整初始化。无需证明旧文件出自本 skill；用户手写的规则也按更新方式保护。
• 目标不存在或尚无工作区规则：继续 Step 4；已有目录内容仍先检查，只补缺失部分。

更新路径完成后直接执行适用的 Done when 检查。只有更新提案明确需要某项脚手架操作时，才引用 Step 5/6 的对应步骤，不自动重建连接、克隆仓库或改变 git 跟踪方式。

Step 4 — 补充需求与选择章节

根据已有要求一轮询问缺口，不重复询问探测能回答的事实：

1. 目标目录、工作区名、维护者与用途。
2. 源码仓库：已有路径还是待克隆、一个还是多个；待克隆需远端 URL。
3. Quick Context：模块归属、维护的上游库、需要防止误判的事项。
4. 是否采用 Herdr 并行协作（当前可用时建议采用，但不自动启用）。Pi 任务优先使用已配置的 Shepherdr，其他任务按 $herdr 交互；用户的工具选择优先。只读任务不额外建 worktree，并行修改用独立 worktree。
5. 是否生成 CODINGRULES.md（默认否），工作区是否 git 跟踪（默认否）。
6. 是否引用用户指定的模型策略文件（默认不生成）。策略表达工具/模型/额度偏好，不把本次扫描清单复制进去。

已有文件逐节提出保留/替换/新增方案，模板不认识的章节原样保留。确认后才写入。用户已明确授权的全新空目录无需再问一次。

完成条件： 明确本次修改范围、源码仓位置与章节选择，已获相应写入确认。

Step 5 — 生成候选规则与脚手架

按 references/environment-checks.md 的 decisions 格式整理明确选择，用 scripts/render_agents.py 输出候选 AGENTS.md 到系统临时目录。它只做模板渲染，不读取扫描结果自行决策。

• AGENTS.md：使用 assets/AGENTS.template.md。新文件核验后写入；已有文件逐节修改，不将完整候选重定向覆盖。重复补全先对照现有章节，避免重复规则。
• 可选 Herdr 章节来自 assets/sections/herdr.md，只有采用 Herdr 且可读其 skill 时加入，保留用户的工具选择。环境故障参考链接指向本次使用的 init-workspace/SKILL.md；渲染器填入其实际文件 URI，手工生成时同样填写可读地址。think-twice 用于正式任务书/交付；why-here 只在废弃尝试、纠正误解、完成迁移或替换实现后使用。
• 模型策略引用必须指向目标工作区实际可读的文件；在本次明确授权创建该文件时可以先生成候选，交付前检查引用。没有文件就省略，不生成空策略文件。采用个人外部策略时，在工作区文件中写清实际来源、读取条件和失效处理。
• CLAUDE.md：先尝试符号链接到 AGENTS.md；Windows 需要管理员权限或开发者模式。失败时写一行 @AGENTS.md。已有可用桥不动。
• CODINGRULES.md：用户选择生成时使用 assets/CODINGRULES.template.md，同时保留 AGENTS 指针；未选择时不删已有文件。
• Python 不可用时，Agent 根据同一模板与章节选择生成候选；仍执行占位符、指针、脱敏及行数检查。

只创建缺失的部分：

<workspace>/
|- .agents/skills/           真身目录
|- .claude/skills            指向 .agents/skills
|- docs/                     按需建立 prd/ plans/ guides/ sop/
|- <repo>/                   一个或多个源码仓
|- pkgs/                     参考库
|- scripts/                  工作区脚本
|- .gitignore                至少含 nul
|- <project>.code-workspace
|- justfile                  仅当 PATH 有 just
|- AGENTS.md, CLAUDE.md

• Windows Junction：New-Item -ItemType Junction -Path .claude\skills -Target <绝对路径>\.agents\skills，无需管理员权限。POSIX：ln -s ../.agents/skills .claude/skills。已有目录/连接先检查，不覆盖。
• 从 assets/project.code-workspace 填充：Workspace（.）、每个源码仓、Docs 各一个入口；有独立入口的目录在 Workspace 视图的 files.exclude 隐藏。
• 有 URL 的待克隆仓按授权克隆到对应目录；没有 URL 的只建空目录并记入 docs/TODO.md。
• 写最小 docs/README.md 目录地图，与生成规则中引用的目录保持一致。
• justfile 空骨架：default: 下接 @just --list。

完成条件： 仅授权且缺失的资源被创建，既有内容按确认方案修改，候选中的可选指针已有实际目标。

Step 6 — git 跟踪（用户选择才执行）

1. git init。
2. pkgs/.gitignore 屏蔽全部，只放行 .gitignore 与 README.md；pkgs/README.md 维护参考仓名单。
3. 对已有源码仓确认是否登记为 submodule；确认后用 git submodule add <url> <dir> 登记。拿不到远端 URL 的记入 docs/TODO.md，不强行处理。

Done when

先确定验收范围：只检查时只验收检查报告；新建时验证本次全部生成资源；更新时验证本次修改及其必要依赖，不将范围外的既有问题变成本轮修复要求。以下文件检查只适用于对应范围。既有问题按更新策略登记；本轮必要依赖未验证时明确标为未验证或阻塞。

• 只检查模式没有创建工作区资源、启动 Agent、登录或发起模型推理
• 报告区分宿主可读/文件存在、agent 定义/运行实例、模型列出/调用验证；integration、扩展声明/文件/宿主加载/worker 可用分开，受限列表未发现不等于全机未安装
• 重复使用或已有规则时进入更新策略，仅询问缺口；环境暂时缺失不导致删除既有规则
• 写入已有文件前得到确认；未知章节和无关用户内容保留，重复补全无重复章节；没有差异时不写文件
• 本次新增或修改的规则不重复，AGENTS.md 与 CODINGRULES.md 职责分明，commit 尾注规则放在前者
• 本轮涉及的 skill、文档与策略指针带触发条件和动作，且必要目标可读，包括协作章节的环境故障参考链接
• 协作规则按任务选择回传方式，没有同时要求插件自动交付和手工重复回报；下发状态不明时不降级重发，迁移不重启或重发活动任务
• 本轮创建、修改或依赖的 skills 连接和 CLAUDE 桥有效，涉及的 code-workspace 是合法 JSON
• 新生成内容无占位符、模板注释或未替换示例，候选 AGENTS.md 不超过 200 行；更新不为清除既有超限而删除用户内容
• 输出做字段筛选及密钥模式屏蔽，说明未验证能力与未完成事项