kikita-labs/kikita-create-angular-app

kikita-create-angular-app 是做什么的？

引导一个新的 Angular 项目，并生成其 AGENTS.md / .agents/ 文档树， 使得之后在此项目中工作的任何 AI 代理（Claude Code、Codex 等）都拥有一个 完整的、可自维护的“真相源”。

0. 模式检测（始终优先执行）

目标目录有三种可能的状态 —— 按此顺序检查：

1. .agents/.kikita-scaffold.json 存在 → 该项目已被此技能脚手架化或采用。 遵循 update.md —— 不要重新运行问卷，不要重新脚手架化，不要重新运行 adopt.md。 update.md 负责拉取最新模板，对比记录的提交，然后将变更合并到项目的（可能已自定义的）.agents/ 文件中。
2. 空目录或近乎空目录（没有 package.json，没有 angular.json，最多只有用户刚创建的 .git//README）→ 全新初始化。继续执行下面的第 1 节，然后执行 plan.md。
3. 已有项目，无脚手架记录（存在 package.json/angular.json，但不存在 .agents/.kikita-scaffold.json）→ 这是别人的（或更早的、此技能之前的）Angular 项目。不要 运行 plan.md —— 它假定目录为空，并会尝试在真实项目上执行 ng new。而应遵循 adopt.md：它针对实际存在的项目生成 .agents/ 树，从现有配置推断问卷答案，而不是脚手架化新的工具链，并且在修改任何已存在的内容之前会进行询问。

0.5 前置条件（仅限全新初始化）

• 确认工作目录为空，或者用户明确希望在此初始化。
• 如果检查后发现目录非空，则停止并重定向到上面的情况 3（adopt.md），而不是强制走初始化路径 —— 不要仅仅询问用户“确认在此初始化没问题”，因为实际需要的是适配流程。

1. 问卷（在触碰文件系统之前始终询问）

从这里开始，逐步遵循 plan.md。不要跳过问卷。不要跳过 MCP 安装。完成后，在告知用户已完成之前，运行一遍 checklist.md。

一次性向用户提出所有问题：

1. CSS：原生 CSS（自定义属性）、SCSS 还是 Tailwind CSS？
   • Tailwind 是一个结构上不同的分支，而不是其他两种的变体：没有 @layer {{PREFIX}}.* 方案，没有手写的 :root 令牌，没有 SCSS mixin —— 参见 templates/.agents/code-style/css-architecture.md、component-structure.md 和 templates/.agents/architecture/folder-structure.md 中的 CSS=Tailwind 脚手架块。
2. UI 库：@kikita-labs/ui、Taiga UI、PrimeNG 还是无（构建一套本地基于令牌的 UI 集）？
   • 如果选择了某个库：查看它是否提供了 ng add 原理图（schematic）和/或 MCP 服务器。优先使用原理图。如果它有 MCP，安装它（参见 plan.md 第 4 步）。
3. 测试：无、仅单元测试、仅端到端测试、还是两者都选？使用哪个运行器（Vitest/Jasmine+Karma 在 Angular 新项目中已弃用 —— 推荐 Vitest；端到端测试推荐 Playwright）？
4. SSR：此应用是否进行服务端渲染（Angular SSR / 水合）还是仅客户端？
   • 决定是否生成 .agents/architecture/platform-adapter.md。
5. 国际化（i18n）：此项目是否需要多语言（@angular/localize 或一个运行时国际化库）？如果需要，使用哪种方案？
   • 决定是否生成 .agents/i18n.md。
6. 公共 API 上的 JSDoc：强制要求每个导出的符号都有 JSDoc，还是跳过？
   • 决定是否生成 .agents/agent-surface.md（推荐默认值：是）。
7. 项目前缀：组件/指令的短横线命名法（kebab-case）选择器前缀。
8. Git 策略：代理是否可以不经每次询问就提交和推送，还是每次提交/推送都必须确认？
9. 包管理器：npm、pnpm 还是 yarn？默认推荐：pnpm（更快，通过共享的内容可寻址存储提高磁盘效率，依赖解析更严格）。仅当用户要求其他工具时才覆盖默认值。
10. Git 远程仓库：用户是否已有要推送的仓库 URL？如果有，记录下来 —— git remote add origin <url> 在 git init 之后立即执行（参见 plan.md 第 9 步）。如果没有给出 URL，则跳过此项；用户稍后自行配置远程仓库。

记录每一个答案 —— 它们既驱动脚手架生成，也决定哪些文档文件会被生成。绝不要静默地假设默认值；如果用户跳过了某个问题，就针对该问题再次询问。 此技能面向单个 Angular 项目，而非 monorepo —— 如果用户想要 monorepo/Nx 工作区，请说明此技能不涵盖这种情况并停止，而不是自行发挥。

2. 生成

遵循 plan.md。将 templates/ 中的文件复制到目标项目中，包括点文件（.gitignore、.editorconfig、.prettierrc、.prettierignore、.nvmrc、.vscode/extensions.json）。

问卷答案会涉及两种不同的事情，不要混淆：

• 文本占位符 —— 查找并替换每个 {{TOKEN}} 为实际值，不留任何残留：{{PREFIX}}、{{PROJECT_NAME}}、{{CSS}}、{{CSS_EXT}}、{{UI_LIB}}、{{UI_LIB_MCP_NAME}}、{{UI_LIB_MCP_PURPOSE}}、{{TESTS}}、{{GIT_POLICY}}、{{PACKAGE_MANAGER}}、{{NODE_VERSION}}、{{I18N_APPROACH}}、{{DATE}}。
• 包含门（Inclusion gates） —— SSR、i18n、强制 JSDoc、UI 库和 CSS 引擎的答案不会填充占位符；它们决定是否复制整个文件（或文件内由 <!-- SCAFFOLD --> 标记的块）。如果答案为“否”（对于 CSS，则是两个未被选中的引擎），则意味着该文件/块被删除，而不是填充为空字符串。受包含门控制的文件，如果保留，则仍需在 AGENTS.md / 相关的 README 中链接；如果跳过，则移除其链接。

3. 验证

在报告成功之前，完整运行 checklist.md。

关于文档结构的说明（阅读一次，然后严格遵循 templates/ 中的内容）

• CLAUDE.md 始终是一个指向 AGENTS.md 的一行存根。
• AGENTS.md 是强制性的入口点：一个简短的“必读”列表加上不可协商的规则，位于项目根目录。
• .agents/README.md 是 .agents/ 下所有内容的平面索引 —— 相当于文档树的筒仓 index.ts。每个根文档和每个子文件夹的 README 都从它链接。当条件文件（i18n、agent-surface、platform-adapter）被添加或跳过时，保持同步。
• 对于真正短小的单个文档的主题，保持扁平放在 .agents/*.md（workflow、git-policy、documentation、mcp、testing-and-quality、agent-surface、refactoring、progress、i18n、accessibility）。
• 对于需要分散成多个小文档的主题，创建一个子文件夹，并配上自己的 README.md 枢纽：agents/code-style/、.agents/architecture/、.agents/shared/、.agents/core/、.agents/decisions/。这是有意与 kikita-ui/-docs（它们保持着完全扁平的结构）不同的，因为此技能的需求规定了每个组件和每个关注点的复用文档，这些文档在脚手架化后还会不断增长。
• .agents/shared/README.md 注册 src/app/shared/ 下的所有内容，按依赖形态拆分：shared/ui/（组件/指令/管道，Angular 装饰器）和 shared/utilities/（纯函数，零 Angular 导入 —— 通过 ESLint 的 restricted-import 规则强制实施）。如果选择了 SCSS，SCSS mixin 放在 styles/mixins/ 下，而不是 shared/ 下。.agents/core/README.md 注册 src/app/core/ 下的应用级单例（服务/守卫/拦截器）。两者都不命名为“components”—— 它们涵盖的范围都超过组件，因此得名。
• .agents/decisions/README.md 解释何时需要简短的 ADR（层方向、状态所有权、路由策略、公共别名方案）—— 始终生成，开始时没有 ADR 文件。AGENTS.md 将其链接在一个条件性的“用于结构性变更”组下，而不是必读列表 —— 与 shared//core/ 的“用于组件工作”组采用相同模式。
• 所有被跟踪的文件内容 —— 包括 JSDoc —— 均为英文。没有西里尔字母，没有乱码。
• .agents/ 中的所有文档必须读起来像 kikita-ui 中的 angular-code-style.md：命令式、简短、示例驱动，并以审查/验证检查清单结尾。