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
```
依赖行为、章程审查工作流、版本控制、修订规则及章程一致性检查，可参考
```
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步骤、文件路径及验证标准的详细任务式实现方案。若方案违反章程中的“禁止”条款、削弱章程原则、与已批准愿景冲突或超出权限范围，则停止规划。

输出： 实现方案文档，路径为

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。以下情况保留在主上下文：

人工希望与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
— 产品章程工作流、基础关卡、章程审查、版本控制、修订规则及一致性检查
references/product-vision.md
— 产品愿景工作流、基础关卡、愿景审查、版本控制及上下文/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指引模板