specsfy-setup

准备项目上下文

交互模式

交互模式：perguntas。 提出任何问题之前，请阅读并遵循 .specsfy/Spec.md 中的 编号提问约定。

知识水平与答案记忆

此设置会进行简短的自适应对话。它不会使用固定问卷，也不会再次询问已经确认的信息。

提出任何问题之前，请按以下顺序阅读：

1. .specsfy/USER-PROFILE.md（如果存在）；
2. 当前对话及已给出的回答；
3. PROJECT.md、DESIGNSYSTEM.MD、.specsfy/STACK.md、 .specsfy/RULES.md、.specsfy/DATABASE.md 和 .specsfy/PACKAGES.md；
4. AGENTS.md、CLAUDE.md、.specsfy/SPECKIT.md，以及其中列出的相关来源文件（如果存在）；
5. 适用的 Inbox、backlog 和规格说明，不要修改这些文件。

在心中整理一份已回答事项的清单。只要本人有明确陈述，或来源中有明确无误的信息，即视为已回答该事项，即使措辞与问题不同也一样。不要要求确认、选择或改述已经明确的信息。仅针对遗漏、冲突或自上次确认以来发生变化的信息提问。

如果档案和对话中都尚未记录总体水平，请先提出这一轮问题：

Pergunta 1. Como você prefere receber as orientações deste setup?
1. Iniciante: explique os termos técnicos e o efeito de cada escolha antes de prosseguir.
2. Intermediário: conheço os fundamentos e prefiro explicações curtas junto das escolhas.
3. Experiente: posso responder com detalhes de stack, arquitetura, comandos e integrações.
4. Escrever outra resposta
5. Gere outras opções
6. Avançar

将回答归一化为 iniciante、intermediário 或 experiente，并连同来源和日期写入 .specsfy/USER-PROFILE.md。如果档案中已有确认的水平，则直接采用，不要提问。如果对话与档案记录的水平不同，只提出一个问题来解决冲突，并记录更新。

根据每轮调整说明深度：

• iniciante：在问题中解释每个技术术语，说明为何需要该信息，并描述各选项的实际影响；
• intermediário：使用常见的技术名称，仅在选择可能造成混淆时补充简短说明；
• experiente：对于尚未明确的事项，直接询问版本、框架边界、身份验证、持久化、测试、界面、部署或集成。

水平只调整措辞，不代表可以臆测答案。如果本人在不同领域展现出不同经验，可针对该领域调整，但未经确认不得更改总体水平。每次收到回答后，更新档案，从遗漏清单中移除该事项，然后再选择下一个问题。遵守每个领域最多八个问题的限制及编号约定的其余要求。

自适应 setup 流程

确认目录并阅读项目后，选择第一个尚未得到确认答复的必要主题：

1. 产品目标与主要成果；
2. 用户、团队与角色；
3. 访问、身份验证与权限；
4. 主要数据、关系与保留时间；
5. 界面、导航与界面状态；
6. 测试、可观测性与部署；
7. 外部集成与依赖服务。

每轮提问前都要查阅主题地图。如果来源已清楚说明某个主题，就在档案中记录来源并继续下一个主题。如果两个来源存在分歧，只针对差异提问。如果所有适用主题都已确认，说明 setup 将进入文件协调阶段，不要编造问题。

根据已确认的熟悉程度调整提问方式。对于初学者，在问题中解释术语、说明答案的用途，并展示各选项的实际影响。对于有一定经验的人，使用技术名称并简要说明。对于经验丰富的人，直接询问尚未明确的版本、框架边界、身份验证策略、持久化、测试、可观测性、部署和集成契约。

每轮根据 .specsfy/Spec.md 中的约定，提供一个问题、编号选项、Escrever outra resposta、Gere outras opções 和 Avançar。收到答复后，先规范化内容，再将领域、主题、答复、来源、日期和范围记录到 .specsfy/USER-PROFILE.md，然后才继续。

setup 中必须覆盖的功能

阅读产品信息时，将每个业务实体与用户需要执行的操作关联起来。如果用户旅程要求管理记录，请确认是否覆盖创建、查询、编辑和删除。不要强行对只读数据、不可变历史记录、事件或由集成维护的信息套用 CRUD。如果来源未说明需要哪些操作，请先通过一轮符合编号约定的问题向用户确认，再记录覆盖情况。

对于每个常用界面，确定用户如何通过系统菜单进入，并将菜单项、目标位置、权限和响应式行为记录到 INTERFACE.md。技术路由、回调或仅通过重定向访问的步骤，如果用户旅程本身能证明这种访问方式，可以不放入菜单。如果不清楚界面是否会收到链接或会出现在何处菜单中，请在继续前用一轮问题向用户确认。

setup 会在持久化上下文中记录这些需求，并将任何行为变更交由待办事项列表和 spec 处理。它不会自行创建界面、路由或持久化逻辑。后续实现必须覆盖已确认的 CRUD 操作和链接，并为其设置专属任务和测试。

每次完整执行 setup 时，在协调上下文和专家后，都要加载 $specsfy-documentator。重建 docs/ 和 .specsfy/PACKAGES.md 中整个现有系统的技术文档，即使应用、持久化逻辑或依赖项近期没有变更也不例外。保留受管理区块之外的人工编写文本，并在结束前解决所有 PENDING 结果。

setup 期间的数据库保护

如果项目包含 artisan，请在 setup 期间执行：

node .agents/skills/specsfy-setup/scripts/check_database_safety.mjs \
  --project <raiz>

必须提供 .env.testing，其中包含 APP_ENV=testing 和明确声明的数据库目标。测试数据库必须不同于 .env 中指定的数据库；不接受缺失的值，以免 Laravel 继承开发环境配置。脚本不会显示凭据或连接值。 PENDING 结果会阻止任何定向测试、测试套件或回归测试。修复测试环境，重新运行检查，并且只有在结果为 SAFE 后才能继续。切勿使用开发数据库运行测试，即使只是为了诊断。IGNORED 表示某个命令或配置可能会删除结构或记录；不要执行该命令，也不要提供强制执行的选项。

1. 读写前，确认项目目录。在对话中的首次执行时，如果用户已提供路径，将其解析为绝对路径并复述。如果用户未提供路径，请准确提供以下编号选项并等待回复：1. 使用当前目录。、2. 使用 Hub 的子目录。 和 3. 指定其他路径。。不要根据 Git 根目录推断目标路径。在同一对话中后续必须执行的步骤中，复用已确认的根目录，不要重复提问。

2. 在每条后续命令中使用已确认的根目录。在 Hub 中操作时，请在选定的子目录中执行，或为上下文和规格脚本传入 --project <根目录> 和 --root <根目录>。不要在父目录中创建上下文、规格、测试或代码。

3. 写入前，阅读已确认根目录中的 AGENTS.md、CLAUDE.md 和本地说明。然后执行 node scripts/inspect_project.mjs --project <根目录>。按返回的顺序阅读列出的源文件：说明、清单、配置、应用、路由、持久化、集成、界面、测试和文档。在理解当前系统并记录需要保留的内容之前，不要开始探索、建议技术栈或写入。

4. 需要审查 Agent 文件中的保留区块时，阅读可发布指南。 当 .specify/memory/constitution.md 存在时，也要阅读 与 GitHub Spec Kit 的兼容性。

5. 执行 specsfy doctor --project <根目录>，并在准备上下文前修复每项缺失要求。该诊断会检查 Node.js、Git、npm、项目访问权限和 npx。

6. 执行 node scripts/setup_context.mjs --project <根目录>。 如果 .specsfy/templates/custom/<名称>.md 存在，则从中渲染 PROJECT.md、STACK.md、RULES.md、DATABASE.md、INTERFACE.md、DESIGNSYSTEM.MD 和 .specsfy/USER-PROFILE.md；否则从受管理的文件 .specsfy/templates/Project.md、Stack.md、Rules.md、Database.md、Interface.md、DESIGNSYSTEM.MD 和 UserProfile.md 渲染；不要在脚本中维护并行的内嵌模板。DESIGNSYSTEM.MD 位于项目根目录，初始内容为通用界面默认值，且仅在文件尚不存在时创建。 当检测到 GitHub Spec Kit 时，同一命令还必须读取宪章和 specs/ 中的所有常规文件，然后更新 .specsfy/SPECKIT.md 的受管理区块。 初始设置不会创建 SEMVER、Dockerfile、compose.yaml、 stack.yaml、deploy 或 ansible/。只有在用户明确要求此流程时，才开始版本管理和部署；此时请宣布将交接给 $specsfy-specialist-deploy。 每次执行都必须具备幂等性：使用相同输入重复运行设置，不得修改已协调一致的文件、重复添加区块或启动其他步骤。

7. 每次变更开始和结束时，执行：

   node scripts/monitor_context.mjs --project <raiz> --check
   

   对于 Laravel，还要执行 check_database_safety.mjs --project <根目录>，并在结果为 SAFE 之前暂停所有测试执行。

8. 检查初始文件，包括 .specsfy/USER-PROFILE.md，以及生成后的 .specsfy/PACKAGES.md 和脚本使用的技术栈来源。当 .specsfy/SPECKIT.md 存在时，打开其中的章程以及投影中列出的每个原始来源。在进行任何界面发现之前，还要执行 node scripts/inspect_interface.mjs --project <raiz>，并打开与请求相关的现有路由、组件和页面。输出可指导分析，但不能替代对系统来源的阅读。项目整体阅读范围包括报告中出现的授权规则、角色、数据、集成、路由、页面、组件、状态、测试和现有文档。当项目规模较大时，按组继续阅读，并在提出任何更改之前说明已阅读的来源；不得将未阅读视为可以替换既有惯例的许可。

9. 绝不替换现有上下文文件，即使其内容不完整。对于 AGENTS.md、CLAUDE.md 和 .specsfy/SPECKIT.md，只更新框架限定区块，并保留区块以外的所有内容。绝不在 .specify/ 和 specs/ 中编写、移动、重命名或删除文件。

10. 阅读技术栈后，先安装 Specsfy 的核心必备专家：specsfy-specialist-data-modeling、specsfy-specialist-domain-modeling、specsfy-specialist-software-architecture、specsfy-specialist-shadcn-ui 和 specsfy-specialist-reui。随后执行 specsfy skills detect --project <raiz>。提供下方的匹配表，列出核心专家和检测到的专家，并说明将安装哪些专家。用户在开始设置时已授权此操作；在使用项目中安装核心专家和每个检测到的专家，不得添加其他通用专家，且必须始终通过以下方式安装：

npx skills add https://github.com/promovaweb/specsfy \
  --skill <especialista-detectado> --agent universal --copy -y --full-depth

安装后，加载当前阶段所需的已安装专家。如果命令失败，请说明命令名称、输出和可继续采取的方式；不得通过手动复制替代安装。手动安装的专家仍然有效：不要移除它们，也不要在没有必要时尝试重新安装。 11. 为补全或修正规模、规则或数据，宣布交接，并分别加载 $specsfy-aux-stack、$specsfy-aux-rules 或 $specsfy-aux-database。 12. 每次完整执行设置时，在辅助工具之后加载 $specsfy-documentator，并根据整个项目重建 docs/ 和 .specsfy/PACKAGES.md。如果在其他阶段更改了应用、持久化或依赖项，则在实现结束时再次运行文档工具。 13. 只有当用户明确要求或明确表示项目使用 Gitflow 时（参见 references/gitflow.md），才宣布交接、加载 $specsfy-specialist-gitflow，并通过 $specsfy-aux-rules 在 RULES.md 中记录已确认的分支约定。绝不根据仓库的分支结构、存在 develop 分支或任何其他隐含信号来建议、假定或应用 Gitflow。

不要绕过 PENDING 结果。更新指定文档，并再次运行监控程序。对于不会实质影响项目历史或目的的应用更改，在任务来源中记录该评估，并使用 --acknowledge-project-no-change 重试。对规则使用 --acknowledge-rules-no-change 时，也必须遵守相同要求；绝不使用确认选项来掩盖实际的文档更改。

将 PROJECT.md、INTERFACE.md 和 DESIGNSYSTEM.MD 保留在根目录。将 STACK.md、RULES.md、DATABASE.md、PACKAGES.md、USER-PROFILE.md 和可选投影 SPECKIT.md 保留在 .specsfy/ 中。将这些文档视为项目的衍生上下文，而非规范、门禁或实施授权。 在包含多个框架的项目中，记录所有观察到的技术栈； 不要默默选择单一技术栈。如果未识别出任何框架，则创建通用模型， 并说明仍待确认。

setup 安装的技术栈与专家

观察到的技术栈	安装的专家
Laravel	specsfy-specialist-laravel
通过 GitHub URL 获取的 Laravel 包	specsfy-specialist-laravel-package-manager
Supabase	specsfy-specialist-supabase
PostgreSQL	specsfy-specialist-postgres
Redis	specsfy-specialist-redis
React	specsfy-specialist-react 和 specsfy-specialist-react-ui-components
Astro	specsfy-specialist-astro
Next.js	specsfy-specialist-nextjs
TypeScript	specsfy-specialist-typescript
Tailwind CSS	specsfy-specialist-tailwind-css
shadcn/ui	specsfy-specialist-shadcn-ui
Docker 或 Compose	specsfy-specialist-docker
完整发布或部署	specsfy-specialist-deploy
Docker Swarm	specsfy-specialist-docker-swarm
Ansible	specsfy-specialist-ansible
OpenAPI	specsfy-specialist-web-api-design
OpenTelemetry 或 Prometheus	specsfy-specialist-observability
CI/CD	specsfy-specialist-delivery-engineering

每次 setup 都会安装的核心组件	用途
specsfy-specialist-data-modeling	数据、实体、关系和生命周期
specsfy-specialist-domain-modeling	领域语言、规则和边界
specsfy-specialist-software-architecture	模块、依赖和技术结构
specsfy-specialist-reui	为 React/Tailwind 界面和 CRUD 提供 ReUI 基础
specsfy-specialist-shadcn-ui	ReUI 的 primitives、主题和 registry

对于所有使用 React 的 Laravel 项目，setup 都会同时安装 shadcn/ui 和 ReUI。 不要将这对组合视为可选项：shadcn/ui 用于准备基础，ReUI 则在此基础上构建 CRUD 和界面。

对于所有 Laravel 应用，Laravel Octane 与 Open Swoole 都是必需的。 检查 composer.json 和 composer.lock 中的 laravel/octane、镜像中的 openswoole 扩展，以及运行时中的 --server=swoole。在 .specsfy/STACK.md 中记录这一组合，并在批准 setup 前，将缺失的安装或修正事项交由 spec 处理。

安装这对组合后，setup 会在 INTERFACE.md 中记录：React 页面由组件组成。每个新页面都必须查阅组件图谱、复用已有组件，并记录自定义组件、shadcn/ui primitives 和 ReUI 组合，以及真实存在的文件和使用者。