product-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Product Development Lifecycle

产品开发生命周期

Guide features through the product development lifecycle from idea to implementation plan. Each workflow produces specific artifacts that feed into the next. Workflow transitions are gated by human review, with optional automated review passes.

引导功能完成从想法到实施规划的产品开发生命周期。每个工作流都会生成特定的工件，为下一阶段提供输入。工作流的过渡由人工审查把控，也可选择加入自动化审查环节。

Lifecycle Map

生命周期图谱

[Project Setup]                              ← one-time setup (scripts/init.sh)
  ↓
Foundation Stage
  ├─ Product Constitution approval
  ├─ Product Vision workflow (Vision Grill)
  ├─ additional product-anchor workflows (planned extension point)
  └─ Foundation Gate: approved, versioned constitution + approved, versioned vision before first PRD
  ↓
Discovery and Design
  ↓  [human approves design]
Requirements
  ├─ PRD  [human approves before TRD]
  └─ TRD  [human approves PRD + TRD]  → optional review pass
  ↓
User Stories
  ↓  [human approves stories]         → optional review pass
BDD Scenarios
  ↓  [human approves scenarios]       → optional review pass
Implementation Planning

Foundation Stage does not block brainstorming or design exploration. Foundation Gate blocks creation of the first PRD. Later PRDs must check constitution and vision alignment before proceeding.

[Project Setup]                              ← 一次性设置（scripts/init.sh）
  ↓
基础阶段
  ├─ 产品章程审批
  ├─ 产品愿景工作流（Vision Grill）
  ├─ 额外的产品锚点工作流（规划中的扩展点）
  └─ 基础关卡：首个PRD编写前需完成已批准、带版本的章程 + 已批准、带版本的愿景
  ↓
发现与设计
  ↓  [人工审批设计]
需求阶段
  ├─ PRD  [编写TRD前需人工审批]
  └─ TRD  [人工审批PRD + TRD]  → 可选审查环节
  ↓
用户故事
  ↓  [人工审批故事]         → 可选审查环节
BDD场景
  ↓  [人工审批场景]       → 可选审查环节
实施规划

基础阶段不会阻碍头脑风暴或设计探索，但基础关卡会阻止首个PRD的创建。后续PRD在推进前必须检查是否与章程和愿景保持一致。

Workflows

工作流

Project Setup

项目设置

Trigger: The project does not yet have a

docs/product/

directory, or the user asks to "initialize product docs" or "set up product documentation."

Process: Run the initialization script (

scripts/init.sh

) to scaffold the documentation structure. The script uses templates with placeholders, auto-detects project context (name, surfaces), and prompts the user for domain-specific values. Consult

references/initialization.md

for the full workflow.

Output:

```
docs/product/README.md
```
— documentation hierarchy and boundary rules
```
docs/product/AGENTS.md
```
— agent guidance for organizing product docs
```
docs/product/features/
```
— empty directory ready for the first feature

This workflow runs once per project. Skip if

docs/product/README.md

already exists.

触发条件： 项目尚未创建

docs/product/

目录，或用户要求“初始化产品文档”或“设置产品文档”。

流程： 运行初始化脚本（

scripts/init.sh

）来搭建文档结构。该脚本使用带占位符的模板，自动检测项目上下文（名称、交互端），并提示用户输入领域特定的值。完整工作流请参考

references/initialization.md

。

输出：

```
docs/product/README.md
```
— 文档层级结构与边界规则
```
docs/product/AGENTS.md
```
— 用于组织产品文档的Agent指导说明
```
docs/product/features/
```
— 为空的目录，可用于存放首个功能相关文档

此工作流每个项目仅运行一次。 若

docs/product/README.md

已存在则跳过。

Foundation Stage

基础阶段

Trigger:

docs/product/constitution.md

docs/product/vision.md

is missing, the user asks to create or update product-anchor docs, or the agent is preparing to start the first feature PRD and must verify Foundation Gate before drafting.

Process: Establish product-anchor docs in this hierarchy:

Product Constitution workflow: create, ratify, or amend approved, versioned
```
docs/product/constitution.md
```
. Consult
```
references/product-constitution.md
```
for
```
grill-with-docs
```
dependency behavior, Constitution Grill workflow, versioning, amendment behavior, and constitution alignment checks.
Product Vision workflow: run the Vision Grill after Constitution approval. Consult
```
references/product-vision.md
```
for
```
grill-with-docs
```
dependency behavior, context/ADR coordination, and vision versioning.
Additional product-anchor workflows: planned extension point for product-anchor documents when approved.
Foundation Gate: complete only when approved, versioned
```
docs/product/constitution.md
```
and approved, versioned
```
docs/product/vision.md
```
exist.

Output: Approved, versioned

docs/product/constitution.md

; approved, versioned

docs/product/vision.md

; optional

CONTEXT-MAP.md

docs/product/CONTEXT.md

, and ADRs when approved and used.

Foundation Gate: Do not create the first PRD until the user approves

docs/product/constitution.md

, it has version metadata, and approved, versioned

docs/product/vision.md

exists.

触发条件：

docs/product/constitution.md

或

docs/product/vision.md

缺失，用户要求创建或更新产品锚点文档，或Agent准备开始编写首个功能PRD，必须先验证基础关卡才能起草。

流程： 按以下层级建立产品锚点文档：

产品章程工作流：创建、批准或修订已批准、带版本的
```
docs/product/constitution.md
```
。关于
```
grill-with-docs
```
依赖行为、章程审查（Constitution Grill）工作流、版本控制、修订规则及章程一致性检查，请参考
```
references/product-constitution.md
```
。
产品愿景工作流：章程获批后运行愿景审查（Vision Grill）。关于
```
grill-with-docs
```
依赖行为、上下文/ADR协调及愿景版本控制，请参考
```
references/product-vision.md
```
。
额外的产品锚点工作流：已获批的产品锚点文档的规划扩展点。
基础关卡：仅当已批准、带版本的
```
docs/product/constitution.md
```
和已批准、带版本的
```
docs/product/vision.md
```
均存在时，才算完成。

输出： 已批准、带版本的

docs/product/constitution.md

；已批准、带版本的

docs/product/vision.md

；若获批并使用，还会生成可选的

CONTEXT-MAP.md

、

docs/product/CONTEXT.md

及ADR文档。

基础关卡： 在用户批准

docs/product/constitution.md

（需包含版本元数据）且已批准、带版本的

docs/product/vision.md

存在前，不得创建首个PRD。

Discovery and Design

发现与设计

Trigger: An idea, feature request, or problem statement arrives.

Process: Invoke the

brainstorming

skill. It handles collaborative exploration, approach proposals, and design approval.

Output: Approved design document at

docs/plans/YYYY-MM-DD-<topic>-design.md

Gate: Do not proceed to Requirements until the design is approved.

触发条件： 收到想法、功能请求或问题陈述。

流程： 调用

brainstorming

技能。该技能负责协作探索、方案提议及设计审批。

输出： 已批准的设计文档，路径为

docs/plans/YYYY-MM-DD-<topic>-design.md

。

关卡： 设计获批后才能进入需求阶段。

Requirements

需求阶段

Trigger: Design document is approved.

Required inputs: Approved design document, approved, versioned

docs/product/constitution.md

, and approved, versioned

docs/product/vision.md

. Missing, unapproved, or unversioned foundation documents block first-PRD requirements work.

Process: Create product and technical requirements documents. Consult

references/phase-2-requirements.md

for structure, conventions, constitution alignment, and vision alignment.

Gate: The PRD defines what; the TRD defines how. Present the PRD for human approval before writing the TRD. This prevents wasted architectural work if the requirements shift.

Output:

```
docs/product/features/{feature}/PRD.md
```
```
docs/product/features/{feature}/TRD.md
```

Gate: Both documents reviewed and approved before proceeding. Run configured review passes (see Configuration).

Artifacts live at platform level — requirements describe what the product does regardless of surface.

触发条件： 设计文档已获批。

必填输入： 已批准的设计文档、已批准且带版本的

docs/product/constitution.md

、已批准且带版本的

docs/product/vision.md

。若基础文档缺失、未获批或未带版本，将阻碍首个PRD的需求工作。

流程： 创建产品需求文档（PRD）和技术需求文档（TRD）。关于文档结构、规范、章程一致性及愿景一致性，请参考

references/phase-2-requirements.md

。

关卡： PRD定义“做什么”；TRD定义“怎么做”。在编写TRD前，需先提交PRD供人工审批。这样可避免因需求变更导致架构工作浪费。

输出：

```
docs/product/features/{feature}/PRD.md
```
```
docs/product/features/{feature}/TRD.md
```

关卡： 两份文档均需经过审查和批准后才能推进。运行配置好的审查环节（详见配置部分）。

工件位于平台层级 —— 需求描述的是产品功能，与交互端无关。

User Stories

用户故事

Trigger: PRD and TRD are reviewed and stable.

Process: Decompose PRD requirements into user-facing narratives. Consult

references/phase-3-user-stories.md

for format, sizing guidance, and acceptance criteria conventions.

Output: Story files at

docs/product/features/{feature}/stories/

Gate: Stories reviewed and approved. Run configured review passes.

Stories are platform-level — they describe user intent, not surface-specific interactions.

触发条件： PRD和TRD已审查并稳定。

流程： 将PRD需求拆解为面向用户的叙事内容。关于格式、规模指导及验收标准规范，请参考

references/phase-3-user-stories.md

。

输出： 故事文件存放在

docs/product/features/{feature}/stories/

目录下。

关卡： 故事需经过审查和批准。运行配置好的审查环节。

故事属于平台层级 —— 它们描述的是用户意图，而非特定交互端的交互方式。

BDD Scenarios

BDD场景

Trigger: User stories have acceptance criteria defined.

Process: Express acceptance criteria as Gherkin scenarios. Consult

references/phase-4-scenarios.md

for the boundary rule, file placement, and writing conventions.

Output:

Platform-level scenarios:

docs/product/features/{feature}/scenarios/*.feature

Surface-specific scenarios:

apps/{surface}/docs/features/{feature}/scenarios/*.feature

Gate: Scenarios reviewed and approved. Run configured review passes.

Boundary rule: If the Given/When/Then language is surface-neutral, the scenario is platform-level. If it references a specific interaction model (swipe, D-pad, gaze), it is surface-specific.

触发条件： 用户故事已定义验收标准。

流程： 将验收标准表述为Gherkin场景。关于边界规则、文件存放位置及编写规范，请参考

references/phase-4-scenarios.md

。

输出：

平台级场景：

docs/product/features/{feature}/scenarios/*.feature

交互端特定场景：

apps/{surface}/docs/features/{feature}/scenarios/*.feature

关卡： 场景需经过审查和批准。运行配置好的审查环节。

边界规则： 如果Given/When/Then的表述与交互端无关，则该场景属于平台级；如果引用了特定的交互模式（如滑动、方向键、视线），则属于交互端特定场景。

Implementation Planning

实施规划

Trigger: Scenarios are reviewed and cover the acceptance criteria.

Process: Load the approved constitution and approved vision with the reviewed scenarios, then invoke the

writing-plans

skill. It creates a detailed, task-by-task implementation plan with TDD steps, file paths, and verification criteria. Stop before planning if the plan would violate

MUST NOT

language, weaken a constitutional principle, conflict with the approved vision, or exceed clear authority.

Output: Implementation plan at

docs/plans/YYYY-MM-DD-<topic>.md

触发条件： 场景已审查并覆盖所有验收标准。

流程： 加载已批准的章程、愿景及已审查的场景，然后调用

writing-plans

技能。该技能会创建详细的、按任务划分的实施规划，包含TDD步骤、文件路径及验证标准。若规划违反

MUST NOT

条款、削弱章程原则、与已批准的愿景冲突或超出明确权限，则停止规划。

输出： 实施规划文档，路径为

docs/plans/YYYY-MM-DD-<topic>.md

。

Gates and Review Passes

关卡与审查环节

Gate behavior

关卡行为

At each gate:

The agent presents artifacts to the human for review
If review passes are configured for this gate, they run first and findings are included in the presentation
The human approves, requests changes, or rejects
On approval, proceed to next workflow. On changes, iterate and re-present.

在每个关卡：

Agent将工件提交给人工审查
若该关卡配置了审查环节，则先运行审查环节，并将审查结果纳入提交内容
人工进行批准、要求修改或拒绝
批准后进入下一工作流；若要求修改，则迭代后重新提交

Configurable review passes

可配置的审查环节

Review passes are optional automated checks that run at gates before human review. They are configured per-project or per-user (see Configuration). Examples:

Constitution alignment check — verify PRD satisfies all governance principles
Traceability audit — verify every FR-* is covered by a story, every story by a scenario
Code review agent — run a review skill (e.g.,
```
coderabbit:review
```
) against the artifacts
Custom review prompt — project-specific review instructions from
```
AGENTS.md
```

If no review passes are configured for a gate, the gate is human-only.

审查环节是可选的自动化检查，在人工审查前于关卡处运行。可按项目或用户进行配置（详见配置部分）。示例：

章程一致性检查 —— 验证PRD是否符合所有治理原则
可追溯性审计 —— 验证每个FR-*都有对应的故事，每个故事都有对应的场景
代码审查Agent —— 针对工件运行审查技能（如
```
coderabbit:review
```
）
自定义审查提示 —— 来自
```
AGENTS.md
```
的项目特定审查指令

若某关卡未配置审查环节，则仅需人工审查。

Configuration

配置

Configuration lives in two locations, with project-level overriding user-level:

User-level:

~/.config/prometheas-product-development-skill/

Project-level:

$PROJECT_ROOT/.config/prometheas-product-development-skill/

配置存放在两个位置，项目级配置会覆盖用户级配置：

用户级：

~/.config/prometheas-product-development-skill/

项目级：

$PROJECT_ROOT/.config/prometheas-product-development-skill/

settings.toml

Declarative, structured configuration for what runs where:

toml

[review_gates.requirements]
reviews = ["constitution-check"]

[review_gates.user_stories]
reviews = ["traceability-audit"]

[review_gates.bdd_scenarios]
reviews = ["traceability-audit", "coderabbit:review"]

[workflows]
use_subagents = true      # Delegate heavy writing to sub-agents
prd_before_trd = true     # Human approves PRD before TRD

声明式结构化配置，定义各环节的运行规则：

toml

[review_gates.requirements]
reviews = ["constitution-check"]

[review_gates.user_stories]
reviews = ["traceability-audit"]

[review_gates.bdd_scenarios]
reviews = ["traceability-audit", "coderabbit:review"]

[workflows]
use_subagents = true      # 将繁重的撰写工作委托给子Agent
prd_before_trd = true     # 人工先批准PRD再编写TRD

AGENTS.md

Natural language instructions that review agents receive as context. Use this for nuanced, project-specific guidance that doesn't fit structured config:

markdown

undefined

审查Agent接收的自然语言指令上下文。用于存放不适合结构化配置的、细致的项目特定指导：

markdown

undefined

Review Context

审查上下文

When reviewing PRDs, ensure constitution alignment with particular attention to Principle II (Privacy).

审查PRD时，需确保与章程保持一致，尤其关注原则II（隐私）。

Requirements Notes

需求说明

All TRDs must follow the vendor-agnostic facade pattern.

undefined

所有TRD必须遵循与供应商无关的外观模式。

undefined

Merge behavior

合并规则

Project-level

settings.toml

overrides user-level per-key. Project-level

AGENTS.md

is appended after user-level

AGENTS.md

, so project-specific instructions take precedence in context.

项目级

settings.toml

会按键覆盖用户级配置。项目级

AGENTS.md

会追加在用户级

AGENTS.md

之后，因此项目特定指令在上下文中优先级更高。

No configuration

无配置情况

If neither config location exists, the skill runs with defaults: human-only gates, no automated review passes, sub-agents used at the agent's discretion based on context size.

若两个配置位置均不存在，则技能将使用默认设置：仅人工关卡，无自动化审查环节，Agent会根据上下文大小自主决定是否使用子Agent。

Context Management

上下文管理

Requirements, User Stories, and BDD Scenarios involve substantial writing. To keep the main context focused on orchestration and human collaboration, delegate heavy writing to sub-agents. The lifecycle is sequential — never run workflows in parallel.

需求、用户故事及BDD场景涉及大量撰写工作。为使主上下文专注于编排和人机协作，需将繁重的撰写工作委托给子Agent。生命周期是顺序执行的——切勿并行运行工作流。

Sub-agent dispatch pattern

子Agent调度模式

For each writing workflow, dispatch a sub-agent with only the inputs it needs:

Workflow	Sub-agent receives	Sub-agent returns
Requirements PRD	Design doc, constitution, vision, `references/phase-2-requirements.md` , example features	PRD written to disk
Requirements TRD	Approved PRD, constitution, vision, `references/phase-2-requirements.md` , example features	TRD written to disk
User Stories	Approved PRD, TRD, constitution, vision, `references/phase-3-user-stories.md`	Story files written to disk
BDD Scenarios	User stories, TRD, constitution, vision, `references/phase-4-scenarios.md`	`.feature` files written to disk

The main context reviews sub-agent output with the human and iterates if needed.

对于每个撰写工作流，仅向子Agent发送其所需的输入：

工作流	子Agent接收内容	子Agent返回内容
需求PRD	设计文档、章程、愿景、 `references/phase-2-requirements.md` 、功能示例	写入磁盘的PRD
需求TRD	已批准的PRD、章程、愿景、 `references/phase-2-requirements.md` 、功能示例	写入磁盘的TRD
用户故事	已批准的PRD、TRD、章程、愿景、 `references/phase-3-user-stories.md`	写入磁盘的故事文件
BDD场景	用户故事、TRD、章程、愿景、 `references/phase-4-scenarios.md`	`.feature` 文件写入磁盘

主上下文会与人工一起审查子Agent的输出，若有需要则进行迭代修改。

When to stay in main context

何时使用主上下文

Not every workflow needs a sub-agent. Stay in the main context when:

The human wants to collaborate interactively on the artifact
The feature is small enough that writing fits comfortably in context
The human explicitly asks to work through it together

并非所有工作流都需要子Agent。在以下情况使用主上下文：

用户希望交互式协作创建工件
功能足够小，撰写内容可完全容纳在上下文中
用户明确要求共同完成

Documentation Hierarchy

文档层级

All product documentation follows a three-tier hierarchy. See

docs/product/README.md

for the full specification.

Tier	Location	Contains
Platform	`docs/product/`	PRDs, TRDs, user stories, platform-level scenarios
App	`apps/{surface}/docs/`	Surface-specific scenarios
Code	`apps/{surface}/tests/`	Step definitions (test automation)

所有产品文档遵循三级层级结构。完整规范请参考

docs/product/README.md

。

层级	位置	包含内容
平台	`docs/product/`	PRD、TRD、用户故事、平台级场景
应用	`apps/{surface}/docs/`	交互端特定场景
代码	`apps/{surface}/tests/`	步骤定义（测试自动化）

Workflow Selection

工作流选择

Not every feature starts at the beginning. Match the entry point to the current state:

Starting point	Enter at
No `docs/product/` directory	Project Setup
Missing, unapproved, or unversioned constitution or vision before first PRD	Foundation Stage
Vague idea, no clarity on approach	Discovery and Design
Clear requirements, needs documentation	Requirements after Foundation Gate
PRD exists, needs decomposition	User Stories
Stories exist, needs testable criteria	BDD Scenarios
Scenarios exist, needs implementation	Implementation Planning

Clear requirements may skip brainstorming only after Foundation Gate passes. If this is the first PRD and

docs/product/constitution.md

docs/product/vision.md

is missing, unapproved, or unversioned, run Foundation Stage before Requirements.

并非所有功能都要从初始阶段开始。需根据当前状态匹配入口点：

起始状态	进入阶段
无 `docs/product/` 目录	项目设置
首个PRD编写前，章程或愿景缺失、未获批或未带版本	基础阶段
想法模糊，方案不明确	发现与设计
需求明确，需要文档化	基础关卡通过后的需求阶段
PRD已存在，需要拆解	用户故事
故事已存在，需要可测试的标准	BDD场景
场景已存在，需要实施规划	实施规划

只有在基础关卡通过后，明确的需求才能跳过头脑风暴环节。若这是首个PRD，且

docs/product/constitution.md

或

docs/product/vision.md

缺失、未获批或未带版本，则需先运行基础阶段再进入需求阶段。

Skill Delegation

技能委托

This skill orchestrates the lifecycle but delegates to specialized skills for bookend workflows:

Discovery and Design: Delegate to
```
brainstorming
```
skill
Requirements, User Stories, BDD Scenarios: Follow the reference files in this skill
Implementation Planning: Delegate to
```
writing-plans
```
skill

本技能负责编排生命周期，但会将首尾工作流委托给专业技能：

发现与设计： 委托给
```
brainstorming
```
技能
需求、用户故事、BDD场景： 遵循本技能中的参考文件
实施规划： 委托给
```
writing-plans
```
技能

Specification Evolution

规范演进

Product specifications are living artifacts. Different artifact types evolve at different rates. Consult

docs/METHODOLOGY.md

for the full methodology. Summary:

Artifact	Strategy
Constitution, Vision	Immutable + supersede (semver)
PRD, TRD	Living document with changelog
User Stories	Living — add, complete, archive
Platform Scenarios	Living + self-verifying
Surface Scenarios	Living + self-verifying

When updating an existing spec, append to its changelog with date, change, and rationale. When changes are so extensive the document is unrecognizable from its original form, supersede with a new document instead.

产品规范是活的工件。不同类型的工件演进速度不同。完整方法请参考

docs/METHODOLOGY.md

。摘要：

工件	策略
章程、愿景	不可变 + 替代（语义化版本semver）
PRD、TRD	带变更日志的活文档
用户故事	活文档 —— 添加、完成、归档
平台场景	活文档 + 自验证
交互端场景	活文档 + 自验证

更新现有规范时，需在变更日志中添加日期、变更内容及理由。若变更幅度极大，导致文档与原始版本差异显著，则需用新文档替代旧文档。

Reference Files

参考文件

Detailed guidance for each workflow lives in reference files to keep context targeted. The

phase-*

filenames are legacy compatibility paths; load them by the workflow names below:

references/initialization.md
— Project initialization workflow, placeholders, post-init steps
references/product-constitution.md
— Product Constitution workflow, Foundation Gate, Constitution Grill, versioning, amendment behavior, and alignment checks
references/product-vision.md
— Product Vision workflow, Foundation Gate, Vision Grill, versioning, and context/ADR coordination
references/phase-2-requirements.md
— PRD and TRD structure, conventions, constitution and vision checks
references/phase-3-user-stories.md
— Story format, acceptance criteria, sizing
references/phase-4-scenarios.md
— Gherkin conventions, boundary rule, file placement
docs/METHODOLOGY.md
— Specification evolution strategies, changelog conventions, supersession rules

Load

references/source/product-constitution-guide.md

only through

references/product-constitution.md

when exact source detail is needed. Load

references/source/vision-document-guide.md

only through

references/product-vision.md

when exact source detail is needed.

每个工作流的详细指导存放在参考文件中，以保持上下文聚焦。

phase-*

文件名是旧兼容路径；请按以下工作流名称加载：

references/initialization.md
—— 项目初始化工作流、占位符、初始化后步骤
references/product-constitution.md
—— 产品章程工作流、基础关卡、章程审查（Constitution Grill）、版本控制、修订规则及一致性检查
references/product-vision.md
—— 产品愿景工作流、基础关卡、愿景审查（Vision Grill）、版本控制及上下文/ADR协调
references/phase-2-requirements.md
—— PRD和TRD的结构、规范、章程及愿景检查
references/phase-3-user-stories.md
—— 故事格式、验收标准、规模评估
references/phase-4-scenarios.md
—— Gherkin规范、边界规则、文件存放位置
docs/METHODOLOGY.md
—— 规范演进策略、变更日志规范、替代规则

仅当需要精确的源细节时，才通过

references/product-constitution.md

加载

references/source/product-constitution-guide.md

；仅当需要精确的源细节时，才通过

references/product-vision.md

加载

references/source/vision-document-guide.md

。

Scripts

脚本

scripts/init.sh
— Project initialization script. Scaffolds
```
docs/product/
```
from templates with placeholder substitution. Supports interactive prompts, CLI arguments, and
```
--dry-run
```
.

scripts/init.sh
—— 项目初始化脚本。从模板搭建
```
docs/product/
```
目录，替换占位符。支持交互式提示、CLI参数及
```
--dry-run
```
模式。

Templates

模板

templates/README.md.tmpl
— Documentation hierarchy template
templates/AGENTS.md.tmpl
— Agent guidance template

templates/README.md.tmpl
—— 文档层级结构模板
templates/AGENTS.md.tmpl
—— Agent指导说明模板