Enforces a fixed directory-and-naming convention for product documentation, suitable for general product families. Ready-to-copy Markdown templates live under templates/. Detailed file mappings and conventions in references/structure.md.
1. When to Use
- Creating or initializing a product documentation repository
- Scaffolding doc trees for product families or standalone products
- Auditing or aligning existing repos against the product doc standard
- Generating / renaming docs to match the naming convention
- Aligning
product-docs/content with the template structure - Writing or expanding any of the 10 root-level planning documents
2. Start Here
Before copying or editing templates, load only the references needed for the task:
- Placeholder interpretation and secret handling:
references/placeholder-protocol.md - Product/version/module/delivery ownership:
references/document-boundaries.md - Optional architecture and product patterns:
references/applicability.md - Reusable example identities and adaptation rules:
references/example-profiles.md - Evidence-oriented completion criteria:
references/quality-rubric.md - Exact filenames and dependency map:
references/structure.md - Project README selection, evidence, bilingual, and preservation rules:
references/readme-template-guide.md - Rust common template and optional domain-profile selector:
templates/readme/rust-profiles/README.md - Complete architecture template, evidence, and profile selection:
references/architecture-template-guide.md
2.1 Placeholder Summary
| Placeholder | Meaning | Example |
|---|---|---|
{{PRODUCT_NAME}} |
Product / brand name | ExampleCommerce, ExampleMemory |
{{OPEN_SOURCE_NAME}} |
Open-source variant name (if dual-track) | ExampleCommerce-Open, ExampleMemory-Open |
{{VERSION}} |
Version directory name | V1, V2 |
{{MODULE_NAME}} |
Module short name | 登录页, 设备中心 |
{{DATE}} |
Date placeholder | 2026-03-27 |
{{OWNER}} |
Author / reviewer name | 张三 |
{{ORGANIZATION}} |
Organization name | ExampleOrg |
{{DOC_ROOT}} |
Documentation root | product-docs/ExampleProduct |
Replace double-brace placeholders in both filenames and content. Single-brace prompts such as {例如：订单中心} are authoring examples, not global tokens. Root keeps one 6、 file; the former detailed feature list is merged into 10、功能菜单与版本规划.
2.2 Adaptation Contract
- Inspect the target repository and collect confirmed facts before filling templates.
- Choose applicable sections; remove non-applicable dual-track, SaaS, DDD/COLA, Agent, CLI/IM, mobile, or enterprise examples.
- Keep rich examples as labeled examples, but never present them as facts about the target product.
- Label uncertain content as Inference, Assumption, or To be confirmed and attach evidence where possible.
- Preserve source examples when maintaining this skill; improve boundaries and labels instead of deleting depth.
- Name generated standalone architecture documents
*-Architecture.mdor*-Architecture.zh_CN.md; place component/version qualifiers before-Architecture.
3. Document Architecture
3.1 Four-Layer Structure
{{PRODUCT_NAME}}/
├── 1、{{PRODUCT_NAME}}-命名与品牌说明.md ─┐
├── 2、{{PRODUCT_NAME}}-术语表与词汇表.md │
├── 3、{{PRODUCT_NAME}}-市场与商业分析.md │
├── 4、{{PRODUCT_NAME}}-技术与可行性分析.md │ Root (10) — 产品级，与版本无关
├── 5、{{PRODUCT_NAME}}-技术方案与路线.md │
├── 6、{{PRODUCT_NAME}}-产品与版本规划.md │
├── 7、{{PRODUCT_NAME}}-领域模型设计.md │
├── 8、{{PRODUCT_NAME}}-Architecture.zh_CN.md │
├── 9、{{PRODUCT_NAME}}-视觉与交互DNA规范.md │
├── 10、{{PRODUCT_NAME}}-功能菜单与版本规划.md ─┘
│
├── V1/ ─┐
│ ├── 1、{{PRODUCT_NAME}}-需求调研文档-V1.md │
│ ├── 2、{{PRODUCT_NAME}}-需求分析文档-V1.md │
│ ├── 3、{{PRODUCT_NAME}}-V1-Architecture.zh_CN.md│ Version (7) — 版本级实施文档
│ ├── 4、{{PRODUCT_NAME}}-功能与界面规划-V1.md │
│ ├── 5、{{PRODUCT_NAME}}-PRD文档-V1.md │
│ ├── 6、{{PRODUCT_NAME}}-功能菜单与版本规划-V1.md│
│ ├── 7、{{PRODUCT_NAME}}-UI设计说明-V1.md │
│ │ ─┘
│ ├── 1、{模块A}/ ─┐
│ │ ├── {{PRODUCT_NAME}}-{模块A}-PRD-V1.md │ Module (3) — 可选，按模块
│ │ ├── {{PRODUCT_NAME}}-{模块A}-Stitch设计提示词.md │
│ │ └── {{PRODUCT_NAME}}-{模块A}-UI设计说明-V1.md ─┘
│ └── ...
│
├── 其他/ ─┐
│ ├── 1、技术细分模板.md │
│ ├── 2、功能提测模板.md │ Delivery (5) — 可选，研发交付
│ ├── 3、测试结果模板.md │
│ ├── 4、上线通知模板.md │
│ └── 5、项目运维模板.md ─┘
│
├── 技术调研/ ── 技术调研、协议分析（版本无关）
└── assets/ ── 图片、附件等
3.2 Scope Summary
| Scope | Count | Templates | Naming Pattern |
|---|---|---|---|
| Root | 10 | templates/root/ |
{{MODULE_INDEX}}、{{PRODUCT_NAME}}-{文档名}.md |
Version ({{VERSION}}/) |
7 | templates/version/ |
{{MODULE_INDEX}}、{{PRODUCT_NAME}}-{文档名}-{{VERSION}}.md |
| Module (optional) | 3 per module | templates/module/ |
{{PRODUCT_NAME}}-{{MODULE_NAME}}-{类型}-{{VERSION}}.md |
| Delivery (optional) | 5 | templates/delivery/ |
Context-dependent |
3.3 Root 10 Documents — Authoring Chain
There are strict upstream and downstream dependencies between documents; when writing, they should progress in order:
flowchart LR
D1["1、命名与品牌"] --> D2["2、术语表"]
D2 --> D3["3、市场分析"]
D3 --> D4["4、可行性分析"]
D4 --> D5["5、技术方案"]
D5 --> D6["6、版本规划"]
D6 --> D7["7、领域模型"]
D7 --> D8["8、系统架构"]
D8 --> D9["9、视觉DNA"]
D6 --> D10["10、功能菜单"]
D9 --> D10
| No. | Document | Key Input | Key Output | Benchmark Mermaid Type |
|---|---|---|---|---|
| 1 | Naming and Brand Statement | Product Vision | Brand Voice, Boundaries | graph LR (Brand Relationship) |
| 2 | Terminology and Glossary | Doc 1 Brand Positioning | Unified Language | None (Pure Tables) |
| 3 | Market and Business Analysis | Doc 1 Positioning + External Data | TAM/SAM/SOM, Competitors, Pricing | quadrantChart / funnel |
| 4 | Technical and Feasibility Analysis | Doc 3 Opportunities + Doc 5 Preliminary Selection | Feasibility Conclusion, Risks | flowchart / sequenceDiagram |
| 5 | Technical Solution and Roadmap | Doc 4 Conclusion | Tech Stack, ADR, Milestones | flowchart / gantt |
| 6 | Product and Version Planning | Doc 3 Business + Doc 5 Roadmap | Version Matrix, Pricing, Release Strategy | graph / timeline |
| 7 | Domain Model Design | Doc 2 Terminology + Doc 6 Functional Boundaries | Bounded Contexts, Aggregates, Events | classDiagram / graph TB |
| 8 | System Architecture Design | Doc 5 Tech Stack + Doc 7 Domain | Layers, Data Flow, Deployment | flowchart / sequenceDiagram |
| 9 | Visual and Interaction DNA Specification | Doc 1 Brand Character | Colors, Fonts, Components, Motion | flowchart (Page Skeleton) |
| 10 | Feature Menu and Version Planning | Doc 6 + Doc 8 + Doc 9 | Navigation, Routing, Feature List, Priorities | mindmap / pie / flowchart |
4. Scaffolding Workflow
Step 1 — Root Docs
Copy all 10 files from templates/root/ into the project root. Rename each replacing {{PRODUCT_NAME}}:
# Example: ExampleCommerce
for f in templates/root/*.md; do
name=$(basename "$f" | sed 's/{{PRODUCT_NAME}}/ExampleCommerce/g')
cp "$f" "product-docs/ExampleCommerce/$name"
done
Step 2 — Version Docs
Create {{VERSION}}/ (e.g., V1/). Copy 7 files from templates/version/. Replace both {{PRODUCT_NAME}} and {{VERSION}} in filenames and content.
Step 3 — Module Docs (optional)
For each functional module, create {{VERSION}}/{{MODULE_INDEX}}、{{MODULE_NAME}}/. Copy 3 files from templates/module/. Replace {{PRODUCT_NAME}}, {{MODULE_NAME}}, and {{VERSION}}.
Example (ExampleCommerce V1 Product Collection):
V1/1、商品采集/
├── ExampleCommerce-商品采集-PRD-V1.md
├── ExampleCommerce-商品采集-Stitch设计提示词.md
└── ExampleCommerce-商品采集-UI设计说明-V1.md
Step 4 — Delivery Docs (optional)
Copy templates/delivery/ into 其他/ or a dedicated delivery folder. Replace {{PRODUCT_NAME}} and dates.
Step 5 — Special Directories
Create 技术调研/ for tech research and 其他/ for non-standard docs. Directories like demo/, assets/, .stitch/ stay untouched.
Step 6 — Validate
Run the validation checklist (Section 7).
5. Quality Standards
5.1 Evidence-Oriented Quality Gates
Line counts, table counts, and diagram counts are diagnostics, not acceptance gates. A document is complete when it enables the next decision or delivery step with traceable evidence.
| Dimension | Required outcome |
|---|---|
| Scope | Audience, ownership, included/excluded scope, and upstream/downstream boundaries are explicit |
| Evidence | External claims include source, date, and confidence; repository claims point to files, APIs, tests, or runtime evidence |
| Decisions | Alternatives, decision, rationale, constraints, and reversal conditions are recorded |
| Consistency | Terms, versions, timelines, menu names, APIs, states, and acceptance criteria agree across documents |
| Delivery | Each requirement has verifiable acceptance criteria; architecture/UI sections cover failure, empty, loading, permission, and rollback states where applicable |
| Honesty | Confirmed facts, inferences, assumptions, and TBD items are distinguishable |
Use references/quality-rubric.md for scoring. Add diagrams and tables only when they make a relationship or comparison materially clearer.
5.2 Universal Document Structure
Each root document must contain the following standard structure:
Document Header:
# {{PRODUCT_NAME}} 文档标题
> **文档说明**：一句话说明文档用途与范围。
>
> **版本**：V1.0.0
> **最后更新**：{{DATE}}
Document Footer:
---
**文档版本**：V1.0.0
**创建日期**：{{DATE}}
**最后更新**：{{DATE}}
**文档状态**：✅ 待评审
5.3 Formatting Conventions
| Element | Specification |
|---|---|
| Section Numbering | ## N. top-level,### N.M sub-level, no more than 3 levels |
| Table Alignment | Use :--- left align |
| Feasibility Rating | ✅ High feasibility / ⚠️ Medium feasibility / 🔴 Low feasibility |
| Priority | P0 (Required) / P1 (Important) / P2 (Desired) / P3 (Optional) |
| Version Tag | 🆓 Free / 👤 Personal / 👥 Professional / 🏢 Enterprise |
| Status Marker | ✅ Implemented / 🔧 In Development / ⏳ Planned / ❌ Not Implemented |
| Mermaid | Blank lines before and after each diagram; diagram type should match the content (see 3.3 Benchmark column) |
| Code Block | Annotate language (typescript/go/bash/yaml/sql） |
| Chinese-English Mixed Typesetting | Add spaces between Chinese and English/numbers:OpenAI 模型 |
5.4 Cross-Reference Rules
- Doc 3 related documents must link Doc 1 (brand boundaries) and Doc 5 (technical feasibility)
- Doc 5 Gantt dates must be consistent with Doc 6 version milestones and Doc 10 release cadence
- Doc 7 aggregate names must be defined in the Doc 2 glossary
- Doc 8 layer names must correspond to the Doc 5 technology selections
- The version annotations in the Doc 10 feature list must be consistent with the Doc 6 version matrix
6. Gotchas
- Sequence numbers
1–7in version folders are reserved for the 7 standard docs. Non-standard docs must use8+or go into其他/. - Root has one file numbered
6、(Product and Version Planning). Detailed feature lists are embedded in10、功能菜单与版本规划. - Don't reorganize special directories (
demo/,assets/,.stitch/,stitch_*,实施指南/) unless the user explicitly requests it. - Delivery templates are optional and do not occupy root-level standard sequence numbers.
- When a product has open-source + commercial dual-track (e.g., ExampleCommerce-Open/ExampleCommerce), each track gets its own full 10-doc set with cross-references.
7. Validation Checklist
Run the bundled structural validator from the skill directory:
python3 scripts/validate_templates.py
For generated standalone architecture documents, validate filenames before delivery:
python3 scripts/validate_architecture_filenames.py \
docs/ExamplePlatform-Architecture.md \
docs/ExamplePlatform-Architecture.zh_CN.md
Then review semantic consistency that cannot be reduced to file counts:
- Target facts are evidence-backed; examples remain labeled examples
- Root/version/module/delivery responsibilities do not duplicate ownership
- Non-applicable dual-track, DDD/COLA, Agent, SaaS, CLI/IM, mobile, or enterprise sections were removed or adapted
- Timeline dates agree across market, technology, version, and menu documents
- Terminology agrees with the glossary; menu, route, API, and state names agree across PRD/UI/architecture
- Requirements have observable acceptance criteria and failure/permission/empty/loading states where relevant
- No resolved passwords, tokens, private paths, or private product/repository names were introduced
- Standalone architecture filenames match
*-Architecture.mdor*-Architecture.zh_CN.md
8. Template Inventory
| Group | Location | Count | Main responsibility |
|---|---|---|---|
| Product baseline | templates/root/ |
10 | Brand, terminology, market, technology, roadmap, domain, architecture, design DNA, and product-wide IA |
| Version delivery | templates/version/ |
7 | Research, analysis, version architecture, scope, PRD, menu, and UI decisions |
| Module detail | templates/module/ |
3 | Module-specific PRD, design-generation prompt, and UI specification |
| Engineering delivery | templates/delivery/ |
5 | Technical breakdown, test handoff/result, release, and operations |
| Project entry point | templates/readme/ |
5 + 7 Rust profiles | Java, Rust, plugin, and skill-ecosystem direct-use templates, a complete reference, and composable Rust domain coverage |
| Architecture design | templates/architecture/ |
1 + 7 profile documents | Complete architecture contract plus runtime, plugin, edge, event, AI, and control-plane profiles |
The original 25 lifecycle templates intentionally retain detailed reusable content and labeled full examples. The README family adds four type-specific templates plus one complete reference; the Rust template adds seven composable profile documents. The architecture family adds one complete master template and seven profile documents. Do not replace any of them with short empty shells.
9. Related Skills
doc-coauthoring: Interview-driven collaborative document drafting. Install with:npx skills add full-stack-skills/document-skills --skill doc-coauthoring.api-doc-generator: Source/OpenAPI-driven API documentation. Install with:npx skills add full-stack-skills/document-skills --skill api-doc-generator.
10. Completion Contract
Before reporting completion, state which template groups were used, which optional patterns were removed, which claims remain assumptions/TBD, and which validation commands passed. For standalone architecture outputs, report the filename validation result. If the target repository could not be inspected, say so explicitly rather than presenting example content as confirmed facts.