workflow-project-intake

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Intake (Brainstorm + Clarify + Route)

项目接入（头脑风暴+需求澄清+路由调度）

Treat Skills as "stateless execution units", externalize all state to the file system.

This skill is positioned as "project entry / requirements clarification":

When user only has a vague idea: help them clarify requirements (minimum information set) before entering execution chain
When user provides repo / clear objectives: quickly confirm understanding, then enter the correct workflow/step

This skill is not responsible for actual large-scale implementation (that's the job of execution skills like

workflow-ship-faster

workflow-feature-shipper

). It's responsible for converging "conversation" into "executable input", then handing off control.

将Skills视为“无状态执行单元”，所有状态都外置到文件系统中。

本Skill定位为**「项目入口/需求澄清」**：

当用户只有模糊想法时：在进入执行链路前，帮助他们澄清需求（收集最小信息集）
当用户提供仓库/明确目标时：快速确认理解，然后进入正确的工作流/步骤

本Skill不负责实际的大规模实现（这是

workflow-ship-faster

workflow-feature-shipper

等执行类Skills的工作）。它的职责是将“对话内容”转化为“可执行输入”，然后移交控制权。

Core Principles (Must Follow)

核心原则（必须遵守）

Pass paths only, not content: agents/sub-agents only pass
```
..._path
```
, let the executor read the file itself.
Files are first-class citizens: Every step must persist artifacts; failures can be retried; replayable; traceable.
Write operations must have checkpoints: Any action with external side effects (delete/modify cloud resources/DB writes/refunds/cancel subscriptions) must write a plan first and wait for explicit user confirmation.
Ask one question at a time: If information is missing, ask follow-ups, but each message asks only 1 question (prefer multiple choice); break complex topics into multiple rounds.
Hooks doctor (required check; non-blocking): If running under Claude Code and you want the evolution loop active, run
```
tool-hooks-doctor
```
once early; if hooks are missing, offer to install project-level hooks (continue either way).

仅传递路径，不传递内容：Agent/子Agent只传递
```
..._path
```
，由执行器自行读取文件。
文件是一等公民：每一步都必须持久化工件；失败可重试；可重放；可追溯。
写入操作必须有检查点：任何带有外部副作用的操作（删除/修改云资源/数据库写入/退款/取消订阅）必须先写入计划，等待用户明确确认。
一次只提一个问题：如果信息缺失，进行跟进提问，但每条消息只提1个问题（优先使用选择题）；将复杂话题拆分为多轮对话。
Hooks检查（必填项；非阻塞）：如果在Claude Code环境下运行且希望启用进化循环，请尽早运行一次
```
tool-hooks-doctor
```
；如果缺少hooks，可提供安装项目级hooks的选项（无论是否安装都可继续）。

0) Brainstorm Module (Replaces Old Approach)

0) 头脑风暴模块（替代旧方案）

When user input is still "idea/direction/vague requirement", first use

workflow-brainstorm

module to refine it into an executable design, then enter Intake Checklist.

workflow-brainstorm

module requirements:

Check project context first (if repo exists)
Ask only 1 question at a time (prefer multiple choice)
Provide 2-3 options with trade-offs explained
Output design in segments (~200-300 words each), ask "Does this look good?" at the end of each segment

当用户输入仍为“想法/方向/模糊需求”时，首先使用

workflow-brainstorm

模块将其细化为可执行设计，然后进入接入检查清单。

workflow-brainstorm

模块要求：

先检查项目上下文（如果仓库已存在）
一次只提1个问题（优先使用选择题）
提供2-3个选项并解释取舍
分段落输出设计（每段约200-300字），每段结尾询问“这个设计看起来可行吗？”

Minimum Information Set to Produce (Intake Checklist)

需要生成的最小信息集（接入检查清单）

Converge user input into the following information (ask for what's missing; if user already provided it, don't ask again).

Questioning Protocol (Required):

Each message asks 1 question only
Prefer multiple choice; use open questions only when necessary
Ask direction-determining questions first (success criteria/non-goals/constraints), then implementation details

将用户输入整合为以下信息（询问缺失的内容；如果用户已提供则不再询问）。

提问规则（必填）：

每条消息仅提1个问题
优先使用选择题；仅在必要时使用开放式问题
先询问决定方向的问题（成功标准/非目标/约束），再询问实现细节

A) Entry Type

A) 接入类型

```
entry_type
```
:
```
idea
```
|
```
prototype
```
If
```
prototype
```
:
```
repo_root
```
(local path or repo link)

```
entry_type
```
:
```
idea
```
|
```
prototype
```
如果是
```
prototype
```
：需提供
```
repo_root
```
（本地路径或仓库链接）

B) Success Criteria (Required)

B) 成功标准（必填）

The "one core loop" user wants to implement first (one sentence)
Acceptance criteria (3-5 items)
Clear non-goals (1-3 items)

用户首先要实现的“核心循环”（一句话描述）
验收标准（3-5项）
明确的非目标（1-3项）

C) Ship Faster Key Switches (Must Clarify)

C) 快速上线关键开关（必须澄清）

```
need_database
```
: Whether database is needed (default Supabase)
```
need_billing
```
: Whether billing/payment is needed (default Stripe)
```
need_auth
```
: Whether authentication is needed (default: false)
```
need_deploy
```
: Whether deployment to production is needed (default GitHub + Vercel)
```
need_seo
```
: Whether SEO is needed (sitemap/robots/llms.txt etc.)

```
need_database
```
: 是否需要数据库（默认使用Supabase）
```
need_billing
```
: 是否需要计费/支付功能（默认使用Stripe）
```
need_auth
```
: 是否需要身份验证（默认：false）
```
need_deploy
```
: 是否需要部署到生产环境（默认使用GitHub + Vercel）
```
need_seo
```
: 是否需要SEO优化（站点地图/robots.txt/llms.txt等）

D) Constraints (Optional but Recommended)

D) 约束条件（可选但推荐）

Launch timeline (if any)
Risk preference (aggressive/conservative)
Existing design constraints (brand colors/fonts/existing component library)

上线时间线（如有）
风险偏好（激进/保守）
现有设计约束（品牌颜色/字体/现有组件库）

Run Directory Specification

运行目录规范

Default (recommended): create in target project root:

runs/<workflow>/active/<run_id>/

OpenSpec-compatible mode (when

openspec/project.md

exists, or user forces it via

context.json

Active:
```
openspec/changes/<change-id>/
```

Archive:

openspec/changes/archive/YYYY-MM-DD-<change-id>/

Backend selection rule (deterministic):

context.json

includes

"artifact_store": "runs"

"openspec"

, follow it.

Else if
```
openspec/project.md
```
exists in
```
repo_root
```
, use OpenSpec mode.
Else use
```
runs/
```
.

Recommended structure (OpenSpec-style, low ceremony):

```
proposal.md
```
: User goal (original question + expected output + constraints + acceptance criteria + non-goals)
```
tasks.md
```
: Executable checklist (
```
- [ ]
```
→
```
- [x]
```
) + approval gates
```
context.json
```
: Key context (repo_root, need_* switches, risk preference, known IDs)
```
evidence/
```
(optional): Evidence/analysis from each analyzer (keep big output out of chat)
```
logs/
```
(optional):
- ```
events.jsonl
```
  : Structured event log (append one line per step)
- ```
state.json
```
  : Optional machine-readable state (what’s next / what’s complete)

Archive convention (after completion): move

active/<run_id>/

→

archive/YYYY-MM-DD-<run_id>/

默认（推荐）：在目标项目根目录下创建：

runs/<workflow>/active/<run_id>/

兼容OpenSpec模式（当

openspec/project.md

存在，或用户通过

context.json

强制启用时）：

活跃目录：
```
openspec/changes/<change-id>/
```

归档目录：

openspec/changes/archive/YYYY-MM-DD-<change-id>/

后端选择规则（确定性）：

如果

context.json

包含

"artifact_store": "runs"

或

"openspec"

，则遵循该配置。

否则，如果
```
repo_root
```
下存在
```
openspec/project.md
```
，则使用OpenSpec模式。
否则使用
```
runs/
```
模式。

推荐结构（OpenSpec风格，低仪式感）：

```
proposal.md
```
: 用户目标（原始问题+预期输出+约束条件+验收标准+非目标）
```
tasks.md
```
: 可执行检查清单（
```
- [ ]
```
→
```
- [x]
```
）+ 审批节点
```
context.json
```
: 关键上下文（repo_root、need_*开关、风险偏好、已知ID）
```
evidence/
```
（可选）：来自每个分析器的证据/分析内容（避免大体积输出出现在对话中）
```
logs/
```
（可选）：
- ```
events.jsonl
```
  : 结构化事件日志（每步追加一行）
- ```
state.json
```
  : 可选的机器可读状态（下一步操作/已完成内容）

归档约定（完成后）：将

active/<run_id>/

移动到

archive/YYYY-MM-DD-<run_id>/

Event Log Format (Recommended)

事件日志格式（推荐）

One JSON per line:

json

{"ts":"2026-01-11T12:00:00Z","step":"evidence","action":"cloudflare.query_worker_observability","status":"ok","artifacts":["evidence/observability.md"],"note":"p95 latency spike"}

Don't log sensitive content (token/email/phone/secret). Write redacted versions when necessary.

每行一条JSON：

json

{"ts":"2026-01-11T12:00:00Z","step":"evidence","action":"cloudflare.query_worker_observability","status":"ok","artifacts":["evidence/observability.md"],"note":"p95 latency spike"}

不要记录敏感内容（令牌/邮箱/电话/密钥）。必要时写入脱敏版本。

Checkpoint Protocol (Required for Write Operations)

检查点协议（写入操作必填）

Before executing write operations:

Write the approval plan into
```
tasks.md
```
under an Approvals section (object ID, impact scope, verification method)
Show same summary in conversation, wait for explicit user reply "confirm/yes/proceed"
Execute only after user confirms, write results to
```
evidence/
```
(and optionally
```
logs/events.jsonl
```
)

执行写入操作前：

将审批计划写入
```
tasks.md
```
的Approvals部分（对象ID、影响范围、验证方法）
在对话中展示相同的摘要，等待用户明确回复“confirm/yes/proceed”
仅在用户确认后执行，并将结果写入
```
evidence/
```
（可选写入
```
logs/events.jsonl
```
）

Artifacts (This Skill Must Persist)

工件（本Skill必须持久化）

Before routing/execution, write clarification results to:

```
proposal.md
```
: Goals, scope, acceptance criteria, non-goals, timeline
```
context.json
```
:
```
repo_root
```
,
```
entry_type
```
,
```
need_*
```
switches, risk preference, etc.

If this Intake includes "design spec" phase (from

workflow-brainstorm

module), also persist:

```
evidence/YYYY-MM-DD-<topic>-design.md
```
: Confirmed design and key decisions (for downstream plan/implementation reference)

Notes:

If file already exists: Only add missing fields / append information, don't blindly overwrite (avoid duplicate writes with downstream workflow)
Goal is to let downstream workflow "start running directly" without another round of clarification

context.json

(recommended minimal structure):

json

{
  "entry_type": "idea",
  "repo_root": "",
  "scope": "full",
  "artifact_store": "auto",
  "need_database": false,
  "need_billing": false,
  "need_auth": false,
  "need_deploy": false,
  "need_seo": false
}

在路由/执行前，将澄清结果写入：

```
proposal.md
```
: 目标、范围、验收标准、非目标、时间线
```
context.json
```
:
```
repo_root
```
、
```
entry_type
```
、
```
need_*
```
开关、风险偏好等

如果本次接入包含“设计规范”阶段（来自

workflow-brainstorm

模块），还需持久化：

```
evidence/YYYY-MM-DD-<topic>-design.md
```
: 已确认的设计和关键决策（供下游计划/实现参考）

注意：

如果文件已存在：仅添加缺失字段/追加信息，不要盲目覆盖（避免与下游工作流重复写入）
目标是让下游工作流“直接启动运行”，无需再次进行需求澄清

context.json

（推荐最小结构）：

json

{
  "entry_type": "idea",
  "repo_root": "",
  "scope": "full",
  "artifact_store": "auto",
  "need_database": false,
  "need_billing": false,
  "need_auth": false,
  "need_deploy": false,
  "need_seo": false
}

Routing: Which Workflow / Skill to Choose (Default to Ship Faster)

路由：选择哪个工作流/Skill（默认选择快速上线）

Priority recommendations:

From idea/small prototype to launch (default): Use
```
workflow-ship-faster
```

```
workflow-ship-faster
```
will persist to
```
runs/ship-faster/active/<run_id>/
```
by default (or
```
openspec/changes/<change-id>/
```
when OpenSpec mode is selected), and decide whether to execute DB/payment/deploy/SEO optional steps based on
```
context.json
```
switches
Just style/design system: Use
```
tool-design-style-selector
```
Just one feature iteration (split+deliver): Use
```
workflow-feature-shipper
```
Just React/Next.js performance review (waterfalls/bundle/re-renders): Use
```
review-react-best-practices
```
Just DB-side actions (SQL/migration/logs/type generation): Use
```
supabase
```
skill
Just Stripe-side operations (products/prices/payment links/refunds etc.): Use
```
stripe
```
skill

If unsure: Complete Intake Checklist first → Write

proposal.md/context.json

→ Then route (don't execute big actions upfront).

优先级推荐：

从想法/小型原型到上线（默认）：使用
```
workflow-ship-faster
```

```
workflow-ship-faster
```
默认会持久化到
```
runs/ship-faster/active/<run_id>/
```
（当启用OpenSpec模式时则使用
```
openspec/changes/<change-id>/
```
），并根据
```
context.json
```
中的开关决定是否执行数据库/支付/部署/SEO等可选步骤
仅样式/设计系统：使用
```
tool-design-style-selector
```
仅单个功能迭代（拆分+交付）：使用
```
workflow-feature-shipper
```
仅React/Next.js性能审查（请求瀑布/打包/重渲染）：使用
```
review-react-best-practices
```
仅数据库端操作（SQL/迁移/日志/类型生成）：使用
```
supabase
```
Skill
仅Stripe端操作（产品/定价/支付链接/退款等）：使用
```
stripe
```
Skill

如果不确定：先完成接入检查清单 → 写入

proposal.md/context.json

→ 再进行路由（不要提前执行大型操作）。

Conversation Convergence at End (Required)

对话收尾要求（必填）

Before handing off control to downstream skill, end this skill with 3 paragraphs:

Restate understanding (goal + acceptance criteria + non-goals)
Clarify the route to take (default
```
workflow-ship-faster
```
, and explain why)
Ask user if they want to start execution now:
- "Ready to start
```
workflow-ship-faster
```
  ? (Will write artifacts to
```
runs/ship-faster/active/<run_id>/
```
  in your project by default, and require confirmation before critical write operations)"

在将控制权移交下游Skill前，以3段内容结束本Skill：

重述理解内容（目标+验收标准+非目标）
明确要采用的路由（默认
```
workflow-ship-faster
```
，并解释原因）
询问用户是否要立即开始执行：
- "是否准备启动
```
workflow-ship-faster
```
  ？（默认会将工件写入你项目中的
```
runs/ship-faster/active/<run_id>/
```
  ，关键写入操作前会要求确认）"

Parallel Execution (Subagent)

并行执行（子Agent）

When any of these situations occur, split into parallel subtasks:

Need to scan by directory/module
Need to review by dimension (naming/functions/duplication/...)
Need to generate multiple alternatives (Plan A/B/C)

Parallel subtask conventions:

Input: Only receive paths (
```
proposal_path
```
,
```
context_path
```
,
```
output_dir
```
)
Output: Write artifacts to
```
evidence/parallel/<task-name>/
```
, return list of artifact paths

当出现以下情况时，拆分为并行子任务：

需要按目录/模块扫描
需要按维度审查（命名/函数/重复代码/...）
需要生成多个备选方案（方案A/B/C）

并行子任务约定：

输入：仅接收路径（
```
proposal_path
```
,
```
context_path
```
,
```
output_dir
```
）
输出：将工件写入
```
evidence/parallel/<task-name>/
```
，返回工件路径列表

Resume from Checkpoint

从检查点恢复

When running again:

Read
```
tasks.md
```
first; use
```
logs/state.json
```
only if it exists and you need machine state
Don't repeat completed steps; only fill in missing artifacts or continue from failure point

再次运行时：

先读取
```
tasks.md
```
；仅当
```
logs/state.json
```
存在且需要机器状态时才使用它
不要重复已完成的步骤；仅补充缺失的工件或从失败点继续

Deliverables (Minimum Requirements)

交付物（最低要求）

```
tasks.md
```
: Checklist reflects reality + execution summary + next steps
Optional:
```
logs/events.jsonl
```
for traceability

After completion, do a

skill-evolution

Evolution checkpoint (3 questions); if user chooses "want to optimize", call

skill-improver

to review this run and propose minimal patch suggestions.

```
tasks.md
```
: 检查清单反映实际情况+执行摘要+下一步计划
可选：
```
logs/events.jsonl
```
用于可追溯性

完成后，执行

skill-evolution

进化检查点（3个问题）；如果用户选择“需要优化”，调用

skill-improver

审查本次运行并提出最小化补丁建议。